From ae1e6367a3bd9eb87ad2dc4b12960998923b3b58 Mon Sep 17 00:00:00 2001
From: d_m <d_m@plastic-idolatry.com>
Date: Mon, 18 Dec 2023 22:54:33 -0500
Subject: [PATCH] document uuid-based extensions

---
 console.txt | 60 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 56 insertions(+), 4 deletions(-)

diff --git a/console.txt b/console.txt
index e626dc2..d3daa0c 100644
--- a/console.txt
+++ b/console.txt
@@ -22,6 +22,7 @@ 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)
@@ -49,9 +50,10 @@ 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
+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
@@ -59,6 +61,7 @@ port (0x1e) determine which one:
 
 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
@@ -67,10 +70,12 @@ for a host-put (0x1f). the meaning values by host-put value:
  - 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.
+
+(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
@@ -84,6 +89,7 @@ using the host-put port (0x1f):
    + 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)
@@ -93,4 +99,50 @@ the host-put port (0x1f) specifies which host action to take:
  - 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 )
+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
+  - flags (2 byte): 0000 (may be updated by emulator)
+
+after being loaded, flags will be 0x0000 if the console expansion is
+not supported. otherwise, it will contain one or more of the following
+flags:
+
+ - 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 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).