TweetFollow Us on Twitter

Debugging PPC
Volume Number:10
Issue Number:8
Column Tag:Powering Up

Debugging

A slight detour into the subterranean areas of the PowerMac

By Richard Clark, General Magic & Jordan Mattson, Apple

Since January, we have been demonstrating that programming a Power Macintosh is very similar to programming a 68K-based Macintosh. This month we’ll show you that debugging on a Power Macintosh is quite similar to debugging on a 68K Macintosh, but with a few changes due to Mixed Mode and the new runtime architecture. (Astute readers might notice that we promised to talk about Human Interface programming this month. We’ve had to take a slight detour away from this plan, due to technical problems with our Human Interface demo code and a new job, but we’ll be back on track next month.)

We’ll begin by examining the available tools, then review the most common new problems a Power Macintosh programmer faces.

Choose Your Tool

We’ll begin with some good news - debugging an emulated application on the Power Macintosh is the same as debugging that application on a 68K Macintosh. You can use MacsBug, SADE, Jasik’s “The Debugger,” TMON, the THINK C debugger, and anything else you use normally. In fact, MacsBug just thinks it’s running on a 68020.

However, since you’re reading this column you probably want to debug a PowerPC application on your Power Macintosh. If you like using source-code debuggers, you’ll need to use a different set of tools: either Apple’s “Macintosh Debugger for PowerPC”, or Metrowerks’ “MW Debug.” Three tools support assembly-level debugging on PowerPC: Apple’s “Macintosh Debugger”, Jasik’s “The Debugger”, and MacsBug.

Looking At The New Debuggers

The new Power Macintosh source-level debuggers come in two parts - the debugger application, and a low-level “nub” which does most of the work of handling breakpoints and reading/writing memory. (Apple supplies the nubs for both its own debugger and the Metrowerks debugger.) You could think of the nub as a version of Macsbug which depends on an application to provide the interface.

Like Macsbug, the nub used with Apple’s “Macintosh Debugger” installs itself at the lowest level of the operating system and completely takes over the machine when active. (The nub actually disables interrupts while doing its work.) Since the machine is completely frozen when the nub has control, Apple’s debugger requires two machines: a Power Macintosh with the nub and the program being tested, and a 68K Macintosh or Power Macintosh running the debugging application. These two machines are connected by a serial cable which carries commands and data to the nub, and data back from the nub.

The two-machine mode provides some real advantages. If something happens to the machine running the debugging application, you can restart it and continue as if nothing happened. Also, using two machines for debugging keeps the user interface that you’re testing separate from the interface on the test tools. (Anybody’s who’s tried to track down redrawing problems with a single-machine source level debugger can appreciate that!)

Metrowerks’ debugger uses a different version of Apple’s nub which doesn’t take over the machine completely and which doesn’t use the serial port directly. This version of the nub communicates with the debugging application through the Program-to-Program Communication toolbox, which allows the nub and the application to be on the same machine or connected via the Macintosh’s built-in networking.

This nub has both advantages and disadvantages. The first disadvantage: since the nub is built on the PPC toolbox, much of the system has to be functioning correctly for the nub to communicate with the debugging application, so a crash could also kill your debugging tools. Disadvantage 2: the Process Manager gets involved when you send a message via the PPC toolbox, which limits the top speed of the connection. The final disadvantage is this: since this nub isn’t installed automatically as an extension, so you have remember to start it running before you run the debugger application, or place it in your startup folder. In this nub’s favor, you can debug with one machine, which saves money, desk space, and keeps you from trying to remember which mouse does which!

Both of these debuggers work with .SYM/.xSYM files - known generically as “symbol files” - which are generated by the PowerPC linker. (The only difference between a .SYM file and an .xSYM file is the name - Apple’s engineers adopted the convention of ending PowerPC symbol files with .xSYM so that developers who build “fat binaries” could have symbol files for both the PowerPC and 68K code at the same time.) Symbol files match the start of each line of source code to the corresponding location in the compiled program. Symbol files also list each of the variables in the application, and where each variable is located. Using this information, debuggers can determine which line of source the current program counter points to, let you set breakpoints at the beginning of a current line (and single-step through the source code), and examine and modify variables.

