pages / How it works
How it works
docs/armless.md has the design in full; the main points:
- Interpreter and JIT. The interpreter decodes and runs instructions. Hot entries (1024
runs by default,
ARMLESS_JIT_THRESHOLD) are compiled a page at a time: to WebAssembly in the browser, to host code with Cranelift natively, on a compiler thread per CPU. Compiled code covers the integer instructions, SIMD&FP loads and stores, the common integer NEON operations, scalar floating point (inline when FPCR is as Linux runs it and the numbers are ordinary), and in-page indirect branches. Vector floating point runs lane by lane through the interpreter's arithmetic; atomics and crypto instructions go to the interpreter. Anything else is handed to the interpreter one instruction at a time. - Native JIT.
ARMLESS_JIT=nativeturns it on forrunner::new_vm(or callCpu::enable_native_jit). It needs no hypervisor, so it works in sandboxes. Each CPU keeps up toARMLESS_JIT_CODE_MB(default 16) MB of compiled code and starts over when full.armless-run --fallbacksorARMLESS_JIT_HELPER_STATS=1counts what falls back to the interpreter, by opcode. - Warm JIT. A restore starts with no compiled code.
Runner::jit_profilelists the pages a machine compiled and ran,jit::profile::mergecombines the profiles of many runs, andRunner::jit_prewarmcompiles a profile's pages as soon as a machine restored from the same snapshot starts. A page that holds other code than when it was profiled is skipped. - Hardware backends.
ARMLESS_HV=1with thehypervisorfeature runs the CPUs on the host's own cores where Hypervisor.framework (Apple silicon) or/dev/kvm(Linux arm64) is available, and falls back to the interpreter and JIT otherwise. See docs/hypervisor.md, including the macOS entitlement. - MMU. A software page-table walker with a direct-mapped TLB, ASID-aware; TLBI by VA invalidates what it names and other invalidations flush everything. With several CPUs, TLB shootdowns are delivered between them. Code pages written by the guest or by DMA are invalidated on every CPU.
- SMP. One host thread or Web Worker per CPU. Devices run on whichever thread touches
them, under one lock. Atomics are host compare-and-swap on guest RAM. In the browser,
armless-smp.wasmimports a shared memory that every worker instantiates on. - Devices. UART, GIC and RTC are memory-mapped; the virtio devices sit on a PCI bus in
fixed slots (1 console, 2 9p with tag
host9p, 3 network, 4 free page reporting). The machine never calls the host synchronously: what the host must do is queued as events and answered throughBoard. - Snapshots. CPUs, GIC, timers, device state and the filesystem tree (with the files the guest wrote), plus every non-zero RAM page, in a streamable format. Blobs are not saved; the guest's unmodified files are fetched again after a restore. A machine can be saved as one of its first n CPUs once the guest has taken the others offline.
- Browser memory model. WebAssembly memory never shrinks, so every peak stays committed
until the page goes. The decompressed file cache is capped (
fs_cache_mb), files the guest writes grow a chunk at a time, a restore only commits the pages the snapshot holds, and a save is produced a piece at a time rather than as one buffer the size of the snapshot. With a large guest, write or compress the pieces as they arrive instead of callingsave_state(), which joins them into one buffer.