konami-msx-disasm

Files (1)

• SKILL.md

SKILL.md (first lines)

# Konami MSX disassembly

Workbench: `tools/workbench` (this repo as a submodule). Game-specific dumpers
stay in the game’s `tools/`. Read the game’s `docs/progress.md` and
`docs/game-notes.md` plus `workbench.cfg` before assuming a mapper layout.

## Placement

If a helper would apply to a **second** MSX/Konami cart, put it in MSXDAW and
run `bin/add-skill` / `bin/install-skills`. If it names this ROM’s stems, RAM,
banks, or dumpers, keep it in the game. No ROM-specific addresses in DAW skills.

## Non-negotiables

- **Byte-exact round-trip at every step.** The build must reproduce the original
  ROM byte-for-byte (`make verify` checks SHA-1 against a committed
  `<Game>.sha1`). Run it after every edit. Never commit a change that breaks it.
  An original ROM dump is not required to assemble or verify.
- **No leftover binaries.** End state is labelled `.asm` for every ROM byte
  (code and identified data). Banks start as `INCBIN` and graduate; PNG/WAV
  catalogues are previews, not assemble source. Don’t mass-convert unknown
  blobs to opaque `db`. Peel: `msx-code-data`.
- Assembler = sjasmplus, disassembler = z80dasm.

## Bank vs segment

- **Bank** — 8 KiB mapper unit.
- **CPU page** — 16 KiB MSX slot page.
- **Window file** — one `.asm` (and matching `.blocks`) for every set of
  banks this cart maps together. See below.
- Do not say **segment** in new text.

Mapper first: size, bank count, switch addresses, which pages are switchable.
Konami4: typically `6000`/`8000`/`A000` (page `4000-5FFF` often fixed). Konami
SCC: `5000`/`7000`/`9000`/`B000`; SCC at `9800` after `3F` → `9000`. Document
it at the top of `<Game>.asm`. Do not copy another game’s window grouping.

## Window files (combine contiguous banks)

Bootstrap is one `banks/bankNN.asm` per 8 KiB (`msx-bootstrap`). That split is
scaffold. Once paging helpers are named (`page_triplet` / pair / A000-only
wrappers → `bank_org`), **merge every set of banks that helper maps as
consecutive mapper ids into consecutive CPU pages** into one window file,
one `PHASE` covering the whole range.

A Konami triplet `ld a,N / write / inc a / write / inc a / write` into
6000/8000/A000 is one window (banks N, N+1, N+2). An 8000+A000 pair is one
window. A bank that is *also* switched A000-only still lives in its triplet
file. Do **not** merge two pagers just because they reuse the same CPU
addresses at different times — that is a `MODULE`, not one file. Bank 0 stays
its own window when page 4000–5FFF is never remapped.

Stem: `banks_` + concatenated **unpadded hex** ids in CPU order
(`banks_123`, `banks_9a`, `banks_bcd`, `banks_ef`). Same stem for
`banks_<stem>.asm` and `banks_<stem>.blocks`. Section the `.blocks` file per
8 KiB (`; bank 1 @ 0x6000`); `regen-bank.sh` keeps only blocks whose **start**
falls in the slice being disassembled (`msx-regen`, `msx-code-data`).

Later windows that occupy a CPU range already used by an earlier window wrap
the INCLUDE in one `MODULE` (not one MODULE per 8 KiB) so z80dasm `lXXXXh`
names do not collide. The first window in that range can stay global. Do not
put those overlapping addresses in `msx.sym`.

Fold generated 8 KiB listings into the window file by hand; `make verify`.
`.blocks` / peel: `msx-code-data`.

## Naming a window

A finished resident window has essentially no automatic labels (`lXXXXh`,
`sub_XXXXh`, `loc_`). Trailing comments land on roughly a quarter of its
code lines, and they say why. That density is the target, not the first
pass. A comment that restates `ld a,(named_field)` adds nothing.

Name the window that stays mapped (bank 0, plus the boot triplet it maps)
before folding the next code window. That window holds the loop, the RAM
writers, and the dispatchers. Another raw listing adds automatic labels
and does not add names.

1. **Work-RAM map.** Count `C000`–`FFFF` immediates in the folded window.
   Map the densest contiguous bands into `banks/ram.inc` first. Name a byte
   only when a writer and a reader agree; leave unread holes as hex. Then
   replace those immediates once across the window. `ram.inc` stays out of
   `msx.sym` (z80dasm would rewrite every match).
2. **Repeated index record.** If `ix+n` / `iy+n` offsets cluster into one
   span, that span is one record (actor slot, projectile, sound channel).
   Name a field when two uses agree; leave the rest `field_N`. One struct
   rewrites every offset in the window.
3. **High fan-in routines.** `romscan xref` the automatic callees; rename
   the ones with the most callers first. Rename that routine’s branch
   labels in the same pass. A banner goes on the entry only: what it does,
   and which registers or RAM are inputs. Branch targets get a short name
   and usually no paragraph. The name states the job. An address, a
   register, or a size is not a name (`blit_c0`, `row_e5`, `origin_7`).
   The ROM address stays in the banner.
4. **Symbolic dispatch.** Once those handlers have names, the inline word
   table is `defw` of the names. `dec a` before the call means index base 1
   (`msx-code-data`). When an index byte’s values are known, put the ids in
   an `INCLUDE`d `.inc`, never `msx.sym`.
5. **Split after the name exists.** A named routine may move to its own
   file, `INCLUDE`d from the window. The filename is the chunk. Splitting a
   window that is still `sub_` labels only scatters them.
6. **Why-comments last**, on the routine being named. Roughly one code line
   in four in a finished window. If a line is already in front of you and
   the why is confirmed, write it then (column 32). Do not sweep a raw
   listing from the top. Guessing does not count.

Resident-page helpers with a unique address (`fill` routine, the dispatcher)
may go in `msx.sym`, so the next bank’s regen emits `call` that name.
Overlapping window labels stay out of `msx.sym`. Do not regen a window
after step 1 has been applied in the asm: regen does not see `ram.inc` and
writes the hex back (`msx-regen`).

Low call density relative to the resident window means graphics or pointer
tables. Leave those `INCBIN` until a consumer is named (`msx-code-data`).

## Unused but present

A slot, id, or string that a named consumer would accept, and that nothing
in the ROM selects, stays in the source. Record it in the game repo's

From 0xe1f/MSXDAW, Apache-2.0.

More from 0xe1f/MSXDAW