jit/

lib.rs

//! The runtime owns guest process state and calls generated native code through a stable C ABI.
//!
//! The guest is an RV64 Linux process. The host is the machine that runs this crate.
//! The runtime maps the guest ELF file, builds its first user stack, and handles a small
//! set of Linux system calls. Generated code uses raw pointers to enter and leave this
//! runtime. Thus, the data layout in this file is also part of the JIT interface.

mod mmu;
mod remi;

use liil::nnil::{Nnil, NnilInstruction};

use std::collections::{BTreeMap, BTreeSet, VecDeque};
use std::error::Error;
use std::fs::{self, File, OpenOptions};
use std::io::{self, IsTerminal as _, Read as _, Seek as _, SeekFrom, Write as _};
use std::os::unix::fs::{FileExt as _, MetadataExt as _};
use std::panic::{AssertUnwindSafe, catch_unwind, set_hook, take_hook};
use std::path::{Component, Path, PathBuf};
use std::sync::{
    Arc,
    atomic::{AtomicBool, Ordering},
};
use std::time::{Duration, Instant};

pub use mmu::{GuestMemory, GuestMemoryAbi, GuestPageAbi, GuestTranslationAbi, PagePerms};
use mmu::{align_down, align_up};
use remi::compile_jit_multi;
pub use remi::{CompiledJit, compile_jit};

/*

    todo v7
     - performance
     - timen
     - alle nnils impl.: riscv-arch testsuite
        - Z* instructions
     - syscalls ? exit & recovery
     - reset
     - privilged
     - threads?
    - mmu? / memory richtig

*/

// todo - barebones
// These fixed sizes keep the host and generated copies of `GuestState` ABI-compatible.
// Slots 0..31 hold integer registers, slots 32..63 hold floating-point registers,
// and slots 64..95 are spare project capacity.
// The emitter checks each index before it writes generated Rust code.
const GUEST_REG_COUNT: usize = 96;
// NNIL uses numbered temporary values. The fixed ABI array has a project maximum of 256.
// The emitter rejects a temporary index that reaches this limit.
const GUEST_TMP_COUNT: usize = 256;
// A small fixed array keeps debugger data inside the C-compatible control structure.
// The value 64 is a project limit, not a RISC-V or Linux ABI value.
const DEBUG_SLOTS: usize = 64;

// RISC-V register x0 always reads as zero. Generated code must also ignore writes to it.
const INTEGER_ZERO_REG: usize = 0;
// Slots 0 through 31 hold x0 through x31. Thus, slot 32 can hold floating-point f0
// without a second register array.
const FP_REG_BASE: usize = 32;

// This emulator selects 4 KiB guest pages. Linux and RISC-V do not require this one size.
// One project value must be used in masks, mappings, `mmap` offsets, and AT_PAGESZ.
const PAGE_SIZE: usize = 4096;

// The project gives each guest a deterministic 128 KiB stack. This is an emulator
// policy value. It is not a limit from the RISC-V ABI.
const DEFAULT_STACK_SIZE: u64 = 0x20_000;
// Keep the stack at a stable high guest address so low ELF mappings have much free space.
// Page alignment avoids a partial top page. The fixed address makes mappings repeatable.
const DEFAULT_STACK_TOP: u64 = 0x0000_7fff_ffff_0000;
// Leave 256 bytes of mapped headroom below the stack top before startup data is added.
// This project reserve has no documented ABI purpose. It is not an unmapped guard page.
const DEFAULT_STACK_POINTER_OFFSET: u64 = 0x100;
// Load the ELF interpreter at a fixed 1 GiB guest bias for deterministic separation
// from normal low-address executable segments.
const DYNAMIC_LOADER_BIAS: u64 = 0x4000_0000;
// Start the automatic guest `mmap` cursor at 1.25 GiB, above the fixed loader bias.
// Successful mappings move this cursor upward.
const MMAP_BASE: u64 = 0x5000_0000;

// These values are from the architecture-neutral Linux file-control UAPI.
// Source: https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/fcntl.h
// Bits 0 and 1 encode the access mode. The mask 3 selects only these two bits.
const O_ACCMODE: u64 = 3;
// Bit 0 requests write-only access. A clear access field means read-only access.
const O_WRONLY: u64 = 1;
// Bit 1 requests read and write access.
const O_RDWR: u64 = 2;
// Bits 6, 7, 9, 10, and 19 are independent options. Bitwise AND tests one option,
// and bitwise OR can test a group of options without changing the other flag bits.
// O_CREAT creates a missing file. O_EXCL makes creation fail if the file exists.
// O_TRUNC clears an existing file. O_APPEND puts each write at the file end.
// O_CLOEXEC asks a future `exec` operation to close this descriptor.
const O_CREAT: u64 = 0x40;
const O_EXCL: u64 = 0x80;
const O_TRUNC: u64 = 0x200;
const O_APPEND: u64 = 0x400;
const O_CLOEXEC: u64 = 0x80000;

// Commands 1 and 2 read and write the per-descriptor close-on-exec flag.
const F_GETFD: u64 = 1;
const F_SETFD: u64 = 2;
// Only bit 0 has a defined meaning for these commands. Mask all other argument bits.
const FD_CLOEXEC: u64 = 1;

// todo -- wird das überhaupt gebraucht
// siehe https://docs.rs/auxv/latest/auxv/
// Linux puts these type numbers in the auxiliary vector on the first process stack.
// The dynamic loader and C library use the values to find loader information without
// parsing the executable again.
// Source: https://github.com/torvalds/linux/blob/master/include/uapi/linux/auxvec.h
// Consumer reference: https://man7.org/linux/man-pages/man3/getauxval.3.html
// Type 0 ends the vector. Its value field has no meaning.
const AT_NULL: u64 = 0;
// Types 3 through 5 give the address, entry size, and count of program headers.
const AT_PHDR: u64 = 3;
const AT_PHENT: u64 = 4;
const AT_PHNUM: u64 = 5;
// Type 6 tells libc which page size the emulated MMU uses.
const AT_PAGESZ: u64 = 6;
// Type 7 is the load base of the ELF interpreter. It is zero for a static process.
const AT_BASE: u64 = 7;
// Type 8 carries process-entry flags. This runtime supplies zero.
const AT_FLAGS: u64 = 8;
// Type 9 is the executable entry. It is not the interpreter entry.
const AT_ENTRY: u64 = 9;
// Types 11 through 14 supply real and effective user and group IDs.
const AT_UID: u64 = 11;
const AT_EUID: u64 = 12;
const AT_GID: u64 = 13;
const AT_EGID: u64 = 14;
// Type 16 reports the RISC-V ISA letters that this runtime chooses to advertise.
const AT_HWCAP: u64 = 16;
// Type 17 gives the number of `times()` clock ticks in one second.
const AT_CLKTCK: u64 = 17;
// Type 23 tells libc if secure execution rules must apply. Zero means normal execution.
const AT_SECURE: u64 = 23;
// Type 25 points to exactly 16 seed bytes on the initial stack.
const AT_RANDOM: u64 = 25;
// Type 26 is a second architecture capability word. This runtime has no values for it.
const AT_HWCAP2: u64 = 26;
// Type 31 points to the pathname used to execute the file.
// This runtime approximates that pathname with the first argument string.
const AT_EXECFN: u64 = 31;

// Linux assigns one HWCAP bit to each ISA letter at position `letter - 'A'`.
// These shifts set A=0, C=2, D=3, F=5, I=8, and M=12. OR combines the six bits.
// This is a fixed advertised IMAFDC word. It is not derived from decoder coverage;
// atomics and parts of floating-point support are still incomplete.
// Source: https://github.com/torvalds/linux/blob/master/arch/riscv/include/uapi/asm/hwcap.h
const RISCV_HWCAP: u64 = (1 << 0) | (1 << 2) | (1 << 3) | (1 << 5) | (1 << 8) | (1 << 12);

// Linux gives AT_RANDOM a pointer to 16 bytes. Fixed bytes make guest startup and
// snapshots repeatable. They are not suitable for security or cryptography.
// Source: https://github.com/torvalds/linux/blob/master/fs/binfmt_elf.c
const ELF_AUX_RANDOM: [u8; 16] = *b"moin-liebe-leute";

// https://doc.rust-lang.org/rust-by-example/error/multiple_error_types/boxing_errors.html
// ELF, file, memory, and compiler operations return different error types. A boxed
// error lets one public result type carry all of them without a large local error enum.
type JitResult<T> = Result<T, Box<dyn Error>>;
// Generated libraries expose one C-ABI function. It is unsafe because Rust cannot
// prove that the raw pointer is valid or that both libraries use the same layout.
pub(crate) type ExecuteFn = unsafe extern "C" fn(*mut GuestState) -> ExitReason;

// Each auxiliary-vector record contains one 64-bit type and one 64-bit value on RV64.
type AuxEntry = (u64, u64);

#[repr(u8)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Distinguishes fault types so the runtime can report the failed guest operation.
pub enum AccessKind {
    // Values 0 through 3 are enum tags shared with generated code. They are not permission bits.
    // Zero means that no memory fault is pending.
    /// Reports that no memory access fault is pending.
    None = 0,
    // Nonzero values keep read, write, and instruction-fetch failures separate.
    /// Reports a failed guest data read.
    Read = 1,
    /// Reports a failed guest data write.
    Write = 2,
    /// Reports a failed guest instruction fetch.
    Execute = 3,
}

// C ABI kompatibiliät todo muss das?
// ExitReason von gamozo!
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Transfers control from generated code to the runtime without unwinding across the ABI.
pub enum ExitReason {
    // The order is part of the C ABI that generated libraries copy. Do not reorder it
    // unless the generated definition changes at the same time.
    // Implicit discriminants start at zero and increase by one.
    /// Reports that generated code has not selected a stop reason.
    None,
    // The generated block could not find the next guest PC in its dispatch table.
    /// Returns an uncached computed target to the runtime for compilation or dispatch.
    IndirectBranch,
    // These values return detailed MMU failures without a host signal or Rust panic.
    /// Reports that a guest load did not have a readable mapping.
    ReadFault,
    /// Reports that a guest store did not have a writable mapping.
    WriteFault,
    /// Reports that instruction fetch did not have an executable mapping.
    ExecFault,
    // A host call has no runtime implementation, so the caller can decide what to do.
    /// Reports an NNIL host call that the runtime does not implement.
    UnhandledHostCall,
    // GuestExit is separate from Syscall so normal process exit is easy to identify.
    /// Reports normal termination through the guest `exit` system call.
    GuestExit,
    /// Returns a guest environment call to the runtime system-call handler.
    Syscall,
    /// Returns a guest breakpoint instruction to the runtime.
    Sysbreak,
    // These stops support the interactive debugger and bounded execution.
    /// Stops before a translated block at a configured guest address.
    Breakpoint,
    /// Stops after another thread sets the shared pause flag.
    Paused,
    /// Stops after a bounded run uses its translated-block budget.
    BlockLimit,
}

// todo - fuzzer api klären
#[repr(C)]
/// Keeps debugger checks optional so normal generated blocks do not call back into the runtime.
pub struct GuestControl {
    // A raw pointer avoids an `Arc` in the generated ABI. The runtime owns the `Arc`.
    pause: *const AtomicBool,
    // Fixed arrays make the layout stable across the host and generated library.
    breakpoints: [u64; DEBUG_SLOTS],
    // Only this sorted prefix contains active breakpoints.
    breakpoint_count: usize,
    // `u64::MAX` is the no-skip sentinel. A breakpoint at that address conflicts with it.
    skip_breakpoint: u64,
    // Generated blocks reduce this value when bounded execution is active.
    blocks_left: u64,
    // Use one byte as an ABI flag. Zero is false and any nonzero value is true.
    limited: u8,
    // This array is a ring. `trace_pos` can increase after the array becomes full.
    trace: [u64; DEBUG_SLOTS],
    trace_pos: usize,
}

#[repr(C)]
#[derive(Clone, Copy)]
/// Pairs a guest target with native code for indirect dispatch from generated code.
pub struct JitEntryAbi {
    // The vector is sorted by this key so generated code can use binary search.
    /// Gives the guest block-entry address used as the sorted lookup key.
    pub guest_pc: u64,
    // This pointer enters the compiled block that starts at `guest_pc`.
    /// Calls native code that starts at `guest_pc`.
    pub execute: ExecuteFn,
}

#[repr(C)]
#[derive(Clone)]
/// Uses one shared layout because both the runtime and generated libraries access guest state.
pub struct GuestState {
    // Generated code writes the reason before it gives control back to the runtime.
    /// Tells the runtime why generated code returned.
    pub exit_reason: ExitReason,
    // The PC is a guest virtual byte address, not a host function address.
    /// Gives the current guest virtual instruction address.
    pub pc: u64,
    // Registers store raw bits. Slots 0 through 31 are integer x0 through x31.
    // Floating-point register f0 starts at slot 32.
    /// Stores raw integer and floating-point register bits in the shared ABI layout.
    pub regs: [u64; GUEST_REG_COUNT],
    // NNIL temporaries live only for translated calculations but share block exits.
    /// Stores NNIL temporary values that must remain available across generated functions.
    pub tmps: [u64; GUEST_TMP_COUNT],
    // Generated code uses this MMU view because it cannot borrow `GuestMemory`.
    /// Points to the MMU view that generated code can use without Rust containers.
    pub memory: *mut GuestMemoryAbi, // todo siehe txt
    // These fields identify the guest operation that failed. The runtime can then
    // report an emulated fault instead of a host segmentation fault.
    /// Gives the guest address of the last failed memory access.
    pub fault_addr: u64,
    /// Identifies the operation that failed at `fault_addr`.
    pub fault_access: AccessKind,
    // A null pointer selects fast execution without debugger checks.
    /// Points to optional debugger controls, or is null for unrestricted execution.
    pub control: *mut GuestControl,
    // This borrowed sorted array lets compiled blocks call other compiled blocks.
    /// Points to sorted cross-artifact dispatch entries.
    pub jit_entries: *const JitEntryAbi,
    /// Gives the valid length of `jit_entries`.
    pub jit_entry_count: usize,
}

impl Default for GuestState {
    /// Starts with no active guest operation and no borrowed ABI pointers.
    /// The runtime installs each pointer only after it owns the target allocation.
    fn default() -> Self {
        Self {
            exit_reason: ExitReason::None,
            pc: 0,
            regs: [0; GUEST_REG_COUNT],
            tmps: [0; GUEST_TMP_COUNT],
            memory: std::ptr::null_mut(),
            fault_addr: 0,
            fault_access: AccessKind::None,
            control: std::ptr::null_mut(),
            jit_entries: std::ptr::null(),
            jit_entry_count: 0,
        }
    }
}

// todo -- refactor nach remu über cli flags setzen lassen
#[derive(Debug, Clone)]
/// Keeps process and compiler inputs together so snapshots and cache behavior are reproducible.
pub struct RemuConfig {
    // These strings become guest-owned NUL-terminated data on the initial stack.
    /// Supplies guest argument strings for the initial process stack.
    pub argv: Vec<String>,
    /// Supplies guest environment strings for the initial process stack.
    pub envp: Vec<String>,
    // Absolute guest paths resolve below `sysroot`. Syscall policy normally treats this tree
    // as read-only. The openat subset documents one flag-combination limit.
    /// Selects the read-only host root for absolute guest paths.
    pub sysroot: Option<PathBuf>,
    // Relative guest paths resolve below `workdir`. Guest file changes stay here.
    /// Selects the writable host root for relative guest paths.
    pub workdir: Option<PathBuf>,
    // This value goes to rustc as `opt-level`. The runtime accepts only 0, 1, or 2
    // to limit compile time during lazy translation.
    /// Selects Rust compiler optimization level 0, 1, or 2 for generated code.
    pub jit_opt_level: u8,
    // A disk cache can reuse generated source and machine code across runtime instances.
    /// Selects an optional directory for reusable generated artifacts.
    pub jit_cache_dir: Option<PathBuf>,
    // Raw JIT output uses the custom ELF mapper and the Linux x86-64 memory-map ABI.
    /// Requests the Linux x86-64 raw loader instead of a shared library.
    pub raw_jit: bool, // todo - so wie gamozolabs - nur linux64
}

