infocom/interpreters/old/zipdebug/zipdebug.readme

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 <StoryFileName>

Execution commands:
        X [P] <Address>                 start execution at address
        A [P] <Address>                 start execution with trace
        S                               enter single step mode
In single step mode the following keys can be typed:
        <space>                         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] <AddressRange>            list code
        G [P] <AddressRange>            list code assumming address is subroutine
                                        start (register initialization data)
        T [P] <AddressRange>            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] <AddressRangle> list memory (words | bytes)


List object:
        O [P] ( <AddressRange> | "<string>" [, <Address>] ) [#]

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 <address>                     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  <address> [<number>]        Set breakpoint at <address> with
                                        an optional hit count of <number>
        BC  [<address>]                 Clear breakpoint at address or
                                        last breakpoint set
        BOS <number>                    Set breakpoint on opcode <number>
        BOC <number>                    Clear breakpoint on opcode <number>
        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] <AddressRange> {, <Number>}

Parameter syntax:
        AddressRange  = [<Address> [. <Address>]]
        Address       = [&] [*] <Number> [W|Q] | ~ | ^ | @ | + <Address>
        Number        = <Hexdigit> {<Hexdigit>}

@ 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 <storyfilename>
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.