liil/

nnil.rs

//! The lifter stores guest operations here so that backends do not have to decode RISC-V.
//!
//! NNIL is a linear, append-only intermediate representation. Each operation gets an [`Insn`]
//! handle. A later operation uses that handle to refer to the earlier result. This design is
//! similar to a value graph, but explicit `Reg`, `Set`, load, store, and control-flow operations
//! keep guest state visible.
//!
//! NNIL stores integer and address bits in one backend value width. `Signed` and `Unsigned`
//! operations add interpretation information when the same bits need different arithmetic.
//! Memory and extension sizes are byte counts. For example, size 4 means 32 bits.

use std::collections::BTreeMap;

// These macros keep all simple emitters consistent with the append-only instruction model.
// A Rust macro writes repeated source code at compile time. It does not add a run-time call.
// `$func` is the generated method name. `$insn` is the matching enum variant name.
macro_rules! emit_alu {
    ($func:ident, $insn:ident) => {
        /// Appends this two-input value operation and returns its stable result handle.
        pub fn $func(&mut self, lhs: Insn, rhs: Insn) -> Insn {
            // The next vector index is also the stable handle for the new result.
            let ret = self.insns.len();
            // Store operand handles instead of operand copies so the backend can follow values.
            self.insns.push(NnilInstruction::$insn { lhs, rhs });
            // Use `u64` for handles so the public IR does not depend on the host `usize` width.
            Insn(ret as u64)
        }
    };
}

macro_rules! emit_branch {
    ($func:ident, $insn:ident) => {
        /// Appends this comparison branch with explicit true and false targets.
        pub fn $func(&mut self, lhs: Insn, rhs: Insn, ttgt: Label, ftgt: Label) -> Insn {
            let ret = self.insns.len();
            // Store both targets. A basic block must state where both comparison results go.
            self.insns.push(NnilInstruction::$insn {
                lhs,
                rhs,
                ttgt,
                ftgt,
            });
            Insn(ret as u64)
        }
    };
}

macro_rules! emit_mem {
    ($func:ident, $insn:ident) => {
        /// Appends this memory operation with an explicit byte width.
        pub fn $func(&mut self, dst: Insn, src: Insn, size: u64) -> Insn {
            let ret = self.insns.len();
            // The same shape supports load and store. Their variants define operand direction.
            self.insns.push(NnilInstruction::$insn { dst, src, size });
            Insn(ret as u64)
        }
    };
}

macro_rules! emit_ext {
    ($func:ident, $insn:ident) => {
        /// Appends this width extension so the backend does not infer a guest width.
        pub fn $func(&mut self, size: usize, dst: Insn) -> Insn {
            let ret = self.insns.len();
            // Keep extension width explicit because guest XLEN can differ from host width.
            self.insns.push(NnilInstruction::$insn { size, dst });
            Insn(ret as u64)
        }
    };
}

macro_rules! emit_sys {
    ($func:ident, $insn:ident) => {
        /// Appends this runtime exit and returns its stable operation handle.
        pub fn $func(&mut self) -> Insn {
            let ret = self.insns.len();
            // System exits have no value operands, but they still need an index and boundary.
            self.insns.push(NnilInstruction::$insn {});
            Insn(ret as u64)
        }
    };
}

