The host is a freestanding x86-64 Linux executable. The linker script is “there is no linker script”: ld -static -nostdlib with _start in src/host/start.asm.
| rax | name | use |
|---|---|---|
| 0 | read |
-- guest ecall read, and reading source files |
| 1 | write |
stdout stats, stderr errors, guest write |
| 3 | close |
after openat |
| 8 | lseek |
asm file size |
| 9 | mmap |
one arena |
| 11 | munmap |
atexit-ish, also on host_die |
| 60 | exit |
_exit |
| 228 | clock_gettime |
optional wall clock next to rdtsc |
| 257 | openat |
AT_FDCWD, source and image files |
No brk. No ioctl. No writev. Formatting is userspace into a 4 KiB scratch buffer, then one write.
mmap flags: MAP_PRIVATE | MAP_ANONYMOUS. Prot: READ | WRITE. The arena is not MAP_HUGETLB by default; a comment in mem.asm says how to turn it on if you have pages.
System V AMD64, because NASM call to our own functions should look like every other Linux binary if we ever grow a C test harness (we did not).
- Args:
rdi, rsi, rdx, rcx, r8, r9 - Volatile:
rax, rcx, rdx, rsi, rdi, r8-r11 - Callee-saved:
rbx, rbp, r12-r15 - Return:
rax(value or negative-errnofor host I/O wrappers) - Stack 16-byte aligned at
call
Booleans are 0 / 1 in eax, not flags, unless the function is documented as “ZF means miss.” Cache probes return ZF miss for compactness on the LSU path. That is the only flag-return.
arena_init(size) -> pointer, also stored in [g_arena]
arena_alloc(bytes, align) -> pointer ; bump, never free
arena_reset() ; only between tests
Bump pointer is 8-byte aligned at minimum. cpu_init asks for the CPU, then ROB, RS arrays, predictor tables, cache tag arrays, guest RAM, in that order. Tests that run back-to-back call arena_reset and cpu_init again.
OOM: if the bump would exceed the mapping, host_die("arena: out of memory"). Size is cpu_struct + 64MiB RAM + ~2MiB tables by default, mapping 80 MiB to have slack.
src/host/io.asm is a tiny stdio:
io_write(fd, buf, len)io_cstr(fd, zstring)io_u64(fd, val, width, base), base 10 or 16, width 0 means no padio_i64, sign thenio_u64io_hex32,0x+ 8 digitsio_nl,io_sp,io_chr
No printf. A stats line is a sequence of those calls. That is annoying to write and impossible to format-string inject.
src/host/hash.asm. Open addressing, FNV-1a 64 of a byte string, linear probe, tombstones for delete (assembler does not delete; the API still has it).
hash_init(map, cap_pow2, arena)
hash_put(map, key, keylen, val) -> 0 ok, -1 full
hash_get(map, key, keylen, *val) -> 0 hit, -1 miss
Used for labels and .equ. Cap starts at 1024. hash_grow allocates 2x from the arena and reinserts. Old table is leaked in arena terms, bump allocators do that. Assembler runs once per process in run, many times in test; tests arena_reset.
rdtsc is serialized with lfence before and lfence after the measured region, not rdtscp + cpuid (cpuid is a VM exit on some hosts and makes the histogram about the hypervisor). Histogram is a 64-bucket log2 of cycle deltas for ooo_tick and for interp_step, so you can see tail behavior of the simulator.
clock_gettime(CLOCK_MONOTONIC) is used only in bench for a human-readable ns number next to TSC.
start.asm walks argv. Flags are exact matches (--mode, --stats, …). Unknown flags die. --mode ooo and --mode functional are the only modes. --mem accepts 64m, 64M, 67108864.
host_read_file(path, *ptr, *len) allocates a buffer from the arena, reads the whole file. Max source 2 MiB. The assembler holds pointers into that buffer; it does not copy lines.
host_die(msg):
write(2, "planck: ", 8)
write(2, msg, strlen)
write(2, "\n", 1)
exit(1)
No unwind. Guest traps that halt without mtvec go through cpu_halt_dump, which is not host_die: exit code is 0 if the guest ecall exit 0, 1 if a fault, or the guest code.