impl Default for RemuConfig {
    /// Selects repeatable compiler and cache settings for callers that need no guest I/O roots.
    fn default() -> Self {
        Self {
            argv: Vec::new(),
            envp: Vec::new(),
            sysroot: None,
            workdir: None,
            jit_opt_level: 2,
            jit_cache_dir: Some(PathBuf::from("jit-tmp/cache")),
            raw_jit: false,
        }
    }
}

// todo - nm, readelf
#[derive(Debug, Clone)]
/// Keeps file and memory sizes separate because ELF load segments can contain zero-filled BSS.
pub struct LoadSegment {
    // ELF virtual addresses are guest addresses. They never point into host memory.
    /// Gives the first guest virtual address of the segment.
    pub vaddr: u64,
    // `mem_size` includes file bytes and the zero-filled tail, such as `.bss`.
    /// Gives the total mapped size, including the zero-filled tail.
    pub mem_size: u64,
    // `file_size` limits the bytes that the loader copies from the ELF file.
    /// Gives the number of initialized bytes copied from the file.
    pub file_size: u64,
    // The MMU enforces the R, W, and X flags after it maps the segment.
    /// Gives the guest access permissions from the ELF program header.
    pub perms: PagePerms,
    // Keep an owned copy because the input byte slice can go out of scope.
    /// Owns the initialized file bytes after the source ELF buffer is gone.
    pub bytes: Vec<u8>,
}

#[derive(Debug, Clone)]
/// Retains symbol metadata for entry selection and debugger address display.
pub struct ProgramSymbol {
    // A copied name makes symbol lookup independent from the ELF string-table lifetime.
    /// Owns the symbol name from its ELF string table.
    pub name: String,
    // This is the guest symbol address for an executable image.
    /// Gives the symbol guest address.
    pub value: u64,
    // A zero size is valid. Some assembler and linker symbols have no object extent.
    /// Gives the symbol extent, or zero when ELF does not supply one.
    pub size: u64,
    // Index zero is ELF `SHN_UNDEF`. Dynamic imports commonly use that index.
    /// Gives the defining ELF section index; zero means undefined.
    pub section_index: u16,
}

impl ProgramSymbol {
    /// Rejects undefined table entries when the debugger resolves an address.
    pub fn is_defined(&self) -> bool {
        self.section_index != 0
    }
}

#[derive(Debug, Clone)]
/// Retains jump-slot locations so dynamic imports can be connected later.
pub struct ImportedSymbol {
    // The name lets a later shim select the host service.
    /// Owns the imported symbol name used to select a future shim.
    pub name: String,
    // A jump-slot relocation writes the resolved function address at this GOT address.
    /// Gives the guest GOT slot that receives the resolved address.
    pub got_addr: u64,
}

#[derive(Debug, Clone)]
/// Stores parsed ELF data in a form that the MMU can map without parsing again.
pub struct ProgramImage {
    // ELF type 2 is an executable. Type 3 is a shared object or a PIE executable.
    /// Gives the ELF object type, such as `ET_EXEC` or `ET_DYN`.
    pub elf_type: u16,
    // Start execution here unless PT_INTERP makes the runtime start an interpreter first.
    /// Gives the main executable entry address before interpreter selection.
    pub entry_pc: u64,
    // Program headers, not sections, define the data that Linux maps into a process.
    /// Owns the loadable segments that define the initial process image.
    pub segments: Vec<LoadSegment>,
    // A tree map gives stable lookup and iteration order for debugger output.
    /// Maps each retained ELF symbol name to its metadata.
    pub symbols: BTreeMap<String, ProgramSymbol>,
    /// Lists RISC-V jump-slot relocations for future import connection.
    pub imports: Vec<ImportedSymbol>,
    // `PT_INTERP` names the guest dynamic loader, such as `/lib/ld-linux-riscv64-lp64d.so.1`.
    /// Names the guest dynamic loader from `PT_INTERP`, when present.
    pub interp: Option<String>,
    // The initial break follows the highest load segment so the heap does not cover ELF data.
    /// Gives the page-aligned initial heap end after all load segments.
    pub brk_base: u64,              // initialer heap start
    // Linux passes these three values in AT_PHDR, AT_PHENT, and AT_PHNUM.
    /// Gives the mapped program-header address used for `AT_PHDR`.
    pub elf_phdr_addr: Option<u64>, // todo
    /// Gives one program-header entry size used for `AT_PHENT`.
    pub elf_phent_size: u16,        // todo
    /// Gives the program-header count used for `AT_PHNUM`.
    pub elf_phnum: u16,             // todo
}

impl ProgramImage {
    /// Builds a synthetic image from caller-supplied segments.
    pub fn from_segments(entry_pc: u64, mut segments: Vec<LoadSegment>) -> Self {
        // Sorted segments make memory mapping and free-range behavior deterministic.
        segments.sort_by_key(|segment| segment.vaddr);

        // todo -- heap
        // Round every segment end up to 4 KiB because `brk` maps and unmaps complete pages.
        // Saturating addition limits the unrounded end. `align_up` still assumes that the
        // rounded result fits in u64.
        let brk_base = segments
            .iter()
            .map(|segment| {
                align_up(
                    segment.vaddr.saturating_add(segment.mem_size),
                    PAGE_SIZE as u64,
                )
            })
            .max()
            .unwrap_or(0);

        Self {
            // Value 2 is ELF `ET_EXEC`. Synthetic images have fixed guest addresses.
            elf_type: 2,
            entry_pc,
            segments,
            symbols: BTreeMap::new(),
            imports: Vec::new(),
            interp: None,
            brk_base,
            elf_phdr_addr: None,
            elf_phent_size: 0,
            elf_phnum: 0,
        }
    }

    // todo !!!
    /// Accepts only RISC-V ELF64 little-endian input because the current process ABI is RV64.
    pub fn from_elf_bytes(bytes: &[u8]) -> JitResult<Self> {
        // The generic ELF ABI assigns machine number 243 to RISC-V.
        // Source: https://gabi.xinuos.com/elf/a-emachine.html
        const EM_RISCV: u16 = 243; // unnötig (?)

        // Program-header types tell a process loader what it must map or inspect.
        // `PT_LOAD` maps bytes. `PT_DYNAMIC` describes dynamic linking. `PT_INTERP`
        // names that linker. `PT_PHDR` gives the in-memory header-table address.
        // Source: https://gabi.xinuos.com/elf/07-pheader.html
        const PT_LOAD: u32 = 1;
        const PT_INTERP: u32 = 3;
        const PT_DYNAMIC: u32 = 2;
        const PT_PHDR: u32 = 6;

        // ELF program-header permissions use bit 0 for execute, bit 1 for write,
        // and bit 2 for read. This differs from Linux `PROT_*`, which uses R=1,
        // W=2, and X=4. Each AND test isolates one permission bit and ignores other flags.
        const PF_X: u32 = 1;
        const PF_W: u32 = 2;
        const PF_R: u32 = 4;

        // These section types are the only ones needed for names and jump-slot imports.
        // `SHT_SYMTAB` is the full link symbol table. `SHT_DYNSYM` is the smaller table
        // used for dynamic linking. `SHT_RELA` stores relocations with explicit addends.
        // Source: https://gabi.xinuos.com/elf/03-sheader.html
        const SHT_RELA: u32 = 4;
        const SHT_SYMTAB: u32 = 2;
        const SHT_DYNSYM: u32 = 11;

        // RISC-V relocation type 5 connects one PLT entry to its GOT function slot.
        // Source: https://riscv-non-isa.github.io/riscv-elf-psabi-doc/#relocations
        const R_RISCV_JUMP_SLOT: u32 = 5;

        //  const ELF_MAGIC: &[u8; 4] = b"\x7fELF";
        // const ELFCLASS64: u8 = 2;
        // const ELFDATA2LSB: u8 = 1;
        /* if bytes.len() < 64 || &bytes[..4] != ELF_MAGIC {
            return Err(io::Error::other("falsch").into());
        }
        if bytes[4] != ELFCLASS64 {
            return Err(io::Error::other("falsch").into());
        }
        if bytes[5] != ELFDATA2LSB {
            return Err(io::Error::other("falsch").into());
        } */

        // Check the magic, class, and byte order before fixed-offset reads interpret the input.
        // This parser does not validate all ELF identity and header-version fields.
        // Bytes 0..4 are 0x7f and `ELF`. Byte 4 is class 2 for ELF64. Byte 5 is data
        // encoding 1 for little endian. All later integer reads depend on these values.
        // Source: https://gabi.xinuos.com/elf/02-eheader.html
        if bytes.get(..6) != Some(b"\x7fELF\x02\x01") {
            return Err(io::Error::other("expected a little-endian ELF64 file").into());
        }

        // The first 16 bytes are `e_ident`. Thus, `e_type` starts at byte 16 and
        // `e_machine` starts at byte 18 in an ELF64 header.
        let elf_type = read_u16(bytes, 16)?;
        let march = read_u16(bytes, 18)?;

        if march != EM_RISCV {
            return Err(io::Error::other(format!("nicht riscv???? -- sondern: {}", march)).into());
        }

        // ELF64 aligns the next 64-bit fields to byte 24. `e_entry` is the guest entry.
        let entry_pc = read_u64(bytes, 24)?;

        // Bytes 32 and 40 hold the program-header and section-header table offsets.
        // Bytes 54 through 60 give table strides and counts. Fixed reads still require
        // program entries of at least 56 bytes and section entries of at least 64 bytes,
        // but this parser does not validate those minima. It also lacks extended counts.
        let phoff_u64 = read_u64(bytes, 32)?;
        let phoff = phoff_u64 as usize;
        let phentsize_u16 = read_u16(bytes, 54)?;
        let phentsize = phentsize_u16 as usize;
        let phnum_u16 = read_u16(bytes, 56)?;
        let phnum = phnum_u16 as usize;

        let shoff = read_u64(bytes, 40)? as usize;
        let shentsize = read_u16(bytes, 58)? as usize;
        let shnum = read_u16(bytes, 60)? as usize;

        let mut segments = Vec::new();
        let mut interp = None;
        let mut elf_phdr_addr = None;

        // Some ELF files have no `PT_PHDR`. Keep a derived address as a fallback for AT_PHDR.
        let mut dephdra = None;

        for idx in 0..phnum {
            // Each index selects one file-defined entry. Checked addition rejects address
            // wrap. Saturating multiplication cannot wrap before the checked addition.
            let header = phoff
                .checked_add(idx.saturating_mul(phentsize))
                .ok_or_else(|| io::Error::other("program header overflow"))?;

            // An ELF64 program header is 56 bytes. The field offsets are 0 for type,
            // 4 for flags, 8 for file offset, 16 for virtual address, 32 for file size,
            // and 40 for memory size. Physical address and alignment are not needed here.
            let p_type = read_u32(bytes, header)?;
            let p_flags = read_u32(bytes, header + 4)?;
            let p_offset_u64 = read_u64(bytes, header + 8)?;
            let p_offset = p_offset_u64 as usize;
            let p_vaddr = read_u64(bytes, header + 16)?;
            let p_filesz = read_u64(bytes, header + 32)?;
            let p_memsz = read_u64(bytes, header + 40)?;

            // dbg!(header);
            // dbg!(p_type);

            // todo --
            match p_type {
                PT_LOAD => {
                    if dephdra.is_none() {
                        let Some(segment_end) = p_offset_u64.checked_add(p_filesz) else {
                            return Err(io::Error::other("overflow").into());
                        };

                        // Derive AT_PHDR when ELF omits PT_PHDR and maps the table start.
                        // This check does not prove that the complete header table is mapped.
                        // Convert a file offset to a guest address with the containing
                        // segment relation `p_vaddr + (e_phoff - p_offset)`.
                        if phoff_u64 >= p_offset_u64 && phoff_u64 < segment_end {
                            let delta = phoff_u64 - p_offset_u64;

                            dephdra = Some(
                                p_vaddr
                                    .checked_add(delta)
                                    .ok_or_else(|| io::Error::other("overflow"))?,
                            );
                        }
                    }

                    if p_filesz > p_memsz {
                        // A load segment can add a zero-filled memory tail, but it cannot
                        // place more file bytes in less memory.
                        return Err(io::Error::other("overflow").into());
                    }

                    let end = p_offset
                        .checked_add(p_filesz as usize)
                        .ok_or_else(|| io::Error::other("overflow"))?;

                    let file_bytes = bytes
                        .get(p_offset..end)
                        .ok_or_else(|| io::Error::other("overflow"))?;

                    // Preserve ELF permissions so guest fetches and data accesses fault correctly.
                    // Bitwise AND asks if one ELF flag is set. Bitwise OR adds the matching
                    // internal permission without removing permissions that were added before it.
                    let mut perms = PagePerms::empty();

                    if (p_flags & PF_R) != 0 {
                        perms |= PagePerms::READ;
                    }
                    if (p_flags & PF_W) != 0 {
                        perms |= PagePerms::WRITE;
                    }
                    if (p_flags & PF_X) != 0 {
                        perms |= PagePerms::EXEC;
                    }

                    segments.push(LoadSegment {
                        vaddr: p_vaddr,
                        mem_size: p_memsz,
                        file_size: p_filesz,
                        perms,
                        bytes: file_bytes.to_vec(),
                    });
                }

                PT_INTERP => {
                    // ELF requires a trailing NUL byte in this file range.
                    let end = p_offset
                        .checked_add(p_filesz as usize)
                        .ok_or_else(|| io::Error::other("interp overflow"))?;

                    let raw = bytes
                        .get(p_offset..end)
                        .ok_or_else(|| io::Error::other("interp overflow"))?;

                    // Use bytes before the first NUL. A missing terminator is not rejected here.
                    let path = raw.split(|byte| *byte == 0).next().unwrap_or_default();
                    interp = Some(String::from_utf8_lossy(path).into_owned());
                }

                // The guest interpreter processes dynamic metadata after it starts.
                // This parser does no separate work for PT_DYNAMIC and relies on overlapping
                // PT_LOAD bytes when the ELF file supplies them.
                PT_DYNAMIC => {}
                PT_PHDR => {
                    // `p_vaddr` is already the in-memory address that AT_PHDR requires.
                    elf_phdr_addr = Some(p_vaddr);
                }

                _ => {
                    // dbg!("?");
                }
            }
        }

        let elf_phdr_addr = elf_phdr_addr
            .or(dephdra)
            .ok_or_else(|| io::Error::other("elf headers nicht da"))?;

        // Section headers are not required for process mapping. They are parsed only to
        // support symbol names, entry selection, debugger output, and import discovery.
        let sections = parse_section_headers(bytes, shoff, shentsize, shnum)?;
        let mut symbols = BTreeMap::<String, ProgramSymbol>::new();
        let mut symbol_sections = BTreeMap::<usize, Vec<ProgramSymbol>>::new();

        for (section_idx, section) in sections.iter().enumerate() {
            if matches!(section.sh_type, SHT_SYMTAB | SHT_DYNSYM) {
                let parsed = parse_symbol_section(bytes, &sections, section)?;

                // passt noch nicht todo
                for symbol in &parsed {
                    if symbol.name.is_empty() {
                        continue;
                    }

                    // Prefer defined, nonzero symbols because debug and entry lookup need addresses.
                    let replace = match symbols.get(&symbol.name) {
                        Some(existing) => {
                            (symbol.is_defined() && !existing.is_defined())
                                || (symbol.is_defined() && existing.value == 0 && symbol.value != 0)
                                || (!existing.is_defined()
                                    && symbol.value != 0
                                    && existing.value == 0)
                        }
                        None => true,
                    };

                    if replace {
                        symbols.insert(symbol.name.clone(), symbol.clone());
                    }
                }

                symbol_sections.insert(section_idx, parsed);
            }
        }

        let mut imports = Vec::new();

        for section in &sections {
            if section.sh_type != SHT_RELA || section.sh_entsize == 0 {
                // A zero entry size cannot be the divisor for a relocation count.
                continue;
            }

            let symbol_table_index = section.sh_link as usize;
            let Some(section_symbols) = symbol_sections.get(&symbol_table_index) else {
                continue;
            };

            // ELF64 Rela records are 24 bytes, but this parser checks only for a nonzero
            // entry size and reads the first 16 bytes. A smaller declared size is not rejected.
            // Integer division also ignores incomplete trailing bytes. These are parser limits.
            let count = (section.sh_size / section.sh_entsize) as usize;
            //let count = 0;

            for idx in 0..count {
                let rela_offset = section
                    .sh_offset
                    .checked_add((idx as u64).saturating_mul(section.sh_entsize))
                    .ok_or_else(|| io::Error::other("overflow"))?
                    as usize;

                // In an ELF64 `Rela` record, `r_offset` starts at byte 0 and `r_info`
                // starts at byte 8. The explicit addend at byte 16 is not needed to find imports.
                let r_offset = read_u64(bytes, rela_offset)?;
                let r_info = read_u64(bytes, rela_offset + 8)?;
                // ELF64 packs the relocation type in the low 32 bits. A cast to `u32`
                // discards the high symbol-index bits and keeps this type field.
                let r_type = r_info as u32;

                // Only jump slots identify external function calls that the runtime can shim.
                if r_type != R_RISCV_JUMP_SLOT {
                    continue;
                }

                // Shift right by 32 to remove the type field and move the symbol-table
                // index into the low bits. This follows the ELF64 `ELF64_R_SYM` rule.
                let symbol_idx = (r_info >> 32) as usize;

                let Some(symbol) = section_symbols.get(symbol_idx) else {
                    return Err(io::Error::other("missing symbol ").into());
                };

                if symbol.name.is_empty() {
                    continue;
                }

                imports.push(ImportedSymbol {
                    name: symbol.name.clone(),
                    got_addr: r_offset,
                });
            }
        }

        // Sort by GOT address for deterministic grouping. `dedup_by` removes only adjacent
        // exact duplicates; different names at one address can keep equal pairs apart.
        imports.sort_by_key(|symbol| symbol.got_addr);
        imports.dedup_by(|lhs, rhs| lhs.got_addr == rhs.got_addr && lhs.name == rhs.name);

        //dbg!(imports);

        Ok(Self {
            elf_type,
            // The first page after the highest memory segment is the initial heap break.
            // Saturating addition limits the unrounded end. `align_up` assumes that its
            // rounded result fits in u64.
            brk_base: segments
                .iter()
                .map(|segment| {
                    align_up(
                        segment.vaddr.saturating_add(segment.mem_size),
                        PAGE_SIZE as u64,
                    )
                })
                .max()
                .unwrap_or(0),
            entry_pc,
            segments,
            symbols,
            imports,
            interp,
            elf_phdr_addr: Some(elf_phdr_addr),
            elf_phent_size: phentsize_u16,
            elf_phnum: phnum_u16,
        })
    }

