The machine

This article describes machine profile 1, the only profile so far: the CPU, the memory map, how frames and the budget work, how a machine stops, the image file a program is shipped in, and how programs call devices, with the complete table of calls. Each device's calls are described in full in that device's article.

The machine is the optional third layer of Terse: the network and the article format are the core, and a reader can implement them without it. A machine host that only wants to run the reader may provide the machine's reading profile: the machine and devices 1, 2, 4 and 7, with every content operation the reader needs (get, subscriptions, timeline, names, identity, subscribe, unsubscribe); it may answer the others with status 05h, and lacks devices 3, 8 and 9, so it refuses an image that lists them. terse run --profile reading runs a machine that way.

CPU

The CPU executes exactly RV32I with the M (multiply and divide) and C (compressed) extensions, little-endian, in user mode. There is no A, F, D or B extension, no Zicsr or Zifencei, and no privileged architecture: no control and status registers, counters or traps are visible.

InstructionBehaviour
FENCE (funct3 = 0, including FENCE.TSO, PAUSE, hint forms)does nothing
HINT encodings (c.addi x0, 5, slli x0, x0, 3, ...)execute as written; writes to x0 are discarded
div, divu by zerogive all ones; no trap
rem, remu by zerogive the dividend
div of −2³¹ by −1gives −2³¹; rem gives 0
jumps and branchestargets need only be even; jalr clears bit 0
loads and storesmust be aligned to their size (2 or 4), else a misaligned fault
ecalla device call (see Calls below)

A jump to an address outside ROM and RAM faults when the instruction there is fetched, not at the jump. Everything else faults as an illegal instruction: ebreak and c.ebreak (a breakpoint fault); every reserved or illegal encoding, including the all-zero parcel c.unimp, C.ADDI4SPN, C.ADDI16SP and C.LUI with a zero immediate, C.LWSP and C.JR with register 0, compressed shifts with shamt[5] set, C.SUBW, C.ADDW and the reserved MISC-ALU codes, every compressed floating-point load or store, all 48-bit and longer encodings, CSR instructions, FENCE.I, MRET, WFI and the other privileged encodings.

Memory map

AddressContentsAccess
0001_0000h to 0001_0000h + rom_len − 1ROM: the image's bytesread, execute
0010_0000h to 0010_0000h + 8,192 × ram_pages − 1RAMread, write, execute
everything elsenothingany access faults

So address 0 faults, a store to ROM faults, and so does fetching an instruction any part of which lies outside ROM and RAM (for example a 32-bit instruction whose second half would be past the end of ROM). Code may run from RAM; an instruction fetched from RAM is decoded when it is executed, so code written to RAM takes effect at once, but each such instruction costs 4 units instead of 1.

Reset state

Frames and the budget

Time advances in frames, nominally 60 a second. There are no interrupts. For each frame the host does, in order:

StepWhat happens
1appends the frame's input events to the event queue, latches the clock, the random bytes and the controllers, and applies the content completions it has for this frame (their content-done events come after the input events)
2adds 125,000 to the budget, subtracts the charge for the content delivered in step 1, and runs the CPU while the budget is greater than zero
3ends the frame: the frame counter increases by one, and the host presents the terminal, the vector displays and the page as they are now
RuleDetail
Instruction cost1 unit fetched from ROM, 4 fetched from RAM
ecall cost1 (or 4 from RAM) plus the call's charge
Overrunan instruction that starts with a positive budget runs to completion, so the budget can end below zero
Negative carrya negative remainder carries into the next frame; if it exceeds a whole frame's budget, that frame runs nothing and the rest carries on
No positive carryunused budget never carries forward
Running outthe machine pauses and continues with the next instruction in the next frame; the program is not told
wait_framethe rest of the budget is discarded and the call returns at the start of the next frame, which always runs (content delivered in a frame costs at most 32,768 units)
Stoppingexit or a fault stops the machine at once; the rest of the budget is dropped, the frame still counts, nothing runs later

A host that falls behind real time lets virtual time lag; it never runs extra frames to catch up. In a system of several machines each machine has its own budget, carry and frame counter.

Stopping and faults

A machine is running, or stopped by an exit or a fault. A fault has no exit code, and a host must show a fault as a fault, with its kind and addresses. The faulting instruction is not executed and not charged, and pc is left pointing at it.

StoppedCauseRecorded
Exitthe exit callthe exit code, 0 to 255
Faultone of the kinds belowthe kind, pc and an address
NumberFault kindCauseAddress recorded
1Illegal instructiona reserved, illegal or unsupported encoding; the 16- or 32-bit encoding is recorded toopc
2Breakpointebreak, c.ebreakpc
3Fetchan instruction, or its second half, is not in ROM or RAMthe address that could not be fetched
4Loada load from outside ROM and RAMthe load address
5Storea store outside RAM (ROM included)the store address
6Misaligneda load or store not aligned to its sizethe access address

The numbers are those of the state serialization and of the shell's info record.

The image format

A program is one file (suggested extension .terse): a 32-byte header, the device requirements, then the ROM. All numbers are little-endian.

OffsetSizeField
04Magic: 54h 45h 52h 53h (TERS)
41Format version: 0
51Machine profile: 1
63rom_len: 1 to 131,072
91ram_pages: 8 KiB pages of RAM, 1 to 128
101n_dev: device requirements, 0 to 16
115Reserved, zero
1616Title, UTF-8, padded with 00h
322 × n_dev(device slot, device version) pairs
32 + 2 × n_devrom_lenROM; byte 0 is at 0001_0000h
SlotDeviceVersionStatus
1System0specified; reading profile
2Terminal0specified; reading profile
32D vector display0specified
4Content0specified; reading profile
5Messagesnonereserved
6Sound0specified; optional
7Page0specified; reading profile
8Machines0specified; only the shell of a system has it
93D vector display0specified

