remu/

main.rs

//! The CLI builds one guest process and keeps runtime policy outside the JIT library.
//!
//! RISC-V instruction lengths: https://docs.riscv.org/reference/isa/unpriv/intro.html#base-instruction-length-encoding
//! RISC-V register names: https://riscv-non-isa.github.io/riscv-elf-psabi-doc/#_integer_register_convention

use chrono::Local;
use clap::Parser;

use jit::{ExitReason, GuestMemory, GuestState, JitRuntime, ProgramImage, RemuConfig};
use lifter::{MemoryView, RiscVArch, lift_block};

use std::env;
use std::fs;
use std::io::{self, Write as _};
use std::path::{Path, PathBuf};
use std::sync::atomic::Ordering;

#[derive(Parser, Debug)]
#[command(name = "remu")]
// Keep all host and guest inputs explicit so a run can be reproduced from its command line.
struct Cli {
    // A path type preserves host path syntax and avoids a later text-to-path conversion.
    input_file: PathBuf,

    #[arg(long)]
    // Print the address of one ELF symbol for entry-point diagnostics.
    entry_symbol: Option<String>,

    #[arg(long)]
    // Skip early compilation so all regions use the lazy JIT path.
    no_aot: bool,

    #[arg(long)]
    // Supply the guest root for absolute paths and the ELF interpreter.
    sysroot: Option<PathBuf>,

    #[arg(long)]
    // Supply the writable guest directory for relative paths.
    workdir: Option<PathBuf>,

    #[arg(short, long)]
    // Show compiler and cache activity that normal guest output does not need.
    verbose: bool,

    #[arg(long)]
    // Stop before execution and enable block-level debugger commands.
    debug: bool,

    #[arg(
        long,
        default_value_t = 2,
        value_parser = clap::value_parser!(u8).range(0..=2)
    )]
    // The range matches the three optimization levels that this JIT runtime supports.
    // The default value 2 gives generated code the highest enabled optimization level.
    jit_opt_level: u8,

    #[arg(long)]
    // Use per-run artifacts only, which prevents reuse of old compiled regions.
    no_jit_cache: bool,

    // todo -- wip
    #[arg(long)]
    // Use the Linux x86-64 raw loader instead of a host shared library.
    raw_jit: bool,

    // `last` keeps guest flags separate from emulator flags after `--`.
    #[arg(last = true)]
    // Pass all values after `--` to the guest process without CLI interpretation.
    guest_args: Vec<String>,
}

/*

 --- todo ----

- config flags
- tracing ?
- https://docs.rs/clap/latest/clap/
- mehr dgb/prints für nnil sachen
*/

