uxn11/doc/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 - 00000000 - no input (-)
 - 0x01 - 00000001 - stdin (stdin)
 - 0x02 - 00000010 - argument (stdin)
 - 0x03 - 00000011 - argument spacer (-)
 - 0x04 - 00000100 - argument end (-)
 - 0x05 - 00000101 - host response
 - 0x06 - 00000110 - host response end (-)
 - 0x07 - 00000111 - stdin end (-)
 - 0x20 - 00100000 - child 0 sent data
 - 0x21 - 00100001 - child 1 sent data
 - 0x22 - 00100010 - child 2 sent data
 - 0x23 - 00100011 - child 3 sent data
 - 0x40 - 01000000 - child 0 data end
 - 0x41 - 01000001 - child 1 data end
 - 0x42 - 01000010 - child 2 data end
 - 0x43 - 01000011 - child 3 data end
 - 0x80 - 10000000 - child 0 exited (stdin contains exit code)
 - 0x81 - 10000001 - child 1 exited (stdin contains exit code)
 - 0x82 - 10000010 - child 2 exited (stdin contains exit code)
 - 0x83 - 10000011 - 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
 - 0x04 - (raw-tty) unused
 - 0x04 - (restore-tty) 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
 - 0x04 - put stdin tty into raw mode
 - 0x05 - restore stdin tty to canonical mode
 - 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

SYSTEM EXPANSION SUPPORT

the system expansion port can be used to determine whether or not the
console supports these additional capabilities. the convention is to
use UUID-based extensions as defined by uxn38. the unix console device
uses `01231250-d878-4462-bc41-d0927645a2fa` as its UUID, and uses the
following expansion layout:

  - operation (1 byte): 03 (uuid extension)
  - device (1 byte): 10 (console)
  - uuid (16 bytes): 0123 1250 d878 4462 bc41 d092 7645 a2fa
  - version (1 byte): 00 (set to non-zero by supporting emulators)
  - flags (2 byte): 0000 (updated by supporting emulators)

after being loaded, version will be non-zero if console expansion is
supported, and zero otherwise. flags will contain bits describing the
available capabilities (0x0000 if console expansion is unsupported).
the flags are as follows:

 - 0x0001: supports `execute`
 - 0x0002: supports `kill`
 - 0x0004: supports `raw-tty`, `restore-tty`
 - 0x0008: supports `getenv` and `setenv`
 - 0x0010: supports writing to child stdin
 - 0x0020: supports reading from child stdout
 - 0x0040: supports reading from child stderr
 - 0x0080: supports allocating child pty
 - 0x0100 to 0x8000: (currently unused)

currently uxn11 will write 0x00ff to the flags field, so programs
wishing to detect unx11 can check for that value. here's a snippet
that determines whether the console expansion can be used:

  |00 @System [ &unused $2 &expansion $2 ( ... ) ]

  |0010
    ;query .System/expansion DEO2
    ;query/flags LDA2 #00ff EQU2 ?enable-uxn11-console
    BRK

  @enable-uxn-console ...

  @query 03 10 ( uuid ) 0123 1250 d878 4462 bc41 d092 7645 a2fa &flags 00 0000

note that uxn11 unconditionally enables the expanded console. so in
this case the uuid-based extension mechanism is only used to detect
the presence (or absence) of emulator support. if device 0x10 is not
provided then flags will be 0x0000 (moving or adding additional
console devices is not supported).