Skip to content

Source Equates and Scoped Replacements

Jump to bottom
HoraceAndTheSpider edited this page Jul 23, 2026 · 1 revision

Source equates and scoped replacements

Reverse-engineered source sometimes gives an immediate constant the appearance of an address. This happens when the original instruction contains a long numeric value which coincides with an address in the program. Treating that value as a referenced data label can prevent an otherwise valid data block from being extracted and replaced.

The SPS 439 disassembly provides a confirmed example:

move.l  #adrL_0186A0,d1    ;223C000186A0

In this disk-reading routine, $000186A0 is a countdown value used while waiting for disk DMA completion. It is not a pointer to the data later labelled adrL_0186A0. The clearer representation is:

DiskReadTimeoutCount: equ $000186A0

move.l  #DiskReadTimeoutCount,d1    ;223C000186A0

The opcode remains 223C000186A0, so the correction improves the source without changing the executable.

Why replacements must be scoped

Many small constants have several unrelated meanings. For example, #$40 might represent character form $40 (Zendik) in a character-selection routine, but the same literal can be a count, flag, colour or size elsewhere.

A constant must therefore never be replaced globally merely because its value matches. A confirmed replacement records:

  • the executable profile;
  • the EQU name and value;
  • the labels bounding the relevant routine or source region;
  • the complete original instruction;
  • its encoded opcode bytes;
  • the replacement instruction; and
  • whether the finding is verified, proposed or disabled.

The bounding labels remain stable when source line numbers change. The opcode acts as a byte-level fingerprint. Relabel stops if the labels are missing, the instruction is not found exactly once, or the opcode differs.

EQUATES worksheet

These findings are recorded on the optional EQUATES worksheet in segments.xlsx:

Column Purpose
profile Executable profile to which the finding applies.
equ_name Human-readable source constant.
equ_value Original numeric value.
scope_start, scope_end Labels bounding the confirmed use.
source_match Complete instruction in the original disassembly.
expected_opcode Original encoded instruction bytes.
source_replace Complete instruction using the EQU.
status verified, proposed or disabled.
source_comment Concise explanation suitable for generated source.
notes Optional research notes.

Rows marked proposed document a possible meaning but do not change generated source. The same EQU name and value may be repeated when several independent uses have been confirmed in different routines.

An EQU with no identified instruction may leave the scope and instruction fields blank. It remains documented without causing a source rewrite.

Relationship to extracted data

Correcting false references is important before replacing data with INCBIN. Inspector deliberately retains a source data block if an internal label still appears to be referenced by code that will remain. Once a false operand has been converted to its genuine constant, that safety check can distinguish real references from disassembly artefacts and remove the complete validated block.

This is separate from the temporary aliases used for data_start / data_append layouts. Those aliases represent genuine addresses inside a contiguous data block and exist only until the split INCBIN labels are generated.

Clone this wiki locally