REVAS V2 Z80/8080 DISASSEMBLER .USER'S MANUAL Copyright (c) 1978 A.E. HAWLEY LOS ANGELES, CALIF. *** REVAS *** REVERSE ASSEMBLER FOR Z80 OBJECT CODE PROGRAMS REVAS is an interactive reverse assembler (disassembler) designed to translate Z80 or 8080 machine language code into an assembly-like listing. It is written in Z80 code and can be used in any system that uses a Z80 central processor. It supports a punch and line printer as well as a CRT or TTY. With 22 commands, REVAS can help you: **Analyse undocumented programs **Document your machine language patches **Document your special I/O routines **Debug developmental programs **Modify and relocate your software Here are some of REVAS' features: **Assembly format listings **Output suitable for reassembly **Generates synthetic labels **Accepts your choice of real labels **Prints tables in data format **Displays alphanumeric equivalents of the machine code **Displays symbol table at any time **Cross reference listing shows where and how each symbol is used **Up to 3 output devices can be used **You are always in complete control of the disassembly process..stop and restart, return to monitor, or return to command mode at will The instruction mnemonics produced by REVAS are the same as those used by the Technical Design Labs' Z-80 Relocating Macro Assembler, and by Intel for the 8080. The remainder of this manual shows you how to make REVAS work for you. The 'A LITTLE INSIGHT' section introduces the general algorithm by which REVAS performs a disassembly. The use of tables is explained and related to the commands that use these tables. You will need to understand this subject in order to make most effective use of the REVAS capabilities. In particular, the two most frequently used commands are introduced in that section. In the 'REVAS COMMANDS' section, you will find a detailed description of the syntax and operation of each command. Until you become thoroughly familiar with the command set, you will have frequent use for this section. A careful reading of the formal command descriptions will reveal the freedom of format that is designed into these commands. A list of REVAS COMMANDS appears on the back cover for ready reference. The IMPLEMENTATION section contains the information you need to load REVAS into your system and properly interface to your I/O devices. The I/O jump vectors are explained there, as well as the register usage associated with I/O. Some of the addresses and their functions within REVAS are given to permit minor changes to be made in output format if you wish. Read the manual clear through before trying to operate REVAS, then refer to it frequently. Then go ahead and disassemble something! One caution! Think carefully before you use the 'A' command or the 'G' command. They can cause a system crash; the 'A' command by assigning tables in a program area, and the 'G' command by calling an address that is not the subroutine you intended. You have control of such situations because you are the one who specifies the address for these commands. It is my intent to furnish software and documentation that is as useful and free of errors as possible. The REVAS program has been in constant use during its own development(!) and for many months by several users before the first version was released. All known bugs have been exterminated. I am interested in improving wherever possible the quality of the program and its documentation. Thus, I will welcome and respond to comments and recommendations sent to the address below. (accolades are also welcome!) Please include a stamped self-addressed envelope if you wish a reply. Al Hawley HOW THE DISASSEMBLER WORKS Here is a brief description of REVAS: Program size-- 4k bytes Symbol table location--end of REVAS or as assigned Symbol table usage-- synthetic symbols 4 bytes/symbol assigned labels 6 bytes/label Symbol table length is initially zero, increasing as required to accomodate symbols and up to 682 labels. The object program to be disassembled must be in memory at it's normal location. When control is passed to REVAS, the prompt character(#) will appear and you may respond with one of the commands described in the next section. Let's start with the 'D' (display disassembly) command: REVAS will examine the byte located at the start address and analyse it as the first byte of an instruction by finding it in internal lookup tables. The operator mnemonic is obtained from the tables, as well as the number of bytes in the current instruction. The operand field contents, if any, are next determined by a combination of logical operations and table lookup. The operator and operand are stored in appropriate fields of the line buffer(LB). Next, the address of the instruction and the object code are stored in the LB as hex characters, and the object code is converted and placed in the comment field of the buffer for printout as ASCII data. The symbol tables are searched for a label assigned to the address just defined. If a label is found, it is inserted in the label field of the line buffer. If there is no label, then the tables are searched for a synthetic label to insert. If none exists, then the field is left blank. Labels can be right or left justified (see Patch Locations below). Now the contents of LB are printed on the output devices, the console is checked for any pending commands, and the process is repeated until terminated by reaching the last address or by a command from the console. The symbol tables comprise two tables: an index table and a label table. The index table is constructed during execution of the 'B' command. It contains the hex value of each 16 bit argument encountered in the address ranges that have been disassembled. It also contains flags which indicate for each entry the presence of an assigned label, the mode of the label (instruction mode or table mode), and a pointer to the location of the assigned label in the second (label)table. The 'K' command deletes entries from the index. The 'M' command changes the flag which indicates label mode. The 'F' command adds it's argument to the index table if it is not already there. The label table (assigned labels) is constructed during execution of the 'L','S', or 'T' commands. When one of these commands is given, the label specified in the command is added to the label table. The index table is then searched for the corresponding hex value (address of the label in the object program) and a pointer is entered in the index table that points to the label entry. If there is no corresponding entry in the index table, then one is created. Thus, these commands also act to build the index table. The 'S' command resets a flag to indicate that this label belongs to an instruction. The 'T' command sets the flag to indicate that this label belongs to a byte in a table of data. The 'L' command leaves the mode flag unchanged. A description of the flag and pointer words for the symbol tables is included in the implementation section. If you choose to store the tables (on tape or disc, for example) for future use, then you must be sure to also record these locations and restore them when you restore the tables. Mode, Mode Character, and Mode Control The character immediately following the 'D' or 'B' in those commands is the mode character. Two modes are possible: instruction mode and table mode. Table mode is specified if the mode character is a 'T'; any other specifies instruction mode. In the instruction mode, bytes from the object program are interpreted as Z-80 and 8080 instructions. In the table mode, bytes from the object program are interpreted as single-byte constants which are part of a table of data. There are two flags associated with mode control. The mode control flag is set (or reset) by the mode control character when the 'D' or 'B' command is issued to REVAS. The second flag, the mode bit, is part of the data stored for each entry in the index table. The mode bit is set or reset during execution of the 'B','M','S',and 'T' commands. The function of the 'M' command is to define the state of the mode bit for a particular (address) entry in the index table, creating a dummy entry if none is present when the command is given. Operation of the 'D' Command The 'D' command displays the disassembly on the selected output device(s), using the mode control flag to determine the format of the output. ***If an index table entry matching the current instruction or data byte address is encountered, then the mode bit from that table entry replaces the mode control flag; the output format (or mode) is controlled for this and subsequent bytes by this new mode control flag.*** Clearly, when the index table is empty (at the start of a session or after the 'I' command) all output format is specified by the mode control character. After any of the table building commands (B,L,M,S,T) have been executed, mode information from the index table entries will be used as appropriate. Operation of the 'B' Command The 'B' command functions much like the 'D' command. One difference is in the use of the mode flags. ***When, during disassembly, an index table entry is found which matches the current instruction or byte address, the mode bit of the entry is changed to correspond with that specified by the current mode control flag.*** Another difference is the table building function. When a 16 bit argument is found in the current operand field, it is replaced by a synthetic symbol formed by the concatenation of an 'S' or 'T' and the hex representation of the argument. The first letter will be an 'S' if there is no index table entry. It will be either 'S' or 'T' (depending on the state of the mode bit) when an entry already exists. If this is the first occurence of the argument value, then an entry is created in the index table whose mode bit specifies instruction mode ('S'). Later, when tables of data are being disassembled with the 'BT' command, those arguments in the index table that refer to labels in the object-program table area will have their mode bits changed to specify table ('T') mode. Incidentally, the index table itself can be listed using the 'DT' command. Note that if a table of data in the object program is disassembled using the 'B?' (? not a 'T') command, many spurious arguments will be generated and stored in the index table with curious effects during later listing. For example, the hex code sequence 20 20...(ASCII blanks) would be interpreted as a relative jump from the Z-80 instruction set, and the destination of the jump would be stored in the index as the current address plus 20H. similar situations exist for code sequences that look like LXI, SHLD, LDA, etc., from the 8080/Z-80 instruction sets. Because of the above considerations, it is usually best to analyse object code initially with the 'D' command, reserving the use of the 'B' command until the instruction and table areas have been located. Then the 'B' command can be used to build tables (and assign synthetic symbols), first to the instruction areas, and then to the tables of data.