Annotations are embedded directly in the listing file using a specific format that 9900dis parses at the start of every run. Rather than maintaining a separate hints file, you mark up the listing itself — the tool reads your annotations, regenerates the output, and re-emits them in the new file. Understanding the exact syntax ensures your edits survive every re-run intact.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.
Line structure
A fully annotated instruction line has the following anatomy:| Field | Description |
|---|---|
LABEL | Optional symbol for this address. Up to 6 alphanumeric characters, no spaces, placed before the tab character. |
MNEMONIC operand(s) | The disassembled instruction, generated by 9900dis. Do not edit this field manually — it is regenerated on each run. |
pc:>XXXX | The program counter value at this instruction, in hex. |
w:>XXXX | The raw 16-bit word read from the ROM at this address, in hex. |
f:hint | Optional format hint. Currently, f:data is the only supported value. |
; user comment | Optional free-text comment, introduced by a second semicolon. |
The comment field (
; pc:>XXXX ...) is delimited by the first semicolon on the line. The user comment is delimited by a second semicolon. Any number of spaces may separate the format hint from the second semicolon.Labels
A label is any non-empty token that appears before the tab character at the start of an instruction line. Labels are associated with thepc:>XXXX value on that line and stored in a lookup table. On subsequent runs, any operand that resolves to a labelled address is replaced with the label name instead of the raw hex constant.
>0000 will appear as:
Label detection uses a simple tab-split — there is no regex length constraint in the parser. Any non-empty token before the first tab is recorded as the label. Keep labels short and xas99-compatible (typically uppercase, 1–6 characters) so the output reassembles cleanly.
Equates
Equates define symbolic names for fixed memory addresses — typically memory-mapped hardware registers or well-known ROM locations. They are written as standalone lines using the following format:(\w{1,6})\s+EQU\s+>(\w{4}) before generating output. When the four-digit hex address appears as an operand anywhere in the ROM, the equate symbol is substituted:
AORG directive.
The equate symbol must be 1 to 6 word characters. The address must be exactly 4 hex digits preceded by
>. Lines that do not match this pattern exactly are ignored by the parser.Data hints
By default, 9900dis attempts to decode every word as a TMS9900 instruction. When a word happens to encode a valid instruction but is actually data (a lookup table entry, a vector, a string byte pair, etc.), you can force it to be emitted asDATA by adding f:data to the comment field.
Before adding the hint, the word at >0000 decodes as an instruction:
f:data to the comment field:
f:data is the only supported format hint. The hint is detected as the fourth space-delimited token in the comment segment (the text between the first and second semicolons). Any other value in that position is ignored.Inline comments
Free-text comments can be added after a second semicolon on any instruction line. 9900dis captures everything after the second; (stripped of leading and trailing whitespace) and re-emits it with a tab-indented ; prefix on subsequent runs.
pc:>XXXX value, so they follow the instruction even if surrounding code shifts due to label substitution.
Annotation parsing rules
How labels are detected
How labels are detected
The parser splits each line on the tab character (
\t) and takes the first segment. It then strips leading and trailing whitespace. If the resulting string is non-empty, it is recorded as the label for the address given by pc:>XXXX on that line. Because label detection requires a pc:>XXXX segment (i.e. at least one ; on the line), equate lines are not incorrectly interpreted as labels even though they begin with a symbol.How equates are detected
How equates are detected
Each line in the listing is tested against the regular expression:The first capture group becomes the symbol name; the second capture group (interpreted as a base-16 integer) becomes the key in the equates table. Lines that do not match — including instruction lines that happen to contain
EQU elsewhere — are skipped.How format hints are detected
How format hints are detected
The parser splits each line on
; and works with the second segment (index 1), which contains the pc:>XXXX w:>XXXX [f:hint] fields. That segment is then split on spaces. If the resulting list has more than three elements, the element at index 3 is the format hint. Currently, only f:data is acted upon; any other value is stored but has no effect on disassembly.How inline comments are preserved
How inline comments are preserved
Lines are split on
;. If there are three or more segments, the third segment (index 2) is the user comment. It is stored in a dictionary keyed by the integer PC value. When the listing is regenerated, 9900dis looks up the PC of each instruction and, if a comment exists, appends \t; <comment> after the structured comment field.