From 2538b138946128cc5ff473e14ba9bde564aef2e9 Mon Sep 17 00:00:00 2001
From: user <user@clank>
Date: Thu, 16 Jul 2026 00:37:09 +0200
Subject: shell working: fix syscall ABI (trap clobbers HL) + document

- root cause of the read/echo corruption: SyscallTrap uses HL to index the
  dispatch table, so HL is clobbered across a syscall; the shell then wrote its
  buffer pointer's garbage into the $0000-$7FFF MBC register region, corrupting
  the mapper. fix: userland saves HL around sys_read (push/pop).
- shell now runs commands end to end: $ hello -> hello world!, $ worker ->
  worker!, $ foo -> ?
- README: document that syscalls clobber BC/DE/HL (return in A, B for wait);
  add read + shell to the syscall table.
---
 README.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 929cafe..a0b8338 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,10 @@ $FFEF-$FFF2 HRAM   bank shadows + switch target
 
 ## Syscall ABI
 
-User loads `C` = syscall number, args in `DE`/`B`, then `rst $30`. Return in `A`.
+User loads `C` = syscall number, args in `DE`/`B`/`HL`, then `rst $30`.
+Return in `A` (and `B` for `wait`). **The trap clobbers `BC`/`DE`/`HL`** (it uses
+`HL` to index the dispatch table), so userland must save any pointer it needs
+across a syscall (`push hl` / `pop hl`). Libc syscall stubs handle this for C.
 
 | # | name    | status |
 |---|---------|--------|
@@ -52,7 +55,24 @@ User loads `C` = syscall number, args in `DE`/`B`, then `rst $30`. Return in `A`
 | 7 | wait    | ✅ blocks; reaps a zombie child → `A`=pid `B`=code |
 | 8 | getpid  | ✅ |
 | 11| yield   | ✅ cooperative switch |
-| 2,4,5,9,10 | read/open/close/kill/brk | ⛔ `ENOSYS` |
+| 2 | read    | ✅ blocking console input (1 byte) via external-clock serial |
+| 4,5,9,10 | open/close/kill/brk | ⛔ `ENOSYS` |
+
+### The shell (PROG_SH)
+
+init `exec`s a tiny shell: **prompt → read a line (with echo) → match a command
+→ `fork`+`exec`+`wait`**. Commands live in a table (`worker`, `hello`). Runs
+entirely over the headless serial console:
+
+```
+$ hello
+hello world!
+$ worker
+worker!
+$ foo
+?
+$
+```
 
 ### Process lifecycle (exit / wait / reaping)
 
-- 
cgit v1.3.1-sl0p