manpagez: man pages & more
man kextutil(8)
Home | html | info | man
kextutil(8)               BSD System Manager's Manual              kextutil(8)


NAME

     kextutil -- load, diagnose problems with, and generate symbols for kernel
     extensions (kexts)


SYNOPSIS

     kextutil [options] [--] [kext] ...


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 Mac OS X.  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 per-
              forming 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 depen-
              dency 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 depen-
              dencies 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 /mach_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-authenticate 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 CFBundleI-
              dentifier 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, authenti-
              cation, and dependency resolution; a failure at any stage can
              make tests in further stages impossible.  Thus, a kext with val-
              idation failures may have unreported authentication problems or
              missing dependencies.

     -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 opera-
                           tion.

              3            Print more information about user-kernel interac-
                           tion, 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-authenticate
              Don't authenticate kexts.  This option is for convenience during
              development, and is allowed only for operations that don't actu-
              ally load a kext into the kernel (such as when generating sym-
              bols).

     -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 indi-
     vidual 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/ reposito-
     ries 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 automati-
     cally 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 dependen-
     cies, 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 tar-
     get 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.
     /mach_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 depen-
     dencies 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 permis-
     sions 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

     kextcache(8), kextd(8), kextload(8), kextstat(8), kextunload(8),
     kext_logging(8)

Darwin                         November 14, 2012                        Darwin

Mac OS X 10.9 - Generated Fri Oct 18 05:36:22 CDT 2013
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.