TweetFollow Us on Twitter

Executing Code
Volume Number:10
Issue Number:4
Column Tag:Powering UP

Executing Code
On A Power Macintosh

PEF files are more than just object code; at last you get initialization routines and global data

By Richard Clark, Apple Computer, Inc.

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

This month’s Powering Up takes a different approach than previous columns - in the past, we told you about moving existing code to the Power Macintosh. Today, we’ll tell you some things about using the new capabilities of the Power Macintosh runtime to enhance new and existing applications.

The greatest advantages on the Power Macintosh come from its speed and a new runtime architecture. This architecture was designed from the ground up for operation on a RISC processor; in fact, most of the new runtime was derived from IBM’s runtime model for their RISC systems. The new runtime architecture supports:

• Executable code that may be stored anywhere (i.e. in ROM, in a resource, or in the data fork of a file)

• Executable code which may have its own static data (including global variables)

• Executable code which may export code and data, and which can import code and data automatically from other executables, and

• Register-based calling conventions which execute quickly and efficiently

The structure of executable code

On a Power Macintosh, all native code is packaged up as “fragments.” An application consists of one large fragment (stored in the data fork of the application file), with supporting resources such as windows and menus in the resource fork. Other kinds of PowerPC code, such as INITs and CDEVs, may be stored as fragments in a resource or in the data fork of the file. Finally, the ROMs on a Power Macintosh include fragments which implement parts of the System software.

To support such a wide range of uses, each fragment has some important common capabilities: each has its own static data, references to imported code or data, and pointers to functions and variables that it exports. Each fragment is stored in a “PEF container”, which holds code in the Preferred Executable Format (PEF). Each PEF container consists of three parts: a Data Segment, a Code Segment, and a Loader Segment. Each of these segments is used when loading a fragment into memory:

• The Code Segment holds the executable code. The system treats code as read only, and may load the code anywhere in memory. As a result, all branches in the code have to be either relative to the current location, or go through pointers.

• The Data Segment holds the static data for the code, and a special table called the “Table of Contents” or TOC. The TOC contains pointers to each global variable used by the program, as well as pointers to code which cannot be accessed through a PC-relative branch or which exist in other code fragments.

• The Loader Segment contains tables which list each import and export for the current fragment, and other information as required to load a fragment.

PEF containers always retain the same format no matter where they are stored.

When a fragment is first loaded, the Code and Data segments are copied into memory (where they become Code and Data sections.) If a fragment uses code or data from other fragments, the Code Fragment Manager (CFM) locates and loads the referenced fragments. The CFM then sets up the static data for each loaded fragment; this involves filling in pointers in the Table Of Contents, expanding initialized data values, and calling the fragment’s optional “initialization routine.” Once this is done, the CFM returns the fragment’s “main” address and a unique “connection ID.”

If you try to load an already loaded fragment, the code is not loaded twice, but a second copy of the data might be loaded. Fragments support three types of data sharing:

• Global data sharing uses only one data section no matter now many times the code is loaded.

• Per-context data sharing - the default setting - loads the code once, but allocates a different data section for each “context.” (A “context” is a name space associated with each application, so all of the fragments used by an application (and all of the fragments they use) fall into the same context.) This setting allows a fragment to treat each application which calls it as a separate entity.

• Per-load data sharing allocates a data section each time the fragment is loaded, even if multiple load requests come from the same context. You might use this feature to implement a “network communications” fragment where each time you load the fragment you get another connection to the network. Each connection would get its own copy of the static data.

The Fragment Loading API

Fragments are loaded through calls to the Code Fragment Manager, as documented in FragLoad.h. The FragLoad API consists of 7 calls for loading and unloading fragments, as well as looking up function and data pointers in a loaded fragment:

• GetDiskFragment is commonly used for loading “plug-in additions” - it takes an FSSpec for a file and loads the container contained in the data fork.

• GetMemFragment “prepares” a fragment that was loaded into memory without using the Code Fragment Manager.