    // siehe trait
    /// Limits lifting to file-backed executable bytes so data and BSS are not decoded as code.
    pub fn exec_region_containing(&self, pc: u64) -> Option<(u64, &[u8])> {
        self.segments.iter().find_map(|segment| {
            // Checked addition rejects a malformed segment whose file range wraps.
            let end = segment.vaddr.checked_add(segment.file_size)?;

            if segment.perms.contains(PagePerms::EXEC) && pc >= segment.vaddr && pc < end {
                Some((segment.vaddr, segment.bytes.as_slice()))
            } else {
                None
            }
        })
    }

    /// Finds one symbol by its exact ELF name for entry and register setup.
    pub fn find_symbol(&self, name: &str) -> Option<&ProgramSymbol> {
        self.symbols.get(name)
    }

    /// Finds the closest defined symbol at or below a mapped guest address.
    pub fn symbol_at(&self, address: u64) -> Option<&ProgramSymbol> {
        // Reject unmapped addresses before selecting the nearest preceding symbol.
        if !self.segments.iter().any(|segment| {
            address >= segment.vaddr && address < segment.vaddr.saturating_add(segment.mem_size)
        }) {
            return None;
        }
        // A symbol size can be zero or missing. Use the nearest preceding value so the
        // debugger can still label addresses inside assembler and linker symbols.
        self.symbols
            .values()
            .filter(|symbol| symbol.is_defined() && symbol.value <= address)
            .max_by_key(|symbol| symbol.value)
    }

    /// Borrows sorted jump-slot imports without exposing the owned vector for changes.
    pub fn imports(&self) -> &[ImportedSymbol] {
        &self.imports
    }
}

struct GuestFile {
    // The host file supplies storage, but the descriptor number and flags belong to the guest.
    file: File,
    // Keep `FD_CLOEXEC` outside the host file because only a guest `exec` would use it.
    fd_flags: u64,
}

// todo - fuzz api später - erstmal provisorisch
struct SnapshotFile {
    // A cloned handle keeps the open file alive when the active guest closes its descriptor.
    file: File,
    // File data is external to guest memory, so save the stream position explicitly.
    offset: u64,
    fd_flags: u64,
}

/// Saves mutable process data while leaving compiled code available for reuse after restore.
pub struct RuntimeSnapshot {
    // The baseline includes mappings, bytes, permissions, stack bounds, and heap state.
    memory: GuestMemory,
    // Raw ABI pointers are cleared before this value is stored.
    state: GuestState,
    // Guest descriptor numbers must remain stable after restore.
    files: BTreeMap<i32, SnapshotFile>,
    next_fd: i32,
    // A restored allocation sequence must start its next search at the same address.
    mmap_base: u64,
}

/// Uses a lifting callback so this crate does not depend on a specific guest architecture crate.
pub struct JitRuntime<L>
where
    L: Fn(&GuestMemory, u64) -> JitResult<Nnil>,
{
    // Keep parsed executable metadata for symbols, startup data, and debugger queries.
    program: ProgramImage,
    // Keep normalized path roots and compiler settings for every later guest operation.
    process: RemuConfig,
    // A box gives the MMU owner a stable address while generated code has raw ABI pointers.
    memory: Box<GuestMemory>,

    // The key is a guest block-entry PC. A tree map keeps keys sorted for ABI dispatch.
    cache: BTreeMap<u64, CompiledJit>,
    // This dense mirror has only the C-compatible data that generated code needs.
    jit_entries: Vec<JitEntryAbi>,

    // Dynamic programs start at the loader entry. `program.entry_pc` stays the main entry.
    initial_pc: u64,
    // Zero means a static process. A dynamic process uses the fixed interpreter bias.
    loader_base: u64,
    // This is the register and stop-state object shared with native blocks.
    state: GuestState,
    // Guest descriptors 0, 1, and 2 map directly to host standard streams. This map starts at 3.
    files: BTreeMap<i32, GuestFile>,
    // Monotonic allocation makes the next descriptor stable after snapshot restore.
    next_fd: i32,
    // This cursor separates automatic mappings from the growing heap.
    mmap_base: u64,
    // Generated source and compiler products go here for inspection and loading.
    jit_output_dir: PathBuf,
    // Keep diagnostic work out of the fast path unless the caller requests it.
    verbose: bool,

    // todo - mehr verbose stats später
    // todo - fuzz logs?
    // These counters measure JIT cost but do not affect guest-visible state.
    compile_count: usize,
    compile_time: Duration,
    execute_time: Duration,
    // Boxes keep raw control pointers stable even when the runtime value moves.
    control: Box<GuestControl>,
    // The `Arc` keeps the atomic flag alive while another thread requests a pause.
    pause: Arc<AtomicBool>,
    // `None` is used only during construction and while `reset` moves the value out.
    initial_snapshot: Option<RuntimeSnapshot>,

    // Eight words hold syscall number, PC, and argument registers a0 through a5.
    last_syscall: Option<[u64; 8]>,
    // The callback changes guest bytes at one PC into one NNIL region.
    lift_region: L,
}

