From a0775c5dcf77d0c8de2e4a0932d47b0505842ec4 Mon Sep 17 00:00:00 2001
From: Virgil Dupras <hsoft@hardcoded.net>
Date: Sun, 3 Jan 2021 14:01:34 -0500
Subject: [PATCH] Add a new "Remote Shell" application

This allows a COS shell to remotely control another shell from a
serial line. It's very crude now, but the plan is to add tools much
like the POSIX tools, but for COS.
---
 blk.fs        |  9 +++++++++
 doc/intro.txt |  4 ++++
 doc/rsh.txt   | 22 ++++++++++++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 doc/rsh.txt

diff --git a/blk.fs b/blk.fs
index 9bf064d..466f0a3 100644
--- a/blk.fs
+++ b/blk.fs
@@ -4,6 +4,7 @@ MASTER INDEX
 005 Z80 assembler             030 8086 assembler
 050 AVR assembler             70-99 unused
 100 Block editor              120 Visual Editor
+150 Remote Shell
 160 AVR SPI programmer        165 Sega ROM signer
 170-259 unused                260 Cross compilation
 280 Z80 boot code             350 Core words
@@ -873,6 +874,14 @@ CREATE PREVPOS 0 , CREATE PREVBLK 0 , CREATE xoff 0 ,
     1 XYMODE C! clrscr 0 ACC ! 0 PREVPOS ! nums bufs contents
     BEGIN xoff? status setpos KEY handle UNTIL
     0 XYMODE C! 19 aty IN$ ;
+( ----- 150 )
+( Remote Shell )
+0 :* rsh<? 0 :* rsh>
+: rsh BEGIN
+    rsh<? IF
+        DUP 4 ( EOT ) = IF DROP EXIT THEN EMIT THEN
+    KEY? IF DUP 0x80 < IF rsh> ELSE DROP EXIT THEN THEN
+    AGAIN ;
 ( ----- 160 )
 ( AVR Programmer, load range 160-163. doc/avr.txt )
 ( page size in words, 64 is default on atmega328P )
diff --git a/doc/intro.txt b/doc/intro.txt
index 12f8e10..7a917e9 100644
--- a/doc/intro.txt
+++ b/doc/intro.txt
@@ -47,8 +47,12 @@ When you're ready to move to real hardware, read hw/intro.txt.
 * Dictionary of core Forth words (dict.txt)
 * Editing text (ed.txt)
 * Assembling binaries (asm.txt)
+* Remote Shell (rsh.txt)
 * Programming AVR chips (avr.txt)
 * Bootstrap Collapse OS to a new system (bootstrap.txt)
 * Cross-compilation mechanisms (cross.txt)
 * Protocols (protocol.txt)
+* Grid subsystem (grid.txt)
+* Sega Master System ROM signatures (sega.txt)
+* Self-hosting notes (selfhost.txt)
 
diff --git a/doc/rsh.txt b/doc/rsh.txt
new file mode 100644
index 0000000..b68b971
--- /dev/null
+++ b/doc/rsh.txt
@@ -0,0 +1,22 @@
+# Remote Shell
+
+You can control a remote system from Collapse OS using the
+Remote Shell application at B150. All you need are words that
+follow the EMIT and KEY? signatures. Serial lines drivers
+provide those words.
+
+To use the remote shell, first plug your words into RSH aliases:
+
+' FOO> ' rsh> *! ' FOO<? ' rsh<? *!
+
+FOO> being the "EMIT" word and "FOO<?" being the KEY? word.
+
+Then, it's only a matter of running "rsh". This will repeatedly
+poll rsh<? and emit whatever is coming from there and at the
+same time, poll KEY? and push whatever key you type to rsh>.
+
+You can stop the remote shell by typing any character over 0x7f.
+For example, on a TRS-80 4P, the BREAK key yields 0x80 and will
+break the loop.
+
+See hw/acia.txt for tips on configuring a serial line.