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 <