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-idoption. -aidentifier@address,-addressidentifier@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-loadoption. See also-use-load-addressesand-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-loadoption. See also-addressand-no-load. -bidentifier,-bundle-ididentifier- 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-repositoryoptions 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,
kextutilattempts to use cache files and (when running as root) to create them if they are out of date or don't exist. -dkext,-dependencykext- 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-extensionsand-repositoryoptions. -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
-dependencyand-repositoryoptions. 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.
-kkernel_file,-kernelkernel_file- Link against the given kernel_file. Allowed only
with the
-no-loadoption to generate debug symbols. By defaultkextutilattempts 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-onlyand 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
-symbolsoption, or when diagnosing kexts with the-print-diagnosticsoption. For convenience in development, this option implies the-no-authenticationoption. See also the-addressand-use-load-addressesoptions. -ppersonality,-personalitypersonality- Send only the named personalities from the kext to the kernel. Repeat for
each personality desired, or use the
-interactiveoption to havekextutilask for each personality. -q,-quiet- Quiet mode; print no informational or error messages. If
kextutilis run with-quietin a way that might require user interaction, as with the-interactiveand-interactive-alloptions, and some uses of-no-load, the program silently exits with an error status. -rdirectory,-repositorydirectory- 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-idoption. 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-dependencyand-no-system-extensionsoptions. -sdirectory,-symbolsdirectory- 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
kextutilprints 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
kextutilimplicitly 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
kextutilas 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-cachesoption.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-loadand-print-diagnosticsoptions to test a kext for problems. It is not allowed with the-symbolsoption 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)