impl<L> JitRuntime<L>
where
    L: Fn(&GuestMemory, u64) -> JitResult<Nnil>,
{
    /// Creates a runtime with default guest-process settings and the local output directory.
    pub fn new(program: ProgramImage, lift_region: L) -> JitResult<Self> {
        // todo - default path
        Self::init_runtime(
            program,
            RemuConfig::default(),
            Path::new("output").to_path_buf(),
            lift_region,
        )
    }

    /// Maps the program and optional interpreter, then builds Linux process startup state.
    pub fn init_runtime(
        program: ProgramImage,
        mut process: RemuConfig,
        jit_output_dir: PathBuf,
        lift_region: L,
    ) -> JitResult<Self> {
        // todo - doku schreiben
        // Reject unsupported settings before files, mappings, or snapshots are created.
        if process.jit_opt_level > 2 {
            return Err(io::Error::other("JIT optimization level ist entweder 0, 1 oder 2").into());
        }
        // `cfg!` is a compile-time host check. Raw artifacts contain x86-64 Linux details,
        // so another host cannot safely load them.
        if process.raw_jit && !cfg!(all(target_os = "linux", target_arch = "x86_64")) {
            return Err(io::Error::other("--raw-jit läuft nur auf Linux x86-64!!").into());
        }
        if let Some(cache_dir) = &process.jit_cache_dir {
            fs::create_dir_all(cache_dir)?;
        }

        // Map the main executable before the interpreter so overlap checks include it.
        let mut memory = Box::new(GuestMemory::from_program(&program)?);

        // Canonical roots make later path checks reliable.
        if let Some(sysroot) = &process.sysroot {
            process.sysroot = Some(fs::canonicalize(sysroot).map_err(|err| {
                io::Error::other(format!(
                    "cannot open sysroot in {}: {err}",
                    sysroot.display()
                ))
            })?);
        }

        // todo - workdir wirklich gebraucht?
        // Use the host current directory only when the caller gives no writable guest root.
        let workdir = process.workdir.clone().unwrap_or(std::env::current_dir()?);
        let workdir = fs::canonicalize(&workdir).map_err(|err| {
            io::Error::other(format!(
                "cannot open workdir in {}: {err}",
                workdir.display()
            ))
        })?;
        if !workdir.is_dir() {
            return Err(io::Error::other("workdir is not a directory").into());
        }
        process.workdir = Some(workdir);

        // dbg!(process);

        let mut loader_base = 0;
        let mut initial_pc = program.entry_pc;

        if let Some(interp) = &program.interp {
            // `PT_INTERP` makes this a dynamic process. The named file is a guest absolute
            // path, so it must come from the configured sysroot and not the host root.
            let sysroot = process.sysroot.as_ref().ok_or_else(|| {
                io::Error::other(format!(
                    "WICHTIG - dynamic ELF requires --sysroot containing {interp}"
                ))
            })?;

            let loader_path = resolve_guest_path(sysroot, interp)?;
            let loader_bytes = fs::read(&loader_path).map_err(|err| {
                io::Error::other(format!(
                    "cannot read guest interpreter {}: {err}",
                    loader_path.display()
                ))
            })?;
            // Apply the same ELF checks to the loader because it will execute as guest code.
            let loader = ProgramImage::from_elf_bytes(&loader_bytes)?;

            // if loader.elf_type != 3 {
            //     return Err(io::Error::other("ist nich ET_DYN").into());
            // }

            // A fixed bias keeps loader addresses stable across repeat fuzzing runs.
            loader_base = DYNAMIC_LOADER_BIAS;

            // Check the loader pages first to avoid a partially mapped interpreter.
            // This arithmetic assumes that each biased segment end and rounded end fit in u64.
            for segment in &loader.segments {
                if segment.mem_size == 0 {
                    continue;
                }

                // Segment addresses and sizes need not be page-aligned. Check every host-style
                // mapping page from the rounded-down start to the rounded-up end.
                let start = align_down(loader_base + segment.vaddr, PAGE_SIZE as u64);
                let end = align_up(
                    loader_base + segment.vaddr + segment.mem_size,
                    PAGE_SIZE as u64,
                );

                if !memory.range_is_free(start, end - start) {
                    return Err(io::Error::other("??").into());
                }
            }

            // Add the bias to every loader segment and to its entry PC. The main executable
            // retains its original addresses for AT_ENTRY and AT_PHDR.
            memory.map_program_at(&loader, loader_base)?;
            initial_pc = loader_base
                .checked_add(loader.entry_pc)
                .ok_or_else(|| io::Error::other("interpreter entry error"))?;
        }

        // `Arc` uses shared ownership. The debugger can retain a clone without borrowing
        // the complete runtime.
        let mut state = GuestState::default();
        let pause = Arc::new(AtomicBool::new(false));

        // dbg!(state);

        // todo -- hier meckert clippy
        // Initialize raw pointers only after their boxed owners have stable addresses.
        state.memory = memory.as_abi_mut();
        // `regs[2]` is RISC-V x2 (`sp`). Use the same 256-byte top reserve as startup setup.
        state.regs[2] = memory.stack_top - DEFAULT_STACK_POINTER_OFFSET;

        let mut runtime = Self {
            program,
            process,
            memory,
            cache: BTreeMap::new(),
            jit_entries: Vec::new(),
            initial_pc,
            loader_base,
            state,
            files: BTreeMap::new(),
            // Linux processes conventionally start with 0, 1, and 2 as standard streams.
            // This runtime keeps those descriptors fixed instead of permitting close and reuse.
            next_fd: 3,
            mmap_base: MMAP_BASE,
            jit_output_dir,
            verbose: false,

            compile_count: 0,
            compile_time: Duration::ZERO,
            execute_time: Duration::ZERO,

            // todo -- anders machen
            control: Box::new(GuestControl {
                pause: Arc::as_ptr(&pause),
                breakpoints: [0; DEBUG_SLOTS],
                breakpoint_count: 0,
                // Use the no-skip sentinel until execution stops at a breakpoint.
                skip_breakpoint: u64::MAX,
                blocks_left: 0,
                // Zero is false in the generated C-compatible ABI.
                limited: 0,
                trace: [0; DEBUG_SLOTS],
                trace_pos: 0,
            }),
            pause,
            initial_snapshot: None,
            last_syscall: None,
            lift_region,
        };

        //runtime.initialize_shim_data()?;
        //runtime.install_shims()?;

        runtime.initialize_process_state()?;

        runtime.state.pc = runtime.initial_pc;
        runtime.state.memory = runtime.memory.as_abi_mut();
        // The initial snapshot restores guest memory and file-handle state during reset.
        // It does not restore external file contents that the guest or another process changes.
        runtime.initial_snapshot = Some(runtime.snapshot()?);

        Ok(runtime)
    }

    /// Returns the number of guest entry PCs that have native code.
    pub fn cache_len(&self) -> usize {
        self.cache.len()
    }

    /// Borrows parsed program data without giving permission to change runtime mappings.
    pub fn program(&self) -> &ProgramImage {
        &self.program
    }

    /// Borrows guest registers and stop data for inspection.
    pub fn state(&self) -> &GuestState {
        &self.state
    }

    /// Gives controlled callers direct access to guest registers and the PC.
    pub fn state_mut(&mut self) -> &mut GuestState {
        &mut self.state
    }

    /// Borrows guest memory for reads and mapping inspection.
    pub fn memory(&self) -> &GuestMemory {
        &self.memory
    }

    /// Borrows guest memory for changes and first refreshes its generated-code view.
    pub fn memory_mut(&mut self) -> &mut GuestMemory {
        // Refresh the ABI first because a previous mapping change can make its pointers stale.
        self.state.memory = self.memory.as_abi_mut();
        &mut self.memory
    }

    /// Changes both reset entry and current execution entry to keep them consistent.
    pub fn set_entry_pc(&mut self, pc: u64) {
        self.initial_pc = pc;
        self.state.pc = pc;
    }

    /// Enables compiler, dispatch, and syscall diagnostics for manual investigation.
    pub fn set_verbose(&mut self, verbose: bool) {
        self.verbose = verbose;
    }

    /// Exposes the normalized roots and JIT options that this runtime uses.
    pub fn process_config(&self) -> &RemuConfig {
        &self.process
    }

    /// Clones the shared pause handle so another thread can stop generated code safely.
    pub fn pause_flag(&self) -> Arc<AtomicBool> {
        Arc::clone(&self.pause)
    }

    /// Adds one guest block-entry address to the generated-code breakpoint table.
    pub fn add_breakpoint(&mut self, address: u64) -> Result<(), &'static str> {
        // The fixed generated-code ABI has DEBUG_SLOTS entries. This method does not report
        // a full table, so callers must not add more than DEBUG_SLOTS different addresses.
        let mut values = self.control.breakpoints[..self.control.breakpoint_count].to_vec();

        if values.contains(&address) {
            return Ok(());
        }

        // Generated code uses binary search, so the shared breakpoint array must stay sorted.
        values.push(address);
        values.sort_unstable();

        self.control.breakpoint_count = values.len();
        self.control.breakpoints[..values.len()].copy_from_slice(&values);
        Ok(())
    }

    /// Removes all copies of an address and keeps the active prefix compact.
    pub fn remove_breakpoint(&mut self, address: u64) {
        let mut values = self.control.breakpoints[..self.control.breakpoint_count].to_vec();
        values.retain(|value| *value != address);
        self.control.breakpoint_count = values.len();
        self.control.breakpoints[..values.len()].copy_from_slice(&values);
    }

    /// Hides all saved array values by setting the active count to zero.
    pub fn clear_breakpoints(&mut self) {
        self.control.breakpoint_count = 0;
    }

    /// Returns only the active sorted prefix, not unused fixed-array slots.
    pub fn breakpoints(&self) -> &[u64] {
        &self.control.breakpoints[..self.control.breakpoint_count]
    }

    /// Returns the retained block-entry trace in execution order for debugger output.
    pub fn trace(&self) -> Vec<u64> {
        // Reorder the ring buffer so callers always receive entries from oldest to newest.
        // `min(DEBUG_SLOTS)` limits output to the array capacity. Subtraction finds the oldest
        // retained sequence number. Modulo DEBUG_SLOTS maps each sequence number to its slot.
        let count = self.control.trace_pos.min(DEBUG_SLOTS);
        let start = self.control.trace_pos.saturating_sub(count);
        (start..self.control.trace_pos)
            .map(|index| self.control.trace[index % DEBUG_SLOTS])
            .collect()
    }

    /// Returns the last syscall register record for debugger and fuzzer diagnostics.
    pub fn last_syscall(&self) -> Option<[u64; 8]> {
        self.last_syscall
    }

    /// Runs the architecture callback without compiling or changing the JIT cache.
    pub fn lift_at(&self, pc: u64) -> JitResult<Nnil> {
        (self.lift_region)(&self.memory, pc)
    }

    /// Captures guest-visible mutable state so one runtime can replay from this point.
    pub fn snapshot(&mut self) -> JitResult<RuntimeSnapshot> {
        let mut files = BTreeMap::new();
        for (&fd, file) in &mut self.files {
            // `try_clone` keeps the same underlying open file available in the snapshot.
            // Save the current offset because the guest can change it with read or seek.
            files.insert(
                fd,
                SnapshotFile {
                    file: file.file.try_clone()?,
                    offset: file.file.stream_position()?,
                    fd_flags: file.fd_flags,
                },
            );
        }

        // Raw ABI pointers belong to this runtime and cannot be copied into a saved snapshot.
        let mut state = self.state.clone();

        state.memory = std::ptr::null_mut();
        state.control = std::ptr::null_mut();
        state.jit_entries = std::ptr::null();
        state.jit_entry_count = 0;

        // Start dirty tracking after the full baseline copy for fast later restores.
        let memory = (*self.memory).clone();
        self.memory.clear_dirty();

        // dbg!(state);

        Ok(RuntimeSnapshot {
            memory,
            state,
            files,
            next_fd: self.next_fd,
            mmap_base: self.mmap_base,
        })
    }

    // todo - optimize
    // todo - dirty bit so wie gamozo
    /// Restores process data but keeps compiled native blocks for fast replay.
    pub fn restore(&mut self, snapshot: &RuntimeSnapshot) -> JitResult<()> {
        let mut files = BTreeMap::new();

        // Clone file descriptions and restore offsets so guest I/O resumes at the same position.
        for (&fd, saved) in &snapshot.files {
            let mut file = saved.file.try_clone()?;
            file.seek(SeekFrom::Start(saved.offset))?;
            files.insert(
                fd,
                GuestFile {
                    file,
                    fd_flags: saved.fd_flags,
                },
            );
        }

        // Use dirty pages when layouts match; otherwise rebuild all memory and ABI pointers.
        if !self.memory.restore_dirty_from(&snapshot.memory) {
            *self.memory = snapshot.memory.clone();
        }

        self.state = snapshot.state.clone();
        self.state.memory = self.memory.as_abi_mut();

        // Do not resume old debugger limits or pointers after a restore.
        self.state.control = std::ptr::null_mut();
        self.sync_jit_entries();
        self.files = files;
        self.next_fd = snapshot.next_fd;

        // self.sync_jit_entries();

        self.mmap_base = snapshot.mmap_base;
        self.last_syscall = None;
        Ok(())
    }

    // todo -- siehe restore 
    /// Restores the snapshot that was made after initial process setup.
    pub fn reset(&mut self) -> JitResult<()> {
        // Rust cannot mutably borrow `self` for `restore` while it also borrows a field
        // from `self`. `take` moves the snapshot out, then the code puts it back.
        let snapshot = self
            .initial_snapshot
            .take()
            .ok_or_else(|| io::Error::other(" snapshot missing"))?;

        // Put the snapshot back even when restore reports an error, so a later reset can retry.
        let result = self.restore(&snapshot);
        self.initial_snapshot = Some(snapshot);
        result
    }

    /*
    // todo - brauchen wir die alle hier wirklich?

            let nnil = (self.lift_region)(&self.program, self.state.pc)?;
        let compiled = compile_jit(&nnil, &self.jit_output_dir)?;

        if self.verbose {
            println!(
                "jit-cache-miss: neu compiled für pc=0x{:x}: {} {}",
                self.state.pc,
                compiled.source_path().display(),
                compiled.library_path().display(),
            );
        }

        self.cache.insert(self.state.pc, compiled);
    } else {
        if self.verbose {
            println!(
                "jit-cache-hit für pc=0x{:x}",
                self.state.pc,
            );
        } */

    /// Compiles a linear walk from the entry to reduce lazy JIT stops during startup.
    pub fn precompile(&mut self) -> JitResult<usize> {
        let start_pc = self.initial_pc;

        let segment_end = self.memory.executable_end(start_pc).ok_or_else(|| {
            io::Error::other(format!("entry pc 0x{start_pc:x} is not executable"))
        })?;

        // https://ratatui.rs/recipes/apps/panic-hooks/

        // Hide expected decoder panics while the best-effort walk probes unknown code.
        // Rust panic hooks are process-global. A concurrent panic can also be hidden, and
        // restoring this saved hook can replace a hook that another thread installed.
        let old_panic_hook = take_hook();
        set_hook(Box::new(|_| {}));

        let mut pc = start_pc;
        let mut regions = Vec::new();

        // Walk linearly to get broad startup coverage without requiring a complete control-flow graph.
        while pc < segment_end {
            // The decoder can panic on unsupported bytes. Catch that panic because this
            // optional walk must not terminate the emulator. The callback only borrows memory.
            let attempt = catch_unwind(AssertUnwindSafe(|| (self.lift_region)(&self.memory, pc)));

            match attempt {
                Ok(Ok(nnil)) => {
                    let next_pc = nnil.pc();

                    // dbg!(nnil);

                    // Every lifted region must advance. This check prevents an infinite walk.
                    if next_pc <= pc {
                        if self.verbose {
                            println!(
                                "aot-stop: entry walk kein progress bei pc=0x{:x} next=0x{:x}",
                                pc, next_pc
                            );
                        }
                        break;
                    }

                    regions.push(nnil);

                    if next_pc >= segment_end {
                        break;
                    }

                    pc = next_pc;
                }

                Ok(Err(err)) => {
                    if self.verbose {
                        println!("aot-skip: entry walk stopped at pc=0x{:x}: {}", pc, err);
                    }
                    break;
                }

                Err(_) => {
                    if self.verbose {
                        println!("aot-skip: entry walk panic pc=0x{:x}", pc);
                    }
                    break;
                }
            }
        }

        // Restore the process-wide hook so later real panics remain visible.
        set_hook(old_panic_hook);

        if regions.is_empty() {
            return Ok(0);
        }

        // One bundle reduces rustc start cost for all regions found by the walk.
        let compiled_regions = match compile_jit_multi(
            &regions,
            &self.jit_output_dir,
            "generated-aot",
            self.process.jit_opt_level,
            self.process.jit_cache_dir.as_deref(),
            self.process.raw_jit,
        ) {

            Ok(compiled_regions) => compiled_regions,
            Err(err) => {
                if self.verbose {
                    println!("aot-bundle-stop: failed to compile start batch: {}", err);
                }
                return Ok(0);
            }
        };

        // dbg!(compiled_regions);

        if self.verbose
            && let Some((_, first)) = compiled_regions.first()
        {
            println!(
                "aot-bundle: compiled {} regions into {} {}",
                compiled_regions.len(),
                first.source_path().display(),
                first.library_path().display(),
            );
        }

        let compiled_count = compiled_regions.len();

        // Each returned handle shares the loaded bundle but has its own guest entry function.
        for (entry_pc, compiled) in compiled_regions {
            self.cache.insert(entry_pc, compiled);
        }
        self.sync_jit_entries();

        Ok(compiled_count)
    }

    // todo -- schnitstelle nach "außen"
    // todo -- hashing
    // todo -- resetting
    /// Runs until the guest exits, faults, makes an unsupported call, or requests a stop.
    pub fn run(&mut self) -> JitResult<ExitReason> {
        // A null control pointer removes debugger checks from an unrestricted run.
        self.state.control = std::ptr::null_mut();
        self.run_inner()
    }

    /// Runs at most `limit` translated blocks so a debugger can step or stay responsive.
    pub fn run_for_blocks(&mut self, limit: u64) -> JitResult<ExitReason> {
        // One block is one translated basic block, not one RISC-V instruction.
        self.control.blocks_left = limit;

        // One is true in this byte-sized ABI flag, so generated blocks use the limit.
        self.control.limited = 1;

        // Skip the current breakpoint once so continue and step can make progress.
        self.control.skip_breakpoint = if self.state.exit_reason == ExitReason::Breakpoint {
            self.state.pc
        } else {
            u64::MAX
        };

        self.state.control = &mut *self.control;
        let result = self.run_inner();

        // dbg!(self.state);

        self.state.control = std::ptr::null_mut();
        self.control.limited = 0;
        // The pause flag is only a stop request. It does not protect other memory, so relaxed
        // atomic ordering is sufficient and avoids an unnecessary synchronization barrier.
        self.pause.store(false, Ordering::Relaxed);
        result
    }

    fn run_inner(&mut self) -> JitResult<ExitReason> {
        // PC zero is the runtime's not-started sentinel. Replace it with the selected entry.
        // This convention prevents this path from starting or resuming a real block at address zero.
        if self.state.pc == 0 {
            self.state.pc = self.initial_pc;
        }

        // Each native exit returns here for lazy compilation, syscalls, or user control.
        loop {
            self.state.memory = self.memory.as_abi_mut();
            self.state.exit_reason = ExitReason::None;

            // Remove details from the previous exit. A caller must not mistake an old
            // fault address for the cause of a later syscall or debugger stop.
            self.state.fault_addr = 0;
            self.state.fault_access = AccessKind::None;

            if self.verbose {
                println!("neuer pc=0x{:x}", self.state.pc)
            }

            // todo - fault memory läuft noch nicht ganz
            if !self.memory.can_execute(self.state.pc) {
                self.state.exit_reason = ExitReason::ExecFault;
                self.state.fault_addr = self.state.pc;
                self.state.fault_access = AccessKind::Execute;


                return Ok(self.finished(ExitReason::ExecFault));
            }

            // Compile only on first entry so unused guest regions do not pay JIT cost.
            if !self.cache.contains_key(&self.state.pc) {
                let _ = self.compile_region(self.state.pc)?;
            } else if self.verbose {
                println!("jit-cache-hit für pc=0x{:x}", self.state.pc);
            }

            // todo -- raw_jit siehe oben
            let compiled = self
                .cache
                .get(&self.state.pc)
                .ok_or_else(|| io::Error::other("cache fehler"))?;

            // Calling native code is unsafe because the library receives a raw pointer.
            // `CompiledJit` keeps the library loaded for the full call.
            let exit_reason = if self.verbose {
                let started = Instant::now();
                let reason = unsafe { compiled.run(&mut self.state) };
                self.execute_time += started.elapsed();
                reason
            } else {
                unsafe { compiled.run(&mut self.state) }
            };

            // Internal dispatch exits resume automatically. Caller-visible stops return to the caller.
            match exit_reason {
                ExitReason::IndirectBranch => continue,
                ExitReason::Syscall => {
                    if self.verbose {
                        self.log_syscall();
                    }
                    if self.handle_syscall() {
                        continue;
                    }
                    if self.state.exit_reason == ExitReason::GuestExit {
                        return Ok(self.finished(ExitReason::GuestExit));
                    }
                    return Ok(self.finished(ExitReason::Syscall));
                }
                other => return Ok(self.finished(other)),
            }
        }
    }

    // todo - schöne logs für benchmarks
    fn finished(&self, reason: ExitReason) -> ExitReason {
        if self.verbose {
            println!(
                "jit stats: {} rustc calls, {:.2?} compiling, {:.2?} executing",
                self.compile_count, self.compile_time, self.execute_time
            );
        }
        reason
    }

    // todo -- refactor vereinfachen
    // Return `(compiled, next_pc)` so callers can distinguish a cache hit and continue a walk.
    fn compile_region(&mut self, pc: u64) -> JitResult<(bool, u64)> {
        if self.cache.contains_key(&pc) {
            /*  if self.verbose {
                println!(
                    "jit-cache-hit: für pc=0x{:x}",
                    pc,
                );
            } */
            return Ok((false, pc));
        }

        // A bounded batch improves cross-region branches without making one source file unlimited.
        // The limit of 128 is a project tradeoff. It gives rustc more cross-block context
        // and caps region count and source size for one cache miss. It cannot bound rustc time.
        let regions = self.collect_lazy_batch(pc, 128)?;
        // Collection reports an error if it cannot lift the required first region.
        // Thus, index zero is the requested block and is safe to use as the fallback.
        let next_pc = regions[0].pc();

        // Use the simpler single-entry artifact path when no useful neighbor was found.
        if regions.len() == 1 {
            let started = Instant::now();

            let compiled = compile_jit(
                &regions[0],
                &self.jit_output_dir,
                self.process.jit_opt_level,
                self.process.jit_cache_dir.as_deref(),
                self.process.raw_jit,
            )?;

            if compiled.compiled_now() {
                self.compile_count += 1;
                self.compile_time += started.elapsed();
            }

            if self.verbose {
                println!(
                    "jit-cache-{} für pc=0x{:x}: {} {}",
                    if compiled.compiled_now() {
                        "miss: compiled"
                    } else {
                        "disk-hit!"
                    },
                    pc,
                    compiled.source_path().display(),
                    compiled.library_path().display(),
                );
            }

            self.cache.insert(pc, compiled);
            self.sync_jit_entries();

            return Ok((true, next_pc));
        }

        let started = Instant::now();

        // The result keeps compiled handles with one shared-artifact cache flag because
        // statistics and diagnostics need both parts.
        let (compiled_regions, compiled_now) = match compile_jit_multi(
            &regions,
            &self.jit_output_dir,
            "generated-batch",
            self.process.jit_opt_level,
            self.process.jit_cache_dir.as_deref(),
            self.process.raw_jit,
        ) {
            Ok(compiled_regions) => {
                // All entries come from one artifact. Its first handle therefore reports
                // whether rustc built that common artifact now.
                let compiled_now = compiled_regions
                    .first()
                    .is_some_and(|(_, compiled)| compiled.compiled_now());

                if compiled_now {
                    self.compile_count += 1;
                    self.compile_time += started.elapsed();
                }
                (compiled_regions, compiled_now)
            }

            Err(err) => {
                // Keep execution available when one neighbor makes the batch invalid.
                self.compile_count += 1;
                self.compile_time += started.elapsed();
                if self.verbose {
                    println!(
                        "jit-batch-stop: fallback to single region bei pc=0x{:x}: {}",
                        pc, err
                    );
                }

                let started = Instant::now();
                
                /*
                 * self.sync_jit_entries();
                 */

                let compiled = compile_jit(
                    &regions[0],
                    &self.jit_output_dir,
                    self.process.jit_opt_level,
                    self.process.jit_cache_dir.as_deref(),
                    self.process.raw_jit,
                )?;

                if compiled.compiled_now() {
                    self.compile_count += 1;
                    self.compile_time += started.elapsed();
                }

                if self.verbose {
                    println!(
                        "jit-cache-{} für pc=0x{:x}: {} {}",
                        if compiled.compiled_now() {
                            "miss: compiled"
                        } else {
                            "disk-hit !"
                        },
                        pc,
                        compiled.source_path().display(),
                        compiled.library_path().display(),
                    );
                }

                // dbg!(self.cache);

                self.cache.insert(pc, compiled);
                self.sync_jit_entries();
                return Ok((true, next_pc));
            }
        };

        // dbg!(compiled_regions);

        if self.verbose
            && let Some((_, first)) = compiled_regions.first()
        {
            println!(
                "jit-cache-batch-{}: {} regions ab pc=0x{:x}: {} {}",
                if compiled_now { "compiled" } else { "disk-hit !" },
                compiled_regions.len(),
                pc,
                first.source_path().display(),
                first.library_path().display(),
            );
        }

        for (entry_pc, compiled) in compiled_regions {
            self.cache.insert(entry_pc, compiled);
        }
        self.sync_jit_entries();

        Ok((true, next_pc))
    }

    // todo -- code dupliction
    // Collect direct control-flow neighbors so one rustc call can link their tail calls.
    fn collect_lazy_batch(&self, start_pc: u64, max_regions: usize) -> JitResult<Vec<Nnil>> {
        self.memory.executable_end(start_pc).ok_or_else(|| {
            io::Error::other(format!("entry pc 0x{start_pc:x} is not executable! ende"))
        })?;

        // Breadth-first order favors nearby direct successors and gives stable bundle content.
        let mut queue = VecDeque::from([start_pc]);
        let mut seen = BTreeSet::new();
        let mut regions = Vec::new();

        // Stop when the queue is empty or the project batch limit is reached. Thus, one
        // cache miss cannot grow the compilation bundle without a limit.
        while let Some(pc) = queue.pop_front()
            && regions.len() < max_regions
        {
            // `insert` returns false for a duplicate. Short-circuit OR then skips that PC
            // without a second tree lookup. Non-executable targets are also unsafe to lift.
            if !seen.insert(pc) || !self.memory.can_execute(pc) {
                continue;
            }
            
            // todo -- refactor vereinfachen

            // A bad optional successor must not prevent compilation of the required start region.
            // The hook is process-global. Concurrent panics can be hidden, and restoring the
            // saved value can replace a hook that another thread installed.
            let old_panic_hook = take_hook();
            set_hook(Box::new(|_| {}));
            let lifted = catch_unwind(AssertUnwindSafe(|| (self.lift_region)(&self.memory, pc)));
            set_hook(old_panic_hook);

            // Failure at an optional neighbor is harmless. Failure at the requested start
            // address must be reported because execution cannot make progress without it.
            let nnil = match lifted {
                Ok(Ok(nnil)) => nnil,
                Ok(Err(_)) if pc != start_pc || !regions.is_empty() => continue,
                Ok(Err(err)) => return Err(err),
                Err(payload) => {
                    if pc != start_pc || !regions.is_empty() {
                        continue;
                    }

                    // Rust panic payloads are usually `&str` or `String`. Downcast without
                    // taking ownership so the diagnostic can cover both common forms.
                    let message = payload
                        .downcast_ref::<&str>()
                        .copied()
                        .or_else(|| payload.downcast_ref::<String>().map(String::as_str))
                        .unwrap_or("unknown panic");

                    // Show four executable bytes for context. This can include a second compressed
                    // instruction. If four bytes are unavailable, show the first 16-bit parcel.
                    let raw = self
                        .memory
                        .fetch_u32(pc)
                        .map(|value| format!("0x{value:08x}"))
                        .or_else(|| {
                            self.memory
                                .fetch_u16(pc)
                                .map(|value| format!("0x{value:04x}"))
                        })
                        .unwrap_or_else(|| "unreadable".to_string());

                    return Err(io::Error::other(format!(
                        "lifter panic bei guest pc 0x{pc:x}, instruction {raw}: {message}"
                    ))
                    .into());
                }
            };

            let next_pc = nnil.pc();

            if next_pc <= pc {
                return Err(io::Error::other(format!(
                    "compiling pc 0x{pc:x} kein progress (next pc 0x{next_pc:x})"
                ))
                .into());
            }

            // Queue only static targets because indirect targets are unknown until runtime.
            for successor in direct_successors(&nnil) {
                if !seen.contains(&successor) {
                    queue.push_back(successor);
                }
            }

            if !self.cache.contains_key(&pc) {
                regions.push(nnil);
            }
        }

        Ok(regions)
    }

    fn log_syscall(&self) {
        // The RV64 Linux ABI puts the syscall number in x17 (`a7`). Arguments use
        // x10 through x15 (`a0` through `a5`), and x2 is the stack pointer.
        // Source: https://man7.org/linux/man-pages/man2/syscall.2.html
        let nr = self.state.regs[17];

        println!(
            "achtung syscall {} - pc=0x{:x} a0=0x{:x} a1=0x{:x} a2=0x{:x} a3=0x{:x} a4=0x{:x} a5=0x{:x} sp=0x{:x}",
            nr,
            self.state.pc,
            self.state.regs[10],
            self.state.regs[11],
            self.state.regs[12],
            self.state.regs[13],
            self.state.regs[14],
            self.state.regs[15],
            self.state.regs[2],
        );
    }

    // todo - fuzz api
    // todo -- refactor, eigene datei
    fn handle_syscall(&mut self) -> bool {
        // Keep the entry registers before a handler changes a0 into the return value.
        let nr = self.state.regs[17];
        self.last_syscall = Some([
            nr,
            self.state.pc,
            self.state.regs[10],
            self.state.regs[11],
            self.state.regs[12],
            self.state.regs[13],
            self.state.regs[14],
            self.state.regs[15],
        ]);

        // dbg!(self.state);

        // Handlers use positive Linux errno numbers internally. The values used below are:
        // 2=ENOENT, 5=EIO, 9=EBADF, 12=ENOMEM, 13=EACCES, 14=EFAULT,
        // 17=EEXIST, 22=EINVAL, 25=ENOTTY, 30=EROFS, and 38=ENOSYS.
        // Sources:
        // https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno-base.h
        // https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno.h

        // https://gpages.juszkiewicz.com.pl/syscalls-table/syscalls.html
        // Emulate only the process services needed by current user-mode guests.
        // RV64 uses the architecture-neutral Linux syscall table for these numbers.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/unistd.h
        // 17=getcwd, 25=fcntl, 29=ioctl, 35=unlinkat, 48=faccessat,
        // 56=openat, 57=close, 62=lseek, 63=read, 64=write, 66=writev,
        // 67=pread64, 78=readlinkat, 79=newfstatat, and 80=fstat.
        let result = match nr {
            17 => self.sys_getcwd(),
            25 => self.sys_fcntl(),
            // No guest ioctl is available. Error 25 is `ENOTTY`, which tells libc that
            // this descriptor does not support the requested device operation.
            29 => Err(25),
            35 => self.sys_unlinkat(),
            // Number 439 is `faccessat2`. Routing it to the old path check ignores its fourth
            // flags argument. This is an ABI limitation of the current subset.
            48 | 439 => self.sys_faccessat(),
            56 => self.sys_openat(),
            57 => self.sys_close(),
            62 => self.sys_lseek(),
            63 => self.sys_read(),
            64 => self.sys_write(),
            66 => self.sys_writev(),
            67 => self.sys_pread64(),
            78 => self.sys_readlinkat(),
            79 => self.sys_newfstatat(),
            80 => self.sys_fstat(),
            // 93 is `exit` and 94 is `exit_group`. This runtime has one guest thread,
            // so both calls stop the complete guest process.
            93 | 94 => {
                self.state.exit_reason = ExitReason::GuestExit;
                return false;
            }
            // 96 is `set_tid_address`. Return virtual thread ID 1 because there is one thread.
            // The runtime does not record the x10 clear-child-TID pointer or clear it at exit.
            96 => Ok(1),
            // Calls 99 and 233 are set_robust_list and madvise; this model ignores both.
            // Call 259 is riscv_flush_icache. Returning success without invalidating translated
            // blocks is a limitation and can leave stale code after a guest modifies instructions.
            99 | 233 | 259 => Ok(0),
            // 113=clock_gettime, 123=sched_getaffinity, 160=uname, and 163=getrlimit.
            113 => self.sys_clock_gettime(),
            123 => self.sys_sched_getaffinity(),
            160 => self.sys_uname(),
            163 => self.sys_getrlimit(),
            // 172=getpid and 178=gettid. Both identify the only virtual task as 1.
            172 | 178 => Ok(1),
            // 174..177 are getuid, geteuid, getgid, and getegid. A stable unprivileged
            // identity matches the IDs in auxiliary-vector and synthetic stat data.
            174..=177 => Ok(1000),
            // 214=brk, 215=munmap, 222=mmap, and 226=mprotect.
            214 => self.sys_brk(),
            215 => self.sys_munmap(),
            222 => self.sys_mmap(),
            226 => self.sys_mprotect(),
            // 258 is `riscv_hwprobe`. Error 38 is `ENOSYS`, so libc can use an older
            // capability path when detailed CPU data is not available.
            // Source: https://github.com/torvalds/linux/blob/master/arch/riscv/kernel/syscalls/syscall.tbl
            258 => Err(38),
            // 261=prlimit64 and 278=getrandom.
            261 => self.sys_prlimit64(),
            278 => self.sys_getrandom(),
            // 293 is `rseq`. Return `ENOSYS` because this runtime has no guest thread scheduler.
            293 => Err(38),
            // Return control to the caller when host policy does not define this syscall.
            _ => return false,
        };

        // Linux returns success values or negative errno values in x10 (`a0`).
        self.state.regs[10] = result.unwrap_or_else(guest_errno);
        self.state.exit_reason = ExitReason::None;
        true
    }

    fn sys_openat(&mut self) -> Result<u64, i32> {
        // `openat` receives dirfd in x10, path in x11, flags in x12, and mode in x13.
        // This subset uses host creation defaults, so it does not read the mode argument.
        // x10 is signed because Linux uses -100 for `AT_FDCWD`. Casting the saved u64
        // preserves its two's-complement bit pattern as an i64.
        let dirfd = self.state.regs[10] as i64;
        // One 4 KiB page is a project limit for path scanning. It bounds work when a guest
        // gives an address with no NUL terminator.
        let path = self.read_guest_string(self.state.regs[11], 4096)?;
        let flags = self.state.regs[12];

        // Supporting only AT_FDCWD avoids implementing guest directory-FD state and keeps
        // every lookup relative to the configured process roots.
        // Source for -100 (`AT_FDCWD`):
        // https://github.com/torvalds/linux/blob/master/include/uapi/linux/fcntl.h
        if dirfd != -100 {
            // Error 22 is `EINVAL`: this emulator does not accept another dirfd form.
            return Err(22);
        }

        // AND with 3 removes all option bits and keeps the two access-mode bits.
        let access = flags & O_ACCMODE;

        if access > O_RDWR {
            // Access value 3 is reserved, so it is not a valid read or write mode.
            return Err(22);
        }
        // Detect normal write access and the listed file-changing options.
        let writable = access != 0 || flags & (O_CREAT | O_TRUNC | O_APPEND) != 0;
        // This test omits O_EXCL. O_EXCL without O_CREAT can still reach Rust `create_new`
        // below, so this subset does not fully enforce the read-only sysroot for that form.
        // Absolute paths are intended to stay in the read-only sysroot.
        if path.starts_with('/') && writable {
            // Error 30 is `EROFS`. This presents the sysroot as a read-only guest file system.
            return Err(30);
        }

        let path = self.resolve_process_path(&path, flags & O_CREAT != 0)?;
        let mut options = OpenOptions::new();


        // Translate only the supported Linux flags to host `OpenOptions`. Read-only is
        // encoded as zero, so `access != O_WRONLY` enables reads for modes 0 and 2.
        // Unsupported option bits are ignored instead of rejected. This is an ABI limitation.
        options
            .read(access != O_WRONLY)
            .write(access != 0)
            .create(flags & O_CREAT != 0)
            .create_new(flags & O_EXCL != 0)
            .truncate(flags & O_TRUNC != 0)
            .append(flags & O_APPEND != 0);

        let file = options.open(path).map_err(host_errno)?;
        // Allocate monotonically instead of reusing a closed number. This keeps descriptor
        // assignment deterministic across snapshots and avoids a free-list data structure.
        let fd = self.next_fd;
        self.next_fd += 1;

        self.files.insert(
            fd,
            GuestFile {
                file,
                // AND tests only Linux bit 19. Store the guest flag even though this runtime
                // does not currently replace its process image with guest `exec`.
                fd_flags: if flags & O_CLOEXEC != 0 {
                    FD_CLOEXEC
                } else {
                    0
                },
            },
        );

        // dbg!(self.files);

        Ok(fd as u64)
    }

    fn sys_unlinkat(&mut self) -> Result<u64, i32> {
        // `unlinkat` receives dirfd in x10, path in x11, and option flags in x12.
        // Support only `AT_FDCWD` with flags zero. In particular, flag 0x200
        // (`AT_REMOVEDIR`) is not implemented because this function removes files only.
        if self.state.regs[10] as i64 != -100 || self.state.regs[12] != 0 {
            return Err(22);
        }
        let path = self.read_guest_string(self.state.regs[11], 4096)?;
        // Never remove files from the shared sysroot.
        if path.starts_with('/') {
            return Err(30);
        }
        let path = self.resolve_process_path(&path, false)?;
        fs::remove_file(path).map_err(host_errno)?;
        Ok(0)
    }

    fn sys_fcntl(&mut self) -> Result<u64, i32> {
        // `fcntl` receives the descriptor in x10, command in x11, and command value in x12.
        let fd = self.state.regs[10] as i32;
        let command = self.state.regs[11];
        let argument = self.state.regs[12];
        // Error 9 is `EBADF`. Standard streams have no stored guest flag record here.
        let file = self.files.get_mut(&fd).ok_or(9)?;

        match command {
            F_GETFD => Ok(file.fd_flags),
            F_SETFD => {
                // Keep only bit 0 because Linux defines no other descriptor flag here.
                file.fd_flags = argument & FD_CLOEXEC;
                Ok(0)
            }
            _ => Err(22),
        }
    }

    fn sys_close(&mut self) -> Result<u64, i32> {
        // `close` receives its descriptor in x10.
        let fd = self.state.regs[10] as i32;
        // Treat standard streams as always present because the runtime does not own their handles.
        if (0..=2).contains(&fd) || self.files.remove(&fd).is_some() {
            Ok(0)
        } else {
            // Error 9 is `EBADF`: the guest number is not open.
            Err(9)
        }
    }

    fn sys_read(&mut self) -> Result<u64, i32> {
        // `read` receives the descriptor in x10, guest buffer in x11, and byte count in x12.
        let fd = self.state.regs[10] as i32;
        let addr = self.state.regs[11];
        let size = usize::try_from(self.state.regs[12]).map_err(|_| 22)?;
        // Read into host-owned memory first. This prevents the host I/O API from receiving
        // a raw guest pointer and lets the MMU validate the later copy.
        let mut bytes = vec![0; size];

        // let size = 256;

        // Descriptor 0 is the conventional standard input number.
        let count = if fd == 0 {
            io::stdin().read(&mut bytes).map_err(host_errno)?
        } else {
            let file = self.files.get_mut(&fd).ok_or(9)?;
            file.file.read(&mut bytes).map_err(host_errno)?
        };

        // Copy only bytes returned by the host so unread buffer space stays unchanged.
        if !self.memory.store_bytes(addr, &bytes[..count]) {
            // Error 14 is `EFAULT`: the output guest range is not writable.
            return Err(14);
        }
        Ok(count as u64)
    }

    fn sys_write(&mut self) -> Result<u64, i32> {
        // `write` receives the descriptor in x10, guest buffer in x11, and byte count in x12.
        let fd = self.state.regs[10] as i32;
        let size = usize::try_from(self.state.regs[12]).map_err(|_| 22)?;
        // Copy from guest memory before host I/O so invalid guest pages return `EFAULT`
        // instead of causing a host memory fault.
        let bytes = self
            .memory
            .load_bytes(self.state.regs[11], size)
            .ok_or(14)?;

        let count = self.write_fd(fd, &bytes)?;
        Ok(count as u64)
    }

    fn sys_writev(&mut self) -> Result<u64, i32> {
        // `writev` receives the descriptor in x10, iovec address in x11, and count in x12.
        let fd = self.state.regs[10] as i32;
        let iov = self.state.regs[11];
        let count = usize::try_from(self.state.regs[12]).map_err(|_| 22)?;
        // Bound allocation and guest-memory work for invalid vector counts.
        // Linux defines `UIO_MAXIOV` as 1024, so larger arrays are invalid.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/linux/uio.h
        if count > 1024 {
            return Err(22);
        }

        let mut bytes = Vec::new();
        for index in 0..count {
            // RV64 `struct iovec` contains an 8-byte pointer followed by an 8-byte size.
            // Thus, each record is 16 bytes and record `index` starts at `iov + index * 16`.
            let entry = self
                .memory
                .load_bytes(iov + (index * 16) as u64, 16)
                .ok_or(14)?;
            // The first byte ranges have known length because `load_bytes` returned 16 bytes.
            // Convert each field from guest little-endian order to a host integer.
            let addr = u64::from_le_bytes(entry[..8].try_into().unwrap());
            let size = u64::from_le_bytes(entry[8..].try_into().unwrap());
            let size = usize::try_from(size).map_err(|_| 22)?;
            bytes.extend(self.memory.load_bytes(addr, size).ok_or(14)?);
        }

        Ok(self.write_fd(fd, &bytes)? as u64)
    }

    // todo
    fn write_fd(&mut self, fd: i32, bytes: &[u8]) -> Result<usize, i32> {
        // Mark terminal output so emulator diagnostics stay distinct from guest text.
        match fd {
            // Descriptors 1 and 2 conventionally start as standard output and error.
            // This runtime keeps those meanings fixed instead of permitting close and reuse.
            1 => write_marked_output(
                io::stdout().lock(),
                bytes,
                "stdout",
                // ANSI sequence 1;36 selects bright cyan on a compatible terminal.
                "\x1b[1;36m", // juckt
                io::stdout().is_terminal(),
            ),
            2 => write_marked_output(
                io::stderr().lock(),
                bytes,
                "stderr",
                // ANSI sequence 1;31 selects bright red for error output.
                "\x1b[1;31m",
                io::stderr().is_terminal(),
            ),
            _ => self
                .files
                .get_mut(&fd)
                .ok_or(9)?
                .file
                .write(bytes)
                .map_err(host_errno),
        }
    }

    fn sys_pread64(&mut self) -> Result<u64, i32> {
        // `pread64` receives fd, buffer, count, and file offset in x10 through x13.
        let fd = self.state.regs[10] as i32;
        let addr = self.state.regs[11];
        let size = usize::try_from(self.state.regs[12]).map_err(|_| 22)?;
        let offset = self.state.regs[13];
        let file = self.files.get(&fd).ok_or(9)?;

        let mut bytes = vec![0; size];

        // Positional reads must not change the file offset saved in runtime snapshots.
        let count = file.file.read_at(&mut bytes, offset).map_err(host_errno)?;

        if !self.memory.store_bytes(addr, &bytes[..count]) {
            return Err(14);
        }
        Ok(count as u64)
    }

    fn sys_lseek(&mut self) -> Result<u64, i32> {
        // `lseek` receives fd in x10, signed offset in x11, and origin in x12.
        let fd = self.state.regs[10] as i32;
        let offset = self.state.regs[11] as i64;
        let whence = self.state.regs[12];
        let file = self.files.get_mut(&fd).ok_or(9)?;
        // Linux values 0, 1, and 2 are `SEEK_SET`, `SEEK_CUR`, and `SEEK_END`.
        // A start-relative position cannot be negative, but current and end offsets can be.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/linux/fs.h
        let position = match whence {
            0 if offset >= 0 => SeekFrom::Start(offset as u64),
            0 => return Err(22),
            1 => SeekFrom::Current(offset),
            2 => SeekFrom::End(offset),
            _ => return Err(22),
        };

        file.file.seek(position).map_err(host_errno)
    }

    fn sys_faccessat(&self) -> Result<u64, i32> {
        // `faccessat` receives dirfd in x10, path in x11, and access mode in x12.
        // This subset checks path existence below the selected root. It does not evaluate
        // the requested access-mode argument against guest credentials.
        if self.state.regs[10] as i64 != -100 {
            return Err(22);
        }
        let path = self.read_guest_string(self.state.regs[11], 4096)?;
        self.resolve_process_path(&path, false).map(|_| 0)
    }

    fn sys_fstat(&mut self) -> Result<u64, i32> {
        // `fstat` receives the descriptor in x10 and the guest `stat` address in x11.
        let fd = self.state.regs[10] as i32;
        // Standard streams have no owned `File`, so write a synthetic character-device record.
        let metadata = if (0..=2).contains(&fd) {
            None
        } else {
            Some(
                self.files
                    .get(&fd)
                    .ok_or(9)?
                    .file
                    .metadata()
                    .map_err(host_errno)?,
            )
        };
        self.write_guest_stat(self.state.regs[11], metadata.as_ref())
    }

    fn sys_newfstatat(&mut self) -> Result<u64, i32> {
        // `newfstatat` receives dirfd, path, output address, and flags in x10 through x13.
        // Allow only bit 8, Linux `AT_SYMLINK_NOFOLLOW` (0x100). `flags & !0x100`
        // clears that supported bit and detects if any unsupported bit remains.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/linux/fcntl.h
        if self.state.regs[10] as i64 != -100 || self.state.regs[13] & !0x100 != 0 {
            return Err(22);
        }
        let path = self.read_guest_string(self.state.regs[11], 4096)?;
        let path = self.resolve_process_path(&path, false)?;
        // `symlink_metadata` normally describes the link itself, but path resolution above
        // already canonicalizes and follows the final link. NOFOLLOW is not fully implemented.
        let metadata = if self.state.regs[13] & 0x100 != 0 {
            fs::symlink_metadata(path)
        } else {
            fs::metadata(path)
        }
        .map_err(host_errno)?;

        self.write_guest_stat(self.state.regs[12], Some(&metadata))

        // dbg!(self.state);
    }

    fn sys_readlinkat(&mut self) -> Result<u64, i32> {
        // `readlinkat` receives dirfd, path, output address, and size in x10 through x13.
        // This current shortcut ignores dirfd and path. It returns the configured argv[0].
        // let path = self.read_guest_string(self.state.regs[11], 4096)?;

        // if path != "/proc/self/exe" {
        //     return Err(2);
        // }

        let size = usize::try_from(self.state.regs[13]).map_err(|_| 22)?;
        // Report argv[0] so `/proc/self/exe` style guest queries see their guest executable name.
        let bytes = self
            .process
            .argv
            .first()
            .map(String::as_bytes)
            .unwrap_or_default();

        // `readlinkat` does not append a NUL byte. Copy at most the supplied buffer size
        // and return the exact number of bytes that were copied.
        let count = size.min(bytes.len());

        if !self
            .memory
            .store_bytes(self.state.regs[12], &bytes[..count])
        {
            return Err(14);
        }
        Ok(count as u64)
    }

    fn sys_getcwd(&mut self) -> Result<u64, i32> {
        // `getcwd` receives the output address in x10 and buffer size in x11.
        let addr = self.state.regs[10];
        // The virtual process always starts at guest root. Two bytes are needed for `/`
        // and its C-string NUL terminator.
        if self.state.regs[11] < 2 || !self.memory.store_bytes(addr, b"/\0") {
            return Err(14);
        }
        // The raw Linux syscall should return length 2, including NUL. This implementation
        // returns the buffer address and also uses EFAULT for an undersized buffer.
        Ok(addr)
    }

    fn sys_brk(&mut self) -> Result<u64, i32> {
        // `brk` receives the requested first address after the heap in x10.
        let requested = self.state.regs[10];

        if requested == 0 {
            // Linux permits a zero request to query the current program break.
            return Ok(self.memory.brk);
        }

        // Keep the heap below the current automatic mmap cursor. Successful mmap calls can
        // move this boundary upward, so it is not a fixed heap limit.
        if requested >= self.mmap_base {
            // Linux `brk` reports the unchanged break when it cannot grant the request.
            return Ok(self.memory.brk);
        }

        let old = self.memory.brk;

        if requested > old {
            // The break can end within a page. Map only complete new pages between the
            // old and requested page-rounded ends, with normal heap read/write permission.
            let start = align_up(old, PAGE_SIZE as u64);
            let end = align_up(requested, PAGE_SIZE as u64);
            if end > start {
                self.memory
                    .map_zeroed(start, end - start, PagePerms::READ | PagePerms::WRITE)
                    .map_err(|_| 12)?;
            }
        } else {
            // Keep the page that contains the new break. Only pages wholly above it can go.
            let start = align_up(requested, PAGE_SIZE as u64);
            let end = align_up(old, PAGE_SIZE as u64);
            if end > start {
                self.memory.unmap(start, end - start).map_err(|_| 22)?;
                // Removed heap pages can contain code, so their compiled entries are unsafe to keep.
                self.invalidate_cache(start, end - start);
            }
        }

        self.memory.brk = requested;
        Ok(requested)
    }

    fn sys_mmap(&mut self) -> Result<u64, i32> {
        // `mmap` receives address, length, protection, flags, fd, and offset in x10 through x15.
        let hint = self.state.regs[10];
        // Linux mappings cover complete pages, so round a nonzero byte length up to 4 KiB.
        // `align_up` assumes that the rounded guest length fits in u64.
        let size = align_up(self.state.regs[11], PAGE_SIZE as u64);
        let prot = self.state.regs[12];
        let flags = self.state.regs[13];
        // Linux flag 0x10 is `MAP_FIXED`: the address is a requirement, not a hint.
        let fixed = flags & 0x10 != 0;


        // Linux flag 0x20 is `MAP_ANONYMOUS`: no file supplies the initial bytes.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/mman-common.h
        let anonymous = flags & 0x20 != 0;
        // Only MAP_FIXED and MAP_ANONYMOUS affect this implementation. It does not implement
        // or validate MAP_PRIVATE, MAP_SHARED, or other Linux mmap flags.

        // Protection bits 0, 1, and 2 mean read, write, and execute. Decimal 7 is the
        // mask `0b111`. AND with its complement detects all unsupported protection bits.
        if size == 0 || prot & !7 != 0 {
            return Err(22);
        }

        // Honor a free hint, but use the deterministic mmap cursor when it overlaps a mapping.
        let base = if fixed {
            // A fixed mapping must start at a page boundary because it can replace pages.
            if !hint.is_multiple_of(PAGE_SIZE as u64) {
                return Err(22);
            }
            hint
        } else if hint != 0
            && self
                .memory
                .range_is_free(align_down(hint, PAGE_SIZE as u64), size)
        {
            align_down(hint, PAGE_SIZE as u64)
        } else {
            self.memory
                .find_free_range(self.mmap_base, size)
                .ok_or(12)?
        };

        let bytes = if anonymous {
            // An empty source tells the MMU to zero-fill the complete new mapping.
            Vec::new()
        } else {
            let fd = self.state.regs[14] as i32;
            let offset = self.state.regs[15];
            // Linux file mappings require the byte offset to be a multiple of page size.
            if !offset.is_multiple_of(PAGE_SIZE as u64) {
                return Err(22);
            }
            let file = self.files.get(&fd).ok_or(9)?;
            let mut bytes = vec![0; size as usize];
            let count = file.file.read_at(&mut bytes, offset).map_err(host_errno)?;
            // Keep only bytes that the host file supplied. The MMU zero-fills the tail.
            bytes.truncate(count);
            bytes
        };

        self.memory
            .replace_mapping(base, size, page_perms(prot), &bytes)
            .map_err(|_| 12)?;
        // Replacement can change executable bytes or permissions at an existing guest PC.
        self.invalidate_cache(base, size);
        // A successful replacement validated that the mapping end fits in u64.
        self.mmap_base = self.mmap_base.max(base + size);

        // dbg!(self.memory);

        Ok(base)
    }

    fn sys_mprotect(&mut self) -> Result<u64, i32> {
        // `mprotect` receives address, length, and protection in x10 through x12.
        let base = self.state.regs[10];
        let size = self.state.regs[11];
        let prot = self.state.regs[12];
        // As in `mmap`, reject every protection bit outside the low R/W/X mask.
        if prot & !7 != 0 || !self.memory.protect(base, size, page_perms(prot)) {
            return Err(22);
        }
        Ok(0)
    }

    fn sys_munmap(&mut self) -> Result<u64, i32> {
        // `munmap` receives address in x10 and byte length in x11.
        let base = self.state.regs[10];
        let size = self.state.regs[11];
        self.memory.unmap(base, size).map_err(|_| 22)?;
        self.invalidate_cache(base, size);
        Ok(0)
    }

    fn sys_getrandom(&mut self) -> Result<u64, i32> {
        // `getrandom` receives output address in x10, byte count in x11, and flags in x12.
        // This deterministic subset ignores all flag values, including invalid Linux flags.
        let size = usize::try_from(self.state.regs[11]).map_err(|_| 22)?;
        // Deterministic bytes make replay and fuzzing results reproducible.
        // They are not random and are not safe for cryptographic or security use.
        // The odd multiplier 31 visits each byte value once for every 256 indices.
        // The offset 17 avoids an all-zero prefix. Wrapping keeps arithmetic modulo 256.
        let bytes = (0..size)
            .map(|idx| (idx as u8).wrapping_mul(31).wrapping_add(17))
            .collect::<Vec<_>>();
        if !self.memory.store_bytes(self.state.regs[10], &bytes) {
            return Err(14);
        }

        Ok(size as u64)
    }

    fn sys_clock_gettime(&mut self) -> Result<u64, i32> {
        // `clock_gettime` receives the clock ID in x10 and output address in x11.
        // This deterministic clock accepts and ignores every clock ID. Linux does not do this;
        // it is an ABI limitation of the emulator.
        // A fixed time removes host timing from deterministic guest runs.
        // RV64 `timespec` has one 8-byte seconds field and one 8-byte nanoseconds field.
        // Sixteen zero bytes therefore represent time zero without host-layout casts.
        if !self.memory.store_bytes(self.state.regs[11], &[0; 16]) {
            return Err(14);
        }
        Ok(0)
    }

    fn sys_sched_getaffinity(&mut self) -> Result<u64, i32> {
        // `sched_getaffinity` receives pid, mask size, and mask address in x10 through x12.
        // This single-task model does not need the pid to select another guest task.
        let size = usize::try_from(self.state.regs[11]).map_err(|_| 22)?;
        // Expose one virtual CPU so guests do not create host-dependent worker counts.
        // Bit 0 in the byte selects virtual CPU 0. Return 1 because one mask byte was written.
        // Raw Linux returns its kernel affinity-mask byte size, which need not be one.
        // Returning one is an emulator policy and ABI limitation.
        if size == 0 || !self.memory.store_bytes(self.state.regs[12], &[1]) {
            return Err(14);
        }
        Ok(1)
    }

    fn sys_uname(&mut self) -> Result<u64, i32> {
        // `uname` receives the guest `utsname` output address in x10.
        // Fixed identity data prevents host details from changing guest behavior.
        // Linux `new_utsname` has six arrays of 65 bytes. Each array permits 64 text
        // bytes plus one NUL. The arrays are system, node, release, version, machine,
        // and domain name.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/linux/utsname.h
        let mut uts = [0u8; 65 * 6];
        for (index, value) in ["Linux", "remu", "6.0.0", "#1", "riscv64", ""]
            .iter()
            .enumerate()
        {
            // Multiply by one complete field width to keep text in its own NUL-filled array.
            let start = index * 65;
            uts[start..start + value.len()].copy_from_slice(value.as_bytes());
        }
        if !self.memory.store_bytes(self.state.regs[10], &uts) {
            return Err(14);
        }
        Ok(0)
    }

    fn sys_getrlimit(&mut self) -> Result<u64, i32> {
        // `getrlimit` receives the resource in x10 and output address in x11.
        self.write_guest_rlimit(self.state.regs[11], self.state.regs[10])
    }

    fn sys_prlimit64(&mut self) -> Result<u64, i32> {
        // `prlimit64` receives pid, resource, new-limit pointer, and old-limit pointer
        // in x10 through x13. This one-process model ignores pid.
        // A non-null x12 is a request to set a new limit. Reject it because emulator
        // policy limits must stay consistent with mapped memory and descriptor handling.
        if self.state.regs[12] != 0 {
            return Err(22);
        }
        // A non-null x13 requests the old limit. x11 contains the resource number.
        if self.state.regs[13] != 0 {
            self.write_guest_rlimit(self.state.regs[13], self.state.regs[11])?;
        }
        Ok(0)
    }

    fn read_guest_string(&self, addr: u64, max: usize) -> Result<String, i32> {
        // Linux path arguments are NUL-terminated byte strings in guest memory. This runtime
        // chooses a Rust `String`, so it accepts only UTF-8 guest paths.
        // Path handlers pass 4096 as an emulator work limit because it is one selected guest
        // page. This value is not a universal Linux pathname limit.
        let mut bytes = Vec::new();
        let mut current = addr;

        // Read per page so a terminator before an unmapped next page still succeeds.
        while bytes.len() < max {
            // A 4 KiB page is a power of two. AND with 4095 (`PAGE_SIZE - 1`) keeps
            // the low 12 address bits, which are the offset inside the current page.
            // Subtract that offset to get the byte count up to the next page boundary.
            let page_left = PAGE_SIZE - (current as usize & (PAGE_SIZE - 1));
            let count = page_left.min(max - bytes.len());
            let chunk = self.memory.load_bytes(current, count).ok_or(14)?;
            if let Some(end) = chunk.iter().position(|byte| *byte == 0) {
                // Exclude the NUL marker. Error 22 (`EINVAL`) reports a non-UTF-8 path.
                bytes.extend_from_slice(&chunk[..end]);
                return String::from_utf8(bytes).map_err(|_| 22);
            }
            bytes.extend_from_slice(&chunk);
            current = current.checked_add(count as u64).ok_or(14)?;
        }

        // No NUL occurred within the policy limit, so the path argument is invalid.
        Err(22)
    }

    // todo - egal
    fn write_guest_stat(&mut self, addr: u64, metadata: Option<&fs::Metadata>) -> Result<u64, i32> {
        // Build the RV64 Linux byte layout explicitly because the host Rust type has another ABI.
        // The generic 64-bit Linux `struct stat` is 128 bytes. It has explicit padding at
        // bytes 40..48 and 60..64, and unused bytes at 120..128. Starting with zero fills
        // these ABI gaps and prevents host data from leaking to the guest.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/stat.h
        let mut stat = [0u8; 128];
        if let Some(metadata) = metadata {
            // Bytes 0 and 8 hold 64-bit device and inode numbers.
            put_u64(&mut stat, 0, metadata.dev());
            put_u64(&mut stat, 8, metadata.ino());
            // Bytes 16 through 28 hold four 32-bit values: mode, link count, user ID,
            // and group ID. These widths are part of the guest ABI, not host Rust types.
            put_u32(&mut stat, 16, metadata.mode());
            put_u32(&mut stat, 20, metadata.nlink() as u32);
            put_u32(&mut stat, 24, metadata.uid());
            put_u32(&mut stat, 28, metadata.gid());
            // Byte 32 holds the special-file device. Byte 40 is the first padding slot.
            put_u64(&mut stat, 32, metadata.rdev());
            // File size starts at byte 48. Preferred I/O block size is a 32-bit value at 56.
            put_u64(&mut stat, 48, metadata.size());
            put_u32(&mut stat, 56, metadata.blksize() as u32);
            // Byte 60 is padding. The 64-bit count of allocated 512-byte blocks starts at 64.
            put_u64(&mut stat, 64, metadata.blocks());
            // Three timestamp pairs follow. Each pair has 8-byte seconds and 8-byte
            // nanoseconds fields, at offsets 72, 88, and 104.
            put_u64(&mut stat, 72, metadata.atime() as u64);
            put_u64(&mut stat, 80, metadata.atime_nsec() as u64);
            put_u64(&mut stat, 88, metadata.mtime() as u64);
            put_u64(&mut stat, 96, metadata.mtime_nsec() as u64);
            put_u64(&mut stat, 104, metadata.ctime() as u64);
            put_u64(&mut stat, 112, metadata.ctime_nsec() as u64);
        } else {
            // Octal 020000 is `S_IFCHR`, and 0666 gives read/write permission to all users.
            // This makes a standard stream look like a character device instead of a file.
            put_u32(&mut stat, 16, 0o020666);
            // A synthetic stream has one link and the same unprivileged ID 1000 as auxv.
            put_u32(&mut stat, 20, 1);
            put_u32(&mut stat, 24, 1000);
            put_u32(&mut stat, 28, 1000);
            // Report 4 KiB as the preferred I/O block size to match guest memory pages.
            put_u32(&mut stat, 56, PAGE_SIZE as u32);
        }
        if !self.memory.store_bytes(addr, &stat) {
            return Err(14);
        }
        Ok(0)
    }

    fn resolve_process_path(&self, guest_path: &str, create: bool) -> Result<PathBuf, i32> {
        let path = Path::new(guest_path);
        // Absolute guest paths use the sysroot; relative paths use the writable work directory.
        let root = if path.is_absolute() {
            // Error 2 is `ENOENT`. Without a sysroot, no absolute guest tree exists.
            self.process.sysroot.as_ref().ok_or(2)?
        } else {
            self.process.workdir.as_ref().ok_or(2)?
        };

        resolve_beneath(root, path, create).map_err(host_errno)
    }

    fn write_guest_rlimit(&mut self, addr: u64, resource: u64) -> Result<u64, i32> {
        // Linux resource 3 is `RLIMIT_STACK`, and 7 is `RLIMIT_NOFILE`. The project
        // exposes its 128 KiB mapped stack and reports 1024 descriptors. It does not enforce
        // that descriptor limit. It also reports infinity for unknown resources, although
        // Linux normally returns EINVAL. Infinity has an all-ones unsigned representation.
        // Source: https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/resource.h
        let value = match resource {
            3 => DEFAULT_STACK_SIZE,
            7 => 1024,
            _ => u64::MAX,
        };
        // RV64 `struct rlimit` has two 8-byte words. Write the same value as the soft
        // current limit and the hard maximum limit.
        if !self.memory.store_le(addr, 8, value) || !self.memory.store_le(addr + 8, 8, value) {
            return Err(14);
        }
        Ok(0)
    }

    fn invalidate_cache(&mut self, base: u64, size: u64) {
        // Native code is tied to guest addresses whose mappings can be replaced or removed.
        // Saturating addition treats an overflowing range as one that reaches the highest
        // guest address. It cannot wrap and retain low-address entries by mistake.
        let end = base.saturating_add(size);
        self.cache.retain(|pc, _| *pc < base || *pc >= end);
        self.sync_jit_entries();
    }

    fn sync_jit_entries(&mut self) {
        // Rebuild after each cache change because vector growth can move the raw ABI array.
        self.jit_entries = self
            .cache
            .iter()
            .map(|(&guest_pc, compiled)| JitEntryAbi {
                guest_pc,
                execute: compiled.entry(),
            })
            .collect();
        // `as_ptr` borrows vector storage without moving entries. Generated code must use
        // the paired count and must not keep the pointer after the cache changes.
        self.state.jit_entries = self.jit_entries.as_ptr();
        self.state.jit_entry_count = self.jit_entries.len();

        // dbg!(self.state.jit_entries);
    }

    fn initialize_process_state(&mut self) -> JitResult<()> {
        // RISC-V x2 is `sp`. Begin below the exact mapping top so startup data can grow down.
        self.state.regs[2] = self.memory.stack_top - DEFAULT_STACK_POINTER_OFFSET;

        // Use the linker-defined global pointer because RISC-V code can address data through it.
        self.state.regs[3] = self
            .program
            .find_symbol("__global_pointer$")
            .map(|symbol| symbol.value)
            .unwrap_or(0);

        // RISC-V x4 is `tp`, the thread pointer. Zero is valid until a guest dynamic loader
        // sets up thread-local storage. This runtime does not create a guest thread itself.
        self.state.regs[4] = 0;

        self.build_elf_entry_state()?;
        self.state.pc = self.initial_pc;
        Ok(())
    }

    // todo - quatsch
    fn build_elf_entry_state(&mut self) -> JitResult<()> {
        // Linux starts a process with strings at high stack addresses and an entry table
        // below them. The table contains argc, argv, envp, and auxiliary-vector records.
        // Source: https://github.com/torvalds/linux/blob/master/fs/binfmt_elf.c
        let mut sp = self.memory.stack_top - DEFAULT_STACK_POINTER_OFFSET;

        // Clone these vectors to avoid a Rust borrow conflict: the stack-writing methods
        // need mutable access to the runtime while configuration is stored in the same value.
        let argv_values = self.process.argv.clone();
        let envp_values = self.process.envp.clone();

        // Store strings first so the final entry table can contain stable guest pointers.
        let argv = self.push_guest_strings(&mut sp, &argv_values)?;
        let envp = self.push_guest_strings(&mut sp, &envp_values)?;

        // Keep the 16-byte AT_RANDOM object aligned to 16 bytes. Linux defines the object
        // size as 16, and aligned placement also preserves the final RISC-V stack alignment.
        let random_addr = self.push_guest_stack_bytes(&mut sp, &ELF_AUX_RANDOM, 16)?;

        let argc = argv.len() as u64;
        // Linux AT_EXECFN points at the executed pathname. This runtime uses argv[0] as an approximation.
        // Use null when no argument exists.
        let execfn_ptr = argv.first().copied().unwrap_or(0);

        // todo -- siehe oben struct auxv
        let auxv = self.build_elf_auxv(random_addr, execfn_ptr)?;

        // RV64 uses 8-byte words. The table has one argc word, one word per pointer,
        // one null word after each pointer list, and two words per auxiliary entry.
        let table_size = 8
            + ((argv.len() + 1) as u64 * 8)
            + ((envp.len() + 1) as u64 * 8)
            + (auxv.len() as u64 * 16);

        // Linux requires an aligned initial stack for the process entry ABI.
        // The RISC-V psABI requires x2 to be aligned to 128 bits, which is 16 bytes.
        // Source: https://riscv-non-isa.github.io/riscv-elf-psabi-doc/#integer-calling-convention
        let table_addr = self.reserve_guest_stack(&mut sp, table_size, 16)?;
        self.write_elf_entry_table(table_addr, argc, &argv, &envp, &auxv)?;

        // x1 is the return-address register. Process entry has no RISC-V caller, so zero is
        // the no-caller sentinel. A guest can still execute address zero if it is mapped.
        self.state.regs[1] = 0;
        self.state.regs[2] = table_addr;
        // `_start` reads argc and pointer lists from x2. Clear a0 through a2 so startup
        // cannot depend on old values from a reused runtime state.
        self.state.regs[10] = 0;
        self.state.regs[11] = 0;
        self.state.regs[12] = 0;

        Ok(())
    }

    // todo ??
    fn build_elf_auxv(&self, random_addr: u64, execfn_ptr: u64) -> JitResult<Vec<AuxEntry>> {
        // The main executable must expose its program headers because the dynamic loader
        // uses them before normal application code starts.
        let phdr_addr = self
            .program
            .elf_phdr_addr
            .ok_or_else(|| io::Error::other("missing ELF program header address"))?;

        // Keep the records explicit. This makes guest-visible process policy independent
        // from the host process and gives the dynamic loader a stable environment.
        Ok(vec![
            (AT_PHDR, phdr_addr),
            (AT_PHENT, self.program.elf_phent_size as u64),
            (AT_PHNUM, self.program.elf_phnum as u64),
            (AT_PAGESZ, PAGE_SIZE as u64),
            // Zero means no interpreter. Otherwise this is the fixed loader bias.
            (AT_BASE, self.loader_base),
            (AT_FLAGS, 0),
            (AT_ENTRY, self.program.entry_pc),
            // ID 1000 models one unprivileged user and agrees with identity syscalls.
            (AT_UID, 1000),
            (AT_EUID, 1000),
            (AT_GID, 1000),
            (AT_EGID, 1000),
            (AT_HWCAP, RISCV_HWCAP),
            // Advertise the fixed policy value of 100 clock ticks per second.
            (AT_CLKTCK, 100),
            (AT_SECURE, 0),
            (AT_RANDOM, random_addr),
            (AT_HWCAP2, 0),
            (AT_EXECFN, execfn_ptr),
            // The final zero type is mandatory because consumers scan until AT_NULL.
            (AT_NULL, 0),
        ])
    }

    fn write_elf_entry_table(
        &mut self,
        table_addr: u64,
        argc: u64,
        argv: &[u64],
        envp: &[u64],
        auxv: &[AuxEntry],
    ) -> JitResult<()> {
        // `c` is a guest byte address. Each write advances it by one RV64 word.
        let mut c = table_addr;

        self.write_guest_u64(c, argc, "argc")?;
        c += 8;

        // The table order is argc, argv pointers, null, envp pointers, null, then auxv.
        self.write_u64_s(&mut c, argv, "argv entry")?;
        self.write_guest_u64(c, 0, "argv terminator")?;
        c += 8;

        self.write_u64_s(&mut c, envp, "envp entry")?;
        self.write_guest_u64(c, 0, "envp terminator")?;
        c += 8;

        // Write each auxiliary entry as its type word followed by its value word, as the ABI requires.
        for &(kind, value) in auxv {
            self.write_guest_u64(c, kind, "auxv type")?;
            c += 8;
            self.write_guest_u64(c, value, "auxv value")?;
            c += 8;
        }

        Ok(())
    }

    fn write_u64_s(&mut self, cursor: &mut u64, values: &[u64], what: &str) -> JitResult<()> {
        for &value in values {
            self.write_guest_u64(*cursor, value, what)?;
            // Advance by 8 because every pointer and integer word is 64 bits on RV64.
            *cursor += 8;
        }

        Ok(())
    }

    fn write_guest_u64(&mut self, addr: u64, value: u64, what: &str) -> JitResult<()> {
        // Store exactly 8 bytes in guest little-endian order. Do not copy the host memory
        // representation because host byte order is not part of the guest ABI.
        if !self.memory.store_le(addr, 8, value) {
            return Err(io::Error::other(format!("failed to write guest {what}")).into());
        }

        Ok(())
    }

    // fn invalidate_cache(&mut self, base: u64, size: u64) {
    //     let end = base.saturating_add(size);
    //     self.cache.retain(|pc, _| *pc < base || *pc >= end);
    //     self.sync_jit_entries();
    // }

    fn push_guest_strings(&mut self, sp: &mut u64, values: &[String]) -> JitResult<Vec<u64>> {
        let mut addresses = Vec::with_capacity(values.len());

        // Push in reverse because the stack grows down, then restore logical argument order.
        for value in values.iter().rev() {
            // Linux C strings need one zero byte after their text.
            let mut bytes = value.as_bytes().to_vec();
            bytes.push(0);
            let addr = self.push_guest_stack_bytes(sp, &bytes, 1)?;
            addresses.push(addr);
        }

        addresses.reverse();
        Ok(addresses)
    }

    fn push_guest_stack_bytes(&mut self, sp: &mut u64, bytes: &[u8], align: u64) -> JitResult<u64> {
        // Reserve before writing because a downward-growing stack places new data below `sp`.
        let addr = self.reserve_guest_stack(sp, bytes.len() as u64, align)?;

        if !self.memory.store_bytes(addr, bytes) {
            return Err(io::Error::other("failed to write guest stack bytes").into());
        }
        Ok(addr)
    }

    fn reserve_guest_stack(&mut self, sp: &mut u64, size: u64, align: u64) -> JitResult<u64> {
        // Checked subtraction rejects a request that would wrap below guest address zero.
        let next = sp
            .checked_sub(size)
            .ok_or_else(|| io::Error::other("guest stack underflow"))?;

        // Alignment can add padding below the object. `max(1)` prevents a zero alignment.
        // `align_down` requires a power of two. Current callers supply only 1 or 16.
        let aligned = align_down(next, align.max(1));

        // The stack mapping starts 128 KiB below its fixed top. Reject data outside it.
        if aligned < DEFAULT_STACK_TOP - DEFAULT_STACK_SIZE {
            return Err(io::Error::other("overflow!").into());
        }

        *sp = aligned;
        Ok(aligned)
    }
}

