Xtrap Debugger
Volume Number: 7
Issue Number: 4
Column Tag: Programmer's Forum
Xtrap, A Hardware Debugger
By Mike Scanlin, Mountain View, CA
A New Macintosh Debugging Tool
Software debuggers have come a long way since the Mac was first introduced.
Among other improvements, symbolic and source-level debugging are awesome.
However, there are times when it is difficult or impossible to debug software by using
software. Sometimes the observing software (the debugger) interferes with the
software being observed. Other times there are situations where you just cannot do
what you need with a software debugger. Have you ever tried to set a breakpoint in ROM
or in a VBL? Have you ever tried to debug a time-sensitive piece of code such as a
driver? Have you ever wondered if somewhere, deep within the core of your program,
you were unknowingly reading or writing to memory location zero? Have you ever had a
bug that wedged your machine so bad that your debugger was out to lunch until you
rebooted? These are all examples of the types of problems that the new Xtrap hardware
debugger from HotWire Labs can help you solve.
Real-Time Trace
In a nutshell, Xtrap is a hardware device that monitors and records all of the
activity on the address bus and data bus of the 68000 and allows you to play back that
activity at a later time. It allows you to set your own hardware-defined breakpoint
conditions (for example, “stop recording cycles as soon as there is a read or write
cycle to memory location zero”) and to play back the last 32K worth of cycles before or
after the breakpoint conditions are met. This makes it easy to see how your program got
into a particular state that you’ve defined and/or what it did after it got to that point.
Because this is a hardware device monitoring the processor it is totally transparent --
your program will run at it’s normal speed and nothing will prevent Xtrap from
recording cycles (including a munged debugger and/or operating system).
A Simple Example
Here is a simple example to give you a feel for what Xtrap is all about. Let’s say
you have a program that is causing an illegal instruction and that by the time you see
the error the PC is in a random location (and you don’t know how it got there). So you
configure Xtrap to record cycles until you get an illegal instruction. You do this by
asking Xtrap to record cycles until there is a data read cycle to the illegal instruction
exception vector (memory location $10). Once it gets one, you ask Xtrap to show you
what happened before that illegal instruction cycle. You could end up with this output:
-00039:1B572E:4EBA: : ;Jsr BugProc
-00038:1B5730:FFD0:oe :
-00037:1B5700:48E7: :BugProc ;Movem.L D5-D3,-(A7)
-00036:1BDCDA:001B:w’••’:
-00035:1BDCDC:5732:w’W2':
-00034:1B5702:1C00:oe :BugProc+0002
-00033:1B5704:61E4: :BugProc+0004 ;Bsr.S TrashRegs
-00032:1BDCD8>0000
-00031:1BDCD6>0000
-00030:1BDCD4>0000
-00029:1BDCD2:0000:w’••’:
-00028:1BDCD0>0000
-00027:1BDCCE>0000
-00026:1B5706:4CDF:sof :
-00025:1BDCCA>001B
-00024:1BDCCC>5706
-00023:1B56EA:7603: :TrashRegs ;Moveq #$03,D3
-00022:1B56EC:7804: :TrashReg+0002 ;Moveq #$04,D4
-00021:1B56EE:7A05: :TrashReg+0004 ;Moveq #$05,D5
-00020:1B56F0:4E75: :TrashReg+0006 ;Rts
-00019:1B56F2:8009:sof :
-00018:1BDCCA>001B
-00017:1BDCCC>5706
-00016:1B5706:4CDF: :BugProc+0006 ;Movem.L (A7)+,D3/D5
-00015:1B5708:0028:oe :BugProc+0008
-00014:1B570A:4E75: :BugProc+000A ;Rts
-00013:1BDCCE>0000
-00012:1BDCD0>0000
-00011:1BDCD2:0000:r’••’:
-00010:1BDCD4>0000
-00009:1BDCD6>0000
-00008:1B570C:8007:sof :
-00007:1BDCD6>0000
-00006:1BDCD8>0000
-00005:000000:00F8: : ;????
-00004:000002:0000:oe :
-00003:1BDCD8>0000
-00002:1BDCD4>2000
-00001:1BDCD6>0000
00000:000010:0039:r’•9':
00001:000012:9E08:r’••’:
The first column is for the cycle index. Negative indexes are cycles that occurred
before the breakpoint conditions we specified were met. Positive indexes occurred after
the breakpoint conditions were met. As you will see in the next example, you can tell
Xtrap what percentage (0..99) of the trace buffer you want reserved for cycles that
occur after the breakpoint conditions have been met. Normally you’ll be interested in
recording cycles before the breakpoint conditions are met so you can look backwards
and see how you got into the state you’ve defined, but the ability to look forwards from
that point comes in handy, too.
The second column is the value of the address bus for that cycle. Notice that for
cycle 0 the address bus is $000010, the illegal instruction vector. Once Xtrap saw this
value on the address bus it stopped recording cycles into the trace buffer (because we
asked it to record cycles until we got an access to the illegal instruction vector) and
generated a non-maskable interrupt to put us in MacsBug. By definition, cycle 0 is
always the cycle within the trace buffer (it’s a cyclical buffer) than meets the
breakpoint conditions that we’ve defined.
The third column is the value of the data bus for that cycle. The “>” and “<“ that
you see around the data bus value in some cycles means that the value at disassembly
time at that address is different than the value at trace record time at that address.
The fourth column is the cycle type:
blank = opcode cycle
oe = opcode extension cycle
sof = spurious opcode fetch cycle
w’xx’ = data write cycle, ‘xx’ is the value written
r’xx’ = data read cycle, ‘xx’ is the value read
The fifth column is the symbolic address column. Xtrap supports all
MacsBug-style symbols and, in addition, allows you to add your own symbols if you want
(more on this later).
The sixth column is the disassembly column.
The “????” at cycle -5 is the instruction that caused the illegal instruction
exception. How did we get there? Well, if you look at cycle -39 you see that there is a
Jsr to BugProc. The first thing BugProc does is save registers D5-D3 (the reason it is
written this way instead of D3-D5 is because when Xtrap disassembles a Movem
instruction it displays the registers in the order that they are pushed or popped --
this is useful for determining the registers’ values by looking at the corresponding data
write or data read cycles). BugProc then calls TrashRegs at cycle -33. Cycles -32 to
-27 are the data write cycles corresponding to the Movem.L D5-D3,-(SP) at cycle
-37. They occur here, instead of immediately after the Movem instruction, because of
the 68000’s pipelining.
Okay, now we’re getting close to the bug in this example code. Notice when
TrashRegs returns to BugProc that BugProc only restores registers D3 and D5 (and not
D4). That means it’s popping one less register than it pushed -- a sure way to end up
with a random location for the PC when the Rts instruction is executed. Looking in the
source you will see that you need to replace “D3/D5” with “D3-D5” to fix this bug.
Pretty cool, huh? For comparison with the Xtrap output, here’s the original
source code:
TrashRegs PROC
Moveq #3,D3
Moveq #4,D4
Moveq #5,D5
Rts
DC.B $80,’TrashRegs’
DC.W $0000
ENDP
BugProc PROC
Movem.L D3-D5,-(SP)
Bsr.S TrashRegs
Movem.L (SP)+,D3/D5
Rts
DC.B $80,’BugProc’
DC.W $0000
ENDP
Installation
Currently, Xtrap only works on a Mac SE (although a Mac II class machine
version is in the works). It comes with two pieces of hardware: one is a circuit board
that goes in the SE’s internal slot and the other is a 5" x 6" x 1" external control panel
that hooks onto the internal board via a 5' cable. The control panel has 5 buttons and 15
LEDs:
The manual gives two sets of installation instructions; one for people who are
familiar with installing Mac SE boards and a more detailed one for those who need a
little help with removing the Mac SE’s case and motherboard. The complete installation
takes about ten minutes.
You communicate with Xtrap (i.e. define breakpoints and get disassemblies of the
trace buffer) through MacsBug dcmds (TMON Pro support is planned and may be
available by the time you read this). To install the dcmds you paste the provided
resources into the Debugger Prefs file in your System Folder and reboot. They will be
loaded automatically the next time MacsBug installs itself.
Accessing Memory Location Zero
What follows is a complete example debug session with Xtrap that illustrates how
you would check if your program is reading or writing memory location zero (which is
not altogether illegal, but certainly is not very good programming practice).
Interestingly enough, both MPW Shell and Finder do this. I discovered this within five
minutes of hooking up Xtrap for the first time.
(Note: Xtrap is far more powerful than the Mr. Bus Error INIT in terms of
checking for location zero access. Mr. Bus Error (which stuffs $00F0F0F1 into
location zero) only catches dereferenced NIL pointer errors; it won’t tell you if you are
reading a byte from location zero (NIL PString pointer, for instance), nor will it tell
you if you are writing a byte, word or long to location zero.)
Let’s say you’ve installed the Xtrap hardware and software and have launched
MPW Shell (version 3.0). The first thing you do is press the programmer’s switch (or
the NMI button on the Xtrap control panel; they are equivalent) to get into MacsBug.
You can define up to four separate breakpoint conditions. Each breakpoint has an
address value, an address mask, a data value, a data mask and a cycle type. You can
specify things like: any access to a certain address (read access, write access, or