All Databases MacTech Vol 10-1994

PowerPC Code

Volume Number: 10

Issue Number: 4

Column Tag: Powering Up

Connecting A 68k Object File

To PowerPC Code

A robust technique for loading and calling 68K modules from your

PowerPC application

By Richard Clark, Apple Computer, Inc.

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

source code disks.

Many developers run into a major problem when porting code to PowerPC:

incorporating 68K object models which came from an outside vendor. Since you can’t

just hand a 68K module to the PowerPC linker, you have to find some alternative for

loading the library and calling the library’s functions. Fortunately, developers can use

the Code Fragment Manager and the Mixed Mode Manager together to solve this

problem.

The solution involves creating a stand-alone version of the 68K code, then

assembling a “jump table” of Universal Procedure Pointers which the application can

use to call this code. Since applications (and, in fact, any PowerPC code fragment) can

have global variables, it makes sense to allocate this table within the application.

However, since the 68K library entry points are only available to the 68K code, that

code has to create the universal procedure pointers. This would create an impossible

dilemma except for one fact - both Mixed Mode and the Code Fragment Manager can be

called from emulation on a Power Macintosh via A-Traps.

Thus we have a solution - the application must create the jump table as a global

variable, and then pass its address to the 68K code which assembles the jump table.

(An alternate method involves exporting the table from the application. The 68K code

must open a connection back to the application, and ask the CFM for the address of the

jump table.) The 68K code creates Universal Procedure Pointers to fill the table,

which allows the application to call the library functions using Mixed Mode.

Creating the Jump Table

The first step is to prepare a list of all of the functions that your application

calls in the library. Next, define ProcInfo values for each of these functions, using the

MixedMode.h header and any header which defines callback functions (such as

Controls.h) as a guide. You should also create macros for creating and calling a

UniversalProcPtr in this way.

Next, create a data structure which contains Mixed Mode “Universal Procedure

Pointers” for each of these functions. Put a copy of this data structure into a global

variable in your PowerPC application, and don’t declare it as “static” (i.e. hidden.)

You should also export this table, for a reason that will become clear shortly.

/* 1 */
// This is a header file common to the application and 68K code
#include 
#include 
typedef void (*CallbackPtr)(void); // A pointer which is fed to the
library
typedef pascal OSErr (*Routine1ProcPtr)(CallbackPtr callbackRoutine);
enum {
uppRoutine1ProcInfo = kPascalStackBased
 | RESULT_SIZE (SIZE_CODE(sizeof(OSErr)))
 | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(CallbackPtr)))
};
#if USESROUTINEDESCRIPTORS
// Use these definitions if we're compiling for Power Macintosh or
another
// Macintosh system which supports Mixed Mode
typedef UniversalProcPtr Routine1UPP;
#define CallRoutine1Proc(userRoutine, longValue) 
CallUniversalProc((UniversalProcPtr)(userRoutine),
uppRoutine1ProcInfo, longValue)
#define NewRoutine1Proc(userRoutine) 
(RoutineUPP) NewRoutineDescriptor((ProcPtr)userRoutine, 
   uppRoutine1ProcInfo, GetCurrentISA())
#else
// Use these definitions if we're compiling for a 68K-based Macintosh
typedef Routine1ProcPtr Routine1UPP;
#define CallRoutine1Proc(userRoutine, longValue) 
(*((Routine1ProcPtr )userRoutine))(longValue)
#define NewRoutine1Proc(userRoutine) 
(Routine1UPP)(userRoutine)
#endif
// Here's the list of Universal Procedure Pointers
struct JumpTable {
Routine1UPP routine1;
};
typedef struct JumpTable JumpTable, *JumpTablePtr;
// === Information on calling the 68K setup functions
typedef pascal OSErr (*SetupProcPtr)(JumpTablePtr);
enum {
uppSetupProcInfo = kPascalStackBased
 | RESULT_SIZE (SIZE_CODE(sizeof(OSErr)))
 | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(JumpTablePtr)))
};
#if USESROUTINEDESCRIPTORS
// Use these definitions if we're compiling for Power Macintosh or
another
// Macintosh system which supports Mixed Mode
typedef UniversalProcPtr SetupUPP;
#define CallSetupProc(userRoutine, jumpTableAddr) 
CallUniversalProc((UniversalProcPtr)(userRoutine),
uppSetupProcInfo, jumpTableAddr)
#define NewSetupProc(userRoutine) 
(SetupUPP) NewRoutineDescriptor((ProcPtr)userRoutine, 
   uppSetupProcInfo, GetCurrentISA())
