The Machines device (device 8)

A host can run several machines as one system. One of them, the shell, starts the others, decides where their screens are shown and which of them gets the keyboard, through device 8 (slot 8, version 0). Layout and policy are the shell's.

Who has it

The shell has device 8 if its image lists (8, 0) (terse pack --device 8:0) and the host starts it as the shell (terse run --shell <image>, terse-host --shell <image>). For every other machine, and an image run alone, every call returns FFFF_FFFFh. At reset no handle is in use, the focus is 0 and there is no view.

Handles and states

The shell starts machines under handles 1 to 8. Each is a complete, separate machine with its own ROM, RAM, devices, events, content handles, budget, frame counter and 640 x 480 screen; machines share only the host's store, feeds and identity. A handle is in use from the call that returns it until a stop.

ValueStateMeaning
0nonenot in use
1loadingthe host does not have the image yet
2runningruns a frame in every system frame
3pausedruns no frames, receives no input
4exitedstopped by exit
5faultedstopped by a fault
6failedcould not start; info gives the reason

Each handle also has a run flag, a rectangle (x, y, width, height in the shell's screen units) and possibly an identity. The focus is a handle, or 0 for the shell. The system also has a view of the shell's 3D scene, set by face (see Screens and the view, below).

A program's identity is (publisher's feed key, name), as in a program entry of a feed. Built-in programs have 32 zero bytes and their image title. A machine started with start_program keeps that identity for life; one started with start has none; a restored one has its snapshot's. Identity decides whose named records a machine reads (named records).

Calls

a7CallArgumentsResult
800hstarta0 = image ID (32, read)handle, 0 none free
801hstopa0 = handle1, 0 not in use
802hplacea0 handle, a1-a4 x y w h1, 0 not in use
803hruna0 handle, a1 1 run 0 pause1, 0 refused
804hfocusa0 handle or 01, 0 refused
805hinfoa0 handle, a1 buffer (48, written)1, 0 not 1-8
806hbuiltina0 index, a1 buffer (32, written)1, 0 past last
807hstart_programa0 program record (read)handle, 0 none free
808hidentitya0 handle, a1 buffer (81, written)1, 0 none
809hrequesta0 handle, a1 buffer (82, written)1, 0 none waits
80Ahargumenta0 handle, a1 blob ID (32, read)1, 0 not loading
80Bhsnapshota0 handle, a1 slot1, 0 refused
80Chrestorea0 slothandle, 0
80Dhsnapshot_infoa0 slot, a1 buffer (122, written)1 held, 0
80Ehsnapshot_deletea0 slot1, 0 out of range
80Fhfacea0 handle, a1 frames, a2-a5 x y w h1, 0 refused
810hunfacea0 frames1, 0 refused

A read buffer must lie wholly in ROM or wholly in RAM, a written one wholly in RAM, else the call returns FFFF_FFFEh and does nothing else. The reference host checks the buffer before the handle or slot.

Records

The info record (48 bytes, mach_record in terse.h), as latched at the start of the frame plus the shell's own calls since:

OffsetSizeField
01State
11Exit code if exited, else 0
21Fault kind if faulted (1 illegal instruction, 2 breakpoint, 3 fetch, 4 load, 5 store, 6 misaligned), else 0
31Failure reason if failed, else 0
44Units used in the machine's last frame (delivered content included), 0 before its first
84The machine's frame counter
124Fault pc if faulted, else 0
1632Image ID (see below)

The image ID is the one given to start. For start_program and restore it is zero while loading, then the ID of the image the host got, also when that image failed to run or to fit the snapshot.

ReasonWhy the start failed
1not found (no such blob or program)
2not a valid image
3needs a device (slot, version) the host lacks
4no room for another machine
5restore: no snapshot in the slot, unreadable, or does not fit its image

The request record is 82 bytes: the kind (1), then for kind 1 (a blob) the blob ID (32) and zeros, for kind 2 (a program) the 81 bytes identity writes.

