Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/caljer1/9900dis/llms.txt

Use this file to discover all available pages before exploring further.

This quickstart walks you through the core 9900dis workflow: run an initial disassembly pass, read the output, add labels and equates, and re-run to get a progressively more readable listing. By the end you will understand how the iterative annotation loop works and be ready to apply it to your own ROM files.
Before you begin, make sure 9900dis is installed and accessible on your PATH (or that you know the full path to the binary). You will also need a binary ROM file to disassemble. See installation if you have not set up 9900dis yet.
1

Run the first pass

Run 9900dis with the base address of your ROM (--aorg), the input binary (--rom), and the output listing file (--listing):
9900dis --aorg 6000 --rom sys.bin --listing sys.asm
  • --aorg 6000 sets the base address to >6000 in hex. This is the address the ROM is mapped to in the CPU’s address space. The disassembler uses it to compute the correct program counter value for each instruction.
  • --rom sys.bin is the input binary file.
  • --listing sys.asm is the output file. If it does not exist it will be created. If it already exists, any annotations you have added will be read back and preserved.
After the first run, sys.asm contains a raw listing with no symbolic information.
2

Examine the raw output

Open sys.asm in a text editor. A typical raw output line looks like this:
      	SOCB    @>028a,r2        ; pc:>0000 w:>f0a0
Each line contains:
  • The decoded mnemonic and operands (SOCB @>028a,r2).
  • A comment with two fields: pc:>0000 is the program counter (ROM base address plus offset), and w:>f0a0 is the raw 16-bit word stored at that address.
At this stage all addresses are numeric. The iterative workflow is about replacing those numbers with meaningful symbols.
3

Add a label

Identify a line whose address you know to be an entry point. Add a label in the label column (the text before the mnemonic, separated by a tab):
RESET 	DATA    >f0a0            ; pc:>0000 w:>f0a0 f:data
Two things were done here:
  1. The label RESET was added to the left of the mnemonic.
  2. The f:data format hint was appended to the comment to tell the disassembler to treat this word as a data value rather than an instruction on the next run.
Labels are associated with the pc value on that line. Save the file.
4

Re-run and see the improvement

Run the disassembler again with the same arguments:
9900dis --aorg 6000 --rom sys.bin --listing sys.asm
The disassembler reads back sys.asm, picks up the RESET label at address >0000, and rewrites every reference to that address using the symbol. For example, a BLWP instruction elsewhere in the ROM that previously read:
      	BLWP    @>0000           ; pc:>0824 w:>0420
now reads:
      	BLWP    @RESET           ; pc:>0824 w:>0420
Every reference to >0000 throughout the listing is replaced with @RESET automatically.
5

Add an equate

For memory-mapped I/O addresses and other constants that are not inside the ROM itself, use an equate. Add a line anywhere in the listing (typically near the top):
VDPIO	EQU	>E000
Re-run the disassembler. Any instruction that references the address >E000 as an operand will now use the symbolic name:
	MOVB	@VDPIO,r8
instead of the raw address:
	MOVB	@>E000,r8
Repeat this process — adding labels, equates, f:data hints, and comments — across as many passes as needed until the listing is as readable as you require.

​
Next steps

Iterative workflow

Learn the full iterative annotation loop and strategies for identifying entry points in complex ROMs.

Annotation format

Complete reference for labels, equates, format hints, and inline comments.

Command reference

All command-line options for 9900dis, including --aorg, --cpu, and --version.

Build docs developers (and LLMs) love

Get started for freeTalk to us