=head1 NAME idbg - IJVM debugger. =head1 SYNOPSIS idbg [debug symbols file] =head1 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. =head1 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. =head2 Definitions =over 4 =item 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.) =item 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. =item 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. =item string If a string is not interpreted as a method name, it's left as a string. =item 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. =back =head2 Commands =over 4 =item reinit This command causes idbg to reset the execution environment. =item 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. =item 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. =item step This command causes idbg to execute one instruction. =item 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.) =item show This command causes the program output screen to be displayed until a key is pressed on the keyboard. =item 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. =item disasm
This command causes disassembly of number bytes starting at the given address. =item 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. =item stack Like the above, but prints number words, rather than the current stack frame. =item 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. =item 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. =item break
This sets a breakpoint at the given address. =item drop break
This removes a breakpoint at the given address. =item show break This shows a list of all currently active breakpoints. =item set page This sets the number of lines before the pager interrupts output. Set it to -1 and the output is never paged. =item 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. =item 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. =item set disasm This controls the printing of the disassembly of the instruction at PC before every prompt. =item set log This enables the logging of all output to the file named by string. =item stop log This stops the logging of output. =item quit This causes idbg to exit. =back =head1 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. =head1 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. =head1 AUTHOR AND WEB SITE Idbg was written by Tom Rothamel . It's available from the web at .