macro_rules! emit_sign {
    ($func:ident, $insn:ident) => {
        /// Appends this arithmetic interpretation marker without changing the input bits.
        pub fn $func(&mut self, dst: Insn) -> Insn {
            let ret = self.insns.len();
            // Signedness is a backend marker. It preserves the input bits without conversion.
            self.insns.push(NnilInstruction::$insn { dst });
            Insn(ret as u64)
        }
    };
}

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
/// Identifies an NNIL value by its stable position in the instruction list.
///
/// The tuple field is public so a backend can use the number directly. The wrapper prevents a
/// value handle from being used by mistake as a guest address or label.
pub struct Insn(pub u64);
impl std::fmt::Debug for Insn {
    // Keep the type name in debug output because a bare number could mean an address or register.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Insn({})", self.0)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
/// Identifies a branch target without storing a temporary instruction index.
///
/// A label number indexes `Nnil::label_addrs`. It stays valid when more NNIL operations are added.
pub struct Label(pub u64);

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
/// Keeps guest addresses distinct from instruction and label identifiers.
///
/// Guest addresses use `u64` because the current runtime stores guest PCs in 64 bits.
pub struct Address(pub u64);

#[derive(Clone, Copy, PartialEq, Eq)]
/// Represents guest semantics in a form that the JIT can emit directly.
///
/// Most operands are [`Insn`] handles. `lhs` and `rhs` are value inputs. A `dst` can be a value
/// input or a write target, depending on the operation. Load, `Mov`, `Set`, LR, SC, and AMO use
/// a register-like `dst` as a write target. The operation index is also its result handle.
pub enum NnilInstruction {
    /// Adds two bit patterns with wrapping semantics because guest overflow does not panic.
    Add {
        /// Supplies the left input value.
        lhs: Insn,
        /// Supplies the right input value.
        rhs: Insn,
    },
    /// Subtracts with wrapping semantics for the same guest-overflow rule.
    Sub {
        /// Supplies the value to subtract from.
        lhs: Insn,
        /// Supplies the value to subtract.
        rhs: Insn,
    },
    /// Produces the low backend-width part of an integer product.
    Mul {
        /// Supplies the left factor.
        lhs: Insn,
        /// Supplies the right factor.
        rhs: Insn,
    },
    /// Produces the high backend-width part of a double-width product.
    /// Signedness markers on the operands select MULH, MULHSU, or MULHU behavior.
    Mulh {
        /// Supplies the left factor and its signedness marker.
        lhs: Insn,
        /// Supplies the right factor and its signedness marker.
        rhs: Insn,
    },
    /// Divides integer values. Operand markers select signed or unsigned behavior.
    Div {
        /// Supplies the dividend and its signedness marker.
        lhs: Insn,
        /// Supplies the divisor and its signedness marker.
        rhs: Insn,
    },
    /// Produces an integer remainder. Operand markers select signed or unsigned behavior.
    Mod {
        /// Supplies the dividend and its signedness marker.
        lhs: Insn,
        /// Supplies the divisor and its signedness marker.
        rhs: Insn,
    },
    /// Divides IEEE floating-point bit patterns at the selected byte width.
    Fdiv {
        /// Supplies the floating-point dividend bits.
        lhs: Insn,
        /// Supplies the floating-point divisor bits.
        rhs: Insn,
        // Four bytes select f32 and eight bytes select f64 in the current backend.
        /// Selects the floating-point width as a byte count.
        size: usize,
    },
    /// Performs bitwise AND without a signedness distinction.
    And {
        /// Supplies the left input bits.
        lhs: Insn,
        /// Supplies the right input bits.
        rhs: Insn,
    },
    /// Performs bitwise OR without a signedness distinction.
    Or {
        /// Supplies the left input bits.
        lhs: Insn,
        /// Supplies the right input bits.
        rhs: Insn,
    },
    /// Performs bitwise exclusive OR without a signedness distinction.
    Xor {
        /// Supplies the left input bits.
        lhs: Insn,
        /// Supplies the right input bits.
        rhs: Insn,
    },
    /// Shifts left and fills low bits with zero.
    Sll {
        /// Supplies the value to shift.
        lhs: Insn,
        /// Supplies the shift count.
        rhs: Insn,
    },
    /// Shifts right and fills high bits with zero.
    Srl {
        /// Supplies the value to shift.
        lhs: Insn,
        /// Supplies the shift count.
        rhs: Insn,
    },
    /// Shifts right and copies the sign bit into high bits.
    Sra {
        /// Supplies the signed value to shift.
        lhs: Insn,
        /// Supplies the shift count.
        rhs: Insn,
    },
    /// Returns one or zero for a less-than comparison.
    /// Operand markers tell the backend whether it must compare signed or unsigned values.
    Slt {
        /// Supplies the left comparison value.
        lhs: Insn,
        /// Supplies the right comparison value.
        rhs: Insn,
    },

    /// Copies a value to a write target.
    Mov {
        /// Selects the register-like write target.
        dst: Insn,
        /// Supplies the value to copy.
        src: Insn,
    },
    /// Writes a computed value to a guest register or temporary target.
    Set {
        /// Selects the guest register or temporary write target.
        dst: Insn,
        /// Supplies the value to write.
        src: Insn,
    },