// todo - quatsch
// Finds known block-entry PCs so lazy compilation can include direct neighbors.
fn direct_successors(nnil: &Nnil) -> Vec<u64> {
    let mut successors = Vec::new();

    // Use only explicit targets so lazy batching never guesses an indirect destination.
    // NNIL regions end with their control-flow operation. Earlier instructions cannot
    // select the next region, so only the final instruction is relevant here.
    match nnil.insns().last() {
        Some(
            NnilInstruction::Beq { ttgt, ftgt, .. }
            | NnilInstruction::Bne { ttgt, ftgt, .. }
            | NnilInstruction::Blt { ttgt, ftgt, .. }
            | NnilInstruction::Bgt { ttgt, ftgt, .. },
        ) => {
            // Conditional branches have one false label and one true label. Both can be
            // the next block, so resolve both labels to guest addresses.
            if let Some(address) = nnil.label_address(*ftgt) {
                successors.push(address.0);
            }
            if let Some(address) = nnil.label_address(*ttgt) {
                successors.push(address.0);
            }
        }

        Some(NnilInstruction::Jr { dst } | NnilInstruction::Jmp { dst }) => {
            // `dst` is an NNIL instruction handle. It is a static successor only when that
            // instruction is a nonnegative immediate guest address.
            if let Some(NnilInstruction::Imm { imm }) = nnil.insns().get(dst.0 as usize)
                && *imm >= 0
            {
                successors.push(*imm as u64);
            }
        }


        Some(NnilInstruction::Syscall {} | NnilInstruction::Sysbreak {}) => {
            // Generated code records the post-region PC before either stop. A later resume
            // starts there; a syscall can also resume inside the runtime.
            successors.push(nnil.pc());
        }
        _ => {}
    }

    successors
}

