Technical Note TN2163

Building Universal I/O Kit Drivers

Describes the steps for configuring an Xcode I/O Kit kernel driver project to produce a universal driver. Also discusses common problems when loading universal drivers.

Introduction Which Xcode and Mac OS X SDK Versions to Use Building for Intel-based Mac computers Building for PowerPC-based Mac computers Building for PowerPC-based Mac computers: Targeting Versions of Mac OS X Earlier than 10.4 Building for PowerPC-based Mac computers: Targeting Mac OS X 10.4.x Using Xcode 2.2.x or Xcode 2.3 Building for PowerPC-based Mac computers: Targeting Mac OS X 10.4.x Using Xcode 2.4 or Later Xcode Project Settings for a Universal I/O Kit Kernel Driver Common Problems with Universal I/O Kit Drivers Document Revision History

Introduction

Building universal I/O Kit drivers is very similar to building universal applications, but there are critical differences that can affect a driver's binary compatibility. This technical note describes the steps for configuring an Xcode I/O Kit kernel driver project to produce a universal driver and discusses common binary compatibility problems with universal drivers.

Back to Top 

Which Xcode and Mac OS X SDK Versions to Use

Xcode 2.2.1 is the oldest version of Xcode that can be used to build universal I/O Kit drivers.

Building for Intel-based Mac computers

The Intel side of your I/O Kit KEXT must be built using GCC 4.0 and the Mac OS X 10.4u (Universal) SDK found in Xcode 2.2.1 or later. This allows your driver to load and run on Intel-based Macintosh computers running Mac OS X 10.4.4 or later.

Back to Top 

Building for PowerPC-based Mac computers

The PowerPC side of your KEXT should be built using the Mac OS X SDK representing the oldest version of Mac OS X you wish to support.

Building for PowerPC-based Mac computers: Targeting Versions of Mac OS X Earlier than 10.4

Building for versions of Mac OS X prior to 10.4 also requires you to build using GCC 3.3.

Back to Top 

Building for PowerPC-based Mac computers: Targeting Mac OS X 10.4.x Using Xcode 2.2.x or Xcode 2.3

When using Xcode 2.2.x or 2.3, I/O Kit drivers targeting Mac OS X 10.4.x on PowerPC-based systems must be built using the Mac OS X 10.4.0 (not Universal) SDK. This is different from universal applications where the 10.4u (Universal) SDK can be used on both architectures.

The 10.4.0 SDK is available as a stand-alone installer from the Apple Developer Connection web site. A read me file is available for the SDK installer.

The 10.4.0 SDK can also be installed from the Xcode 2.0 installer, located on the Mac OS X 10.4 install DVD. It can be found in the Xcode custom installs under Cross Development.

Back to Top 

Building for PowerPC-based Mac computers: Targeting Mac OS X 10.4.x Using Xcode 2.4 or Later

Beginning with Xcode 2.4 there is another option, which is to define the preprocessor symbol KPI_10_4_0_PPC_COMPAT when building for the PowerPC architecture. When this preprocessor symbol is defined, the 10.4u (Universal) SDK will give the same results as using the 10.4.0 SDK. The same SDK can then be used for both PowerPC and Intel architectures.

Back to Top 

Xcode Project Settings for a Universal I/O Kit Kernel Driver

Using the proper SDK and compiler versions is easily accomplished using Xcode's per-architecture build settings.

To convert a PowerPC-only Xcode I/O Kit driver project to a universal project, first make sure that all targets in your project are native Xcode targets. You can check this by opening your project in Xcode, then select the Project menu and see if the command Upgrade All Targets in Project to Native is enabled. If it is, make a backup copy of your project, then use that command to convert all of your legacy targets to native.

Then, make the following changes to the Project or Target Build settings. Modify the Project settings if you want the settings to apply to all targets in the project. Modify the Target settings if you want just a particular target to produce a universal KEXT.

1. Set Architectures to ppc i386. This can be done by double-clicking the word Architectures and then selecting both the PowerPC and Intel checkboxes.

2. Remove any setting for SDK Path and VALID_ARCHS by selecting the option and then clicking the - button at the bottom of the window.

3. Add the custom settings SDKROOT_i386 and SDKROOT_ppc. Set the value of each to the path of the SDK to use to build on each architecture. SDKROOT_i386 should be set to /Developer/SDKs/MacOSX10.4u.sdk and SDKROOT_ppc should point to the SDK matching the oldest major Mac OS X release you wish to support, such as /Developer/SDKs/MacOSX10.2.8.sdk.

4. Add the settings GCC_VERSION_i386 and GCC_VERSION_ppc that specify the compiler version to use when building for each architecture. GCC_VERSION_i386 must be set to 4.0 or greater. If you want to support versions of Mac OS X prior to 10.4, GCC_VERSION_ppc must be set to 3.3.

5. If you are using Xcode 2.4 or later and the PowerPC side of your KEXT is targeting Mac OS X 10.4.x, add the setting PER_ARCH_CFLAGS_ppc that specifies compiler flags to pass to GCC only when building for the PowerPC architecture. Set the value of PER_ARCH_CFLAGS_ppc to -DKPI_10_4_0_PPC_COMPAT.

6. Set Mac OS X Deployment Target to Compiler Default.

7. Add the settings MACOSX_DEPLOYMENT_TARGET_i386 and MACOSX_DEPLOYMENT_TARGET_ppc. These settings must have the value of a major Mac OS X release version number such as 10.2 or 10.4. Do not specify software update versions such as 10.3.9. MACOSX_DEPLOYMENT_TARGET_i386 must be set to 10.4 or later, and MACOSX_DEPLOYMENT_TARGET_ppc should be set to the oldest major Mac OS X release you wish to support.

Back to Top 

Common Problems with Universal I/O Kit Drivers

Most problems you'll encounter after building a universal driver will appear when loading it. For example, kextload might report the error

com.mycompany.driver.MyDriverClass is not compatible with its superclass,
<superclass name> superclass changed?

The reason for most load-time errors is that the wrong SDK was used when building the driver. For example, the PowerPC side of the driver is targeting Mac OS X 10.3.x but was built using the 10.4u SDK. Refer to the SDK version information shown earlier in Which Xcode and Mac OS X SDK Versions to Use. Then verify that your Xcode project is set up as described earlier in Xcode Project Settings for a Universal I/O Kit Kernel Driver.

Back to Top 

Document Revision History

Posted: 2006-11-10