TweetFollow Us on Twitter

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


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, 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;
 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

Markly 1.5.3 - Create measurement and de...
Markly is a measurement and design-spec plugin/extension for Photoshop and Sketch. It is made for modern Web designers and app front-end developers. You can add specification marks simply by clicking... Read more
Suitcase Fusion 6 17.3.0 - Font manageme...
Suitcase Fusion 6 is the creative professional's font manager. Every professional font manager should deliver the basics: spectacular previews, powerful search tools, and efficient font organization... Read more
Nisus Writer Pro 2.1.2 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
calibre 2.40.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Vivaldi - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more
Typinator 6.7 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more

Balloony Land offers a fresh twist on th...
Balloony Land by Palringo offers a fresh twist on the match three genre and is out now on iOS and Android. First-off, you'll be popping balloons instead of crushing candy and the balloons will float up and fill the empty spaces instead of dropping... | Read more »
Graphic - vector illustration and design...
Graphic - vector illustration and design 1.0 Device: iOS iPhone Category: Productivity Price: $2.99, Version: 1.0 (iTunes) Description: Autodesk Graphic is a powerful full-featured vector drawing and illustration application right in... | Read more »
Sago Mini Babies (Education)
Sago Mini Babies 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Introducing the Sago Mini babies. Boys and girls love caring for these adorable characters. Feed Robin her favorite mush... | Read more »
PAUSE - Relaxation at your fingertip (H...
PAUSE - Relaxation at your fingertip 1.1 Device: iOS iPhone Category: Healthcare & Fitness Price: $1.99, Version: 1.1 (iTunes) Description: | Read more »
Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
Dub Dash (Games)
Dub Dash 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: ARE YOU READY FOR THE ULTIMATE CHALLENGE? UNIQUE SYMBIOSIS OF MUSIC AND GRAPHICS | Read more »
Leave Me Alone (Games)
Leave Me Alone 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: 33% off launch sale!!! Somewhere between the 1980s and 1990s there exists a world that never was. A world of skatepunks,... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Chesh (Games)
Chesh 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It’s like chess, only not at all. ***40% off for a limited time to celebrate our launch!*** Chesh is a game of skill, strategy, luck,... | Read more »

Price Scanner via

TP-LINK Next-Gen Routers Support a Large Numb...
TP-LINK, specialists in consumer and business networking products, have announced the availability of Archer C2600, the company’s next-generation router featuring wireless AC, multi-user MIMO, and 4-... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
Apple refurbished 2014 13-inch Retina MacBook...
Apple has Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and shipping is free... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... Read more
Is The iPad Pro Really A Serious Laptop Repla...
Probably not, at least for productive professionals and other power users. Steve Jobs declared that we’d entered the “post-PC Era” with the advent of the original iPad in 2010, a phrase we don’t hear... Read more

Jobs Board

*Apple* Desktop Analyst - KDS Staffing (Unit...
…work with some of the brightest engineers. Job Description Title: Apple Desktop AnalystPosition Type: Full-time PermanentLocation: White Plains, NYHot Points:Depth of Read more
*Apple* Retail Online, Customer Experience R...
**Job Summary** Apple Retail's Online Store sells Apple products to customers around the world. In addition to selling Apple products with unique services such Read more
Frameworks Engineer, *Apple* Watch - Apple...
**Job Summary** Join the team that is shaping the future of software development for Apple Watch! As a software engineer on the Apple Watch Frameworks team you will Read more
Senior Manager, Global Direct Marketing *App...
**Job Summary** Apple Retail is looking for an experienced Direct Marketing Leader to join its Marketing team. This position will take a leadership role in creating Read more
*Apple* Online Store Expansion - Apple (Unit...
**Job Summary** The Online Apple Store is seeking a person to lead its expansion into new countries. Based in Cupertino, CA, this person will develop and maintain an Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.