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

FontExplorer X Pro 7.1.3 - Font manageme...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
DiskCatalogMaker 8.2.5 - Catalog your di...
DiskCatalogMaker is a simple disk management tool which catalogs disks. Simple, light-weight, and fast Finder-like intuitive look and feel Super-fast search algorithm Can compress catalog data for... Read more
Skim 1.5.12 - PDF reader and note-taker...
Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. Skim includes many features and has a... Read more
rekordbox 6.1.0.0030 - Professional DJ m...
rekordbox is the best way of preparing and managing your tracks, be it at home, in the studio, or even on the plane! It allows you to import music from other music-management software using the... Read more
iExplorer 4.4.0 - View and transfer file...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
OmniGraffle 7.17.5 - Create diagrams, fl...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
Apple Configurator 2.13.1 - Configure an...
Apple Configurator makes it easy to deploy iPad, iPhone, iPod touch, and Apple TV devices in your school or business. Use Apple Configurator to quickly configure large numbers of devices connected to... Read more
OmniGraffle Pro 7.17.5 - Create diagrams...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
FoldersSynchronizer 5.1.6 - Synchronize...
FoldersSynchronizer is a popular and useful utility that synchronizes and backs-up files, folders, disks and boot disks. On each session you can apply special options like Timers, Multiple Folders,... Read more
Adobe After Effects 17.1.4 - Create prof...
After Effects is available as part of Adobe Creative Cloud for $52.99/month (or $20.99/month for a single app license). The new, more connected After Effects can make the impossible possible. Get... Read more

Latest Forum Discussions

See All

