Where would we be without our venerable friend MacsBug? Those long debugging
sessions, with soda cans piling up, would be so lonely. Like a trusted buddy, only a key
press away, MacsBug has helped us solve the toughest problems and has taken us into
the very core of the Macintosh.
Yet now the core has changed. The Macintosh has transmuted into a RISC powerhouse,
and its new runtime environment is a foreign place to the old MacsBug. But instead of
leaving our friend in the past, Apple is developing a next-generation MacsBug. The
next MacsBug, version 6.5, supports PowerPC debugging with the same commands that
you already know. An early release of the new MacsBug is provided on this issue's CD.
A QUICK LOOK
When we're confronted with a MacsBug display that heralds the beginning of a new
debugging challenge, our first questions are "Where are we?" and "How did we get
here?" MacsBug has always provided tools and information to help us quickly answer
these questions. The stack crawl commands, for example, show not only what code
you're executing but also how you got there. On a Power Macintosh, however, the old
MacsBug often failed at tasks like the stack crawl. The PowerPC architecture changes
fundamental structures -- such as stack frame formats -- and introduces new hurdles
like mixed-mode switches and native code. The key goal of the new MacsBug is to
restore the functionality you need in order to debug on a Power Macintosh.
The new MacsBug adds many features to satisfy this goal. It lets you disassemble,
trace, and step through PowerPC code. You can set breakpoints in PowerPC code, and
easily find out what code fragment you've interrupted and what native symbol is
closest. And you can display a stack crawl that includes both PowerPC and 680x0 stack
frames. Let's take a closer look at these and other new features.
DISASSEMBLING POWERPC CODE
The new MacsBug will disassemble both PowerPC and 680x0 code. Some commands are
now sensitive to which type of code is executing. The td (total display) command will
show the PowerPC register set during execution of native code, and the 680x0
emulated registers during execution of 680x0 code. When used without an address, the
il and ip commands will disassemble the code currently being executed, whether
PowerPC or 680x0; however, when an address is specified with il and ip, MacsBug
will disassemble 680x0 code at the specified address.
We've introduced a few new commands to force disassembly of PowerPC native code.
They include the following:
To demonstrate, we'll set a native breakpoint in the Memory Manager with brp
__SetHandleSize. After we type g and wait for a second, MacsBug interrupts with
this display:
PowerPC breakpoint at 000A06C4 __SetHandleSize
We type the il command and see the following (notice the familiar breakpoint bullet
and the asterisk showing the current program counter location):
Disassembling PowerPC code from 000A06C4
__SetHandleSize
+00000 000A06C4 **mflr r0
+00004 000A06C8 stmw r26,-0x0018(SP)
+00008 000A06CC stw r0,0x0008(SP)
+0000C 000A06D0 stwu SP,-0x0170(SP)
+00010 000A06D4 lwz r30,0x0000(RTOC)
+00014 000A06D8 addic r7,SP,72
+00018 000A06DC lwz r26,0x0000(r30)
+0001C 000A06E0 ori r31,r4,0x0000
+00020 000A06E4 stw r7,0x0000(r30)
+00024 000A06E8 ori r29,r5,0x0000
+00028 000A06EC lwz r3,0x0004(RTOC)
+0002C 000A06F0 bl __HSetStateQ+013C
+00030 000A06F4 lwz RTOC,0x0014(SP)
+00034 000A06F8 ori r28,r3,0x0000
+00038 000A06FC addic r3,SP,72
From here we can display any PowerPC register, step or trace through the code, or ask
for our location using the improved wh command. The wh command now lists which
code fragment contains the address, using the code fragment export symbols to display
the nearest earlier symbol. In this example, we interrupted at __SetHandleSize in the
MemoryMgr code fragment, so wwh produces this:
Address 000A06C4 is in the System heap at
00002800 at __SetHandleSize
This address is within the code fragment
named "MemoryMgr".
It is 000021D4 bytes into this heap block:
Start Length Tag Mstr Ptr Lock
* 0009E4F0 00009050+04 R 00002BF0 L
CRAWLING AROUND TOGETHER
MacsBug version 6.5 distinguishes between PowerPC and 680x0 stack frames but will
display them as a unified stack crawl. This makes it very easy to determine where you
are and where you've been. Since the PowerPC version of the Mac OS still contains a
substantial amount of 680x0 code, you'll often see references to 680x0 callers in the
stack crawl. Otherwise, expect to see the nearest earlier code fragment symbol to each
caller. A sample stack crawl, displayed with the sc command, would look like this:
Frame Caller ISA 01D87FB2 00013CA0 PPC 'MyApp'+1A0 01D87F4A 00043050 PPC 'MyApp'+2F450 01D87EF0 4085FF06 68K ComponentDispatch+26 01D87EC8 4085FFE6 68K ComponentDispatch+106 01D87E50 00063144 PPC 'NativeComponent'+40
Here you can see that we're executing a native application with the exported main
symbol MyApp. The application calls a subroutine at MyApp+1A0, leaving the first
stack frame that we see here. Then at MyApp+2F450 the subroutine appears to call
the 680x0-based Component Manager. We assume this because the next two stack
frames are marked "68K" and appear within the ComponentDispatch code. The
Component Manager then calls native code with the symbol NativeComponent. The last
frame is generated when NativeComponent calls a subroutine.
EVEN MORE NEW FEATURES
Besides support for native Power Macintosh debugging, the new MacsBug adds other
exciting new features, including:
We once used ResEdit to construct a single MacsBug preferences file with all our
favorite dcmds and templates. Those days are over: the new MacsBug version will load
up to 32 preferences files that you provide. And if you haven't discarded the ROM list
files provided with MPW, you can build them and use the resulting ROM map files with
the new MacsBug. Put the map files in the new MacsBug preferences folder to use the
map's symbol information. When disassembling or displaying addresses in the ROM,
MacsBug will then display better symbols.
The improved dcmd format adds new action calls and an expanded parameter block
structure, which provides full access to the PowerPC register set and machine state.
Although this doesn't give you special support for developing PowerPC-native dcmds,
you now have access to valuable internal state information. With this new information,
your dcmds can do things that were previously reserved for Apple dcmds, such as tdp
(total dump PowerPC), which was introduced in the article "Debugging on PowerPC"
in develop Issue 17. This dcmd, among others from Apple, has intimate knowledge of
how the PowerPC system software works. With the new dcmd format, this intimate
knowledge is no longer necessary since MacsBug provides access to everything you'll
need.
The new dcmd format has been designed with maximum flexibility in mind. Your dcmds
can check at run time for the availability of MacsBug features. When new callbacks are
defined, you can check whether MacsBug supports the calls, rather than being tied to a
specific MacsBug version.
On 68040-based Macintosh computers, MacsBug will perform most tasks much
faster, and with an important side effect. The new MacsBug doesn't flush the 68040
processor cache nearly as often, greatly improving performance for most commands.
The key side effect is for bugs related to cache flushing: in the past, MacsBug would
flush the cache frequently enough to make these bugs hard to reproduce when you're
stepping or using breakpoints; the new MacsBug, with its selective flushing, should
allow you to more readily reproduce this type of problem.
IT'S LOG, LOG, LOG!
Here at Apple, bugs are usually found by test engineers using automated scripts and
manual testing. When they find a bug in our code, we're rarely nearby to analyze it
immediately. Therefore, they collect key information so that we can later reproduce
the problem. One useful piece of information they collect is called a standard log.
The standard log is a sequence of MacsBug commands that are run after a crash or
interrupt -- for example, a register display and stack crawl. These commands are
logged in a text file, and the result is copied into a report that describes the problem.
Having this information in the problem report saves significant time and sometimes
provides enough detail to resolve the problem immediately. MacsBug version 6.5
makes this log useful on the Power Macintosh. Its improved stack crawl, native
disassembly, and PowerPC register display provide key information for later analysis.
We recommend that you incorporate a standard log into your testing process; you'll
find ours included as the StdLog macro.
DON'T HESITATE
You can read the release notes provided on the CD for detailed descriptions of these and
other improvements. We hope you'll install the new version of MacsBug without delay!
DAVE EVANS denies rumors that he modeled for the Mac OS logo. Although he works
in the Mac OS team at Apple and does perpetually smile -- and his favorite color is
blue -- Dave could never sit still long enough for the pose. You're more likely to spot
him racing off in his hunter green Jeep Sahara. He'll probably be late, after fitting too
many activities into his day, and he'll certainly be en route to some new adventure.
JIM MURPHY (AppleLink MURPH, Internet murph@apple.com) dislikes one thing
more than the Pittsburgh Penguins hockey club without superstar center Mario
Lemieux, and that's a Macintosh without MacsBug. When he's not dodging a tedious
meeting at Apple, blearily staring at a logic analyzer, or hacking the Mac OS boot
process, he can be found plying the backroads of the Santa Cruz mountains in his
trusty Miata.
Thanks to Brian Bechtel, Dave Lyons, and Greg Robbins for reviewing this column.