Skip to main content

Crate sleigh

Crate sleigh 

Source
Expand description

§wazabin-sleigh

CI crates.io

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_one matches one instruction against the compiled specification and reports a typed error rather when it fails.
  • Disassembly — Instruction::display renders the specification’s display section.
  • Semantics — Instruction::pcode_ast gives a source-shaped p-code AST with macros, sub-tables and delay slots already expanded. See the semantics module for the type graph and the conventions it follows.
  • Source tooling — analyze reports diagnostics and lints without building a runtime specification. wazabin-sleigh-fmt formats 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:

MethodGives youUse when
Instruction::pcode_astSource-shaped AST, macros and sub-tables expandedYou want to read, print, or pattern-match semantics
Instruction::pcode_opsFlat Ghidra-style opsYou want the classic p-code array
Instruction::pcode_ops_streamedThe same ops, streamed into your sink, with a PcodePlan firstYou 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

Ghidrawazabin-sleigh
Input.slaspec → built .sla, then decode the .sla.slaspec source, compiled in-process
.sla filesProduces and consumes themNot supported — source only
EmbeddingVia Ghidra, or by linking the C++ decompilercargo add wazabin-sleigh
CorpusShips all 149 specificationsCompiles 142 of 149 (see Status)
DiagnosticsCompiler messagesDiagnostic 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 .sla interop. If you have a built .sla from Ghidra, this crate cannot read it. Point it at the .slaspec sources instead. Conversely nothing here produces a .sla for 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-precompile exists.

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 compiled

Working: 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:

SpecificationsCause
ARM6_be, ARM6_leUnimplemented builtin: sdiv
ARM8_be, ARM8_le, ARM8m_be, ARM8m_leARMv8.sinc leaves an @if unclosed; Ghidra’s preprocessor tolerates this, ours does not
hexagonThe <<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,r4

It 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-fmt is 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 sink

Re-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 value comments 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§

BitRangeFieldId
Identifies a bit-range field — one entry of a define bitrange declaration, 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.
BitRangeInfo
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.
FieldTableId
Identifies one attachment table — the list of registers, integers or names bound to a field’s values by an attach variables, attach values or attach names statement.
InstructionPcode
Flat p-code emitted for one machine instruction.
LabelId
Identifies one instruction-local p-code label.
LocalVarId
Integer identifier for a local p-code variable. Strings are never stored; uniqueness is guaranteed by allocation order within each macro/constructor scope.
PcodeAst
Backend-neutral, source-shaped p-code AST for one decoded instruction.
PcodeBinop
An infix operator and its two operands.
PcodeError
An error raised while lowering SLEIGH p-code, with an optional source span.
PcodeExpr
A p-code expression: a node kind, plus the width its value has.
PcodeLoad
*[space]:size ptr — a read from memory.
PcodeOp
One flat p-code operation.
PcodePlan
Whole-instruction facts a consumer needs before p-code emission starts.
PcodeRange
x[start, size] — size bits of x, counting from bit start.
PcodeStatement
A p-code statement with a byte-range span.
RegisterId
A stable identifier for a Register.
RegisterSlice
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 pcodeop names.
Opcode
An opcode from Ghidra’s p-code operation reference.
PcodeBinaryOp
An infix operator in a p-code expression.
PcodeDelaySlot
The minimum number of delay-slot bytes a delayslot(n) directive asks for.
PcodeErrorTy
The kind of a PcodeError.
PcodeExprKind
The shape of a p-code expression node.
PcodeIdent
A named thing a p-code expression refers to.
PcodeLowerError
Failure while lowering source-shaped SLEIGH p-code to flat operations.
PcodeSpaceRef
A space reference that may be unresolved at Phase 2 parse time.
PcodeStatementKind
A single p-code statement node.
PcodeTarget
A branch/call target that may be a label, an unresolved name, or an expression.
PcodeUnaryOp
A prefix operator in a p-code expression.
RangeParam
A bit position or width in a Range, which a macro may parameterise.
SpaceType
The broad category of a memory space.

Constants§

SPACE_CONST
The const space is used for constant values such as immediate values

Traits§

PcodeLoweringContext
Producer-specific information required to lower a source-shaped AST.
PcodeSink
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§

PcodeResult
Shorthand for a result carrying a PcodeError.
Size
Fixed-width size/offset type for serialized SLEIGH structures.