jit/

remi.rs

//! The Rust emitter uses `rustc` as the native backend to keep machine-code generation small.

use crate::{
    DEBUG_SLOTS, ExecuteFn, ExitReason, FP_REG_BASE, GUEST_REG_COUNT, GUEST_TMP_COUNT, GuestState,
    INTEGER_ZERO_REG, JitResult, PAGE_SIZE,
};

use liil::nnil::{Address, AmoOp, Insn, Label, Nnil, NnilInstruction};

use std::collections::{BTreeMap, BTreeSet};
use std::fmt::Write as _;
use std::fs;
use std::io;
use std::path::{Path, PathBuf};
use std::process::Command;
use std::sync::{Arc, OnceLock};
use std::time::{SystemTime, UNIX_EPOCH};

// todo -- via .so/dynamic loader wahrscheinlich nicht das beste.
//         gamozolabs baut static und lädt mit eigenen Tldscript.ld
use libloading::Library;

/*
    remi = Rust EMItter

    todo
    ----
    - duplicate code
    - refactor block emitter
    - rustc > memory > tdlink statt als cdylib
*/

enum LoadedJitCode {
    // The shared-library mode lets the host dynamic loader apply relocations and map sections.
    Shared(Library),
    #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
    // The raw mode omits the dynamic loader to reduce the load work for small JIT regions.
    Raw(RawCode),
}

// Keep the code owner beside its paths so an entry pointer cannot outlive the loaded artifact.
struct LoadedJitArtifact {
    // This owner keeps either the library mapping or the raw `mmap` allocation alive.
    code: LoadedJitCode,
    // Keep both paths for diagnostics, even after the code is in memory.
    source_path: PathBuf,
    library_path: PathBuf,
    // The runtime uses this flag to separate cache hits from new compiler work.
    compiled_now: bool,
}

/// Owns a callable JIT entry and the artifact that keeps its native code valid.
pub struct CompiledJit {
    artifact: Arc<LoadedJitArtifact>,
    execute: ExecuteFn,
}

impl CompiledJit {
    /// Exposes generated Rust for diagnostics and translation inspection.
    pub fn source_path(&self) -> &Path {
        &self.artifact.source_path
    }

    /// Exposes the native artifact so verbose output can identify cache entries.
    pub fn library_path(&self) -> &Path {
        &self.artifact.library_path
    }

    pub(crate) fn compiled_now(&self) -> bool {
        self.artifact.compiled_now
    }

    pub(crate) fn entry(&self) -> ExecuteFn {
        self.execute
    }

    pub(crate) unsafe fn run(&self, state: &mut GuestState) -> ExitReason {
        // The artifact lifetime guarantees the entry pointer stays mapped for this call.
        unsafe { (self.execute)(state as *mut GuestState) }
    }
}

#[derive(Debug, Clone, Copy)]
struct BasicBlock {
    // A guest address is also a possible run-time entry point into this block.
    addr: Address,
    // Store NNIL indexes instead of slices because the emitter keeps one shared NNIL owner.
    start_insn: usize,
    end_insn: usize,
    // A known fallthrough permits a direct tail call instead of a table lookup.
    fallthrough: Option<Address>,
    // A region end still needs a precise guest PC before it returns to the dispatcher.
    next_pc: u64,
}

// Load mode is separate from the load operation because NNIL uses following marker values.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum LoadMode {
    Raw,
    ZeroExtend,
    SignExtend,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Signedness {
    // NNIL stores all integer bits in `u64`; these values select their interpretation.
    Signed,
    Unsigned,
}

struct RustEmitter<'a> {
    // A borrow avoids a copy of the full intermediate program during code generation.
    nnil: &'a Nnil,
    blocks: Vec<BasicBlock>,
    // Ordered maps make generated symbol order and output text reproducible.
    block_names: BTreeMap<Address, String>,
    // A set makes repeated signedness checks independent of a scan through all NNIL.
    unsigned_markers: BTreeSet<u64>,
}

/// Compiles one NNIL region for callers that need an independent entry point.
pub fn compile_jit(
    nnil: &Nnil,
    output_dir: &Path,
    opt_level: u8,
    cache_dir: Option<&Path>,
    raw_jit: bool,
) -> JitResult<CompiledJit> {
    // Generate source before file creation, so an emitter error leaves no partial artifact.
    let rust_code = generate_rust_code(nnil)?;
    let artifact = compile_generated_artifact(
        rust_code,
        output_dir,
        "generated",
        opt_level,
        cache_dir,
        raw_jit,
    )?;
    compiled_symbol_from_artifact(&artifact, b"execute")
}

// todo - code duplication ^^^^
/// Compiles many regions together to reduce external compiler and linker startup cost.
pub fn compile_jit_multi(
    regions: &[Nnil],
    output_dir: &Path,
    artifact_prefix: &str,
    opt_level: u8,
    cache_dir: Option<&Path>,
    raw_jit: bool,
) -> JitResult<Vec<(u64, CompiledJit)>> {
    // Do not start `rustc` when the caller has no work.
    if regions.is_empty() {
        return Ok(Vec::new());
    }

    let (rust_code, exports) = generate_bundle_rust_code(regions)?;
    let artifact = compile_generated_artifact(
        rust_code,
        output_dir,
        artifact_prefix,
        opt_level,
        cache_dir,
        raw_jit,
    )?;

    // Allocate the exact result capacity because each export gives one entry.
    let mut compiled = Vec::with_capacity(exports.len());

    for (entry_pc, export_name) in exports {
        let jit = compiled_symbol_from_artifact(&artifact, export_name.as_bytes())?;
        compiled.push((entry_pc, jit));
    }

    Ok(compiled)
}

fn compile_generated_artifact(
    rust_code: String,
    output_dir: &Path,
    artifact_prefix: &str,
    opt_level: u8,
    cache_dir: Option<&Path>,
    raw_jit: bool,
) -> JitResult<Arc<LoadedJitArtifact>> {
    // Raw and shared artifacts need different compilers, file formats, and owners.
    if raw_jit {
        return compile_raw_artifact(rust_code, output_dir, artifact_prefix, opt_level, cache_dir);
    }


    // Process-specific temporary names reduce collisions when emulator processes share a cache.
    // Nanoseconds add separation. The process ID separates processes with equal clocks.
    let timestamp = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
    let (source_path, library_path, compile_source, compile_library) =
        if let Some(cache_dir) = cache_dir {
            fs::create_dir_all(cache_dir)?;
            let key = cache_key(&rust_code, opt_level, false)?;
            let source_path = cache_dir.join(format!("jit-{key}.rs"));
            let library_path = cache_dir.join(format!("libjit-{key}.so"));

            // Require the exact source too, so a hash collision cannot load unrelated code.
            // A successful load also rejects corrupt or incompatible shared-library files.
            if library_path.is_file()
                && fs::read_to_string(&source_path).ok().as_deref() == Some(rust_code.as_str())
                && let Ok(library) = unsafe { Library::new(&library_path) }
            {
                return Ok(Arc::new(LoadedJitArtifact {
                    code: LoadedJitCode::Shared(library),
                    source_path,
                    library_path,
                    compiled_now: false,
                }));
            }

            // Write to private names first. A later rename publishes a complete cache entry.
            let unique = format!("{}-{timestamp}", std::process::id());
            (
                source_path,
                library_path,
                cache_dir.join(format!("jit-temp-{unique}.rs")),
                cache_dir.join(format!("libjit-temp-{unique}.so")),
            )
        } else {
            fs::create_dir_all(output_dir)?;
            let source_path = output_dir.join(format!("{artifact_prefix}-{timestamp}.rs"));
            let library_path = output_dir.join(format!("lib{artifact_prefix}-{timestamp}.so"));
            (
                source_path.clone(),
                library_path.clone(),
                source_path,
                library_path,
            )
        };

    // Keep the source on a non-cache run because it is the best compiler failure report.
    fs::write(&compile_source, rust_code)?;

    // One codegen unit improves cross-block optimization inside a generated bundle.
    let mut command = Command::new("rustc");
    // Edition 2021 accepts the generated unsafe syntax without the added edition-2024 rules.
    // A `cdylib` has a C-facing dynamic-library boundary and no Rust crate dependency ABI.
    // Panic abort prevents unwinding from crossing the JIT function-pointer boundary.
    // Source: https://doc.rust-lang.org/rustc/codegen-options/index.html
    command
        .args(["--edition=2021", "--crate-type", "cdylib", "-C"])
        .arg(format!("opt-level={opt_level}"))
        .args(["-C", "codegen-units=1", "-C", "panic=abort"]); // todo

    if cfg!(target_os = "macos") {
        // A no-std dynamic library can still need system linker support on macOS.
        command.args(["-C", "link-arg=-lSystem"]);
    }
    if cfg!(target_os = "linux") {
        // `-z defs` fails now if generated code has an unresolved symbol.
        // This check prevents a later failure when the emulator loads or calls the library.
        command.args(["-C", "link-arg=-Wl,-z,defs"]);
    }

    let status = command
        .arg("-o")
        .arg(&compile_library)
        .arg(&compile_source)
        .status()?;

    if !status.success() {
        if cache_dir.is_some() {
            let _ = fs::remove_file(&compile_source);
            let _ = fs::remove_file(&compile_library);
        }
        return Err(io::Error::other("rustc failed to generate JIT").into());
    }

    if cache_dir.is_some() {
        // Publish complete files only after rustc succeeds, so readers do not see partial cache data.
        // Rename also keeps the source and library names stable for the content key.
        fs::rename(&compile_source, &source_path)?;
        fs::rename(&compile_library, &library_path)?;
    }

    // Loading is unsafe because library initializers and exported code are outside Rust checks.
    let library = unsafe { Library::new(&library_path)? };
    Ok(Arc::new(LoadedJitArtifact {
        code: LoadedJitCode::Shared(library),
        source_path,
        library_path,
        compiled_now: true,
    }))
}

#[cfg(not(all(target_os = "linux", target_arch = "x86_64")))]
fn compile_raw_artifact(
    _rust_code: String,
    _output_dir: &Path,
    _artifact_prefix: &str,
    _opt_level: u8,
    _cache_dir: Option<&Path>,
) -> JitResult<Arc<LoadedJitArtifact>> {
    // Raw loading depends on Linux ELF64 and the x86-64 memory-map ABI.
    // A hard error prevents the x86-64 ELF parser and Linux flag values from use on another host.
    Err(io::Error::other("raw JIT nur auf Linux x86-64").into())
}

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn compile_raw_artifact(
    rust_code: String,
    output_dir: &Path,
    artifact_prefix: &str,
    opt_level: u8,
    cache_dir: Option<&Path>,
) -> JitResult<Arc<LoadedJitArtifact>> {

    // The raw path uses the same private-name rule as the shared-library cache.
    let timestamp = SystemTime::now().duration_since(UNIX_EPOCH)?.as_nanos();
    let (source_path, artifact_path, compile_source, compile_artifact) =
        if let Some(cache_dir) = cache_dir {
            fs::create_dir_all(cache_dir)?;
            let key = cache_key(&rust_code, opt_level, true)?;
            let source_path = cache_dir.join(format!("jit-{key}.rs"));
            let artifact_path = cache_dir.join(format!("jit-{key}.raw"));

            // Validate every cache layer before native bytes become executable.
            // The source check protects against a hash collision. The parser protects the layout.
            if artifact_path.is_file()
                && fs::read_to_string(&source_path).ok().as_deref() == Some(rust_code.as_str())
                && let Ok(bytes) = fs::read(&artifact_path)
                && let Ok((image, symbols)) = read_raw_cache(&bytes)
                && let Ok(code) = RawCode::new(&image, symbols)
            {
                return Ok(Arc::new(LoadedJitArtifact {
                    code: LoadedJitCode::Raw(code),
                    source_path,
                    library_path: artifact_path,
                    compiled_now: false,
                }));
            }

            // A process ID and a nanosecond time make concurrent temporary paths independent.
            let unique = format!("{}-{timestamp}", std::process::id());
            (
                source_path,
                artifact_path,
                cache_dir.join(format!("jit-temp-{unique}.rs")),
                cache_dir.join(format!("jit-temp-{unique}.raw")),
            )
        } else {
            fs::create_dir_all(output_dir)?;
            let source_path = output_dir.join(format!("{artifact_prefix}-{timestamp}.rs"));
            let artifact_path = output_dir.join(format!("{artifact_prefix}-{timestamp}.raw"));
            (
                source_path.clone(),
                artifact_path.clone(),
                source_path,
                artifact_path,
            )
        };

    // Keep intermediate names near the source to make failure artifacts easy to match.
    // Rust emits an object. GNU ld then applies its relocations and creates one ELF image.
    let object_path = compile_source.with_extension("o");
    let elf_path = compile_source.with_extension("elf");
    let script_path = compile_source.with_extension("ld");
    fs::write(&compile_source, rust_code)?;
    fs::write(&script_path, RAW_LINKER_SCRIPT)?;

    // Position-independent code (PIC) uses relative addressing so the flat image can run
    // at any address returned by `mmap`.
    // One codegen unit lets LLVM optimize calls between generated blocks.
    // `panic=abort` removes the need to unwind through manually loaded code.
    // Source: https://doc.rust-lang.org/rustc/codegen-options/index.html#relocation-model
    let rustc_status = Command::new("rustc")
        .args(["--edition=2021", "--crate-type", "lib", "--emit=obj", "-C"])
        .arg(format!("opt-level={opt_level}"))
        .args([
            "-C",
            "codegen-units=1",
            "-C",
            "panic=abort",
            "-C",
            "relocation-model=pic",
            "-o",
        ])
        .arg(&object_path)
        .arg(&compile_source)
        .status()?;


    if !rustc_status.success() {
        clean_raw_temps(
            &compile_source,
            &object_path,
            &elf_path,
            &script_path,
            cache_dir,
        );
        return Err(io::Error::other("rustc failed to generate raw JIT").into());
    }

    // Static, no-standard-library linking leaves no run-time library dependency in the flat image.
    // The custom script sets the section addresses that later become offsets from `mmap` base.
    // A build ID is not useful after this code removes the ELF metadata.
    let ld_status = Command::new("ld")
        .args(["-static", "-nostdlib", "--build-id=none", "-T"])
        .arg(&script_path)
        .arg("-o")
        .arg(&elf_path)
        .arg(&object_path)
        .status()?;

    if !ld_status.success() {
        clean_raw_temps(
            &compile_source,
            &object_path,
            &elf_path,
            &script_path,
            cache_dir,
        );
        return Err(io::Error::other("GNU ld failed to link raw JIT object").into());
    }

    // Remove ELF metadata because execution needs only load bytes and entry offsets.
    // Keep the compact symbol map because each exported region needs a callable offset.
    let (image, symbols) = parse_raw_elf(&fs::read(&elf_path)?)?;
    fs::write(&compile_artifact, write_raw_cache(&image, &symbols))?;
    let code = RawCode::new(&image, symbols)?;

    let _ = fs::remove_file(&object_path);
    let _ = fs::remove_file(&elf_path);
    let _ = fs::remove_file(&script_path);
    if cache_dir.is_some() {
        fs::rename(&compile_source, &source_path)?;
        fs::rename(&compile_artifact, &artifact_path)?;
    }

    Ok(Arc::new(LoadedJitArtifact {
        code: LoadedJitCode::Raw(code),
        source_path,
        library_path: artifact_path,
        compiled_now: true,
    }))
}