Without a symbol file, the debuggers can only show you machine-language instructions, and let you modify locations in memory directly.

Teaching An Old Debugger New Tricks

The other two PowerPC debuggers - MacsBug and Steve Jasik’s “The Debugger” are 68K debuggers with some additional commands for the Power Macintosh.

MacsBug is still a 68K debugger at its heart: it is completely emulated and all of the register displays, breakpoints, stack crawls, and code displays operate as if running on a 68020. The largest single change to MacsBug is that it now knows about the “Modern” Memory Manager introduced with the Power Macintosh. The new memory manager uses different algorithms and different structures internally than the “classic” memory manager; this causes older versions of MacsBug to claim that the heap is corrupted when using the new memory manager. (MacsBug 6.5 contains the changes to work with the new memory manager.)

If MacsBug is still a 68K debugger, how can you debug PowerPC code with it? Apple has released an unsupported set of debugger extensions (known as dcmds, pronounced dee-commands) for PowerPC debugging. These commands include a disassembler, register display, stack crawl, and breakpoint setter for PowerPC code. (Setting breakpoints requires that you have one of the debugging nubs installed, so the breakpoint will be handled in the source-level debugger.)

The new MacsBug and the dcmds were shipped with the March, 1994 issue of develop magazine (issue 17), on the CD-ROM which accompanied the magazine. The dcmds don’t appear to be available anywhere else. However, the new MacsBug is available on the Internet via anonymous ftp. Connect to ftp.apple.com, look in the /dts/mac/tools/macsbug directory, and download macsbug-6-5d6.hqx. (If there’s a later version in the directory, take that instead.)

On the other hand, Steve Jasik’s “The Debugger” has been completely revised to include PowerPC debugging support. It supports source-level and assembly-level debugging, including breakpoints, stack traces, and disassembling PowerPC code. The Debugger isn’t a complete solution for PowerPC debugging yet, since single-stepping through source code, A-Trap breaks, and the “step spy” command don’t work for PowerPC code. (They should be working by the time you read this column.)

One interesting feature of The Debugger is the way it annotates PowerPC disassemblies. Every line is labeled with the name of the instruction, which helps if you’re learning PowerPC assembly language.


/* 1 */
;#  void MainLoop()
;#  {
;#    EventRecordtheEvent;
;#  
                     .MainLoop
 0:mfsprr0,LR  ; Move From Special Purpose Reg
 4:stmw r28,-16(SP); Store Multiple Word
 8:stw  r0,8(SP) ; Store Word
 C:stwu SP,-96(SP) ; Store Word with Update
 10:    lar29,gDone(RTOC) ; Load Address
;#    while (!gDone) {
 14:    jplad_2  ; Branch
;#      WaitNextEvent(everyEvent, &theEvent, 1L, NULL);
;#  
;#      // The external code didn't handle the event, so we will
 18:  lad_1 li r3,-1 ; Load Immed
 1C:    lar4,theEvent(SP) ; Load Address
 20:    lir5,1 ; Load Immed
 24:    lir6,0 ; Load Immed
 28:    bl.WaitNextEvent  ; Branch, set LR
 2C:    lwz RTOC,20(SP) ; Load Word and Zero

The Debugger is completely self-contained, i.e. it doesn’t require a separate nub, and requires a symbol file to enable its source-level debugging abilities.

Are There Any New Bugs On The Power Mac?

The first thing to remember when debugging a Power Macintosh program is that you’re still using a Macintosh. The same toolbox managers are present on the Power Macintosh, and much of the Toolbox and Operating System code is emulated. This means that most crashes into MacsBug (or another debugger) happen for the same reasons as on a 68K Macintosh: the program either passed a bad value to the toolbox, or corrupted a block in the heap, or grew the stack into the heap, and so on.

