uxn11/console.txt

CONSOLE DEVICE

 0x10 vector*      0x18 @stdout
 0x11 (vector)     0x19 @stderr
 0x12 stdin        0x1a @proc-put
 0x13              0x1b
 0x14              0x1c param*
 0x15              0x1d (param)
 0x16              0x1e opts
 0x17 type         0x1f @host-put

(* denotes a short register, i.e. two bytes wide)
(@ denotes a register that causes an immediate effect)

vector ports (0x10-0x11) contain an address to jump to when input is
available. when the vector fires one byte can be read from the read
port (0x12), and its meaning is defined by the type (0x17).

the stdin port (0x12) contains one byte of data to be read. the byte
represents input read from one of the following: arguments, stdin,
child processes, or host messages. the type port (0x17) says which.

the type (0x17) field explains how to interpret calls to the console
vector (0x10) and where data can be read from:
 - 0x00 - no input (-)
 - 0x01 - stdin (stdin)
 - 0x02 - argument (stdin)
 - 0x03 - argument spacer (-)
 - 0x04 - argument end (-)
 - 0x05 - host response
 - 0x06 - host response end (-)
 - 0x07 - stdin end (-)
 - 0x20 - child 0 sent data
 - 0x21 - child 1 sent data
 - 0x22 - child 2 sent data
 - 0x23 - child 3 sent data
 - 0x40 - child 0 data end
 - 0x41 - child 1 data end
 - 0x42 - child 2 data end
 - 0x43 - child 3 data end
 - 0x80 - child 0 exited (stdin contains exit code)
 - 0x81 - child 1 exited (stdin contains exit code)
 - 0x82 - child 2 exited (stdin contains exit code)
 - 0x83 - child 3 exited (stdin contains exit code)

writing a byte to the stdout port (0x18) will send one byte of data to
the emulator's stdout.

writing a byte to the stderr port (0x19) will send one byte of data to
the emulator's stderr.

writing a byte to the proc-put port (0x1a) will send one byte of data to
one of the emulator's child processes. the lower 2 bits of the opts
port (0x1e) determine which one:
 - 0x00: child 0
 - 0x01: child 1
 - 0x02: child 2
 - 0x03: child 3

the param ports (0x1c-0x1d) specify the a value to use as a parameter
for a host-put (0x1f). the meaning values by host-put value:
 - 0x00 - (nop) unused
 - 0x01 - (execute) command string (e.g. 'gcc -o "demo" demo.c')
 - 0x02 - (getpid) unused
 - 0x03 - (kill) unused
 - 0x10 - (getenv) name string (e.g. "TERM")
 - 0x11 - (setenv) assignment string (e.g. "TERM=vt100")
strings must be null-terminated. commands are parsed by /bin/sh -c.

the opts port (0x1e) specifies options that affect host actions run
using the host-put port (0x1f):
 - lower 2 bits control which child process to use (when applicable)
   + 0x00 - child 0
   + 0x01 - child 1
   + 0x02 - child 2
   + 0x03 - child 3
 - next 2 bits (0x0c) are unused
 - upper 4 bits control which pipes to use with execute:
   + 0x80 - use child's pty (implies 0x70)
   + 0x40 - read from child's stderr
   + 0x20 - read from child's stdout
   + 0x10 - write to child's stdin

the host-put port (0x1f) specifies which host action to take:
 - 0x00 - nop: does nothing
 - 0x01 - execute: reads command string, starts a subprocess
 - 0x02 - getpid: responds with child process pid (if any)
 - 0x03 - kill: shuts down child process
 - 0x10 - getenv: looks up a name (e.g. TERM) in env, responds with value
 - 0x11 - setenv: reads an assignment (e.g. TERM=vt100), updates env

( FRAGMENTS REMOVED UNTIL I VERIFY THEM WORKING )