How to use
Unassemble Window
Execution control
Breakpoints
Trap Breaks
Dump Memory
Write to Memory
Miscellaneous
Legends
Added new command sc, Stack crawl, from A6.
Improved the speed by inlining some methods and other things.
reg now re-fetches all the registers each time and also shows the USP, SSP and PC contents.
Trapped some possible NumberFormatExceptions.
Added new commands te Enable Trap Break, and td Disable Trap Break.
Fixed go end to work on the Simulator. You still need to be careful using this, that's why I removed the Go End button.
Tried to improve the speed in some places, like the Shut-Down, and it now uses a table-based CRC16 calculation.
Fixed an issue with Unassemble u.
Made other, various, improvements.
Now works with the Simulator in addition to the Emulator.
Works with Java 1.5.
Added new Routine Name command.
Fixed numerous problems.
Added new Fill memory command.
New argument 'a' to clear all Breakpoints or Trap Breaks.
New buttons for Step, Next, Go, Go End and Out in addition to the existing function keys and regular command keys.
Faster disassembly speeds in the Unassemble window.
Disabled Debug and Unassemble windows until debugging session has started.
Re-added u ( Unassemble ) command back in for doing disassembly in the Debug window.
Menu. Now it has a menu with Options ( change between 'Decimal' and 'Hex' output ) Window ( change between 'Debug' and 'Unassemble' windows ) and Help ( help window )
In addition to the regular Debug window, there's now a new Unassemble window! This gives you a view of the entire procedure unassembled. With it there are also buttons to navigate forward or backward to the next procedure. There is also a convenient Set Breakpoint button for setting both Trap breaks and regular Breakpoints.
I'm pretty confidant that every opcode, no matter how seldom used or obscure, is working well now. Some other debuggers won't even disassemble some of the opcodes that Debug supports. Movep, which I doubt anybody actually uses ;), is working, and the "CCR", "SR" and "USP" operands are fixed.
The output for the displacement has been improved and is now more "standard".
Most of the other changes are a lot of tweaking of Debug's data file.
Fixed some problems with unassemble (u). It's now smarter about handling data between 'rts' and 'link'. Sometimes there were problems with using a starting address.
Dropped CPU Usage from 100% to 2%, and it's even more responsive! ;)
Rewrote Next (n) routine. Occasionally it would get hung-up. Works great now.
Fixed a register mask problem with 'movem'.
Fixed a small problem with one of the effective address modes.
Bumped up the default number of bytes to search in Find to 16384. The <address> now defaults to the current PC loaction.
By going with a new GUI (AWT) based application Debug gains use of: Easier startup, now you can double-click on Debug.jar to launch it, or use the included .bat file. One-touch commands through the function keys: F4 out F5 Go end ( see below ) F6 Go F7 Next F8 Step It also opens the door for even more enhancements.
Added new "go end" command which continues execution till it reaches the last instruction in the procedure, where it breaks. Makes debugging much easier!
Fixed a problem with "go" which would sometimes get Debug into an unresponsive state.
The Step Spy is now fully supported and works! ( More details below ) It was always there, it just didn't work too well, so I didn't fully document it. ;)
Fixed "rn". It didn't display the routine name when it was there.
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.3.0_02
JRE 1.4.2_08
JRE 1.5 Update 3
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.
Under Windows, the easiest way to run Debug, is just to double-click the included 'Debug.bat' file, once you have the path to your JRE setup.
I create/run a .bat file that does the following:
If your JRE is in C:\jre1.5.0
SET CLASSPATH=.;C:\jre1.5.0\lib\rt.jar ( Don't forget the leading "." ( current directory ))
SET PATH=C:\jre1.5.0\bin;%PATH%
Add a "trap #8" into your assembly source, or for C add: #include <DebugMgr.h> and DbgBreak(); 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
If Java is setup correctly, you can also double-click the Debug.jar file, in Windows, to start it.
Debug will start and wait for the Emulator or Simulator to run..
Start the Emulator or Simulator. After the Emulator or Simulator runs, Debug will display "Connected.." indicating a successful socket connection.
If you don't get "Connected.." when the Simulator is running, do a Soft Reset on the Simulator and that should get it to work.
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 F8 (s). When you hit a "SysTrap" use F7 (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 F4 (out) to step out of that routine. One 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 F7 (go) to continue execution till it gets hit.
Unassemble Window
Selecting Unassemble in the Window menu will display the Unassemble window. The entire current procedure is unassembled and displayed in a scrollable window. At any time you can select Debug from the Window menu which will take you back to the Debug window.
Proc < and Proc > buttonsThese buttons will go forward, or backward, and unassemble the next procedure. When the first or last procedure is hit and you try to go further in that direction, a Dialog window will pop-up informing you of that, and will not let you go further. After pressing these buttons, give it time to read, unassemble and display the results.
Set Breakpoint button
This button allows you to easily set both Trap breaks, SysTrap FrmGetActiveForm etc., and regular Breakpoints ( all other statements ). To set a Breakpoint in the displayed procedure, position the cursor anywhere on the line of the statement you wish to set a Breakpoint on. It is not necessary to 'select' the line by highlighting it. Hit the Set Breakpoint button. If the Breakpoint was set successfully the entire statement line will be highlighted. If the Breakpoints are full, it will put up a Dialog window informing you of this, and the line will not be highlighted. To clear one or more Breakpoints, you need to go back into the regular Debug window and clear them there.
Simulator Note:
Sometimes the Simulator can be a little slow to respond to the Proc < and Proc > buttons, especially when it's trying to unassemble a large procedure. Sometimes it can take up to five seconds, or more, to output the results. Wait for the button to loose focus and for the display to be updated. Please resist the temptation to keep hitting the button. :-) If it's taking up to thirty seconds to respond, then there is a problem.
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 (F8) Single step. Execute the next instruction.
n (F7) Execute the next instruction, stepping over bsr, jsr and SysTraps.
go [<address>] (F6) Continue execution until a Breakpoint ( <address> ) is hit or an exception is encountered.
go end (F5) Continue execution until the last statement in the current procedure is hit. ( Sets a Breakpoint at the rts at the end of the procedure ) Great for skipping ahead to the end of a long, time consuming procedure. In some cases it might not work, as the procedure could be exited before it hits the Breakpoint set at the end.
out (F4) 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 a] Clear the Breakpoint in the given slot number, or the last ( most recent ) slot. 'a' clears all Breakpoints. 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 new entries. This method of doing Breakpoints also pretty much eliminates the need for you to deal with slot numbers.
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
te [0 - 4] Enable the Trap Break in the given slot number, or last ( most recent ) slot. The Trap Break's SysTrapName is unaffected. 'Enable' is only needed if you specifically 'Disable' a Trap Break, they are enabled automatically.
td [0 - 4] Disable the Trap Break in the given slot number, or the last ( most recent ) slot. The Trap Break's SysTrapName is unaffected.
tl Lists all active Trap Breaks, their corresponding slot number and their enabled status.
tc [0 - 4 a] Clear the Trap Break in the given slot number, or the last ( most recent ) slot. 'a' clears all Trap Breaks. 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.
fill <address> <value> <byteVal> Fill memory with <byteVal> starting at <address> for <value> number of bytes.
Example: fill $35001c 10 $ff
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>.
spy <address> <value> Step Spy. The Emulator will monitor <value> bytes ( 1, 2, or 4 ) at <address>. When the contents of that location changes, an exception is generated which causes Debug to break. Usually you would issue a "go" after "spy". After it breaks you need to issue "nospy" ( below ) to disable it. This can be useful for detecting if, and when, a variable or memory is getting clobbered.
nospy Disable the Step Spy.
reg Re-fetch and display all registers contents including USP, SSP and PC. Useful when you have many screenfulls of Dump, or other data, and want to look at the register contents again.
sc Stack crawl. Display list of functions on the stack using A6.
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 needed) use '$' for up to four hex bytes starting at <address> ' i ' = use case-insensitive search ( case-sensitive default ) <bytes to search> ( 16384 default ). Displays memory dump, at that location, if successfull.
Examples:
f $29ee $10032f8c
f AppEventLoop a2
Use ' f ' ( with no arguments ) to continue search immediately after a previous Find.
u [<address>] Unassemble instructions at <address>, or current PC location by default. The Unassemble Window gives you a better view of the procedure, but this is handy for the Debug Window.
rn [<address>] Display the Routine Name, if available, and the Starting and Ending address of Routine at <address>, or current PC location by default.
I found, what looks like, a problem with the Get Routine Name command in the Debugger protocol when running it under the Emulator. Usually when you give it the address of the leading 'link' instruction of a procedure, it returns with that address as it's startAddr but I've seen it return the startAddr many bytes before the leading 'link' instruction. Also, be careful when using it on the Simulator, I've seen it not respond to some addresses, which will basically lock-up Debug waiting for it to respond.
[] 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 a5+$35c a5-2
( normal precedence/associativity is not used )
<value> Hex number, preceded with '$', or decimal number, giving value information.
( numbers exceeding four bytes ( Int32 ) will be truncated without warning )
I hope you enjoy using Debug. If you've found a bug, would like a feature added, an existing command changed, or just want to say "Hey!" please send me an email, I want to hear from you! Really! :-)