Using a Language Model to Explain 6502 Assembly and Annotate Disassemblies

What a language model can contribute to a disassembly

A disassembly presents machine code as assembly instructions, usually with addresses and sometimes raw byte values. It is more readable than a hexadecimal dump, but it still assumes familiarity with processor registers, addressing modes, flags, and branching. A short routine can be difficult to understand when its variables are stored in unnamed memory locations or when the surrounding program is unavailable.

A language model can provide an initial explanation of individual instructions and their relationships. It can describe why a routine loads a value into the accumulator, compares it with another value, or branches when a processor flag has a particular state. It can also suggest useful labels for memory locations and identify places where a routine appears to call a subroutine or return to its caller.

This is particularly useful when annotating old software for which comments have been lost. However, the model may recognize a familiar pattern and assign it a familiar purpose without sufficient evidence. A sequence that resembles a joystick read, for example, could be part of a different input routine or a custom hardware interface.

• Translate individual mnemonics into plain language.
• Explain register and flag dependencies.
• Identify conditional branches and likely control-flow structure.
• Suggest provisional names for memory locations.
• Separate visible instruction behavior from inferred program purpose.

Give the model enough assembly context

An isolated instruction is rarely enough for a useful explanation. Provide a continuous disassembly containing addresses, opcodes when available, labels, and the instructions surrounding the target routine. Include the processor family and any known memory-map information. For a 6502 system, distinguish the original processor from variants that introduce additional instructions or different behavior.

A good instruction asks for a line-by-line explanation that preserves addresses and does not invent comments or symbol names as established facts. It should request an explanation of each register change, memory access, flag dependency, and branch destination. Ask the model to identify missing context explicitly, especially when the routine accesses hardware registers or calls code outside the supplied range.

For example, an annotation request might specify that an address such as $00A2 is an unknown zero-page location. The model can describe how the routine reads or writes that address, but it should not declare it to be a player position or timer without supporting evidence from the surrounding program.

Read 6502 instructions through their actual effects

The 6502 has an accumulator, X and Y index registers, a stack pointer, a program counter, and a processor status register containing flags. These components interact. An instruction can change a register and also update flags that determine whether the next conditional branch is taken. An explanation that describes only the visible arithmetic can therefore miss the routine's central behavior.

Consider the illustrative sequence LDA #$03, CMP #$05, and BCC LOWER. LDA places the immediate value 3 in the accumulator. CMP compares that value with 5 and sets processor flags according to the subtraction comparison without storing the subtraction result. BCC branches when the carry flag is clear. For this unsigned comparison, 3 is below 5, so the branch condition is satisfied.

That example demonstrates why a useful annotation needs to explain flag behavior, not simply translate mnemonics into English. Signed and unsigned interpretations also deserve care. The carry flag and the negative flag do not mean the same thing, and a model that confuses them can produce a convincing explanation of completely different control flow.

• Track accumulator changes after arithmetic and load instructions.
• Identify which instructions affect the carry, zero, negative, and overflow flags.
• Follow branch destinations using their actual addresses.
• Distinguish immediate, zero-page, absolute, indexed, and indirect addressing.
• Check stack operations and subroutine return behavior.

Turn explanations into emulator trace questions

An emulator trace can show the program counter, instruction, register values, processor status, and relevant memory changes over time. Its exact facilities depend on the emulator and the target machine. When debugging an explanation, select a small execution interval around the instruction or branch in question. A trace is most useful when its starting state is known and the relevant input conditions can be reproduced.

Suppose an explanation claims that a routine exits when the accumulator reaches zero. The relevant question is whether the instruction immediately before the branch actually sets the zero flag and whether the branch tests that flag. Compare the trace's accumulator and status register at that point with the instruction sequence. A branch that depends on carry cannot be justified by a zero value alone.

The trace should be read alongside the processor documentation. Emulator behavior can depend on its selected machine model, timing implementation, and configuration. A trace from an incorrectly configured system may show a different execution environment from the one the original program expected. Record the emulator identity and machine configuration when preparing annotations for other readers.

• Record the starting program counter and relevant register values.
• Identify the instruction that establishes the branch condition.
• Compare the status register before and after that instruction.
• Follow the actual branch destination.
• Repeat the trace with a documented starting state when necessary.

Separate observed behavior from inferred intent

A strong disassembly annotation has at least two levels. The first describes what the instructions demonstrably do. The second offers a possible explanation of why the original programmer arranged them that way. For example, repeated subtraction followed by a conditional branch might suggest a division routine, but the complete memory inputs and outputs are needed before that purpose can be assigned confidently.

This distinction is especially important for hardware access. A store to a memory-mapped address can affect a display, sound generator, input device, or another system component. The address alone may suggest its role, but the target machine's memory map and hardware documentation determine what the access means. A language model can confuse similar addresses across different computers built around the same processor.

Use provisional labels such as UNKNOWN_ZERO_PAGE_A2 or POSSIBLE_COUNTER until the surrounding code supports a more descriptive name. Preserve original addresses in the annotation so another researcher can follow every claim back to the disassembly.

Apply the same discipline to Z80 routines

The Z80 presents a different instruction set and register model, so a 6502 explanation cannot simply be transferred to it. Its main and alternate register sets, index registers IX and IY, stack operations, and flag behavior all require processor-specific interpretation. A model explaining a Z80 routine should be given the exact processor context and should distinguish instructions available on the target variant.

For example, a Z80 sequence using LD A,n, CP n, and JR C,label performs a comparison and a relative conditional jump. The comparison affects flags, while the jump depends on the carry condition. The meaning of the resulting control flow must be established from the Z80 instruction definitions, not from an approximate analogy with a 6502 branch.

The practical workflow remains similar: supply sufficient context, request instruction-level explanations, preserve uncertain interpretations, and use an emulator trace to examine the actual execution state. Keep separate reference material for each processor family. A shared annotation format is useful, but processor semantics should never be shared by assumption.

Build annotations another researcher can follow

An annotation should identify the address range, processor, source of the disassembly, and any assumptions about memory mapping. Keep original bytes alongside the assembly where possible. Each explanatory note should distinguish direct instruction effects from inferred functionality, and references to processor documentation should be precise enough for another reader to find the relevant definition.

Avoid allowing a language model to rewrite the original assembly into a more familiar form without preserving the source. Suggested labels belong in a separate annotation layer. This is particularly important when documenting undocumented software, where an apparently unnecessary instruction may be a timing delay, compatibility measure, or side effect required by the hardware.

For the next disassembly, choose a routine of approximately 10 to 20 instructions. Ask for a line-by-line explanation, identify every claim involving a flag or memory access, and compare those claims with the processor reference and an emulator trace. Keep the resulting notes attached to the original addresses.

Questions readers ask