    /// Transfers control to a computed address value and ends the current basic block.
    Jr {
        /// Supplies the computed guest target address.
        dst: Insn,
    },
    /// Transfers control to a direct or computed value and ends the current basic block.
    Jmp {
        /// Supplies the direct or computed guest target address.
        dst: Insn,
    },

    // Both labels are explicit because emitted basic blocks cannot depend on list fallthrough.
    /// Branches to `ttgt` when two values are equal. Otherwise it branches to `ftgt`.
    Beq {
        /// Supplies the left comparison value.
        lhs: Insn,
        /// Supplies the right comparison value.
        rhs: Insn,
        /// Selects the target when the values are equal.
        ttgt: Label,
        /// Selects the target when the values differ.
        ftgt: Label,
    },
    /// Branches to `ttgt` when two values differ. Otherwise it branches to `ftgt`.
    Bne {
        /// Supplies the left comparison value.
        lhs: Insn,
        /// Supplies the right comparison value.
        rhs: Insn,
        /// Selects the target when the values differ.
        ttgt: Label,
        /// Selects the target when the values are equal.
        ftgt: Label,
    },
    /// Branches on less-than. Operand markers select signed or unsigned comparison.
    Blt {
        /// Supplies the left comparison value.
        lhs: Insn,
        /// Supplies the right comparison value.
        rhs: Insn,
        /// Selects the target when `lhs` is less than `rhs`.
        ttgt: Label,
        /// Selects the other target.
        ftgt: Label,
    },
    /// Branches on greater-than. Operand markers select signed or unsigned comparison.
    Bgt {
        /// Supplies the left comparison value.
        lhs: Insn,
        /// Supplies the right comparison value.
        rhs: Insn,
        /// Selects the target when `lhs` is greater than `rhs`.
        ttgt: Label,
        /// Selects the other target.
        ftgt: Label,
    },

    /// Reads `size` bytes at address `src` and writes the result through `dst`.
    /// A later `Unsigned` marker requests zero extension. Integer loads otherwise sign-extend.
    Load {
        /// Selects the register-like target for the loaded value.
        dst: Insn,
        /// Supplies the guest source address.
        src: Insn,
        /// Selects the memory width as a byte count.
        size: u64,
    },
    /// Writes the low `size` bytes of `src` to address `dst`.
    Store {
        /// Supplies the guest destination address.
        dst: Insn,
        /// Supplies the value whose low bytes are stored.
        src: Insn,
        /// Selects the memory width as a byte count.
        size: u64,
    },

    /// Sign-extends the low `size` bytes to the backend value width.
    Sext {
        /// Selects the input width as a byte count.
        size: usize,
        /// Supplies the value to extend.
        dst: Insn,
    },
    /// Zero-extends the low `size` bytes to the backend value width.
    Zext {
        /// Selects the input width as a byte count.
        size: usize,
        /// Supplies the value to extend.
        dst: Insn,
    },
    /// Marks a value for signed arithmetic without changing its bits.
    Signed {
        /// Supplies the value that later arithmetic must interpret as signed.
        dst: Insn,
    },
    /// Marks a value for unsigned arithmetic without changing its bits.
    Unsigned {
        /// Supplies the value that later arithmetic must interpret as unsigned.
        dst: Insn,
    },
    /// Converts an integer value to an IEEE floating-point bit pattern.
    IntToFloat {
        /// Supplies the integer bits to convert.
        src: Insn,
        // Sizes are byte counts, so 4 and 8 select 32-bit and 64-bit source values.
        /// Selects the integer source width as a byte count.
        src_size: usize,
        // A Boolean keeps signedness explicit without two conversion variants.
        /// Selects signed or unsigned integer interpretation.
        signed: bool,
        // Destination sizes are byte counts: 4 selects f32 and 8 selects f64.
        // The current Rust backend emits only the eight-byte form.
        /// Selects the floating-point result width as a byte count.
        dst_size: usize,
    },

    /// Creates a constant. Signed storage keeps negative RISC-V immediates direct.
    Imm {
        /// Stores the signed constant directly.
        imm: i64,
    },
    /// Reads one architectural register. The backend enforces special rules such as x0.
    Reg {
        /// Selects a register in the combined integer and floating-point namespace.
        reg: u64,
    },
    /// Reads one translator-private temporary register without using a guest register number.
    TmpReg {
        /// Selects a translator-private temporary index.
        reg: u64,
    },