fn main() {
    // `clap` converts command-line text to typed values before runtime setup starts.
    let cli = Cli::parse();

    println!("\n--------- remu ---------");

    // Create a per-run directory before JIT work so all generated artifacts stay together.
    let output_dir = match create_output_dir(&cli.input_file) {
        Ok(path) => path,
        Err(err) => {
            eprintln!("error while creating output dir: {err}");
            return;
        }
    };

    // A `match` handles the error here because `main` returns no `Result` to the operating system.
    let image = match fs::read(&cli.input_file) {
        Ok(bytes) => bytes,
        Err(err) => {
            eprintln!(
                "error while reading input file {}: {err}",
                cli.input_file.display()
            );
            return;
        }
    };

    let program = match ProgramImage::from_elf_bytes(&image) {
        Ok(program) => program,
        Err(err) => {
            eprintln!("error while loading ELF: {err}");
            return;
        }
    };

    println!("\n\n----- ELF loaded -----");
    println!("Input: {}", cli.input_file.display());
    println!("Output dir: {}", output_dir.display());
    println!("Entry point: 0x{:x}", program.entry_pc);

    // `if let` enters this block only when both optional values exist.
    if let Some(value) = &cli.entry_symbol
        && let Some(entry_sym) = program.find_symbol(value)
    {
        println!("{} symbol gefunden: 0x{:x}", value, entry_sym.value);
        // todo - start ab diesem entry point
    }

    // Guest argv[0] uses a guest-visible name instead of exposing the host input path.
    let mut argv = vec![input_basename(&cli.input_file)];
    argv.extend(cli.guest_args);
    // `None` tells the JIT to use per-run files and to skip all disk-cache lookup.
    let jit_cache_dir = if cli.no_jit_cache {
        None
    } else {
        // Use one project cache so separate run directories can reuse compiled regions.
        match project_root() {
            Ok(root) => Some(root.join("jit-tmp/cache")),
            Err(err) => {
                eprintln!("error while finding project root: {err}");
                return;
            }
        }
    };
    let process = RemuConfig {
        argv,
        envp: Vec::new(),
        sysroot: cli.sysroot,
        workdir: cli.workdir,
        jit_opt_level: cli.jit_opt_level,
        jit_cache_dir,
        raw_jit: cli.raw_jit,
    };

    let mut runtime =
        // The closure gives the runtime a lifter without making the JIT crate depend on RISC-V.
        match JitRuntime::init_runtime(program, process, output_dir.clone(), |memory, pc| {
            // Fetch through the MMU so the lifter respects execute permissions and mapping changes.
            let view = MemoryView { memory };

            // Loaded executables use RV64. XLEN, the integer-register width, is therefore 64 bits.
            match lift_block(RiscVArch::Rv64, &view, pc) {
                Some(nnil) => Ok(nnil),
                None => Err(io::Error::other(format!(
                    "no executable region contains guest pc 0x{pc:x}"
                ))
                .into()),
            }
        }) {
            Ok(runtime) => runtime,
            Err(err) => {
                eprintln!("error while creating runtime: {err}");
                return;
            }
        };

    runtime.set_verbose(cli.verbose);

    if cli.verbose {
        println!("AOT precompile: {}", if cli.no_aot { "off" } else { "on" });
    }

    if !cli.no_aot {
        // Best-effort precompilation reduces pauses before lazy JIT fallback begins.
        println!("\n----- pre-compiling as much as possible now -----");
        let compiled_regions = match runtime.precompile() {
            Ok(count) => count,
            Err(err) => {
                eprintln!("aot precompile failed: {err}");
                return;
            }
        };

        if cli.verbose {
            println!("amount of precompiled regions: {}", compiled_regions);
        }
    }

    println!("\n----- starting execution + JIT now -----");

    let exit_reason = match if cli.debug {
        run_debugger(&mut runtime)
    } else {
        runtime.run()
    } {
        Ok(reason) => reason,
        Err(err) => {
            eprintln!("oh oh: {err}");
            return;
        }
    };

    let state = runtime.state();

    println!("Exit reason: {exit_reason:?}");
    println!("pc = 0x{:x}", state.pc);
    // The psABI uses x10 for return values and x2 for the stack pointer.
    println!("a0/x10 = {}", state.regs[10]);
    println!("sp/x2 = 0x{:x}", state.regs[2]);
    println!("fault_addr = 0x{:x}", state.fault_addr);
    println!("fault_access = {:?}", state.fault_access);
    println!("cached regions = {}", runtime.cache_len());

    match exit_reason {
        ExitReason::UnhandledHostCall => {
            println!("UnhandledHostCall");
        }
        ExitReason::GuestExit => {
            println!("GuestExit");
        }
        _ => {}
    }
}


// todo - refactor
fn run_debugger<L>(runtime: &mut JitRuntime<L>) -> Result<ExitReason, Box<dyn std::error::Error>>
where
    L: Fn(&GuestMemory, u64) -> Result<liil::nnil::Nnil, Box<dyn std::error::Error>>,
{
    // The Ctrl-C crate runs this closure on a dedicated thread.
    // An atomic flag requests a pause without borrowing or locking the runtime.
    let pause = runtime.pause_flag();
    // Relaxed order is sufficient because this atomic communicates only one independent stop flag.
    // `?` returns the setup error to the caller instead of continuing without Ctrl-C support.
    ctrlc::set_handler(move || pause.store(true, Ordering::Relaxed))?;

    // Keep a user checkpoint separate from the runtime's private reset snapshot.
    let mut checkpoint = None;
    let mut reason = ExitReason::Paused;
    print_stop(runtime, reason);

    loop {
        print!("(remu) ");
        io::stdout().flush()?;
        let mut line = String::new();

        // A zero-byte read means end-of-file. This also lets a pipe close the debugger cleanly.
        if io::stdin().read_line(&mut line)? == 0 {
            return Ok(reason);
        }

        let mut words = line.split_whitespace();
        let Some(command) = words.next() else {
            continue;
        };

        match command {
            "continue" | "c" => {
                // u64::MAX is an effective unlimited block count without a separate run mode.
                reason = match runtime.run_for_blocks(u64::MAX) {
                    Ok(reason) => reason,
                    Err(err) => {
                        println!("execution error: {err}");
                        print_stop(runtime, runtime.state().exit_reason);
                        continue;
                    }
                };
                print_stop(runtime, reason);

                if reason == ExitReason::GuestExit {
                    return Ok(reason);
                }
            }
            "step" | "s" => {
                // Generated code checks debugger controls at each basic-block entry.
                // A limit of one therefore executes one block before it stops.
                reason = match runtime.run_for_blocks(1) {
                    Ok(reason) => reason,
                    Err(err) => {
                        println!("execution error: {err}");
                        print_stop(runtime, runtime.state().exit_reason);
                        continue;
                    }
                };
                print_stop(runtime, reason);
            }
            "break" | "b" => {
                if let Some(value) = words.next() {
                    match parse_address(runtime.program(), value) {
                        Some(address) => match runtime.add_breakpoint(address) {
                            Ok(()) => println!("breakpoint at 0x{address:x}"),
                            Err(err) => println!("error: {err}"),
                        },
                        None => println!("unknown address or symbol: {value}"),
                    }
                } else {
                    for address in runtime.breakpoints() {
                        println!("0x{address:x}");
                    }
                }
            }
            "delete" => match words.next() {
                Some("all") => runtime.clear_breakpoints(),
                Some(value) => match parse_address(runtime.program(), value) {
                    Some(address) => runtime.remove_breakpoint(address),
                    None => println!("unknown address or symbol: {value}"),
                },
                None => println!("usage: delete <address|symbol|all>"),
            },
            "regs" => print_registers(runtime.state()),
            "mem" => {
                let Some(value) = words.next() else {
                    println!("usage: mem <address> [length]");
                    continue;
                };
                let Some(address) = parse_address(runtime.program(), value) else {
                    println!("unknown address or symbol: {value}");
                    continue;
                };
                // Show 64 bytes by default. Limit input to 4096 bytes to bound debugger output.
                let length = words.next().and_then(parse_number).unwrap_or(64).min(4096) as usize;
                print_memory(runtime.memory(), address, length);
            }
            "maps" => {
                for (start, end, perms) in runtime.memory().mappings() {
                    // A letter means that its permission bit is set. A dash means that it is clear.
                    // Sixteen hexadecimal digits show all 64 address bits and keep columns aligned.
                    println!(
                        "0x{start:016x}-0x{end:016x} {}{}{}",
                        if perms.contains(jit::PagePerms::READ) {
                            'r'
                        } else {
                            '-'
                        },
                        if perms.contains(jit::PagePerms::WRITE) {
                            'w'
                        } else {
                            '-'
                        },
                        if perms.contains(jit::PagePerms::EXEC) {
                            'x'
                        } else {
                            '-'
                        },
                    );
                }
            }
            "where" => print_stop(runtime, reason),
            "nnil" => match runtime.lift_at(runtime.state().pc) {
                Ok(nnil) => println!("{nnil:?}"),
                Err(err) => println!("error: {err}"),
            },
            "trace" => {
                for pc in runtime.trace() {
                    println!("0x{pc:016x}");
                }
            }
            "snapshot" => {
                checkpoint = Some(runtime.snapshot()?);
                println!("snapshot saved");
            }
            "restore" => match &checkpoint {
                Some(snapshot) => {
                    runtime.restore(snapshot)?;
                    reason = ExitReason::Paused;
                    print_stop(runtime, reason);
                }
                None => println!("wip! no snapshot saved"),
            },
            "reset" => {
                runtime.reset()?;
                reason = ExitReason::Paused;
                print_stop(runtime, reason);
            }
            "help" | "h" => println!(
                "ACHTUNG, NOCH WORK-IN-PROGRES. Commands: continue, step, break <address oder symbol>, delete <address oder symbol oder all>, regs, mem <address> [length], maps, where, nnil, trace, snapshot, restore, reset, quit"
            ),
            "quit" | "q" => return Ok(reason),
            _ => println!("unknown command, use help"),
        }
    }
}

fn parse_number(value: &str) -> Option<u64> {
    // Prefix 0x selects radix 16. Without this prefix, debugger input is decimal.
    value
        .strip_prefix("0x")
        .and_then(|value| u64::from_str_radix(value, 16).ok())
        .or_else(|| value.parse().ok())
}

fn parse_address(program: &ProgramImage, value: &str) -> Option<u64> {
    // Prefer numeric input so a symbol that looks like a number cannot change command meaning.
    parse_number(value).or_else(|| program.find_symbol(value).map(|symbol| symbol.value))
}