fn resolve_guest_path(sysroot: &Path, guest_path: &str) -> io::Result<PathBuf> {
    // Check ELF interpreter paths against the configured sysroot.
    if !guest_path.starts_with('/') {
        return Err(io::Error::other("guest path is not absolute"));
    }

    resolve_beneath(sysroot, Path::new(guest_path), false)
}

// todo - macht fuzzer schon?
// Converts a guest path to a host path and checks its current canonical target against `root`.
fn resolve_beneath(root: &Path, path: &Path, create: bool) -> io::Result<PathBuf> {
    let mut relative = PathBuf::new();

    // Reject parent components before canonicalization to make escape attempts explicit.
    for component in path.components() {
        match component {
            // Ignore the guest root marker so `PathBuf::join` cannot replace the host root.
            // A current-directory marker does not change the location.
            Component::RootDir | Component::CurDir => {}
            // Normal components are the only guest-controlled text added below the root.
            Component::Normal(value) => relative.push(value),
            // `..` can leave the root. A platform prefix can select another host volume.
            Component::ParentDir | Component::Prefix(_) => {
                return Err(io::Error::new(
                    io::ErrorKind::PermissionDenied,
                    "guest path escapes its root",
                ));
            }
        }
    }

    let candidate = root.join(relative);

    // Canonicalization detects symbolic links that leave the allowed root at check time.
    // A later host-side link change can race the file operation, so this is not a strong sandbox boundary.
    match fs::canonicalize(&candidate) {
        // `Path::starts_with` compares path components, not an unsafe text prefix.
        Ok(path) if path.starts_with(root) => Ok(path),
        Ok(_) => Err(io::Error::new(
            io::ErrorKind::PermissionDenied,
            "guest path escapes its root",
        )),

        Err(err) if create && err.kind() == io::ErrorKind::NotFound => {
            // A new file has no canonical path, so validate its existing parent instead.
            let parent = candidate
                .parent()
                .ok_or_else(|| io::Error::other("guest path has no parent"))?;
            let parent = fs::canonicalize(parent)?;
            if !parent.starts_with(root) {
                return Err(io::Error::new(
                    io::ErrorKind::PermissionDenied,
                    "guest path escapes its root",
                ));
            }
            let name = candidate
                .file_name()
                .ok_or_else(|| io::Error::other("guest path has no file name"))?;
            Ok(parent.join(name))
        }
        Err(err) => Err(err),
    }
}

