collapseos/doc/protocol.txt

# Protocols

Some subsystems (and in the case of KEY and EMIT, the core) re-
quire drivers to implement certain words in a certain way. For
example, the core requires drivers to implement (key) and (emit)
or else it won't know how to provide a console.

These protocols are described here.

# TTY protocol

(key)      -- c    Returns the next typed key on the console.
                   If none, block until there is one.
(emit)     c --    Spit a character on the console.

# PS/2 protocol

This protocol enables communication with a device that spits
PS/2 keycodes.

(ps2kc)   -- kc    Returns the next typed PS/2 keycode from the
                   console. Blocking.

# SPI Relay protocol

This protocol enables communication with a SPI relay. This
protocol is designed to support devices with multiple endpoints.
To that end, (spie) takes a device ID argument, with a meaning
that is up to the device itself. To disable all devices, supply
0 to (spie).

We expect relay devices to support only one enabled device at
once. Enabling a specific device is expected to disable the
previously enabled one.

(spie)    n --     Enable SPI device
(spix)    n -- n   Perform SPI exchange (push a number, get a
                   number back)
                  
# Grid protocol

A grid is a device that shows as a grid of ASCII characters and
allows random access to it.

COLS      -- n     Number of columns in the device
LINES     -- n     Number of lines in the device
CELL!     g pos -- Set glyph at pos

Optional:
CLRLN     ln --    Clear line number ln.

"pos" is a simple number (y * cols) + x. For example, if we
have 40 columns per line, the position (x, y) (12, 10) is 412.

A glyph is ASCII-0x20. If the resulting glyph number exceeds the
number of glyphs in the font, it's up to CELL! to ignore it.

Glyph 0 is always blank.

If CLRLN is not defined, the grid system uses multiple CELL!
calls to clear it. On some devices, this is highly inefficient.
Drivers for those devices should define CLRLN.