    /// Returns control to the runtime for an execution-environment call.
    Syscall {},
    /// Returns control to the runtime for a guest breakpoint.
    Sysbreak {},

    /// Loads a value and starts an atomic reservation for the addressed memory.
    /// The current Rust backend does not keep reservation state, which is an implementation limit.
    Lr {
        /// Selects the register-like target for the loaded value.
        dst: Insn,
        /// Supplies the guest source address.
        src: Insn,
        /// Selects the access width as a byte count.
        size: u64,
    },
    
    /// Stores through a reservation and writes the success code through `dst`.
    /// The current Rust backend always reports success because it does not model reservations.
    Sc {
        /// Selects the target for the architectural success code.
        dst: Insn,
        /// Supplies the value to store.
        src: Insn,
        /// Supplies the reserved guest address.
        addr: Insn,
        /// Selects the access width as a byte count.
        size: u64,
    },
    /// Performs one atomic read-modify-write operation and returns the old memory value.
    Amo {
        /// Selects how the loaded and source values form the stored value.
        op: AmoOp,
        /// Selects the target for the old memory value.
        dst: Insn,
        /// Supplies the value combined with memory.
        src: Insn,
        /// Supplies the guest memory address.
        addr: Insn,
        /// Selects the access width as a byte count.
        size: u64,
    },

    /// Carries guest memory-order information even when a single-threaded backend needs no code.
    Fence {
        // Four mode bits permit FENCE extensions such as total-store-order encodings.
        /// Keeps extension-specific fence mode bits.
        mode: u8,
        // The four predecessor and successor bits select I/O, memory read, and memory write classes.
        /// Selects predecessor access classes that must complete first.
        pred: u8,
        // Keep the successor mask separate because FENCE orders selected earlier and later classes.
        /// Selects successor access classes that must start later.
        succ: u8,
    },
}

#[derive(Clone, Copy, PartialEq, Eq)]
/// Selects an atomic operation while one instruction form supplies the common operands.
///
/// The A extension gives all AMOs the same address, source, destination, and width fields.
/// A small enum avoids duplicate NNIL variants for that common structure.
pub enum AmoOp {
    /// Stores the source value without combining it with the loaded value.
    Swap,
    /// Stores the wrapping sum of the loaded and source values.
    Add,
    /// Stores the bitwise exclusive OR of both values.
    Xor,
    /// Stores the bitwise AND of both values.
    And,
    /// Stores the bitwise OR of both values.
    Or,
    /// Stores the smaller signed value.
    Min,
    /// Stores the larger signed value.
    Max,
    /// Stores the smaller unsigned value.
    Minu,
    /// Stores the larger unsigned value.
    Maxu,
}

impl std::fmt::Debug for AmoOp {
    // Use RISC-V mnemonic suffixes so a developer can compare output with a disassembler.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Swap => write!(f, "swap"),
            Self::Add => write!(f, "add"),
            Self::Xor => write!(f, "xor"),
            Self::And => write!(f, "and"),
            Self::Or => write!(f, "or"),
            Self::Min => write!(f, "min"),
            Self::Max => write!(f, "max"),
            Self::Minu => write!(f, "minu"),
            Self::Maxu => write!(f, "maxu"),
        }
    }
}

