zipdebug help file (19-Mar-94) ------------------------------ zipdebug was written by Frank Lancaster during 1984-1994. zipdebug and sources are free, you may do anything with them. Contact: email: fl@tools.de paper mail: Frank Lancaster Karl-Barth-Str. 39 D-53129 Bonn Germany This programme is a combined interpreter and debugger for Infocom adventures. It contains a complete interpreter and disassmbler for code versions 1, 2, 3, 4 and 5 (Borderzone (including real time action) and Sherlock run without problems, in Beyond Zork the on-line mapping will only work correctly with the alternate font with Acorn RISC OS, colour is also only supported in RISC OS). Code version 6 (Zork Zero, Shogun, King Arthur) can be partially disassembled but will not run properly (work will continue on getting it to run). I invented the mnemonics for the op-codes myself, so they won't be compatible to anything else you may have seen. Descriptions of the mnemonics and opcodes will be avaialble "real soon now" (that means whenever I find time). With RISC OS zipdebug should be started from the desktop, either by double clicking the application icon (this will start the programme in interactive mode) or by double-clicking a story data file (file type should be 1, this will start executing the story). Under UNIX zipdebug should be used from the command line. To run a story call the programme with the story name as first parameter to the programme. E.g.: zipdebug Borderzone zipdebug is programmed in UCSD Pascal which is translated to c with p2c. This removed a lot of bugs which were due to the Acorn ISO Pascal (spit, spit!) Compiler (I didn't have any other Pascal compiler for the Archimedes). The programme started out on an Apple II with UCSD Pascal and initially was only a z-code disassembler. The source code (Pascal & C) is included. I will continue to use the Pascal source, so I would prefer any changes to be made in that source. If the programme is called without a parameter, it will prompt you for commands on its own command line. zipdebug understands the following commands (the P option sends output to the listing file (this is called 'listing' in the current directory): [] surround optional parameters, <> surround parameter names, {} surround repeatable parameters, () group alternatives, | separates alternatives): Load new story file: N Execution commands: X [P]
start execution at address A [P]
start execution with trace S enter single step mode In single step mode the following keys can be typed: step one instruction O execute until instruction after this one is reached L disassemble next instruction G execute until listed instruction is reached T switch to trace mode X start normal execution B set break point C clear break point Ctrl-B interrupts execution and the last instruction is disassembled. ESC interrupts any operation and returns you to the command line. List commands: L [P] list code G [P] list code assumming address is subroutine start (register initialization data) T [P] list text (compressed) I[P][M|S] list header info or statistics V[P|A] list vocabulary (A = with pointers) C[P] list calls (backtrace) R [P] list registers W ( W | B ) [P] list memory (words | bytes) List object: O [P] ( | "" [,
] ) [#] Objects can be specified by number (if a range is given all objects in that range are listed) or searched for by specifing a string and optionally the maximum number of objects which should be checked. Each object, which has the specified string in its name, is listed. The # option enables property listing (object properties are additional data per object. Each property has a number and a value, the number is displayed first, then the value, which can be a single byte a two byte word or a multi byte string). Z-State command: Z [P] [S|I|R|X] Options: S list z-state R reset z-state I initialise z-state (reload data pages and reset) X start execution at start address Entry point command: E [C|D|N|Y] The disassembler saves every subroutine address for better disassembly (register initialization data is at the start of a subroutine, trying to list this data as code gives wrong disassembly). Options: C delete all saved entry points D
delete entry point at address Y turn on entry point saving N turn off entry point saving With no option the saved entry points are listed. Breakpoint commands: B[P] List breakoints BS
[] Set breakpoint at
with an optional hit count of BC [
] Clear breakpoint at address or last breakpoint set BOS Set breakpoint on opcode BOC Clear breakpoint on opcode BOZ Clear all "on opcode" breakpoints BZ Clear all breakpoints Quit: Q Help: ? | H Verify code: $ Set option: D ( (C|T|U|N) | ( (B||F|I|K|O|R|S|V) (Y|N|T|F) ) ) Dump options: DC Set dump state to code dump DT Set dump state to text dump DU Set dump state to unpacked value dump DN Turn off all code and text dumping Switches (Y, N, T or F must follow the switch character): DB Disassemble breakpoints DF Fault unimplemented operations and operand errors DI Disassemble with object names DK Crash on internal error DO Set IPC to restart operations after internal error or break DR Check for register lists in code while disassembling DS Start computing opcode statistics DV Debug parsing of vocabulary Modify memory: M ( W | B ) [P] {, } Parameter syntax: AddressRange = [
[.
]] Address = [&] [*] [W|Q] | ~ | ^ | @ | +
Number = {} @ is the start address supplied in the header. ~ is the previouly specified address. ^ is the address specified before the previous address. & as prefix means indirect. * as prefix means data relative. W as suffix means word address. Q as suffix means double word address. G as suffix means code address If no address is used the last address will be used, so repeating 'L' will disassemble code sequentially. To execute an adventure type the following commands: N X Special keys: Ctrl-B Break-Key. Typing this will interrupt the execution of a story. Ctrl-S Wait-Key. Typing this will suspend output until Ctrl-S ist typed again. ESC Output interrupt. Typing this will stop any output and return to the command line.