Infinity Mechs is an upcoming idle game...
Indie developer SkullStar studio has announced an upcoming idle mech game called Infinity Mechs. It draws inspiration from the mobile game Iron Saga and has been officially licensed by Game Duchy. It's set to launch for both iOS and Android on... | Read more »
PUBG Mobile Lite's latest update se...
PUBG Mobile Lite, the streamlined version of the popular battle royale that's designed to work on less powerful devices, sees the return of a popular game variant today, Survive Till Dawn mode. It arrives as part of the 0.19.0 content update. [... | Read more »
Matchy Catch, Jyamma Games’ new hyper-ca...
Matchy Catch is a new hyper-casual puzzler from Jyamma Games, the Italian studio behind the Pong-inspired puzzle-adventure Hi-Ball Rush. It’s only the developer’s second game for iOS and Android devices, but it promises to be every bit as fun and... | Read more »
Among Us! Imposter Guide - How to be a s...
Among Us! continues to be getting a lot of play in these parts, and since our first guide we've learned a thing or two about the game. This is especially true regarding the imposter role, as its a relatively rare opportunity that we've now put... | Read more »
Paladin's Story is an upcoming fant...
Paladin's Story is an upcoming fantasy RPG with an off-kilter sense of humour that's heading for iOS and Android. It will officially launch for both on September 16th though the game is already available on Google Play in Early Access. [Read more... | Read more »
Among Us! Guide - Tips for the uninitiat...
| Read more »
A Pretty Odd Bunny is a stealth-platform...
A Pretty Odd Bunny is a stealth-platformer from two-man team AJ Ordaz and René Rivera. It follows the story of a red-eyed rabbit who is allergic to carrots and instead has a penchant for devouring pigs. It's available now for Android devices. [... | Read more »
Apple Arcade: Ranked - Top 25 [Updated 9...
In case you missed it, I am on a quest to rank every Apple Arcade game there is. [Read more] | Read more »
The 5 Best Mobile Games Like Tony Hawk...
Tony Hawk’s Pro Skater 1+2 dropped last week, meaning you can get remastered versions of two of the most iconic “sports” games ever made and experience some of the highest watermarks set in games of generations’ past. [Read more] | Read more »
Bouncing Box is a challenging platformer...
In platformers, we often spend a large amount of time mindless destroying boxes by jumping onto or into them, whatever makes them splinter apart. Bouncing Box from developer The K Brothers aims to give those poor destructible cubes a chance to be... | Read more »

Price Scanner via MacPrices.net

Price drop! Get a 44mm Apple Watch Series 5 G...
Amazon has dropped their price on the 44mm Apple Watch Series 5 GPS + Cellular by $100 to $429 shipped. That’s $100 off Apple’s original MSRP for this model. For the latest prices and sales, see our... Read more
Verizon offers $200 discount on new Apple Wat...
Verizon will take up to $200 off the purchase of a new GPS + Cellular Apple Watch Series 6 or Apple Watch SE with select trade-in and the purchase of a new iPhone with service. The fine print: “Get... Read more
Verizon offers $250 discount on new 8th gener...
Verizon will take up to $250 off the price of an 8th generation 2020 Apple Cellular iPad with select trade-ins and a new iPhone purchase. Plus get Apple News+ free for 6 months. The fine print: “Save... Read more
Apple’s Implementation Of COVID-19 Exposure...
NEWS: 09.18.20 – The latest effort by Apple to embed exposure notifications for COVID-19 contact tracing right into its mobile operating system has some iPhone users weary of being exposed to... Read more
Here’s how to get a 16″ MacBook Pro for $300...
B&H Photo has new 16″ MacBook Pros on sale today for $250-$300 off Apple’s MSRP, starting at $2099. Expedited shipping is free to many addresses in the US: – 2019 16″ 2.6GHz 6-Core MacBook Pro... Read more
Apple has Certified Refurbished 16″ MacBook P...
Apple has Certified Refurbished 2019 16″ MacBook Pros available for up to $420 off the cost of new models, starting at $2039. Each model features a new outer case, shipping is free, and an Apple 1-... Read more
Price drops! Apple reseller B&H drops App...
B&H Photo has dropped prices on Apple Watch Series 5 models by $50-$70 off Apple’s original MSRP. Shipping is free. These are the same Apple Watch models sold by Apple in their retail and online... Read more
Apple extends their 2020 Back-to-School promo...
As part of their Back to School promotion for 2020, Apple will include one free pair Apple AirPods (with charging case) with the purchase of a MacBook Air, MacBook Pro, iMac, iMac Pro (Mac Pro and... Read more
Apple 7.9″ iPad minis are on sale today for $...
Amazon has new 7.9″ 64GB WiFi iPad minis on sale today for $50 off Apple’s MSRP, each including free shipping. Prices start at $349. These are the same iPad minis sold by Apple in their retail and... Read more
Lowest price anywhere! New 16″ 6-core MacBook...
Expercom has the Silver 16″ 6-core MacBook Pro back on sale for a limited time for $2079 shipped. Their price is $320 off Apple’s MSRP for this model, and it’s the cheapest price currently available... Read more

Jobs Board

Platform - Workplace Eng - *Apple* Enterpri...
MORE ABOUT THIS JOB We are looking for an Apple Platform Engineer who will bring a unique engineering skill set, support, clarity, organization and above all else, Read more
*Apple* Certified Repair Technician - Utah S...
…selected candidate will work in the USU Campus Store Tech Department as an Apple Certified Repair Technician and floor associate. This position is for both summer Read more
Senior Data Engineer - *Apple* - Theorem, L...
Job Summary Apple is seeking an experienced, detail-minded data engineeringconsultant to join our worldwide business development and strategy team. If you are Read more
Desktop Support Technician - A+, *Apple* -...
Desktop Support Technician - A+, Apple **Ref No.:** 20-01604 **Location:** Miami, Florida **e** at http://www.excell.com/ **X** at http://www.excell.com/ **cell** at Read more
Tier 2 Technical Support Analyst - ( *Apple*...
…Analystiless than/strong>who will analyze and determine user software needs on all Apple devices (first support contact), Windows devices, and support printers in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.