18. WLA Symbols

Symbols can be optionally generated as a part of the assembly and link steps. With a compatible emulator, this can provide extra information for debugging a ROM, or otherwise help in understanding how it operates.

The symbols file can be generated by wlalink by adding “-S” onto the command line. This will output labels, definitions, and some other rudimentary data. Most prominently, this can be used to understand where the ROM output various sections such as subroutines and data, and be able to look that up in the emulator’s ROM or RAM space.

Extra information for address-to-line mapping can be provided by adding the following command line arguments: - Run object generation (e.g. “wla-65816”) with “-i” to include list data in the output obj files - Run wlalink with “-S -A” to generate symbols with information related to address-to-line mapping

Address-to-line mappings includes information to relate lines in the source files to individual instructions in the generated ROM. This can be used to provide richer disassembly in the emulator, or allow for rich debugging in an external IDE.

18.1. Information For Emulator Developers

In order to properly support loading of WLA symbol files, it is recommended to follow this specification below, especially so as to gracefully support future additions to the symbol files.

  • The file should be read one line at a time
  • Any text on a line following a ; should be ignored
  • Lines matching \[\S+\] in regex or [%s] in scanf code are section headers, and represent a new section. Note that no section data will start with [.
  • Lines following the section header are the data for that section. If you’re acknowledging the section, utilize that section’s specific formatting. Read lines that match until a new section header is encountered.
  • Unless otherwise specified, none of the data in any section should be assumed to be sorted in any particular way.

The following are the list of currently supported sections, what they mean, and how their data should be interpreted.

18.1.1. [labels]

This is a list of all Labels to sections of the ROM, such as subroutine locations, or data locations. Each line lists an address in hexadecimal (bank and offset) and a string associated with that address. This data could be used, for example, to identify what section a given target address is in, by searching for the label with the closest address less than the target address.

  • Regex match: [0-9a-fA-F]{2}:[0-9a-fA-F]{4} .*
  • Format specifier: %2x:%4x %s

18.1.2. [definitions]

This is a list of various definitions provided in code - or automatically during WLA’s processing - and values associated with them. Most prominently, WLA outputs the size of each section of the ROM. Each line lists an integer value in hexadecimal, and a string (name) associated with that value.

  • Regex match: [0-9a-fA-F]{8} .*
  • Format specifier: %8x %s

18.1.3. [breakpoints]

This is a list of hexadecimal ROM addresses where the .BREAKPOINT directive was used in the source assembly. Each line lists an address in hexadecimal (bank and offset).

  • Regex match: [0-9a-fA-F]{2}:[0-9a-fA-F]{4}
  • Format specificer: %2x:%4x

18.1.4. [symbols]

This is a list of hexadecimal ROM addresses where the .SYMBOL directive was used in the source assembly. Each line lists an address in hexadecimal (bank and offset) and a string associated with that address.

  • Regex match: [0-9a-fA-F]{2}:[0-9a-fA-F]{4} .*
  • Format specifier: %2x:%4x %s

18.1.5. [source files]

These are used to identify what files were used during the assembly process, especially to map generated assembly back to source file contents. Each line lists a hexadecimal file index, a hexadecimal CRC32 checksum of the file, and a file path relative to the generated ROM’s root. This could be used to load in the contents of one of the input files when running the ROM and verifying the file is up-to-date by checking its CRC32 checksum against the one generated during assembly.

  • Regex match: [0-9a-fA-F]{4} [0-9a-fA-F]{8} .*
  • Format specifier: %4x %8x %s

18.1.6. [rom checksum]

This is just a single line identifying what the hexadecimal CRC32 checksum of the ROM file was when the symbol file was generated. This could be used to verify that the symbol file itself is up-to-date with the ROM in question. This checksum is calculated by reading the ROM file’s entire binary, and not by reading any platform-specific checksum value embedded in the ROM itself.

  • Regex match: [0-9a-fA-F]{8}
  • Format specifier: %8x

18.1.7. [addr-to-line mapping]

This is a listing of hexadecimal ROM addresses (bank and offset) each mapped to a hexadecimal file index and hexadecimal line index. The file index refers back to the file indices specified in the source files section, so that the source file name can be discovered. This information can be used to, for example, display source file information in line with disassembled code, or to communicate with an external text editor the location of the current Program Counter by specifying a source file and line instead of some address in the binary ROM file.

  • Regex match: [0-9a-fA-F]{2}:[0-9a-fA-F]{4} [0-9a-fA-F]{4}:[0-9a-fA-F]{8}
  • Format specifier: %2x:%4x %4x:%8x