impl std::fmt::Debug for NnilInstruction {
    // Print a compact assembly-like form so lifted output is easy to compare by eye.
    // This output is diagnostic text. It does not control execution semantics.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Add { lhs, rhs } => write!(f, "add {lhs:?}, {rhs:?}"),
            Self::Sub { lhs, rhs } => write!(f, "sub {lhs:?}, {rhs:?}"),
            Self::Mul { lhs, rhs } => write!(f, "mul {lhs:?}, {rhs:?}"),
            Self::Mulh { lhs, rhs } => write!(f, "mulh {lhs:?}, {rhs:?}"),
            Self::Div { lhs, rhs } => write!(f, "div {lhs:?}, {rhs:?}"),
            Self::Mod { lhs, rhs } => write!(f, "mod {lhs:?}, {rhs:?}"),
            Self::Fdiv { lhs, rhs, size } => match size {
                // Floating-point sizes are bytes: 4, 8, and 16 mean 32, 64, and 128 bits.
                4 => write!(f, "fdiv.s {lhs:?}, {rhs:?}"),
                8 => write!(f, "fdiv.d {lhs:?}, {rhs:?}"),
                16 => write!(f, "fdiv.q {lhs:?}, {rhs:?}"),
                _ => write!(f, "fdiv.{size} {lhs:?}, {rhs:?}"),
            },
            Self::And { lhs, rhs } => write!(f, "and {lhs:?}, {rhs:?}"),
            Self::Or { lhs, rhs } => write!(f, "or {lhs:?}, {rhs:?}"),
            Self::Xor { lhs, rhs } => write!(f, "xor {lhs:?}, {rhs:?}"),
            Self::Sll { lhs, rhs } => write!(f, "sll {lhs:?}, {rhs:?}"),
            Self::Srl { lhs, rhs } => write!(f, "srl {lhs:?}, {rhs:?}"),
            Self::Sra { lhs, rhs } => write!(f, "sra {lhs:?}, {rhs:?}"),
            Self::Slt { lhs, rhs } => write!(f, "slt {lhs:?}, {rhs:?}"),

            Self::Mov { dst, src } => write!(f, "mov {dst:?}, {src:?}"),
            Self::Set { dst, src } => write!(f, "set {dst:?}, {src:?}"),

            Self::Jr { dst } => write!(f, "jr {dst:?}"),
            Self::Jmp { dst } => write!(f, "jmp {dst:?}"),

