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

- 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.

1 files changed, 20 insertions, 2 deletions

diff --git a/include/gbos.inc b/include/gbos.inc
index 329430c..3b96f56 100644
--- a/include/gbos.inc
+++ b/include/gbos.inc
@@ -46,7 +46,22 @@ DEF KSTACK_TOP      EQU $D000   ; kernel stack top (grows down into WRAM0)
 ; Process table
 ; -----------------------------------------------------------------------------
 DEF MAX_PROCS       EQU 8
-DEF NUM_RAM_BANKS   EQU 4    ; MBC5 cart RAM banks available (-r 3 = 32 KiB)
+DEF NUM_RAM_BANKS   EQU 8    ; process data/stack banks 0..7 (of 16; -r 4 = 128 KiB)
+
+; -----------------------------------------------------------------------------
+; Block device (persistent, battery-backed cart RAM). The "disk" is cart-RAM
+; banks FS_BANK0.. accessed 256 bytes at a time through a WRAM bounce buffer
+; (read_block / write_block), so only those two routines ever touch banking.
+; -----------------------------------------------------------------------------
+DEF FS_BANK0    EQU 8      ; disk starts at cart-RAM bank 8
+DEF FS_NBLOCKS  EQU 128    ; 128 blocks x 256 B = 32 KiB (banks 8..11)
+DEF BLK_SIZE    EQU 256
+DEF BLK_PERBANK EQU 32     ; 8 KiB / 256
+DEF SUPER_BLOCK EQU 0      ; block 0 = superblock
+DEF SUPER_MAG0  EQU $47    ; 'G'
+DEF SUPER_MAG1  EQU $42    ; 'B'
+DEF SUPER_MAG2  EQU $46    ; 'F'
+DEF SUPER_MAG3  EQU $53    ; 'S'
 DEF KSTACK_TOP2     EQU $D000 ; kernel stack top reused for syscalls (fork)
 DEF INIT_PID        EQU 1    ; pid of the init task (orphan reaper)
 
@@ -102,7 +117,9 @@ DEF SYS_LOOKUP  EQU 19   ; program id for a command name  (DE=name -> A=id/$FF)
 DEF SYS_PS      EQU 20   ; process table entry            (B=slot, DE=buf3 -> A=1/0)
 DEF SYS_PROGNAME EQU 21  ; program id -> name             (B=id, DE=namebuf)
 DEF SYS_REAP    EQU 22   ; reap a zombie child, nohang    (-> A=pid or 0)
-DEF SYS_MAX     EQU 23
+DEF SYS_BFILL   EQU 23   ; [debug] fill a disk block      (B=block, E=byte)
+DEF SYS_BPEEK   EQU 24   ; [debug] read a disk block[0]   (B=block -> A)
+DEF SYS_MAX     EQU 25
 ; SYS_KILL (9) is now implemented (B=pid -> A=0/$FF; pid 1 is immortal)
 ; (SYS_OPEN=4 / SYS_CLOSE=5 are now implemented by the filesystem)
 
@@ -148,5 +165,6 @@ DEF PROG_RM     EQU 15
 DEF PROG_PS     EQU 16
 DEF PROG_KILL   EQU 17
 DEF PROG_SPIN   EQU 18
+DEF PROG_BLK    EQU 19
 
     ENDC