The snapshot_info record (122 bytes, mach_snapshot_record):

OffsetSizeField
01Present: 1, or 0 for an empty slot
132Image ID
3381Identity as identity writes it; zero for none
1144The machine's frame counter when taken
1184The Unix time latched for its last frame, as its state holds it (0 if it never ran)

Events for the shell

TypeNameab
0AhMachine changedhandlenew state
0BhHome00
0ChMachine pressedhandlebuttons
0FhOpen requestedhandle0
10hSnapshot doneslot1 stored, 3 failed

c is 0. Machine changed is sent for each change the shell did not make by a call: loading to running, paused or failed; running to exited or faulted. If the focused machine exits, faults or fails, the focus becomes 0 (no home event). Open requested comes once per request. Snapshot done comes once per accepted snapshot, in call order; failed means the machine was stopped in the same frame or the host could not store it. See events.

Screens and input

A machine's picture is its screen scaled into its rectangle. In the shell's 3D list a Screen shows a machine as a panel in space instead, and face flies a panel flat onto the glass. How pictures, panels and the view are drawn, how input is routed to them and the home key are in screens, panels and input.

The system frame

1. Latch. In handle order: loading handles whose image arrived or failed become running, paused or failed (a new machine is reset with its argument, or is the restored one); running handles whose machine stopped become exited or faulted; each change queues machine changed; records take units and frame counters. Then open requested for each open request of the last frame, in handle order, then snapshot done events, all before the frame's input. 2. Route the input. 3. The shell runs its frame. If the view's machine is no longer shown as a panel, the view becomes none. 4. Its starts and stops are carried out in call order. A machine started now runs first in the next system frame. 5. Each running machine, in handle order, runs one frame with a full budget and its own carry. So run, stop and place take effect this frame; focus takes effect at the next frame's routing, for keys, text, the pointer and the controllers alike. 6. Snapshots and deletes, in call order.

Other machines run no frames. When the shell stops, the system stops.

Snapshots

A snapshot is a machine's state serialization (holding its image ID and argument) plus its identity. A restored machine has the state hash it had when taken and, given the same later inputs, runs as it would have; its frame counter continues.

Determinism and state

Each machine is deterministic given its own inputs. The shell's include its device 8 events and what the device reports that the shell did not set (latched records, identities of restored or by-name programs, requests, built-ins, snapshot_info). For a started machine, what open returns is an input. The view is the shell's own state; the eye the host routes the pointer by is an input. Device 8's state is part of the shell's; a started machine's state holds nothing of the system.

Charges

Each call costs 4 (plus the ecall instruction), and copies cost 1 per 4 bytes, rounded up: start 8 (when the ID is read), start_program (33 + n) / 4 up, info 12, builtin 8, identity 21, request 21, argument 8 (when the ID is read) and snapshot_info 31, each when written. face and unface copy nothing; drawing the scene is the host's work. See charges.

Example: a minimal shell

#include "terse.h"

static uint8_t id[32], req[82];

int main(void)
{
    terse_event ev;
    uint32_t h = mach_builtin(0, id) ? mach_start(id) : 0;
    if (h) {
        mach_place(h, 0, 0, 640, 480);
        mach_focus(h);
    }
    for (;;) {
        while (terse_event_pop(&ev)) {
            if (ev.type == EV_MACHINE_PRESSED)
                mach_focus(ev.a);
            else if (ev.type == EV_MACHINE_CHANGED
                     && ev.b >= MACH_EXITED)
                mach_stop(ev.a);
            else if (ev.type == EV_OPEN_REQUESTED
                     && mach_request(ev.a, req) && req[0] == 1
                     && (h = mach_start(req + 1)) != 0)
                mach_place(h, 0, 0, 640, 480);
        }
        terse_wait_frame();
    }
}

It starts the first built-in full screen with the keyboard, stops machines that end and opens requested blobs as new machines.