NAME
    idbg - IJVM debugger.

SYNOPSIS
      idbg <bytecode file> [debug symbols file]

DESCRIPTION
    Idbg is a debugger for IJVM bytecode files. It can execute the
    files, and provides several facilites for the debugging and
    tracing of the code. It can use a symbols file generated by
    ijvmasm to annotate it's output with the same names used in the
    source.

COMMAND GUIDE
    This is a guide to the commands that can be typed on the idbg
    command line. An empty command line causes the previous command
    to be repeated.

  Definitions

    number
        Where a number is required by a command, it can be input
        either as a decimal number, or a hex number preceded by 0x.
        (Like 0x42 or 66.)

    boolean
        A boolean value is input as a number. If the number given is
        0, the value is interpreted as false. Otherwise, it's
        considered to be true.

    method name
        This is the name of a method. It's usually input just as a
        name. It can also be entered as a string in double quotes.

    string
        If a string is not interpreted as a method name, it's left
        as a string.

    address
        An address can be a method name (in which case it's the
        address of the first executable opcode in that method), a
        method name + an offset, PC (the program counter), PC + or -
        an offset, or a numerical address.

  Commands

    reinit
        This command causes idbg to reset the execution environment.

    go  This command causes idbg to begin continual execution of the
        bytecode. Idbg will only stop execution when a breakpoint is
        hit, when an interrupt is recieved, or the program executes
        a halt instruction.

    run This command causes idbg to begin continual execution of the
        bytecode from the start. Idbg will only stop execution when
        a breakpoint is hit, when an interrupt is recieved, or the
        program executes a halt instruction.

    step
        This command causes idbg to execute one instruction.

    next
        This command causes idbg to execute one instruction.
        However, if the instruction that is executed is a method
        invocation, idbg continues execution until the method
        returns. (Or until the a breakpoint is reached, an interrupt
        is typed, or a halt occurs.)

    show
        This command causes the program output screen to be
        displayed until a key is pressed on the keyboard.

    disasm <address>
        This command causes a method to be disassembled. The method
        that is chosen is the one containing the address.

        The output looks like this:

                000094 <print+0x0000>: 2 parameters.
                000096 <print+0x0002>: 2 local variables.
         B PC-> 000098 <print+0x0004>:   10 09          bipush 0x09
                00009A <print+0x0006>:   36 03          istore index
         B      00009C <print+0x0008>:   10 01          bipush 0x01
                00009E <print+0x000a>:   36 02          istore place
                0000A0 <print+0x000c>:   10 00          bipush 0x00
                0000A2 <print+0x000e>:   15 03          iload index
                0000A4 <print+0x0010>:   10 01          bipush 0x01

        The first column contains 'B' if a breakpoint is set on this
        opcode, or spaces otherwise. The second contains 'PC->' if
        the current PC is this instruction, or space otherwise.
        After that is the address of the instruction, both as an
        absolute number and as a method offset. After that is a
        printout of the bytes that make up the instruction, followed
        by a symbolic representation of the opcode and it's
        parameters.

        The first four bytes of a method that isn't main contain
        information about the number of paramters and local
        variables. That information is decoded and printed as
        appropriate.

    disasm <address> <number>
        This command causes disassembly of number bytes starting at
        the given address.

    stack
        This command causes a full stack dump to be printed. It
        attempts to decode the value of each member of the current
        stack frame.

         Stack 00008008:       +1   00000001 (SP) 
         Stack 00008007:       +9   00000009 
         Stack 00008006:       +0   00000000 
         Stack 00008005:   +49152   0000C000 (Old LV) 
         Stack 00008004:      +64 @ 00000040 (Old PC) 
         Stack 00008003:       +9   00000009 index 
         Stack 00008002:       +1   00000001 place 
         Stack 00008001:    +1401   00000579 total 
         Stack 00008000:   +32772   00008004 LINK PTR (LV) 

        The second column of the stack dump is the address of this
        stack word. The third column displays the value of the stack
        word as a decimal number. The fourth tries to display it as
        a character if it's in range. The fifth is the value as a
        hex number.

        Finally, idbg attempts to print out the meaning of this word
        on the stack. If a variable name is associated with this
        word, it's printed. If SP or LV are pointing to this word,
        (SP) or (LV) are printed, respectively. If this word
        contains the old values of PC or LV pushed onto the stack,
        (Old PC) or (Old PC) are printed.

    stack <number>
        Like the above, but prints number words, rather than the
        current stack frame.

    vars
        Prints the current variables. It's useful for debugging
        main, which doesn't store it's variables on the stack, but
        rather stores it in a special area. The format is the same
        as that of a stack trace.

    trace
        Executes instructions until interrupted, a breakpoint is
        reached, or halt is executed. At the time of each
        instruction fetch-decode, the stack is printed, as is the
        new instruction. A line is printed to separate fetch-decode
        cycles from each other.

        This is most useful in conjunction with set log.

    break <address>
        This sets a breakpoint at the given address.

    drop break <address>
        This removes a breakpoint at the given address.

    show break
        This shows a list of all currently active breakpoints.

    set page <number>
        This sets the number of lines before the pager interrupts
        output. Set it to -1 and the output is never paged.

    set quick <boolean>
        This controls the printing of a quick stack/variable dump
        before every prompt is issued. What is meant by quick is
        that no more than 10 words of stack is printed.

        Only one of 'set quick' and 'set full' should be set, but
        this isn't enforced.

    set full <boolean>
        This controls the printing of a full dump of the current
        stack frame and variables before every prompt.

        Only one of 'set quick' and 'set full' should be set, but
        this isn't enforced.

    set disasm <boolean>
        This controls the printing of the disassembly of the
        instruction at PC before every prompt.

    set log <string>
        This enables the logging of all output to the file named by
        string.

    stop log
        This stops the logging of output.

    quit
        This causes idbg to exit.

THE FETCH-DECODE-EXECUTE CYCLE
    When the commands in idbg look at memory, they do it while the
    virtual machine is in the fetch phase of the fetch-decode-
    execute cycle. (Actually, idbg combines the fetch and decode
    phases of instruction execution into a single fetch-decode
    phase.)

    What this means is that the stack displayed represents the stack
    before the execution of the instruction pointed to by PC.

IJVM VERSION IMPLEMENTED
    This program implements the version of IJVM described in
    _Structured Computer Organization_ Fourth Edition. It also adds
    the IN, OUT, HALT, and ERR instructions from
    <http://www.ontko.com/mic1/jas.html>, the specification of IJVM
    used by the mic1 simulator.

    It also supports my IJVMA instruction set, which adds the
    ALLOCA, BASE, IGET, and IPUT instructions for addressing.

    The IN instruction is blocking, but it may return 0 if
    interrupted.

AUTHOR AND WEB SITE
    Idbg was written by Tom Rothamel <tom-11021@onegeek.org>. It's
    available from the web at
    <http://onegeek.org/~tom/software/ijvm/>.

