isCopyright partof this without in or permissionofpublisher. requeststo priorwritten Altos, FirstStreet, Inc.,

Volltext

(1)REVAS. Release Z80/8080. 3. DISASSEMBLER. USER'S. MANUAL. by A.E.. Hawley. No part of is Copyright 1982, 1985 by A.E. Hawley. this by may be reproduced in any way or any means without Address permission of publisher. requests to prior written 101 Echelon, Los Altos, CA 94022. First Street, Inc.,. REVAS. document.

(2) TABLE CHAPTER CHAPTER. l,. OF. CONTENTS. 1-l. INTRODUCTION. ........................... 2-1 2, ........................ 2-2 ................... 2-6 ...................... 2-8 DEFINITIONS ............................... 2-9 2-9 ............................ 2-10 EXIT ........................... 2-lO .......................... .............. 2-11 ........................... 2-ll .......................... 2-11 ....................... 2-12 .............................. 2-12 2-13 ............................ ......... 2-13 ............................. 2-14 ................................ 2-15 .................................. REVAS3. OVERVIEW. ALGORITHM A DISASSEMBLY THE REVAS3 ALGORITHM. REVAS RE-ENTRY COMMAND EDITING GENERAL COMMAND DESCRIPTION RESERVED WORDS PARAMETER NAMES SYMBOLS AND LABELS MACRO NAMES ABBREVIATIONS & COMMAND PARSING INTERPRETATION MEMORY USAGE MNEMONICS SUMMARY INVOKING &. CHAPTER. 3,. GETTING. CHAPTER. 4,. DISASSEMBLY. FIELD. STARTED. WITH. ......................... 3-1. REVAS3. NAMES DESTINATION OF THE DISASSEMBLY CODE INTERPRETATION DISASSEMBLY OF XD.OBJ LABELS SYMBOL TABLES TARGET CODE ANALYSIS REAL SYMBOLS & LABELS REMOVING SYMBOLS & LABELS CONTROL ENTRIES CROSS REFERENCING SAVING THE SYMBOL TABLES COMMENTS. 4-1. 4-1 ............................... ............ 4-2 4-3 ....................... 4-3 ..................... 4-4 .................................... 4-J ............................. 4-8 ...................... 4-9 ..................... 4-lO ................. 4-lO .......................... ........................ 4-ll ................. 4-11 .................................. Page. O-1.

(3) CONTENTS. CHAPTER. 5, UTILITY INSTANT. COBMANDS. COPMANDS. 5-3 5-4 5-4 5-4 5-5 5-5 5-6 5-6 5-6 5-7 5-8 5-8. 6,. .................. 6-1. ..................... 6-2. CALC CALL ERASE (A MACRO) HELP MACRO MEMQRY/VIRTUAL QUIT SHOW. SET, TURN STATUS. CHAPTER. DISPLAY. CLASS. COMMANDS. DISPLAY, IDISPLAY, BDISPLAY, WDISPLAY. CHAPTER. PRINT,. IPRINT, BUILD, IBUILD,. BPRINT, BBUILD,. 7,. COMMANDS. DISASSEMBLY. WPRINT WBUILD. ............. .............. AT EQUALS FIND. 8,. 8-l. UNLOCK. DISK. TBLFILE LSTFILE WRITE SAVE CLOSE. FILE. ACCESS. COMMANDS. ............... ..................................... ................................... ................................... ................................... ..................................... ...................................... ...................................... PGMFILE. O-2. 7-l. 7-1 7-2 7-3 7-3 7-4 7-5. FILES. Page. 6-4 6-5. ........................................ .................................... KILL ...................................... ...................................... .............................. ...................................... ....................................... LOCK, MARK XREF. CHAPTER. 5-3. .......................... ...................................... ...................................... ........................... ...................................... ..................................... REINIT ............................ .................................... ...................................... ...................................... ................................. TITLE .................................... ...................................... 8-2 8-3 8-3 8-3 8-4 8-4 8-4.

(4) CONTENTS. CHAPTER. 9,. PARAMETER. DESCRIPTIONS. AMODE ARGRAD ASMFLAG BOTMAR CMT CONSOLE DMODE ECHO HLINES. ..................................... .................................... ................................... .................................... ....................................... ................................... ..................................... ...................................... LSTFILE .................................... ................................... ....................................... ...................................... ....................................... .................................... ..................................... ..................................... .................................... ................................... .................................... ..................................... .................................... ..................................... ........................................ MNE MODE ORG OUTRAD PAGER PAUSE PLINES PRINTER PS, PE PUNCH RPTRAD TABLE TOP. CHAPTER. 10,. CHANGING. 9-1 9-1. 9-l. 9-2 9-2 9-2 9-2 9-2 9-3 9-3 9-3 9-4 9-4 9-4 9-5 9-5 9-5 9-6 9-5 9-6 9-6 9-7 9-7. REVAS3. SETTING DEFAULT PARAMETERS FORBIDDEN OUTPUT CHARACTERS USER PATCH AREA INTERUPTS FINDING MNEMONIC TABLES BUFFER SIZES. ............... .............. .......................... ................................ .................. .............................. lO-1 lO-2 10-2 10-2 10-3 10-5. APPENDIXES FORMAL COMMAND SYNTAX COMMAND LIST PARAMETER LIST WORD RESERVED LIST. A-2 A-3 A-3. MEMORY MAP. B-1. Initial. ..................... .............................. ............................ ........................ ................................ Disassembly. Disassembly Disassembly A MACRO. of XD.OBJ ............. after Building Tables Labels ......... with. demonstration. ................... ...................... A-l. C-l. C-3 C-5 D-1. Page. O-3.

(5) CHAPTER. I. INTRODUCTION. named REVAS has been available For several years a disassembler produces the Z80 a systems whichuse central processor. for Design Labs: mnemonics originated by Technical of an extension 8080 mnemonic to was originally designed the Intel set. operate under a monitor (TDL'S ZAPPLE and functionally similar could disassemble ones) and was completely relocatable so that CPU'S code resident anywhere was memory space. in the modified to operate under CP/M, making elementary use of CP/M REVAS handling capabilities. is by now a mature and. It. It. it. file effectiveprogram good, but I felt written.. that is beingusedall that an even better. It. over the world. It is disassembler could be. Users of the original REVAS have asked for a disassembler that they also wanted one handles either TDL or ZILOG mnemonic sets; would disassemble large a too that for available memory program Incorporation of these and many other suggestions from space. users would have resulted in major surgery to the architecture of Such the original REVAS program. surgery usually incurs the risk The compromises, bugs, and inefficient code. of unacceptable best approach seemed be complete a rewrite, incorporating new to and data control structures along with the proven functional features of the old revas. REVAS3. and, some. is the result. The rest of this manual describes its use as seems necessary, the algorithms employed to implement of the main functions.. The manual. in three major sections: a tutorial is arranged GETTING STARTED, and DISASSEMBLY), a command section (OVERVIEW, and description section, an interface and configuration section (CHANGING REVAS). Ready reference is provided by the table of contents, The. Appendices,. an index,. and page headings.. introduces you to the language defined by tutorial section and to the concepts involved in using REVAS3. how chapter tells you to invoke and exit from REVAS3 and. REVAS3 commands The OVERVIEW REVAS3,. introduces you to the syntax editing of commands, and defines many of the terms used in the rest of the manual. GETTING STARTED introduces you to some of commands DISASSEMBLY and leads you through a simple disassembly. continues advanced examples which include the with more tutorial disassembly whose code a not of real program is available. source. theutility. a complete description In the commanddescriptionchapters, of and command each the function forms of is presented. The emphasis is on how commands work so that youcan make full and effective use of their EjK)wer and flexibility.. Page. l-1.

