info
Basic loading
To load a kext you must run kextload as the superuser and supply a kext bundle name; no options are required:
kextload TabletDriver.kext
Alternatively, you can use the -b option to specify a kext by its CFBundleIdentifier:
kextload -b com.mycompany.driver.TabletDriver
With no additional options kextload will look in /System/Library/Extensions for a kext with the given CFBundleI-
dentifier. Adding repository directories with the -r option or individual kexts with the -d option expands the
set of kexts that kextload looks among:
kextload -r ${USER}/Library/Extensions TabletDriver.kext
If you're modifying system startup to load a kext, be sure to check whether the system is starting up in safe
boot mode (typically when the user presses the Shift key) and use the -x option to indicate this. (The various
rc files in /etc can simply use the $SafeBoot shell variable on the command line. It evaluates to an empty
string during normal startup and "-x" during safe boot mode.)
Validating Kexts
The -t option causes kextload to perform all possible validation and authentication checks on the specified
kexts and to attempt to resolve their dependencies. If there are any problems with the specified kexts,
kextload prints a list of the problems.
The -t option is typically used with -n after a load failure to pinpoint a problem. It can be used with any
other set of options, however.
If you want to validate a kext in isolation, as in a build environment where dependencies may not be available,
you can use the -e and -Z options to omit the /System/Library/Extensions repository and to suppress dependency
resolution, respectively:
kextload -entZ PacketSniffer.kext
Only validation and authentication checks will be performed.
Generating Debug Symbols When Loading
To generate a symbol file for use with gdb when loading a kext, use the -s option to specify a directory where
symbol files will be written for the kext being loaded and all its dependencies.
kextload -s ~/ksyms PacketSniffer.kext
Generating Debug Symbols For an Already-Loaded Kext
If you want to generate symbols for a kext that's already loaded, whether on the same system or on another, use
the -s option along with the -n option. Since in this case addresses must be known for the kext and all its
dependencies, though, you must specify these. If you don't indicate them on the command line, kextload will ask
you for the load address of each kext needed. Use kextstat(8) on the machine you're generating symbols for to
get these addresses and enter them at each prompt.
kextload -n -s ~/ksyms GrobbleEthernet.kext
enter the hexadecimal load addresses for these modules:
com.apple.iokit.IONetworkingFamily: 0x1001000
...
Alternatively, if you know the CFBundleIdentifiers of all the kexts, you can use the -a option for each kext
(you needn't specify -n when using the -a option):
kextload -s ~/ksyms \
-a com.apple.iokit.IONetworkingFamily@0x1001000 \
-a com.apple.iokit.IOPCIFamily@0x1004000 \
-a com.mycompany.driver.GrobbleEthernet@0x1007000 \
GrobbleEthernet.kext
Simplest of all, however, provided you can run kextload on the same machine as the loaded kext, is to use the -A
option, which checks with the kernel for all loaded kexts and automatically gets their load addresses.
kextload -s ~/ksyms -A GrobbleEthernet.kext
Explicitly Specifying Dependencies
Because kextload resolves dependencies automatically, it's possible that a kext other than the one you intend
might get used as a dependency (such as when there are multiple versions, or if you're working on a new version
of a kext that's already installed in /System/Library/Extensions). By default, when loading a kext into the
kernel kextload checks which versions of possible dependencies are already loaded in order to assure a success-
ful load. When not loading, however, it always chooses the most recent versions of any dependencies.
If you want to have complete control over the set of extensions used to resolve dependencies, use the -e, -d,
and -r options. The -e option excludes the standard /System/Library/Extensions folder, leaving the set of can-
didate extensions for dependency resolution entirely up to you. To specify candidate dependencies you use
either -d, which names a single kext as a candidate, or -r, which adds an entire directory of extensions.
kextload -n -s ~/ksyms -e \
-d /System/Library/Extensions/System.kext \
-r ~/TestKexts -d JoystickSupport.kext JoystickDriver.kext
Note also that if you use -e, you must supply some version of the System.kext bundle in order to supply informa-
tion about the kernel. This should always match the kernel you're linking against, which is by default the
installed kernel on the machine you're using kextload on; you can use the -k option to indicate a different ker-
nel file.
Debug-Loading an I/O Kit Driver
If you need to debug an I/O Kit driver's early startup code, you must load the driver on the target machine
without starting matching by using the -l option:
kextload -l DiskController.kext
Once you have done this, you can use the generated symbol file in your debug session to set breakpoints and then
trigger matching by running kextload again on the target machine with the -m option:
kextload -m DiskController.kext
You may wish to use the -p option as well in order to send selected personalities to the kernel. Alternatively,
you can use the -i option for the whole process, which causes kextload to pause just before loading any person-
alities and then to ask you for each personality whether that one should be sent to the kernel:
kextload -i DiskController.kext
Debug-Loading a non-I/O Kit Kext
A non-I/O Kit kext doesn't have a personality-matching phase of loading; it just starts executing. In order to
debug a non-I/O Kit kext's startup code, you must use the -i or -I option, which pauses loading at each signifi-
cant stage so that you can set up your debugging session as needed before proceeding.
FILES
/System/Library/Extensions The standard system repository of kernel extensions
directoryname/Caches/* Cache files for a given directory of kernel extensions
/var/run/mach.sym The symbol file for the running kernel, written by kextd(8) at system startup.
/mach_kernel The default kernel file, used for linking as a last resort.
DIAGNOSTICS
kextload exits with a zero status upon success. Upon failure, it prints an error message and continues process-
ing any kexts if possible, then exits with a nonzero status.
For a kext to be loadable, it must be valid, authentic, have all dependencies met (that is, all dependencies
must be found and loadable). A valid kext has a well formed bundle, info dictionary, and executable. An
authentic kext's component files are owned by root:wheel, with permissions nonwritable by group and other. If
your kext fails to load, try using the -t option to print diagnostics related to validation and authentication.
Also, of course, the executable must contain code for the host machine's architecture and link successfully.
However, since this is expensive to do, these checks are not made unless the kext is actually being linked. You
can confirm these aspects of loadability by attempting to generate symbol files using the -s option.
SEE ALSO
kextcache(8), kextd(8), kextstat(8), kextunload(8)
BUGS
Upon encountering a kext with validation errors, kextload typically prints an error message about that kext,
even if it isn't involved in the load request.