            Self::Beq {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => write!(f, "beq {lhs:?}, {rhs:?} => {ttgt:?} ({ftgt:?})"),
            Self::Bne {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => write!(f, "bne {lhs:?}, {rhs:?} => {ttgt:?} ({ftgt:?})"),
            Self::Blt {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => write!(f, "blt {lhs:?}, {rhs:?} => {ttgt:?} ({ftgt:?})"),
            Self::Bgt {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => write!(f, "bgt {lhs:?}, {rhs:?} => {ttgt:?} ({ftgt:?})"),

            Self::Load { dst, src, size } => {
                let size = match size {
                    // These are internal debug suffixes. `q` means eight bytes here; it is not
                    // RISC-V Q, which means a 16-byte value.
                    1 => "b",
                    2 => "h",
                    4 => "w",
                    8 => "q",
                    _ => unreachable!("unknown size for load {}", size),
                };
                write!(f, "l{size} {dst:?}, ({src:?})")
            }
            Self::Store { dst, src, size } => {
                let size = match size {
                    // Use the same internal byte-count suffixes as loads. Thus, `q` is eight
                    // bytes here and does not mean the 16-byte RISC-V Q format.
                    1 => "b",
                    2 => "h",
                    4 => "w",
                    8 => "q",
                    _ => unreachable!("unknown size for store {}", size),
                };
                write!(f, "s{size} {src:?}, ({dst:?})")
            }

            Self::Sext { size, dst } => {
                let size = match size {
                    // Extension width is also a byte count. The suffix states the source width;
                    // internal `q` means eight bytes.
                    1 => "b",
                    2 => "h",
                    4 => "w",
                    8 => "q",
                    _ => unreachable!("unknown size for store {}", size),
                };
                write!(f, "sext.{size} {dst:?}")
            }
            Self::Zext { size, dst } => {
                let size = match size {
                    // Zero extension uses the same 1, 2, 4, and 8 byte vocabulary.
                    1 => "b",
                    2 => "h",
                    4 => "w",
                    8 => "q",
                    _ => unreachable!("unknown size for store {}", size),
                };
                write!(f, "zext.{size} {dst:?}")
            }
            Self::Signed { dst } => write!(f, "signed {dst:?}"),
            Self::Unsigned { dst } => write!(f, "unsigned {dst:?}"),
            Self::IntToFloat {
                src,
                src_size,
                signed,
                dst_size,
            } => {
                // A leading `i` or `u` makes integer signedness visible in diagnostic output.
                let src_ty = if *signed { "i" } else { "u" };
                let dst_ty = match dst_size {
                    // Destination byte counts 4, 8, and 16 map to IEEE precision names.
                    4 => "f32",
                    8 => "f64",
                    16 => "f128",
                    _ => "f?",
                };
                // Multiply bytes by eight because Rust type names state a width in bits.
                write!(f, "{src_ty}{}to{dst_ty} {src:?}", src_size * 8)
            }

            Self::Imm { imm } => write!(f, "imm({imm:?})"),
            Self::Reg { reg } => write!(f, "reg({reg:?})"),
            Self::TmpReg { reg } => write!(f, "tmpreg {reg:?}"),

            Self::Syscall {} => write!(f, "syscall"),
            Self::Sysbreak {} => write!(f, "sysbreak"),

            Self::Lr { dst, src, size } => {
                write!(f, "lr.{size} {dst:?}, ({src:?})")
            }
            Self::Sc {
                dst,
                src,
                addr,
                size,
            } => {
                write!(f, "sc.{size} {dst:?}, {src:?}, ({addr:?})")
            }
            Self::Amo {
                op,
                dst,
                src,
                addr,
                size,
            } => {
                write!(f, "amo{op:?}.{size} {dst:?}, {src:?}, ({addr:?})")
            }

            Self::Fence { .. } => write!(f, "fence"),
        }
    }
}

/// Owns one lifted region so its value handles and address maps stay valid together.
pub struct Nnil {
    /// Base address of the lifted image
    /// This value lets tools relate NNIL output to the source image.
    /// It does not change while the lifter advances `pc`.
    base: u64,

    /// Current address of the lifter
    /// This value avoids a second address counter in each architecture lifter.
    /// It always points at the guest instruction that the lifter will decode next.
    pc: u64,

    /// List of all lifted instructions
    /// Append-only storage keeps every `Insn` identifier valid.
    /// The vector position is the operation result number used by later operands.
    insns: Vec<NnilInstruction>,

    /// Mapping of jump targets to stable label ids
    /// A sorted map makes generated output reproducible.
    /// It also makes repeated requests for one guest address return one label.
    labels_by_addr: BTreeMap<Address, Label>,

    /// Reverse lookup for branch target labels
    /// A vector makes label resolution a constant-time operation for the emitter.
    /// The label number is the index into this vector.
    label_addrs: Vec<Address>,

    /// Mapping of address to corresponding NNIL instruction
    /// The emitter needs this boundary map to recover guest instructions and basic blocks.
    /// One guest instruction can map to several NNIL operations, so only the first index is stored.
    mapping: BTreeMap<Address, Insn>,
}

impl std::fmt::Debug for Nnil {
    // Group NNIL operations under their source guest addresses for manual decoder checks.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // Eight hexadecimal digits keep common 32-bit guest addresses vertically aligned.
        writeln!(f, "Base: 0x{:08x}", self.base)?;
        writeln!(f, "PC: 0x{:08x}", self.pc)?;
        writeln!(f, "\nInstructions:")?;

        // An empty mapping has no first or last key. Return before later unwrap operations.
        if self.mapping.is_empty() {
            return Ok(());
        }

        // Each adjacent pair gives the start index of one guest instruction and the start index
        // of the next. Their difference is the NNIL range for the first guest instruction.
        for (addr, i1, i2) in self
            .mapping
            .iter()
            .map_windows(|&[(&Address(addr1), &Insn(insn1)), (_, &Insn(insn2))]| {
                (addr1, insn1, insn2)
            })
            // Collect copied boundaries before formatting so the loop no longer holds the map iterator.
            .collect::<Vec<_>>()
        {
            if self.labels_by_addr.contains_key(&Address(addr)) {
                // `:03` zero-pads a small decimal guest address to a minimum width of three.
                writeln!(f, "\nLabel_{addr:03}:").unwrap();
            }
            writeln!(f, "Address: {addr:08x}").unwrap();
            for x in i1..i2 {
                // Width eight aligns NNIL instruction indices for easier diagnostic scanning.
                writeln!(f, "{:8}: {:?}", x, self.insns[x as usize]).unwrap();
            }
        }

        // No adjacent pair contains the final guest instruction. Print its range separately.
        let (&Address(addr), &Insn(insn)) = self.mapping.last_key_value().unwrap();
        if self.labels_by_addr.contains_key(&Address(addr)) {
            writeln!(f, "\nLabel_{addr:03}:").unwrap();
        }
        writeln!(f, "Address: {addr:08x}").unwrap();
        for x in insn..self.insns.len() as u64 {
            // Keep the final NNIL range aligned with the earlier diagnostic rows.
            writeln!(f, "{:8}: {:?}", x, self.insns[x as usize]).unwrap();
        }

        Ok(())
    }
}

impl Default for Nnil {
    // Keep generic Rust construction equal to the explicit address-neutral constructor.
    fn default() -> Self {
        Self::new()
    }
}

impl Nnil {
    /// Creates address-neutral NNIL for callers that lift a complete byte slice.
    pub fn new() -> Self {
        Self {
            // Zero makes addresses equal to byte offsets for raw-slice diagnostics.
            base: 0,
            pc: 0,
            insns: Vec::new(),
            labels_by_addr: BTreeMap::new(),
            label_addrs: Vec::new(),
            mapping: BTreeMap::new(),
        }
    }