fn host_errno(err: io::Error) -> i32 {
    // Preserve native Unix error numbers when the host supplied one. These are guest Linux
    // values only on a Linux host. Another Unix host needs an explicit errno translation.
    if let Some(errno) = err.raw_os_error() {
        return errno;
    }

    // Use Linux generic errno values when Rust has only a portable error category:
    // 2=ENOENT, 13=EACCES, 17=EEXIST, and 22=EINVAL. Error 5, EIO, is the project fallback.
    // Source: https://github.com/torvalds/linux/blob/master/include/uapi/asm-generic/errno-base.h
    match err.kind() {
        io::ErrorKind::NotFound => 2,
        io::ErrorKind::PermissionDenied => 13,
        io::ErrorKind::AlreadyExists => 17,
        io::ErrorKind::InvalidInput | io::ErrorKind::InvalidData => 22,
        _ => 5,
    }
}

fn guest_errno(errno: i32) -> u64 {
    // Linux reports syscall errors as negative values in the unsigned guest register.
    // The final cast keeps the two's-complement bit pattern that RV64 sees in x10.
    (-(errno as i64)) as u64
}

// todo - code dup
fn write_marked_output(
    mut output: impl io::Write,
    bytes: &[u8],
    name: &str,
    color: &str,
    colored: bool,
) -> Result<usize, i32> {

    // Add color only for terminals so redirected guest output has no escape sequences.
    let (color, reset) = if colored {
        // ANSI sequence 0 clears color and intensity after the marker.
        (color, "\x1b[0m")
    } else {
        ("", "")
    };

    writeln!(output, "\n{color}----- guest {name} -----{reset}").map_err(host_errno)?;
    // `write` can complete only a prefix. Return that actual count as the guest result.
    let count = output.write(bytes).map_err(host_errno)?;
    // Add a display newline only when the written prefix has none. This newline is part
    // of the host marker and is not included in the guest byte count.
    if bytes
        .get(..count)
        .is_none_or(|written| !written.ends_with(b"\n"))
    {
        writeln!(output).map_err(host_errno)?;
    }

    writeln!(output, "{color}----- end guest {name} -----{reset}").map_err(host_errno)?;
    // Flush now so guest output appears before later emulator diagnostics.
    output.flush().map_err(host_errno)?;

    Ok(count)
}

