Advanced Search

Log In | Not a Member? Contact ADC

Adding New Files or Modules

In this context, the term module is used loosely to refer to a collection of related files in the kernel that are controlled by a single config option at compile time. It does not refer to loadable modules (KEXTs). This section describes how to add additional files that will be compiled into the kernel, including how to add a new config option for an additional module.

In this section:

Modifying the Configuration Files
Modifying the Source Code Files

Modifying the Configuration Files

The details of adding a new file or module into the kernel differ according to what portion of the kernel contains the file. If you are adding a new file or module into the Mach portion of the kernel, you need to list it in various files in xnu/osfmk/conf. For the BSD portion of the kernel, you should list it in various files in xnu/bsd/conf. In either case, the procedure is basically the same, just in a different directory.

This section is divided into two subsections. The first describes adding the module itself and the second describes enabling the module.

Adding the Files or Modules

In the appropriate conf directory, you need to add your files or modules into various files. The files MASTER, MASTER.ppc, and MASTER.i386 contain the list of configuration options that should be built into the kernel for all architectures, PowerPC, and i386, respectively.

These are supplemented by files, files.ppc, and files.i386, which contain associations between compile options and the files that are related to them for their respective architectures.

The format for these two files is relatively straightforward. If you are adding a new module, you should first choose a name for that module. For example, if your module is called mach_foo, you should then add a new option line near the top of files that is whitespace (space or tab) delimited and looks like this:

OPTIONS/mach_foo    optional mach_foo

The first part defines the name of the module as it will be used in #if statements in the code. (See “Modifying the Source Code Files” for more information.) The second part is always the word optional. The third part tells the name of the option as used to turn it on or off in a MASTER file. Any line with mach_foo in the last field will be enabled only if there is an appropriate line in a MASTER file.

Then, later in the file, you add

osfmk/foo/foo_main.c            optional mach_foo

osfmk/foo/foo_bar.c             optional mach_foo

and so on, for each new file associated with that module. This also applies if you are adding a file to an existing module. If you are adding a file that is not associated with any module at all, you add a line that looks like the following to specify that this file should always be included:

osfmk/crud/mandatory_file.c     standard

If you are not adding any modules, then you’re done. Otherwise, you also need to enable your option in one of the MASTER files.

Enabling Module Options

To enable a module option (as described in the files files), you must add an entry for that option into one of the MASTER files. If your code is not a BSD pseudo-device, you should add something like the following:

options MACH_FOO

Otherwise, you should add something like this:

pseudo-device   mach_foo

In the case of a pseudo-device (for example, /dev/random), you can also add a number. When your code checks to see if it should be included, it can also check that number and allocate resources for more than one pseudo-device. The meaning of multiple pseudo-devices is device-dependent. An example of this is ppp, which allocates resources for two simultaneous PPP connections. Thus, in the MASTER.ppc file, it has the line:

pseudo-device   ppp 2   

Modifying the Source Code Files

In the Mac OS X kernel, all source code files are automatically compiled. It is the responsibility of the C file itself to determine whether its contents need to be included in the build or not.

In the example above, you created a module called mach_foo. Assume that you want this file to compile only on PowerPC-based computers. In that case, you should have included the option only in MASTER.ppc and not in MASTER.i386. However, by default, merely specifying the file foo_main.c in files causes it to be compiled, regardless of compile options specified.

To make the code compile only when the option mach_foo is included in the configuration, you should begin each C source file with the lines

#include <mach_foo.h>

#if (MACH_FOO > 0)

and end it with

#endif /* MACH_FOO */

If mach_foo is a pseudo-device and you need to check the number of mach_foo pseudo-devices included, you can do further tests of the value of MACH_FOO.

Note that the file <mach_foo.h> is not something you create. It is created by the makefiles themselves. You must run make exporthdrs before make all to generate these files.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice