# How translation works

## A process, not a machine

Champollion is user-mode only. A guest program is not a simulated machine; it
is the host process itself. `rvrun` loads the ELF, maps its segments into a
reserved guest address space, and starts executing at its entry point. When the
program makes a system call, the runtime serves it — implemented directly
where possible, translated to the host where it is not.

## From file to first instruction

The loader parses the ELF, maps its segments into guest memory (a 256 GiB
reservation; on macOS a guest address is a fixed offset into it, on arm64 Linux
guest addresses are host addresses), builds the initial Linux stack, and
relocates static-PIE images. When the program is dynamically linked, its
`PT_INTERP` — musl's `ld-musl-riscv64.so.1` — runs first, resolved against the
sysroot passed with `-L`.

## Two engines, one oracle

The interpreter fetches and decodes every instruction it executes, and it is
the permanent oracle: the other engines are diffed against it rather than
trusted. The fast engine keeps a cache of decoded blocks, chained to their last
two successors, plus a per-thread software TLB over the guest's 4 KiB pages.
The cache is dropped when memory mappings change or the guest runs `fence.i`.

The `riscv-tests` suite runs the fast engine and the JIT against the
interpreter and requires identical state at the end of every case.

## The JIT

Blocks are translated to arm64 by a hand-written encoder whose output is
checked against the assembler in tests. Generated code keeps guest addresses
masked into the reservation and reaches translated successors through a jump
cache. Translated blocks are saved per executable in a persistent cache
(`~/Library/Caches/champollion` by default), so the second run of a program
starts translated; `RVRUN_CACHE=0` turns that off, and `RVRUN_JIT=0` drops
back to the interpreter.

## Syscalls and signals

Guest syscalls use the Linux ABI. Some are served by the runtime itself
(`mmap`, `brk`, and similar calls); the rest cross a small `HostOs` interface.
macOS backend translates the differences — `open` flag bits, errno values,
signals, `flock` — and its Linux backend passes calls straight to the kernel,
identity address space included. Errors come back as Linux errno values either
way, and a host thread pumps signals into the guest.