gbos.git/README.md, branch master

docs: drop the link-drop investigation writeup

2026-07-18T19:02:47Z

hooks: clang-format pre-commit (changed lines only) + .clang-format

2026-07-18T18:57:37Z

Same setup as sl0pboy: git-clang-format scopes formatting to the lines each commit touches, re-adds the formatted files, and refuses partially-staged C files. Style file matches the house style (4-space, attached braces, 100 cols, short cases/ifs inline, no include sorting - order is load-bearing for SDCC userland). Enable once: git config core.hooksPath hooks

docs: concise README (networking + demo gif up front); internals.md

2026-07-18T18:41:37Z

README is now pitch -> proof (real capture gif) -> quick start -> docs pointers, with the network stack and gbhub/gbjoin/gbtype getting explicit billing. The full technical breakdown (memory model, syscall ABI, fork/exec/context switch, FS layout, toolchain war stories) moves to docs/internals.md, plus previously-undocumented sections on the network stack and the terminal/OSK.

refactor: c/ -> usr/, compiled program blobs out of the source tree

2026-07-17T22:38:38Z

Userland sources live in usr/ (fits the Unix theme better than 'c'). SDCC output .bin blobs land in build/usr/ with the other build artifacts instead of littering the source dir; programs.asm INCBINs them from there. Byte-identical ROM.

fs rewrite stage 3: nested directories, paths, cwd (cd/mkdir/ls)

2026-07-16T10:49:19Z

- directories generalized: dir_find/dir_add/dir_remove take any dir inode; every dir carries '.'/'..'. Path resolution (resolve / resolve_parent) walks absolute or cwd-relative paths; open/mkdir/chdir/remove/opendir take paths. - per-process cwd: PROC_CWD in the PCB (root by default, inherited on fork); sys_chdir sets it, sys_opendir points ls at any directory. - shell: 'cd' builtin + cwd-aware prompt; 'mkdir'/'ls ' tools; 'exit'/'quit' and EOF call poweroff() (clean shutdown via the $ED opcode -> reliable save). - three HL/buffer-clobber bugs fixed along the way: resolve didn't preserve the path cursor across dir_find; cur_cwd clobbered HL; resolve_parent set the final name before resolve() overwrote wFsNameBuf (now copied after). - verified: nested mkdir/cd/save, multi-level paths (cat docs/sub/b), and the whole tree persists across a reboot. - README: document directories + the poweroff opcode.

fs rewrite stage 2: inodes + root directory (block-based, persistent)

2026-07-16T10:20:57Z

- fs.asm: a real block filesystem on the persistent block device - superblock, block/inode bitmaps, a 32-entry inode table (type, size, 8 direct block pointers -> files up to 2 KiB), and a root directory of 16-byte entries. Metadata cached in WRAMX; one-block data cache streams file/dir blocks. - same syscall interface (open/getb/putb/list/remove) -> tools unchanged; ls now enumerates until flist() runs out (16 files, was hardcoded 8). - old 8-slot WRAM FS removed; cart RAM partitioned: process banks 0-7, disk 8-11. - two register-clobber bugs fixed: alloc_block/alloc_inode returned the bitmap-block number (write_bitmap clobbers C); db_use loaded the wrong block on a transition (db_flush->write_block clobbers C) -> multi-block files broke. - verified: 10+ files, multi-block (300-byte) files, delete, and persistence across reboots. Debug 'blk' disk tool retained (fill/peek). - README: document the block filesystem.

fs rewrite stage 1: persistent block device (bounce buffer, cart SRAM)

2026-07-16T09:42:38Z

- blk.asm: read_block/write_block move 256-byte blocks between battery-backed cart-RAM banks (8-11, the 'disk') and a WRAM bounce buffer. Banking is hidden in those two routines; they inline the 'restore my bank' step so they never touch the stack while the disk bank is mapped over the process's $A000 window (the stack lives there too -- a call/ret would rug-pull it). - format-on-first-boot: superblock magic in block 0; otherwise the disk persists. - cart RAM bumped to 128 KiB (-r 4); process banks 0-7, disk banks 8-11. - debug tool 'blk fill/peek' + syscalls to validate round-trip and persistence. - verified: round-trip incl. cross-bank (block 100 -> bank 11); block survives a reboot via .sav; magic intact (no reformat on 2nd boot). - old WRAM 8-slot FS still backs the tools until stages 2-3.

jobs: background execution (&), non-blocking reap, spin demo

2026-07-16T09:15:12Z

- sys_reap: nohang reap of a finished zombie child (-> pid or 0). - shell: 'cmd &' launches in the background (prints [pid], no wait); reaps finished jobs at the prompt ([pid done]). Foreground now waits for its own child specifically (loops wait(), reporting bg completions meanwhile) so kill reports the right pid. - spin: a process that yields forever - a target for ps/kill. - verified: spin &; ps shows it; kill removes just that one; immortal init; self-finishing bg worker reaped with [pid done].

shell: I/O redirection (>/<) and pipes (|); rewrite shell in C

2026-07-16T06:25:35Z

- kernel I/O routing: PCB gains PROC_STDIN/PROC_STDOUT (default console $FF), inherited across fork. KGetc/KPutc route read/write/putc to the console or a file fd. New syscalls: putc(16), setin(17), setout(18), lookup(19). read/write now go through the routing; putc/puts/nl use SYS_PUTC. - sys_lookup + NameTable move command-name resolution into the kernel. - shell rewritten in C (c/sh.c): tokenizes a line, parses > / < / |, and drives fork+setin/setout+exec+wait. Pipes run as 'a > __pipe ; b < __pipe' (temp file). asm shell + cmdtab removed; StrEqual/SkipName kept for sys_lookup. - libc: fork/exec/wait/setin/setout/lookup wrappers. - verified: echo>file, cat file, wc

filesystem: a RAM FS (WRAMX) + ls/cat/save/rm; wc/head read files

2026-07-16T05:53:19Z

- fs.asm: 8-slot RAM filesystem in WRAMX ($D000-$DFFF), name[8]+len[2]+data[502]; syscalls open/close/getb/putb/list/remove, seeded with a 'readme' at boot. - libc: open/close/fgetc/fputc/flist/fremove wrappers + O_READ/O_WRITE/NOFD. - tools: ls, save (stdin->file, one line), rm; cat/wc/head now take a file arg. - fix: syscall dispatch clobbers A, so putb takes its byte in E (was reading the handler's low address byte, 0xDC); ls NUL-terminates 8-char names. - verified: save/cat/ls/rm cycle; wc readme -> '2 7 38'; head -n 1 readme. - README: document the filesystem + the A-clobber ABI note.