// todo - VON GAMOZO!
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
// Zero-based sections make ELF symbol values usable as offsets in the flat image.
// This loader selects a 16-byte x86-64 baseline. Input sections can require more alignment.
// The wildcards include the per-function and per-constant sections that rustc emits.
// Keep the global offset table (GOT) with data because PIC reads target addresses from it.
// The raw loader retains these bytes, then maps the complete final image as read-execute.
// Keep BSS in the memory image because it supplies zero-initialized static storage.
// Discard unwind and note data because this loader does not unwind or inspect metadata.
// Source: https://sourceware.org/binutils/docs/ld/SECTIONS.html
const RAW_LINKER_SCRIPT: &str = r#"
SECTIONS {
    . = 0;
    .text : ALIGN(16) { *(.text .text.*) }
    .rodata : ALIGN(16) { *(.rodata .rodata.*) }
    .data : ALIGN(16) { *(.data .data.*) *(.got .got.*) }
    .bss : ALIGN(16) { *(.bss .bss.*) *(COMMON) }
    /DISCARD/ : { *(.eh_frame .eh_frame.*) *(.comment) *(.note .note.*) }
}
"#;

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn clean_raw_temps(source: &Path, object: &Path, elf: &Path, script: &Path, cache: Option<&Path>) {
    // Preserve source outside the cache so a user can inspect a compile or link failure.
    if cache.is_some() {
        let _ = fs::remove_file(source);
    }
    let _ = fs::remove_file(object);
    let _ = fs::remove_file(elf);
    let _ = fs::remove_file(script);
}

// todo - crate von gamozo reinschauen / benutzen
fn cache_key(rust_code: &str, opt_level: u8, raw_jit: bool) -> JitResult<String> {
    // Change this value when a cache layout or an unlisted generation rule changes.
    // This text separates incompatible cache entries. It is not stored in the raw file format.
    const CACHE_VERSION: &str = "4-moin";
    // Flag text makes compiler-mode changes visible to the key without parsing commands.
    const SHARED_FLAGS: &str = "edition=2021;crate-type=cdylib;codegen-units=1;panic=abort;macos=-lSystem;linux=-Wl,-z,defs";
    const RAW_FLAGS: &str = "edition=2021;crate-type=lib;emit=obj;codegen-units=1;panic=abort;relocation-model=pic;ld=-static,-nostdlib,--build-id=none";

    let version = "rustcversiontodo";
    // let linker = if raw_jit {
    //     "ldversiontodo"
    // } else {
    //     String::new()
    // };

    // siehe notion
    // This is the 64-bit FNV-1a offset basis. It gives a fixed initial hash state.
    // FNV is small and stable. The exact source comparison supplies collision safety.
    // Source: https://www.rfc-editor.org/rfc/rfc9923.html
    let mut hash = 0xcbf29ce484222325u64;

    // Hash the source and the generation settings that this list records.
    // Toolchain versions are placeholders, so `CACHE_VERSION` must cover relevant tool changes.
    for part in [
        CACHE_VERSION,
        if raw_jit { RAW_FLAGS } else { SHARED_FLAGS },
        std::env::consts::ARCH,
        std::env::consts::OS,
        &version,
        //&linker,
        if raw_jit { "raw" } else { "shared" },
        &opt_level.to_string(),
        rust_code,
    ] {
        // `0xff` separates fields, so `["ab", "c"]` differs from `["a", "bc"]`.
        for byte in part.bytes().chain(std::iter::once(0xff)) {
            // FNV-1a XORs each input byte into the hash before it multiplies by the prime.
            hash ^= byte as u64;
            // This is the 64-bit FNV prime. Wrapping keeps the defined low 64 bits.
            hash = hash.wrapping_mul(0x100000001b3);
        }
    }
    // Sixteen hexadecimal digits preserve all 64 hash bits in a file-name-safe form.
    Ok(format!("{hash:016x}"))
}

// fn rustc_version() -> JitResult<String> {
//     static VERSION: OnceLock<Result<String, String>> = OnceLock::new();
//     let version = VERSION.get_or_init(|| {
//         let output = Command::new("rustc")
//             .arg("-Vv")
//             .output()
//             .map_err(|err| err.to_string())?;
//         if !output.status.success() {
//             return Err("rustc -Vv failed".to_string());
//         }
//         String::from_utf8(output.stdout).map_err(|err| err.to_string())
//     });

//     version.clone().map_err(|err| io::Error::other(err).into())
// }

// fn ld_version() -> JitResult<String> {
//     static VERSION: OnceLock<Result<String, String>> = OnceLock::new();
//     let version = VERSION.get_or_init(|| {
//         let output = Command::new("ld")
//             .arg("--version")
//             .output()
//             .map_err(|err| err.to_string())?;
//         if !output.status.success() {
//             return Err("ld --version failed".to_string());
//         }
//         String::from_utf8(output.stdout).map_err(|err| err.to_string())
//     });

//     version.clone().map_err(|err| io::Error::other(err).into())
// }

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
struct RawCode {
    // The base points to the start of one read-execute host mapping.
    base: *mut u8,
    // Keep the page-rounded size because `mprotect` and `munmap` use the full mapping.
    length: usize,
    // Symbol offsets are relative to `base`, not process virtual addresses.
    symbols: BTreeMap<Vec<u8>, usize>,
}

// todo - refactor
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
impl RawCode {
    fn new(image: &[u8], symbols: BTreeMap<Vec<u8>, usize>) -> JitResult<Self> {
        if image.is_empty() {
            return Err(io::Error::other("raw JIT image is empty").into());
        }
        // Linux protects whole pages. Round up so the final partial image page is mapped.
        let length = image.len().div_ceil(PAGE_SIZE) * PAGE_SIZE;
        // Map the image as read-write without execute permission, then change it to read-execute.
        // Thus, no page is writable and executable at the same time.
        // A null address asks Linux to select a page-aligned base.
        // A private anonymous map has no file, so its file descriptor is -1 and offset is 0.
        // Source: https://man7.org/linux/man-pages/man2/mmap.2.html
        let base = unsafe {
            mmap(
                std::ptr::null_mut(),
                length,
                PROT_READ | PROT_WRITE,
                MAP_PRIVATE | MAP_ANONYMOUS,
                -1,
                0,
            )
        };
        // Linux returns `(void *) -1`, not null, when `mmap` fails.
        if base as isize == -1 {
            return Err(io::Error::last_os_error().into());
        }
        // The allocation has `length` bytes and `length` is at least `image.len()`.
        // The new anonymous mapping cannot overlap the source Rust slice.
        unsafe {
            std::ptr::copy_nonoverlapping(image.as_ptr(), base.cast::<u8>(), image.len());
        }
        // Switch to read-execute after the copy to enforce write-xor-execute.
        // Page-aligned `base` and page-rounded `length` meet the `mprotect` contract.
        // Source: https://man7.org/linux/man-pages/man2/mprotect.2.html
        if unsafe { mprotect(base, length, PROT_READ | PROT_EXEC) } != 0 {
            let error = io::Error::last_os_error();
            unsafe {
                munmap(base, length);
            }
            return Err(error.into());
        }
        Ok(Self {
            base: base.cast(),
            length,
            symbols,
        })
    }

    fn entry(&self, name: &[u8]) -> JitResult<ExecuteFn> {
        // Resolve by bytes because ELF symbol names are byte strings, not Rust UTF-8 strings.
        let offset = self.symbols.get(name).ok_or_else(|| {
            io::Error::other(format!(
                "raw JIT has no exported symbol {}",
                String::from_utf8_lossy(name)
            ))
        })?;
        if *offset >= self.length {
            return Err(io::Error::other("WICHTIG - <raw JIT symbol is outside its image").into());
        }
        // The ELF parser accepts only exported `execute*` symbols inside the mapped image.
        // The generated `extern "C"` signature must match `ExecuteFn` for this cast to be valid.
        Ok(unsafe { std::mem::transmute::<*mut u8, ExecuteFn>(self.base.add(*offset)) })
    }
}

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
impl Drop for RawCode {
    fn drop(&mut self) {
        // Unmap only after the last `Arc<LoadedJitArtifact>` releases this code owner.
        unsafe {
            munmap(self.base.cast(), self.length);
        }
    }
}

// todo - cfg anders oder weg

// These numeric values come from the Linux x86-64 `sys/mman.h` ABI.
// Keep them behind the Linux x86-64 configuration because another OS can use other values.
// Protection bits 1, 2, and 4 permit read, write, and execute access.
// Mapping flag 2 selects a private map. Flag 0x20 selects memory without a backing file.
// Source: https://man7.org/linux/man-pages/man2/mmap.2.html
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
const PROT_READ: i32 = 1;
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
const PROT_WRITE: i32 = 2;
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
const PROT_EXEC: i32 = 4;
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
const MAP_PRIVATE: i32 = 2;
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
const MAP_ANONYMOUS: i32 = 0x20;

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
// Direct declarations avoid an additional Rust libc binding dependency in the host crate.
unsafe extern "C" {
    fn mmap(
        address: *mut std::ffi::c_void,
        length: usize,
        protection: i32,
        flags: i32,
        fd: i32,
        offset: i64,
    ) -> *mut std::ffi::c_void;
    fn mprotect(address: *mut std::ffi::c_void, length: usize, protection: i32) -> i32;
    fn munmap(address: *mut std::ffi::c_void, length: usize) -> i32;
}

