NAME

SYNOPSIS

DESCRIPTION

Perfect, in this case, means that you can take what dxa spits out and feed it right back into xa(1), and get the exact same object file you started with, even if sometimes dxa can't identify everything correctly. With a few extra options, you can tease and twist the output to generate something not quite so parseable, or even more like true assembler source.

OPTIONS

--datablock xxxx-yyyy

-b xxxx-yyyy

Defines the memory range xxxx to yyyy (hexadecimal, inclusive) to be a data block. The memory range can be further specified:

--datablocks filename

-B filename

Reads data blocks from file filename as if they had been specified on the command line, one per line (such as xxxx-yyyy, ?xxxx-yyyy, etc.).

--labels filename

-l filename

Causes label names to be read from file filename. This file format is the same as the labelfile/symbol table file generated by xa(1) with the -l option. The -l was chosen on purpose for consistency with xa(1).

--routine xxxx

-r xxxx

Specifies an address (in hexadecimal) that is declared to be a valid routine. It is strongly recommended that you specify the initial execution address as a routine. For example, for a Commodore 64 binary with a BASIC header that performs SYS 2064, specify -r0810 so that disassembly starts at that location (or use the -U option, which can automatically do this for you). Note that specifying this manually may have interactions with datablock detection (-d).

--routines filename

-R filename

Causes a list of routines to be read from file filename, one per line as if they had been specified on the command line.

--addresses option

-a option

Determines if and what kind of address information should be dumped with the disassembly, if any. Note that this may make your output no longer intelligible to xa(1). The valid options are:

--colon-newline

-N

--no-colon-newline

-n

A purely cosmetic option to determine how labels are emitted. Many people, including myself, prefer a listing where the label is given, then a tab, then the code (-n). Since this is my preference, it's the default. On the other hand, there are also many who prefer to have the label demarcated by a colon and a newline, and the code beginning indented on the next line. This is the way d65 used to do it, and is still supported with -N.

--processor option

-p option

Specify the instruction set. Note that specifying an instruction set that permits and disassembles illegal and/or undocumented NMOS opcodes may make your output unintelligible to xa(1). Only one may be specified. The valid options are:

--get-sa

-G

--no-get-sa xxxx

-g xxxx

Enables or disables automatic starting address detection. If enabled (the default), dxa looks at the first two bytes as a 16-bit word in 6502 little-endian format and considers that to be the starting address for the object, discarding them without further interpretation. This is very useful for Commodore computers in particular. If your binary does not have a starting address, you must specify one using -g or --no-get-sa followed by a hexadecimal address. The starting address will then be encoded into the output using * =.

--no-word-sa

-q

--word-sa

-Q

Only relevant if automatic starting address detection is enabled. If so, the default is to also emit the starting address as a .word pseudo-op before the starting address indicated with * = so that it will be regenerated on re-assembly (-Q). Otherwise, if this option is disabled, the starting address word will not be re-emitted and will need to be tacked back on if the target requires it. If you specify an address with -g, then that address will be used here too.

--no-detect-basic

-u

--detect-basic

-U

If the starting address is recognized as a typical BASIC entry point (currently supported for Commodore computers), then dxa will attempt to see if a BASIC header is present, and if so, determine its length and mark the section as a completely dead datablock not eligible for further disassembly or referencing. If the first line is a construct such as 10 SYS 2061, then dxa will additionally parse the provided address and mark it as a valid routine if the address is within the boundaries of the disassembled file. Note that although its heuristics are designed to be permissive, it may nevertheless misinterpret certain files with intentionally pathologic line link addresses, and unusual applications where the linked machine code is designed to actually modify the BASIC text may not disassemble correctly with this option. These are highly atypical situations, so this option will likely become the default in a future release.

--verbose

-v

Enables verbose output, which may or may not be useful in the same way that Schroedinger's Cat may or may not be dead.

--help

-?

-V

A quick summary of options.

The following options control how program code is scanned and determined to be a valid (or invalid) portion of a putative routine.

--datablock-detection option

-d option

This controls how the program automatically detects data blocks for addresses where no previous hints are specified. Only one method may be specified. The valid options are:

--no-external-labels

-e

--external-labels

-E

Controls whether labels should be generated for addresses outside of the program itself. The default is not to (i.e., leave the addresses absolute).

--address-tables option

-t option

Controls detection of address tables/dispatch tables. The following options are available:

--no-suspect-jsr

-j

--suspect-jsr

-J

These options indicate whether JSRs are always expected to return to the following instruction or not. This will affect how routines are parsed. For example, the Commodore 128 KERNAL has a routine called PRIMM that prints a null-terminated string directly following the JSR instruction, returning after the null byte. In this case, -J should be specified to alert the disassembler that this is possible. The default is to expect "normal" JSRs (i.e., -j).

--no-one-byte-routines

-o

--one-byte-routines

-O

These options permit or inhibit a single RTS, RTI or BRK instruction (or STP if enabled by the instruction set), or a conditional branch, from being automatically identified as a routine. The default is to inhibit this; specific cases may be selectively overridden with the -r option.

--no-stupid-jumps

-m

--stupid-jumps

-M

These options consider jumps or branches to the current address (such as JMP *, BCC *) to be invalid or valid code depending on which is specified. Note that BVC * is always accepted as the V flag can sometimes be toggled by an external hardware signal. The default is to consider them invalid otherwise.

--no-allow-brk

-w

--allow-brk

-W

These options control if BRK (or STP if enabled by the instruction set) should be treated as a valid exit from a routine, just like RTS or RTI. The default is not to do so.

--no-suspect-branches

-c

--suspect-branches

-C

These options are rarely needed, but account for the case where a program may intentionally obfuscate its code using branches with unusual destination addresses like LDA #2:BEQ *-1. In the default case, this would be considered to be invalid and not treated as a routine (-c); if -C is specified, it would be accepted as valid.

BUGS/TO-DO

65816 opcodes are not (yet) supported.

There are a few options Marko created that aren't hooked up to anything (and are not documented here on purpose). I might finish these later.

SEE ALSO

AUTHOR

WEBSITE