(6) INTRODUCTION. The. is. configuration chapter not necessary to change. CP/M. system. parameters,. is small, because make run in a standard to You may have preferences regarding screen format device characteristics, or the label and comment disassembly so, you can consult that listing. (CHANGING REVAS3. REVAS). list a. delimiters in. chapter.. it. it. If. The appendix contains a formal command syntax description and command words, reserved words, and parameter names. of lists There is a memory map which you will find useful in understanding the organization of REVAS and its table structure. Lastly, there are some sample disassemblies which are referenced in the. tutorial sections.. REVAS3. Assembly language written in assembly language. for all but trivial programs has been described as an To my wife Stephanie, I oweadebt of "exercise in masochism". gratitude for her love and forbearance during the long programming anddebugging period; I am surethat she lookson assembly language programming as an "exercise in sadism"!. was programming. What would encouragement. be like without friends? I life and intellectual support that. am. grateful. for the. Bob Doolittle, Tom extended development Krug andAl during the of REVAS3. Gallant, Many of the capabilities included in the program were selected as The many and advice. discussions a result of their observations about programming styles, techniques, and architecture eased the way' impfementREVAS3. Thanks, selecting task of 'the right to Tom, proofreading the improved the for that organization critical of this manual, made me stick to good english usage, and protected the reader from inaccuracies in the command descriptions. And thanks to Al Krug for the hours of frustration he spent running developmental versions with their inevitable bugs.. Excitement exists in my relationship System with REVAS3 becoming a z-Tool.. with Echelon. and. the Z-. to supply software and documentation that is as All known bugs have been of errors as Fc)s8ible. REVAS3. from am interested in improving the exterminated I Thus, quality of REVAS3 and its documentation wherever FK)ssible. and respond and recommendations welcome comments sent to I will below. address the to is my intent It useful and free. Al Hawley February 1985 Echelon Team Member 6032 Charlton Avenue 90056 CA Angeles, Los 2. Page. l-2.

(7) CHAPTER REVAS3. 2. OVERVIEW. with the you comfortable The main concepts involved disassembler. operation of the in disassembly are given here along with an introduction to some of the commands fromREVAS3's rich set. Someof theterms used You want to know what the in later chapters are defined here. disk for and how to execute are programs on your distribution REVAS3. As you manual, the concepts and through the progress commands are expanded on in increasing detail. This chapter forms the foundation of understanding that will helpyou keep before going on to your bearings in a sea of detail. Study examples. actual. The. of this chapter. purEK)se. REVAS3. is to. make. it. distribution disk contains a file named REVAS.COM, a number files with the extension "MNE", and a "READ.ME" file. The ".MNE" files are overlays that provide interactive selection of One of the sets (normally mnemonic sets during disassembly. Other files may also be TDL.MNE) is already present in REVAS. READ.ME present. All are described in the file, which can be listed using the Z-System and CP/M 'TYPE' command. Your. of. REVAS3 (CP/M. under the Z-System and CP/M operating systems. registered trademark of Digital Research, Inc.) Here are some of the features that you will find in REVAS3 as you become familiar with it: executes. is. a. * * * * * * * * * * * * * * * *. disassembly of programs oRg'd anywhere disassembly of memory or disk resident programs disassembly of programs too large to into memory automatic symbol generation automatic data type assignment assignmnet & control real labels include comments in the disassembly interactive, dynamic choice of mnemonic sets undocumented Z80 opcodes command easy-to-remember words & abbreviations command symbolic arguments. fit. multiple. commands. command. on. a. command. line. macros control over source, destination, and names of files a calculator that operates in your choice of radix a HELP command reviews commands, parameters for you. In order to. make. effective use of a program like REVAS, you must You must also know how to functions can perform. request those functions (the Command Set). The next few pages will introduce you to many of the basic functions and commands.. know what. it. Page. 2-l.

(8) A SIMPLE. DISASSEMBLY. ALGORITEM. Let's review just what is that we expect a disassembler to do. Youareprobably familiar with the'L' cornmandof z-Tool ZDM or DDT CP/M debugger; produces assembly a language list of which mnemonics. Other debuggers do about available the are We same. We expect more from a disassembler, though. expect a disassembler to display the address of each instruction, the code and and we expect to see labels the entire instruction; itself, We expect and symbols where they are appropriate. to see somePRN assemblers produce, most thing like the that even file including data ('DB' or '.BYTE') entries where the code does not represent instructions.. it it. does a disassembler produce such a result? The answer to that be question a disassembly algorithm. The algorithm on page will A good way 2-4 is a simplified version of that used by REVAS. to understand theprocess is to perform the disassembly manually, then relate the experience to the REVAS command set. The paragraphs which follow set up the logical environment within which the algorithm operates. How. there accessible. First,. be. it. must. be. some. for 'reading'. the Target Program.. object code to disassemble, on a byte-by-byte basis.. and We'll. if. it. must. call. (Use XD.OBJ you want a concrete example. Your debugger or monitor can produce a HEX listing for manual use. Also, see the example in the Appendix, page C-l.) accessed serially from the target program code and will be demand supplied on to the disassembler. Associated with each A logical byte is its memory address. register (the Program PC) address each Bytes. Counter, accessed.. contains the. or. of. byte as. it. is. requests exactly the number of bytes requiredto of disassembled code. The line of code is translated into appropriate mnemonics, register names, numbers, and The line is then sent to an output deviee for other symbols. The arguments of the display (with appropriate formatting). symbol table when appropriate. recorded in the instructionare The process is repeated for each line of disassembly to be. The algorithm produce a line. produced.. execute the algorithm manually, you will need three sheets of DISASSEMBLY sheet The LISTING and will is paper. The second contains a single line code. contain the disassembled 7 fields. working 'scratch-pad' the space for is divided into looks: Here's how the algorithm. To. titled. first. It. it. DISASSEMBLY ADDRESS:. Page. 2-2. CODE:. LABEL:. OPR:. LINE opAl:. OPA2:. COMMENT:.

