KEXTUTIL(8) System Manager's Manual KEXTUTIL(8)
NAME
kextutil – load, diagnose problems with, and generate symbols for kernel
extensions (kexts)
SYNOPSIS
kextutil [options] [--] [kext] ...
DEPRECATED
The kextutil utility has been deprecated. Please use the kmutil(8)
equivalents: kmutil load, or kmutil print-diagnostics.
DESCRIPTION
The kextutil program is used to explicitly load kernel extensions (kexts),
diagnose problems with kexts, and to generate symbol files for debugging
kexts. In order to load a kext into the kernel kextutil must run as the
superuser; for all other uses it can run as any user.
kextutil is the developer utility for kext loading in the Darwin OS and in
macOS. Software and installers should use kextload(8) instead of this
program.
The arguments and options available are these:
kext The pathname of a kext bundle to load or otherwise use. Kexts can
also be specified by CFBundleIdentifier with the -bundle-id
option.
-a identifier@address, -address identifier@address
Treat the kext whose CFBundleIdenfier is identifier as being
loaded at address when generating symbol files and not loading.
When generating symbols, any dependencies with unspecified
addresses are skipped. Use this option repeatedly to name every
nonkernel dependency for which you want symbols. This option
implies the use of the -no-load option. See also
-use-load-addresses and -no-load.
-arch Use the specified architecture for generating symbols and
performing tests. If loading into the kernel or getting load
addresses from the kernel, the specified arch must match that of
the running kernel.
-A, -use-load-addresses
When generating symbol files and not loading, look up all
dependency kext addresses within the running kernel. This option
implies the use of the -no-load option. See also -address and
-no-load.
-b identifier, -bundle-id identifier
Look up the kext whose CFBundleIdentifier is identifier within the
set of known kexts and load it. The kext of the highest
CFBundleVersion with the given identifier is used; in the case of
version ties, the last such kext specified on the command line is
used. See the -dependency, -no-system-extensions, and -repository
options for more information.
-c, -no-caches
Ignore any repository cache files and scan all kext bundles to
gather information. If this option is not given, kextutil
attempts to use cache files and (when running as root) to create
them if they are out of date or don't exist.
-d kext, -dependency kext
Add kext and its plugins to the set of known kexts for resolving
dependencies. This is useful for adding a single kext from a
directory. See “Explicitly Specifying Dependencies” for more
information, as well as the -no-system-extensions and -repository
options.
-e, -no-system-extensions
Don't use the contents of /System/Library/Extensions/ or
/Library/Extensions/ as the default repository of kexts. If you
use this option you will have to explicitly specify all
dependencies of the kext being loaded or otherwise worked on using
the -dependency and -repository options. See “Explicitly
Specifying Dependencies” for more information.
-h, -help
Print a help message describing each option flag and exit with a
success result, regardless of any other options on the command
line.
-i, -interactive
Interactive mode; pause after loading each specified kext and wait
for user input to start the kext and send its personalities to the
kernel. This allows for debugger setup when the kext needs to be
debugged during its earliest stages of running.
-I, -interactive-all
Interactive mode, as described above, for each specified kext and
all of their dependencies.
-k kernel_file, -kernel kernel_file
Link against the given kernel_file. Allowed only with the
-no-load option to generate debug symbols. By default kextutil
attempts to get link symbols from the kernel at
/System/Library/Kernels/kernel.
-l, -load-only
Load and start the kext only; don't send I/O Kit personalities to
the kernel to begin matching. Matching may still occur if the
personalities are present from an earlier load operation. You may
want to use kextunload(8) before loading a kext with this option.
-m, -match-only
Don't load the kext, but do send its personalities to the kernel
to begin matching. Use this option after you have loaded a driver
with -load-only and after setting up the debugger.
-n, -no-load
Neither load the kext nor send personalities to the kernel. This
option is for use when generating debug symbols only with the
-symbols option, or when diagnosing kexts with the
-print-diagnostics option. For convenience in development, this
option implies the -no-authentication option. See also the
-address and -use-load-addresses options.
-p personality, -personality personality
Send only the named personalities from the kext to the kernel.
Repeat for each personality desired, or use the -interactive
option to have kextutil ask for each personality.
-q, -quiet
Quiet mode; print no informational or error messages. If kextutil
is run with -quiet in a way that might require user interaction,
as with the -interactive and -interactive-all options, and some
uses of -no-load, the program silently exits with an error status.
-r directory, -repository directory
Use directory as a repository of kexts. This adds to the set of
known kexts for resolving dependencies or looking up by
CFBundleIdentifier when using the -bundle-id option. This is not
recursive; only the directory's immediate contents (and their
plugins) are scanned. See “Explicitly Specifying Dependencies”
for more information, as well as the -dependency and
-no-system-extensions options.
-s directory, -symbols directory
Write all generated symbol files into directory. The directory
must already exist. Symbol files are named after the
CFBundleIdentifier of each kext with a .sym suffix appended.
-t, -print-diagnostics
Perform all possible tests on the specified kexts, even with
options that implicitly disable some tests, and indicate whether
the kext is loadable, or if not, what problems it has. Note that
tests are performed in three stages, validation, authentication,
and dependency resolution; a failure at any stage can make tests
in further stages impossible. Thus, a kext with validation
failures may have unreported authentication problems or missing
dependencies. Additionally, some tests require being run as root.
-v [0-6 | 0x####], -verbose [0-6 | 0x####]
Verbose mode; print information about program operation. Higher
levels of verbosity include all lower levels. By default kextutil
prints only warnings and errors. You can specify a level from
0-6, or a hexadecimal log specification (as described in
kext_logging(8)). The levels of verbose output are:
0 Print only errors (that is, suppress warnings); see
also -quiet.
1 (or none) Print basic information about program operation.
2 Print basic information about the link/load
operation.
3 Print more information about user-kernel interaction,
link/load operation, and processing of I/O Kit
Personalities.
4 Print detailed information about module start and C++
class construction.
5 Print internal debug information, including checks
for loaded kexts.
6 Identical to level 5 but for all kexts read by the
program.
To ease debug loading of kexts, the verbose levels 1-6 in kextutil
implicitly set the OSBundleEnableKextLogging property for each
kext specified on the command line to true. See kext_logging(8)
for more information on verbose logging.
-x, -safe-boot
Run kextutil as if in safe boot mode (indicating startup with the
Shift key held down). Kexts that don't specify a proper value for
the OSBundleRequired info dictionary property will not load. This
option implies the use of the -no-caches option.
Note that if the system has actually started up in safe boot mode,
this option is redundant. There is no way to simulate non-safe
boot mode for a system running in safe boot mode.
-z, -no-authentication
Don't authenticate kexts. This option is for convenience during
development, and is allowed only for operations that don't
actually load a kext into the kernel (such as when generating
symbols).
-Z, -no-resolve-dependencies
Don't try to resolve dependencies. This option is allowed only
when using the -no-load and -print-diagnostics options to test a
kext for problems. It is not allowed with the -symbols option as
generating symbols requires dependencies to be resolved.
-- End of all options. Only kext names follow.
EXAMPLES
Here are the common uses and usage patterns for kextutil.
Basic Loading
To load a kext you must run kextutil as the superuser and supply a kext
bundle name; no options are required:
kextutil TabletDriver.kext
Alternatively, you can use the -bundle-id (-b) option to specify a kext by
its CFBundleIdentifier:
kextutil -b com.mycompany.driver.TabletDriver
With no additional options kextutil looks in /System/Library/Extensions/
and /Library/Extensions/ for a kext with the given CFBundleIdentifier.
Adding repository directories with the -repository (-r) option or
individual kexts with the -dependency (-d) option expands the set of kexts
that kextutil looks among:
kextutil -r ${USER}/Library/Extensions TabletDriver.kext
Diagnosing Kexts
kextutil prints diagnostic information about kexts by default, but some
options cause certain tests to be skipped. The ensure that all tests are
performed, use the -print-diagnostics (-t) option.
The -print-diagnostics option is typically used with -no-load (-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
-no-system-extensions (-e) and -no-resolve-dependencies (-Z) options to
omit the /System/Library/Extensions/ and /Library/Extensions/ repositories
and to suppress dependency resolution, respectively:
kextutil -entZ PacketSniffer.kext
Only validation and authentication checks are performed.
Generating Debug Symbols When Loading
To generate a symbol file for use with gdb when loading a kext, use the
-symbols (-s) option to specify a directory where symbol files will be
written for the kext being loaded and all its dependencies.
kextutil -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 -symbols (-s) option along with
the -no-load (-n) option. Since in this case addresses must be known for
the kext and all its dependencies, though, you must specify them. If you
don't indicate them on the command line, kextutil asks for the load address
of each kext needed. To get these addresses you can use kextstat(8) on the
machine you're generating symbols for, the showallkmods gdb(1) macro
defined by the kgmacros file in the Kernel Development Kit, or consult a
panic backtrace.
kextutil -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 -address (-a) option for each kext (you needn't specify
-no-load when using the -address option):
kextutil -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 kextutil on the same machine
as the loaded kext, is to use the -use-load-addresses (-A) option, which
checks with the kernel for all loaded kexts and automatically gets their
load addresses.
kextutil -s ~/ksyms -A GrobbleEthernet.kext
Explicitly Specifying Dependencies
Because kextutil resolves dependencies automatically, it's possible that a
kext other than the one you intend might get used as a dependency (as when
there are multiple copies of the same version, or if you're working with a
different version of a kext that's already in /System/Library/Extensions/).
By default, when loading a kext into the kernel, kextutil checks which
versions of possible dependencies are already loaded in order to assure a
successful load. When not loading and not using -use-load-addresses,
however, it always chooses the highest versions of any dependencies, and in
the case of a tie it chooses from kexts specified on the command line using
the -dependency or -repository options, or as command line arguments (in
decreasing order of priority).
For precise control over the set of extensions used to resolve
dependencies, use the -no-system-extensions (-e) option along with the
-dependency (-d), and -repository (-r) options. The -no-system-extensions
option excludes the standard /System/Library/Extensions/ and
/Library/Extensions/ directories, leaving the set of candidate extensions
for dependency resolution entirely up to you. To specify candidate
dependencies you use either -dependency (-d), which names a single kext as
a candidate, or -repository (-r), which adds an entire directory of
extensions.
kextutil -n -s ~/ksyms -e \
-d /System/Library/Extensions/System.kext \
-r ~/TestKexts -d JoystickSupport.kext JoystickDriver.kext
Note also that if you use -no-system-extensions (-e), you must supply at
least some version of System.kext in order to supply information 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 kextutil on;
you can use the -kernel (-k) option to specify a different kernel file.
You may also need to explicitly specify other library or family kexts.
Debug Loading an I/O Kit Driver
Pure I/O Kit driver kexts have empty module-start routines, but trigger
matching and driver instance creation on load. If you need to debug an I/O
Kit driver's early startup code, you can load the driver on the target
machine without starting matching by using the -load-only (-l) option:
kextutil -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
kextutil again on the target machine with the -match-only (-m) option:
kextutil -m DiskController.kext
You may wish to use the -personality (-p) option as well in order to send
selected personalities to the kernel. Alternatively, you can use the
-interactive (-i) option for the whole process, which causes kextutil to
pause just before loading any personalities and then to ask you for each
personality whether that one should be sent to the kernel:
kextutil -i DiskController.kext
DiskController.kext appears to be loadable (not including linkage
for on-disk libraries).
Load DiskController.kext and its dependencies into the kernel [Y/n]? y
Loading DiskController.kext.
DiskController.kext successfully loaded (or already loaded).
DiskController.kext and its dependencies are now loaded,
but not started (unless they were already running).
You may now set breakpoints in the debugger before starting them.
start DiskController.kext [Y/n]? y
DiskController.kext started.
send personalities for DiskController.kext [Y/n]? y
send personality Test Match Personality [Y/n]? y
Debug Loading a Kext with a Module-Start Routine
In order to debug a kext's module-start routine, you must use the
-interactive (-i) or -interactive-all (-I) option, which pause after
loading and before calling the module-start function, so that you can set
up your debugging session as needed before proceeding.
FILES
/System/Library/Extensions/ The standard system repository of kernel
extensions.
/Library/Extensions/ The standard repository of non Apple kernel
extensions.
/System/Library/Caches/com.apple.kext.caches/*
Contains all kext caches for a Mac OS X 10.6
(Snow Leopard) system: prelinked kernel,
mkext, and system kext info caches.
/System/Library/Kernels/kernel
The default kernel file.
DIAGNOSTICS
kextutil exits with a zero status upon success. Upon failure, it prints an
error message and continues processing remaining 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
-print-diagnostics (-t) option to print diagnostics related to validation
and authentication.
BUGS
Many single-letter options are inconsistent in meaning with (or directly
contradictory to) the same letter options in other kext tools.
SEE ALSO
kmutil(8), kernelmanagerd(8), kextcache(8), kextd(8), kextload(8),
kextstat(8), kextunload(8), kext_logging(8)
Darwin November 14, 2012 Darwin