fn print_stop<L>(runtime: &JitRuntime<L>, reason: ExitReason)
where
    L: Fn(&GuestMemory, u64) -> Result<liil::nnil::Nnil, Box<dyn std::error::Error>>,
{
    let state = runtime.state();
    print!("stopped: {reason:?}, pc=0x{:x}", state.pc);
    if let Some(symbol) = runtime.program().symbol_at(state.pc) {
        print!(" <{}+0x{:x}>", symbol.name, state.pc - symbol.value);
    }
    println!();

    // Read the first halfword because its low bits select the RISC-V instruction length.
    if let Some(half) = runtime.memory().fetch_u16(state.pc) {
        // Instructions of at least 32 bits end in binary 11. This debugger supports the 32-bit form.
        // Other low-bit values select 16-bit compressed RISC-V (RVC) instructions.
        // Mask 3 is binary 11, so `half & 3` keeps only these two length bits.
        if half & 3 == 3 {
            if let Some(word) = runtime.memory().fetch_u32(state.pc) {
                // Eight hex digits show all 32 instruction bits, including leading zero bits.
                println!("instruction: 0x{word:08x}");
            }
        } else {
            // Four hex digits show all 16 compressed-instruction bits.
            println!("instruction: 0x{half:04x}");
        }
    }
    if state.fault_access != jit::AccessKind::None {
        println!(
            "fault: {:?} at 0x{:x}",
            state.fault_access, state.fault_addr
        );
    }
    if let Some([nr, pc, a0, a1, a2, a3, a4, a5]) = runtime.last_syscall() {
        // RISC-V Linux puts as many as six syscall arguments in a0 through a5.
        // Keep the syscall number and PC beside them so a stop report identifies the call site.
        println!(
            "last syscall: {nr} at 0x{pc:x} (0x{a0:x}, 0x{a1:x}, 0x{a2:x}, 0x{a3:x}, 0x{a4:x}, 0x{a5:x})"
        );
    }
}

fn print_registers(state: &GuestState) {
    // The base RISC-V ISA defines 32 integer registers. The psABI gives them these readable names.
    const NAMES: [&str; 32] = [
        "zero", "ra", "sp", "gp", "tp", "t0", "t1", "t2", "s0", "s1", "a0", "a1", "a2", "a3", "a4",
        "a5", "a6", "a7", "s2", "s3", "s4", "s5", "s6", "s7", "s8", "s9", "s10", "s11", "t3", "t4",
        "t5", "t6",
    ];
    // A fixed 16-digit width makes changed bits easy to compare between debugger stops.
    println!("pc   0x{:016x}", state.pc);
    for (index, name) in NAMES.iter().enumerate() {
        println!("x{index:<2} {name:<4} 0x{:016x}", state.regs[index]);
    }
    // The runtime stores 32 floating-point registers directly after the 32 integer registers.
    for index in 0..32 {
        println!("f{index:<2}      0x{:016x}", state.regs[32 + index]);
    }
}

fn print_memory(memory: &GuestMemory, address: u64, length: usize) {
    // Sixteen bytes per row is a common hex-dump width and keeps addresses easy to scan.
    for offset in (0..length).step_by(16) {
        // The last row can contain fewer than 16 bytes.
        let count = 16.min(length - offset);
        let Some(bytes) = memory.load_bytes(address + offset as u64, count) else {
            println!("0x{:016x}: <unreadable>", address + offset as u64);
            return;
        };
        print!("0x{:016x}:", address + offset as u64);
        for byte in &bytes {
            // Two hexadecimal digits show all eight bits of one byte, including a leading zero.
            print!(" {byte:02x}");
        }
        println!();
    }
}

// hier landen libjit.so und generated.rs
// todo - generated.rs mergen
fn create_output_dir(input_file: &Path) -> io::Result<PathBuf> {
    let root = project_root()?.join("output");
    fs::create_dir_all(&root)?;

    let file_name = input_basename(input_file);
    let timestamp = Local::now().format("%Y-%m-%d_%H-%M-%S"); // todo - kann sein dass es mal doppelung gibt!

    // Timestamps separate and order normal runs. Two runs in one second can still reuse a directory.
    let output_dir = root.join(format!("run-{file_name}-{timestamp}"));
    fs::create_dir_all(&output_dir)?;

    Ok(output_dir)
}

fn project_root() -> io::Result<PathBuf> {
    // Derive the root from the crate location so the current working directory can be a guest workdir.
    // The first ancestor is `crates/remu`, the second is `crates`, and the third at index 2 is the root.
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .ancestors()
        .nth(2)
        .map(Path::to_path_buf)
        .ok_or_else(|| io::Error::other("project root not found!"))
}

fn input_basename(input_file: &Path) -> String {
    // Use the complete input only when it has no final file-name component.
    input_file
        .file_name()
        .unwrap_or(input_file.as_os_str())
        .to_string_lossy()
        .into_owned()
}