(9) A SIMPLE. ALGORITHM. DISASSEMBLY. provides for an indefinitely is the third sheet format. It REVAS the number number of lines is limited of lines. (In large space.) by the amount of available memory Everything that the "remember" is stored in the Symbol algorithm is required to REVAS algorithm does not use all the Table. The simplified included here for later reference. fields; they are Here. SYMBOLTABLE SYMBOL:. VALUE:. Here are 0100 1A4C. : :. some. typical entries for the. BEGIN COUNTR. :. (. BEGIN. :. (. assigned. Here are the allowed. MODE-LOCK:. DATA-TYPE:. SYMBOL-TYPE:. &. first COUNTR. by. fields:. two. are symbols. ) ). a human. entries for the other fields:. :. :. :. :. :. :. SYNTHETIC REAL NONE. : :. :. INSTRUCTION BYTE(or DB) DW) WORD(or. : :. UNLOCKED LOCKED. : :. :. :. There is one further requirement. The disassembler algorithm have op-codes which contains must relevant access to a table of each information on instruction: number of bytes, the equivalent mnemonic, register(s) referenced, and location of byte or word data bytes. This table is derived from information supplied by be called the opthe manufacturer of your 8080/Z80 CPU. will code table. For manual disassembly, you must use the manufacturer's data, your assembler manual, or one of the several books available at computer suppliers.. It. Step 3 symbol.. letters. letter. of the algorithm calls for generation of Such a symbol is generated by concatenating. a. synthetic. one or two and the hex ASCII value field contents. For now, use the A typical 'S' (for Symbol). synthetic symbol is 'S12F8'.. Page. 2-3.

(10) A SIMPLE. DISASSEMBLY. ALGORITHM. Manual DisassemblyAlgorithm 1. Erase the value of the. contents of the disassembly line, then copy the into the disassembly line address field.. PC. 2. Search the symbol table for a value field which matches the address field of the disassembly line. none exists, skip to in the label field by continuing with step 4. Otherwise, step 3.. If. fill. 3. A symbol table entry has been found. assigned, transfer to the field; else and transfer the field. to. it. it. 4.. If. make. a a. symbol. has been synthetic symbol. Transfer the next byte of code from the target to the code. field. and increment. 5. Look up the byte there, go to step 4.. the. in. PC.. a. table of op codes.. If it. is not found. 6. An op code has been found. From data in the opcode table, determine the length of the instruction and finish transferring bytes from the target to the code field. The code field now contains the entire instruction. 7. Get enter. the mnemonic for the instruction from the opcode table; in the OPR field of the disassembly.. it. entries are not required, go to step 9. Else as required. one of the fields is a 16 bit fields If quantity which matches a value entry in the symbol table, then use the procedure of step to replace that quantity with a Real 8.. OPA field If the. fill. 3. or Synthetic. symbol.. 9. Place a comment field delimiter (';') in the comment field and then transfer the code bytes to the comment field, translating them into theirASCII equivalents. Ignore the high bit of each byte, and replace non-printing characters with ".". 10.. Copy. the. line to the. DISASSEMBLY. LISTING.. there are no 16 bit values in the operand fields, go to If step 12. Otherwise, a 16 bit argument is present inone of the OPA fields. Search the symbol table for a record containing that value. If none is found, then write the 16 bit argument in the next empty value of the symbol table 11.. list.. field. 12. end. Page. 2-4. of algorithm (Repeat from step. 1. for each line).

(11) THE. ALGORITHM. REVAS. doesn't take long to become disenchanted with a manual It disassembly; if you've tried it previously, you probably used a This algorithm is worthwhile to study and different procedure. understand because about. observations. brings it process.. the. to. light. a. number. of important. isn't Notice the unconventional use of the comment field; entered there are being used for comments at all! The characters really a different way of interpreting the code from the target rather than as instructions for the program: as ASCII characters Z80 CPU 8080 or After all, some code bytes represent to execute. in real programs. This alternate strings of ASCII thedata comment field helps you to spot those areas interpretation in THERE easily. But there's a more important observation to make.. it. ARE. A NUMBER. OF. POSSIBLE. WAYS. Disassembly We mnemonics! op codes into own Data Types, each with its. TO INTERPRET. is not just a matter of translating classify segments of code into The four modes MODE of interpretation.. can. consider. will. are. INSTRUCTION,. BYTE,. THE. CODE.. of interpretation. WORD,. and ASCII.. that the simple algorithm provision for B-bit or DB) and 16-bit (WORD or segments. That's not fatal for an assembler, but inconvenient for people! You. will. already. have noticed (BYTE. it. that. we. makes no DW) data. sure. is. see In step 3 of the algorithm, the symbol table is searchedto made a label belongs in the label field. A similar search is at step 8 in order to use any symbol found to replace a 16 bit A symbol table is necessary argument. to store such information for later use. More significantly, notice that new symbol table An argument whose information is only available for later'use. value is less than the current address is called a backward reference. Only on a subsequentpass through the code will new backward references result in a symbol being generated in the label field.. if. In step 11, all 16-bit arguments are entered in the symbol table. Is that really what we want done? Some 16-bit arguments are really being used as numbers rather than addresses; such numbers should not result in symbol generation. Although a field was reserved in the symbol table for a label, there is no provision for entering one there. The synthetic label of step 3 is not actually stored; is generated as needed from the value field of the table. Similarly, no use was made of the data-type and mode-lock fields in the symbol table.. it. Clearly,. better algorithm is needed for execution by REVAS. simple are at least two functions beingperformedbythe and BUILD the symbol tables. algorithm; DISPLAY the disassembly, The display function includes the actual disassembly according to mode INSTRUCTION an algorithm in steps 4 through 9, after which the completed line is sent to an output device represented by the DISASSEMBLY The Table Symbol BUILDing function occurs LISTING. in step 11. a. There. Page. 2_5.

(12) THE. REVAS. ALGORITHM. DISPLAY and BUILD are two of the principle commands in REVAS. The principle which solves the backward reference problem is simple: DISPLAY does not make symbol table entries, and BUILD does not produce disassembled output.. We'll get to the other problems by giving the REVAS algorithm. REVAS For this algorithm, which uses an output buffer is logically organized to contain one line of output with the same fields as illustrated for the "disassembly line", except that there are up to four OPA fields instead of two. The symbol table is a table in memory (initially empty) which is built and mainDATA-TYPE, and tained by REVAS with your help. The SYMBOL-TYPE, MODE-LOCK fields are used to store information about interpretation of the code which starts at the address value in the symbol record. In the algorithm, the contents of these fields are called "attributes". THE. REVAS. DISASSEMBLY. ALGORITHM. with spaces, then enter the Fill the line buffer l. program counter contents in the address field. 2. Search the symbol table the same as the PC.. If. for an entry whose value not found, goto step 5.. current. field is. 3. Table entry exists. Fetch attributes which specify: a) DATA-TYPE, i.e. which mode of interpretation is appropriate for the code which follows. Real or Synthetic Symbol or none at all b) SYMBOL-TYPE, 4.. the current MODE 3a. SYMBOL-TYPE Otherwise, enter a Real Change. If. field. 5. Using CODE,. 6.. If If. 7. end. the current. OPR,. DISPLAY,. BUILD,. COMMENT,. MODE. and. daÉa. type from step to agree with 'none', then go to step 5. is symbol the label synthetic in or. (of. OPA. in the line buffer.. interpretation), the fields of. fill. line buffer to output device(s) entries or changes to symbol tables.. send make. of algorithm. before, the algorithm is for the disassembly of only one line, Furthermore, and the starting address must be supplied. 'current MODE' is not necessarily defined too within the algorithm, so REVAS. These parameters must be supplied. within are variables by default and respecified Their values are initially determined MODE by commands. The is specified the I,B, or W prefixes in permitted with the DISPLAY, PRINT, and BUILDcoinmands; the address range for disassembly is determined from arguments supplied commands. with the. As. it. Page. 2-6.

(13) THE. REVAS. ALGORITHM. algorithm requires, in step 5, that there be several of code, and algorithms available for interpretation different the provided be a means algorithm. relevant for selection of that which is inturn The selection mechanism isthe MODEparameter by information controlled both by keyboard entry and dynamically BYTE, and WORD stored in the symbol table. Only the INSTRUCTION, modes are implemented, andtheASCII interpretation is left in the comment field. The INSTRUCTIONalgorithm is equivalentto steps 4 through 9 of the first algorithm. The. REVAS. need only supply a pseudo-op is simpler; and reformat the data from the code field for field for the number of the OPA fields. Output format restrictions limit somewhat WORD 4. The more algorithm is bytes per line to complex, because is dealing with words which must be replaced with symbols when appropriate.. The. BYTE. algorithm. theOPR. it. it. about the handling of 16 bit arguments which are not really Twoapproaches addresses? be are employed by interpretedas to REVAS REVAS checks handle problem. the the to see to First, as value is within the range of the target program's addresses, determined by the values of the PS (Program Start) and PE Automatic (Program End) parameters. entry in the symbol table is The second method involves skipped the value is out of range. command. KILL KILL the use of the removes entries from the symbol table. In subsequent disassemblies, a 16 bit quantity which has been KILLed will be shown as a hex value. How. if. if. and waited for you to assign a symbol of your symbol in the algorithm) each time encountered a new 16 bit argument during BUILD, you would be aggravated You need time to analyze beyond belief. the disassembled code in The order to assign meaningful symbols. solution is to let REVAS BUILD. ahead and during go use synthetic labels Later, after you have displayed the resulting disassembly, you can use the EQUALS command to insert Real symbols. In fact, you don't even have to make symbol a wait for BUILD to table entry; you can use the EQUALS command at any time to assign a symbol to any 16-bit quantity. with the EQUALS command, you have absolute control symbol table. over the contents of that 'symbol' field in the For examples see the disassemblies in Appendix C. REVAS stopped If (a choice 'Real'. it. During the BUILD FKjrtion of step 6, allusion is made to 'changes' to the symbol tables. Such changes are modification of the data type information stored there, and occur because of blind application of an algorithm to ambiguous code constructs. What One of the to control such situations. is needed is athemethod When symbol "mode-lock". a locked, attributes in table is changes to the data type attribute during execution prevents of The MARK command the BUILD function. controls the mode-lock.. it. In summary, BUILD, EQUALS, and KILL determine the main contents of the symbol tables; MARK gives you keyboard control over the effect of the DATA-TYPE in the tables. And DISPLAY gives you the main disassembly. output.. Page. 2-7.

(14) DEFINITIONS Metalanguage Throughout. this manual, and particularly in the command descripsections, certain symbols are used to avoid excessively tion wordy and confusing descriptions. These symbols are not a command the but serve to express alternatives and literal part of choices incommandconstruction. In the caseof CR and SP, the symbols express an entity which may be included in a command, but This collection of symbols is otherwise difficult to describe. is called a Metalanguage, and its definitions follow so that you The can refer to them as necessary while reading the manual. same set of metalanguage definitions will also be found inthe. Appendix.. !. =. {. ]. [. =. ...]. < (. =. >. =. ). =. CR SP ^. = = =. logical OR optionally present. of times syntactic unit establishes logical grouping ASCII CR (carriage return) ASCII SP (input from space bar) next character is ASCII control character present defines. any number. Hórd There are two definitions of"word" used in one is applicable depends on, and is usually. this. context.. a) In a command string, a word is numeric characters terminated by. defined as a. carriage return.. space,. manual.. Which. apparent from, the a. string of alphasemicolon, or. comma,. b) In a DATA context, a word is taken to mean 16 This is the data and is equivalent to two bytes. 8 assemblers most computers. in for bit. binary bits of definition used. is a word which is comEKjsed entirely of characters from the currently active radix. If the first character of a word entered from the keyboard is a digit (O to 9), then that word REVAS as a number. the character will be a interpreted by REVAS If first attempt to identify the is not digit, then will first reserved word, parameter name, or macro word as a command, label, before interpretation as a number. name. A. number. Arglj=nt An argument. position. below) is considered. Page. 2-8. in. a word conunand. is a. identified, arguments.. distinguished primarily by its lexical Once the command word (defined string. all other words in a command string are.

(15) EXIT. ENTRY,. ENTRY:. INVOKING. REVAS. is invoked in the same manner as other utilities under the by typing its name after the or CP/M operating system: the target code that manner, prompt. Called in this REVAS be assumed portion of your in some to disassembles is code cannot overlay the systems memory space. Naturally, target REVAS the system. operating or. REVAS. Z-System command. As. the. you might. calling. file. expect, an unambiguous from the system level: line. A> A>. or. revas revas. xd.obj xd. (REVAS. name. assumes. be. may. a. .COM. included. extension). In such cases, the code from the named file is disassembled however, The never overlays were in memory. file, The be as long may outside the bounds of REVAS. file These bytes! This is the virtual memory mode of access. as well as other extensions will be discussed in section now, the simplest invocation will suffice:. it. A> Once. loaded,. and. finally a. if. as memory as 64K. forms, 8. For. revas REVAS a. is waiting for Once. on. print a will(!q#). The. prompt a. command. line of input. sign-on message, prompt indicates from the console:. has been entered, linecommand. REVAS. a status report, that the program a command line.. begins. command. During execution, a few single-character commands are recognized. These are called instant commands. Their function is to permit stopping/restarting command execution mode. and aborting further execution by returning to command execution.. EXIT. FROM REYAS. The. next most important thing to know about a program like REVAS how There are to return gracefully to the operating system. is two ways to leave REVAS; The they are completely equivalent. as your intuition has already suggested, is to typea ^C from the keyboard. This method only works when the ^C is the character typed following REVAS' prompt; at other times ^C The second method is completely ignored. is to enter the command word QUIT.. first, first. RE-ENTRY. Provided that no other system transient commands have been executed, is Ejc)ssible to re-enter REVAS and pick up where you to the'^C' or'QUIT' exits from REVAS. off prior just save left a and '.COM' ('@.COM', with length for extension zero file REVAS, example) and execute whose code is location at still or tables. 100, will be restartedit.without reinitializing files. it. Page. 2-9.

(16) RE-ENTRY,. COMMAND. EDITING,. COMMAND FORMAT. COMMANDEDITING. For. instant all but console. commands, REVAS input; the command. uses. the operating system. buffered buffer will hold 70 characnormal The editing functions are active until the CR is ters. end entered at the of the command line. You can correct typing using the system editing functions. For editing details, errors operating manual. system refer to your There. exception. Control-C (^C), as the first character of the input line, results in a return to the operating system Since REVAS does not disturb the without a warm boot operation. operating system routines, the warm boot is not necessary.. is. one. WORDS REVAS. KNOWS. contains three kinds a built-in "dictionary" which contains command words, reserved words, and words: parameter of names. A A. words each Appendix in of the category is given in In defined words recognized they defined addition, user once are are as Macro Names or Labels.. REVAS. list. COMMANDFORMAT. is a string of words and/or numbers terminated by a Each command element (word or semicolon or carriage return. number) must be delimited by spaces or a comma. The rules for well formed commands are more flexible than just implied; more detailed descriptions are given in the command descriptions and in Appendix A (Formal Command Syntax, Page A-l).. A. command. Acommand contains exactly one command word, and as many other One number words or numbers as may be appropriate. (or other command The word) may precede the word. other words follow the A Macro Name command word. is treated as and may replace a command word once the Macro is defined. The 'other words' are A else number numeric argument; anything called arguments. is a The be called a symbolic which precedes a argument. argument can command RPT stands for word is referred to as the RPT argument. the word 'repeat'; the name reflects the fact that in many of the commands this argument specifies the number of times that disassembly of the next instruction is to be executed. Syntax in the Appendix, you you refer to the Formal Command made command command reference words; a note no is that to will is simply defined as a delimited sequence of arguments, or a Functionally, Syntactically, that correct. macro name. is word. either the or second argument must be a command. If. first. Arguments. not. instance, the. Page. 2-10. expected by the current command For are ignored. SAVEcommand requires noarguments; arguments. if.

(17) RESERVED. WORDS,. PARAMETERS,. SYMBOL. NAMES. If. word, they are ignored. thecommand word (SAVE), that one will also one argument precedes the command be ignored. There is a limit, however, to the number of arguword: no more than one. REVAS ments which may precede a command two words in a command string to be a expects one of the command word; neither word is, then the entire string is be displayed on your ignored and an irreverent reminder console.. are supplied following. if. first. will. RESERVED. WORDS. ON and OFF Reserved words are symbols whose value is predefined. Reserved words are much easier to are typical reserved words. numeric value because they make instead equivalent of their use mnemonic sense in the command. In fact, in any command that numeric a value as part of the command, a reexpects to find served word or user assigned label may be used instead of the Command and parameter names do not number. words, Macro Names, have associated and cannot be used that way. numeric values,. PARAMETERNAMES. names are used in only one context: as one of the of the SET command. In any other context they will be unrecognized unless they have been assigned a value as a label. (That might confuse you, but REVAS will distinguish between the two usages of the same name. You can assign command names as labels, too, without conflict.). Parameter arguments. SYMBOLS. AND LABELS. A string symbol is a string of six or less characters. (see <string> in the FORMAL COMMAND SYNTAX in Appendix A.) starts with an alphabetic character, and may contain all but a few of the A symbol has an equiprintable alphanumeric set of characters. valent 16 bit numeric value. When a symbol is used as a label, its value is a memory address (location).. A. A. label is. assembly. a. symbol. listing. which may appear in the label with proper termination.. field of. an. A Real There are two kinds of symbols: Real and Synthetic. symbol is one which you create by a keyboard entry; is stored A Synthetic symbol is created and used literally. by REVAS. of one or two letters and the Hex is created by concatenation ASCII value of the symbol. Only the hex part of a synthetic symbol will be recognized in a command string.. it. It. During executionof the BUILD command, REVAS identifies 16 bit quantities in the operand field of machine language instructions. Each such newly identifiedquantity is added to a table in free Page. 2-ll.

(18) MACRO NAMES;. ABBREVIATIONS. On subsequent DISPLAY memory above REVAS' disk buffer areas. of Symbol (Synthetic a disassembly, a Synthetic Label) is generated and displayed wherever its 16 bit value would have occurred. have created a real label with the EQUALS command, then that you be displayed instead the label will of synthetic label. Labels and Symbols are thus associated each with a specific numeric value; that value is usually an address.. If. MACRONAMES. is a command line which has beenassigned a MACRONAME using the MACROcommand. A macro name may contain from one to Once assigned, the macro name may six alphanumeric characters. be used as a command word in a command string, where results in execution of all the commands included in its definition.. A. macro. it. ABBREVIATIONS Command words may be abbreviated DISPLAY word may be shortened D, DIS, DISP, DISPL,. by truncation. For example, to any of the following:. DI,. The names. letters,. DISPLA. of parameters in the abbreviated. Reserved. similarlybut. will. not. be. the. (or TURN) command may be words maybeabbreviated to 2 recognized abbreviated to 1 letter. SET. if. Symbols, and Macro names may not be abbreviated. These are all assigned by the u3er and are treated literally by REVAS. you assign a macro name which is a possible abbreword, the macro of not be executed when viation a command in a command string; instead, the command will be you include executed. Labels, symbols. If. it. will. REVAS uses to recognize an abbreviation. parameter, is searched in the or reserved word order given in the HELP listing, and the first match found is the Thus, you must include enough letters of the one used by REVAS. word to avoid ambiguity.. Here. The. is the algorithm. command,. list. A contains lists of all thekey words thatREVASuses. listings, the smallest unambiguous abbreviation is shown The HELP command produces in parentheses after each word. similar lists on your console or printer. In the HELP listings, the key words are shown in mixed upper and lower case; the upper case pjrtion of each word is the shortest possible abbreviation.. Appendix In those. Page. 2-12.

(19) COFMAND. COMMAND. a) The command then. & INTERPRETATION. PARSING. is compared with entries in the abbreviated) (EK)ssibly a match is found, list. word, and the command argument is identified as the is excluded from any further searches.. first word. that. command. PARSING. <arg>. in. a. command. If. list. then a match is not found, b) the symbol table and the reserved word table are searched (in a match is found, then the argument has been that order). identified and the parsing is continued with the next argument. a match is not found, then the argument is assumed to be a number, and is converted to binary according to the current input radix; parsing is continued with the next argument.. If. If. If. it. the first argument was a command word, then all lexically If subsequent arguments are identified by the same procedure as in word, the second is (b). the argument was NOT a command If first searched. match is assumed to be; the command word is Ifis noterminated list found, then an error condition exists and parsing with an error message. If a match is found, then the command is identified, and subsequent arguments are identified as in (b). Parsing. is terminated. when. a. encountered. When. Macros searched as. semicolon or end-of-line. have been defined, the were appended to the command. list. if it. is. of Macro names is word. list.. MEMORYUSAGE. Appendix. B. contains. the organization addresses. given. a. memory. map. which. will. of the major parts of. on the. map. are symbolic. help you. REVAS.. to visualize of the. Many because they are. differ-. ent in the various versions and revisions of REVAS that may You will not need these follow the printing of this manual. When REVAS addresses to configure REVAS for your system. is invoked the issued by arguments, without of any one reports first the implicit STATUS display is theaddress of the first byte of free memory. That address is where the first byte of the symbol immediately tables will be stored; follows the 128 byte buffer symbol reserved for the table header (HDR, on the memory map). Later, after symbol table entries have been generated, the 'free memory' report is simply an indicator of the extent to which you have utilized your available memory space.. it. Page. 2-13.