• GetSharedLibrary locates an existing Shared Library on the disk and loads it. This call is normally used to get a connection ID for one of the standard shared libraries (such as the System software “InterfaceLib”) before looking up the address of an exported function.

• CloseConnection is used to unload a fragment. This function takes the Connection ID returned by one of the above calls, checks a reference count which is maintained by the CFM, and unloads the code and/or data sections for the given fragment.

• FindSymbol looks up a symbol (code or data pointer) by name given a string and a connection ID. If your application supports drop-in additions similar to HyperCard XCMDs, you could use this to look up the address of an optional function in an addition. As we will see later, this function plays a key role in linking 68K code to a PowerPC application.

• CountSymbols counts the total number of symbols exported from a fragment. Like FindSymbol, this call also requires a connection ID.

• GetIndSymbol can be used to index through all of the symbols exported from a fragment. It takes a connection ID and an index number, and returns the symbol’s name and address.

The API calls in action

We now know enough to start loading and executing code contained in a PEF container. The following code loads a fragment from the data fork of a file and prepares it for execution. (This code is part of “SimpleApp”, which is located on the MacTech source code disks or from the MacTech forums on line.)


/* 1 */
FSSpec  fileSpec;
ProcPtr mainAddr;
ConnectionIDconnID;
OSErr err;
Str255  errName;
err = GetDiskFragment ( &fileSpec, 0, 0, fileSpec.name,
 kLoadNewCopy, &mainAddr, (Ptr*)&gMain,
 errName);

That’s all there is to it - once this call is made, “mainAddr” contains a pointer into the fragment (usually the entry point for the code, though the fragment could put a pointer to some static data there if it wanted to export a table of procedure pointers, for example.) The returned connection ID can be used to look up other exports from the fragment, or to unload the fragment via a call to CloseConnection:

CloseConnection(&connID);

Loading a resource-based fragment is a little more difficult: it’s your responsibility to get the fragment into memory, then you have to ask the CFM to “prepare” the fragment for execution:


/* 2 */
FSSpec  fileSpec;
ProcPtr mainAddr;
ConnectionIDconnID;
short refNum;
Handle  codeResource;
OSErr err;
Str255  errName;

