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}