(20) MEMORY. USAGE,. MNEMONICS. ERASE or KILL symbol table entries, the space so libeadded rated is of empty records that is maintained in toa the symbol table area. Subsequent new symbol table entries will possible; only when utilize space from the empty reeord new insufficient space exists in the empty record entries use memory at the 'free' location and thereby increase the size of the symbol tables. you use the STATUS command be able to observe the incremental changes in frequently you will symbol table size. There is no mechanism provided for reducing the size of the symbol tables short of complete annihilation (the REINIT command). When. you. list. list if. list will. If. MNEMONICS. superset of that used by the 8080 CPU, REVAS The mnemonic sets disassembles code intended for either. supported by REVAS 3 include the set introduced by TDL and the ZIIÁJG Several .MNE files will be found on your distribution set. TDL.MNE disk. is the overlay file which produces TDL mnemonics; When Z80.MNE produces ZILOG mnemonics. the TDL mnemonics are chosen, the pseudo-ops produced are consistent with the TDL Since. Z80. code. 3. is. a. When assembler (.BYTE, .WORD, and .END). ZILOG mnemonics are You can pseudo-ops are DB, DW, and END. chosen the corresponding interactively select among the mnemonic sets which are present on you the default disk drive using the SET MNE ... command. prefer, you can use your system debugger to change the default MNE set to one of the others. Just follow the directions in the REVAS) 10 (CHANGING READ.ME chapter of this manual. in or. If. file. Page. 2-14.

(21) SUMMARY. OVERVIEW. Z80 code that makes use of have occasion to disassemble Z80 during them may encounter opcodes. undocumented the Or, you 3 REVAS code detects segment that contains data. DISPLAY of a and displays these opcodes using the 5 new mnemonics listed opcodes were described by Daniel R. below. The undocumented Lunsford in Dr. Dobb's journal, Number 44, April 1980 (vol 5, of them in Issue 4), p 47. See also a more recent discussion Codes Revealed" by 1981, 58, "Secret Microcomputing, April page Edwin E. Freed. You. may. HX,. LX, SLLR. HY LY. = = =. one. high order bytes of IX and IY registers low order bytes of IX an IY registers shift left, set low bit to one (Freed calls RIJO). this. SUMYIARY. you have been introduced to the strategy that The terms 'command', performing a disassembly. in and have 'number', 'word', 'argument', 'symbol', 'label' words, been and words, The command concepts defined. of reserved Some have been about notes described. memory usage parameters have been presented, and the command parsing algorithm has been given. Finally, the unique opcodes produced by REVAS were introduced.. In. chapter, thisemploys. REVAS. I hope that this list of diverse subjects serves its intended establishing a common ground of comprehension so that purpose: the more detailed treatment in following chapters will be clear and unambiguous. In the next chapter, we will go through a simple set of operations which will give you a more intuitive You will have an opportunity feel for REVAS operation. to the practical aspect of some of the concepts presented experience So, turn on your computer and try out REVAS as you read so far. Chapter 3.. Page. 2-15.

(22) CHAPTER GETTING. 3. STARTED. trying to execute REVAS, make sure that you have a copy of the distribution disk (marked with the copyright notice, of course) as a working master, and that the distribution disk is safely archived. you are using Z-System or CP/M Version 2.2, If should be marked RIO (READ ONLY). all the files a oncopybothof disks Now transfer REVAS.COM onto a blank disk along with and system might need. operating system any your utilities you You may also wish to copy one or more of the .MNE files (You will be using PIP; be sure to include the lol switch, since these On the Master Disk is a file named contain binary code!). files examples XD.OBJ. If you wish to duplicate the that follow, you should also transfer that file to the Test Disk. your system If make uses more than one disk drive, sure that there is nothing irreplaceable on the alternate drives. These are the precautions that I always follow when first trying out new software, and REVAS does not eat disks, destroy apply to ANY program. files, crashes; after initial trial or cause system can be used like any other utility program under Z-System and CP/M. Before. it. REVAS. is executed. System or. CP/M.. A>revas. just like any other transient program under Zdrive A: is logged in, type. Assuming. ('A>' is the system prompt). a you should now see the copyright notice, your terminal HELP STATUS and a message to type display of for assistance, information. On the last line will be the REVAS prompt:. On. M# The. command second iInExjrtant you need to know is how to get out and back of to the operating system level; there are two Either type"quit" or""c" (control-c). ways. Theyare exactly equivalent in function, but "c only works when is the character following the prompt. Try one, reinvoke REVAS, try the other, reinvoke REVAS, and then try the HELP command: REVAS. it. first. M# QUIT A> REYAS 0 0. m. A>. ^C REVAS. 0 0. m help. Page. 3-1.

(23) GETTING. STARTED. three commands try theCount the number listing.. the main HELP command displayed before the lines You can change that number to anything. Now. suggested. continuation message. that you desire by preceding the the following sequence of commands: M# M# M# M#. 5 h c h p 8 h h. (sets (See?. by. of. screen. REVAS. "H". by the. paging to remembers!). required. 5. number.. Try. lines). p. to invoke REVAS and exit from it, and how to get functions. Did you notice that after each command word in can use listing is the shortest abbreviation that you idea word? Youhavealso introducedyourself of to the forthat that precedes the command word in REVAS commands. an argument For the HELP command, this argument updates the parameter HLINES which you saw in the parameter listing when you typed "h p".. You. the. now know HELP the HELP. Now. how. let's explore. the. STATUS. command.. Try the. following. command. sequence:. m status m s all m s hlines m s c This is the command that lets you check on the state of REVAS' internal parameters. You can, you wish, change the values assigned to these parameters by using the SET command. Try the. if. followingcommands:. m set echo on; set hlines stat argrad; h p. 5. Mi#. that you can issue multiple commands in a eommand line by separating them witha';'. Also notice the connection between 'argrad', the number following 'hlines' above, and the number of lines displayed by the 'H' command.. Notice. words SET and TURN to be completely equivalent; youcanuse the one which seems most natural in the To activate command string context. the command-echo feature above, you could have typed:. REVAS. considers. the. command. m turn echo on; set hlines. 5. Youhave seenthe effect of the'ECHO' parameter. Youshould be and in the echo feature off now. Do able to turn the command HLINES value that seems the to same line set right for your screen display.. it,. Page. 3-2.

(24) GETTING. STARTED. that you're getting the feel of the REVAS command format, We'll disassemble the start of disassembling. let's do some but REVAS bother don't now with trying to analyse the itself, (You for do code itself. that later, after you have feel free to can mastered set.) the instruction Try the following command. Now. sequence:. M# d. lOó. many lines were displayed? You can control lines displayed by including a REPEAT (abbreviated as in the following: in front of the command,. How. M#. 4 d. (the. lOó. M# d M# d 100 M# d M# 10 d M# d lOó. '4'. is the. RPT. the number of RPT). argument. argument). 110. Experiment with the commands (particularly the DISPLAY command we've covered so far until they become just demonstrated) Use different Look at the STATUS display arguments. familiar. after each command and see the relation to the displayed values You the RPT and the commands you have executed. will notice that because argument is not included in the parameter list. That's there's never any reason to SET independently; its value is always controlled by being specified as the argument which precommand. DISPLAY. it. cedes. class. a. you If number. O. (zero) for the RPT argument, then the specify a value of of lines displayed will be essentially infinite. How do That's where the 'instant commands' come you stop the process? commands in. Instant are recognized at any time except during entry of a command string: ^S!S!S Stops current display activity. Display resumes following any other keyboard input (except the instant commands). "E!e!E Aborts the current the next (if any) command.. command. execution. and continues. with. "X!X!X Aborts the entire command line and prompts for another command. the command line only contains one command, then 'E' and 'X' are equivalent.). (If. These commands editing procedures. Note:. (^C. use direct input, bypassing has no effect).. the system. Page. input. 3-3.

(25) GETTING. STARTED. issue the following command and use 'S' to stop the disassembly, and any key except E, S, or X to restart; use 'E' or 'X' to get back to the REVAS command level. Now. M# M#. O. d. 100 114 (here's. d. where. instant. commands. are needed). This use of the RPT argument is good for scanning a long section of code rapidly. the console can cause trouble, however, because you parameter is OFF (as is during the BUILD command) good a idea can't see what is happening. re-establish to It's the RPT argument at some finite value (such as a screen of lines) by issuing another display command like:. It. if. it. full. m. 15. d. Are you ready now Try the following: M# pgm. for. If the filename 'COM', and then. let's try. V#. it. again:. pgm. real. file?. OK,. let's try the. XD.OBJ. file.. xd. CXJPS!. be. a. extension. is not given, REVAS expects to ok, then, can't find xd.com on the disk!. it. xd.obj. By the way, did you notice the change in prompt character? The 'V' means that REVAS is now in virtual memory mode; reads (as required by the dissegments of code from the disk assembly) instead of from absolute memory locations. you how done disassemble REVAS, you the disk among find handling routines.. it. file. file. If. it's. will. back to business. Use the STATUS command to see the values PS(prograni of start) and PE(pgm end) in the line starting with V#. How do they relate tothe lengthof the XD.OBjondisk? (Hint: subtract PE from PS; that's HEX arithmetic, and you can do with the CALC command) Also note that STATUS informs youof the names currently active. OK,. file. it file. the parameter setting command (T or SE) to turn on the then give the STATUS command again. If your system doesn't have a list device (or you don't want printed output) turn the Printer back off. Use the STATUS command to be sure you Now. use PRINTER;. if. were successful.. Page. 3-4.

(26) STARTED. GETTING. Go. ahead and use. with:. V#. d. the DISPLAY command to scan the code.. (you. did set the. RPT. argument,. Start. didn't you?). That's because Notice that the display started at address lOClH. the default starting address was automatically set to the value does that in Memory mode, too. of PS.. It. you disassemble beyond address 50OH, you will notice a disk Don't panic! REVAS just read in the next code segment. access. Now stop the disassembly and try: necessary), (instant command. As. if. V#. d. 120. (or. some. other address less than 4ffH). There was another disk access, appropriate code segment.. as. REVAS. automatically read in the. code outside the range of addresses defined try disassembling Why does make no sense to by PS and PE. What happens? disassemble outside the PS-PE range? (Hint: where does the next code segment come from?) Now. it. So better than using the disassembly far, it's just a feature of your debugger program. Right? Don't give up yet; read commands. the section of this manual on the DISPLAY Experiment with BDisplay and WDisplay to see what they do. After using each form, display a few lines with the D command (no prefix). Now command, then try Display again. Experiment try the IDisplaycomfortable feel with the commands discussed up to this until youDon't be tempted point. to try other commands until you are familiar with these.. little. At this point, you have become acquainted with the basic commands command You can invoke REVAS and format that REVAS understands. You can perform and return to the operating rudimentary system. disassemblies of memory resident code and of code from a disk You have been introduced to the parameters that control You have used two of the many of the functions in REVAS. Reserved Words (ON and OFF) to supply values (Offh and DO) for the SET command. And, for those (rare?) times when you need command HELP you can use the to refresh your memory.. file.. it,. .. Page. 3-5.

(27) GETTING. STARTED. you are ready to explore the other commands and features. While you are exploring, make frequent use of the Status command; the parameters that displays tell you what is going on. Start MARK, commands and use Display and EQUALS KILL, with the Mark or Equals has been Once frequently to see their effects. used, a symbol table will have been started, and you can save Read about each command and understand with the SAVE command. The next chapter, DISASSEMBLY, before going to the next. will be command. BUILD You already help the have met of particular with commands. Learn the rest at your with some of the As you get acquainted with REVAS, find that leisure. you "tearing apart" some mysterious code (or entire programs) produces disassemblies that are more complete andunderstandable than with anything you have seen before!. Now. it. it it. Utility. Page. 3-6. will.

(28) FIELD. CHAPTER. DIsAssmBLY. NAMES;. DESTINATIONS. 4. WITH. REVAS. FIELDNAMES STARTED', REVAS disassembles code to As we have seen in 'GETTING One produce a listing which contains line. instruction per one below. shown such disassembled instruction the is is instruction from the XD.OBJ file. The line is composed of seven fields; the name of each field appears just above its contents.. first. It. ADDR. 0100. CODE 21 0000. LABEL. OPR. LXI. OPA1,OPA2 H,0OOOH. CMT. ;!... in hexadecimal of the memory field contains the address code shown in the CODE field. location of the first byte of the The LABEL field is blank because no label has been assigned to The code in the CODE has the instruction at this address. field been translated into the instruction which appears in the next three fields: the Operator (OPR) mnemonic, and the two operands in the OPAl andOPA2 fields. For many instructions one or both of the operand fields will be blank. The comment (CMT) field contains a different kind of translation: the ASCII equivalent of the hex values in the code field. For this purpose, the high order bit of each byte is ignored and non-printing characters are The. ADDR. replaced with periods('.').. These field name assignments correspond to the terminology used The the assemblers. for source text for listing produced by many and an assembler includes only the label, operator, operand, REVAS comment fields. In order to use the output of for reassembly, the address and code fields must be suppressed; the comment field is of no use to the assembler, so can be suppressed also.. it. DESTINATION. OF THE. DISASSEMBLY. The disassembly can be sent to the console, the printer, the punch, by turning the appropriate switch paraor a disk meter(s) on. In all cases, suppression of the address, code, and comment fields is controlled by the ASMFLAG switch parameter; when ASMFLAG is turned ON, the fields are suppressed and will not only the CMT switch is turned appear in the output. If, instead, OFF bedisplayedor sent to thenall but the comment each of which is on a User supplied comments, the .LST by are never suppressed. the ECHO switch has line been turned ON then each command will be repeated on the output just before is executed.. file. file. itself,. fieldwill. If. it. Page. 4-l.

(29) CODE. INTERPRETATION. Disassembly. .LST file by turning ON the LSTFILE isthesent to the turned OFF, switch. switch is transmission to the file but the file is not closed. Subsequent output can be cea3es, appended to the by turning the switch back on. The file file REVAS. You may also close be closed when from the exit you will commands the CIX)SE command. The with manipulation are file file more fully explained in chapter 8. See also the LSTFILE parachapter 9. When. meter. description in. Another way to send the WRITE command.. a disassembly The WRITE command. to the. .LST. file. open8 the. is by. file,. means. sends. of the. disassembly to the file with the ASMFLAG ON, closes the file, then turns the ASMFLAGOFF. Any previous contents of the file are overwritten and lost. CODE. The remark. INTERPRETATION. above. that the comment field is a different transcode the introduees an important concept in lation disassembly. Any given segment of code in memory could have been generated by a number of different types of source statements in the assembler source, and the code itself carries no information about how was generated. The threebytes ofcode ataddress lOó could have been generated exactly as shown by an assembler using Intel mnemonics, but exactly the same code would have been generated assembler using Zilog an entirely different Likewise, could rnnemonies were used. to emphasize the FKjint, have been the result of a .BYTE or .WORD (equivalent to DB and pseudo-ops in many assemblers) data area in which the contents of the memory locations are defined at assembly time, or of an assembler pseudo-op that simply sets aside memory locations without initialization. In the latter case, any random bytes present would have been included. The point is that that location at there are a number of FKjssible ways to translate the raw code: to instructions or to one of several kinds of data. REVAS must "know" at all times which translation algorithm to use in order to supply the disassembly that makes the most sense to you. REVAS can translate to straight ASCII (in the comment field), to Instructions, to byte oriented data, and to word oriented data. of. it. if. it. DW. to use the Instruction translamode algorithm new until tion is requestedorbecomesapprocommands similarly request The BDISPLAY and WDISPLAY priate. The DISPLAY disassembly to byte and word type data modes. command requests disassembly in the most recently specified mode. The. Page. IDISPLAY. 4-2. command. tells a. REVAS.

