Make a host, step 1: run a program to its end

A host runs Terse32 programs: it reads a program file, runs its instructions and gives the program its devices. You can write one in any language and check it against the reference exactly. The specifications cover every device; a host starts much smaller. This guide builds one in four tested steps: run a program until it stops (this page), keep time, show hello through the reference terminal, prove the host exact. Each says how much code it took in tcore, a core written in C from the specifications alone (native/core-c).

The program file

A program file (.terse) starts with a 32-byte header:

Two bytes per device entry follow, then the ROM. Refuse a file whose length is not exactly 32 + 2 × entries + the ROM's length. Until step 3, run only programs that list no devices.

Memory and reset

The ROM, the program's bytes, is at 0001_0000h, to read and execute. The RAM, all zero, is at 0010_0000h, to read, write and execute. Nothing else is there. Start at the first byte of ROM, with sp (x2) at the end of RAM, 0010_0000h + 8,192 × pages, and every other register 0.

The processor

RV32IMC: RISC-V's 32-bit integer instructions with multiply and divide (M) and the 16-bit compressed forms (C), in user mode: no floating point, atomics, control registers or interrupts. fence does nothing; division by zero gives RISC-V's answers, not a trap.

A fault stops the machine: an instruction it does not have (ebreak, the CSR instructions and every reserved encoding among them), a fetch or load outside ROM and RAM, a store outside RAM, or a load or store at an address that is not a multiple of its size. The faulting instruction is not carried out and pc stays on it. Show the user the fault, never an exit code.

Calls

ecall calls a device: a7 holds the device's slot × 256 + the function, a0 to a5 the arguments, and the result goes in a0. Two cases are enough now:

Check yourself

STATE.md gives a 42-byte program that exits with code 7: c.li a0, 7, addi a7, x0, 106h, ecall. Make the file:

xxd -r -p > exit.terse <<EOF
5445525300010a000001000000000000657869740000
000000000000000000001d459308601073000000
EOF

Your host should stop with exit code 7, pc = 0001_000Ah, a0 = 0 and a7 = 106h. The reference's exit status is the program's exit code, 7:

terse run exit.terse --frames 1
echo $?

This one adds 100 + 99 + ... + 1 and exits with the sum's low byte, 186:

xxd -r -p > sum.terse <<EOF
544552530001160000010000000000007375
6d0000000000000000000000000001459302
40061695fd12e39e02fe9308601073000000
EOF

How much code

In tcore the processor is 262 lines of C (cpu.c); the file and the memory map about 50 more.

What you have now

A Terse32 processor that runs a program to its end. Next, make it keep time: Make a host, step 2: frames and the budget.

The detail is in The Terse32 machine, sections "CPU", "Memory map", "Reset state", "Stopping and faults", "The image format" and "Calls" (SPEC §cpu, §memory, §reset, §stopping, §image, §calls.convention), and exit in The system device.