The terminal (device 2)

The terminal is a grid of 80 columns by 30 rows of character cells, held by the device rather than in the program's memory. A program writes UTF-8 text to it the way it would to a simple console, or reads and writes the cells directly. It is the text layer of the screen: the host draws it over the vector displays and the page.

Getting the device

The terminal is slot 2, version 0. An image gets it by listing (2, 0) among the device requirements in its header, which terse pack ... --device 2:0 does. In an image that does not list it, every call from 200h to 2FFh returns FFFF_FFFFh and does nothing else. With the device present, a call number in that range that is not one of the ten below (20Ah and up) also returns FFFF_FFFFh.

The grid

The grid is 2,400 cells (9,600 bytes). Cell number row * 80 + column is the cell at (column, row), with (0, 0) at the top left. On the 640 by 480 unit screen a cell is 8 units wide and 16 high, so the cell at (column, row) covers x from column * 8 and y from row * 16.

Each cell is four bytes:

ByteField
0Character code, low byte
1Character code, high byte
2Foreground palette index
3Background palette index

The character code is a Unicode code point from 0000h to FFFFh. A character is wide if its Unicode 16.0 East Asian Width property is W or F (including unassigned code points that Unicode gives W by default, such as U+FA6E); every other character is narrow. A wide character takes two cells of a row: the left cell holds its code and the right cell holds the continuation code FFFFh (TERM_CONTINUATION in terse.h; term_is_wide tells whether a code point is wide). Combining marks get no special treatment: each takes a cell.

Calls

a7CallArgumentsResultClass
200hwritea0 buffer, a1 length (at most 4,096)the lengthdeferred
201hcommanda0 command0deferred
202hset_cursora0 column, a1 row0deferred
203hget_cursornonea0 column, a1 rowanswered
204hset_coloursa0 fg, a1 bg0deferred
205hget_coloursnonea0 fg, a1 bganswered
206hcells_reada0 first, a1 buffer, a2 countcountanswered
207hcells_writea0 first, a1 buffer, a2 countcountdeferred
208hpalette_seta0 first, a1 buffer, a2 countcountdeferred
209hsizenonea0 = 80, a1 = 30deferred