(30) XD.OBJ. DISASSEMBLY. initial C.. An Appendix. invoking. disassembly of. It. was. produced. a. PGM XD.OBJ. ;. 55. LABELS. XD.OBJ. portion of following. by the. REVAS): M#. OF. DISASSEMBLY;. XD.OBJ command. is shown in line (after. PRINT. Notice that the "most recently specified" mode must have been That's because until otherwise requested, the Instruction. mode Notice also that the disassembly is "Instruction". default blank broken by lines inserted after each uncondiis up listing branch instruction. That's because such an instruction tional breaks the flow of program instructions; following instructions not related to those preceding the hard certainly are almost The blank branch. line helps you to visualize program structure. Clearly, the CPU stack at the first five instructions. 06BBH in the being saved pointer is at location first three, then a new stack is being designated in the fourth instruction. 0135H. jump to location Finally, there is an unconditional Scanning down the listing, the code Nothing strange here! on "looks" sensible until we come to address 0160. Why would anyone load the accumulator twice from the same location? And what sense does make tohave 8 JRNZ instructions in a row? A lookat the comment field doesn't help; all the bytes are non-printing. But Da 0D and code is a carriage return inASCII lookat the itself; And jRNZ's the are actually a string of ASCII is a line-feed. Look. it. This must be a data area! But where does end? You can spaces. XD.OBJ probably out by listing figure yourself until you find code that makes sense, but let's instead consider a much more powerful tool that REVAS has for you.. it. it. LABELS. of the 16 bit operands encountered so far is potentially a pointer to a segment of code; in other words, they could be used Assemblers as labels. don't like labels that start with a number, and they generally accept a label that is six characters long. If REVAS could put one or two letters in front of the 16 bit number (in hex) and supplya suitable label delimiter, that as a label in the label field at the approentity could beused REVAS wouldalsohaveto'remember' to consistpriate address. ently use such a synthetic label in other operand fields where appropriate. If such assignments were made indiscriminately during the DISPLAY command, a whole bunch of incorrect labels would have been generated at the string of JRNZ commands at We need a special command location 0163 to 0171, though. so the That command command, BUILD caribe controlled. the is process AND WBUILD) whose other forms (IBUILD, BBUILD, are analogous to command. DISPLAY the similar forms of the Each. Page. 4-3.

