How to use
Execution control
Breakpoints
Trap Breaks
Dump Memory
Write to Memory
Miscellaneous
Legends
Being able to use a registers contents for an address worked out so well, that now any command that has an <address> option you can specify a register.
You can now also use simple expressions for <address>! Example: a5+$2c
Improved Find, so that you can now do a 'Find Next' from the previous search.
Fixed bug in effective address calculation for showing source operand contents.
Improved Dump commands, now they have options for using a register as the starting address, and an optional number of bytes to display.
Added new "reg" command which re-displays all the register contents.
Improved Find command, now you can specify up to four hex bytes in the search string. ( should have done this a long time ago.. ) ;) Default search range bumped up to 5120 bytes.
Added more error checking.
Fixed problem with setting registers using "r".
Added new Routine Name command "rn".
Masked-off some pesky sign extension bits that caused opcode size problems.
Fixed a routine that was causing problems with the address of dump commands.
Minimized empty Trap Listings.
Fixed some startup problems: a NullPointerException, and problems if it tried to pre-fetch source data for the first instruction it disassembled.
Tweaked "tabdat" and updated the SysTraps to the latest Palm OS 3.5.
Went to a more standard .JAR file.
Fixed-up the Exit code.
If you don't already have Java set up on your system, I'd recommend downloading the JRE ( Java Runtime Environment ) from SUN. ( It's a fairly small download )..
JRE 1.1.x
JRE 1.2.2
Unfortunately, I can only tell you how to get it going under Windows, for other OS's, find your local guru, or try and figure it out yourself.
I create/run a .bat file that does the following:
SET CLASSPATH=.;C:\JRE\1.1\lib\rt.jar ( Don't forget the leading "." ( current directory ))
SET PATH=C:\JRE\1.1\BIN;%path%
For assembly add a "trap #8", or for C: #include <DebugMgr.h> and add "DbgBreak();" into your source code, where you want the debugger to break-in, and compile it. Open a Command Prompt ( DOS window ), CD into the directory Debug.jar is in and start Debug: ( here's how I do it )
java -jar Debug.jar
or..
java -cp .\Debug.jar debug
Debug will start and wait for the Emulator to run..
Start the Emulator. After the Emulator runs, Debug will display "Connected.." indicating a successful Socket connection.
Load and start your application.
When the Trap is hit you're ready to start stepping through your code.
Typical Usage
Once the initial Trap is hit, step through your code using "s". When you hit a "SysTrap" use "n" to step over it ( you usually don't want to step through it's system code ). If you accidentally step into it, keep using "s" till you step past "link", then use "out" to step out of that routine. An easy way to skip past a time consuming section of code is to find a SysTrap in your code at the end of it and use "tb" <SysTrapName> to set a Trap Break there and use "go" to continue execution till it gets hit.
Want 'stack backtrace'? RPC command access? Other commands, or enhancements to existing commands? Let me know. I'd like to make Debug more useful for debugging higher-level languages, I see a lot of: "I can't get X to work".
I'm currently working on a new GUI version which will feature double-click startup, and have one-touch function key commands. Your feedback is important, let me know what YOU want.
Execution control commands let you step through instructions, one at a time, or let execution continue until a Breakpoint is hit or an exception is encountered.
s ( Single step ) Execute the next instruction.
n Execute the next instruction, stepping over bsr, jsr and SysTraps.
go [<address>] Continue execution until a Breakpoint ( <address> ) is hit or an exception is encountered.
out Step Out of the current routine. ( Step past "link" before you execute this )
Debug will display the contents of the source operand when appropriate. This saves you the trouble of doing a Dump of its effective address.D0: 00000000 D1: 00000009 D2: 0000000c D3: 0000273a D4: fdde621f D5: 000001e8 D6: 00000000 D7: 00010000 A0: 0000268e A1: 10c19c74 A2: 0000033c A3: 00020000 A4: 10c10100 A5: 0000011a A6: 0000272a A7: 0000271a S=1 X=0 N=0 Z=0 V=0 C=0 10c15af4: 286e 000c move.l $c(a6),a4 (0000273a) ^ | contents of $c(a6)
Breakpoints are stored in six "slots", the last slot is used only for temporary breakpoints. Slots zero through four are available for normal Breakpoint use.
bp [<address>] Loads the given address, or current PC location by default, into the next available Breakpoint slot. The Breakpoint is automatically enabled.
be [0 - 4] Enable the Breakpoint in the given slot number, or last ( most recent ) slot. The Breakpoint's address is unaffected. 'Enable' is only needed if you specifically 'Disable' a Breakpoint, they are enabled automatically.
bd [0 - 4] Disable the Breakpoint in the given slot number, or the last ( most recent ) slot. The Breakpoint's address is unaffected.
bl Lists all available Breakpoints, their corresponding slot number, and their enabled status.
bc [0 - 4] Clear the Breakpoint in the given slot number, or the last ( most recent ) slot. The Breakpoint slots are compacted to remove any empty slot.
Breakpoints and Trap Breaks both work on the "most recent" ( last ) entry if a slot number isn't specified. If you clear a slot, all entries are compacted to make room for newer ones.
The Trap Break commands let you re-enter Debug when a particular system trap is called. You can store up to five Trap Breaks.
tb <SysTrapName> Loads the given system trap, FrmGotoForm etc., into the next available slot, and it is automatically enabled
tl Lists all active Trap Breaks and their corresponding slot number.
tc [0 - 4] Clear the Trap Break in the given slot number, or the last ( most recent ) slot. The slots are compacted to remove any empty slot.
The Dump Memory commands let you display the contents of selected memory addresses. The contents are arranged by byte, word, or long/double-word and shows the corresponding ASCII characters. Repeated Dump commands, without an address, continues from the last.
The optional entry for <numBytes> is the number of bytes to display ( 256 maximum ), a default number of bytes is displayed if not used.
db [<address>] [<numBytes>] Dump Bytes at the given address, or current PC location by default.
dw [<address>] [<numBytes>] Dump Words at the given address, or current PC location by default.
dl/dd [<address>] [<numBytes>] Dump Longs/Double-words at the given address, or current PC location by default.
The write to memory commands let you modify byte, word or long memory locations.
wb <address> <value> Write byte at <address> with <value>.
ww <address> <value> Write word at <address> with <value>.
wl <address> <value> Write long at <address> with <value>.
reg Re-display all registers contents. Useful when you have many screenfulls of Dump, or other data, and want to look at the register contents again.
r <register> <value> Set Register ( d0-d7 or a0-a6 ) to <value>.
f [ <[$]search string> <address>
[i] [<bytes to search>] ]Find <[$]search string> (no quotes) use '$' for up to four hex bytes starting at <address> ' i ' = use case-insensitive search ( case-sensitive default ) <bytes to search> ( 5120 default ). Displays memory dump, at that location, if successfull.
Examples:
f $29ee $1e110
f string a2
Use ' f ' ( with no arguments ) to continue search immediately after a previous Find.
u [<address>] Unassemble instructions at <address> or current PC.
rn Get Routine Name ( if any ) and it's starting and ending addresses
e, Ctrl-C Exit.
rad <value> Set radix to ( 10 (decimal) or 16 (hex) ). Default 16
?, help, --debug Display Help.
[] Optional command argument.
<address> Hex number ( preceded with '$' ), decimal number, register ( d0-d7 or a0-a7 ) contents
or simple expression giving address location. Expressions of up to three arguments,
with no spaces between, can use registers ( d0-d7 or a0-a7 ), '+', '-', hex numbers
( preceded with '$' ) and decimal numbers.
Examples: a2+d1-$10 $2+a5
( normal precedence/associativity is not used )
<value> Hex number, preceded with '$', or decimal number, giving value information.
( numbers exceeding four bytes will be truncated without warning )