An answered call (its result depends on the terminal's state) costs 64, a deferred one 4; see Charges below.

A buffer the device reads must lie wholly in ROM or wholly in RAM; one it writes must lie wholly in RAM; an empty one may be anywhere. Otherwise the call returns FFFF_FFFEh (a bad buffer) and does nothing else.

Put character

The bytes given to write are decoded as UTF-8. When a character is complete it is handled by this table:

CharacterAction
08hCursor left one column, stopping at column 0
09hCursor to the next column that is a multiple of 8, stopping at column 79
0AhCursor to column 0 of the next row; scrolls up if on the last row
0ChClear the grid and move the cursor to (0, 0)
0DhCursor to column 0
other below 20h, and 7FhIgnored
anything elsePrinted

Printing a character takes four steps:

So writing in the last column does not scroll at once: the wrap happens only when the next printable character arrives. Pending wrap is cleared by step 1, by the control characters 08h, 09h, 0Ah, 0Ch and 0Dh, by set_cursor, and by command 01h. Ignored control characters leave it set.

The code point FFFFh is written as FFFDh, so put character never creates a continuation cell on its own.

Malformed UTF-8 and code points above FFFFh are written as FFFDh. Each maximal invalid prefix of a sequence produces one FFFDh (the WHATWG rule), and the byte that interrupted the sequence is decoded afresh. Overlong forms and surrogates are malformed. In terms of bytes:

Lead byteSecond byte allowedBytes
00h-7Fhnone1
C2h-DFh80h-BFh2
E0hA0h-BFh3
E1h-ECh, EEh-EFh80h-BFh3
EDh80h-9Fh3
F0h90h-BFh4 (gives FFFDh)
F1h-F3h80h-BFh4 (gives FFFDh)
F4h80h-8Fh4 (gives FFFDh)

Later bytes of a sequence must be 80h-BFh. Any other lead byte (80h-C1h, F5h-FFh) gives one FFFDh. For example the bytes E2h 82h 41h give FFFDh and then A; a complete valid four-byte sequence gives a single FFFDh.

Commands

ValueCommand
01hClear: every cell becomes a space with the current colours; cursor to (0, 0)
02hScroll up one row; the bottom row is cleared
03hScroll down one row; the top row is cleared
04hClear from the cursor to the end of the row (see below)
05hShow the cursor
06hHide the cursor

"Cleared" means a space (0020h) with the current colours. For 04h, if the cursor is on the right half of a wide pair, the left half becomes a space and keeps its colours. Commands 02h to 06h leave the cursor and pending wrap as they are; 01h clears pending wrap. In terse.h the values are TERM_CLEAR, TERM_SCROLL_UP, TERM_SCROLL_DOWN, TERM_CLEAR_EOL, TERM_CURSOR_ON and TERM_CURSOR_OFF; term_cmd sends one.

Reset state and palette

At reset every cell is a space with foreground 7 and background 0. The cursor is at (0, 0) and shown, pending wrap is clear and no UTF-8 sequence is pending. The palette is the xterm 256-colour palette:

EntriesColours
0-7000000, CD0000, 00CD00, CDCD00, 0000EE, CD00CD, 00CDCD, E5E5E5
8-157F7F7F, FF0000, 00FF00, FFFF00, 5C5CFF, FF00FF, 00FFFF, FFFFFF
16-231cube: entry 16 + 36r + 6g + b, each of r, g, b 0-5 meaning 00h 5Fh 87h AFh D7h FFh
232-255grey: entry 232 + i has each component 8 + 10i

Charges

WhatCharge
Any call, also one that fails4; 64 for get_cursor, get_colours and cells_read (answered)
write: each byte of the buffer2
A clear, scroll up or scroll down by command150
cells_read, cells_write, palette_set1 per 4 bytes copied, rounded up

The 150 applies to commands 01h, 02h and 03h only: the scrolls and clears a write causes (0Ch, 0Ah on the last row, a wrap on the last row) are paid for by its 2 per byte, so a host makes them cheap (a scroll costs it one row at most). Copies are charged only when the call succeeds: cells_write of all 2,400 cells costs 4 + 2,400 = 2,404 units and cells_read of them 64 + 2,400, on top of the ecall instruction. See charges for the whole table.

State

For determinism and snapshots the terminal's state is, in this order: a present flag (1 byte; if 00h nothing else follows), the 9,600 bytes of the grid, the cursor column, the cursor row, the foreground index, the background index, the cursor-shown flag, the pending wrap flag, the 768 bytes of the palette (red, green, blue for entries 0 to 255), and the incomplete UTF-8 sequence: a count k from 0 to 3, then 3 bytes holding those k bytes padded with 00h. That is 10,379 bytes with the device, 1 without. The incomplete sequence is a valid lead byte (C2h-F4h) and the valid continuation bytes received after it.

The terminal sends no events (keyboard input arrives as system events) and takes no input from the host. How the host draws the grid (font, size, cursor shape, smoothing) cannot be observed by the program. Terminal characters are drawn above the vector displays and the page, and cell backgrounds below them; the 2D vector display describes the layers.

Example

#include "terse.h"

int main(void)
{
    static const uint8_t navy[3] = {0, 0, 64};
    uint32_t col, row;

    /* Redefine entry 4, then clear the grid in it. */
    terse_call(CALL_TERM_PALETTE_SET, 4, (uint32_t)navy, 1);
    term_color(15, 4);
    term_cmd(TERM_CLEAR);
    term_cmd(TERM_CURSOR_OFF);

    term_goto(2, 1);
    /* two wide characters, U+4E16 and U+754C */
    term_puts("Hello, \xE4\xB8\x96\xE7\x95\x8C\n");
    col = terse_call2(CALL_TERM_GET_CURSOR, 0, 0, &row);
    /* col = 0, row = 2 */

    term_fill(0, 29, 80, '-', 11, 4);   /* by cells_write */
    for (;;)
        terse_wait_frame();
}

After the puts, the cursor is at (0, 2): the newline moved it to the next row. The two Chinese characters take four cells, columns 9 to 12 of row 1.