Slots 0 and 10 to 255 are not devices.

Calls

A program reaches a device with ecall. Register a7 holds the call number, (device slot << 8) | function; arguments are in a0 to a5; the result is in a0, and a second result in a1 where listed. A call changes no other register and no memory but the buffers it is said to write; pc continues after the ecall.

In C, terse.h has a constant for every call (CALL_WAIT_FRAME, ...) and the inline functions terse_call, terse_call4, terse_call5 and terse_call2 (for two results).

Call table

Class sets the base charge: 4 for a deferred call (its result and charge follow from its arguments), 64 for an answered one (they depend on the device's state). System and Machines calls cost 4.

The system device, slot 1, always present:

a7CallArgumentsResult
100hwait_framenonethe frame counter in the frame it returns in
101hnext_eventa0 = buffer (4 bytes, written)1 and the event, or 0 if the queue is empty
102hframe_countnonethe frame counter
103hunix_timenonethe Unix time latched at the start of the frame
104hrandoma0 = buffer (written), a1 = length, at most 256the length
105hcontrollera0 = controller number, a1 = buffer (8 bytes, written)byte 0 of the state
106hexita0 = exit code (low 8 bits)does not return
107hopena0 = address of an open request (read)1 passed to the shell, 0 not
108hargumenta0 = buffer (32 bytes, written)1, or 0 if the machine has none

The terminal, slot 2:

a7CallArgumentsResultClass
200hwritea0 = buffer (read), a1 = length, at most 4,096the lengthdeferred
201hcommanda0 = command0deferred
202hset_cursora0 = column, a1 = row0deferred
203hget_cursornonea0 = column, a1 = rowanswered
204hset_coloursa0 = foreground, a1 = background0deferred
205hget_coloursnonea0 = foreground, a1 = backgroundanswered
206hcells_reada0 = first cell, a1 = buffer (written), a2 = countthe countanswered
207hcells_writea0 = first cell, a1 = buffer (read), a2 = countthe countdeferred
208hpalette_seta0 = first entry, a1 = buffer (read), a2 = countthe countdeferred
209hsizenonea0 = 80 columns, a1 = 30 rowsdeferred

The 2D vector display, slot 3:

a7CallArgumentsResultClass
300hsubmita0 = list address, a1 = length0 done, 1 rejecteddeferred
301hclearnone0deferred
302hstylea0 = style0 done, 1 rejecteddeferred
303hpersistencea0 = persistence0 done, 1 rejecteddeferred
304hfilla0 = fill mode0 done, 1 rejecteddeferred

The content device, slot 4 (see blobs, feeds and named records):

a7CallArgumentsResultClass
400hsubmita0 = address of a request blocka handle 1 to 8, or 0 if rejectedanswered

The page, slot 7:

a7CallArgumentsResultClass
700hsubmita0 = document address, a1 = length0 done, 1 rejecteddeferred
701hclearnone0deferred
702hregiona0 = x, a1 = y, a2 = width, a3 = height0deferred
703hscrolla0 = y0deferred
704hbackgrounda0 = colour0deferred
705hlocatea0 = anchor id0 done, 1 rejectedanswered

Machines, slot 8, the shell only:

a7CallArgumentsResult
800hstarta0 = image ID address (32 bytes, read)a handle 1 to 8, or 0 if none is free
801hstopa0 = handle1, or 0 if not in use
802hplacea0 = handle, a1 = x, a2 = y, a3 = width, a4 = height1, or 0 if not in use
803hruna0 = handle, a1 = 1 run, 0 pause1, or 0 if refused
804hfocusa0 = handle, or 01, or 0 if refused
805hinfoa0 = handle, a1 = buffer (48 bytes, written)1, or 0 if the handle is not 1 to 8
806hbuiltina0 = index, a1 = buffer (32 bytes, written)1, or 0 past the last
807hstart_programa0 = program record address (read)a handle 1 to 8, or 0 if none is free
808hidentitya0 = handle, a1 = buffer (81 bytes, written)1, or 0 if it has none
809hrequesta0 = handle, a1 = buffer (82 bytes, written)1, or 0 if no request waits
80Ahargumenta0 = handle, a1 = blob ID address (32 bytes, read)1, or 0 if not loading
80Bhsnapshota0 = handle, a1 = slot1 accepted, 0 refused
80Chrestorea0 = slota handle 1 to 8, or 0 if none is free or the slot is out of range
80Dhsnapshot_infoa0 = slot, a1 = buffer (122 bytes, written)1 if the slot holds a snapshot, else 0
80Ehsnapshot_deletea0 = slot1, or 0 if the slot is out of range
80Fhfacea0 = handle, a1 = frames, a2 = x, a3 = y, a4 = width, a5 = height1, or 0 if refused
810hunfacea0 = frames1, or 0 if refused

The 3D vector display, slot 9:

a7CallArgumentsResultClass
900hsubmita0 = list address, a1 = length0 done, 1 rejecteddeferred
901hclearnone0deferred
902hstylea0 = style0 done, 1 rejecteddeferred
903hpersistencea0 = persistence0 done, 1 rejecteddeferred

Screen units

Every device that draws, and the pointer, uses one coordinate system: the screen is 640 units wide and 480 high, (0, 0) at the top left, x to the right and y down. Units are square; the host shows the screen at a 4:3 shape, so a circle is round. A terminal cell is 8 units wide and 16 high: the cell at (column, row) starts at x = column × 8, y = row × 16. The vector displays use sixteenths of a unit for finer positions.