Skip to main content

sleigh/syntax/
ast.rs

1//! Typed, unresolved SLEIGH AST produced by a single Pest parse.
2//!
3//! All cross-references are `Box<str>` names; no symbol IDs are assigned during
4//! construction. Resolution (name → ID) is deferred to the Phase 3 `resolve()`
5//! pass, which walks this tree in declaration order while populating
6//! `SpecBuilder`.
7//!
8//! Each node carries `leading_trivia` so the formatter can reconstruct
9//! whitespace and comments without a second tree walk.
10
11// Without `unstable-syntax` this AST is the compiler's own front end and
12// nothing outside the crate reads it, so most fields look dead. They are not:
13// they are the formatter's input.
14#![cfg_attr(not(feature = "unstable-syntax"), allow(dead_code, unreachable_pub))]
15
16use crate::{
17    action::{BinOp as ActionBinOp, UnOp as ActionUnOp},
18    constraint::ConstraintAst,
19    pmacro::PCodeMacro,
20    source::Span,
21};
22use pcode_types::SpaceType;
23
24/// A single whitespace or comment token between structural AST nodes.
25#[derive(Debug, Clone)]
26pub struct TriviaToken {
27    /// Raw text (whitespace run or `# ...` comment).
28    pub text: Box<str>,
29    /// Mapped physical-source span, if available.
30    pub span: Span,
31}
32
33/// The root of a parsed SLEIGH source.
34#[derive(Debug, Clone)]
35pub struct SleighFile {
36    /// Top-level items in source order. Order is significant: SLEIGH resolves
37    /// names in declaration order, so a definition must precede its uses.
38    pub items: Vec<SleighItem>,
39}
40
41/// One top-level item in a SLEIGH file.
42///
43/// The same set of items is legal inside a `with` block, so this enum is also
44/// what [`WithBlockDef::items`] holds.
45#[derive(Debug, Clone)]
46pub enum SleighItem {
47    /// `define endian=big;` / `define endian=little;`
48    Endianness(EndiannessDef),
49    /// `define alignment=4;`
50    Alignment(AlignmentDef),
51    /// `define space ram type=ram_space size=4 default;`
52    Space(SpaceDef),
53    /// `define register offset=0 size=8 [ RAX RCX ... ];`
54    Register(RegisterDef),
55    /// `define bitrange zf=statusreg[10,1] ...;`
56    BitRange(BitRangeDef),
57    /// `define pcodeop cpuid;` — declares a user-defined p-code operation.
58    PcodeOp(PcodeOpDef),
59    /// `define token instr(16) op=(0,5) ...;`
60    Token(TokenDef),
61    /// `define context contextreg phase=(0,1) ...;`
62    Context(ContextDef),
63    /// `macro addflags(op1, op2) { ... }`
64    Macro(MacroDef),
65    /// `attach variables [ rs rt ] [ r0 r1 ... ];`
66    AttachVar(AttachVarDef),
67    /// `attach values [ imm ] [ 8 16 32 64 ];`
68    AttachVal(AttachValDef),
69    /// `attach names [ cc ] [ "eq" "ne" ... ];`
70    AttachStr(AttachStrDef),
71    /// `with tbl : ctx=1 { ... }`
72    WithBlock(WithBlockDef),
73    /// A constructor: `tbl: display is pattern [ actions ] { semantics }`
74    Constructor(ConstructorDef),
75}
76
77impl SleighItem {
78    /// Span of the whole item, from its first token to its last.
79    pub fn span(&self) -> Span {
80        match self {
81            SleighItem::Endianness(d) => d.span,
82            SleighItem::Alignment(d) => d.span,
83            SleighItem::Space(d) => d.span,
84            SleighItem::Register(d) => d.span,
85            SleighItem::BitRange(d) => d.span,
86            SleighItem::PcodeOp(d) => d.span,
87            SleighItem::Token(d) => d.span,
88            SleighItem::Context(d) => d.span,
89            SleighItem::Macro(d) => d.span,
90            SleighItem::AttachVar(d) => d.span,
91            SleighItem::AttachVal(d) => d.span,
92            SleighItem::AttachStr(d) => d.span,
93            SleighItem::WithBlock(d) => d.span,
94            SleighItem::Constructor(d) => d.span,
95        }
96    }
97
98    /// Mutable access to the item's leading trivia, whichever variant it is.
99    ///
100    /// The parser uses this to hand over the whitespace and comments it
101    /// buffered since the previous item once it knows what that item is.
102    pub fn leading_trivia_mut(&mut self) -> &mut Vec<TriviaToken> {
103        match self {
104            SleighItem::Endianness(d) => &mut d.leading_trivia,
105            SleighItem::Alignment(d) => &mut d.leading_trivia,
106            SleighItem::Space(d) => &mut d.leading_trivia,
107            SleighItem::Register(d) => &mut d.leading_trivia,
108            SleighItem::BitRange(d) => &mut d.leading_trivia,
109            SleighItem::PcodeOp(d) => &mut d.leading_trivia,
110            SleighItem::Token(d) => &mut d.leading_trivia,
111            SleighItem::Context(d) => &mut d.leading_trivia,
112            SleighItem::Macro(d) => &mut d.leading_trivia,
113            SleighItem::AttachVar(d) => &mut d.leading_trivia,
114            SleighItem::AttachVal(d) => &mut d.leading_trivia,
115            SleighItem::AttachStr(d) => &mut d.leading_trivia,
116            SleighItem::WithBlock(d) => &mut d.leading_trivia,
117            SleighItem::Constructor(d) => &mut d.leading_trivia,
118        }
119    }
120}
121
122// ── Endianness ────────────────────────────────────────────────────────────────
123
124/// `define endian=big;` — the spec's global byte order.
125///
126/// It fixes the order in which instruction bytes are assembled into tokens,
127/// and is the default for every [`TokenDef`] that does not override it.
128#[derive(Debug, Clone)]
129pub struct EndiannessDef {
130    /// Span of the whole `define endian=...;` statement.
131    pub span: Span,
132    /// `true` for `big`, `false` for `little`.
133    pub big_endian: bool,
134    /// Whitespace and comments between the previous item and this one, kept
135    /// so the formatter can reprint them.
136    pub leading_trivia: Vec<TriviaToken>,
137}
138
139// ── Alignment ─────────────────────────────────────────────────────────────────
140
141/// `define alignment=4;` — the byte granularity instructions start on.
142#[derive(Debug, Clone)]
143pub struct AlignmentDef {
144    /// Span of the whole `define alignment=...;` statement.
145    pub span: Span,
146    /// Instruction alignment in bytes. Defaults to 1 if the value is missing.
147    pub alignment: usize,
148    /// Whitespace and comments between the previous item and this one, kept
149    /// so the formatter can reprint them.
150    pub leading_trivia: Vec<TriviaToken>,
151}
152
153// ── Address space ─────────────────────────────────────────────────────────────
154
155/// `define space ram type=ram_space size=4 default;` — an address space.
156///
157/// Attributes may appear in any order; those omitted take the defaults noted
158/// on each field.
159#[derive(Debug, Clone)]
160pub struct SpaceDef {
161    /// Span of the whole `define space ...;` statement.
162    pub span: Span,
163    /// Space name, as used by `*[ram]` and by register definitions.
164    pub name: Box<str>,
165    /// `type=` attribute: RAM, ROM, or register. Defaults to RAM.
166    pub ty: SpaceType,
167    /// `size=` attribute: width of an address into this space, in bytes.
168    /// Defaults to 4.
169    pub addr_size: usize,
170    /// `wordsize=` attribute: bytes per addressable unit. Defaults to 1, so
171    /// addresses count bytes; word-addressed spaces set it higher.
172    pub word_size: usize,
173    /// `default` attribute. At most one space per spec may carry it; it is the
174    /// space branch targets and bare `*` dereferences refer to.
175    pub is_default: bool,
176    /// Whitespace and comments between the previous item and this one, kept
177    /// so the formatter can reprint them.
178    pub leading_trivia: Vec<TriviaToken>,
179}
180
181// ── Registers ─────────────────────────────────────────────────────────────────
182
183/// `define register offset=0 size=8 [ RAX RCX ... ];` — a run of registers.
184///
185/// One statement names a whole consecutive block: the first entry sits at
186/// `offset`, and each further entry follows `size` bytes later.
187#[derive(Debug, Clone)]
188pub struct RegisterDef {
189    /// Span of the whole `define <space> offset=... size=... [...];`
190    /// statement.
191    pub span: Span,
192    /// Name of the address space registers live in.
193    pub space: Box<str>,
194    /// Byte offset of the first named register within [`Self::space`].
195    pub offset: usize,
196    /// Width of each register in bytes.
197    pub size: usize,
198    /// `None` entries are `_` (gap / skipped offset) placeholders.
199    ///
200    /// A gap still consumes its slot: the following name is placed `size`
201    /// bytes further on, exactly as a real register would be.
202    pub names: Vec<Option<Box<str>>>,
203    /// Whitespace and comments between the previous item and this one, kept
204    /// so the formatter can reprint them.
205    pub leading_trivia: Vec<TriviaToken>,
206}
207
208// ── Bitranges ─────────────────────────────────────────────────────────────────
209
210/// One `name=register[offset,size]` entry of a `define bitrange`.
211///
212/// It gives a name to a sub-range of an existing register, typically a single
213/// status flag such as `define bitrange zf=statusreg[10,1];`.
214#[derive(Debug, Clone)]
215pub struct BitRangeItem {
216    /// Name given to the sub-range.
217    pub name: Box<str>,
218    /// Name of the register the sub-range is carved out of.
219    pub register: Box<str>,
220    /// First bracketed integer: the bit offset of the range within the
221    /// register, counted from its least significant bit.
222    pub low: usize,
223    /// Second bracketed integer: the width of the range in bits, *not* an end
224    /// index. `[10,1]` is the single bit 10.
225    pub high: usize,
226}
227
228/// `define bitrange zf=statusreg[10,1] cf=statusreg[0,1];`
229#[derive(Debug, Clone)]
230pub struct BitRangeDef {
231    /// Span of the whole `define bitrange ...;` statement.
232    pub span: Span,
233    /// The entries of this statement, in source order. One statement may
234    /// define several bit ranges.
235    pub items: Vec<BitRangeItem>,
236    /// Whitespace and comments between the previous item and this one, kept
237    /// so the formatter can reprint them.
238    pub leading_trivia: Vec<TriviaToken>,
239}
240
241// ── PcodeOp ───────────────────────────────────────────────────────────────────
242
243/// `define pcodeop cpuid;` — declares a user-defined p-code operation.
244///
245/// Such an operation has no semantics of its own; the semantic section calls
246/// it by name and the lifter treats it as an opaque intrinsic.
247#[derive(Debug, Clone)]
248pub struct PcodeOpDef {
249    /// Span of the whole `define pcodeop ...;` statement.
250    pub span: Span,
251    /// Name of the declared operation.
252    pub name: Box<str>,
253    /// Whitespace and comments between the previous item and this one, kept
254    /// so the formatter can reprint them.
255    pub leading_trivia: Vec<TriviaToken>,
256}
257
258// ── Tokens and fields ─────────────────────────────────────────────────────────
259
260/// A single field defined inside a token or context block.
261///
262/// Written `name=(low,high)` followed by any attributes, as in
263/// `op=(0,5) signed`. The bit indices are relative to the parent token or
264/// context register.
265#[derive(Debug, Clone)]
266pub struct FieldDef {
267    /// Span of the `name=(low,high) attrs` field definition.
268    pub span: Span,
269    /// Field name, which becomes a spec-wide symbol usable in patterns,
270    /// display sections, and semantics.
271    pub name: Box<str>,
272    /// Inclusive low bit index.
273    pub low: usize,
274    /// Inclusive high bit index.
275    pub high: usize,
276    /// `signed` attribute: the extracted bits are sign-extended rather than
277    /// zero-extended.
278    pub signed: bool,
279    /// `noflow` attribute. Only meaningful for context fields: it stops a
280    /// committed value from persisting past the address it was set at.
281    pub noflow: bool,
282}
283
284/// `define token instr(16) op=(0,5) rd=(6,10);` — an instruction token and
285/// the fields cut out of it.
286///
287/// A token is a fixed-width window onto the instruction stream; its fields are
288/// the bit ranges patterns and semantics address by name.
289#[derive(Debug, Clone)]
290pub struct TokenDef {
291    /// Span of the whole `define token ...;` statement.
292    pub span: Span,
293    /// Token name, as used to disambiguate same-named fields.
294    pub name: Box<str>,
295    /// Token size in bits (always a multiple of 8).
296    pub size: usize,
297    /// `Some(true)` = big, `Some(false)` = little, `None` = inherit from global.
298    pub endian: Option<bool>,
299    /// Fields declared in this token, in source order.
300    pub fields: Vec<FieldDef>,
301    /// Whitespace and comments between the previous item and this one, kept
302    /// so the formatter can reprint them.
303    pub leading_trivia: Vec<TriviaToken>,
304}
305
306/// `define context contextreg phase=(0,1) noflow;` — fields of the context
307/// register.
308///
309/// Context fields hold decoder state rather than instruction bits: they are
310/// read by patterns, written by disassembly actions, and propagated between
311/// addresses by `globalset`. A spec has at most one context register, so every
312/// `define context` in a spec must name the same one.
313#[derive(Debug, Clone)]
314pub struct ContextDef {
315    /// Span of the whole `define context ...;` statement.
316    pub span: Span,
317    /// Name of the register backing the context. It must already be defined
318    /// by a `define register` statement.
319    pub register: Box<str>,
320    /// Context fields declared in this block, in source order.
321    pub fields: Vec<FieldDef>,
322    /// Whitespace and comments between the previous item and this one, kept
323    /// so the formatter can reprint them.
324    pub leading_trivia: Vec<TriviaToken>,
325}
326
327// ── Attach ────────────────────────────────────────────────────────────────────
328
329/// `attach variables [ rs rt ] [ r0 r1 ... ];` — reinterprets fields as
330/// registers.
331///
332/// The attached list is indexed by the field's decoded value, so it must have
333/// exactly `2^width` entries for every field it is attached to.
334#[derive(Debug, Clone)]
335pub struct AttachVarDef {
336    /// Span of the whole `attach variables ...;` statement.
337    pub span: Span,
338    /// Names of the fields the table is attached to. All of them share the
339    /// one table.
340    pub fields: Vec<Box<str>>,
341    /// `None` entries are `_` placeholders.
342    ///
343    /// Position in this list is the field value being mapped; `_` marks an
344    /// encoding with no register attached.
345    pub registers: Vec<Option<Box<str>>>,
346    /// Whitespace and comments between the previous item and this one, kept
347    /// so the formatter can reprint them.
348    pub leading_trivia: Vec<TriviaToken>,
349}
350
351/// `attach names [ cc ] [ "eq" "ne" ... ];` — gives fields display names.
352///
353/// Purely a display attachment: the field's numeric value is unchanged, but
354/// the display section prints the corresponding name. The list is indexed by
355/// field value and must have `2^width` entries.
356#[derive(Debug, Clone)]
357pub struct AttachStrDef {
358    /// Span of the whole `attach names ...;` statement.
359    pub span: Span,
360    /// Names of the fields the table is attached to.
361    pub fields: Vec<Box<str>>,
362    /// One entry per field value; `None` is an `_` slot with no name attached.
363    pub names: Vec<Option<Box<str>>>,
364    /// Whitespace and comments between the previous item and this one, kept
365    /// so the formatter can reprint them.
366    pub leading_trivia: Vec<TriviaToken>,
367}
368
369/// `attach values [ imm ] [ 8 16 32 64 ];` — remaps field values to other
370/// integers.
371///
372/// The list is indexed by the field's decoded value and must have `2^width`
373/// entries.
374#[derive(Debug, Clone)]
375pub struct AttachValDef {
376    /// Span of the whole `attach values ...;` statement.
377    pub span: Span,
378    /// Names of the fields the table is attached to.
379    pub fields: Vec<Box<str>>,
380    /// One entry per field value; `None` is an `_` slot with nothing attached.
381    ///
382    /// `attach values` admits negative literals, which are stored here as
383    /// their 64-bit two's-complement bit pattern.
384    pub values: Vec<Option<u64>>,
385    /// Whitespace and comments between the previous item and this one, kept
386    /// so the formatter can reprint them.
387    pub leading_trivia: Vec<TriviaToken>,
388}
389
390// ── Constructor actions ───────────────────────────────────────────────────────
391
392/// Unresolved disassembly action expression (field names as strings).
393///
394/// Disassembly actions are evaluated at decode time over integers only, so
395/// this is a small integer expression language — no memory, no p-code.
396#[derive(Debug, Clone)]
397pub enum UnresolvedExpr {
398    /// Infix operation, parsed with SLEIGH's action-expression precedence
399    /// (`|` loosest, then `^`, `&`, shifts, `+`/`-`, `*`/`/`).
400    Binary {
401        /// The operator.
402        op: ActionBinOp,
403        /// Left operand.
404        lhs: Box<UnresolvedExpr>,
405        /// Right operand.
406        rhs: Box<UnresolvedExpr>,
407    },
408    /// Prefix operation: `-x` or `~x`.
409    Unary {
410        /// The operator.
411        op: ActionUnOp,
412        /// Operand.
413        expr: Box<UnresolvedExpr>,
414    },
415    /// A bare name. Resolution reads it as a token, context, or global field,
416    /// or as an action-scoped local; a register name has no decode-time value
417    /// and resolves to the constant zero, matching Ghidra.
418    Ident(Box<str>),
419    /// An integer literal. Decimal, `0x`, and `0b` forms all land here.
420    Int(i64),
421}
422
423/// One statement in a constructor's disassembly-action block.
424///
425/// Variants are stored in source order: SLEIGH evaluates an action block
426/// sequentially, and `globalset` commits the value a context variable holds at
427/// that point, so reordering changes the meaning.
428#[derive(Debug, Clone)]
429pub enum UnresolvedAction {
430    /// `field = expr;` — assigns a token, context, or global field.
431    Assign {
432        /// Name of the assigned field.
433        field: Box<str>,
434        /// Right-hand side of the assignment.
435        expr: UnresolvedExpr,
436    },
437
438    /// `globalset(addr, field);` — commits `field`'s current value at `addr`.
439    GlobalSet {
440        /// Address the committed value takes effect at. Usually `inst_next`,
441        /// but may be any action expression or a sub-table operand name.
442        addr: UnresolvedExpr,
443        /// Name of the context field whose value is committed.
444        field: Box<str>,
445    },
446}
447
448// ── Constructors ──────────────────────────────────────────────────────────────
449
450/// A single element of a constructor's display section.
451#[derive(Debug, Clone)]
452pub enum UnresolvedDisplayToken {
453    /// An identifier that may resolve to a field, table, or fall back to a string literal.
454    Ident(Box<str>),
455    /// A literal string fragment (quoted string content, whitespace, or punctuation).
456    Literal(Box<str>),
457}
458
459/// An unresolved constructor definition.
460///
461/// A constructor is one decoding rule, written
462/// `table: display is pattern [ actions ] { semantics }`. It is the unit that
463/// matches bits, prints text, and emits p-code.
464#[derive(Debug, Clone)]
465pub struct ConstructorDef {
466    /// Span of the whole constructor, from its table header through the
467    /// closing brace of the semantic section.
468    pub span: Span,
469    /// Table name, or `None` for the root `instruction` table.
470    ///
471    /// `None` inside a `with` block means the block's default table applies
472    /// instead; see [`WithBlockDef::table`].
473    pub table: Option<Box<str>>,
474    /// The bit pattern between `is` and the action or semantic section. An
475    /// enclosing `with` block's constraint is conjoined with this one during
476    /// resolution.
477    pub constraint: ConstraintAst,
478    /// Display section tokens, parsed from the Pest `display` rule.
479    pub display: Vec<UnresolvedDisplayToken>,
480    /// Byte offset of the `is` keyword in the prepared source. Used by the
481    /// formatter to align `is` columns across consecutive constructors.
482    pub is_start: usize,
483    /// The bracketed disassembly-action block, in source order. Empty when the
484    /// constructor has no `[ ... ]` section. Actions inherited from enclosing
485    /// `with` blocks are prepended during resolution, not here.
486    pub actions: Vec<UnresolvedAction>,
487    /// Pre-parsed p-code body (Phase 2 result with deferred name references).
488    pub(crate) pcode: PCodeMacro,
489    /// Whitespace and comments between the previous item and this one, kept
490    /// so the formatter can reprint them.
491    pub leading_trivia: Vec<TriviaToken>,
492}
493
494impl ConstructorDef {
495    /// Byte spans of the semantic body's top-level statements, in the prepared
496    /// source, in source order.
497    ///
498    /// A formatter uses these to lay a body out without re-lexing it; the
499    /// compiler uses the same spans to point diagnostics at one statement.
500    pub fn statement_spans(&self) -> Vec<(usize, usize)> {
501        self.pcode
502            .body
503            .iter()
504            .map(|statement| statement.span)
505            .collect()
506    }
507}
508
509// ── Macros ────────────────────────────────────────────────────────────────────
510
511/// `macro addflags(op1, op2) { ... }` — a named, inlined block of p-code.
512///
513/// Macros are expanded at their call sites in semantic sections; they take
514/// varnode arguments and export nothing.
515#[derive(Debug, Clone)]
516pub struct MacroDef {
517    /// Span of the whole macro, from `macro` through the closing brace.
518    pub span: Span,
519    /// Macro name, as called from a semantic section.
520    pub name: Box<str>,
521    /// Parameter names in declaration order. They are bound as locals of the
522    /// body, so their order fixes the call-site argument order.
523    pub args: Vec<Box<str>>,
524    /// Pre-parsed p-code body (Phase 2 result with deferred name references).
525    pub(crate) pcode: PCodeMacro,
526    /// Whitespace and comments between the previous item and this one, kept
527    /// so the formatter can reprint them.
528    pub leading_trivia: Vec<TriviaToken>,
529}
530
531// ── With block ────────────────────────────────────────────────────────────────
532
533/// A `with` block, which applies a default table, constraint, and actions to
534/// all nested constructors and sub-blocks.
535#[derive(Debug, Clone)]
536pub struct WithBlockDef {
537    /// Span of the whole `with ... { ... }` block, braces included.
538    pub span: Span,
539    /// Default table name, or `None` for anonymous (inherits outer or `instruction`).
540    pub table: Option<Box<str>>,
541    /// Pattern conjoined onto every nested constructor's own pattern. `with`
542    /// blocks nest, and each enclosing constraint is conjoined in turn.
543    pub constraint: ConstraintAst,
544    /// Disassembly actions prepended to every nested constructor's own
545    /// actions, outermost block first.
546    pub actions: Vec<UnresolvedAction>,
547    /// Nested items. Any top-level item is allowed here, not just
548    /// constructors — ARM puts `attach variables` inside a `with` block.
549    pub items: Vec<SleighItem>,
550    /// Whitespace and comments between the previous item and this one, kept
551    /// so the formatter can reprint them.
552    pub leading_trivia: Vec<TriviaToken>,
553}