idbg - IJVM debugger.
idbg <bytecode file> [debug symbols file]
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.
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.
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.)
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.
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.
If a string is not interpreted as a method name, it's left as a string.
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.
This command causes idbg to reset the execution environment.
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.
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.
This command causes idbg to execute one instruction.
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.)
This command causes the program output screen to be displayed until a key is pressed on the keyboard.
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.
This command causes disassembly of number bytes starting at the given address.
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.
Like the above, but prints number words, rather than the current stack frame.
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.
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.
This sets a breakpoint at the given address.
This removes a breakpoint at the given address.
This shows a list of all currently active breakpoints.
This sets the number of lines before the pager interrupts output. Set it to -1 and the output is never paged.
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.
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.
This controls the printing of the disassembly of the instruction at PC before every prompt.
This enables the logging of all output to the file named by string.
This stops the logging of output.
This causes idbg to exit.
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.
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.
Idbg was written by Tom Rothamel <