Skip to main content

offlineasm_backend/
ast.rs

1//! Defines the offlineasm syntax tree.
2//!
3//! [`Node`] is the tree. [`LabelTable`] interns labels and their flags while
4//! the parser builds it.
5
6use crate::code_origin::CodeOrigin;
7use offlineasm_ir::Reach;
8use std::collections::{HashMap, HashSet};
9
10/// Returns the origin used for builtin nodes.
11pub fn builtin_origin() -> CodeOrigin {
12    CodeOrigin {
13        file_name: "<builtin>".to_string(),
14        basename: "<builtin>".to_string(),
15        file_number: 0,
16        line: 0,
17    }
18}
19
20/// Holds the flags recorded for one label.
21#[derive(Clone, Debug)]
22pub struct LabelFlags {
23    /// Whether the label is defined in this file.
24    pub defined_in_file: bool,
25    /// Whether the label is an unresolved extern reference.
26    pub is_extern: bool,
27    /// Whether the label was declared global.
28    pub global: bool,
29    /// Whether the label keeps default alignment.
30    pub aligned: bool,
31    /// The explicit alignment target, when declared.
32    pub align_to: Option<Box<Node>>,
33    /// Whether the label was declared a global export.
34    pub export: bool,
35}
36
37impl LabelFlags {
38    fn fresh(defined_in_file: bool) -> Self {
39        Self {
40            defined_in_file,
41            is_extern: true,
42            global: false,
43            aligned: true,
44            align_to: None,
45            export: false,
46        }
47    }
48}
49
50/// Interns labels and tracks their flags.
51#[derive(Clone, Debug, Default)]
52pub struct LabelTable {
53    labels: HashMap<String, LabelFlags>,
54    local_labels: HashSet<String>,
55    /// Maps each local label to its emitted symbol text.
56    pub local_strings: HashMap<String, String>,
57    unique_counter: usize,
58    /// Lists the extern labels recorded as referenced, in first-use order.
59    pub referenced_extern: Vec<String>,
60    /// Maps each label declared with `extern` to how code reaches it.
61    pub declared_externs: HashMap<String, Reach>,
62}
63
64impl LabelTable {
65    /// Creates an empty table.
66    pub fn new() -> Self {
67        Self::default()
68    }
69
70    fn ensure_label(&mut self, name: &str, defined_in_file: bool) -> Result<(), String> {
71        if defined_in_file && self.declared_externs.contains_key(name) {
72            return Err(format!(
73                "Label: {} is declared extern and cannot be defined",
74                name
75            ));
76        }
77        if let Some(flags) = self.labels.get_mut(name) {
78            if defined_in_file {
79                flags.is_extern = false;
80                flags.defined_in_file = true;
81            }
82            return Ok(());
83        }
84        if self.local_labels.contains(name) {
85            return Err(format!("Label name collision: {}", name));
86        }
87        let mut flags = LabelFlags::fresh(defined_in_file);
88        if defined_in_file {
89            flags.is_extern = false;
90        }
91        self.labels.insert(name.to_string(), flags);
92        Ok(())
93    }
94
95    /// Interns `name`, marking it defined when `defined_in_file` holds.
96    ///
97    /// # Errors
98    ///
99    /// Returns an error if `name` collides with a local label.
100    pub fn label_for_name(&mut self, name: &str, defined_in_file: bool) -> Result<(), String> {
101        if self.local_labels.contains(name) {
102            return Err(format!("Label name collision: {}", name));
103        }
104        self.ensure_label(name, defined_in_file)
105    }
106
107    /// Interns the local label `name` with its emitted symbol text.
108    ///
109    /// # Errors
110    ///
111    /// Returns an error if `name` collides with a global label.
112    pub fn local_label_for_name(&mut self, origin: &CodeOrigin, name: &str) -> Result<(), String> {
113        if self.labels.contains_key(name) {
114            return Err(format!("Label name collision: {}", name));
115        }
116        self.local_labels.insert(name.to_string());
117        self.local_strings
118            .entry(name.to_string())
119            .or_insert_with(|| {
120                format!(
121                    "__offlineasm_{}_{}",
122                    name.get(1..).unwrap_or(""),
123                    origin.label_string_extension()
124                )
125            });
126        Ok(())
127    }
128
129    /// Carries the flags recorded for `old` over to `new`.
130    pub fn apply_substituted_label_flags(&mut self, old: &str, new: &str) {
131        if old == new {
132            return;
133        }
134        let source = self.labels.get(old).cloned();
135        let entry = self
136            .labels
137            .entry(new.to_string())
138            .or_insert_with(|| match &source {
139                Some(flags) => flags.clone(),
140                // A reference to a name that was never interned: `Label.forName`
141                // creates it fresh (unreferenced, non-global).
142                None => LabelFlags::fresh(false),
143            });
144        if let Some(source) = source {
145            if source.global {
146                entry.global = true;
147            }
148            if source.export {
149                entry.export = true;
150            }
151            if !source.aligned {
152                entry.global = true;
153                entry.aligned = false;
154            }
155            if source.aligned && source.align_to.is_some() {
156                entry.aligned = true;
157                entry.align_to = source.align_to.clone();
158                entry.global = true;
159            }
160            if !source.is_extern {
161                entry.is_extern = false;
162                entry.defined_in_file = true;
163            }
164        }
165    }
166
167    /// Creates a fresh local label derived from `comment`.
168    pub fn unique_local_label(&mut self, origin: &CodeOrigin, comment: &str) -> String {
169        let mut candidate = format!("_{}", comment);
170        if self.labels.contains_key(&candidate) || self.local_labels.contains(&candidate) {
171            loop {
172                candidate = format!("_{}_{}", self.unique_counter, comment);
173                self.unique_counter += 1;
174                if !self.labels.contains_key(&candidate) && !self.local_labels.contains(&candidate)
175                {
176                    break;
177                }
178            }
179        }
180        self.local_labels.insert(candidate.clone());
181        let _ = origin;
182        candidate
183    }
184
185    fn mark_global(&mut self, name: &str, f: impl FnOnce(&mut LabelFlags)) -> Result<(), String> {
186        if self.declared_externs.contains_key(name) {
187            return Err(format!(
188                "Label: {} is declared extern and cannot be global",
189                name
190            ));
191        }
192        if let Some(flags) = self.labels.get_mut(name) {
193            if flags.global {
194                return Err(format!("Label: {} declared global multiple times", name));
195            }
196            f(flags);
197        } else {
198            if self.local_labels.contains(name) {
199                return Err(format!("Label name collision: {}", name));
200            }
201            let mut flags = LabelFlags::fresh(false);
202            f(&mut flags);
203            self.labels.insert(name.to_string(), flags);
204        }
205        Ok(())
206    }
207
208    /// Marks `name` as global.
209    ///
210    /// # Errors
211    ///
212    /// Returns an error if `name` is already global or collides with a local label.
213    pub fn set_as_global(&mut self, name: &str) -> Result<(), String> {
214        self.mark_global(name, |fl| fl.global = true)
215    }
216
217    /// Marks `name` as a global export.
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if `name` is already global or collides with a local label.
222    pub fn set_as_global_export(&mut self, name: &str) -> Result<(), String> {
223        self.mark_global(name, |fl| {
224            fl.global = true;
225            fl.export = true;
226        })
227    }
228
229    /// Marks `name` as an unaligned global.
230    ///
231    /// # Errors
232    ///
233    /// Returns an error if `name` is already global or collides with a local label.
234    pub fn set_as_unaligned_global(&mut self, name: &str) -> Result<(), String> {
235        self.mark_global(name, |fl| {
236            fl.global = true;
237            fl.aligned = false;
238        })
239    }
240
241    /// Marks `name` as an unaligned global export.
242    ///
243    /// # Errors
244    ///
245    /// Returns an error if `name` is already global or collides with a local label.
246    pub fn set_as_unaligned_global_export(&mut self, name: &str) -> Result<(), String> {
247        self.mark_global(name, |fl| {
248            fl.global = true;
249            fl.aligned = false;
250            fl.export = true;
251        })
252    }
253
254    /// Declares `name` an external symbol reached as `reach`.
255    ///
256    /// # Errors
257    ///
258    /// Returns an error if `name` is already declared extern, is defined or
259    /// declared global in this file, or collides with a local label.
260    pub fn set_as_extern(&mut self, name: &str, reach: Reach) -> Result<(), String> {
261        if self.declared_externs.contains_key(name) {
262            return Err(format!("Label: {} declared extern multiple times", name));
263        }
264        if let Some(flags) = self.labels.get(name) {
265            if flags.defined_in_file {
266                return Err(format!(
267                    "Label: {} is defined in this file and cannot be extern",
268                    name
269                ));
270            }
271            if flags.global {
272                return Err(format!(
273                    "Label: {} is declared global and cannot be extern",
274                    name
275                ));
276            }
277        }
278        self.label_for_name(name, false)?;
279        self.declared_externs.insert(name.to_string(), reach);
280        Ok(())
281    }
282
283    /// Marks `name` aligned, optionally to `align_to`.
284    ///
285    /// # Errors
286    ///
287    /// Returns an error if `name` is already aligned or collides with a local label.
288    pub fn set_as_aligned(&mut self, name: &str, align_to: Option<Node>) -> Result<(), String> {
289        if let Some(flags) = self.labels.get_mut(name) {
290            if flags.align_to.is_some() {
291                return Err(format!("Label: {} declared aligned multiple times", name));
292            }
293            flags.aligned = true;
294            flags.align_to = align_to.map(Box::new);
295            flags.global = true;
296        } else {
297            if self.local_labels.contains(name) {
298                return Err(format!("Label name collision: {}", name));
299            }
300            let mut flags = LabelFlags::fresh(false);
301            flags.aligned = true;
302            flags.align_to = align_to.map(Box::new);
303            flags.global = true;
304            self.labels.insert(name.to_string(), flags);
305        }
306        Ok(())
307    }
308
309    /// Returns the flags recorded for `name`, when interned.
310    pub fn label_flags(&self, name: &str) -> Option<&LabelFlags> {
311        self.labels.get(name)
312    }
313
314    /// Reports whether `name` is an extern label.
315    pub fn is_extern_label(&self, name: &str) -> bool {
316        self.labels.get(name).map(|f| f.is_extern).unwrap_or(false)
317    }
318
319    /// Reports whether `name` is a global label.
320    pub fn is_global_label(&self, name: &str) -> bool {
321        self.labels.get(name).map(|f| f.global).unwrap_or(false)
322    }
323
324    /// Clears the referenced-extern list.
325    pub fn reset_referenced(&mut self) {
326        self.referenced_extern.clear();
327    }
328
329    /// Records `name` as referenced when it is extern.
330    pub fn mark_used(&mut self, name: &str) {
331        let is_extern = self.is_extern_label(name);
332        if is_extern && !self.referenced_extern.contains(&name.to_string()) {
333            self.referenced_extern.push(name.to_string());
334        }
335    }
336}
337
338/// Holds one offlineasm syntax tree node.
339#[derive(Clone, Debug)]
340pub enum Node {
341    StructOffset {
342        origin: CodeOrigin,
343        struct_name: String,
344        field: String,
345    },
346    Sizeof {
347        origin: CodeOrigin,
348        struct_name: String,
349    },
350    /// Holds an integer literal or folded immediate.
351    Immediate {
352        origin: CodeOrigin,
353        value: i128,
354    },
355    Add {
356        origin: CodeOrigin,
357        left: Box<Node>,
358        right: Box<Node>,
359    },
360    Sub {
361        origin: CodeOrigin,
362        left: Box<Node>,
363        right: Box<Node>,
364    },
365    Mul {
366        origin: CodeOrigin,
367        left: Box<Node>,
368        right: Box<Node>,
369    },
370    Neg {
371        origin: CodeOrigin,
372        child: Box<Node>,
373    },
374    Or {
375        origin: CodeOrigin,
376        left: Box<Node>,
377        right: Box<Node>,
378    },
379    And {
380        origin: CodeOrigin,
381        left: Box<Node>,
382        right: Box<Node>,
383    },
384    Xor {
385        origin: CodeOrigin,
386        left: Box<Node>,
387        right: Box<Node>,
388    },
389    Bitnot {
390        origin: CodeOrigin,
391        child: Box<Node>,
392    },
393    StringLiteral {
394        origin: CodeOrigin,
395        value: String,
396    },
397    Register {
398        origin: CodeOrigin,
399        name: String,
400    },
401    FpRegister {
402        origin: CodeOrigin,
403        name: String,
404    },
405    VecRegister {
406        origin: CodeOrigin,
407        name: String,
408    },
409    SpecialRegister {
410        name: String,
411    },
412    Variable {
413        origin: CodeOrigin,
414        name: String,
415        original_name: String,
416    },
417    Address {
418        origin: CodeOrigin,
419        base: Box<Node>,
420        offset: Box<Node>,
421    },
422    BaseIndex {
423        origin: CodeOrigin,
424        base: Box<Node>,
425        index: Box<Node>,
426        scale: Box<Node>,
427        offset: Box<Node>,
428    },
429    AbsoluteAddress {
430        origin: CodeOrigin,
431        address: Box<Node>,
432    },
433    Instruction {
434        origin: CodeOrigin,
435        opcode: String,
436        operands: Vec<Node>,
437        annotation: Option<String>,
438    },
439    Error {
440        origin: CodeOrigin,
441    },
442    /// Holds the (possibly `$param`-unsubstituted) tokens of a
443    /// `const { ... }` block, or of the narrower `constexpr(...)`/
444    /// `constexpr a::b::c` forms used in an address's scale position.
445    ConstExpr {
446        origin: CodeOrigin,
447        value: proc_macro2::TokenStream,
448    },
449    ConstDecl {
450        origin: CodeOrigin,
451        variable: Box<Node>,
452        value: Box<Node>,
453    },
454    Label {
455        origin: CodeOrigin,
456        name: String,
457    },
458    LocalLabel {
459        origin: CodeOrigin,
460        name: String,
461    },
462    LabelReference {
463        origin: CodeOrigin,
464        label: String,
465        offset: i64,
466    },
467    LocalLabelReference {
468        origin: CodeOrigin,
469        label: String,
470    },
471    Sequence {
472        origin: CodeOrigin,
473        list: Vec<Node>,
474    },
475    True,
476    False,
477    Setting {
478        origin: CodeOrigin,
479        name: String,
480    },
481    AndPred {
482        origin: CodeOrigin,
483        left: Box<Node>,
484        right: Box<Node>,
485    },
486    OrPred {
487        origin: CodeOrigin,
488        left: Box<Node>,
489        right: Box<Node>,
490    },
491    NotPred {
492        origin: CodeOrigin,
493        child: Box<Node>,
494    },
495    Skip {
496        origin: CodeOrigin,
497    },
498    IfThenElse {
499        origin: CodeOrigin,
500        predicate: Box<Node>,
501        then_case: Box<Node>,
502        else_case: Box<Node>,
503    },
504    Macro {
505        origin: CodeOrigin,
506        name: Option<String>,
507        variables: Vec<Node>,
508        body: Box<Node>,
509    },
510    MacroCall {
511        origin: CodeOrigin,
512        name: String,
513        operands: Vec<Node>,
514        annotation: Option<String>,
515        original_name: String,
516    },
517
518    RustConst {
519        origin: CodeOrigin,
520        ident: String,
521        expr: syn::Expr,
522    },
523}
524
525impl Node {
526    /// Returns the origin string, or `<builtin>` when absent.
527    pub fn origin_string(&self) -> String {
528        self.origin()
529            .map(|o| o.origin_string())
530            .unwrap_or_else(|| "<builtin>".to_string())
531    }
532
533    /// Returns the origin, when the node carries one.
534    pub fn origin(&self) -> Option<&CodeOrigin> {
535        match self {
536            Node::StructOffset { origin, .. }
537            | Node::Sizeof { origin, .. }
538            | Node::Immediate { origin, .. }
539            | Node::Add { origin, .. }
540            | Node::Sub { origin, .. }
541            | Node::Mul { origin, .. }
542            | Node::Neg { origin, .. }
543            | Node::Or { origin, .. }
544            | Node::And { origin, .. }
545            | Node::Xor { origin, .. }
546            | Node::Bitnot { origin, .. }
547            | Node::StringLiteral { origin, .. }
548            | Node::Register { origin, .. }
549            | Node::FpRegister { origin, .. }
550            | Node::VecRegister { origin, .. }
551            | Node::Variable { origin, .. }
552            | Node::Address { origin, .. }
553            | Node::BaseIndex { origin, .. }
554            | Node::AbsoluteAddress { origin, .. }
555            | Node::Instruction { origin, .. }
556            | Node::Error { origin }
557            | Node::ConstExpr { origin, .. }
558            | Node::ConstDecl { origin, .. }
559            | Node::Label { origin, .. }
560            | Node::LocalLabel { origin, .. }
561            | Node::LabelReference { origin, .. }
562            | Node::LocalLabelReference { origin, .. }
563            | Node::Sequence { origin, .. }
564            | Node::Setting { origin, .. }
565            | Node::AndPred { origin, .. }
566            | Node::OrPred { origin, .. }
567            | Node::NotPred { origin, .. }
568            | Node::Skip { origin }
569            | Node::IfThenElse { origin, .. }
570            | Node::Macro { origin, .. }
571            | Node::MacroCall { origin, .. }
572            | Node::RustConst { origin, .. } => Some(origin),
573            Node::SpecialRegister { .. } | Node::True | Node::False => None,
574        }
575    }
576
577    /// Clones the origin, or a builtin origin when absent.
578    pub fn origin_cloned(&self) -> CodeOrigin {
579        self.origin().cloned().unwrap_or_else(builtin_origin)
580    }
581
582    /// Lists the direct children.
583    pub fn children(&self) -> Vec<&Node> {
584        match self {
585            Node::Add { left, right, .. }
586            | Node::Sub { left, right, .. }
587            | Node::Mul { left, right, .. }
588            | Node::Or { left, right, .. }
589            | Node::And { left, right, .. }
590            | Node::Xor { left, right, .. }
591            | Node::AndPred { left, right, .. }
592            | Node::OrPred { left, right, .. } => vec![left, right],
593            Node::Neg { child, .. } | Node::Bitnot { child, .. } | Node::NotPred { child, .. } => {
594                vec![child]
595            }
596            Node::Address { base, offset, .. } => vec![base, offset],
597            Node::AbsoluteAddress { address, .. } => vec![address],
598            Node::BaseIndex {
599                base,
600                index,
601                offset,
602                ..
603            } => vec![base, index, offset],
604            Node::Instruction { operands, .. } => operands.iter().collect(),
605            Node::ConstDecl {
606                variable, value, ..
607            } => vec![variable, value],
608            Node::Sequence { list, .. } => list.iter().collect(),
609            Node::IfThenElse {
610                predicate,
611                then_case,
612                else_case,
613                ..
614            } => vec![predicate, then_case, else_case],
615            Node::Macro {
616                variables, body, ..
617            } => {
618                let mut v: Vec<&Node> = variables.iter().collect();
619                v.push(body);
620                v
621            }
622            Node::MacroCall { operands, .. } => operands.iter().collect(),
623            _ => vec![],
624        }
625    }
626
627    /// Lists all descendants depth-first.
628    pub fn descendants(&self) -> Vec<&Node> {
629        let mut out = Vec::new();
630        for child in self.children() {
631            out.push(child);
632            out.extend(child.descendants());
633        }
634        out
635    }
636
637    /// Lists the node plus all descendants.
638    pub fn flatten_vec(&self) -> Vec<&Node> {
639        let mut out = vec![self];
640        out.extend(self.descendants());
641        out
642    }
643
644    /// Reports whether the node is an address form.
645    pub fn is_address(&self) -> bool {
646        matches!(
647            self,
648            Node::Address { .. } | Node::BaseIndex { .. } | Node::AbsoluteAddress { .. }
649        )
650    }
651
652    /// Reports whether the node references a label.
653    pub fn is_label_node(&self) -> bool {
654        matches!(
655            self,
656            Node::LabelReference { .. } | Node::LocalLabelReference { .. }
657        )
658    }
659
660    /// Reports whether the node is a symbolic Rust const placeholder.
661    pub fn is_rust_const(&self) -> bool {
662        matches!(self, Node::RustConst { .. })
663    }
664
665    /// Reports whether the node is an immediate expression.
666    pub fn is_immediate(&self) -> bool {
667        matches!(
668            self,
669            Node::StructOffset { .. }
670                | Node::Sizeof { .. }
671                | Node::Immediate { .. }
672                | Node::Add { .. }
673                | Node::Sub { .. }
674                | Node::Mul { .. }
675                | Node::Neg { .. }
676                | Node::Or { .. }
677                | Node::And { .. }
678                | Node::Xor { .. }
679                | Node::Bitnot { .. }
680                | Node::ConstExpr { .. }
681        )
682    }
683
684    /// Reports whether the node names a register.
685    pub fn is_register_node(&self) -> bool {
686        matches!(
687            self,
688            Node::Register { .. }
689                | Node::FpRegister { .. }
690                | Node::VecRegister { .. }
691                | Node::SpecialRegister { .. }
692        )
693    }
694
695    /// Reports whether the node is an immediate operand.
696    pub fn is_immediate_operand(&self) -> bool {
697        matches!(
698            self,
699            Node::Immediate { .. }
700                | Node::Add { .. }
701                | Node::Sub { .. }
702                | Node::Address { .. }
703                | Node::AbsoluteAddress { .. }
704                | Node::LabelReference { .. }
705                | Node::LocalLabelReference { .. }
706                | Node::RustConst { .. }
707        )
708    }
709
710    /// Returns the variable name, when the node is a variable.
711    pub fn variable_name(&self) -> Option<&str> {
712        match self {
713            Node::Variable { name, .. } => Some(name),
714            _ => None,
715        }
716    }
717
718    /// Returns the literal value, when the node is an immediate.
719    pub fn immediate_value(&self) -> Option<i128> {
720        match self {
721            Node::Immediate { value, .. } => Some(*value),
722            _ => None,
723        }
724    }
725
726    /// Copies an address node with `extra` added to its offset.
727    ///
728    /// Returns `None` when the node is not an address form.
729    pub fn with_offset(&self, extra: i128) -> Option<Node> {
730        let origin = self.origin_cloned();
731        match self {
732            Node::Address { base, offset, .. } => {
733                let base_offset = offset.immediate_value().unwrap_or(0);
734                Some(Node::Address {
735                    origin,
736                    base: base.clone(),
737                    offset: Box::new(Node::Immediate {
738                        origin: self.origin_cloned(),
739                        value: base_offset + extra,
740                    }),
741                })
742            }
743            Node::BaseIndex {
744                base,
745                index,
746                scale,
747                offset,
748                ..
749            } => {
750                let base_offset = offset.immediate_value().unwrap_or(0);
751                Some(Node::BaseIndex {
752                    origin,
753                    base: base.clone(),
754                    index: index.clone(),
755                    scale: scale.clone(),
756                    offset: Box::new(Node::Immediate {
757                        origin: self.origin_cloned(),
758                        value: base_offset + extra,
759                    }),
760                })
761            }
762            Node::AbsoluteAddress { address, .. } => {
763                let base_value = address.immediate_value().unwrap_or(0);
764                Some(Node::AbsoluteAddress {
765                    origin,
766                    address: Box::new(Node::Immediate {
767                        origin: self.origin_cloned(),
768                        value: base_value + extra,
769                    }),
770                })
771            }
772            _ => None,
773        }
774    }
775
776    /// Copies a label reference with `extra` added to its offset.
777    ///
778    /// Returns `None` when the node is not a label reference or `extra`
779    /// does not fit in an `i64`.
780    pub fn plus_offset(&self, extra: i128) -> Option<Node> {
781        match self {
782            Node::LabelReference {
783                origin,
784                label,
785                offset,
786            } => Some(Node::LabelReference {
787                origin: origin.clone(),
788                label: label.clone(),
789                offset: offset + i64::try_from(extra).ok()?,
790            }),
791            _ => None,
792        }
793    }
794
795    /// Returns the scale of a `BaseIndex` node.
796    ///
797    /// # Errors
798    ///
799    /// Returns an error if the node is not a `BaseIndex`, or if its scale
800    /// is not 1, 2, 4, or 8.
801    pub fn scale_value(&self) -> Result<i128, String> {
802        match self {
803            Node::BaseIndex { scale, .. } => match scale.as_ref() {
804                Node::Immediate { value, .. } if [1, 2, 4, 8].contains(value) => Ok(*value),
805                other => Err(format!(
806                    "Bad scale: {} at {}",
807                    other.dump(),
808                    self.origin_string()
809                )),
810            },
811            _ => Err(format!("Not a BaseIndex at {}", self.origin_string())),
812        }
813    }
814
815    /// Returns the shift matching the scale of a `BaseIndex` node.
816    ///
817    /// # Errors
818    ///
819    /// Returns an error for any reason [`Node::scale_value`] can.
820    pub fn scale_shift(&self) -> Result<u32, String> {
821        match i64::try_from(self.scale_value()?)
822            .map_err(|_| format!("Bad scale at {}", self.origin_string()))?
823        {
824            1 => Ok(0),
825            2 => Ok(1),
826            4 => Ok(2),
827            8 => Ok(3),
828            v => Err(format!("Bad scale: {} at {}", v, self.origin_string())),
829        }
830    }
831
832    /// Renders the canonical text of the node.
833    ///
834    /// Offset keys and error messages use this form.
835    pub fn dump(&self) -> String {
836        match self {
837            Node::StructOffset {
838                struct_name, field, ..
839            } => format!("{}::{}", struct_name, field),
840            Node::Sizeof { struct_name, .. } => format!("sizeof {}", struct_name),
841            Node::Immediate { value, .. } => format!("{}", value),
842            Node::Add { left, right, .. } => format!("({} + {})", left.dump(), right.dump()),
843            Node::Sub { left, right, .. } => format!("({} - {})", left.dump(), right.dump()),
844            Node::Mul { left, right, .. } => format!("({} * {})", left.dump(), right.dump()),
845            Node::Neg { child, .. } => format!("(-{})", child.dump()),
846            Node::Or { left, right, .. } => format!("({} | {})", left.dump(), right.dump()),
847            Node::And { left, right, .. } => format!("({} & {})", left.dump(), right.dump()),
848            Node::Xor { left, right, .. } => format!("({} ^ {})", left.dump(), right.dump()),
849            Node::Bitnot { child, .. } => format!("(~{})", child.dump()),
850            Node::StringLiteral { value, .. } => value.clone(),
851            Node::Register { name, .. }
852            | Node::FpRegister { name, .. }
853            | Node::VecRegister { name, .. } => name.clone(),
854            Node::SpecialRegister { name } => name.clone(),
855            Node::Variable { original_name, .. } => original_name.clone(),
856            Node::Address { base, offset, .. } => format!("{}[{}]", offset.dump(), base.dump()),
857            Node::BaseIndex {
858                base,
859                index,
860                scale,
861                offset,
862                ..
863            } => {
864                format!(
865                    "{}[{}, {}, {}]",
866                    offset.dump(),
867                    base.dump(),
868                    index.dump(),
869                    scale.dump()
870                )
871            }
872            Node::AbsoluteAddress { address, .. } => format!("{}[]", address.dump()),
873            Node::Instruction {
874                opcode, operands, ..
875            } => {
876                format!(
877                    "\t{} {}",
878                    opcode,
879                    operands
880                        .iter()
881                        .map(|o| o.dump())
882                        .collect::<Vec<_>>()
883                        .join(", ")
884                )
885            }
886            Node::Error { .. } => "\terror".to_string(),
887            Node::ConstExpr { value, .. } => format!("const {{ {} }}", quote::quote!(#value)),
888            Node::ConstDecl {
889                variable, value, ..
890            } => format!("const {} = {}", variable.dump(), value.dump()),
891            Node::Label { name, .. } | Node::LocalLabel { name, .. } => format!("{}:", name),
892            Node::LabelReference { label, .. } | Node::LocalLabelReference { label, .. } => {
893                label.clone()
894            }
895            Node::Sequence { list, .. } => {
896                list.iter().map(|n| n.dump()).collect::<Vec<_>>().join("\n")
897            }
898            Node::True => "true".to_string(),
899            Node::False => "false".to_string(),
900            Node::Setting { name, .. } => name.clone(),
901            Node::AndPred { left, right, .. } => format!("({} and {})", left.dump(), right.dump()),
902            Node::OrPred { left, right, .. } => format!("({} or {})", left.dump(), right.dump()),
903            Node::NotPred { child, .. } => format!("(not {})", child.dump()),
904            Node::Skip { .. } => "\tskip".to_string(),
905            Node::IfThenElse {
906                predicate,
907                then_case,
908                else_case,
909                ..
910            } => {
911                format!(
912                    "if {}\n{}\nelse\n{}\nend",
913                    predicate.dump(),
914                    then_case.dump(),
915                    else_case.dump()
916                )
917            }
918            Node::Macro {
919                name,
920                variables,
921                body,
922                ..
923            } => format!(
924                "macro {}({})\n{}\nend",
925                name.clone().unwrap_or_default(),
926                variables
927                    .iter()
928                    .map(|v| v.dump())
929                    .collect::<Vec<_>>()
930                    .join(", "),
931                body.dump()
932            ),
933            Node::MacroCall {
934                original_name,
935                operands,
936                ..
937            } => {
938                format!(
939                    "\t{}({})",
940                    original_name,
941                    operands
942                        .iter()
943                        .map(|o| o.dump())
944                        .collect::<Vec<_>>()
945                        .join(", ")
946                )
947            }
948            Node::RustConst { ident, .. } => ident.clone(),
949        }
950    }
951}