NOTE: This spec is subject to change during the development period. This spec version details V0.9.
CodeX creates two different debug files for your program. The first, DBG, contains a description of your program region and labels for various locations and values. Label values may be contained within your program region, or they may refer to somewhere else in memory, or they may refer to an arbitrary value. The second file, DBI, contains meta data to allow CodeX to properly interpret memory as constants (bytes, words, or string) and expression information to indicate if an instruction argument is a function of another value (e.g. high or low byte).
DBG File Format
This section details the file format of the DBG file. The layout of this data in the Assembly Environment memory will be identical in memory. It is designed to fit in 8 K chunks of high memory.
Some clarification on the entries:
address - This is the CBM "load address" and is ignored by the X16AE.
TAG - This value uniquely identifies the version of the DBG file. V0.5 == "CDF02\000". Note this version will NOT read the previous version.
pgm_region - Minimum and maximum address for the loaded code (including constants).
start_address - Start address of the machine code, exclusive of the basic bootstrap.
label_entries - Two words for each label. Must be the same number of entries as count.
label - The zero terminated string of the label. Must be the same number of entries as count.
label entry offset - The offset from the start of the TAG to the string value.
DBI File Format
This section details the file format of the DBI meta data file. The layout of this data in the Assembly Environment memory will be identical in memory. It is designed to fit in 8 K chunks of high memory.
Expressions are stored as a list of 5 byte entries. The list is sorted from lowest "entry address" to the highest "entry address". Each entry is denoted by the type byte. The low order 6 bytes may have the following values:
0 - None (not likely to be used)
1 - High byte of value ( ">value")
2 - Low byte of value ( "<value")
3 - Pseudo instruction for ".byte"
4 - Pseudo instruction for ".word"
5 - Pseudo instruction for ".cstr"
6 - Pseudo instruction for ".pstr"
The high bit (e.g. $80) indicates that the expression value is an address. The second high bit (e.g. $40) indicates that the expression is a data statement.
As an example, consider the following code:
*=$801
lda #<main
main:
nop
The value of the label "main" is $803. The expression generated is for the low byte value of main. The expression entry will be:
$0108 The instruction at location $801 has this expression
$82 The argument refers to an address value $80 and the function is low byte
$0308 The value of this expression is $0803 (CodeX will look up the label for this address to display)
Whereas the following example is slightly different
*=$801
lda #>1234
main:
nop
$0108 The instruction at location $801 has this expression
$01 The argument refers to an address value $80 and the function is low byte
$3412 The value of this expression is $1234 (CodeX will MOT look up the label for this value to display)