gbos scaffold: working cooperative microkernel (verified ABAB in emulator)

- fix ClearKernelRAM clobbering the kernel stack (only clear $C000-$CBFF)
- fix SyscallTrap clobbering DE (buffer arg) during table dispatch
- README: run via ~/dev/gbc --headless; note bring-up bugs

1 files changed, 86 insertions, 0 deletions

diff --git a/include/gbos.inc b/include/gbos.inc
new file mode 100644
index 0000000..c22344a
--- /dev/null
+++ b/include/gbos.inc
@@ -0,0 +1,86 @@
+; =============================================================================
+; gbos.inc - core constants, memory map, PCB layout, syscall numbers
+; Target: Game Boy Color, MBC5 + RAM + BATTERY
+; =============================================================================
+    IF !DEF(GBOS_INC)
+DEF GBOS_INC EQU 1
+
+; -----------------------------------------------------------------------------
+; Hardware registers we touch (subset; full defs would come from hardware.inc)
+; -----------------------------------------------------------------------------
+DEF rIF     EQU $FF0F   ; interrupt flags
+DEF rIE     EQU $FFFF   ; interrupt enable
+DEF rSVBK   EQU $FF70   ; CGB WRAM bank select ($D000-$DFFF): 1..7
+DEF rKEY1   EQU $FF4D   ; CGB speed switch
+DEF rSB     EQU $FF01   ; serial data
+DEF rSC     EQU $FF02   ; serial control
+DEF rLCDC   EQU $FF40
+DEF rSTAT   EQU $FF41
+DEF rLY     EQU $FF44
+
+; -----------------------------------------------------------------------------
+; MBC5 mapper register addresses (writes to ROM space hit the mapper)
+; -----------------------------------------------------------------------------
+DEF MBC5_RAM_ENABLE EQU $0000   ; write $0A to enable cart RAM
+DEF MBC5_ROMB_LO    EQU $2000   ; ROM bank bits 0..7
+DEF MBC5_ROMB_HI    EQU $3000   ; ROM bank bit 8
+DEF MBC5_RAMB       EQU $4000   ; RAM bank bits 0..3 ($A000-$BFFF)
+
+; -----------------------------------------------------------------------------
+; Memory map (the gbos plan)
+;   $0000-$3FFF ROM0   kernel core (fixed, always mapped)
+;   $4000-$7FFF ROMX   current task TEXT (read-only program code)
+;   $8000-$9FFF VRAM   graphics
+;   $A000-$BFFF SRAM   current task DATA/BSS/HEAP/STACK  (MBC5 RAM bank)
+;   $C000-$CFFF WRAM0  kernel globals + kernel stack (never swapped)
+;   $D000-$DFFF WRAMX  per-process u-area (SVBK bank)
+;   $FF80-$FFFE HRAM   bank-switch trampoline + context switch
+; -----------------------------------------------------------------------------
+DEF TASK_RAM_BASE   EQU $A000
+DEF TASK_RAM_TOP    EQU $C000   ; one past end of the 8 KiB window
+DEF TASK_STACK_TOP  EQU $BFFF   ; task stacks grow down from here
+
+DEF KSTACK_TOP      EQU $D000   ; kernel stack top (grows down into WRAM0)
+
+; -----------------------------------------------------------------------------
+; Process table
+; -----------------------------------------------------------------------------
+DEF MAX_PROCS       EQU 8
+
+; process states
+DEF PS_FREE     EQU 0
+DEF PS_READY    EQU 1
+DEF PS_RUN      EQU 2
+DEF PS_BLOCKED  EQU 3
+DEF PS_ZOMBIE   EQU 4
+
+; PCB (process control block) field offsets
+RSRESET
+DEF PROC_STATE  RB 1    ; PS_*
+DEF PROC_PID    RB 1
+DEF PROC_SP     RW 1    ; saved stack pointer (into task's RAM bank)
+DEF PROC_ROMB   RW 1    ; text ROM bank (16-bit; MBC5 up to 511)
+DEF PROC_RAMB   RB 1    ; data/stack cart-RAM bank
+DEF PROC_WRAMB  RB 1    ; u-area SVBK bank (1..7)
+DEF PROC_PARENT RB 1
+DEF PROC_EXIT   RB 1    ; exit code (valid when PS_ZOMBIE)
+DEF PROC_SIZE   RB 0
+
+; -----------------------------------------------------------------------------
+; Syscall numbers (passed in C; args in DE/HL/B per call, ret in A)
+; -----------------------------------------------------------------------------
+DEF SYS_EXIT    EQU 0
+DEF SYS_FORK    EQU 1
+DEF SYS_READ    EQU 2
+DEF SYS_WRITE   EQU 3
+DEF SYS_OPEN    EQU 4
+DEF SYS_CLOSE   EQU 5
+DEF SYS_EXEC    EQU 6
+DEF SYS_WAIT    EQU 7
+DEF SYS_GETPID  EQU 8
+DEF SYS_KILL    EQU 9
+DEF SYS_BRK     EQU 10
+DEF SYS_YIELD   EQU 11
+DEF SYS_MAX     EQU 12
+
+    ENDC