Writing a program

A Terse program is RV32IMC machine code in one image file: ROM from 0001_0000h, RAM from 0010_0000h, and calls to devices with ecall. It starts at the first ROM byte with sp at the end of RAM and all RAM zero. There are no interrupts: a program does a frame's work and calls wait_frame; if it runs out of budget first, it is paused and continues in the next frame without being told. This article shows how to build, run, test and publish one; the machine and each device have articles of their own.

Tools

You need clang with the riscv32 target, ld.lld and llvm-objcopy, and the terse command of this repository (cargo run -p terse-cli --bin terse --, or target/debug/terse after cargo build --workspace). Below, terse stands for either.

The compiler flags, the same in every programs/*/build.sh:

FlagWhy
--target=riscv32-unknown-elf32-bit RISC-V, no operating system
-march=rv32imc -mabi=ilp32exactly the machine's instruction set; no floating-point registers
-Ossmall code: ROM is at most 128 KiB and every instruction costs budget
-ffreestanding -nostdlib -fno-builtinno C library and no start files
-ffunction-sections -fdata-sectionswith --gc-sections at link time, unused functions are dropped

A C program's build, in fish as the README writes it (the build.sh scripts do the same in sh, and take CLANG, LLD, OBJCOPY, TERSE and CARGO from the environment):

set L programs/lib
set F --target=riscv32-unknown-elf -march=rv32imc -mabi=ilp32
set -a F -Os -ffreestanding -nostdlib -fno-builtin
set -a F -ffunction-sections -fdata-sections
clang $F -I $L -c $L/crt0.S -o 0.o
clang $F -I $L -c prog.c -o 1.o
clang $F -I $L -c $L/terse.c -o 2.o
ld.lld -T $L/terse.ld --gc-sections 0.o 1.o 2.o -o prog.elf
llvm-objcopy -O binary prog.elf prog.bin
terse pack --rom prog.bin --title prog --ram-pages 4 \
    --device 2:0 -o prog.terse

crt0.S must be linked first. The build is reproducible: the same sources and the same clang give the same image, and each program's test fails if its checked-in .terse is not what its sources build to.

The library

What terse.h provides, by area:

There is no other C library and no compiler runtime. Avoid floating point and 64-bit division, which need runtime routines that are not there (the link fails), or bring the routines yourself: crates/terse-core/tests/softfloat/softfloat.c is a tested IEEE double add, subtract, multiply and divide in integer C.

The hello program

programs/hello is written in assembly, hello.S, without the library: it shows how bare the machine is. Its build.sh assembles it with the same flags, links it alone with terse.ld, and packs it with one RAM page and the terminal (--device 2:0). It does this:

A test compares its screen after 30 frames with expected-30-frames.txt.

The same in C

#include "terse.h"

int main(void)
{
    terse_event e;
    term_color(15, 4);
    term_puts(" hello");
    term_cmd(TERM_CLEAR_EOL);
    term_color(7, 0);
    term_goto(0, 2);
    term_puts("> ");
    for (;;) {
        terse_wait_frame();
        while (terse_event_pop(&e)) {
            if (e.type == EV_TEXT) {
                uint32_t cp = e.a | e.b << 8
                    | (uint32_t)(e.c & 0x1F) << 16;
                term_put_cp(cp > 0xFFFF ? 0xFFFD : cp);
            } else if (e.type == EV_KEY_DOWN) {
                if (e.a == KEY_ENTER)
                    term_puts("\n> ");
                else if (e.a == KEY_ESCAPE)
                    return 0;
            }
        }
    }
}

Packing

terse pack --rom <raw.bin> --title <t> --ram-pages <n> [--device <slot:version>]... -o <out.terse> writes the image header before the raw ROM and checks the result as a host would. The title is at most 16 bytes; RAM is 1 to 128 pages of 8 KiB; at most 16 devices. It prints the file's size and its image ID.

SlotDevice--device
1Systemalways present, need not be listed
2Terminal2:0
32D vector display3:0
4Content4:0
5Messagesreserved
6Sound6:0
7Page7:0
8Machines8:0; only the shell of a system gets it
93D vector display9:0

A device the image does not list is absent: its calls return FFFF_FFFFh. A host refuses an image that needs a device version it does not have.

Running it headless

terse run prog.terse --frames 30 --dump

runs the image without a window for 30 frames (or until it stops; at most 36,000) and prints the 80 by 30 grid. Headless, the Unix time is 0, there are no random bytes (random gives zeros), and controllers exist only through the script. --dump-vectors and --dump-page add the vector display's list and the page as the reference layout lays it out. Content requests complete at the start of the next frame, so runs are reproducible. When the program exits, terse run exits with its code; after a fault it prints terse: fault: <kind> at pc <pc>, address <addr> on stderr and ends itself with SIGTERM.

--events <file> gives it input: one event per line, a frame number, a command and its arguments; blank lines and text after # are ignored (except in text). The events of a frame are delivered in the order written.

CommandArgumentsGives
downkey, then any of shift ctrl alt metakey down
upkey, modifierskey up
presskey, modifierskey down and key up in that frame
textthe rest of the lineone text event per character
pointerx, y, buttons 0 to 7 (optional)a pointer event, in screen units
clickx, ya press of the primary button there, then its release
wheelvertical, horizontal (optional)wheel steps; positive is down and right
feeds-updatednonea feeds-updated event
homenonethe home key (with --shell only)
padn, buttons, lx, ly, rx, ry (rx, ry optional)controller n's whole state from this frame on
padn, offcontroller n disconnected

A key is a USB HID usage ID (40 or 0x28) or a name: a-z, 0-9, f1-f12, enter, esc, backspace, tab, space, up, down, left, right, home, end, pageup, pagedown, insert, delete. Pad buttons are hexadecimal, the first button byte in bits 0-7 and the second in bits 8-15 (1 up, 2 down, 4 left, 8 right, 10 A, 20 B, 2000 Start); sticks are -127 to 127. A cell (column, row) starts at screen unit (column times 8, row times 16).

# type, press Enter, then quit
10 text hi
12 press enter
20 press esc

The state hash

--hash prints the machine's state hash after the last frame, 64 hex digits; --hash-every N prints <frame> <hash> after every frame whose counter is a multiple of N. The hash covers the machine's whole state (CPU, RAM, devices), and the machine is deterministic: the same image and the same recorded inputs give the same hashes on every conforming host. Tests record a script and the expected hashes; --save-state and --load-state save and resume a run. See The state hash.

Running it in a window

cargo run -p terse-host -- prog.terse

runs the image alone in a window at 60 frames a second, with every key (F12 included) going to it. The window closes when the program exits; after a fault it stays open with the fault on the bottom row and in the title. --screenshot out.png --frames 30 (with --events if wanted) runs headless and writes a picture instead. Using the shell and the reader shows the shell, where programs run side by side.

Costs to keep in mind

An instruction from ROM costs 1 unit, one from RAM 4. A call costs 5 (the ecall and 4) plus 1 per 4 bytes it copies, or 65 if it is answered (it asks a device for its state: get_cursor, get_colours, cells_read, content submit, page locate); write costs 2 per byte, and a clear or scroll command 150. A frame has 125,000 units. Writing a whole row with one write or term_cells_write is far cheaper than a call per character, and building a display list or document once and submitting it costs 1 unit per 4 bytes. The full table is in Charges and limits.

Publishing it

A program published in your feed has an identity, your feed key and its name, that stays the same from version to version:

terse feed publish --program prog.terse --name "Tiny tool"

checks the image and publishes it as a program entry; it prints seq N program <name> image <id>. The name defaults to the image's title and must be a display name: 1 to 48 bytes of UTF-8, no control characters, no space at either end. Publishing another image under the same name makes it the current version (the entry with the highest seq). Named records belong to the identity, so a new version keeps the old one's records (see Named records). terse key new creates your feed key if you have none.

Others subscribe to your feed (in the reader: F, then S, paste your key, Enter, then Y). Once their host has caught up with your feed it downloads the current version of each of your programs (images up to 131,136 bytes), and the shell's launcher lists it under "From your feeds" with your name and short key, marked ↓ until the image is there. Enter starts it in a tile of its own. An article may also link to it as terse:program/<feed key>/<name>; following such a link asks the shell to open it, and the shell asks the user first. See Feeds and The machines device.

Next: The machine, then the devices, from The system device and The terminal to Events.