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:
- bytes 0 to 3:
TERS; byte 4: 0, the format; byte 5: 1, the machine profile; - bytes 6 to 8: the ROM's length, 1 to 131,072, least significant byte first;
- byte 9: RAM in pages of 8 KiB, 1 to 128; byte 10: the number of device entries, 0 to 16;
- bytes 11 to 15: zero; bytes 16 to 31: the title, padded with zero bytes.
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:
106h,exit: the machine stops with exit codea0&FFh. Like every call it then writes its result, 0, toa0, andpcmoves past theecall.- A call you do not have: put
FFFF_FFFFhina0and go on.
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.