fn page_perms(prot: u64) -> PagePerms {
    // Linux `PROT_READ`, `PROT_WRITE`, and `PROT_EXEC` use the same low three bits as
    // `PagePerms`. Callers reject higher bits before this narrowing cast.
    PagePerms::from_bits(prot as u8)
}

fn put_u32(bytes: &mut [u8], offset: usize, value: u32) {
    // A 32-bit field occupies four bytes. Explicit little-endian order builds RV64 data
    // correctly even if the host layout or alignment is different.
    // The caller must supply an in-bounds fixed ABI offset, or slicing will panic.
    bytes[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
}

fn put_u64(bytes: &mut [u8], offset: usize, value: u64) {
    // A 64-bit field occupies eight bytes. The caller must supply an in-bounds fixed ABI
    // offset, or slicing will panic.
    bytes[offset..offset + 8].copy_from_slice(&value.to_le_bytes());
}

// todo
#[derive(Debug, Clone, Copy)]
// Store only section fields that later symbol and relocation code reads.
struct ElfSectionHeader {
    // The type selects symbol, string, relocation, or other section semantics.
    sh_type: u32,
    // Offset and size select this section's byte range in the ELF file.
    sh_offset: u64,
    sh_size: u64,
    // Its meaning depends on the section type. For SYMTAB or DYNSYM it selects the name
    // string table. For RELA it selects the related symbol table.
    sh_link: u32,
    // A nonzero entry size converts the section byte size to a record count.
    sh_entsize: u64,
}

// todo -- gamozo macht readelf, nm
// Reads the ELF64 section table for optional symbol and import metadata.
fn parse_section_headers(
    bytes: &[u8],
    shoff: usize,
    shentsize: usize,
    shnum: usize,
) -> JitResult<Vec<ElfSectionHeader>> {
    if shnum == 0 {
        // An ELF can execute without section headers because program headers define mapping.
        // ELF also uses zero for extended numbering. This parser treats zero as no sections
        // and does not support that extended form.
        return Ok(Vec::new());
    }

    let mut sections = Vec::with_capacity(shnum);

    // Retain only fields needed for symbol and relocation parsing.
    for idx in 0..shnum {
        // Multiply the file-defined entry size by the index. Saturation prevents a low wrap
        // in that product, and checked addition protects the table base addition.
        let header = shoff
            .checked_add(idx.saturating_mul(shentsize))
            .ok_or_else(|| io::Error::other("section header overflow"))?;

        // Check the declared entry range. The final `header + shentsize` is unchecked, and
        // this parser does not require the 64 bytes that its fixed ELF64 field reads need.
        let _ = bytes
            .get(header..header + shentsize)
            .ok_or_else(|| io::Error::other(""))?;

        // ELF64 section fields start at byte offsets 4, 24, 32, 40, and 56.
        // Source: https://gabi.xinuos.com/elf/03-sheader.html
        sections.push(ElfSectionHeader {
            sh_type: read_u32(bytes, header + 4)?,
            sh_offset: read_u64(bytes, header + 24)?,
            sh_size: read_u64(bytes, header + 32)?,
            sh_link: read_u32(bytes, header + 40)?,
            sh_entsize: read_u64(bytes, header + 56)?,
        });
    }

    Ok(sections)
}

fn parse_symbol_section(
    bytes: &[u8],
    sections: &[ElfSectionHeader],
    section: &ElfSectionHeader,
) -> JitResult<Vec<ProgramSymbol>> {
    if section.sh_entsize == 0 {
        // A zero divisor cannot define records, so treat the malformed table as empty.
        return Ok(Vec::new());
    }

    // ELF links each symbol table to the string table that owns its names.
    let strtab = sections
        .get(section.sh_link as usize)
        .ok_or_else(|| io::Error::other(""))?;

    let strtab_bytes = read_elf_range(bytes, strtab.sh_offset, strtab.sh_size, "string table")?;
    // Integer division silently ignores an incomplete trailing record. This is a parser limit.
    // ELF64 symbols need 24 bytes, but this parser does not reject a smaller nonzero entry size.
    let count = (section.sh_size / section.sh_entsize) as usize;

    let mut symbols = Vec::with_capacity(count);

    for idx in 0..count {
        // Select entry `idx` inside the symbol-table section without unchecked addition.
        let sym_offset = section
            .sh_offset
            .checked_add((idx as u64).saturating_mul(section.sh_entsize))
            .ok_or_else(|| io::Error::other("symbol table overflow"))?
            as usize;

        // An ELF64 symbol record is 24 bytes. `st_name` is at 0, `st_shndx` at 6,
        // `st_value` at 8, and `st_size` at 16. Bytes 4 and 5 hold binding/type and
        // visibility, which current debugger lookup does not need.
        // Source: https://gabi.xinuos.com/elf/05-symtab.html
        let name_offset = read_u32(bytes, sym_offset)? as usize;
        let section_index = read_u16(bytes, sym_offset + 6)?;

        let value = read_u64(bytes, sym_offset + 8)?;
        let size = read_u64(bytes, sym_offset + 16)?;
        let name = read_elf_string(strtab_bytes, name_offset);

        symbols.push(ProgramSymbol {
            name,
            value,
            size,
            section_index,
        });
    }

    // dbg!(symbols);
    Ok(symbols)
}

// todo - code dup
// Reads one 16-bit ELF integer from an in-bounds slice.
fn read_u16(bytes: &[u8], offset: usize) -> io::Result<u16> {
    // The caller must ensure that `offset + 2` does not overflow usize.
    let raw = bytes
        .get(offset..offset + 2)
        .ok_or_else(|| io::Error::other("short ELF read (u16)"))?;
    // The slice check guarantees exactly two bytes, so this conversion cannot fail.
    // The ELF identity check already established little-endian byte order.
    Ok(u16::from_le_bytes(raw.try_into().unwrap()))
}

// Reads one 32-bit ELF integer from an in-bounds slice.
fn read_u32(bytes: &[u8], offset: usize) -> io::Result<u32> {
    // The caller must ensure that `offset + 4` does not overflow usize.
    let raw = bytes
        .get(offset..offset + 4)
        .ok_or_else(|| io::Error::other("short ELF read (u32)"))?;

    // The four-byte slice makes `try_into` safe to unwrap.
    Ok(u32::from_le_bytes(raw.try_into().unwrap()))
}

// Reads one 64-bit ELF integer from an in-bounds slice.
fn read_u64(bytes: &[u8], offset: usize) -> io::Result<u64> {
    // The caller must ensure that `offset + 8` does not overflow usize.
    let raw = bytes
        .get(offset..offset + 8)
        .ok_or_else(|| io::Error::other("short ELF read (u64)"))?;

    // The eight-byte slice makes `try_into` safe to unwrap.
    Ok(u64::from_le_bytes(raw.try_into().unwrap()))
}

fn read_elf_range<'a>(bytes: &'a [u8], offset: u64, size: u64, what: &str) -> io::Result<&'a [u8]> {
    // Check every conversion and addition because ELF offsets are untrusted input.
    let start =
        usize::try_from(offset).map_err(|_| io::Error::other(format!("{what} offset overflow")))?;

    let len =
        usize::try_from(size).map_err(|_| io::Error::other(format!("{what} size overflow")))?;

    let end = start
        .checked_add(len)
        .ok_or_else(|| io::Error::other(format!("{what} range overflow")))?;

    bytes
        .get(start..end)
        .ok_or_else(|| io::Error::other(format!("{what} range overflow")))
}

fn read_elf_string(bytes: &[u8], offset: usize) -> String {
    // An invalid string-table offset is not allowed to index the host slice.
    let Some(rest) = bytes.get(offset..) else {
        return String::new();
    };
    // Stop at NUL because following bytes belong to other strings in the table.
    // If no NUL remains, this parser accepts all remaining bytes. That is a malformed-ELF limit.
    let end = rest
        .iter()
        .position(|byte| *byte == 0)
        .unwrap_or(rest.len());
    // ELF names are bytes. Lossy conversion preserves usable diagnostics for an invalid
    // UTF-8 name and returns owned text that does not borrow the ELF input.
    String::from_utf8_lossy(&rest[..end]).into_owned()
}

/*

fn read_elf_parse(bytes: &[u8], offset: usize) -> String {
    let Some(rest) = bytes.get(offset..) else {
        return String::new();

}
*/