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.

Labels let you assign meaningful names to addresses in your listing. Once defined, 9900dis substitutes the label name wherever that address appears as an operand in subsequent disassembly passes — turning raw hex references into readable symbolic code.

​
Adding a label

Place the label in the first column of the line that corresponds to the target address, before the tab character. The label must start at column 0 with no leading whitespace. 
RESET 	DATA    >f0a0            ; pc:>0000 w:>f0a0 f:data
In this example, the label RESET is now associated with address >0000. On the next run, 9900dis reads the listing back and stores the association >0000 → RESET.

​
How labels are substituted

After re-running the disassembler, any instruction whose operand resolves to the labelled address uses the symbolic name instead of the raw hex value. Before (first pass — no label defined): 
      	BLWP    @>0000           ; pc:>0824 w:>0420
After (second pass — RESET defined at >0000): 
      	BLWP    @RESET           ; pc:>0824 w:>0420
Label substitution applies to:
  • @LABEL — memory-direct and memory-indirect operands (e.g., BLWP @RESET, MOV @GPLRD,r1).
  • Jump targets — branch instructions (JMP, JEQ, JGT, JLT, JNE, etc.) resolve their calculated target address against the label table and emit the symbolic name when a match is found.

​
Label naming rules

Label detection in hints.py works by splitting the line on ;, then splitting the first segment on \t and stripping whitespace. There is no regex length constraint on labels — the parser accepts any non-empty token that appears before the first tab. Practical constraints:
  • No spaces — the label must be a single unbroken token before the tab character.
  • Column 0 only — the label must appear before the first tab on the line; any leading whitespace causes it to be stripped, but a tab-prefix will result in an empty token (no label recorded).
  • Keep labels short and compatible with xas99 assembler conventions (typically uppercase, 1–6 characters) for the output to reassemble cleanly.

​
How labels are parsed

hints.py reads the existing listing file line by line. Each line is split on ; to separate the instruction column from the metadata comment. The code then takes the instruction column (everything before the first ;) and splits it on the tab character, extracting the very first token: 
label = segments[0].split('\t')[0].strip()
if label:
    self.labels[pc] = label
If that token is non-empty, it is stored as the label for the PC address extracted from the pc:>XXXX field in the comment. This means the label is permanently tied to the address — not the line number — so it survives any reorganisation of the listing. When the disassembler later encounters an operand value, it calls hex_or_label() in rom.py, which checks the label table before falling back to raw hex: 
def hex_or_label(self, value):
    equ = self.hints.equate(value)
    if equ:
        return equ
    label = self.hints.label(value)
    if label:
        return label
    return self.word_to_hex(value)
Equates are checked first; labels are checked second.

​
Before and after example

Pass 1 — raw output, no annotations: 
      	DATA    >f0a0            ; pc:>0000 w:>f0a0
      	DATA    >83e0            ; pc:>0002 w:>83e0
      	BLWP    @>0000           ; pc:>0824 w:>0420
Edit the listing to add a label at >0000: 
RESET 	DATA    >f0a0            ; pc:>0000 w:>f0a0 f:data
      	DATA    >83e0            ; pc:>0002 w:>83e0
      	BLWP    @>0000           ; pc:>0824 w:>0420
Pass 2 — label substituted throughout: 
RESET 	DATA    >f0a0            ; pc:>0000 w:>f0a0 f:data
      	DATA    >83e0            ; pc:>0002 w:>83e0
      	BLWP    @RESET           ; pc:>0824 w:>0420
Every reference to >0000 — no matter how many there are in the ROM — now shows RESET.
Name your reset vector and interrupt handlers first. They are the key entry points for the TMS9900 architecture, and labelling them will produce the most substitutions across the rest of the listing in a single re-run.

Build docs developers (and LLMs) love

Get started for freeTalk to us