Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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 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 dependen-cies dependencies
              cies 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 match-ing. matching.
              ing.  Matching may still occur if the personalities are present from an earlier load opera-tion. operation.
              tion.  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 gen-erating generating
              erating 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 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 resolu-tion; resolution;
              tion; 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.

     -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 lev-els levels
              els 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-authenticate
              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 reso-lution, resolution,
     lution, 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 automat-ically automatically
     ically 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 candi-date, candidate,
     date, 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: pre-linked prelinked
                                  linked 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 dependencies met (that is, all depen-dencies dependencies
     dencies must be found and loadable).  A valid kext has a well formed bundle, info dictionary, and exe-cutable. executable.
     cutable.  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
     kextcache(8), kextd(8), kextload(8), kextstat(8), kextunload(8), kext_logging(8)

Darwin                         November 14, 2012                        Darwin