Expand description
§wazabin-sleigh
A Rust implementation of SLEIGH, the processor-specification language Ghidra uses to describe instruction sets.
Give it a .slaspec and some bytes; it gives you back the instruction, its assembly text, and its p-code semantics.
use sleigh::{Compiler, Decoder, SourceDb};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// A whole (very small) processor.
let spec_source = r#"
define endian=little;
define space ram type=ram_space size=4 default;
define space register type=register_space size=4;
define register offset=0 size=4 [ r0 r1 ];
define token instr(8) op=(0,3) reg=(4,7);
attach variables [ reg ] [ r0 r1 _ _ _ _ _ _ _ _ _ _ _ _ _ _ ];
:inc reg is op=1 & reg { reg = reg + 1; }
"#;
// 1. Compile the specification. Do this once; it is the expensive part.
let mut sources = SourceDb::new();
let root = sources.add_file("tiny.slaspec", spec_source);
let spec = Compiler::new(&mut sources).compile(root)?;
// 2. Decode. The context carries decode state between instructions —
// start from the specification's default.
let decoder = Decoder::new(&spec);
let instruction = decoder.decode_one(0x1000, &[0x11], &spec.new_context())?;
assert_eq!(instruction.display()?, "inc r1");
assert_eq!(instruction.len(), 1);
// 3. Ask what it *does*.
assert_eq!(
instruction.pcode_ast()?.pretty_print(&spec),
"r1 = (r1 + 1);"
);
Ok(())
}Developed by Thalium.
§Features
- Decoding —
Decoder::decode_onematches one instruction against the compiled specification and reports a typed error rather when it fails. - Disassembly —
Instruction::displayrenders the specification’s display section. - Semantics —
Instruction::pcode_astgives a source-shaped p-code AST with macros, sub-tables and delay slots already expanded. See thesemanticsmodule for the type graph and the conventions it follows. - Source tooling —
analyzereports diagnostics and lints without building a runtime specification.wazabin-sleigh-fmtformats specification text.
§Two phase architecture
This project work in two seperate stages.
Compilation turns specification text into a CompiledSpec.
preprocess and parse the @include graph, resolve symbols, then concretize every pattern and p-code template.
This is slow (~1s) for a real architecture, so it belongs at startup, or not in your process at all (see Skipping the compile).
Decoding walks the compiled decision tree for one instruction.
This is the hot path and is meant to be called in a loop.
A CompiledSpec is immutable once built, so a Decoder borrows it and many can share one specification.
.slaspec ── compile ─> CompiledSpec ──decode─> Instruction ─> display / p-code§Context
SLEIGH specifications decode against a context: a bit vector holding the processor state that changes what the same bytes mean. This is the single most common way to get plausible-looking wrong answers.
In x86-64, A zero-initialized context reads as 16-bit, so a 64-bit program decodes into nonsense. Set the context :)
let mut context = spec.new_context();
let long_mode = spec.field("longMode").expect("x86 defines longMode");
spec.set_context_field(&mut context, long_mode.id, 1)?;
// Now 48 89 d8 is MOV RAX,RBX, not two 16-bit instructions.
let instruction = decoder.decode_one(0x1000, &[0x48, 0x89, 0xd8], &context)?;Specifications can also write context as they decode.
globalset and context flow, used for things as ordinary as ARM/Thumb mode switching.
When you decode a stream rather than one instruction, carry the context forward instead of starting fresh each time; Instruction::context_effects reports what an instruction changed.
§Chose your p-code
Pick the lowest one that answers your question:
| Method | Gives you | Use when |
|---|---|---|
Instruction::pcode_ast | Source-shaped AST, macros and sub-tables expanded | You want to read, print, or pattern-match semantics |
Instruction::pcode_ops | Flat Ghidra-style ops | You want the classic p-code array |
Instruction::pcode_ops_streamed | The same ops, streamed into your sink, with a PcodePlan first | You are lifting at volume |
The streamed form hands your sink the plan (every label and branch target in the instruction) before the first operation arrives. A consumer can size its state up front and never re-scan.
§Skipping the compile
wazabin-sleigh-precompile compiles a fixed set of architectures during its build and embeds them, so loading is a deserialisation behind a OnceLock:
let spec = sleigh_precompile::x64::spec();
let decoder = sleigh::Decoder::new(spec);Use it for tests and for tools that ship a known architecture (x64..). Use this crate directly when the specification is chosen at runtime, or is not one of the embedded set.
§Compared to Ghidra
Ghidra’s SLEIGH is two programs: a compiler that turns .slaspec into a built .sla, and a runtime that decodes against it
| Ghidra | wazabin-sleigh | |
|---|---|---|
| Input | .slaspec → built .sla, then decode the .sla | .slaspec source, compiled in-process |
.sla files | Produces and consumes them | Not supported — source only |
| Embedding | Via Ghidra, or by linking the C++ decompiler | cargo add wazabin-sleigh |
| Corpus | Ships all 149 specifications | Compiles 142 of 149 (see Status) |
| Diagnostics | Compiler messages | Diagnostic values with spans, renderable as annotated snippets |
| Source tooling | — | analyze lints, wazabin-sleigh-fmt formats, unstable-syntax exposes the AST |
Two consequences worth stating plainly:
- No
.slainterop. If you have a built.slafrom Ghidra, this crate cannot read it. Point it at the.slaspecsources instead. Conversely nothing here produces a.slafor Ghidra to consume. - Compiling is not free. Ghidra pays the compile cost once, offline, and ships the result.
Doing it in-process is what makes this embeddable, but it is why
wazabin-sleigh-precompileexists.
Where behaviour is comparable, the goal is to match Ghidra: p-code opcodes, the unique space, context flow, and delay-slot expansion all follow it.
§Status
The compatibility figure is re-derived rather than asserted — the corpus
example compiles every specification in the vendored Ghidra corpus:
$ cargo run -p wazabin-sleigh --example corpus
142/149 specifications compiledWorking: big-endian tokens, context flow and globalset, delay slots, variable-length register lists, with blocks, p-code macros, and sub-table export.
The seven that do not compile fall into three causes, and they are gaps here rather than defects in Ghidra’s files:
| Specifications | Cause |
|---|---|
ARM6_be, ARM6_le | Unimplemented builtin: sdiv |
ARM8_be, ARM8_le, ARM8m_be, ARM8m_le | ARMv8.sinc leaves an @if unclosed; Ghidra’s preprocessor tolerates this, ours does not |
hexagon | The <<COMMIT>> construct is not parsed |
§sleigh-decode
A small command-line decoder ships with the crate:
$ cargo run -p wazabin-sleigh --bin sleigh-decode -- ./src/tests/fixtures/example.sla 108c
[0x0000] and r3,r4It looks the specification up in the nearest build_config.toml and applies that architecture’s defines and initial context, so it decodes the same way the embedded specifications do rather than from a zero context.
§Unstable features
Two feature flags expose the compiler’s own representations. Both are exempt from this crate’s semantic versioning and change whenever the internals do:
unstable-syntax— the source AST, for tooling that works on specification text.wazabin-sleigh-fmtis the intended consumer.unstable-introspect— read-only views over the decision tree and over constructor p-code with operands still unresolved.
§License
Licensed under the MIT License.
§Pipeline
SLEIGH spec (.sla)
└─ source/ ← file I/O, include resolution, preprocessing
↓
syntax/ ← Pest grammar → SleighFile AST (unresolved names)
↓
resolve.rs ← SleighFile → SpecBuilder (symbol IDs resolved)
↓
builder.rs ← SpecBuilder → Spec (concretized patterns + p-code)
│ uses pmacro/ (expression AST, typed IDs, macro expansion)
↓
CompiledSpec
↓ HOT PATH
walker.rs ← pattern matching → ConstructorInstance
↓
runtime/pcode/traverse.rs ← splices built sub-tables and delay slots
runtime/pcode/view.rs ← resolves each template node in place
↓
PcodeAst, or flat p-code streamed straight into a consumer's sinkRe-exports§
pub use annotate::Annotations;pub use bitrange::BitRange;pub use compile::CompileOptions;pub use compile::Compiler;pub use diagnostic::CompileError;pub use diagnostic::Diagnostic;pub use diagnostic::DiagnosticCode;pub use diagnostic::DiagnosticLabel;pub use diagnostic::Severity;pub use runtime::CompiledSpec;pub use runtime::ConstructorMatch;pub use runtime::Context;pub use runtime::ContextBytes;pub use runtime::ContextDatabase;pub use runtime::ContextEffect;pub use runtime::ContextError;pub use runtime::ContextScope;pub use runtime::DecodeError;pub use runtime::Decoder;pub use runtime::DelaySlotError;pub use runtime::Exclusion;pub use runtime::FieldRef;pub use runtime::Instruction;pub use runtime::ParamField;pub use runtime::RegisterField;pub use runtime::RegisterRef;pub use runtime::Shape;pub use runtime::SpaceRef;pub use runtime::SpecFingerprint;pub use runtime::SymbolKind;pub use runtime::SymbolRef;pub use runtime::TableRef;pub use runtime::TokenRef;pub use semantics::EmitError;pub use semantics::InstructionInfo;pub use semantics::SemanticsSink;pub use source::BytePos;pub use source::FileId;pub use source::FormatChunk;pub use source::FormatChunkKind;pub use source::FormatError;pub use source::FormatLine;pub use source::FormatLineKind;pub use source::IncludeEdge;pub use source::MacroDefinition;pub use source::MacroDefinitionId;pub use source::MacroExpansion;pub use source::MacroExpansionId;pub use source::PreparedSourceId;pub use source::PreprocessOptions;pub use source::SourceDb;pub use source::SourceOrigin;pub use source::Span;pub use syntax::AnalysisResult;pub use syntax::analyze;pub use syntax::AlignmentDef;pub use syntax::AttachStrDef;pub use syntax::AttachValDef;pub use syntax::AttachVarDef;pub use syntax::BitRangeDef;pub use syntax::BitRangeItem;pub use syntax::ConstructorDef;pub use syntax::ContextDef;pub use syntax::EndiannessDef;pub use syntax::FieldDef;pub use syntax::IncludeDirective;pub use syntax::MacroDef;pub use syntax::ParseResult;pub use syntax::PcodeOpDef;pub use syntax::RegisterDef;pub use syntax::SleighFile;pub use syntax::SleighItem;pub use syntax::SourceIndex;pub use syntax::SpaceDef;pub use syntax::TokenDef;pub use syntax::TriviaToken;pub use syntax::UnresolvedAction;pub use syntax::UnresolvedDisplayToken;pub use syntax::UnresolvedExpr;pub use syntax::WithBlockDef;pub use syntax::parse;
Modules§
- annotate
- Section annotations read from
#@key valuecomments in specification source, for tooling that wants to group constructors the language itself has no way to group. Section annotations read from specification comments. - bitrange
- Inclusive bit ranges, used for token fields and context fields.
- compile
- Compilation facade for building runtime SLEIGH specifications.
- diagnostic
- Shared diagnostics for SLEIGH analysis, compilation, linting, and runtime setup.
- highlight
- Tolerant lexical classification of SLEIGH text, for highlighting. Lexical token classification of SLEIGH source, for highlighting.
- introspect
- Read-only views over the compiled specification’s symbolic structures.
- pcode_
error - P-code language diagnostics, re-exported from
wazabin-pcode. - runtime
- Runtime decoding facade for compiled SLEIGH specifications.
- semantics
- The p-code AST: what a decoded instruction does.
- source
- Source ownership and stable source locations for SLEIGH tooling.
- syntax
- SLEIGH source AST, for tooling that works on specification text.
Structs§
- BitRange
Field Id - Identifies a bit-range field — one entry of a
define bitrangedeclaration, which names a run of bits inside a register (for instance a single flag within a status register) so that semantics can read and write it by name. Identifier of a named register bit range. - BitRange
Info - Metadata for a named SLEIGH bit range.
- FieldId
- Identifies a field: a named bit range within a token or within the context
register, or one of the global pseudo-fields such as
inst_start. Identifier used by source-shaped p-code for a decoder field. - Field
Table Id - Identifies one attachment table — the list of registers, integers or names
bound to a field’s values by an
attach variables,attach valuesorattach namesstatement. - Instruction
Pcode - Flat p-code emitted for one machine instruction.
- LabelId
- Identifies one instruction-local p-code label.
- Local
VarId - Integer identifier for a local p-code variable. Strings are never stored; uniqueness is guaranteed by allocation order within each macro/constructor scope.
- Pcode
Ast - Backend-neutral, source-shaped p-code AST for one decoded instruction.
- Pcode
Binop - An infix operator and its two operands.
- Pcode
Error - An error raised while lowering SLEIGH p-code, with an optional source span.
- Pcode
Expr - A p-code expression: a node kind, plus the width its value has.
- Pcode
Load *[space]:size ptr— a read from memory.- PcodeOp
- One flat p-code operation.
- Pcode
Plan - Whole-instruction facts a consumer needs before p-code emission starts.
- Pcode
Range x[start, size]—sizebits ofx, counting from bitstart.- Pcode
Statement - A p-code statement with a byte-range span.
- Register
Id - A stable identifier for a
Register. - Register
Slice - A location expressed inside the widest register enclosing it.
- Space
- A named, uniformly-addressed memory region.
- SpaceId
- A stable, context-unique identifier for a
Space. - Varnode
- A storage location or constant used as an input or output of a p-code op.
Enums§
- Builtin
- The built-in SLEIGH functions — a spec may call these without declaring
them, unlike
define pcodeopnames. - Opcode
- An opcode from Ghidra’s p-code operation reference.
- Pcode
Binary Op - An infix operator in a p-code expression.
- Pcode
Delay Slot - The minimum number of delay-slot bytes a
delayslot(n)directive asks for. - Pcode
Error Ty - The kind of a
PcodeError. - Pcode
Expr Kind - The shape of a p-code expression node.
- Pcode
Ident - A named thing a p-code expression refers to.
- Pcode
Lower Error - Failure while lowering source-shaped SLEIGH p-code to flat operations.
- Pcode
Space Ref - A space reference that may be unresolved at Phase 2 parse time.
- Pcode
Statement Kind - A single p-code statement node.
- Pcode
Target - A branch/call target that may be a label, an unresolved name, or an expression.
- Pcode
Unary Op - A prefix operator in a p-code expression.
- Range
Param - A bit position or width in a
Range, which a macro may parameterise. - Space
Type - The broad category of a memory space.
Constants§
- SPACE_
CONST - The const space is used for constant values such as immediate values
Traits§
- Pcode
Lowering Context - Producer-specific information required to lower a source-shaped AST.
- Pcode
Sink - Receives resolved p-code operations as an instruction is emitted.
Functions§
- lower_
instruction - Lowers a fully expanded source-shaped AST to Ghidra-style instruction p-code.
Type Aliases§
- Pcode
Result - Shorthand for a result carrying a
PcodeError. - Size
- Fixed-width size/offset type for serialized SLEIGH structures.