    /// Starts at a guest address so that branches and fault reports use process addresses.
    pub fn with_base(address: u64) -> Self {
        Self {
            // Start both values together. `base` stays fixed while `pc` advances.
            base: address,
            pc: address,
            insns: Vec::new(),
            labels_by_addr: BTreeMap::new(),
            label_addrs: Vec::new(),
            mapping: BTreeMap::new(),
        }
    }

    /// Reuses a label for each address so that all incoming branches have one identity.
    pub fn create_label(&mut self, addr: u64) -> Label {
        let addr = Address(addr);
        if let Some(label) = self.labels_by_addr.get(&addr) {
            // Reuse the existing identity so all incoming edges agree on one target.
            *label
        } else {
            // The next reverse-map index is a new stable label number.
            let label = Label(self.label_addrs.len() as u64);
            self.label_addrs.push(addr);
            self.labels_by_addr.insert(addr, label);
            label
        }
    }

    /// Records a guest-instruction boundary before its NNIL operations are appended.
    pub fn new_insn(&mut self) {
        // Store the current vector length before lowering appends the first NNIL operation.
        self.mapping
            .insert(Address(self.pc), Insn(self.insns.len() as u64));
    }

    /// Advances the guest PC separately because one guest instruction can emit many operations.
    pub fn advance_by(&mut self, amount: u64) {
        // The architecture decoder supplies two for compressed RISC-V and four for base RISC-V.
        self.pc += amount;
    }

    /// Returns the first guest address that belongs to this NNIL region.
    pub fn base(&self) -> u64 {
        self.base
    }
    /// Returns the next guest address that the lifter will assign.
    pub fn pc(&self) -> u64 {
        self.pc
    }
    /// Returns the lowest mapped guest address, or `None` for an empty region.
    pub fn entrypoint(&self) -> Option<Address> {
        // BTreeMap order selects the lowest address, which need not be the first one decoded.
        self.mapping.first_key_value().map(|(&addr, _)| addr)
    }
    /// Returns operations in handle order so a backend can resolve operands by index.
    pub fn insns(&self) -> &[NnilInstruction] {
        &self.insns
    }
    /// Returns guest-instruction boundaries for basic-block collection and diagnostics.
    pub fn instruction_starts(&self) -> &BTreeMap<Address, Insn> {
        &self.mapping
    }
    /// Returns the address-to-label map for direct control-flow edges.
    pub fn labels(&self) -> &BTreeMap<Address, Label> {
        &self.labels_by_addr
    }
    /// Finds the stable label for a guest address when one was created.
    pub fn label_for_address(&self, addr: Address) -> Option<Label> {
        self.labels_by_addr.get(&addr).copied()
    }
    /// Resolves a label back to its guest address.
    pub fn label_address(&self, label: Label) -> Option<Address> {
        // Invalid or foreign label numbers return `None` instead of indexing past the vector.
        self.label_addrs.get(label.0 as usize).copied()
    }

