DISX4 - Full-Screeen Interactive Disassembler by Bruce Tomlin - bruce@xi6.com DISX4 is a multi-CPU disassembler for various vintage CPU architectures, mostly 8-bit. It will keep track of live changes to label references. What disx4 is intended for: - making a decent disassembly that can be saved as a .asm file that you can tweak later - not for making the prefect disassembly that needs no further touching Cool things that it doesn't do: - track RAM references - deal with split references (high half in one instruction, low half in another) - combine separate binary files (if your code comes from multiple ROMs, you will need to create a combined binary first) - handle multiple code segments with different address ranges === BULDING === This uses a standard makefile, so use the "make" command to build it. It should work in a standard Linux or MacOS environment with C++ developer tools installed. If this isn't sufficient information, then google for "how to use make". On some systems, if you have not previously used the compiler, "make" might have trouble finding it. Consult the documentation of your OS distribution for more information. If you plan on modifying the code, you might want to use "make depend" first. This generates a file named ".depend" with make dependencies for the .h files. That way, when you change a common .h file, all files that use it will be automatically rebuilt. The "make depend" command will probably complain about missing standard includes; you should ignore these warnings. I haven't tried to build this on Windows. It might work with either Cygwin or the Linux subsystem. At least one person has tried with Cygwin, but its system headers defined "addr_t" for some reason. === REFERENCES === Each line of disassembly can have one external reference, to either code or data. Note that some CPUs have 16-bit immediate instructions which can potentially be either an address or a number. This reference address will be used for creating labels, and for code tracing. Word or longword data lines will only allow a reference from the first word on the line. Label creation can be suppressed to certain addresses by using the Control-R command on the address. Address 0x0000 is specifically prevented from automatically generating a reference, because it is almost never used as such. === TRACING === If the label is a code reference, the T command can disassemble into referenced code after finishing the current block of code. This can quickly disasssemble large ranges of code, but it can also be misled by "tricks" like subroutines that pop the return address, read data from that address, and then put it back before returning. Note that the Z-80 series is particularly vulnerable to blank (0x20) characters causing bogus code references. The "rip-stop" functionality attempts to detect the most obvious situations. === COMMENTS === Comments can be attached to any code line by using the semicolon (';') command. This will bring up the current comment (if any) for editing. Press Return to save the line, press Escape to cancel changes, or delete the entire comment line and press Return to remove the comment. Comments are saved in a ".cmt" file, which consists of lines with the address in hexadecimal ASCII, a blank, the comment text, and a newline. They are saved in sorted order, but can be loaded in a non-sorted order. If all comments have been removed, the ".cmt" file is deleted. If a comment "falls off" because its address is now in the middle of a line, it is not immediately deleted, but can not be seen until the address starts a line again. However, when saving, such hidden labels will not be saved. NOTE: Comments are not affected by the Undo command! === UNDO === There is minimal undo support, in the form of one saved state. It is automacially saved by the shift-C and shift-T commands, and manually by the control-U key command. To use it, use the shift-U key command. But it's really not in a useful state right now. === COMMAND LINE === Usage: disx4 [options] [binfile] Options: -c cpu select default CPU type -c ? show list of supported CPU types -b xxxx base address -s xxxx size of binary data -o xxxx offset to start of data in file -a create binfile.asm and exit -l create binfile.lst and exit -! don't load binfile.ctl The addresses for -b, -s, and -o default to hexadecimal unless the selected CPU prefers octal. A prefix letter of "H" or "O" will force hexadecimal or octal. They are also scaled for wide architectures. If started up with no parameters, it will show an empty file, and the selected CPU type will be undefined. If "binfile.ctl" is loaded, its saved -b, -s, and -o parameters are used unless overridden. "-c cpu" will select the default and current CPU type in a new .ctl file. "-c ?" will show a list of supported CPU types. "-b xxxx" will specify the load address of the first byte "-s xxxx" will specify the maximum size of the code image to be loaded. "-o xxxx" will specify the offset in the file to the first byte of the code image. This allows skipping a header. "-!" will prevent automatic loading of "binfile.ctl". This will ignore any existing work in "binfile.ctl". "-a" and "-l" will generate a .asm and/or .lst file, then return to the command line. === SCREEN NAVIGATION KEYS === Up-arrow Move up one line Down-arrow Move down one line Home Move to first line End Move to last line Page Up Scroll down a page at a time, while staying on the same screen line Page Down Scroll up a page at a time, while staying on the same screen line Space bar Same as Page Down Control-B Move to top of screen, then move up a page at a time Control-D Move to bottom of screen, then move down a page at a time === SINGLE-KEY COMMANDS === 0 - 9 Digit keys let you specify a count of 0-99 for some commands. The escape key will clear the count. Some commands have a maximum count. x (no count) Disasssemble as raw data (the default state) a (max count 40) Disassemble as ASCII text b (max count 32) Disassemble as single bytes B (max count 32) Disassemble as decimal bytes (unsigned) h (max count 32) Disassemble as hex bytes with no formatting w (max count 20) Disassemble as 2-byte words shift-W (max count 20) Disassemble as reverse 2-byte words ctrl-W (max count 1) Disassemble as word address - 1 for 6502 jump tables \ (max count 16) Disassemble as 4-byte longwords | (shift-\) (max count 16) Disassemble as reverse 4-byte longwords d (max count 20) Disassemble as decimal words (unsigned) shift-D (max count 16) Disassemble as decimal longwords (signed) _ (underline) (max count 40) Disassemble as EBCDIC text I (max count 16) Disassemble as binary, 0x55 = 01010101B X (max count 16) Disassemble as visible binary, 0x55 = _X_X_X_X O (max count 16) Disassemble as visible binary, 0x55 = O_O_O_O_ See "xobits.h"/"xobits.s" for the "visible binary" equates. * Repeat previous data format command with same count ( and ) Expand or shrink the size of a line of data. shift-E Dissasemble current word as a position-independent offset in a table starting at the most recent label. This is commonly found on certain architectures such as 68k. If the target address has no label, a data label will be created. If the target is already disassembled as code, a code label will be created. ctrl-E The same as shift-E, but with a byte offset. c Disassemble current address as code. Ignored if already disassembled as current CPU, or if an illegal instruction. shift-C Disassemble as code until unconditional branch or illegal instruction. T Trace disassemble from current instruction, same rules as shift-C except that all code references are followed and disassembled as well. shift-T Trace disassemble until unconditional branch or illegal instruction. ctrl-T Disassemble as a word and trace from the referenced address. This is intended for jump tables. The referenced address will become a code label when appropriate. l Toggle a pre-instruction blank line before this code/data line. shift-L Toggle label type at this address between none, data, and code. Note that or if the current line is a "EQU $-n" line, this will only remove the label. control-L You must use "X" to break up the previous instruction, change the label state, then fix it with "c" afterward. ^ Toggle label type at address referenced by the current instruction. control-R Toggle the no-reference attribute for selected address, to prevent labels from being automatically created. This is useful for certain "magic number" addresses like 0x1000, and almost anything at address 0000-00FF. control-U Save current state for the next undo. shift-U Undo to last saved state. State is automatically saved before shift-C and shift-T commands. @ Go to the address referenced by the current instruction. < and > Go backward and forward along "@" or ":xxxx" usages. [ and ] Go backward and forward to the next non-EQU label. ! Search the entire code for any reference to the label at the current line, and delete the label if not found. The address of the first reference is reported. ~ (tilde) Re-center the selected line towards the middle of the screen. This is useful when at the very top or bottom of the screen and you need to see a few more lines. " Change the hint flags for the current address. There are two bits of hint flags that rotate through all four combinations. $ Change the default hint flags for newly disassembled instructions. === TEXT COMMANDS === : command Enter a text command / text Search forward - Searches are case insensitive and collapse all spaces together. Searches also ignore the hex address and data fields. With no text, the previously searched text is reused. ? text Search backward ; comment Edits a comment at the current address. (code/data lines only) While typing in the command line: Backspace or DEL Delete character before cursor, or exit input mode if line is empty. Carriage return Finish line and start executing it. Escape Abort current line and exit input mode. Left/Right Arrow Move the cursor left or right. Ctrl-U / Ctrl-X Erase from the cursor position to the beginning of the line. Ctrl-A or HOME Move cursor to start of line. Ctrl-E or END Move cursor to end of line. Command list: quit / q Exit the program. If the disassembly status has been changed, you must use ":q!" to override the changes, or save first with ":w". cpu Sets the current CPU type for disassembly. If defcpu has not yet been set, it will also be set to this CPU type. defcpu Sets the default CPU type that will be used for such things as number syntax (0FFH vs $FF) and default endian order for pseudo-ops like DW. list Create the file "binfile.lst" as a listing-style file of the whole image. asm Create the file "binfile.asm" as a source-style file of the whole image. save / w Save the current disassembly state into "binfile.ctl". load [!] [Bxxxx] [Sxxxx] [Oxxxx] Load the binary file. - If "file.ctl" exists, it will be used. - If the file name is a single "-" character, the current file will be reloaded. - If ! is used, the disassembly state in an existing "file.ctl" is completely ignored. - The B/S/O parameters will override what is stored in the .ctl file, but will not be saved into the .ctl file until an actual save/w command is done. There must not be a blank before the xxxx address. Changing Oxxxx will almost certainly cause all saved disassembly information to be incorrect. Warning: if the parameters result in a smaller data area, some disassembly state could be lost! Warning: this does not check if the current file has changes! label / l [name] If name is specified, a custom label is added for the current code address. If no name is specified, any custom label for the current address is removed. tabs [!] [n] [n] [n] [n] [n] Without any parameters, shows the current column widths. With parameters, sets column widths. "!" causes listing files to generate hard (0x09) tabs. When this is used, all column widths must be multiples of 8. The five columns are listing address, hex object code, label, opcode, and operands. The default values are: ! 8 16 8 8 16 xxxx A hexadecimal number goes to that address in the image. ":0" should always move to the start of the image, just like the Home key. The current address is added to the < / > stack before going to the new address.