rename ports

console.txt

@@ -1,15 +1,16 @@
 CONSOLE DEVICE
 
- 0x10 vector               0x18 stdout+
- 0x11 (vector)             0x19 stderr+
- 0x12 stdin                0x1a send+
+ 0x10 vector*      0x18 @stdout
+ 0x11 (vector)     0x19 @stderr
+ 0x12 stdin        0x1a @proc-put
  0x13              0x1b
- 0x14 proc-get             0x1c param
+ 0x14 proc-get     0x1c param*
  0x15 host-get     0x1d (param)
  0x16              0x1e opts
- 0x17 type                 0x1f action+
+ 0x17 type         0x1f @host-put
 
-(+ denotes a register that causes an immediate effect)
+(* 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
@@ -22,7 +23,7 @@ the proc-get port (0x14) contains one byte of data to be read. the byte
 represents input read from one of the emulator's subprocesses.
 
 the host-get port (0x15) contains one byte of data to be read. the byte
-represents part of a response to a system action.
+represents part of a response to a host-put (0x1f).
 
 the type (0x17) field explains how to interpret calls to the console
 vector (0x10) and where data can be read from:
@@ -48,7 +49,7 @@ 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 send port (0x1a) will send one byte of data to
+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
@@ -57,7 +58,7 @@ port (0x1e) determine which one:
  - 0x03: child 3
 
 the param ports (0x1c-0x1d) specify the a value to use as a parameter
-for a system action (0x1f). the meaning values by action value:
+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 - (pid) unused
@@ -70,8 +71,8 @@ for a system action (0x1f). the meaning values by action value:
  - 0x21 - (tty-unset-raw) unused
 strings must be null-terminated. commands are parsed by /bin/sh -c.
 
-the opts port (0x1e) specifies options that affect system actions run
-using the action port (0x1f):
+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
@@ -83,7 +84,7 @@ using the action port (0x1f):
    + 0x20 - read from child's stdout
    + 0x10 - write to child's stdin
 
-the action port (0x1f) specifies which system action to take:
+the host-put port (0x1f) specifies which host action to take:
  - 0x00 - nop: does nothing
  - 0x01 - execute: reads command string, starts a subprocess
  - 0x02 - pid: responds with child process pid (if any)
@@ -117,7 +118,7 @@ EXAMPLE PROGRAM FRAGMENTS
     @run-make ( -- )
       ;make-cmd .Console/param DEO2        ( ; set up make to run )
       #01 .Console/opts DEO                ( ; use child without pipelines )
-      #01 .Console/action DEO JMP2r        ( ; run the command now and return )
+      #01 .Console/host-put DEO JMP2r      ( ; run the command now and return )
 
     @make-cmd "make $3c                    ( ; buffer containing cmd to run )
 
@@ -152,7 +153,7 @@ EXAMPLE PROGRAM FRAGMENTS
       ;mpg123-cmd/buf scpy                 ( ; copy path into cmd buffer )      
       ;mpg123-cmd .Console/param DEO2      ( ; set up `mpg123 <path>` cmd to run )
       #02 .Console/opts DEO                ( ; use child 2 without pipelines )
-      #01 .Console/action DEO JMP2r        ( ; start playing mp3 now and return )
+      #01 .Console/host-put DEO JMP2r      ( ; start playing mp3 now and return )
 
     @mpg123-cmd "mpg123 20 &buf $100
 
@@ -168,8 +169,8 @@ EXAMPLE PROGRAM FRAGMENTS
    The following fragment uses `ispell -a` to implement a basic spell checker:
 
     |0000
-      @spelled-ok? $1
-      @resume $2 ( when set should have signature: -- BRK )
+      @spelled-ok? $1                        ( ; was the last word spelled ok? )
+      @resume $2                             ( ; if set should have effect ` -- BRK` )
 
     |0100 ( -- BRK )
       init-ispell                            ( ; set up ispell child process )
@@ -179,7 +180,7 @@ EXAMPLE PROGRAM FRAGMENTS
     @init-ispell ( -- )
       ;ispell-cmd .Console/param DEO2        ( ; set up `ispell -a` to run )
       #61 .Console/opts DEO                  ( ; child 1: write to stdin, read from stdout )
-      #01 .Console/action DEO JMP2r         ( ; run the command now and return )
+      #01 .Console/host-put DEO JMP2r        ( ; run the command now and return )
 
     @ispell-cmd "ispell 20 "-a 00            ( ; "ispell -a" )
 
@@ -205,8 +206,8 @@ EXAMPLE PROGRAM FRAGMENTS
       ;on-ispell-ready .Console/vector DEO2  ( ; drain finished, checker is ready )
       !resume                                ( ; resume whatever we wanted to do after checking )
 
-    @check-spelling ( word* continuation* -- )
+    @check-spelling ( word* continue* -- )
       #01 .Console/opts DEO                  ( ; act on child 1 )
       .resume STZ2                           ( ; write continuation to resume )
       &loop LDAk ?{ POP2 JMP2r }             ( ; when we read \0 we are done )
-      LDAk .Console/send DEO INC2 !&loop    ( ; send byte to child 1 )
+      LDAk .Console/proc-put DEO INC2 !&loop ( ; send byte to child 1 and loop )