NAME idbg - IJVM debugger. SYNOPSIS idbg [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
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 : 2 parameters. 000096 : 2 local variables. B PC-> 000098 : 10 09 bipush 0x09 00009A : 36 03 istore index B 00009C : 10 01 bipush 0x01 00009E : 36 02 istore place 0000A0 : 10 00 bipush 0x00 0000A2 : 15 03 iload index 0000A4 : 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
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 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
This sets a breakpoint at the given address. drop break
This removes a breakpoint at the given address. show break This shows a list of all currently active breakpoints. set page This sets the number of lines before the pager interrupts output. Set it to -1 and the output is never paged. set quick 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 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 This controls the printing of the disassembly of the instruction at PC before every prompt. set log 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 , 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 . It's available from the web at .