// todo -quatsch
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn parse_raw_elf(bytes: &[u8]) -> JitResult<(Vec<u8>, BTreeMap<Vec<u8>, usize>)> {
    // Require the ELF class, byte order, and machine fields that this parser uses.
    // ELF puts its 16-byte identification array first. Bytes 4 and 5 select class and byte order.
    // The `e_machine` field is at byte 18. Value 62 identifies AMD x86-64.
    // Source: https://gabi.xinuos.com/elf/02-eheader.html
    if bytes
        .get(..16)
        .is_none_or(|ident| ident[..4] != *b"\x7fELF" || ident[4] != 2 || ident[5] != 1)
        || elf_u16(bytes, 18)? != 62
    {
        return Err(io::Error::other("raw JIT linker output is not x86-64 ELF64").into());
    }

    // In `Elf64_Ehdr`, offsets 32, 54, and 56 contain `e_phoff`, `e_phentsize`, and `e_phnum`.
    // Do not cast a Rust struct because input can be short or unaligned.
    let phoff = elf_u64(bytes, 32)? as usize;
    let phentsize = elf_u16(bytes, 54)? as usize;
    let phnum = elf_u16(bytes, 56)? as usize;

    // `Elf64_Phdr` is 56 bytes. Larger entries remain readable through their standard prefix.
    if phentsize < 56 {
        return Err(io::Error::other("raw JIT has invalid program headers").into());
    }

    // Flatten all load segments into one image because the raw loader maps one allocation.
    let mut loads = Vec::new();
    // Start minimum search at the largest address and maximum search at zero.
    // The first valid load segment then replaces both sentinel values.
    let mut image_start = u64::MAX;
    let mut image_end = 0u64;

    for index in 0..phnum {
        // Checked arithmetic prevents a hostile count or entry size from wrapping into the file.
        let offset = phoff
            .checked_add(
                index
                    .checked_mul(phentsize)
                    .ok_or_else(|| io::Error::other("ELF overflow"))?,
            )
            .ok_or_else(|| io::Error::other("ELF overflow"))?;
        // Program-header type 1 is `PT_LOAD`. This flat loader copies only these segments.
        // Source: https://gabi.xinuos.com/elf/07-pheader.html
        if elf_u32(bytes, offset)? != 1 {
            continue;
        }
        // These offsets select `p_offset`, `p_vaddr`, `p_filesz`, and `p_memsz` in `Elf64_Phdr`.
        let file_offset = elf_u64(bytes, offset + 8)?;
        let vaddr = elf_u64(bytes, offset + 16)?;
        let file_size = elf_u64(bytes, offset + 32)?;
        let memory_size = elf_u64(bytes, offset + 40)?;
        if file_size > memory_size {
            return Err(io::Error::other("raw JIT has an invalid load segment").into());
        }
        // Include memory size, not only file size. BSS occupies memory but has no file bytes.
        image_start = image_start.min(vaddr);
        image_end = image_end.max(
            vaddr
                .checked_add(memory_size)
                .ok_or_else(|| io::Error::other("raw JIT image overflow"))?,
        );
        loads.push((file_offset, vaddr, file_size));
    }

    if loads.is_empty() || image_end <= image_start {
        return Err(io::Error::other("raw JIT has no loadable code").into());
    }

    // A zero-filled vector gives the required initial value to BSS and segment gaps.
    let image_len = usize::try_from(image_end - image_start)?;
    let mut image = vec![0u8; image_len];

    for (file_offset, vaddr, file_size) in loads {
        // Convert and add with checks before each slice. This keeps all copies in both buffers.
        let source_start = usize::try_from(file_offset)?;
        let source_end = source_start
            .checked_add(usize::try_from(file_size)?)
            .ok_or_else(|| io::Error::other("raw JIT segment overflow"))?;
        // Subtract the lowest virtual address to turn an ELF address into a flat-image offset.
        let target_start = usize::try_from(vaddr - image_start)?;
        let target_end = target_start
            .checked_add(usize::try_from(file_size)?)
            .ok_or_else(|| io::Error::other("raw JIT segment overflow"))?;
        image
            .get_mut(target_start..target_end)
            .ok_or_else(|| io::Error::other("raw JIT segment is outside image???"))?
            .copy_from_slice(
                bytes
                    .get(source_start..source_end)
                    .ok_or_else(|| io::Error::other("truncated raw JIT segment"))?,
            );
    }

    // dbg!(image);

    // Section headers are kept only long enough to locate exported execute symbols.
    // Program headers define load bytes. Section headers define the symbol-table metadata.
    // The fields at 40, 58, and 60 are `e_shoff`, `e_shentsize`, and `e_shnum`.
    let shoff = elf_u64(bytes, 40)? as usize;
    let shentsize = elf_u16(bytes, 58)? as usize;
    let shnum = elf_u16(bytes, 60)? as usize;

    // `Elf64_Shdr` is 64 bytes. Accept a larger compatible entry through its standard prefix.
    if shentsize < 64 {
        return Err(io::Error::other("raw JIT has invalid section headers").into());
    }
    let mut symbols = BTreeMap::new();
    for index in 0..shnum {
        // Use the file entry size because ELF records it and can extend the standard structure.
        let section = shoff
            .checked_add(
                index
                    .checked_mul(shentsize)
                    .ok_or_else(|| io::Error::other("ELF overflow??"))?,
            )
            .ok_or_else(|| io::Error::other("ELF overflow??"))?;
        // Section type 2 is `SHT_SYMTAB`, the full link-time symbol table.
        // Source: https://gabi.xinuos.com/elf/03-sheader.html
        if elf_u32(bytes, section + 4)? != 2 {
            continue;
        }
        // These fields are `sh_offset`, `sh_size`, `sh_link`, and `sh_entsize`.
        let symbol_offset = elf_u64(bytes, section + 24)? as usize;
        let symbol_size = elf_u64(bytes, section + 32)? as usize;
        let string_index = elf_u32(bytes, section + 40)? as usize;
        let entry_size = elf_u64(bytes, section + 56)? as usize;

        // An `Elf64_Sym` needs 24 bytes. `sh_link` must name an existing string-table section.
        if entry_size < 24 || string_index >= shnum {
            return Err(io::Error::other("raw JIT has invalid symbols").into());
        }
        // Follow the symbol section's `sh_link` instead of assuming a fixed string-table order.
        let strings = shoff + string_index * shentsize;
        let strings_offset = elf_u64(bytes, strings + 24)? as usize;
        let strings_size = elf_u64(bytes, strings + 32)? as usize;

        let string_data = bytes
            .get(strings_offset..strings_offset + strings_size)
            .ok_or_else(|| io::Error::other("truncated raw JIT string table"))?;

        for symbol in (symbol_offset..symbol_offset + symbol_size).step_by(entry_size) {
            // In `Elf64_Sym`, name, info, section index, and value start at 0, 4, 6, and 8.
            // Source: https://gabi.xinuos.com/elf/05-symtab.html
            let name_offset = elf_u32(bytes, symbol)? as usize;
            let info = *bytes
                .get(symbol + 4)
                .ok_or_else(|| io::Error::other("truncated raw JIT symbol"))?;
            let section_index = elf_u16(bytes, symbol + 6)?;

            // Section index 0 means undefined. The high four `st_info` bits hold the binding.
            // Binding 0 is local. Raw entries must be defined and visible outside their block.
            if section_index == 0 || info >> 4 == 0 || name_offset >= string_data.len() {
                continue;
            }

            // ELF names end at the first zero byte. Reject a name that runs past the table.
            let name_end = string_data[name_offset..]
                .iter()
                .position(|byte| *byte == 0)
                .map(|length| name_offset + length)
                .ok_or_else(|| io::Error::other("invalid raw JIT symbol name"))?;
            let name = &string_data[name_offset..name_end];
            // Ignore helper symbols. The host calls only the generated `execute*` ABI entries.
            if !name.starts_with(b"execute") {
                continue;
            }
            let value = elf_u64(bytes, symbol + 8)?;
            // The zero-based linker script makes `st_value` an image-relative address in normal
            // output. Subtract `image_start` as required by the general ELF segment layout.
            let offset = usize::try_from(
                value
                    .checked_sub(image_start)
                    .ok_or_else(|| io::Error::other("raw JIT symbol is outside image"))?,
            )?;
            if offset >= image.len() {
                return Err(io::Error::other("raw JIT symbol is outside image??").into());
            }
            symbols.insert(name.to_vec(), offset);
        }
    }
    if symbols.is_empty() {
        return Err(io::Error::other("raw JIT has no exported entry symbols").into());
    }

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

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn write_raw_cache(image: &[u8], symbols: &BTreeMap<Vec<u8>, usize>) -> Vec<u8> {
    let mut bytes = Vec::new();

    // A versioned header lets the reader reject old layouts before it parses lengths.
    // The final `3` is the layout revision. A format change must use a new magic value.
    // Layout: 8-byte magic, u64 image length, u32 symbol count, symbol records, image bytes.
    // One symbol record has a u16 name length, name bytes, and a u64 image offset.
    // Fixed integers use little-endian order so the byte file does not depend on Rust layout.
    bytes.extend_from_slice(b"REMURAW3");
    bytes.extend_from_slice(&(image.len() as u64).to_le_bytes());
    bytes.extend_from_slice(&(symbols.len() as u32).to_le_bytes());
    for (name, offset) in symbols {
        bytes.extend_from_slice(&(name.len() as u16).to_le_bytes());
        bytes.extend_from_slice(name);
        bytes.extend_from_slice(&(*offset as u64).to_le_bytes());
    }
    bytes.extend_from_slice(image);
    bytes
}

// todo - viel zu kompliziert
#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn read_raw_cache(bytes: &[u8]) -> JitResult<(Vec<u8>, BTreeMap<Vec<u8>, usize>)> {
    // Eight bytes give an exact format tag without a terminator or an alignment assumption.
    if bytes.get(..8) != Some(b"REMURAW3") {
        return Err(io::Error::other("invalid raw JIT cache header").into());
    }
    // The fixed header ends at byte 20: 8 magic + 8 image length + 4 symbol count.
    let image_len = usize::try_from(elf_u64(bytes, 8)?)?;
    let symbol_count = elf_u32(bytes, 16)? as usize;
    let mut cursor = 20usize;
    let mut symbols = BTreeMap::new();

    // Validate offsets while parsing so later entry lookup can trust the cache data.
    for _ in 0..symbol_count {
        // Advance by two because the record stores the name length as a little-endian `u16`.
        let name_len = elf_u16(bytes, cursor)? as usize;
        cursor += 2;
        let name = bytes
            .get(cursor..cursor + name_len)
            .ok_or_else(|| io::Error::other("truncated raw JIT cache"))?
            .to_vec();
        // The name has no terminator because its preceding length gives the exact byte count.
        cursor += name_len;
        let offset = usize::try_from(elf_u64(bytes, cursor)?)?;
        // Advance by eight because every cached image offset is a `u64`.
        cursor += 8;
        if offset >= image_len {
            return Err(io::Error::other("invalid raw JIT cache symbol").into());
        }
        symbols.insert(name, offset);
    }

    let image = bytes
        .get(cursor..cursor + image_len)
        .ok_or_else(|| io::Error::other("truncated raw JIT cache image"))?
        .to_vec();
    
    // Reject trailing bytes, a short image, and a cache with no callable entry.
    if cursor + image_len != bytes.len() || symbols.is_empty() {
        return Err(io::Error::other("invalid raw JIT cache size").into());
    }
    Ok((image, symbols))
}

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn elf_u16(bytes: &[u8], offset: usize) -> JitResult<u16> {
    // The caller must ensure that `offset + 2` fits in usize. `get` then checks the file
    // range before little-endian decoding.
    Ok(u16::from_le_bytes(
        bytes
            .get(offset..offset + 2)
            .ok_or_else(|| io::Error::other("truncated ELF"))?
            .try_into()?,
    ))
}

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn elf_u32(bytes: &[u8], offset: usize) -> JitResult<u32> {
    // Do not dereference a cast pointer because an ELF field in a byte slice can be unaligned.
    // The caller must ensure that `offset + 4` fits in usize. `get` then checks the file range.
    Ok(u32::from_le_bytes(
        bytes
            .get(offset..offset + 4)
            .ok_or_else(|| io::Error::other("truncated ELF"))?
            .try_into()?,
    ))
}

#[cfg(all(target_os = "linux", target_arch = "x86_64"))]
fn elf_u64(bytes: &[u8], offset: usize) -> JitResult<u64> {
    // `from_le_bytes` gives the same value on little-endian and big-endian Rust hosts.
    // The caller must ensure that `offset + 8` fits in usize. `get` then checks the file range.
    Ok(u64::from_le_bytes(
        bytes
            .get(offset..offset + 8)
            .ok_or_else(|| io::Error::other("truncated ELF"))?
            .try_into()?,
    ))
}

fn compiled_symbol_from_artifact(
    artifact: &Arc<LoadedJitArtifact>,
    symbol_name: &[u8],
) -> JitResult<CompiledJit> {
    // Both owners return the same C-ABI function type, so callers do not depend on load mode.
    let execute = match &artifact.code {
        // Symbol lookup is unsafe because a file does not encode the Rust function type.
        LoadedJitCode::Shared(library) => unsafe { *library.get::<ExecuteFn>(symbol_name)? },
        #[cfg(all(target_os = "linux", target_arch = "x86_64"))]
        LoadedJitCode::Raw(code) => code.entry(symbol_name)?,
    };

    // Clone the owner because the copied function pointer has no lifetime information.
    Ok(CompiledJit {
        artifact: Arc::clone(artifact),
        execute,
    })
}

fn generate_rust_code(nnil: &Nnil) -> JitResult<String> {
    // The exported region name includes its guest entry address for useful diagnostics.
    let entry = nnil
        .entrypoint()
        .ok_or_else(|| io::Error::other("NNIL ist leer"))?;

    RustEmitter::new(nnil, &format!("region_{:x}", entry.0))?.generate()
}

fn generate_bundle_rust_code(regions: &[Nnil]) -> JitResult<(String, Vec<(u64, String)>)> {
    // Emit one support template per Rust crate, not one copy for every guest region.
    let mut code = genjittemplate();
    let mut exports = Vec::with_capacity(regions.len());
    let mut emitters = Vec::with_capacity(regions.len());

    for (index, region) in regions.iter().enumerate() {
        let entry = region
            .entrypoint()
            .ok_or_else(|| io::Error::other("NNIL ist leer"))?;

        // The guest address gives the host a stable name to resolve from the native artifact.
        let export_name = format!("execute_entry_{:x}", entry.0);
        // The index also keeps names unique if input regions have an equal entry address.
        let prefix = format!("bundle_{index}_{:x}", entry.0);

        emitters.push(RustEmitter::new(region, &prefix)?);
        exports.push((entry.0, export_name));
    }

    // Share all block names so direct branches can tail-call across region boundaries.
    // `BTreeMap` also puts the addresses in stable order for reproducible generated source.
    let linked_blocks = emitters
        .iter()
        .flat_map(|emitter| {
            emitter
                .block_names
                .iter()
                .map(|(&address, name)| (address, name.clone()))
        })
        .collect::<BTreeMap<_, _>>();

    for (emitter, (_, export_name)) in emitters.iter().zip(&exports) {
        emitter.emit_region(export_name, &mut code, &linked_blocks)?;
    }

    Ok((code, exports))
}

