MZBAS/ANALYSIS.md

# Ghidra project analysis — Orion-MSXBASIC / MZBAS$.BRU

Program: **MZBAS$** — MSX BASIC for the Orion-128 (Z80), tape image loaded at `0x0000`.
Banner in the image: `MSX  system / version 1.2/M / MSX BASIC / Copyright 1983,1993 by Microsoft,OBERON Inc`
i.e. the MSX BASIC 2.1 codebase ported to Orion-128 (64K RAM, Z80).

## Source file format (`MZBAS$.BRU`)

Cassette-style image, 33664 (0x8380) bytes:

| Offset | Size | Content |
|--------|------|---------|
| 0x0000 | 8 | name `MZBAS$··` |
| 0x0008 | 2 | load address `0x0000` (LE) |
| 0x000A | 2 | length field `0x8300` (LE; payload is actually 0x8370) |
| 0x000C | 4 | unknown/reserved (`00 49 53 D4`) |
| 0x0010 | 0x8370 | program image → `ram:0x0000–0x836F` |

Mapping verified: file offset 0x10 = `ram:0000`, banner at file 0x8251 = `ram:08241`.
The tape image contains **only** the BASIC program (0x0000–0x836F); high memory in the
Ghidra project was modeled separately.

## Memory map (as modeled in Ghidra)

| Block | Range | Size | Notes |
|-------|-------|------|-------|
| MB | 0000–BFFF | 48K | BASIC program image (real data ends at 0x836F) |
| SCREEN | C000–EFFF | 12K | MSX screen RAM (uninitialized in image) |
| MON_RAM | F000–F2FF | 768B | character generator (`MON_CHARGEN`) |
| ORI_F300_CODE | F300–F3FF | 256B | Orion I/O patch code — **duplicated in the project from its in-image home at 0x0C22** (bytes identical) |
| IOPORTS | F400–F7FF | 1K | `PORT_F400_KBD` (keyboard, 10 xrefs), USR1 F500, USR2 F600, EXT F700, FDC regs F701–F708 |
| MONITOR | F800–FFFF | 2K | zeroed in the image; real monitor lives in Orion ROM. `SYSINIT` does `CALL 0xF830` into it |
| PORTS (io space) | 0000–00FE | 255B | e.g. `P_SW_MEM` io:00F9 (14 xrefs), `P_SW_SCR` io:00FA |

## Entry point and startup

- **Entry**: `SYSINIT` at `0x0000` = `JP 0x24A2`.
- `0x24A2`: `CALL 0xF830` (Orion monitor), sets `SP`, saves it to `0x8D01`, then
  initializes the keyboard port (`LD A,0xAA / LD HL,0xF400 ...`), calls `0x0C0A`,
  does a wait-loop on BC/DE counters, and hands control onward.

## Major structures found

### 1. Vector table, `0x0000–~0x00EC`
~78 entries of `JP nn`. The first ~15 slots are 3-byte-aligned with NOP padding
(`0x0000 JP 24A2`, `0x0008 JP 24C6`, `0x0010 JP 24C9`, `0x0018 JP 2111`,
`0x0020 JP 1B55`, `0x0028 JP 24CC`, …), then densely packed JPs from `0x0038`
(`JP 03AB, 1AA1, 0228, 022E, 028D, 01EB, 0207, 0241, 1B5B, 04AC, 04F6, 0CE8, …`).
This is the built-in command/statement dispatch table; real code starts at ~`0x00ED`.

### 2. Command-prefix table, `0x1AAD–~0x1B50`
Fixed 16-byte records: 8-byte text + 8 zero bytes:
`LOAD"`, `AUTO `, `GOTO `, `LIST `, `RUN␍`, `SAVE"`, `CLOAD"`, `CONT␍`, `LIST.␍`, …
Used to recognize whole-line commands. Table is pointed to from code at `0x1AA1`
(`LD HL,0x1AAD / CALL 0x0FF0`).

### 3. Keyword/function lookup table, `~0x3AF5–0x3DA8`
Variable-length entries: a short distinguishing fragment of the keyword (1–5 chars)
followed by a 2-byte handler address. Fragments include:
`NKEY`(INKEY$), `PRIN`(PRINT), `ETUR`(RETURN), `ESTOR`(RESTORE), `ESUM`(RESUME),
`IGHT`(RIGHT$), `CREE`(DECLARE), `TRING`(STRING), `PACE`(SPACE$), `ARPT`(VARPTR),
`EFST/EFIN/EFSN/EFDB`, `ELET`, `OCAT`, `FILE`, `RESE`, …

### 4. Error table, `0x3DAB–~0x4070` (`MB_ERRTAB`)
Zero-terminated messages, indexed by error code — matches `errors.inc`:
1 `NEXT without FOR`, 2 `Syntax error`, … 19 `Line buffer overflow`,
0x32 `FIELD overflow`, 0x33 `Internal error`, 0x34–0x3B file errors,
plus Orion-specific additions. Followed by `" in "`, `"Ok␍␊"`, `"Break"`.

### 5. Character tables, `0x07E2–0x089A`
Digit/upper/lower case conversion tables (`;1234567890-:`, `-@abcdefghijklmn`, …).

### 6. Banner & workspace, `~0x8200–0x836F`
Code for memory allocation/stack setup (refs to `0x8CC2/0x8CC4`, `0x8EAF/0x8EB0/0x8EB2`)
immediately followed by the banner strings at `0x8241` and end-of-image code at `0x836F`.

### 7. Orion patch code, image copy at `0x0C22` (= project block F300)
Small I/O routines writing port `0xF9` (`LD A,1 / OUT (F9),A`) with HL-based loops —
the Orion-128 hardware glue that replaces MSX I/O calls.

## Project state / gaps

- **2006 symbols** (original Microsoft label names) are present, but:
  - **0 functions** defined, and no instruction listing outside the few ranges
    disassembled in this session (`0x0000–0x005F`, `0x1A80–0x1B47`, `0x24A2–0x2501`,
    `0xF830–0xF86F`).
  - Auto-analysis is marked complete (nothing left to run); scripts are disabled
    (`GHIDRA_MCP_ALLOW_SCRIPTS` not set), so bulk work must go through individual tools.
- High memory (SCREEN/MON_RAM/MONITOR) is placeholder; only F300 patch code and
  port labels carry real content.

## Suggested next steps (for the reconstruction in `mzbas.asm`)

1. Run `reanalyze` or create functions at the vector-table targets to get call graphs.
2. Walk the dispatch table at `0x0038+` — each JP target is a statement handler;
   naming them from the MSX BASIC 2.1 source (`MB_*` labels) will anchor the rest.
3. Reconstruct the global variable block around `0x8C00–0x8F60` (pointers seen:
   `0x8CC2/0x8CC4`, `0x8D01`, `0x8EAF/0x8EB0/0x8EB2`) — these are the BASIC workspace
   (`MB_BASLIM`, program pointer, stack, etc. in the original).
4. The 16-byte command records at `0x1AAD` and the fragment table at `0x3AF5`
   translate directly into assembler tables for sjasmplus.