    // Each emitted value uses its vector position so later operations can refer to it directly.
    /// Appends a signed immediate bit pattern.
    ///
    /// Signed storage represents negative sign-extended immediates without a separate flag.
    pub fn imm(&mut self, imm: i64) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Imm { imm });
        Insn(ret as u64)
    }
    /// Appends a read of one register in the combined NNIL register namespace.
    ///
    /// RISC-V integer registers use indices 0 through 31. The lifter adds 32 for floating-point
    /// registers so integer and floating-point state cannot have the same NNIL index.
    pub fn reg(&mut self, reg: u64) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Reg { reg });
        Insn(ret as u64)
    }

    /// Appends a read of a translator-private temporary.
    ///
    /// A separate variant prevents a temporary index from aliasing guest architectural state.
    pub fn tmp_reg(&mut self, reg: u64) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::TmpReg { reg });
        Insn(ret as u64)
    }

    // These methods append pure value operations. They do not write guest state by themselves.
    emit_alu!(add, Add);
    emit_alu!(sub, Sub);
    emit_alu!(mul, Mul);
    emit_alu!(mulh, Mulh);
    emit_alu!(div, Div);
    // The `r#` prefix permits the Rust keyword `mod` to be used as a method name.
    emit_alu!(r#mod, Mod);
    emit_alu!(and, And);
    emit_alu!(or, Or);
    emit_alu!(xor, Xor);
    emit_alu!(sll, Sll);
    emit_alu!(srl, Srl);
    emit_alu!(sra, Sra);
    emit_alu!(slt, Slt);

    /// Appends a value move and writes its result through `dst`.
    pub fn mov(&mut self, dst: Insn, src: Insn) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Mov { dst, src });
        Insn(ret as u64)
    }
    /// Appends a guest-state write after a pure NNIL calculation.
    pub fn set(&mut self, dst: Insn, src: Insn) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Set { dst, src });
        Insn(ret as u64)
    }

    /// Appends an indirect transfer and ends linear execution.
    pub fn jr(&mut self, dst: Insn) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Jr { dst });
        Insn(ret as u64)
    }
    /// Appends a transfer to the address value in `dst`.
    pub fn jmp(&mut self, dst: Insn) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Jmp { dst });
        Insn(ret as u64)
    }

    // Branch methods require true and false labels so the backend never guesses fallthrough.
    emit_branch!(beq, Beq);
    emit_branch!(bne, Bne);
    emit_branch!(blt, Blt);
    emit_branch!(bgt, Bgt);

    // Memory methods use byte counts because guest widths need not match Rust host types.
    emit_mem!(load, Load);
    emit_mem!(store, Store);

    // Extension methods make the intended source width explicit at an XLEN boundary.
    emit_ext!(sext, Sext);
    emit_ext!(zext, Zext);
    // Sign markers guide comparisons, division, remainder, and high multiplication.
    emit_sign!(signed, Signed);
    emit_sign!(unsigned, Unsigned);

    /// Appends floating-point division for a value width in bytes.
    pub fn fdiv(&mut self, size: usize, lhs: Insn, rhs: Insn) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Fdiv { lhs, rhs, size });
        Insn(ret as u64)
    }

    // todo
    /// Appends an integer-to-floating-point conversion with explicit source and result widths.
    ///
    /// Explicit widths prevent the backend host type from changing guest conversion behavior.
    pub fn int_to_float(
        &mut self,
        src: Insn,
        src_size: usize,
        signed: bool,
        dst_size: usize,
    ) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::IntToFloat {
            src,
            src_size,
            signed,
            dst_size,
        });

        Insn(ret as u64)
    }

    // todo
    // Both system operations exit generated code so the runtime can provide process services.
    emit_sys!(syscall, Syscall);
    emit_sys!(sysbreak, Sysbreak);

    /// Appends an atomic load-reserved of `size` bytes from address `src`.
    pub fn lr(&mut self, dst: Insn, src: Insn, size: u64) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Lr { dst, src, size });
        Insn(ret as u64)
    }
    /// Appends an atomic store-conditional and its architectural success result.
    pub fn sc(&mut self, dst: Insn, src: Insn, addr: Insn, size: u64) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Sc {
            dst,
            src,
            addr,
            size,
        });
        Insn(ret as u64)
    }
    /// Appends an atomic read-modify-write operation.
    ///
    /// `dst` receives the old memory value. `src` contributes to the new memory value.
    pub fn amo(&mut self, op: AmoOp, dst: Insn, src: Insn, addr: Insn, size: u64) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Amo {
            op,
            dst,
            src,
            addr,
            size,
        });
        Insn(ret as u64)
    }

    /// Appends a memory-order fence with the encoded four-bit mode and access masks.
    pub fn fence(&mut self, mode: u8, pred: u8, succ: u8) -> Insn {
        let ret = self.insns.len();
        self.insns.push(NnilInstruction::Fence { mode, pred, succ });
        Insn(ret as u64)
    }
}