(31) SYMBOL. TABLES. SYMBOLTABLES how. Here's. through. it. 015D. command:. works.. looks. We. have decided. like valid. that all the code from 0100 instructions. Usethe following. V#ibuild lOó 15d the All assembly. code. in the range specified is disassembled. The disany output device; instead, a slash is displayed on the console for each 60 lines of disassembly processed (see the BUILD command as a 'working' indication. description.) Each 16 bit argument found in an operand field is examined to see is within the range of the program. If then stored as an entry inthe Symbol Table inmemory is is, above REVAS. In the same record, mode information is stored which identifies the nature of the instruction which referenced this value. Certain instructions characteristically reference data areas; others always reference Also, this an instruction. table entry contains a marker which indicates that a symbol is to. is not sent to. it. if it. it. be generated.. The 16 bitvalue mentionedabove is the valueassociated with a The marker which indicates that a symbol is symbol or label. to be generated also indicates whether the symbol is to be synthetic have designated with the EQUALS command. is a one which you or When synthetic symbol is required during a disassembly, is generated from the 16 bit value. The synthetic label is you have not stored here; only its 16 bit value is stored. assigned a symbolic name, then that name is the symbol which will be used by REVAS.. it. If. itself. table in which the address record is stored is a binary tree The key on which shares high memory with other binary trees. which the tree is organized is the 16 bit argument referenced above. Another tree contains user assigned labels (discussed below); the records in these two trees are cross-referenced by appropriatepointers. Athirdtree store3command macros when they are defined by the user. There is no connection between two. this tree and the The. first. referred to as 'Symbol Tables' in collection of tables is where the context permits, the word this manual. In some cases 'Tables' is used and should cause no confusion with other tables in REVAS such as command or parameter lists. The. After the BUILD command has been executed, we can look at the results withthe DISPLAY command. Do it, displaying a screenat a time, starting with address 100 and stopping at address full 18F. The disassembly you get will be similar to the second Notice that the zero argument at lOó listing in the appendix. symbol, a but remains as a hex constant. assigned as was not because outside the bounds of the target code That's is (XD.OBJ). Likewise, the argument of the instruction at O1lC has The CALL also been treated as a constant for the same reason. 0005H instruction at 0137 is another instance.. it. Page. 4-4.