Still, the Power Macintosh can crash in some unique ways, due to the presence of Mixed Mode and the limited memory protection afforded by the new runtime architecture.

Using Mixed Mode incorrectly can cause crashes into 68K code. The most common problem in all newly ported PowerPC code comes from forgetting to pass a Universal Procedure Pointer:


/* 2 */
// Oops! We’re passing the address of a procedure directly
partCode = TrackControl(myControl, startPoint, myActionProc);

This causes a crash into the debugger with an “illegal instruction error” on the 68K side. You can diagnose this error in several different ways:

• Use the PowerPC disassembler (or the dis dcmd in MacsBug) to look at the address where the crash occurred. If you see reasonable PowerPC instructions, you probably forgot to pass a Universal Procedure Pointer.

• Think about what your code is doing. Did you click on a control, is a dialog being drawn, or is an Apple event being handled? These all involve callback procedures, so you may have forgotten a UPP.

• Set a break on the Mixed Mode A-trap. (This only works in MacsBug.) Using the ATVB (A-Trap Vector Break) dcmd, you can set a break on _MixedModeDispatch (0xAAFE). (The normal A-Trap Break command won’t work because the Power Macintosh doesn’t run all traps through the same trap dispatcher as the 68K Macintosh.) This lets you look at every mixed mode switch

The Power Macintosh’s limited memory protection can uncover bugs you didn’t know you had. If Virtual Memory is turned on, your code is loaded into a read-only area, so attempting to overwrite your code will result in an Access Violation. Even if VM is off, attempts to write to location 0 usually trigger access violations, as do all attempts to overwrite the ROM.

Data structure alignment presents some of the nastiest bugs. Remember that the PowerPC prefers to have all 2-byte values begin on even addresses, and 4-byte values on addresses which are multiples of 4. The compiler will help maintain this alignment in data structures by inserting “padding” in the appropriate places. Naturally, if you weren’t expecting this padding, your program might behave in unexpected ways.

Diagnosing this bug is easy: try re-compiling your code with the “use 68K alignment” option to your compiler, and see if the problem goes away. If it does, you probably forgot to install alignment directives on one or more of your structures.

Next Month In Powering Up

Next month, we’ll return with an “all-code” column exploring some Human Interface techniques you can apply on the Power Macintosh, and talk about a few nifty PowerPC hacks.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Six fantastic ways to spend National Vid...
As if anyone needed an excuse to play games today, I am about to give you one: it is National Video Games Day. A day for us to play games, like we no doubt do every day. Let’s not look a gift horse in the mouth. Instead, feast your eyes on this... | Read more »
Old School RuneScape players turn out in...
The sheer leap in technological advancements in our lifetime has been mind-blowing. We went from Commodore 64s to VR glasses in what feels like a heartbeat, but more importantly, the internet. It can be a dark mess, but it also brought hundreds of... | Read more »
Today's Best Mobile Game Discounts...
Every day, we pick out a curated list of the best mobile discounts on the App Store and post them here. This list won't be comprehensive, but it every game on it is recommended. Feel free to check out the coverage we did on them in the links below... | Read more »
Nintendo and The Pokémon Company's...
Unless you have been living under a rock, you know that Nintendo has been locked in an epic battle with Pocketpair, creator of the obvious Pokémon rip-off Palworld. Nintendo often resorts to legal retaliation at the drop of a hat, but it seems this... | Read more »
Apple exclusive mobile games don’t make...
If you are a gamer on phones, no doubt you have been as distressed as I am on one huge sticking point: exclusivity. For years, Xbox and PlayStation have done battle, and before this was the Sega Genesis and the Nintendo NES. On console, it makes... | Read more »
Regionally exclusive events make no sens...
Last week, over on our sister site AppSpy, I babbled excitedly about the Pokémon GO Safari Days event. You can get nine Eevees with an explorer hat per day. Or, can you? Specifically, you, reader. Do you have the time or funds to possibly fly for... | Read more »
As Jon Bellamy defends his choice to can...
Back in March, Jagex announced the appointment of a new CEO, Jon Bellamy. Mr Bellamy then decided to almost immediately paint a huge target on his back by cancelling the Runescapes Pride event. This led to widespread condemnation about his perceived... | Read more »
Marvel Contest of Champions adds two mor...
When I saw the latest two Marvel Contest of Champions characters, I scoffed. Mr Knight and Silver Samurai, thought I, they are running out of good choices. Then I realised no, I was being far too cynical. This is one of the things that games do best... | Read more »
Grass is green, and water is wet: Pokémo...
It must be a day that ends in Y, because Pokémon Trading Card Game Pocket has kicked off its Zoroark Drop Event. Here you can get a promo version of another card, and look forward to the next Wonder Pick Event and the next Mass Outbreak that will be... | Read more »
Enter the Gungeon review
It took me a minute to get around to reviewing this game for a couple of very good reasons. The first is that Enter the Gungeon's style of roguelike bullet-hell action is teetering on the edge of being straight-up malicious, which made getting... | Read more »