#else
// Use these definitions if we're compiling for a 68K-based Macintosh
typedef SetupProcPtr SetupUPP;
#define CallSetupProc(userRoutine, jumpTableAddr) 
(*((SetupProcPtr)userRoutine))(jumpTableAddr)
#define NewSetupProc(userRoutine) 
(SetupUPP)(userRoutine)
#endif

Next, you have to create the “setup” function in 68K code and link it to your 68K

object library. This routine needs to fill in each of the pointers in the table. The

resulting code should be compiled, linked, and made into a stand-alone 68K code

resource.

Granted, this technique could prove difficult if the library depends on having an

A5 world. If your 68K library requires global variables, you must apply one of the

special coding techniques documented in the Macintosh Developer Technical Notes or

develop magazine.) Also note that if you want this code to run on a 68K machine, you

should check for the presence of Mixed Mode and react appropriately.

/* 2 */
pascal OSErr BuildJumpTable(JumpTablePtr theJumpTable)
// Build a table of pointers to functions in our linked library
{
OSErr err;
// Fill in the table with pointers to each library function
theJumpTable->routine1 = NewMyRoutineProc(Routine1);
err = MemError();
return err;
}

The alternate approach involves exporting the jump table from the Application

using the CFM, and letting the 68K code ask the CFM for the table’s address. Note the

use of a STR# resource to store the application and table name strings - this avoids

needing an A5 world just for the string constants. (Note that this code will not work on

a machine which doesn’t have the Code Fragment Manager or Mixed Mode.)

/* 3 */
OSErr err;
JumpTablePtr theJumpTable;
ConnectionID connID = 0;
Ptr mainAddr;
Str255  errName, appName, tableName;
SymClass  symClass;
// Locate the application that called us
GetIndString(&appName, 128, 1); // Assuming the name is in a STR#
err = GetSharedLibrary(&appName, kPowerPCArch, 0,
&connID, &mainAddr, &errName);
if (err) goto done;
// Now, locate the shared table
// (it's a pointer stored in a global variable)
GetIndString(&tableName, 128, 2);// The table name is in the same
STR#
err = FindSymbol(connID, &tableName,
(Ptr*)&myTablePointer, &symClass);
if (err) goto done;
// Insert the code to create UniversalProcPtrs here
done:
if (connID)
CloseConnection(&connID);
  return err;

To initialize this table, simply load the code resource from the application and

call it via Mixed Mode. When the resource returns, the jump table will be full of

Universal Procedure Pointers. Therefore, you should then modify your application to

use Mixed Mode and the pointers in the table to call the library functions.

/* 4 */
// include the usual macros for creating a UniversalProcPtr for our
callback routine
JumpTable gJumpTable;
// Load the stand-alone code
Handle theResource;
theResource= Get1IndResource('STUB', 1);
if (theResource) {
  MoveHHi(theResource);
  HLock(theResource); // Lock it -- and NEVER unlock it
  // Call the entry point, no parameters
  CallSetupProc(*theResource, &gJumpTable);
// we know it's 68K, so we didn't
// bother with creating a Routine Descriptor
  // Create a UniversalProcPtr for our callback routine
  CallbackUPP ourCallback;
  ourCallback = NewCallbackProc(MyCallbackRoutine);
  result = CallRoutine1Proc(gJumpTable.routine1,ourCallback );
  DisposeRoutineDescriptor(ourCallback);
}

Note that since the library function takes a callback pointer, we had to create a

UniversalProcPtr and pass that instead of the address of the actual code. (If we hadn't

done this, the machine would crash.) Since this causes memory to be allocated for a

Routine Descriptor, we call DisposeRoutineDescriptor afterwards to release the

memory.

That’s all there is to it! This is a robust technique which is now being used in

several commercial applications - perhaps it will prove useful in yours.

Referenced by (9):