Volume Number: 15 (1999)
Issue Number: 3
Column Tag: Programming Techniques
by Miro Jurisic
One of the great things about Macintosh software is that older 68K application software tends to work on the newer PowerPC machines and that user of the older machines can get modern software. One example of this is Apple's support for the Code Fragment Manager on 68K ("CFM68K") beginning with System 7.1. With this, 68K code can use the Code Fragment Manager to implement libraries and plug-ins, or can call PowerPC code when running emulated on a PowerPC system.
George Wagner first described how to call CFM shared libraries (whether PowerPC or 68K) from 68K code; you can find this as Apple Developer Technical Support Technote 1077 (TN 1077).
This article contains improvements to the code provided in TN1077, making the code more robust and provides examples of additional problems and techniques. In particular, this article describes:
This article assumes that you are familiar with the Code Fragment Manager and shared libraries (as described in [IM:PPC] and [IM:RTA]), and that you have read TN 1077 [TN1077].
The code in TN 1077 does an incorrect check to determine the runtime architecture of the machine it's running on.
The problem with the TN 1077 code is that it returns an error when the gestaltSystemArchitecture Gestalt selector is not installed, i.e., on all versions of Mac OS before 7.1.2. However, CFM-68K is backwards compatible to system 7.1; as a result, TN 1077 glue code fails to load CFM-68K shared libraries on Mac OS 7.1 and 7.1.1.
The correct version of the code is:
GetSystemArchitecture
GetSystemArchitecture determines system architecture it is running
in (68K or PPC).
static pascal OSErr GetSystemArchitecture (
OSType *outArchType)
{
// static so we only Gestalt once
static long sSysArchitecture = 0;
OSErr tOSErr = noErr;
// assume wild architecture
*outArchType = kAnyCFragArch;
// If we don't know the system architecture yet...
// Ask Gestalt what kind of machine we are running on.
if (sSysArchitecture == 0)
tOSErr = Gestalt(gestaltSysArchitecture,
&sSysArchitecture);
if (tOSErr == noErr) { // if no errors
if (sSysArchitecture == gestalt68k) // 68k?
*outArchType = kMotorola68KCFragArch;
else if (sSysArchitecture == gestaltPowerPC) // PPC?
*outArchType = kPowerPCCFragArch;
else // who knows what might be next?
tOSErr = gestaltUnknownErr;
} else if (tOSErr == gestaltUndefSelectorErr) {
// No system architecture gestalt
// We must be running on a system older than 7.1.2, so
// we are on a 68K machine.
*outArchType = kMotorola68KCFragArch;
tOSErr = noErr;
}
return tOSErr;
}
The TN 1077 code does not check for presence of the Code Fragment Manager before calling it to load the library. This causes the glue code to crash 68K machines with an Illegal A-Trap when CFM-68K is not present. To fix this error, we add code to the Find_Symbol function to check for presence of CFM:
Find_Symbol
Addition to the Find_Symbol function that correctly checks for presence
of CFM before calling it.
static pascal OSErr Find_Symbol (
Ptr* pSymAddr,
Str255 pSymName,
ProcInfoType pProcInfo)
{
/* Code to determine the runtime architecture goes here*/
if (!HaveCFM()) {
// If we don't have CFM68K
// return a reasonable-looking error.
sOSErr = cfragLibConnErr;
return sOSErr;
}
/* Code to load the library and find the symbol goes here */
}
Clearly, we also need to add the HaveCFM() function:
HaveCFM
Checking for presence of the Code Fragment Manager
static pascal Boolean HaveCFM(void)
{
OSErr theError = noErr;
// static so we only call Gestalt once
static Boolean sHaveCFM = false;
static Boolean sCalledGestalt = false;
long response;
if (!sCalledGestalt) {
theError = Gestalt(gestaltCFMAttr, &response);
sCalledGestalt = true;
sHaveCFM =
(theError == noErr) &&
(((response >> gestaltCFMPresent) & 1) != 0);
}
return sHaveCFM;
}
Restrictions in the Mixed Mode Manager limit which functions in a CFM shared library can be accessed from classic 68K code. Only functions
This means that you cannot access any functions that take or return structs or some floating-point types; however, you can use functions that take or return pointers to structs or pointers to floating-point types.
Thus, if you control the library, you may want to consider changing the library interface so that your functions satisfy the above conditions. If you do not control the library, or you cannot change the library interface, you can write a wrapper library which provides an interface that can be called from classic 68K, and just calls the real library to do the work (with arguments appropriately rearranged).
For example, if you have a function in a shared library with the following prototype:
myFunction
Example of a function that cannot be called via the Mixed Mode Manager
struct myStruct {
UInt32 a;
UInt32 b;
}
// The following function can't be called from classic 68K
// using Mixed Mode Manager because the size of its
// arguments and the return value is not 1, 2, or 4 bytes.
myStruct myFunction (myStruct param1, myStruct param2);
then you can write the wrapper function like this:
myFunctionWrapper
Example of a wrapper function that can be called via the Mixed Mode Manager
// The following function can be called from classic 68K
// code using the Mixed Mode Manager.
// Note how the wrapper function avoids having to deal
// with memory allocation by changing the return value
// into a non-const pointer argument
void myFunctionWrapper (myStruct* result, const myStruct* param1, const myStruct* param2) {
*result = myFunction (*param1, *param2);
}
If you put this wrapper function in a shared library, then you can call the wrapper function from your 68K code (because the wrapper function does not violate the Mixed Mode Manager restrictions), and the wrapper function can call the real function (because that is just a cross-fragment call that does not have those restrictions).
It is not possible to write a simple wrapper for a shared library function which takes a variable number of arguments, such as the C "printf" function. First of all, even if you could write a wrapper function, it would still be limited to no more than 13 arguments. However, the real problem is that the procedure information you would have to pass to the Mixed Mode Manager depends on the number and the types of the arguments, and this information is lost once the arguments are put on the stack. Either you would have to pass the number and sizes of arguments into the glue function, or the glue function would have to parse the arguments to determine how many there are and how big they are.
We can use printf as an example,
printf("Hello, my name is %s\n", "Miro");
The printf function has to take the first argument and use the information provided there to extract the remaining parameters from the stack. To write a wrapper for this function, you would have to write a parser to extract the arguments, build the appropriate routine descriptor, and push them back onto the stack in the correct form before calling the function.
In any case, the work involved in writing the wrapper function is probably better spent rewriting the library function to take a fixed number of arguments.
Suppose your classic 68K code makes a call into a CFM shared library via glue code. The call is executed like this:
To find arguments passed by the glue function and the value returned to the glue function, the Mixed Mode Manager uses procedure information in the UPP. This means that you have to make sure that compiler options you are using to compile the glue functions match the procedure information in the UPPs for the shared library functions. Otherwise, either your shared library function will get garbage arguments, or the glue function will get a garbage return value.
If your glue functions follow Pascal calling conventions, then you should use kPascalStackBased as the calling convention in procedure information.
If your glue functions follow C calling convention, and are compiled with an MPW compiler, or with another MPW-compatible compiler (such as Metrowerks compiler with "MPW Calling Conventions" turned on), then you should use kCStackBased in procedure information.
If you are compiling with the default settings for Metrowerks compilers, then your glue functions will follow the ThinkC calling convention, and you should use kThinkCStackBased in the procedure information. There is one twist, however: if the return value from a UPP call is a pointer, the glue function will expect the result to be returned in the A0 register instead of the D0 register. However, the MixedModeManager will always put the return value in D0 if UPP has kThinkCStackBased for its calling convention.
Therefore, if you start with the default settings for Metrowerks compilers, you have to compile your glue functions so that they expect the results to always be returned in D0. This is done by surrounding your glue code with the following pragmas:
#pragma d0_pointers on // Prototypes for glue functions go here #pragma d0_pointers resetGenerating Glue Code Programatically
As I was working with CFM glue for several shared libraries, it occurred to me that writing the glue was a fairly mechanical process; there is a section of code that's invariant, and a secion of code that contains glue functions, but the glue functions follow a fairly straightforward pattern. Thus I thought generating the glue with a script might be a good idea. Looking at my options, I decided that Perl was a good tool for the job, so I summoned my local Perl deity.
She consed up1 a script that takes as input a list of C function prototypes, such as:
Sample prototype list UInt16 sampleFun1 (void* arg1, UInt32 arg2); void sampleFun2 (UInt32* arg1, UInt16 arg[]); void sampleFun3 (void);
Although it may seem annoying that you need to take your existing C headers and strip them down to the form accepted by the Perl script, we decided that it would be slightly impractical to implement enough of a C parser and semantic analyzer in Perl to extract prototypes from a regular header file.
The script uses MacPerl and its MPW tool; before you can use the script, you will have to install MacPerl and the tool (see [MacPerl] for download and installation instructions).
The output of the script for the above input is:
Sample glue generated by the script
/**** sampleFun1 ****/
/* UInt16 sampleFun1 (void* arg1, UInt32 arg2); */
enum {
sampleFun1_ProcInfo = kThinkCStackBased
| RESULT_SIZE(SIZE_CODE(sizeof(UInt16)))
| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(void *)))
| STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(UInt32)))
};
typedef UInt16 (*sampleFun1_ProcPtrType)(void *, UInt32);
UInt16 sampleFun1 (
void * arg1,
UInt32 arg2)
{
static sampleFun1_ProcPtrType sampleFun1_ProcPtr =
kUnresolvedCFragSymbolAddress;
// if this symbol has not been setup yet...
if ((Ptr) sampleFun1_ProcPtr == (Ptr)
kUnresolvedCFragSymbolAddress)
FindLibrarySymbol ((Ptr *) &sampleFun1_ProcPtr,
"\psampleFun1",
sampleFun1_ProcInfo);
if ((Ptr) sampleFun1_ProcPtr !=
(Ptr) kUnresolvedCFragSymbolAddress)
return sampleFun1_ProcPtr (arg1, arg2);
}
/**** sampleFun2 ****/
/* void sampleFun2 (UInt32* arg1, UInt16 arg[]); */
enum {
sampleFun2_ProcInfo = kThinkCStackBased
| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(UInt32 *)))
| STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(UInt16 *)))
};
typedef void (*sampleFun2_ProcPtrType)(UInt32 *, UInt16 *);
void sampleFun2 (
UInt32 * arg1,
UInt16 * arg)
{
static sampleFun2_ProcPtrType sampleFun2_ProcPtr =
kUnresolvedCFragSymbolAddress;
// if this symbol has not been setup yet...
if ((Ptr) sampleFun2_ProcPtr ==
(Ptr) kUnresolvedCFragSymbolAddress)
FindLibrarySymbol((Ptr *) &sampleFun2_ProcPtr,
"\psampleFun2",
sampleFun2_ProcInfo);
if ((Ptr) sampleFun2_ProcPtr !=
(Ptr) kUnresolvedCFragSymbolAddress)
sampleFun2_ProcPtr(arg1, arg);
}
/**** sampleFun3 ****/
/* void sampleFun3 (void) */
enum {
sampleFun3_ProcInfo = kThinkCStackBased
};
typedef void (*sampleFun3_ProcPtrType)(void);
void sampleFun3 (
void)
{
static sampleFun3_ProcPtrType sampleFun3_ProcPtr =
kUnresolvedCFragSymbolAddress;
// if this symbol has not been setup yet...
if((Ptr) sampleFun3_ProcPtr ==
(Ptr) kUnresolvedCFragSymbolAddress)
FindLibrarySymbol((Ptr *) &sampleFun3_ProcPtr,
"\psampleFun3",
sampleFun3_ProcInfo);
if ((Ptr) sampleFun3_ProcPtr !=
(Ptr) kUnresolvedCFragSymbolAddress)
sampleFun3_ProcPtr();
}
Once we produce this output, we need to assemble it into a final glue file consisting of:
We generate the final glue file with the following MPW commands:
perl MakeCFMGlue.pl < :GlueExample.proto.h > ∂
:GlueExample.Glue.c
Catenate :GlueExample.Glue.pre.c :Glue.c ∂
:GlueExample.Glue.c :GlueExample.Glue.post.c | ∂
Catenate > :GlueExample.Glue.c
As noted before, the Perl script is nowhere near as smart as a C compiler. Because of this, the script cannot detect some things that you cannot or should not put in your glue code, such as:
The script also does not detect the following conditions which will generate incorrect glue code:
The script will detect the following problems in your prototypes:
You should be especially careful about types whose sizeof()is not the same as their size when passed as argument; this is somewhat tricky, as it is usually not obvious. Consider the following code:
typedef UInt32 TwoWordType[2]; void myFunction (TwoWordType arg);
Script-generated glue for such a function would contain the following procedure information:
enum {
myFunction_ProcInfo = kThinkCStackBased
| STACK_ROUTINE_PARAMETER(1,
SIZE_CODE(sizeof(TwoWordType)))
};
The problem is that sizeof(TwoWordType) is 8, but a TwoWordType is passed on the stack as a pointer. So, the size that we really want to use here is that of a UInt32[]. Using sizeof(TwoWordType) causes the procedure information to indicate the size is 0 (see the definition for SIZE_CODE in MixedMode.h), i.e., no argument is passed, so that the CFM library function gets garbage in. ("Nasty." "Yeah.")
A typedef to an array type is the only case that we could find where a bizarre thing like this happens, but it took us a while to figure it out, so be careful with your typedefs when CFM glue is in town.
These weaknesses of the Perl script are the main reason why we consider it a feature that you need to create the prototype list (mostly) by hand, because you have an opportunity to look at all the prototypes at that time and inspect them for possible problems.
Complete source for CFM glue functions is provided with the article; the code consists of the following:
Writing classic 68K glue for CFM library functions can be tricky. There are plenty of ways to make a mistake, and most of them result in moderately baffling failures. Here are some things to try when your glue code doesn't work:
Check whether your library is getting loaded at all, by either:
If the library is not getting loaded, make sure that:
If the library is getting loaded, but it is misbehaving:
If all of this fails, then I sincerely hope you are on friendly terms with MacsBug...
I would like to thank George Wagner of DTS for writing the original "develop" article and the Technote (without him, I would never have been able to get started on this); Alexandra Ellwood, who wrote the glue code generation Perl script (without her, I would have had to learn Perl); Marshall Vale, for asking "I wonder if we could..."; and Scott McGuire, who is not a writing major.
Miro Jurisic is a wacky European working for Massachusetts Institute of Technology Information Systems. In his free time, he is a full-time student at MIT, working on his Master's degree in Computer Science and Bachelor's degree in Mathematics. His only artistic ability is ASCII art. He can be reached at meeroh@mit.edu.