Price Scanner via MacPrices.net

Take $150 off every Apple 11-inch M3 iPad Air
Amazon is offering a $150 discount on 11-inch M3 WiFi iPad Airs right now. Shipping is free: – 11″ 128GB M3 WiFi iPad Air: $449, $150 off – 11″ 256GB M3 WiFi iPad Air: $549, $150 off – 11″ 512GB M3... Read more
Apple iPad minis back on sale for $100 off MS...
Amazon is offering $100 discounts (up to 20% off) on Apple’s newest 2024 WiFi iPad minis, each with free shipping. These are the lowest prices available for new minis among the Apple retailers we... Read more
Apple’s 16-inch M4 Max MacBook Pros are on sa...
Amazon has 16-inch M4 Max MacBook Pros (Silver and Black colors) on sale for up to $410 off Apple’s MSRP right now. Shipping is free. Be sure to select Amazon as the seller, rather than a third-party... Read more
Red Pocket Mobile is offering a $150 rebate o...
Red Pocket Mobile has new Apple iPhone 17’s on sale for $150 off MSRP when you switch and open up a new line of service. Red Pocket Mobile is a nationwide MVNO using all the major wireless carrier... Read more
Switch to Verizon, and get any iPhone 16 for...
With yesterday’s introduction of the new iPhone 17 models, Verizon responded by running “on us” promos across much of the iPhone 16 lineup: iPhone 16 and 16 Plus show as $0/mo for 36 months with bill... Read more
Here is a summary of the new features in Appl...
Apple’s September 2025 event introduced major updates across its most popular product lines, focusing on health, performance, and design breakthroughs. The AirPods Pro 3 now feature best-in-class... Read more
Apple’s Smartphone Lineup Could Use A Touch o...
COMMENTARY – Whatever happened to the old adage, “less is more”? Apple’s smartphone lineup. — which is due for its annual refresh either this month or next (possibly at an Apple Event on September 9... Read more
Take $50 off every 11th-generation A16 WiFi i...
Amazon has Apple’s 11th-generation A16 WiFi iPads in stock on sale for $50 off MSRP right now. Shipping is free: – 11″ 11th-generation 128GB WiFi iPads: $299 $50 off MSRP – 11″ 11th-generation 256GB... Read more
Sunday Sale: 14-inch M4 MacBook Pros for up t...
Don’t pay full price! Amazon has Apple’s 14-inch M4 MacBook Pros (Silver and Black colors) on sale for up to $220 off MSRP right now. Shipping is free. Be sure to select Amazon as the seller, rather... Read more
Mac mini with M4 Pro CPU back on sale for $12...
B&H Photo has Apple’s Mac mini with the M4 Pro CPU back on sale for $1259, $140 off MSRP. B&H offers free 1-2 day shipping to most US addresses: – Mac mini M4 Pro CPU (24GB/512GB): $1259, $... Read more

Jobs Board

All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.