151 lines
5.5 KiB
Plaintext
151 lines
5.5 KiB
Plaintext
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).
|