msx-regen

Files (1)

• SKILL.md

SKILL.md (first lines)

# MSX bank regen

Need `z80dasm`, `tools/sjasmplus`, a `workbench.cfg`, and a built `<Game>.rom`
(`make`, or `ROM=`). Missing assembler: `tools/workbench/bin/install-sjasmplus`
(`msx-scaffold`). Run from the **game** repo root. Do not invent a one-off
disassembler.

## Regen one bank

```
tools/workbench/msx/regen-bank.sh <n> [origin-hex] [banks/banks_<stem>.blocks]
```

`<n>` is the 8 KiB bank index (0-based). Origin defaults to `workbench.cfg`
`bank_org`. Optional `.blocks` marks code vs data (rendering only). After
windows exist, pass that window’s `.blocks` for every slice in the group
(the script keeps blocks whose **start** is in this 8 KiB; z80dasm rejects a range outside the image). How to seed it:
`msx-code-data`. Window merge: `konami-msx-disasm`. Do not regen until
`bank_org` matches the pager.

Writes gitignored scratch:

- `generated/<prefix>NN.generated.asm` — listing comments stripped; **fold this**
- `generated/<prefix>NN.raw.asm` — address/opcode listing; temporary reference

Never copy the generated file over annotated source. Never commit z80dasm
`;addr bytes ascii` tails. `strip-listing.py` is the safety net.

## Graduate one leftover bank

1. Confirm CPU origin from paging helpers; put it in `bank_org` and the
   master’s `PHASE` (`msx-code-data`). Do not z80dasm gfx / packed-PSG /
   table-only payload — those stay `INCBIN` until the consumer is named,
   then labelled `.asm` (`msx-code-data` peel).
2. `regen-bank.sh N [origin] [banks/banks_<stem>.blocks]` (or `bankNN.blocks`
   before windows exist).
3. Grep `generated/<prefix>NN.raw.asm` for `;illegal sequence`.
4. Prepend a header; copy the **generated** file (not raw) into the window
   `.asm` (or `banks/bankNN.asm` if that 8 KiB is still alone). Drop
   z80dasm’s `equ` lines (those symbols live in other banks or `bios.inc`).
   Master: `INCBIN` → `INCLUDE`.
5. BIOS-lie audit on non-`call`/`jp`/`jr` lines. `make verify`, then
   `make banks` (drops the leftover `.bin`).
   Do not regen a window after its `ram.inc` names have been applied in the
   asm. `ram.inc` is kept out of `msx.sym`, so regen writes those immediates
   back as hex. If a regen is required, re-apply the map afterward
   (`konami-msx-disasm`).
6. Two **windows** that share a CPU range cannot share z80dasm `lXXXXh` /
   `sub_XXXXh` names. Wrap later windows in one `MODULE` / `ENDMODULE`, or
   prefix auto labels. Do not put those addresses in `msx.sym`. Combining
   contiguous banks: `konami-msx-disasm`.

## Symbols (`msx.sym` is flat, the ROM is banked)

```
tools/workbench/msx/bank_sym.py N
tools/workbench/msx/bank_sym.py --audit
```

Keep new names in the game’s `msx.sym`. Do not split into committed per-bank
`.sym` files.

## Leftover bins

```
tools/workbench/msx/split-rom.sh
```

Extracts unmigrated `banks/bankNN.bin` from the ROM; deletes bins for migrated
banks (`migrated=all` or a `bankNN.asm` exists).

After regen: audit BIOS-name lies on non-`call`/`jp`/`jr` lines. `make verify`
after every edit; never commit a break. Naming: `konami-msx-disasm`.

From 0xe1f/MSXDAW, Apache-2.0.

More from 0xe1f/MSXDAW