# 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:
NEWLN     ln --    "Enter" line ln
CURSOR!   pos --   Set cursor's position

"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.

NEWLN is called when we "enter" a new line, that is, when we
overflow from previous line or when 0x0d ( ASCII CR ) is emit-
ted.

When this is called, the line being entered should be cleared
of its contents. On some systems, some kinf of screen offset
might be have to be set to give a "scrolling" effect. Now's the
time.

If it's 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 NEWLINE.

CURSOR! is called whenever we change the cursor's position. If
not implemented, it will be a noop. It is never called with an
out of range "pos" (greater than COLS*LINES).