docs/reference/08-re-boot-oscalls.md

@@ -0,0 +1,78 @@
+# Boot & OS-call internals (reverse-engineered from the ROM under MAME)
+
+Source: dynamic trace of `psionwamx` (v7.20f) under MAME — 170,160 instructions
+of boot captured with correct bank mapping. Everything here is **reverse-
+engineered / observed**, not from a manual, and describes internal mechanisms
+below the documented C API.
+
+## Reset & early boot
+
+```
+FFFF0: jmp  A000:0        ; reset vector -> ROM
+A0000: jmp  A14A4
+A14A4: di                 ; disable interrupts
+       in/out 30h,...     ; ASIC hardware init via I/O ports
+       mov ds0,190h       ; segment setup
+       out 2h / 2Ch / 22h / 26h / 24h / 3Ch   ; ASIC control-register init
+       jmp AE69C          ; signature check ([6896h]==0F0A5h) then continue
+```
+Early boot disables interrupts, programs the ASIC control registers through the
+I/O ports, sets up segments, and validates a ROM signature word.
+
+## OS service calls are software interrupts (not a single gate)
+
+SIBO dispatches operating-system services through a **range of `INT` vectors**
+(NEC V-series `brk` mnemonic), each vector a service group with a function
+selector in a register. Vectors observed executing during boot, by frequency:
+
+| Vector | Count (boot) |
+| --- | --- |
+| `0xA6` | 414 |
+| `0x97` | 81 |
+| `0x85` | 49 |
+| `0x96` | 41 |
+| `0xBA` | 41 |
+| `0x8B` | 17 |
+| `0xB9` | 15 |
+| `0xAC` | 12 |
+| others `0x81`–`0xB5` | few each |
+
+Additional service vectors seen in driver code (not exercised at boot):
+- **`INT 0xCF`** — the I/O executive: `CL` = function code, `BX` = channel
+  handle, `DX` = argument, result in `AX`. This is the layer beneath `p_iow`.
+- **`INT 0xD9`**, **`INT 0xD3`** — further service vectors (exact roles TBD).
+
+The specific service behind each vector is not yet mapped; doing so means
+breakpointing each ISR and correlating with the documented C calls. This table
+is the starting point.
+
+## ASIC I/O ports touched during boot
+
+Distinct `out` port targets and write counts during boot (ASIC register access —
+cross-reference the ASIC register maps in the hardware reference):
+
+| Port | Writes | Likely role |
+| --- | --- | --- |
+| `0x28` | 1580 | display/LCD controller (dominant) |
+| `0x15` | 88 | |
+| `0x21` | 54 | |
+| `0x10` | 17 | |
+| `0x02` | 14 | ASIC control |
+| `0x0A` | 13 | |
+| `0x08` | 12 | |
+| `0x2C` `0x24` `0x22` `0x26` `0x30` `0x3C` | few | ASIC control-register setup (from early boot) |
+
+## Method (reproduce)
+
+```
+xvfb-run -a mame psionwamx -rompath roms -debug \
+  -debugscript trace.txt -sound none -seconds_to_run 1
+# trace.txt:  trace boot_trace.asm   /   go
+```
+Then post-process `boot_trace.asm` for instruction/port/vector frequencies.
+
+## Next RE steps
+
+1. Map each `brk` vector to its service (breakpoint ISR, correlate to C API).
+2. Trace `SCANAPP`/`DEMMAN` to resolve the `WL2` scanner data-retrieval path.
+3. Correlate the ASIC ports here with the HDK register maps.