V o y a g e r R e f e r e n c e M a n u a l Derek S. Nickel V1.0-6 30 January 1991 ================================================================ Overview ================================================================ Voyager is a tool to interactively disassemble the memory (RAM or ROM) in the HP 48SX. In this context, the term disassemble is used to refer to disassembly of both machine code (aka unassemble) and threaded instructions (aka unthread). Voyager consists of several images: VOYAGER.EXE Main program DMPTOMEM.EXE Converts ROM dump to Voyager MEM file BINTOMEM.EXE Converts binary file to Voyager MEM file The calculator's address space in Voyager is divided into "ports" (similar to the ports in the calculator itself). The ports are: Port 0: 00000-7FFFF Port 1: 80000-BFFFF Port 2: C0000-FFFFF A 'module' can be loaded into one of Voyager's ports with the LOAD command. The HP48 module is automatically LOADed into port 0 when you invoke Voyager. Each module consists of these files: module.MEM Voyager MEM file (memory dump) module.CA Address Comments module.CC Code Comments module.CAX Index for the CA file module.CCX Index for the CC file The MEM file is required; the other files will be created, if absent. [NOTE! See MEM.DOC in HORN2 before using Voyager. -jkh-] The MEM file is an ASCII listing of the nibbles in the module to unthread or unassemble. It can is produced by downloading via the Memory Scanner or KERMIT transfer and then filtered with either the DMPTOMEM or BINTOMEM programs. Two comment files are used by Voyager. Both have the same format. Each line consists of the 5 nibble address being described, followed by a space and a one-line comment describing the address. Lines beginning with a '-' are considered deleted. The CA file is the address comment file. It provides comments explaining the purpose of address references. For example, the DUP routine is at 1FB87. Unthreading is done with the UNTHREAD or UT commands. Unthreading 1FB87 yields: Voyager> UT 1FB87 1FB87: ; *** DUP (XLIB 2 269) *** 1FB87: 02D9D ! Program 1FB8C: 18AA5 ; Save last RPL token and verify DEPTH >= 1 1FB91: 03188 ; Internal DUP 1FB96: 0312B ! End Marker Each comment following the threaded routine address is stored in the CA file. Note that comments that start with an exclamation point are generated by Voyager; Voyager knows about object prologs and can format in-line objects (including Programs) without assistance. Comments that start with a semicolon are from the CA file. Address comments are created and deleted with the CA and CAD commands. Another example: the RPL routine at 14039 is a very deep internal routine to the code for ERRN. It pushes the Last Error Number as a System Binary (also called "short" or "address" by some people). Voyager> UT 14039 14039: ; *** Push Last Err# as System Binary *** 14039: 1403E ! Machine Code at 1403E 1403E: 34FF607 LCHEX 706FF ; Save Last Err# 14045: 8D3B411 GOVLNG 114B3 ; Push @C.A as new System Binary 114B3: ; *** Push @C.A as new System Binary *** 114B3: DA A=C A 114B5: 8FB9760 GOSBVL 0679B ; Save D,B,D1,D0 (uses C) 114BC: 130 D0=A 114BF: 142 A=DAT0 A 114C2: 8DC7530 GOVLNG 0357C ; Push A as new System Binary The CC file is a code comment file. It provides comments explaining what the code at a particular address is doing. When the corresponding address is unassembled, the comment is appended to the output line. Code comments are created and deleted with the CC and CCD commands. Note that GOTOs are followed. This can be disabled or enabled with the SET MODE NOFOLLOW and SET MODE FOLLOW commands. Example: the RPL routine at 03188 executes the inner-most code for the DUP routine (i.e. after error checking and setup has been done). It is an assembler routine with an RPL entry point, and unthreading the entry point yields: Voyager> UT 03188 03188: ; *** Internal DUP *** 03188: 0318D ! Machine Code at 0318D 0318D: CF D=D-1 A ; room on stack? 0318F: 41F GOC 03181 ; if not, make some 03192: 143 A=DAT1 A ; get obj @ TOS 03195: 1C4 D1=D1- 5 ; push object again 03198: 141 DAT1=A A 0319B: 142 A=DAT0 A ; continue RPL 0319E: 164 D0=D0+ 5 031A1: 808C PC=(A) The CAX and CCX files are index files for the CA and CC files. ================================================================ Conventions ================================================================ UPPERCASE Uppercase characters indicate a command or keyword. These can be entered as either upper or lower case. Most commands can be abbreviated. lowercase Lowercase is used as a placeholder for information that you would enter. [optional] Square brackets indicate an optional parameter or keyword. addr A five digit hexadecimal address address, a "." or a "$". A "." means the next address or 'continue'. A "$" means the last specified address or 'repeat'. The last specified address can be either explicitly specified or implicitly specified. If addr is optional and omitted, it defaults to the next address (continue). addr:addr Indicates an address range. You may omit either the start or end addresses. The start address will default to 00000. The end address will default to FFFFF. You may also use the "." and "$" as specified above. If you specify a single address without the range specifier (the ":") then the range is that single address. For example: Means: : 00000 to FFFFF :14D20 00000 to 14A20 1175: 01175 to FFFFF 3E7:400 003E7 to 00400 2B7 002B7 only ================================================================ Voyager Quick Reference ================================================================ CA addr text CAD addr CC addr text CCD addr CL addr DUMP [addr] DA [addr] DH [addr] DT [addr] EXAMINE HASH_TABLE addr lib-no EXAMINE LINK_TABLE addr lib-no EXAMINE MESSAGE_TABLE addr lib-no EXIT FIND addr:addr partial-comment HELP LIST addr:addr LOAD port module MERGE port filename SEARCH addr:addr hex-string SET LIMIT number SET MODE FOLLOW SET MODE NOFOLLOW SET MODE INFO SET MODE NOINFO SET MODE PAGE SET MODE NOPAGE SET MODE PROMPT SET MODE NOPROMPT SHOW LIMIT SHOW MODES SHOW PORTS SHOW VERSION SORT port UNASSEMBLE [addr] UA [addr] UNCONTINUE [addr] U [addr] UNLOAD port UNTHREAD [addr] UT [addr] ================================================================ Voyager Command Dictionary ================================================================ ---------------------------------------------------------------- CA addr text Creates or replaces an Address Comment for the specified address. ---------------------------------------------------------------- CAD addr Deletes the Address Comment for the specified address. ---------------------------------------------------------------- CC addr text Creates or replaces a Code Comment for the specified address. ---------------------------------------------------------------- CCD addr Deletes the Code Comment for the specified address. ---------------------------------------------------------------- CL addr Lists the Address and Code comments for the specified address. ---------------------------------------------------------------- DUMP [addr] DA [addr] DH [addr] DT [addr] Displays the contents of memory at the specified address. The number of lines displayed can be changed with the SET LIMIT command. DUMP displays the information in the current dump mode (defaults to HEX). DA, DH and DT set the dump mode to ALTERNATE, HEX or TEXT and then displsy the information. ---------------------------------------------------------------- EXAMINE HASH_TABLE addr lib-no Examines the Binary Integer at the specified address as if it were the Hash Table for the specified library. ---------------------------------------------------------------- EXAMINE LINK_TABLE addr lib-no Examines the Binary Integer at the specified address as if it were the Link Table for the specified library. ---------------------------------------------------------------- EXAMINE MESSAGE_TABLE addr lib-no Examines the Array of String at the specified address as if it were the Message Table for the specified library. ---------------------------------------------------------------- EXIT Exit Voyager and return to DOS. ---------------------------------------------------------------- FIND addr:addr partial-comment Searches the Address Comment files for the specified partial comment. The case of the comment is ignored. For example: To search for all occurrences of "prolog" in the range 2000 to 3000, you would say: Voyager> FIND 2000:3000 prolog ---------------------------------------------------------------- HELP Provides brief help on Voyager commands. ---------------------------------------------------------------- LIST addr:addr List the Address Comments in the specified range. For example: list the address comment for 3ADA. Voyager> LIST 3ADA For example: list all the address comments from 3B234 to 3DB15. Voyager> LIST 3B234:3DB15 ---------------------------------------------------------------- LOAD port module Loads the specified module into the specified port. If a module has already been loaded in that port, the old module is unloaded first. The comment files are created if they are missing. The index files are automatically recreated if they are out-of-date or missing. The required MEM file (module.MEM) can be created with either the BINTOMEM or DMPTOMEM programs. For example: load the REV module into port 1. Voyager> LOAD 1 REV ---------------------------------------------------------------- MERGE port filename Merges the comments in the specified file into the address comment file for the specified port. Only new comments are added to the comment file. Existing comments are not overwritten. The format of the comments in the file to be merged can be up to 255 characters long and must be in this format: Where: = a 1 to 5 digit hexadecimal address. = a single character followed by optional whitespace. = any text, up to the new-line character. ---------------------------------------------------------------- SEARCH addr:addr hex-string Search part of the memory. Hex-string specifiers the data for which to search. For example, to search for references to the internal DUP command (at address 03188), you would say: Voyager> SEARCH : 03188 To search for a hex-string in Memory Scanner format (backwards), you would prefix the hex-string with a single quote. For example (this is equivalent to the previous example): Voyager> SEARCH : '88130 ---------------------------------------------------------------- SET LIMIT number Sets the number of lines displayed by the UNASSEMBLE and DUMP commands. The default is ten. ---------------------------------------------------------------- SET MODE FOLLOW SET MODE NOFOLLOW Specifieds whether or not the UNASSEMBLE command follows absolute gotos (GOTO, GOLONG and GOVLNG). Conditional gotos (GOC, GONC, RTNC or RTNNC) that have a Code Comment of "BET" (Branch Every Time) are also subject to the same logic. The default is FOLLOW. ---------------------------------------------------------------- SET MODE INFO SET MODE NOINFO Specifies whether or not information (debug) messages are displayed. The default is NOINFO. ---------------------------------------------------------------- SET MODE PAGE SET MODE NOPAGE Specifies whether or not Voyager pauses after a screen full has been displayed. The default is PAGE. ---------------------------------------------------------------- SET MODE PROMPT SET MODE NOPROMPT Specifies whether or not the Voyager prompt is displayed. The default is PROMPT. ---------------------------------------------------------------- SHOW LIMIT Displays the number of lines that will be displayed by the UNASSEMBLE and DUMP commands. ---------------------------------------------------------------- SHOW MODES Displays the various mode settings. ---------------------------------------------------------------- SHOW PORTS Displays which ports have been loaded. ---------------------------------------------------------------- SHOW VERSION Displays the software version for Voyager. ---------------------------------------------------------------- SORT port Sorts the address and code comment files for the specified port. The files are sorted by address and the index files are recreated. You must fist LOAD the port before sorting it. Sorting is not required, but it will eliminate deleted comments and make the comment files nice and pretty for printing. ---------------------------------------------------------------- UNASSEMBLE [addr] UA [addr] Disassembles the memory as machine code starting at the specified address. The number of lines displayed is specified with the SET LIMIT command. ---------------------------------------------------------------- UNCONTINUE [addr] U [addr] Continues disassembly based on the last mode (unassemble or unthread). ---------------------------------------------------------------- UNLOAD port Unloads the module in the specified port. ---------------------------------------------------------------- UNTHREAD [addr] UT [addr] Disasembles one object starting at the specified address. ================================================================ BINTOMEM input[.BIN] [output[.MEM]] (program) Converts a binary file into a flat memory dump (Voyager format). ================================================================ DMPTOMEM input[.DMP] [output[.MEM]] (program) Converts a Memory Scanner dump into a flat memory dump (Voyager format).