fn genjittemplate() -> String {
    // This function builds a self-contained Rust crate around the translated guest blocks.
    // The host and this crate compile separately. They communicate only through the C ABI
    // layouts below and through raw pointers. Keep each mirrored field in the same order.
    // Rust layout source: https://doc.rust-lang.org/reference/type-layout.html#the-c-representation
    let mut code = String::new();

    // `no_std` avoids runtime dependencies and keeps both loading modes independent.
    // It also makes raw static linking possible without a second Rust standard-library runtime.
    // Source: https://doc.rust-lang.org/std/attribute.no_std.html
    code.push_str("#![no_std]\n");
    // `become` guarantees a tail call. Repeated guest blocks then reuse one host stack frame.
    // The feature is nightly-only, so the crate must enable it and allow its incomplete status.
    // Source: https://doc.rust-lang.org/std/keyword.become.html
    code.push_str("#![feature(explicit_tail_calls)]\n");
    code.push_str("#![allow(incomplete_features)]\n");
    // NNIL-derived names and unused helper variants are normal in machine-generated source.
    // Disable these style warnings so compiler output reports real generation failures.
    code.push_str("#![allow(non_snake_case)]\n");
    code.push_str("#![allow(dead_code)]\n");
    code.push_str("#![allow(unused_variables)]\n");
    // Atomic pause reads permit another host thread to request a stop without a data race.
    code.push_str("use core::sync::atomic::{AtomicBool, Ordering};\n\n");
    // A no-std final library must supply one panic handler.
    // The handler traps instead of unwinding across manually loaded JIT frames.
    // Source: https://doc.rust-lang.org/reference/panic.html#the-panic_handler-attribute
    code.push_str("#[panic_handler]\n");
    code.push_str("fn panic(_: &core::panic::PanicInfo) -> ! {\n");
    // `ud2` is the x86-64 defined invalid instruction. It stops an unexpected panic at once.
    code.push_str("    #[cfg(target_arch = \"x86_64\")]\n");
    code.push_str("    unsafe { core::arch::asm!(\"ud2\", options(noreturn)); }\n");
    // `brk #0` gives AArch64 the same deliberate trap behavior. Zero is only its immediate tag.
    code.push_str("    #[cfg(target_arch = \"aarch64\")]\n");
    code.push_str("    unsafe { core::arch::asm!(\"brk #0\", options(noreturn)); }\n");
    // The loop is a portable non-return fallback for another target architecture.
    code.push_str("    #[allow(unreachable_code)] loop { core::hint::spin_loop(); }\n");
    code.push_str("}\n\n");
    // Some Linux object links request the Rust personality symbol even with abort behavior.
    // Export a no-op definition because generated code never performs Rust unwinding.
    code.push_str("#[cfg(target_os = \"linux\")]\n");
    code.push_str("#[no_mangle]\n");
    code.push_str("pub extern \"C\" fn rust_eh_personality() {}\n\n");

    // A one-byte representation matches the host mirror and makes the fault field size explicit.
    code.push_str("#[repr(u8)]\n");
    code.push_str("#[derive(Clone, Copy, Debug, PartialEq, Eq)]\n");
    code.push_str("pub enum AccessKind {\n");
    // Zero means no fault. Values 1, 2, and 3 identify the operation for diagnostics.
    // These values are enum tags. They are not the read, write, and execute permission bits.
    code.push_str("    None = 0,\n");
    code.push_str("    Read = 1,\n");
    code.push_str("    Write = 2,\n");
    code.push_str("    Execute = 3,\n");
    code.push_str("}\n\n");

    // C representation fixes discriminant and field ABI rules across the two Rust crates.
    code.push_str("#[repr(C)]\n");
    code.push_str("#[derive(Clone, Copy, Debug, PartialEq, Eq)]\n");
    // Implicit discriminants start at zero and increase by one. Keep this exact order equal
    // to the host enum because each ordinal crosses the ABI.
    code.push_str("pub enum ExitReason {\n");
    code.push_str("    None,\n");
    code.push_str("    IndirectBranch,\n");
    code.push_str("    ReadFault,\n");
    code.push_str("    WriteFault,\n");
    code.push_str("    ExecFault,\n");
    code.push_str("    UnhandledHostCall,\n");
    code.push_str("    GuestExit,\n");
    code.push_str("    Syscall,\n");
    code.push_str("    Sysbreak,\n");
    code.push_str("    Breakpoint,\n");
    code.push_str("    Paused,\n");
    code.push_str("    BlockLimit,\n");
    code.push_str("}\n\n");

    code.push_str("#[repr(C)]\n");
    // Debug controls stay behind one nullable pointer, so normal runs can omit their storage.
    code.push_str("pub struct GuestControl {\n");
    // `pause` points into an `Arc<AtomicBool>` that the host owns for the full run.
    code.push_str("    pub pause: *const AtomicBool,\n");
    // Fixed arrays keep the cross-crate layout simple. Counts select the initialized prefix.
    writeln!(code, "    pub breakpoints: [u64; {DEBUG_SLOTS}],").unwrap();
    code.push_str("    pub breakpoint_count: usize,\n");
    // `u64::MAX` is the no-skip sentinel because it cannot be a normal mapped guest block here.
    // It is odd, but supported RISC-V instruction addresses are at least two-byte aligned.
    code.push_str("    pub skip_breakpoint: u64,\n");
    // A separate byte enables the limit, so zero blocks can mean an immediate stop.
    code.push_str("    pub blocks_left: u64,\n");
    code.push_str("    pub limited: u8,\n");
    // The fixed trace array is a ring. It records recent PCs without allocation in JIT code.
    writeln!(code, "    pub trace: [u64; {DEBUG_SLOTS}],").unwrap();
    code.push_str("    pub trace_pos: usize,\n");
    code.push_str("}\n\n");

    code.push_str("#[repr(C)]\n");
    // Each entry maps one aligned guest page base to one stable host allocation.
    code.push_str("pub struct GuestPageAbi {\n");
    code.push_str("    pub guest_base: u64,\n");
    code.push_str("    pub perms: u8,\n");
    // Seven bytes follow the one-byte permission field, so the pointer starts at an 8-byte slot.
    // Explicit padding makes this mirrored ABI intent visible in both crates.
    code.push_str("    pub _padding: [u8; 7],\n");
    code.push_str("    pub data: *mut u8,\n");
    code.push_str("}\n\n");

    code.push_str("#[repr(C)]\n");
    // A translation entry caches a page lookup and its permission result.
    code.push_str("pub struct GuestTranslationAbi {\n");
    code.push_str("    pub guest_base: u64,\n");
    // Keep the page index so a write can add that page to the dirty list without a new search.
    code.push_str("    pub page_index: usize,\n");
    code.push_str("    pub perms: u8,\n");
    // Use the same seven-byte gap as `GuestPageAbi` before its 8-byte-aligned pointer.
    code.push_str("    pub _padding: [u8; 7],\n");
    code.push_str("    pub data: *mut u8,\n");
    code.push_str("}\n\n");

    code.push_str("#[repr(C)]\n");
    // Raw pointers and lengths replace `Vec` because a Rust container has no stable C ABI.
    code.push_str("pub struct GuestMemoryAbi {\n");
    code.push_str("    pub pages: *const GuestPageAbi,\n");
    code.push_str("    pub page_count: usize,\n");
    // The host publishes its page size for ABI users. Generated masks use the same constant.
    code.push_str("    pub page_size: usize,\n");
    // Sixteen entries form a small direct-mapped cache. Later code uses `& 15` as modulo 16.
    // This works because 16 is a power of two and 15 has its low four bits set.
    code.push_str("    pub translations: [GuestTranslationAbi; 16],\n");
    // The list lets restore visit only changed pages. The bitmap records each page once.
    code.push_str("    pub dirty_pages: *mut usize,\n");
    code.push_str("    pub dirty_count: usize,\n");
    code.push_str("    pub dirty_bitmap: *mut u64,\n");
    code.push_str("}\n\n");

    // `extern "C"` fixes the call convention. `unsafe` tells callers to validate the state pointer.
    code.push_str(
        "pub type ExecuteFn = unsafe extern \"C\" fn(*mut GuestState) -> ExitReason;\n\n",
    );
    code.push_str("#[repr(C)]\n");
    // The host sorts these pairs by guest PC before generated binary search uses them.
    code.push_str("pub struct JitEntryAbi {\n");
    code.push_str("    pub guest_pc: u64,\n");
    code.push_str("    pub execute: ExecuteFn,\n");
    code.push_str("}\n\n");

    code.push_str("#[repr(C)]\n");
    // This structure is the full data boundary between safe host ownership and generated code.
    code.push_str("pub struct GuestState {\n");
    writeln!(code, "    pub exit_reason: ExitReason,").unwrap();
    writeln!(code, "    pub pc: u64,").unwrap();
    // Every register uses 64 storage bits. Floating registers keep their IEEE bit patterns here.
    writeln!(code, "    pub regs: [u64; {}],", GUEST_REG_COUNT).unwrap();
    // NNIL temporaries keep values between emitted expressions and guest instructions.
    writeln!(code, "    pub tmps: [u64; {}],", GUEST_TMP_COUNT).unwrap();
    code.push_str("    pub memory: *mut GuestMemoryAbi,\n");
    // Fault fields let the host handle an access after generated code returns.
    code.push_str("    pub fault_addr: u64,\n");
    code.push_str("    pub fault_access: AccessKind,\n");
    code.push_str("    pub control: *mut GuestControl,\n");
    // The table permits an indirect guest branch to enter any already compiled region.
    code.push_str("    pub jit_entries: *const JitEntryAbi,\n");
    code.push_str("    pub jit_entry_count: usize,\n");
    code.push_str("}\n\n");

    // Dispatch uses sorted entries because indirect targets can enter any compiled region.
    // Inline this hot bridge so direct block-to-dispatch transfers have little host overhead.
    code.push_str("#[inline(always)]\n");
    code.push_str("unsafe extern \"C\" fn dispatch_jit(state: *mut GuestState) -> ExitReason {\n");
    code.push_str("    let pc = (*state).pc;\n");
    // Use a lower-bound binary search. It needs logarithmic checks instead of a full table scan.
    code.push_str("    let mut left = 0usize;\n");
    code.push_str("    let mut right = (*state).jit_entry_count;\n");
    code.push_str("    while left < right {\n");
    // Subtract before division so `left + right` cannot overflow `usize`.
    code.push_str("        let mid = left + (right - left) / 2;\n");
    // Pointer addition is valid because `mid` is below `jit_entry_count` in this loop.
    code.push_str("        let entry = &*((*state).jit_entries.add(mid));\n");
    // If `mid` is too small, add one because that entry cannot be the answer.
    code.push_str("        if entry.guest_pc < pc { left = mid + 1; } else { right = mid; }\n");
    code.push_str("    }\n");
    code.push_str("    if left < (*state).jit_entry_count {\n");
    code.push_str("        let entry = &*((*state).jit_entries.add(left));\n");
    // Tail-call the selected region so an indirect-branch loop cannot grow the host stack.
    code.push_str("        if entry.guest_pc == pc { become (entry.execute)(state); }\n");
    code.push_str("    }\n");
    code.push_str("    (*state).exit_reason = ExitReason::IndirectBranch;\n");
    code.push_str("    ExitReason::IndirectBranch\n");
    code.push_str("}\n\n");

    // todo -- hier meckert rustc edition 2024 wegen unsafe
    // Return zero for x0 so reads follow the RISC-V rule without special register state.
    // RISC-V requires x0 to contain zero even if previous generated code tried to write it.
    // Source: https://docs.riscv.org/reference/isa/unpriv/rv32.html
    code.push_str("#[inline(always)]\n");
    code.push_str("unsafe fn read_reg(state: *mut GuestState, reg: usize) -> u64 {\n");
    writeln!(
        code,
        "unsafe {{ if reg == {} {{ 0 }} else {{ *(*state).regs.get_unchecked(reg) }} }}",
        INTEGER_ZERO_REG
    )
    .unwrap();
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    code.push_str(
        "unsafe fn control_block(state: *mut GuestState, pc: u64) -> Option<ExitReason> {\n",
    );
    // A null pointer disables all debug work for a host that does not supply this optional ABI.
    code.push_str("    let control = (*state).control;\n");
    code.push_str("    if control.is_null() { return None; }\n");
    // Relaxed order is sufficient because the atomic value is only a stop request.
    // It does not publish other data that this thread must read after the flag.
    code.push_str("    if !(*control).pause.is_null() && (*(*control).pause).load(Ordering::Relaxed) { return Some(ExitReason::Paused); }\n");
    code.push_str("    if (*control).skip_breakpoint == pc {\n");
    // Reset to the all-ones sentinel after one skip, so the breakpoint stops the next visit.
    code.push_str("        (*control).skip_breakpoint = u64::MAX;\n");
    // The host keeps the initialized breakpoint prefix sorted for this binary search.
    code.push_str("    } else if core::slice::from_raw_parts((*control).breakpoints.as_ptr(), (*control).breakpoint_count).binary_search(&pc).is_ok() {\n");
    code.push_str("        return Some(ExitReason::Breakpoint);\n");
    code.push_str("    }\n");
    // Any nonzero byte enables the block counter. A byte has a simple stable ABI layout.
    code.push_str("    if (*control).limited != 0 {\n");
    code.push_str(
        "        if (*control).blocks_left == 0 { return Some(ExitReason::BlockLimit); }\n",
    );
    // Check before subtraction, so an exhausted unsigned counter cannot wrap to `u64::MAX`.
    code.push_str("        (*control).blocks_left -= 1;\n");
    code.push_str("    }\n");
    writeln!(
        code,
        "    let trace_index = (*control).trace_pos % {DEBUG_SLOTS};"
    )
    .unwrap();
    // Modulo the fixed slot count turns an increasing position into a ring-buffer index.
    code.push_str("    *(*control).trace.get_unchecked_mut(trace_index) = pc;\n");
    // Wrapping keeps trace collection active after `usize::MAX` instead of a debug panic.
    code.push_str("    (*control).trace_pos = (*control).trace_pos.wrapping_add(1);\n");
    code.push_str("    None\n");
    code.push_str("}\n\n");

    // todo -- hier meckert rustc edition 2024 wegen unsafe
    // Ignore writes to x0 because the ISA makes that register read-only zero.
    code.push_str("#[inline(always)]\n");
    code.push_str("unsafe fn write_reg(state: *mut GuestState, reg: usize, value: u64) {\n");
    writeln!(
        code,
        "unsafe {{ if reg != {} {{ *(*state).regs.get_unchecked_mut(reg) = value; }} }}",
        INTEGER_ZERO_REG
    )
    .unwrap();
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    code.push_str("unsafe fn set_fault(state: *mut GuestState, addr: u64, access: AccessKind) {\n");
    // Store both values before exit, so the host can report the exact operation and address.
    code.push_str("    (*state).fault_addr = addr;\n");
    code.push_str("    (*state).fault_access = access;\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Keep only `bytes * 8` low bits because one byte contains eight bits.
    // `(1 << width) - 1` makes `width` low ones. The 8-byte case avoids a shift by 64.
    writeln!(code, "fn zext(value: u64, bytes: usize) -> u64 {{").unwrap();
    code.push_str("    if bytes >= 8 { value } else { value & ((1u64 << (bytes * 8)) - 1) }\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Move the selected sign bit to bit 63, use signed right shift to copy it, then move back.
    // The 8-byte case already fills all 64 bits and avoids a shift by 64.
    code.push_str("fn sext(value: u64, bytes: usize) -> u64 {\n");
    code.push_str("    if bytes >= 8 {\n");
    code.push_str("        value\n");
    code.push_str("    } else {\n");
    // Subtract the source width from 64 to place its top bit at the host sign position.
    code.push_str("        let shift = 64 - (bytes * 8) as u32;\n");
    code.push_str("        (((value << shift) as i64) >> shift) as u64\n");
    code.push_str("    }\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Cast only for the comparison. Convert the Boolean result to the ISA value 0 or 1.
    code.push_str(
        "fn slt_signed(lhs: u64, rhs: u64) -> u64 { ((lhs as i64) < (rhs as i64)) as u64 }\n\n",
    );
    code.push_str("#[inline(always)]\n");
    code.push_str("fn slt_unsigned(lhs: u64, rhs: u64) -> u64 { (lhs < rhs) as u64 }\n\n");

    code.push_str("#[inline(always)]\n");
    // RISC-V defines results for divide-by-zero and the one signed overflow case.
    // Rust division can panic for these cases, so select the ISA results first.
    // All ones is the quotient for zero. MIN / -1 returns MIN instead of overflowing.
    // Source: https://docs.riscv.org/reference/isa/unpriv/m-st-ext.html
    code.push_str("fn div_signed(lhs: u64, rhs: u64) -> u64 {\n");
    code.push_str("    let lhs = lhs as i64;\n");
    code.push_str("    let rhs = rhs as i64;\n");
    code.push_str("    if rhs == 0 {\n");
    // `u64::MAX` has all 64 bits set. As `i64`, the same bits also represent -1.
    code.push_str("        u64::MAX\n");
    code.push_str("    } else if lhs == i64::MIN && rhs == -1 {\n");
    code.push_str("        lhs as u64\n");
    code.push_str("    } else {\n");
    code.push_str("        lhs.wrapping_div(rhs) as u64\n");
    code.push_str("    }\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Unsigned division has no MIN / -1 overflow case, but zero still returns all ones.
    code.push_str("fn div_unsigned(lhs: u64, rhs: u64) -> u64 { if rhs == 0 { u64::MAX } else { lhs / rhs } }\n\n");
    code.push_str("#[inline(always)]\n");
    // RISC-V returns the dividend as the remainder for a zero divisor.
    // It returns zero for MIN % -1 because the matching quotient is MIN.
    code.push_str("fn rem_signed(lhs: u64, rhs: u64) -> u64 {\n");
    code.push_str("    let lhs = lhs as i64;\n");
    code.push_str("    let rhs = rhs as i64;\n");
    code.push_str("    if rhs == 0 {\n");
    code.push_str("        lhs as u64\n");
    code.push_str("    } else if lhs == i64::MIN && rhs == -1 {\n");
    code.push_str("        0\n");
    code.push_str("    } else {\n");
    code.push_str("        lhs.wrapping_rem(rhs) as u64\n");
    code.push_str("    }\n");
    code.push_str("}\n\n");
    code.push_str("#[inline(always)]\n");
    // The unsigned zero-divisor remainder also equals the unchanged dividend.
    code.push_str(
        "fn rem_unsigned(lhs: u64, rhs: u64) -> u64 { if rhs == 0 { lhs } else { lhs % rhs } }\n\n",
    );

    code.push_str("#[inline(always)]\n");
    // Widen both signed operands to 128 bits, multiply without losing bits, and shift by 64.
    // The shift drops the low half and returns bits 127 through 64 of the full product.
    // Source: https://docs.riscv.org/reference/isa/unpriv/m-st-ext.html
    code.push_str("fn mulh_signed_signed(lhs: u64, rhs: u64) -> u64 { (((lhs as i64 as i128) * (rhs as i64 as i128)) >> 64) as u64 }\n\n");
    code.push_str("#[inline(always)]\n");
    // Sign-extend only the first operand for the signed-by-unsigned MULHSU form.
    code.push_str("fn mulh_signed_unsigned(lhs: u64, rhs: u64) -> u64 { (((lhs as i64 as i128) * (rhs as u64 as i128)) >> 64) as u64 }\n\n");
    code.push_str("#[inline(always)]\n");
    // Use `u128` when both operands are unsigned, then select the same high 64 bits.
    code.push_str("fn mulh_unsigned_unsigned(lhs: u64, rhs: u64) -> u64 { ((lhs as u128 * rhs as u128) >> 64) as u64 }\n\n");

    code.push_str("#[inline(always)]\n");
    // One 64-bit bitmap word tracks 64 guest pages, one page per bit.
    code.push_str("unsafe fn mark_dirty(memory: *mut GuestMemoryAbi, page_index: usize) {\n");
    // Integer division by 64 selects the bitmap word that owns this page index.
    code.push_str("    let word = (*memory).dirty_bitmap.add(page_index / 64);\n");
    // Remainder modulo 64 selects the page's bit in that word.
    code.push_str("    let mask = 1u64 << (page_index % 64);\n");
    // Add a page only when its bit was clear. This keeps the dirty list free of duplicates.
    code.push_str("    if *word & mask == 0 {\n");
    code.push_str("        *word |= mask;\n");
    // The host reserves one list slot per page, so each first dirty mark has space here.
    code.push_str("        *(*memory).dirty_pages.add((*memory).dirty_count) = page_index;\n");
    code.push_str("        (*memory).dirty_count += 1;\n");
    code.push_str("    }\n");
    code.push_str("}\n\n");

    // Put the binary search on a cold path because the direct-mapped cache handles repeat access.
    // Internal permissions use separate bits: read is 1, write is 2, and execute is 4.
    // `(perms & required) == required` accepts a page only when it has every requested bit.
    code.push_str("#[cold]\n");
    code.push_str("#[inline(never)]\n");
    code.push_str("unsafe fn translate_slow(memory: *mut GuestMemoryAbi, page_base: u64, offset: usize, required_perm: u8) -> *mut u8 {\n");
    // The host keeps page entries sorted by guest base, so lower-bound search can find one page.
    code.push_str("    let mut left = 0usize;\n");
    code.push_str("    let mut right = (*memory).page_count;\n");
    code.push_str("    while left < right {\n");
    // This midpoint form cannot overflow by adding two large indexes first.
    code.push_str("        let mid = left + (right - left) / 2;\n");
    // `mid` stays below `page_count`, which makes this raw pointer addition in bounds.
    // Pointer safety source: https://doc.rust-lang.org/core/primitive.pointer.html#method.add
    code.push_str("        let page = &*((*memory).pages.add(mid));\n");
    code.push_str(
        "        if page.guest_base < page_base { left = mid + 1; } else { right = mid; }\n",
    );
    code.push_str("    }\n");
    code.push_str("    if left < (*memory).page_count {\n");
    code.push_str("        let page = &*((*memory).pages.add(left));\n");
    code.push_str("        if page.guest_base == page_base && (page.perms & required_perm) == required_perm {\n");
    // Divide by 4096 to get the guest page number. A 4096-byte page has 2^12 bytes,
    // so this removes the low 12 offset bits. `& 15` then selects page-number bits 0..3.
    // The result is page number modulo 16 because the translation array has 16 entries.
    writeln!(
        code,
        "            let slot = ((page_base / {}u64) as usize) & 15;",
        PAGE_SIZE
    )
    .unwrap();
    code.push_str("            let cached = (*memory).translations.get_unchecked_mut(slot);\n");
    // Store the tag as well as the slot data because different pages can map to the same slot.
    code.push_str("            cached.guest_base = page_base;\n");
    code.push_str("            cached.page_index = left;\n");
    code.push_str("            cached.perms = page.perms;\n");
    code.push_str("            cached.data = page.data;\n");
    // Permission value 2 is the write bit. Only a successful write translation makes a page dirty.
    code.push_str("            if required_perm & 2 != 0 { mark_dirty(memory, left); }\n");
    // `offset` is below 4096, so pointer addition stays inside the selected page allocation.
    code.push_str("            return page.data.add(offset);\n");
    code.push_str("        }\n");
    code.push_str("    }\n");
    code.push_str("    core::ptr::null_mut()\n");
    code.push_str("}\n\n");

    // Fast translation checks one cache slot before it enters the cold page search.
    // A null memory pointer means the host did not install the guest-memory ABI.
    code.push_str("#[inline(always)]\n");
    code.push_str("unsafe fn translate(memory: *mut GuestMemoryAbi, addr: u64, required_perm: u8) -> *mut u8 {\n");
    code.push_str("    if memory.is_null() {\n");
    code.push_str("        return core::ptr::null_mut();\n");
    code.push_str("    }\n");
    // PAGE_SIZE is 4096, which is 2^12. Its mask is 4095, with the low 12 bits set.
    // Clear these bits to align the address down to its guest page base.
    writeln!(
        code,
        "    let page_base = addr & !(({}u64) - 1);",
        PAGE_SIZE
    )
    .unwrap();
    // Keep the low 12 bits to get the byte offset in the 4096-byte guest page.
    writeln!(
        code,
        "    let offset = (addr & (({}u64) - 1)) as usize;",
        PAGE_SIZE
    )
    .unwrap();
    // Select one of 16 cache entries from the low four bits of the guest page number.
    // `& 15` is a fast modulo 16 because 15 is binary 1111.
    writeln!(
        code,
        "    let slot = ((page_base / {}u64) as usize) & 15;",
        PAGE_SIZE
    )
    .unwrap();
    code.push_str("    let cached = (*memory).translations.get_unchecked_mut(slot);\n");
    // Check the pointer, address tag, and permissions because a direct-mapped slot can collide.
    code.push_str("    if !cached.data.is_null() && cached.guest_base == page_base && (cached.perms & required_perm) == required_perm {\n");
    // Apply the same write-bit check on a cache hit as on the slow search path.
    code.push_str("        if required_perm & 2 != 0 { mark_dirty(memory, cached.page_index); }\n");
    code.push_str("        return cached.data.add(offset);\n");
    code.push_str("    }\n");
    code.push_str("    translate_slow(memory, page_base, offset, required_perm)\n");
    code.push_str("}\n\n");

    // A single unaligned host access is safe only when the value stays inside one guest page.
    // RISC-V byte order source: https://docs.riscv.org/reference/isa/unpriv/rv32.html#load-and-store-instructions
    // Rust unaligned-read source: https://doc.rust-lang.org/core/ptr/fn.read_unaligned.html
    code.push_str("#[inline(always)]\n");
    code.push_str(
        "unsafe fn load_le(state: *mut GuestState, addr: u64, size: usize) -> Option<u64> {\n",
    );
    // Loads are at most one 64-bit value. The mask gets the low 12 address bits.
    // Adding `size` tests that all requested bytes remain in the current 4096-byte page.
    writeln!(
        code,
        "    if size <= 8 && (addr as usize & ({} - 1)) + size <= {} {{",
        PAGE_SIZE, PAGE_SIZE
    )
    .unwrap();
    // Permission value 1 requests the internal read bit.
    code.push_str("        let ptr = translate((*state).memory, addr, 1);\n");
    code.push_str(
        "        if ptr.is_null() { set_fault(state, addr, AccessKind::Read); return None; }\n",
    );
    // RISC-V sizes are 1, 2, 4, or 8 bytes. Use an unaligned read because guest addresses
    // need not meet the host type alignment. Convert from guest little-endian byte order.
    code.push_str("        return Some(match size {\n");
    code.push_str("            1 => *ptr as u64,\n");
    code.push_str(
        "            2 => u16::from_le(core::ptr::read_unaligned(ptr.cast::<u16>())) as u64,\n",
    );
    code.push_str(
        "            4 => u32::from_le(core::ptr::read_unaligned(ptr.cast::<u32>())) as u64,\n",
    );
    code.push_str("            8 => u64::from_le(core::ptr::read_unaligned(ptr.cast::<u64>())),\n");
    // Width validation makes this arm unreachable; keep a value so the match has one type.
    code.push_str("            _ => 0,\n");
    code.push_str("        });\n");
    code.push_str("    }\n");
    // A cross-page load must translate each byte because the next page can be absent or denied.
    code.push_str("    let mut value = 0u64;\n");
    code.push_str("    for idx in 0..size {\n");
    // Checked addition turns a guest address-space wrap into a read fault.
    code.push_str("        let Some(byte_addr) = addr.checked_add(idx as u64) else {\n");
    code.push_str("            set_fault(state, addr, AccessKind::Read);\n");
    code.push_str("            return None;\n");
    code.push_str("        };\n");
    // Permission value 1 requests a read translation for this byte.
    code.push_str("        let ptr = translate((*state).memory, byte_addr, 1);\n");
    code.push_str("        if ptr.is_null() {\n");
    code.push_str("            set_fault(state, byte_addr, AccessKind::Read);\n");
    code.push_str("            return None;\n");
    code.push_str("        }\n");
    // Each byte has eight bits. In little-endian order, byte `idx` starts at bit `idx * 8`.
    // OR combines the separate non-overlapping byte fields into one 64-bit value.
    code.push_str("        value |= (*ptr as u64) << (idx * 8);\n");
    code.push_str("    }\n");
    code.push_str("    Some(value)\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Stores mirror loads so both paths use the same page and byte-order rules.
    code.push_str("unsafe fn store_le(state: *mut GuestState, addr: u64, size: usize, value: u64) -> bool {\n");
    writeln!(
        code,
        "    if size <= 8 && (addr as usize & ({} - 1)) + size <= {} {{",
        PAGE_SIZE, PAGE_SIZE
    )
    .unwrap();
    // Permission value 2 requests the internal write bit and also marks the page dirty.
    code.push_str("        let ptr = translate((*state).memory, addr, 2);\n");
    code.push_str(
        "        if ptr.is_null() { set_fault(state, addr, AccessKind::Write); return false; }\n",
    );
    // Convert to little-endian before the unaligned host write, independent of host byte order.
    code.push_str("        match size {\n");
    code.push_str("            1 => *ptr = value as u8,\n");
    code.push_str(
        "            2 => core::ptr::write_unaligned(ptr.cast::<u16>(), (value as u16).to_le()),\n",
    );
    code.push_str(
        "            4 => core::ptr::write_unaligned(ptr.cast::<u32>(), (value as u32).to_le()),\n",
    );
    code.push_str(
        "            8 => core::ptr::write_unaligned(ptr.cast::<u64>(), value.to_le()),\n",
    );
    // Width validation makes this arm unreachable. Return false if malformed NNIL reaches it.
    code.push_str("            _ => return false,\n");
    code.push_str("        }\n");
    code.push_str("        return true;\n");
    code.push_str("    }\n");
    // Translate each byte for a page-crossing store. This checks permissions on both pages.
    // A later fault does not undo bytes already written on an earlier page.
    code.push_str("    for idx in 0..size {\n");
    // Checked addition turns a guest address-space wrap into a write fault.
    code.push_str("        let Some(byte_addr) = addr.checked_add(idx as u64) else {\n");
    code.push_str("            set_fault(state, addr, AccessKind::Write);\n");
    code.push_str("            return false;\n");
    code.push_str("        };\n");
    // Permission value 2 requests a write translation and marks its page dirty.
    code.push_str("        let ptr = translate((*state).memory, byte_addr, 2);\n");
    code.push_str("        if ptr.is_null() {\n");
    code.push_str("            set_fault(state, byte_addr, AccessKind::Write);\n");
    code.push_str("            return false;\n");
    code.push_str("        }\n");
    // Shift the wanted little-endian byte down by `idx * 8` bits.
    // Mask with 0xff, eight low one bits, so only that byte reaches memory.
    code.push_str("        *ptr = ((value >> (idx * 8)) & 0xff) as u8;\n");
    code.push_str("    }\n");
    code.push_str("    true\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Floating registers use integer storage only as a bit container.
    // `from_bits` restores the IEEE value, and `to_bits` preserves the result for register storage.
    // This helper does not model guest rounding modes or floating-point exception flags.
    code.push_str("fn fdiv_bits(size: usize, lhs: u64, rhs: u64) -> u64 {\n");
    code.push_str("    match size {\n");
    // Four and eight are the byte widths of single- and double-precision values.
    code.push_str("        4 => (f32::from_bits(lhs as u32) / f32::from_bits(rhs as u32)).to_bits() as u64,\n");
    code.push_str("        8 => (f64::from_bits(lhs) / f64::from_bits(rhs)).to_bits(),\n");
    // The lifter emits only supported widths. This unchecked arm depends on that invariant.
    // Any other value causes undefined behavior; this arm does not perform a run-time check.
    code.push_str("        _ => unsafe { core::hint::unreachable_unchecked() },\n");
    code.push_str("    }\n");
    code.push_str("}\n\n");

    code.push_str("#[inline(always)]\n");
    // Convert the numeric integer value, then return its floating-point bit encoding.
    // Cast through `u32` or `i32` first when the NNIL source has a four-byte width.
    // The current lifter emits an eight-byte floating destination for these conversions.
    // `false` selects an unsigned integer cast. `true` selects a signed integer cast.
    // Host casts do not update guest exception flags or select a guest rounding mode.
    code.push_str(
        "fn int_to_float_bits(src: u64, src_size: usize, signed: bool, dst_size: usize) -> u64 {\n",
    );
    code.push_str("    match (src_size, signed, dst_size) {\n");
    code.push_str("        (4, false, 8) => (src as u32 as f64).to_bits(),\n");
    code.push_str("        (4, true, 8) => ((src as i32) as f64).to_bits(),\n");
    code.push_str("        (8, false, 8) => (src as f64).to_bits(),\n");
    code.push_str("        (8, true, 8) => ((src as i64) as f64).to_bits(),\n");
    // The lifter emits only these width tuples. This unchecked arm depends on that invariant.
    // Any other tuple causes undefined behavior; it does not produce a normal emitter error.
    code.push_str("        _ => unsafe { core::hint::unreachable_unchecked() },\n");
    code.push_str("    }\n");
    code.push_str("}\n\n");

    code
}

impl<'a> RustEmitter<'a> {
    fn new(nnil: &'a Nnil, name_prefix: &str) -> JitResult<Self> {
        // Block discovery validates that the region has at least one guest instruction.
        let blocks = collect_blocks(nnil)?;

        // Unique prefixes prevent symbol collisions when many regions share one Rust crate.
        let block_names = blocks
            .iter()
            .map(|block| {
                (
                    block.addr,
                    format!("{name_prefix}_block_{:x}", block.addr.0),
                )
            })
            .collect::<BTreeMap<_, _>>();

        // Precompute markers because several emitted operators need signedness information.
        // NNIL uses marker instructions instead of distinct Rust integer storage types.
        let unsigned_markers = nnil
            .insns()
            .iter()
            .filter_map(|insn| match insn {
                NnilInstruction::Unsigned { dst } => Some(dst.0),
                _ => None,
            })
            .collect::<BTreeSet<_>>();

        Ok(Self {
            nnil,
            blocks,
            block_names,
            unsigned_markers,
        })
    }

    fn generate(&self) -> JitResult<String> {
        // A single-region artifact still needs the same ABI and helper template as a bundle.
        let mut code = genjittemplate();
        self.emit_region("execute", &mut code, &self.block_names)?;
        Ok(code)
    }

    fn emit_region(
        &self,
        export_name: &str,
        code: &mut String,
        linked_blocks: &BTreeMap<Address, String>,
    ) -> JitResult<()> {
        let entry = self
            .nnil
            .entrypoint()
            .ok_or_else(|| io::Error::other("cannot JIT an empty NNIL region"))?;
        // Emit block functions first so the exported dispatcher can tail-call any of them.
        // Rust permits later functions to refer to these names, but this order aids source reading.
        for block in &self.blocks {
            self.emit_block(block, code, linked_blocks)?;
        }

        // Keep the requested export name unchanged so `libloading` and the ELF parser can find it.
        // Source: https://doc.rust-lang.org/reference/abi.html#the-no_mangle-attribute
        code.push_str("#[no_mangle]\n");
        writeln!(
            code,
            "pub unsafe extern \"C\" fn {export_name}(state: *mut GuestState) -> ExitReason {{"
        )
        .unwrap();
        // Reject null before any generated raw-pointer dereference.
        code.push_str("    if state.is_null() {\n");
        code.push_str("        return ExitReason::IndirectBranch;\n");
        code.push_str("    }\n");
        // The host uses PC zero as an unset sentinel for a new direct entry call.
        writeln!(
            code,
            "    if (*state).pc == 0 {{ (*state).pc = {}; }}",
            entry.0
        )
        .unwrap();
        // Entry dispatch also permits calls into the middle of a previously compiled region.
        // A Rust match lets the compiler choose a compare tree or jump table for known block PCs.
        code.push_str("    match (*state).pc {\n");

        for block in &self.blocks {
            writeln!(
                code,
                "        {} => become {}(state),",
                block.addr.0,
                self.block_name(block.addr)?
            )
            .unwrap();
        }

        // Return to the host when this artifact does not contain the requested guest address.
        code.push_str("        _ => {\n");
        code.push_str("            (*state).exit_reason = ExitReason::IndirectBranch;\n");
        code.push_str("            ExitReason::IndirectBranch\n");
        code.push_str("        }\n");
        code.push_str("    }\n");
        code.push_str("}\n\n");

        Ok(())

        // todo -- shared state siehe gamozo
    }

    fn emit_block(
        &self,
        block: &BasicBlock,
        out: &mut String,
        linked_blocks: &BTreeMap<Address, String>,
    ) -> JitResult<()> {
        // All block functions use one signature, which is required for guaranteed tail calls.
        writeln!(
            out,
            "unsafe extern \"C\" fn {}(state: *mut GuestState) -> ExitReason {{",
            self.block_name(block.addr)?
        )
        .unwrap();

        // Store the precise guest PC before checks so pauses and faults report this block.
        // One control check per basic block limits debug overhead compared with every NNIL value.
        writeln!(out, "    (*state).pc = {};", block.addr.0).unwrap();
        out.push_str("    if let Some(reason) = control_block(state, (*state).pc) {\n");
        out.push_str("        (*state).exit_reason = reason;\n");
        out.push_str("        return reason;\n");
        out.push_str("    }\n");

        // A terminator emits its own control transfer, so the block must not add fallthrough code.
        let mut terminated = false;

        for insn_idx in block.start_insn..block.end_insn {
            if self.emit_insn(block, insn_idx, out, linked_blocks)? {
                terminated = true;
            }
        }

        // Add an explicit transfer because Rust functions must not fall through between blocks.
        // Tail calls also keep host stack use bounded for long straight-line guest execution.
        if !terminated {
            if let Some(next) = block.fallthrough {
                writeln!(out, "    (*state).pc = {};", next.0).unwrap();
                // Four spaces place the generated transfer in the block function body.
                self.write_branch_or_tailcall(next, out, 4, linked_blocks)?;
            } else {
                // The region ended without a local successor. Let the global table find the PC.
                writeln!(out, "    (*state).pc = {};", block.next_pc).unwrap();
                out.push_str("    become dispatch_jit(state);\n");
            }
        }

        out.push_str("}\n\n");
        Ok(())
    }

    fn emit_insn(
        &self,
        block: &BasicBlock,
        insn_idx: usize,
        out: &mut String,
        linked_blocks: &BTreeMap<Address, String>,
    ) -> JitResult<bool> {
        let insn = &self.nnil.insns()[insn_idx];

        // dbg!(insn);

        match insn {
            NnilInstruction::Imm { imm } => {
                // Cast through signed `i64` so a negative immediate keeps its two's-complement bits.
                writeln!(out, "    let v_{insn_idx}: u64 = ({imm}i64) as u64;").unwrap();
            }

            NnilInstruction::Reg { reg } => {
                // Validate now because generated `get_unchecked` cannot report a bad NNIL index.
                self.ensure_reg(*reg)?;
                writeln!(out, "    let v_{insn_idx}: u64 = read_reg(state, {});", reg).unwrap();
            }

            NnilInstruction::TmpReg { reg } => {
                // The bounds check in the emitter makes the later unchecked access valid and small.
                self.ensure_tmp(*reg)?;
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = *(*state).tmps.get_unchecked({});",
                    reg
                )
                .unwrap();
            }

            NnilInstruction::Add { lhs, rhs } => {
                // RISC-V keeps the low XLEN bits and ignores integer overflow.
                // Wrapping gives this rule in debug and optimized Rust builds.
                // Source: https://docs.riscv.org/reference/isa/unpriv/rv32.html#integer-register-register-instructions
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{}.wrapping_add(v_{});",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Sub { lhs, rhs } => {
                // Use the same low-64-bit overflow rule for subtraction.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{}.wrapping_sub(v_{});",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Mul { lhs, rhs } => {
                // MUL returns the low 64 bits, so wrapping discards the high half of the product.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{}.wrapping_mul(v_{});",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Mulh { lhs, rhs } => {
                // Operand markers select one of the RISC-V high-product signedness forms.
                // Swapping mixed operands reuses the signed-by-unsigned helper because
                // mathematical multiplication is commutative.
                let expr = match (self.signedness(*lhs), self.signedness(*rhs)) {
                    (Signedness::Signed, Signedness::Signed) => {
                        format!("mulh_signed_signed(v_{}, v_{})", lhs.0, rhs.0)
                    }
                    (Signedness::Signed, Signedness::Unsigned) => {
                        format!("mulh_signed_unsigned(v_{}, v_{})", lhs.0, rhs.0)
                    }
                    (Signedness::Unsigned, Signedness::Unsigned) => {
                        format!("mulh_unsigned_unsigned(v_{}, v_{})", lhs.0, rhs.0)
                    }
                    (Signedness::Unsigned, Signedness::Signed) => {
                        format!("mulh_signed_unsigned(v_{}, v_{})", rhs.0, lhs.0)
                    }
                };
                writeln!(out, "    let v_{insn_idx}: u64 = {expr};").unwrap();
            }

            NnilInstruction::Div { lhs, rhs } => {
                // Select before emission so generated code has no run-time signedness tag.
                let expr = match self.binary_signedness(*lhs, *rhs) {
                    Signedness::Signed => format!("div_signed(v_{}, v_{})", lhs.0, rhs.0),
                    Signedness::Unsigned => format!("div_unsigned(v_{}, v_{})", lhs.0, rhs.0),
                };
                writeln!(out, "    let v_{insn_idx}: u64 = {expr};").unwrap();
            }

            NnilInstruction::Mod { lhs, rhs } => {
                // Division and remainder share the same signedness rule from their NNIL markers.
                let expr = match self.binary_signedness(*lhs, *rhs) {
                    Signedness::Signed => format!("rem_signed(v_{}, v_{})", lhs.0, rhs.0),
                    Signedness::Unsigned => format!("rem_unsigned(v_{}, v_{})", lhs.0, rhs.0),
                };
                writeln!(out, "    let v_{insn_idx}: u64 = {expr};").unwrap();
            }

            NnilInstruction::And { lhs, rhs } => {
                // Direct bitwise AND already has the required 64-bit RISC-V result.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{} & v_{};",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Or { lhs, rhs } => {
                // Direct bitwise OR combines the corresponding bits without signed interpretation.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{} | v_{};",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Xor { lhs, rhs } => {
                // Direct bitwise XOR differs only where the two operand bits differ.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{} ^ v_{};",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Sll { lhs, rhs } => {
                // RV64 uses only the low six shift-amount bits. Mask 63 is binary 0b11_1111.
                // This limits shifts to 0..63 and prevents an invalid Rust shift by 64 or more.
                // Source: https://docs.riscv.org/reference/isa/unpriv/rv64.html
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{}.wrapping_shl((v_{} & 63) as u32);",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            /*

               NnilInstruction::Load { dst, src, size } => {
                self.ensure_load_store_size(*size)?;
                let load_expr = format!(
                    "match load_le(state, v_{}, {}) {{ Some(value) => value, None => {{ (*state).pc = {}; (*state).exit_reason = ExitReason::ReadFault; return ExitReason::ReadFault; }} }}",
                    src.0, size, block.addr.0
                );

                let value_expr = match self.load_mode(insn_idx, *dst) {
                    LoadMode::Raw | LoadMode::ZeroExtend => format!("zext(raw_{insn_idx}, {size})"),
                    LoadMode::SignExtend => format!("sext(raw_{insn_idx}, {size})"),
                };

                writeln!(out, "    let v_{insn_idx}: u32 = {value_expr};").unwrap();
            }

            */
            NnilInstruction::Srl { lhs, rhs } => {
                // Keep the same low-six-bit rule. A `u64` right shift inserts zero bits.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = v_{}.wrapping_shr((v_{} & 63) as u32);",
                    lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::Sra { lhs, rhs } => {
                // Cast to `i64` before the shift so Rust copies bit 63 into the new high bits.
                // Cast back to `u64` to keep the common register bit container.
                // Mask 63 keeps the low six count bits, as RV64 requires.
                writeln!(out, "    let v_{insn_idx}: u64 = ((v_{} as i64).wrapping_shr((v_{} & 63) as u32)) as u64;", lhs.0, rhs.0).unwrap();
            }

            NnilInstruction::Slt { lhs, rhs } => {
                // NNIL markers decide whether the same 64 bits are a signed or unsigned number.
                let expr = match self.binary_signedness(*lhs, *rhs) {
                    Signedness::Signed => format!("slt_signed(v_{}, v_{})", lhs.0, rhs.0),
                    Signedness::Unsigned => format!("slt_unsigned(v_{}, v_{})", lhs.0, rhs.0),
                };
                writeln!(out, "    let v_{insn_idx}: u64 = {expr};").unwrap();
            }
            NnilInstruction::Mov { dst, src } | NnilInstruction::Set { dst, src } => {
                // Bind a local value first, so all NNIL results use one `v_<index>` naming rule.
                writeln!(out, "    let v_{insn_idx}: u64 = v_{};", src.0).unwrap();
                self.emit_write_target(*dst, format!("v_{insn_idx}"), out)?;
            }

            NnilInstruction::Load { dst, src, size } => {
                // Reject a bad width in the emitter, before it can reach unchecked generated paths.
                self.ensure_load_store_size(*size)?;
                let load_expr = format!(
                    "match load_le(state, v_{}, {}) {{ Some(value) => value, None => {{ (*state).pc = {}; (*state).exit_reason = ExitReason::ReadFault; return ExitReason::ReadFault; }} }}",
                    src.0, size, block.addr.0
                );
                writeln!(out, "    let raw_{insn_idx}: u64 = {load_expr};").unwrap();
                // Integer loads extend, but floating-point loads must keep their raw bit pattern.
                // The lifter's marker selects zero extension. Other integer loads sign-extend.
                let value_expr = match self.load_mode(insn_idx, *dst) {
                    LoadMode::Raw | LoadMode::ZeroExtend => format!("zext(raw_{insn_idx}, {size})"),
                    LoadMode::SignExtend => format!("sext(raw_{insn_idx}, {size})"),
                };
                writeln!(out, "    let v_{insn_idx}: u64 = {value_expr};").unwrap();
                self.emit_write_target(*dst, format!("v_{insn_idx}"), out)?;
            }

            NnilInstruction::Store { dst, src, size } => {
                self.ensure_load_store_size(*size)?;
                // Preserve the source in the NNIL value sequence before memory can fault.
                writeln!(out, "    let v_{insn_idx}: u64 = v_{};", src.0).unwrap();
                writeln!(
                    out,
                    "    if !store_le(state, v_{}, {}, v_{insn_idx}) {{",
                    dst.0, size
                )
                .unwrap();
                // Report the PC of the guest store, not the next block, when translation fails.
                writeln!(out, "        (*state).pc = {};", block.addr.0).unwrap();
                out.push_str("        (*state).exit_reason = ExitReason::WriteFault;\n");
                out.push_str("        return ExitReason::WriteFault;\n");
                out.push_str("    }\n");
            }

            NnilInstruction::Sext { size, dst } => {
                // `size` is in bytes, and the shared helper converts it to bits with `* 8`.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = sext(v_{}, {});",
                    dst.0, size
                )
                .unwrap();
            }

            NnilInstruction::Zext { size, dst } => {
                // Zero extension clears every bit above the selected byte width.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = zext(v_{}, {});",
                    dst.0, size
                )
                .unwrap();
            }

            NnilInstruction::Signed { dst } | NnilInstruction::Unsigned { dst } => {
                // A marker changes interpretation only. It must keep the operand bits unchanged.
                writeln!(out, "    let v_{insn_idx}: u64 = v_{};", dst.0).unwrap();
            }

            NnilInstruction::Fdiv { lhs, rhs, size } => {
                // Pass bit containers to the helper so integer locals do not change NaN payloads.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = fdiv_bits({}, v_{}, v_{});",
                    size, lhs.0, rhs.0
                )
                .unwrap();
            }

            NnilInstruction::IntToFloat {
                src,
                src_size,
                signed,
                dst_size,
            } => {
                // Emit widths as constants, so rustc can remove unsupported match arms.
                writeln!(
                    out,
                    "    let v_{insn_idx}: u64 = int_to_float_bits(v_{}, {}, {}, {});",
                    src.0, src_size, signed, dst_size
                )
                .unwrap();
            }

            // todo - fence ist egeal oder?
            NnilInstruction::Fence { .. } => {
                // The current runtime has one guest thread and no modeled device ordering.
                // Keep a zero NNIL result so later value indexes remain valid.
                writeln!(out, "    let v_{insn_idx}: u64 = 0;").unwrap();
            }

            // todo - wichtig
            NnilInstruction::Jr { dst } | NnilInstruction::Jmp { dst } => {
                // Resolve a nonnegative immediate now. A register target stays a run-time value.
                if let Some(target) = self.direct_jump_target(*dst) {
                    writeln!(out, "    (*state).pc = {};", target.0).unwrap();
                    // Tail-call known blocks to keep long guest runs from growing the host stack.
                    // `become` reuses the current host frame instead of ordinary recursive calls.
                    if let Some(name) = linked_blocks.get(&target) {
                        writeln!(out, "    become {name}(state);").unwrap();
                    } else {
                        out.push_str("    become dispatch_jit(state);\n");
                    }
                } else {
                    // A computed target needs the sorted global entry table.
                    writeln!(out, "    (*state).pc = v_{};", dst.0).unwrap();
                    out.push_str("    become dispatch_jit(state);\n");
                }
                return Ok(true);
            }

            NnilInstruction::Beq {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => {
                // Equality depends only on bits, so it needs no signedness interpretation.
                self.emit_branch(
                    format!("v_{} == v_{}", lhs.0, rhs.0),
                    *ttgt,
                    *ftgt,
                    out,
                    linked_blocks,
                )?;
                return Ok(true);
            }

            NnilInstruction::Bne {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => {
                // Inequality also gives the same result for signed and unsigned operands.
                self.emit_branch(
                    format!("v_{} != v_{}", lhs.0, rhs.0),
                    *ttgt,
                    *ftgt,
                    out,
                    linked_blocks,
                )?;
                return Ok(true);
            }

            NnilInstruction::Blt {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => {
                // A cast to `i64` gives a two's-complement signed comparison without changing bits.
                let cond = match self.binary_signedness(*lhs, *rhs) {
                    Signedness::Signed => format!("(v_{} as i64) < (v_{} as i64)", lhs.0, rhs.0),
                    Signedness::Unsigned => format!("v_{} < v_{}", lhs.0, rhs.0),
                };
                self.emit_branch(cond, *ttgt, *ftgt, out, linked_blocks)?;
                return Ok(true);
            }

            NnilInstruction::Bgt {
                lhs,
                rhs,
                ttgt,
                ftgt,
            } => {
                // Keep the generated condition small by deciding signedness in the emitter.
                let cond = match self.binary_signedness(*lhs, *rhs) {
                    Signedness::Signed => format!("(v_{} as i64) > (v_{} as i64)", lhs.0, rhs.0),
                    Signedness::Unsigned => format!("v_{} > v_{}", lhs.0, rhs.0),
                };
                self.emit_branch(cond, *ttgt, *ftgt, out, linked_blocks)?;
                return Ok(true);
            }

            NnilInstruction::Syscall {} => {
                // Resume after the guest instruction when the runtime completes the syscall.
                // Syscall effects need host services, so generated code exits at this boundary.
                writeln!(out, "    (*state).pc = {};", block.next_pc).unwrap();
                out.push_str("    (*state).exit_reason = ExitReason::Syscall;\n");
                out.push_str("    return ExitReason::Syscall;\n");
                return Ok(true);
            }

            NnilInstruction::Sysbreak {} => {
                // Advance first so the host can resume after it handles the break request.
                writeln!(out, "    (*state).pc = {};", block.next_pc).unwrap();
                out.push_str("    (*state).exit_reason = ExitReason::Sysbreak;\n");
                out.push_str("    return ExitReason::Sysbreak;\n");
                return Ok(true);
            }

            NnilInstruction::Lr { dst, src, size } => {
                // A narrow LR returns a sign-extended value as required by RV64 atomics.
                // Source: https://docs.riscv.org/reference/isa/unpriv/a-st-ext.html
                self.ensure_load_store_size(*size)?;
                writeln!(
                    out,
                    "    let raw_{insn_idx}: u64 = match load_le(state, v_{}, {}) {{ Some(value) => value, None => {{ (*state).pc = {}; (*state).exit_reason = ExitReason::ReadFault; return ExitReason::ReadFault; }} }};",
                    src.0, size, block.addr.0
                ).unwrap();
                // Eight bytes fill the 64-bit RV64 integer-register width, called XLEN.
                // A smaller atomic load needs explicit extension to that width.
                let value_expr = if *size < 8 {
                    format!("sext(raw_{insn_idx}, {})", size)
                } else {
                    format!("raw_{insn_idx}")
                };
                writeln!(out, "    let v_{insn_idx}: u64 = {value_expr};").unwrap();
                self.emit_write_target(*dst, format!("v_{insn_idx}"), out)?;
            }

            NnilInstruction::Sc {
                dst,
                src,
                addr,
                size,
            } => {
                self.ensure_load_store_size(*size)?;
                // A narrow store uses only its low `size * 8` bits.
                // The all-ones mask is safe because `size < 8` avoids a shift by 64.
                let store_val = if *size < 8 {
                    format!("v_{} & ((1u64 << ({} * 8)) - 1)", src.0, size)
                } else {
                    format!("v_{}", src.0)
                };
                // Reservation state is not modeled. This implementation always stores and reports success.
                // This is a current limitation, not complete RISC-V LR/SC behavior. Zero means success.
                writeln!(out, "    let v_{insn_idx}: u64 = 0;").unwrap();
                writeln!(
                    out,
                    "    if !store_le(state, v_{}, {}, {}) {{",
                    addr.0, size, store_val
                )
                .unwrap();
                writeln!(out, "        (*state).pc = {};", block.addr.0).unwrap();
                out.push_str("        (*state).exit_reason = ExitReason::WriteFault;\n");
                out.push_str("        return ExitReason::WriteFault;\n");
                out.push_str("    }\n");
                self.emit_write_target(*dst, format!("v_{insn_idx}"), out)?;
            }

            NnilInstruction::Amo {
                op,
                dst,
                src,
                addr,
                size,
            } => {
                // Use a load, a host calculation, and a store because this runtime has one guest
                // thread. It does not need a host atomic primitive for guest-byte-array storage.
                self.ensure_load_store_size(*size)?;
                writeln!(
                    out,
                    "    let raw_{insn_idx}: u64 = match load_le(state, v_{}, {}) {{ Some(value) => value, None => {{ (*state).pc = {}; (*state).exit_reason = ExitReason::ReadFault; return ExitReason::ReadFault; }} }};",
                    addr.0, size, block.addr.0
                ).unwrap();

                // RV64 word atomics return a sign-extended old value in the destination register.
                let loaded = if *size < 8 {
                    format!("sext(raw_{insn_idx}, {})", size)
                } else {
                    format!("raw_{insn_idx}")
                };
                // Truncate every narrow source, then sign-extend it to the RV64 register form.
                // Unsigned min/max still compare these equal-width forms as `u64` values.
                let rhs = if *size < 8 {
                    format!("sext(zext(v_{}, {}), {})", src.0, size, size)
                } else {
                    format!("v_{}", src.0)
                };

                // Wrapping addition keeps the low result bits on overflow.
                // Signed min/max cast the bit containers to `i64`; unsigned forms do not cast.
                let result_expr = match op {
                    AmoOp::Swap => format!("v_{}", src.0),
                    AmoOp::Add => format!("{loaded}.wrapping_add({rhs})"),
                    AmoOp::Xor => format!("{loaded} ^ {rhs}"),
                    AmoOp::And => format!("{loaded} & {rhs}"),
                    AmoOp::Or => format!("{loaded} | {rhs}"),
                    AmoOp::Min => format!(
                        "if ({loaded} as i64) < ({rhs} as i64) {{ {loaded} }} else {{ {rhs} }}"
                    ),
                    AmoOp::Max => format!(
                        "if ({loaded} as i64) > ({rhs} as i64) {{ {loaded} }} else {{ {rhs} }}"
                    ),
                    AmoOp::Minu => format!("if {loaded} < {rhs} {{ {loaded} }} else {{ {rhs} }}"),
                    AmoOp::Maxu => format!("if {loaded} > {rhs} {{ {loaded} }} else {{ {rhs} }}"),
                };

                // Store only the low atomic-width bits. The shift builds an all-ones width mask.
                let store_val = if *size < 8 {
                    format!("{result_expr} & ((1u64 << ({} * 8)) - 1)", size)
                } else {
                    result_expr
                };
                writeln!(
                    out,
                    "    if !store_le(state, v_{}, {}, {}) {{",
                    addr.0, size, store_val
                )
                .unwrap();
                writeln!(out, "        (*state).pc = {};", block.addr.0).unwrap();
                out.push_str("        (*state).exit_reason = ExitReason::WriteFault;\n");
                out.push_str("        return ExitReason::WriteFault;\n");
                out.push_str("    }\n");

                // AMO writes the old memory value, not the new value, to its destination register.
                writeln!(out, "    let v_{insn_idx}: u64 = {loaded};").unwrap();
                self.emit_write_target(*dst, format!("v_{insn_idx}"), out)?;
            }
        }

        Ok(false)
    }

    fn emit_branch(
        &self,
        condition: String,
        ttgt: Label,
        ftgt: Label,
        out: &mut String,
        linked_blocks: &BTreeMap<Address, String>,
    ) -> JitResult<()> {
        // Labels are NNIL handles. Resolve them before source emission can write a wrong PC.
        let ttgt_addr = self.label_address(ttgt)?;
        let ftgt_addr = self.label_address(ftgt)?;

        writeln!(out, "    if {condition} {{").unwrap();
        writeln!(out, "        (*state).pc = {};", ttgt_addr.0).unwrap();

        // Eight spaces place the transfer inside the generated `if` arm.
        self.write_branch_or_tailcall(ttgt_addr, out, 8, linked_blocks)?;
        out.push_str("    } else {\n");

        //
        // Store the selected PC before transfer, so the target block and host see one state.
        writeln!(out, "        (*state).pc = {};", ftgt_addr.0).unwrap();

        self.write_branch_or_tailcall(ftgt_addr, out, 8, linked_blocks)?;
        out.push_str("    }\n");
        Ok(())
    }

    fn emit_write_target(&self, dst: Insn, value_expr: String, out: &mut String) -> JitResult<()> {
        // Validate NNIL destinations before generated code uses unchecked register indexing.
        // NNIL names a destination through an instruction handle, not a direct register number.
        match self.nnil.insns()[dst.0 as usize] {
            NnilInstruction::Reg { reg } => {
                self.ensure_reg(reg)?;
                writeln!(out, "    write_reg(state, {}, {});", reg, value_expr).unwrap();
            }
            NnilInstruction::TmpReg { reg } => {
                self.ensure_tmp(reg)?;
                // Bounds validation above permits one unchecked access in hot generated code.
                writeln!(
                    out,
                    "    *(*state).tmps.get_unchecked_mut({}) = {};",
                    reg, value_expr
                )
                .unwrap();
            }
            ref other => {
                return Err(
                    io::Error::other(format!("unexpected in emitwritetarget:  {other:?}")).into(),
                );
            }
        }
        Ok(())
    }

    fn block_name(&self, addr: Address) -> JitResult<&str> {
        // A missing name means block collection and branch resolution disagree, so stop emission.
        self.block_names
            .get(&addr)
            .map(String::as_str)
            .ok_or_else(|| {
                io::Error::other(format!("missing block for address 0x{:x}", addr.0)).into()
            })
    }

    fn label_address(&self, label: Label) -> JitResult<Address> {
        // Do not emit a placeholder for an invalid label because native code could jump wrongly.
        self.nnil
            .label_address(label)
            .ok_or_else(|| io::Error::other(format!("unknown label {:?}", label)).into())
    }

    // siehe https://doc.rust-lang.org/std/keyword.become.html
    fn write_branch_or_tailcall(
        &self,
        addr: Address,
        out: &mut String,
        indent: usize,
        linked_blocks: &BTreeMap<Address, String>,
    ) -> JitResult<()> {
        // Indentation affects generated source only. Four spaces mark a block level, and eight
        // spaces mark a branch-arm level in the call sites above.
        let padding = " ".repeat(indent);

        // Use a direct tail call when possible; otherwise the runtime dispatch table handles it.
        // All targets have the same ABI, arguments, and return type as `become` requires.
        // Source: https://doc.rust-lang.org/std/keyword.become.html
        if let Some(name) = linked_blocks.get(&addr) {
            writeln!(out, "{padding}become {name}(state);").unwrap();
        } else {
            writeln!(out, "{padding}become dispatch_jit(state);").unwrap();
        }
        Ok(())
    }

    fn direct_jump_target(&self, dst: Insn) -> Option<Address> {
        // Handle nonnegative immediates as direct targets. Send all other forms to run-time dispatch.
        match self.nnil.insns()[dst.0 as usize] {
            NnilInstruction::Imm { imm } if imm >= 0 => Some(Address(imm as u64)),
            _ => None,
        }
    }

    fn load_mode(&self, load_idx: usize, dst: Insn) -> LoadMode {
        // Floating-point registers carry bits, so integer sign extension would corrupt values.
        // Register numbers at `FP_REG_BASE` and above select floating-register storage.
        if matches!(self.nnil.insns()[dst.0 as usize], NnilInstruction::Reg { reg } if reg as usize >= FP_REG_BASE)
        {
            return LoadMode::Raw;
        }

        // An unsigned marker on the load means the ISA load clears high destination bits.
        if self.unsigned_markers.contains(&(load_idx as u64)) {
            LoadMode::ZeroExtend
        } else {
            LoadMode::SignExtend
        }
    }

    fn signedness(&self, insn: Insn) -> Signedness {
        // Signed is the NNIL default. Only an explicit marker selects unsigned interpretation.
        match self.nnil.insns()[insn.0 as usize] {
            NnilInstruction::Unsigned { .. } => Signedness::Unsigned,
            _ => Signedness::Signed,
        }
    }

    fn binary_signedness(&self, lhs: Insn, rhs: Insn) -> Signedness {
        // Treat a mixed operation as unsigned, which matches how the lifter marks its operands.
        if self.signedness(lhs) == Signedness::Unsigned
            || self.signedness(rhs) == Signedness::Unsigned
        {
            Signedness::Unsigned
        } else {
            Signedness::Signed
        }
    }

    fn ensure_reg(&self, reg: u64) -> JitResult<()> {
        // Generated indexing is unchecked for speed, so the emitter must prove this bound first.
        if reg as usize >= GUEST_REG_COUNT {
            Err(io::Error::other(format!("register {} exceeds register file", reg)).into())
        } else {
            Ok(())
        }
    }

    fn ensure_tmp(&self, reg: u64) -> JitResult<()> {
        // Reject malformed NNIL instead of letting native code access past `tmps`.
        if reg as usize >= GUEST_TMP_COUNT {
            Err(io::Error::other(format!("temporary register {} exceeds tmp file", reg)).into())
        } else {
            Ok(())
        }
    }

    fn ensure_load_store_size(&self, size: u64) -> JitResult<()> {
        // This backend supports scalar widths of 8, 16, 32, and 64 bits.
        // The values below are byte counts, so they are 1, 2, 4, and 8.
        match size {
            1 | 2 | 4 | 8 => Ok(()),
            other => Err(io::Error::other(format!("memory size unsupported: {}", other)).into()),
        }
    }
}

fn collect_blocks(nnil: &Nnil) -> JitResult<Vec<BasicBlock>> {
    // Instruction starts map guest PCs to the first NNIL value for each guest instruction.
    let starts = nnil
        .instruction_starts()
        .iter()
        .map(|(addr, insn)| (*addr, insn.0 as usize))
        .collect::<Vec<_>>();

    if starts.is_empty() {
        return Err(io::Error::other("leere NNIL!").into());
    }

    // Begin at the first guest instruction because an empty list was rejected above.
    let mut blocks = Vec::new();
    let mut block_start_addr = starts[0].0;
    let mut block_start_insn = starts[0].1;

    // End blocks at labels and terminators so each possible target has a function boundary.
    // One host function per block permits direct tail calls between known guest targets.
    for (idx, &(addr, insn_start)) in starts.iter().enumerate() {
        let next = starts.get(idx + 1).copied();

        // The next guest instruction starts after all NNIL values for the current instruction.
        let insn_end = next
            .map(|(_, next_start)| next_start)
            .unwrap_or_else(|| nnil.insns().len());

        let guest_insn = &nnil.insns()[insn_start..insn_end];

        // &nnil.insns()[insn_start..insn_end]
        let terminates = is_terminator(guest_insn);

        // A label makes the next address a legal branch entry, so it must start a new block.
        let next_is_label = next
            .map(|(next_addr, _)| nnil.label_for_address(next_addr).is_some())
            .unwrap_or(false);

        // At region end, `nnil.pc()` is the address where lifting stopped.
        let next_pc = next
            .map(|(next_addr, _)| next_addr.0)
            .unwrap_or_else(|| nnil.pc());
        let should_end = terminates || next.is_none() || next_is_label;

        if should_end {
            // Only non-terminating blocks can use the next guest instruction as fallthrough.
            let fallthrough = if terminates {
                None
            } else {
                next.map(|(next_addr, _)| next_addr)
            };

            blocks.push(BasicBlock {
                addr: block_start_addr,
                start_insn: block_start_insn,
                end_insn: insn_end,
                fallthrough,
                next_pc,
            });

            // dbg!(blocks);

            if let Some((next_addr, next_start)) = next {
                // Start the next block only after this block has captured its full NNIL range.
                block_start_addr = next_addr;
                block_start_insn = next_start;
            }
        }

        // The block split uses `next_addr`; keep this tuple member without an unused warning.
        let _ = addr;
    }

    Ok(blocks)
}

// todo - duplicate code
fn is_terminator(insns: &[NnilInstruction]) -> bool {
    // Only the last NNIL value can end its guest instruction and therefore its basic block.
    // System exits also terminate because the host must handle them before guest execution resumes.
    matches!(
        insns.last(),
        Some(
            NnilInstruction::Jr { .. }
                | NnilInstruction::Jmp { .. }
                | NnilInstruction::Beq { .. }
                | NnilInstruction::Bne { .. }
                | NnilInstruction::Blt { .. }
                | NnilInstruction::Bgt { .. }
                | NnilInstruction::Syscall {}
                | NnilInstruction::Sysbreak {}
        )
    )
}