Implement the Start and Stop Functions

1. Open MyKext.c to edit the start and stop functions.

   Figure 1 shows the unedited file.

   

   The default start and stop functions do nothing but return a successful status. A real kext’s start and stop functions typically register and unregister callbacks with kernel runtime systems, but for this tutorial, your kext simply prints messages so that you can confirm when your kext has been started and stopped.

2. Edit MyKext.c to match the code in Listing 1.

   
   
   

   Listing 1  MyKext.c file contents

   #include <sys/systm.h>

   #include <mach/mach_types.h>

   kern_return_t MyKext_start (kmod_info_t * ki, void * d)

   {

   printf("MyKext has started.\n");

   return KERN_SUCCESS;

   }

   kern_return_t MyKext_stop (kmod_info_t * ki, void * d)

   {

   printf("MyKext has stopped.\n");

   return KERN_SUCCESS;

   }

   Notice that MyKext.c includes two header files, <sys/systm.h> and <mach/mach_types.h>. Both header files reside in Kernel.framework. When you develop your own kext, be sure to include only header files from Kernel.framework (in addition to any header files you create), because only these files have meaning in the kernel environment. If you include headers from outside Kernel.framework, your kernel extension might compile, but it will probably fail to load or run because the functions and services those headers define are not available in the kernel.

3. Save your changes by choosing File > Save.

Edit the Information Property List

Like all bundles, a kext contains an information property list, which describes the kext. The default Info.plist file created by Xcode contains template values that you must edit to describe your kext.

A kext’s Info.plist file is in XML format. Whenever possible, you should view and edit the file from within Xcode or within the Property List Editor application. In this way, you help ensure that you don’t add elements (such as comments) that cannot be parsed by the kernel during early boot.

1. Click Info.plist in the Xcode project window.

   Xcode displays the Info.plist file in the editor pane. You should see the elements of the property list file, as shown in Figure 2.

   

   By default, Xcode’s property list editor masks the actual keys and values of a property list. To see the actual keys and values, Control-click anywhere in the property list editor and choose Show Raw Keys/Values from the contextual menu.

2. Change the value of the CFBundleIdentifier property to use your unique namespace prefix.

   On the line for CFBundleIdentifier, double-click in the Value column to edit it. Select com.yourcompany and change it to com.MyCompany (or your company’s DNS domain in reverse). The value should now be com.MyCompany.kext.${PRODUCT_NAME:rfc1034identifier}.

   Bundles in OS X typically use a reverse-DNS naming convention to avoid namespace collisions. This is particularly important for kexts because all loaded kexts share a single namespace for bundle identifiers.

   The last portion of the default bundle identifier, ${PRODUCT_NAME:rfc1034identifier}, is replaced with the Product Name build setting for the kext target when you build your project.

3. Save your changes by choosing File > Save.

Build the Kernel Extension

Now you’re ready to configure your build settings and build your kext to make sure the source code compiles. First, configure your build settings to build the kext for every architecture, to make sure your kext will load regardless of the architecture of the kernel.

1. Click the disclosure triangle next to Targets in the Groups and Files pane.

2. Select the MyKext target.

3. Choose File > Get Info. The Target “MyKext” Info window opens.

4. In the list of settings, find Build Active Architecture Only and make sure the checkbox is unchecked.

5. Close the Target MyKext Info window.

Now that your kext is building against every architecture, choose Build > Build to build your project. If the build fails, correct all indicated errors and rebuild before proceeding.

Run kextlibs on the Kernel Extension

kextlibs is a command-line program that you run with the Terminal application. Its purpose is to identify libraries that your kext needs to link against.

1. Start the Terminal application, located in /Applications/Utilities.

2. In the Terminal window, move to the directory that contains your kext.

   Xcode stores your kext in the Debug folder of the build folder of your project (unless you’ve chosen a different build configuration or set a different location for build products using Xcode’s Preferences dialog).

   $ cd MyKext/build/Debug

   This directory contains your kext. It should have the name MyKext.kext. This name is formed from the Product Name as set in your target’s build settings, and a suffix, in this case .kext.

3. Run kextlibs on your kernel extension with the -xml command-line flag.

   This command looks for all unresolved symbols in your kernel extension’s executable among the installed library extensions (in /System/Library/Extensions/) and prints an XML fragment suitable for pasting into an Info.plist file. For example:

   $ kextlibs -xml MyKext.kext

   <key>OSBundleLibraries</key>

   <dict>

   <key>com.apple.kpi.libkern</key>

   <string>10.2</string>

   </dict>

4. Make sure kextlibs exited with a successful status by checking the shell variable $?.

   $ echo $?

   0

   If kextlibs prints any errors or exits with a nonzero status, it may have been unable to locate some symbols. For this tutorial, the libraries are known, but in general usage you should use the kextfind tool to find libraries for any symbols that kextlibs cannot locate. See Locate Kexts for information on kextfind.

5. Select the XML output of kextlibs and choose Edit > Copy.

Add the Library Declarations to the Information Property List

Earlier, you edited the information property list with Xcode’s graphical property list editor. For this operation, however, you need to edit the information property list as text.

1. Control-click Info.plist in the Xcode project window, then choose Open As > Source Code File from the contextual menu.

   Xcode displays the Info.plist file in the editor pane. You should see the XML contents of the property list file, as shown in Figure 3. Note that dictionary keys and values are listed sequentially.

   

2. Select all the lines defining the empty OSBundleLibraries dictionary:

   <key>OSBundleLibraries</key>

   <dict/>

3. Paste text into the info dictionary.

   • If kextlibs ran successfully, choose Edit > Paste to paste the text you copied from Terminal.

   • If kextlibs didn’t run successfully, type or paste this text into the info dictionary:

     <key>OSBundleLibraries</key>

     <dict>

     <key>com.apple.kpi.libkern</key>

     <string>10.0</string>

     </dict>

4. Save your changes by choosing File > Save.

5. Choose Build > Build a final time to rebuild your kext with the new information property list.

Set the Kernel Extension’s Permissions

Kexts have strict permissions requirements (see Kernel Extensions Have Strict Security Requirements for details). The easiest way to set these permissions is to create a copy of your kext as the root user. Type the following into Terminal from the proper directory and provide your password when prompted:

$ sudo cp -R MyKext.kext /tmp

Now that the permissions of the kext’s temporary copy are correct, you are ready to run kextutil.

Run kextutil

Type the following into Terminal:

$ kextutil -n -print-diagnostics /tmp/MyKext.kext

The -n (or -no-load) option tells kextutil not to load the driver, and the -t (or -print-diagnostics) option tells kextutil to print the results of its analysis to Terminal. If you have followed the previous steps in this tutorial correctly, kextutil indicates that the kext is loadable and properly linked.

No kernel file specified; using running kernel for linking.

MyKext.kext appears to be loadable (including linkage for on-disk libraries).