(32) TABLES. SYMBOL. load and store type instructions which have numeric operands the are now displayed with synthetic symbols starting with hex). and ending with thevalue of the argument (in letters'UT' The arguments of branch type instructions (as at O1OAand 0123). The. start with the letter 'S'. The 'S' stands for 'symbol', These letters all have meanings. and implies that the code at the address represented by the The stands 'T' symbol is an instruction. for 'table', and letter code associated a implies that as label its is to be interpreted BYTES The 'W' implies a table of data of data. as letter WORDS. organized as. field contains an 'S', the switch to the instruction mode of disassembly; a synthetic label contains a'T', the switch is tobyte mode disassembly. For a'W', the switch is to. When. DISPLAY. a. synthetic procedure. label in the label. automatically will when. WORD mode.. letter 'U' stands for 'uncommitted', 'uncertain',REYASor 'unlocked' (take your choice!). A label is 'unlocked' and'W'. THEABSENCEOFA interchange'T','S', can automatically. The. if. 'U' IN A SYNTHETIC LABEL(SYMBOL) MEANS THAT REVAS CAN NO LONGER MODIFY THE MODE INFORMATION ALGORITHMICALLY; ANY CHANGE IN THE MODE MUST BE BY USER REQUEST. MARK You can command) do which data type the imply; and you may so When mind. mode a you change you MARK command, mode can be changed The and unlocked by the UNLOCK command. by another MARK command, commands MARK, LOCK, UNLOCK and the give absolute. label. if. again using the. disassembly. your that. specify (with the. will. specify is locked. It you. data. control of. process.. the start of a line of disassembly, the Program Counter (PC) The contains the address of the first byte of code. first search the disassembly of algorithm is the to responsibility Tables for an entry whose value equals that of the PC. If an entry is found, then the disassembly (display) mode is set to correspond to that recorded in the tables. If a synthetic label is called for, is generated and placed in the label field; a user assigned label is present, then is used instead of the synthetic label.. At. it. if. it. let's get back to that suspected data area at address 0160 in the disassembly. There are twocourses of action possible. a) We could use the MARK command to designate the first byte (at 160H) as BYTE. Or, b) we could use the BUILD command starting where we think instruction code starts after the data segment. Now. Page. 4-5.

(33) SYMBOL. TABLES. the DISPLAY command, we observe that there is now a synat 018C, and that thetic label is an instruction. So, letW some convert use the BUILD command more arguments into symbol to table entries; to keep things under control we'll just build over a small range of code that looks like valid instructions, then display the results: Using. it. V#. b 18c. l9b. ;. di8 100 19b. results so far are shown in the second listing in Appendix C. has detected (at addr 18C) a data reference to address 160, and assigned a synthetic label to the code at that address. The UTO160. The 'U' label is tells us that the label is unlocked so that subsequent references could change the type from'T' to 'S' or 'W'. The subsequent code is now listed in byte format, in accord with the 'T' in the label. The. REVAS. Although the data area at 160 appears to be quite valid {it's a buffer with some ASCII already present, and terminated with the '$' that the 'print buffer' function of CP/M uses), let's use Try the to experiment with the other forms of the BUILD command. following:. it. V#. ib 160 160;. change. the label to USO160 and, inaccord with the 'S', disassemble all the code up to the next label as been from instructions. If the range of the 'build' above hadwould 160 to 18b, then all of the 'jrnz' instructions have Now try: generated locked synthetic labels.. The. effect is to. 15d 18c. d. V#. wb. 160. 15d. 161; d. This. changes the label label is now displayed. to. 18c. UWOl60,. and. all. the code up to the next OOPS! The last line in. format. the block of data is .BYTE format, andthere is justone byteof code there. What happened? The word format starts at address 160 through 018B; and continues Since that's an odd number of bytes. each word in the data area requires 2 bytes, the one byte left at the end cannot be used to construct a word, and REVAS automatically switches to byte format display for that byte. in'WORD'. in specifying the range, because the is wise to be careful (by default) assign all words within its WBUILD function the of type 'US' (unlocked instruction). range as symbols address had been within the program word in the limits, that would have 2 happened here. Also observe that the address bytes rather than only one as in the range included doesn't make sense to That's because previous example. (2 word! byte byte) a were process one as. It. will list. first. If. it. if it. Now. return to the original byte format V#. Page. 4-6. bb 160 160;. d. 15d 18c. display with:.