refNum = FSpOpenResFile(&fileSpec, fsCurPerm);
if (ResError() == noErr) {
  codeResource = Get1IndResource('PEF ', 1);
  if (codeResource != NULL) {
    DetachResource(codeResource );
    HLock(codeResource );
    // We have the code, but it's not ready to use yet
    // Ask the Code Fragment Manager to "prepare" the code for execution
    err = GetMemFragment (*codeResource , 0, fileSpec.name,
 kLoadNewCopy, &connID, (Ptr*)&mainAddr,
 errName);
  }
  CloseResFile(refNum);

In both of these cases, if the load fails, err will return an appropriate error code and errName will contain the name of the offending fragment.

Using global variables in fragments -
the Initialization routine

One of the more interesting aspects of fragments is how global variables are supported. Every fragment may have its own static data, including global variables, automatically, and this data can be initialized to set values by the Code Fragment Manager. Thus, if you wrote:

 static int x = 1234;
 static ProcPtr y = &z;

x would receive the value 1234 (stored in the container’s data segment), and y would receive the address of function “z”. (This is actually the address of a Transition Vector, as described in “How TOC switches occur” below, and is computed at load time.)

However, the CFM allows fragments to go beyond these simple initializations. Each fragment may designate optional “Initialization” and optional “Termination” routines which will be called when the fragment’s data section is being set up and torn down. The Initialization routine receives a pointer to a block of useful information, including a FSSpec for the fragment’s file, and can return an error value to stop the fragment from loading. (Otherwise, the Initialization routine must return noErr.) The termination routine takes no parameters and returns non values, and release memory, close files, and otherwise undo whatever the initialization routine did.

The initialization and termination routines could be used to implement fully self-initializing Macintosh managers, for instance, or C++ classes complete with their own constructors and destructors. In the sample application, the initialization routine is used to get the FSSpec for a drop-in addition file from within that file’s code. This allows the addition to access its own resources.


/* 3 */
OSErr OurInitRoutine (InitBlockPtr initBlkPtr)
{
 OSErr  err = noErr;
 short  refNum = -1;
 
 // Make sure this code is coming from the data fork of a file
 if (initBlkPtr->fragLocator.where == kOnDiskFlat) {
 refNum = FSpOpenResFile(
 initBlkPtr->fragLocator.u.onDisk.fileSpec,
 fsCurPerm);
 // and so on 

Next month in Powering Up

Next month’s column takes a look at the Power Macintosh calling conventions, and at how that affects debugging.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Google Chrome 59.0.3071.115 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
SoftRAID 5.6.1 - High-quality RAID manag...
SoftRAID allows you to create and manage disk arrays to increase performance and reliability. SoftRAID allows the user to create and manage RAID 4 and 5 volumes, RAID 1+0, and RAID 1 (Mirror) and... Read more
Suitcase Fusion 7 18.2.4 - Font manageme...
Suitcase Fusion 7 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
BetterTouchTool 2.25 - Customize Multi-T...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
WhiteCap 6.7.1 - Visual plug-in for iTun...
WhiteCap is a sleek and sophisticated music visualizer and screensaver that features futuristic, wireframe mesh visuals with dynamic backgrounds and colors. WhiteCap contains thousands of visual... Read more
DiskMaker X 6.0 rc5 - Make a bootable OS...
DiskMaker X (was Lion DiskMaker) helps you to build a bootable drive from the official OS X installer app (the one you download from the Mac App Store). It detects the OS X Install program with... Read more
Lyn 1.9 - Lightweight image browser and...
Lyn is a fast, lightweight image browser and viewer designed for photographers, graphic artists, and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it delivers... Read more
WhiteCap 6.7.1 - Visual plug-in for iTun...
WhiteCap is a sleek and sophisticated music visualizer and screensaver that features futuristic, wireframe mesh visuals with dynamic backgrounds and colors. WhiteCap contains thousands of visual... Read more
DiskMaker X 6.0 rc5 - Make a bootable OS...
DiskMaker X (was Lion DiskMaker) helps you to build a bootable drive from the official OS X installer app (the one you download from the Mac App Store). It detects the OS X Install program with... Read more
Lyn 1.9 - Lightweight image browser and...
Lyn is a fast, lightweight image browser and viewer designed for photographers, graphic artists, and Web designers. Featuring an extremely versatile and aesthetically pleasing interface, it delivers... Read more

Latest Forum Discussions

See All

This War of Mine gets a new ending and m...
This War of Mine just got a big new update, featuring free DLC that adds a new ending to the game, among other exciting changes. The update is celebrating the game's two-year release anniversary. Apart from the new ending, which will be quite... | Read more »
Summon eight new heroes in Fire Emblem H...
Nintendo keeps coming at us with Fire Emblem Heroes updates, and it doesn't look like that trend is stopping anytime soon. The folks behind the game have just announced the new War of the Clerics Voting Gauntlet, expected to start next Tuesday. [... | Read more »
The best deals on the App Store this wee...
iOS publishers are pulling out all the stops this week -- there's a huge number of seriously great games at discounted prices this week. Let's not waste any time and get right down to business. [Read more] | Read more »
The House of da Vinci (Games)
The House of da Vinci 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: Enter The House of Da Vinci, a new must-try 3D puzzle adventure game. Solve mechanical puzzles, discover hidden... | Read more »
Solve the disappearance of history’s gre...
Blue Brain Games invites you to indulge in an immersive hands-on 3D puzzle adventure in similar vein to The Room series, with its debut release The House of Da Vinci. Set during the historic period of the Italian Renaissance (when Leonardo himself... | Read more »
Age of Rivals (Games)
Age of Rivals 3.3 Device: iOS Universal Category: Games Price: $.99, Version: 3.3 (iTunes) Description: Deep civilization-building strategy in a fast-paced card game! | Read more »
Panthera Frontier (Games)
Panthera Frontier 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Angry Birds Evolution beginner's gu...
Angry Birds changes things up a fair bit in its latest iteration, Angry Birds Evolution. The familiar sling-shot physics mechanics are still there, but the game now features team-based gameplay, RPG elements, and a new top-down view. With all of... | Read more »
Sega Forever is for the retro game fans
Sega is launching a new retro games service titled Sega Forever, in a move that's sure to delight games enthusiasts with a bit of nostalgia. Sega's releasing five classic games for free. The titles include Sonic the Hedgehog, Phantasy Star II,... | Read more »
The Little Acre (Games)
The Little Acre 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

13-inch 1.8GHz/256GB MacBook Air on sale for...
B&H Photo has the updated 2017 13″ 1.8GHz/256GB MacBook Air (MQD42LL/A) in stock and on sale for $1129 including free shipping plus NY & NJ tax only. Their price is $70 off MSRP. Read more
27-inch 3.4GHz iMac on sale for $1699, save $...
B&H Photo has the new 2017 27″ 3.4GHz iMac (MNE92LL/A) in stock and on sale for $1699 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
21-inch 2.3GHz iMac on sale for $1049, save $...
B&H Photo has the new 2017 21″ 2.3GHz iMac (MMQA2LL/A) in stock and on sale for $1049 including free shipping plus NY & NJ tax only. Their price is $50 off MSRP. Read more
ABBYY TextGrabber 6 for iOS Implements Instan...
ABBYY has announced the release of TextGrabber 6.0.0, an important feature update to the company’s productivity app developed for iOS and Android devices. TextGrabber 6.0 now offers Real-Time... Read more
vPhone, First Smartphone That Can’t Be Lost,...
Austin, Texas based Hypori has introduced the vPhone, a virtual smartphone that affords every business user the benefits of separate work and personal phones, conveniently delivered on a single... Read more
Save this weekend with 2016 refurbished MacBo...
Apple has dropped prices on Certified Refurbished 2016 15″ and 13″ MacBook Pros by as much as $590 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: -... Read more
New 27-inch 3.4GHz iMac on sale for $1699, sa...
MacMall has the new 2017 27″ 3.4GHz iMac (MNE92LL/A) in stock and on sale for $1699 including free shipping. Their price is $100 off MSRP. Read more
Clearance 2016 MacBook Pros available for up...
B&H Photo has clearance 2016 13″ and 15″ MacBook Pros in stock today and on sale for up to $400 off original MSRP. Shipping is free, and B&H charges NY & NJ sales tax only: - 15″ 2.7GHz... Read more
Apple Ranks 9th In comScore Top 50 U.S. Digit...
comScore, Inc. has released its monthly ranking of U.S. online activity at the top digital media properties for May 2017 based on data from comScore Media Metrix Multi-Platform. * Entity has... Read more
10.5-inch iPad Pros available for up to $20 o...
B&H Photo has the new 2017 10.5″ iPad Pros available for up to $20 off MSRP including free shipping plus NY & NJ sales tax only: - 64GB iPad Pro WiFi: $649 - 256GB iPad Pro WiFi: $749 - 512GB... Read more

Jobs Board

*Apple* News Product Marketing Mgr., Publish...
…organizational consensus on strategy and vision for publisher tools, authoring, and Apple News Format.Carries this strategy and vision across the organization to Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Security Data Analyst - *Apple* Information...
…data sources need to be collected to allow Information Security to better protect Apple employees and customers from a wide range of threats.Act as the subject matter Read more
Lead *Apple* Solutions Consultant - Apple I...
…integrity, and trust.Success Metrics/Key Performance Indicators:Quantitative* Year over Year growth in Apple Product and Beyond the Box sales in the assigned Point of Read more
*Apple* Solutions Consultant till v%u00E5r...
…ethics, integrity, and trust.Success Metrics/Key Performance Indicators:QuantitativeYear over Year growth in Apple Product and Beyond the Box sales in the assigned Point Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.