From 4335d248d18987a050d8ac26965c90718eef7562 Mon Sep 17 00:00:00 2001
From: user <user@clank>
Date: Thu, 16 Jul 2026 07:21:40 +0200
Subject: libc + CLI tools: a small C userland

- libc: add putc, puts, strlen, getargs (args string), EOF (=4) for readc.
- args: shell splits the command line at the first space ("cmd\0args\0" at
  $A000, inherited by the child via fork); getargs() returns the arg string.
- shell: exit on Ctrl-D/EOF; $ prompt over a clean read loop.
- tools (c/): echo (argv), cat (stdin->stdout to EOF), uname, pid (decimal
  print), true, false. Each built to a ROM-bank blob and registered.
- Makefile: CBLOBS list builds all C programs.
- README: document libc + the tool set.
---
 README.md | 40 +++++++++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 49909f9..c386c08 100644
--- a/README.md
+++ b/README.md
@@ -193,12 +193,40 @@ void main(void) {
 }
 ```
 
+### libc
+
+`writes`, `putc`, `puts`, `nl`, `strlen`, `readc` (returns `EOF`=4 at end of
+input), `getargs` (this program's argument string), `getpid`, `sexit`.
+Arguments: the shell splits the command line at the first space and leaves
+`"cmd\0args\0"` at `$A000`; the child inherits it through `fork`, and
+`getargs()` returns the args.
+
+### CLI tools (in `c/`)
+
+| tool | what it does |
+|------|--------------|
+| `echo` | print its arguments (`echo hello world`) |
+| `cat`  | copy stdin to stdout until EOF (Ctrl-D / pipe end) |
+| `uname`| print the system name |
+| `pid`  | print the process's pid (decimal) |
+| `true` / `false` | exit 0 / 1 |
+| `chello` | the C "hello" demo |
+
 ```
-$ chello
-hello from C on gbos!
-my pid is 2
+$ uname
+gbos sm83 (Game Boy Color)
+$ echo C tools on a Game Boy
+C tools on a Game Boy
+$ pid
+5
+$ cat
+hi from cat
+hi from cat
 ```
 
+Each tool is a separate `c/<name>.c`, built to a ROM-bank blob, INCBIN'd, and
+registered in the program table + shell command table (`src/programs.asm`).
+
 **Toolchain gotchas found the hard way:** SDCC's `--asm=rgbds` mode mis-orders
 instructions (emits `ld [hl],a` before the `ld hl,sp+0` that sets the pointer) —
 so we use SDCC's native asxxxx path and INCBIN the blob instead. String literals
@@ -213,8 +241,10 @@ explicit lengths and emit newlines via `nl()`.
 - [ ] `exec` refinement: copy `.data` from ROM + zero `.bss` for RW globals
 - [x] a real shell program: `fork`+`exec`+`wait` driven from the serial console
 - [x] C toolchain: SDCC (sm83) + libc shim, C programs run as gbos processes
-- [ ] grow libc (strings, a `main(argc,argv)`, more syscalls) + port real tools
-- [ ] Makefile-drive multiple C programs (a `CPROGS` list)
+- [x] grow libc (`puts`/`putc`/`strlen`/`getargs`/EOF) + args via the shell
+- [x] CLI tools in C: `echo`, `cat`, `uname`, `pid`, `true`, `false`
+- [x] Makefile builds all C programs (a `CBLOBS` list)
+- [ ] more tools (`wc`, `head`, `rev`), a real `argc/argv`, a RAM filesystem
 - [ ] Preemptive scheduling: real context save in `TimerISR` → `hSwitchTo`
 - [ ] Use the `$D000-$DFFF` u-area (SVBK) for per-process kernel state / kstack
 - [ ] `brk`/heap allocator inside the task bank (heap up, stack down, collision = ENOMEM)
-- 
cgit v1.3.1-sl0p