(34) TARGET. CODE ANALYSIS. There is a general principal to be observed about the conduct of from these examples. a disassembly you simply use the BUILD command inthe instruction mode to build tables (and thus assign labels) over a range of addresses that contain tables be a bunch of false labels. Even more of data, the result command WBUILD used the would be generated them indisyou of The disassembly the touse best criminately. way to starta is DISPLAY commands only to identify ranges of code that are Use the BUILD command to extract the argument instructions. from the instruction areas as thoroughly as Fc)ssible. information After doing that, most of thedata areas will have been identified (by synthetic labels starting with 'UT').. If initially. will. if. mode after one of IBUILD is usually used to ensure instruction WBUILD the other modes has been used. is used principally after you have decided that the code segment of interest really is (typicajÁLy And BBUILD might be used addresses a jump table). when you want to recover from one of the other forms. TARGET. CODE. ANALYSIS. object of complete disassembly is to gain a thorough understanding of the function, logic flow, and data organization of Perhaps youwish to generate a source the target program. file and subsequent reassembly. Or perhaps you wish for modification to learn the techniques used, so you can add them to your own arsenal of programming expertise. For such purposes both heurisand analytic approaches are required; REVAS supplies the tic and tools for analysis you supply the heuristic intelligence. You a complete every clue you can get to piece together will use the analysis of program.. The. willandcontinue run. We XD.COM we. know about. it, if it now:. directory operating system. XD. is. a. to refer to XD.OBJ for examples. you haven't already done so. program that operates listing invoked. it. Rename to Here is what under. the. CP/M. is with optional drive designaand observe argument, that you is not necessary to tor include the usual colon after the drive name. The directory display produced is sorted and formatted on the console, and includes the length of each and finally the number of kiloSuch a statement of program bytes of space on the disk. function furnishes you with clues about the kinds of routines that must be present in the program.. It. left. an. will. it. file. During the initial disassembly and table building processes, additional clues became evident. The code has been organized into segments, each of which can be analysed to determine its The data areas have been identified, and those that function. contain ASCII give a further clue as to function. You will have already started the analysis by observing at address 0104 that thecaller's (CP/M) stackpointer is being stored at a location with the symbolic label UT06BBand that a local stack is estabAs you decipher the lished starting at symbolic address UT06F9.. Page. 4-7.

(35) REAL. SYMBOLS. intent of the code, youcan use the AT command to insert short comments; thenyouwon'thavetodecipher itagain! Be careful, though; the comments do take up memory space! Youco'uldeasily over-do and use up available space.. it. REAL. SYMBOLS. & LABELS. know without even trying that we will not be able to remember The more than a half-dozen or so such labels and what they mean. symbols such mnemonic be a rename to with that trick is meaningful. So, wecanuse the EQUALS commandto assign such a mnemonic: We. will. V#. 6bb eqOLDSP;. 6f9 eq. STACK;. d 100. This command string assigns two labels (OLDSP and STACK), then displays a screenfull of disassembled code starting at 0100. Notice that only the address portion of the synthetic label is used, and that is not necessary to include the leading zero. REVAS a synthetic also recognize label (such as s6bb or will UT6f9) as one of its command arguments; however, only the address portion is actually stored in the symbol table or used for a search in the tables. You should avoid assigning REAL symbols that look like synthetic ones in order to avoid confusion.. it. you change your mind tO'NEWSP'. work:. the name 'STACK' and would Eitherof the following commands about. Suppose. liketochange. will. V# V#. or. it. 6f9 equal STACK. NEWSP e NEWSP. Notice, in the second example, the symbolic reference to the EXAMPLE OF REVAS' THIS IS THE FIRST OBVIOUS value(06f9H). REFERENCES. a lot easier for us ABILITY TO USE SYMBOLIC It's humans subroutine by than by its numeric reference a name to its address!. the above examples have used several purposes, command. REVAS doesn't 'equals' the abbreviations of care which The HELP of the you use, as long as no ambiguity results. commands shows the minimum unambiguous abbreviation of each command. Also note that the labels assigned in the examples are That's only for emphasis. you wish to use lower upper case. REVAS, however, console do converts input to upper so. case, all assign the labels that in listings. way you case, so will apFear For. illustrative. list. If. LABELS. WHICH. YOU. ASSIGN. WITH. THE. If. EQUALS. RECOGNIZEDLITERALLY. you try label, will not be recognized.. it. Incidentally,. REVAS. won't. COMMAND. ARE. to abbreviate. you let you. as3ign. a. a. RECORDED. AND. user assigned symbol which. will be reminded. Mode information stored in the symbol table is not altered by user label assignment. Inpartieular, the mode lockbit is unduplicates an existing one.. Page. 4-8. If. try it,. you.