Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for kextload (opendarwin section 8)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


KEXTLOAD(8)			   BSD System Manager's Manual			      KEXTLOAD(8)

NAME
     kextload -- loads, validates, and generates symbols for a kernel extension (kext)

SYNOPSIS
     kextload [-h] [ -v [0-6] | -q ] [-t] [-i | -I] [-x] [-z] [-e] [-c] [-D] [-k kernel_file]
	      [-d extension] ...  [-r directory] ...  [ -l | -m | -n | -A | -a kext_id@address ]
	      ...  [-s directory] [-p personality] ...	[-b -bundle_id] ...  [--] [extension] ...

DESCRIPTION
     The kextload program is used to explicitly load kernel extensions (kexts), validate them to
     see that they can be loaded by other mechanisms, such as kextd(8), and to generate symbol
     files for debugging the kext in a running kernel.	In order to load a kext into the kernel
     kextload must be invoked as the superuser; for all other uses it can be invoked by any user.

     kextload is a formal interface for kext loading in the Darwin OS and in Mac OS X.	Software
     and installers can rely on its presence and invoke it in order to load kexts.

     kextload has many options, but most of them are rarely necessary.	See the EXAMPLES section
     for tips on common uses.  The arguments and options available are these:

     extension
	      The pathname of a kext bundle to load or otherwise use.  Kexts can also be speci-
	      fied by CFBundleIdentifier with the -b option.

     -a kext_id@address
	      Treat the kext whose CFBundleIdenfier is kext_id as being loaded at address when
	      generating symbol files and not loading.	When generating symbols only, all depen-
	      dencies must have known addresses.  Use this option repeatedly for every nonkernel
	      dependency.  This option implies the use of the -n option. See also -A and -n.

     -A       When generating symbol files and not loading, look up all dependency kext addresses
	      within the running kernel.  This option implies the use of the -n option. See also
	      -a and -n.

     -b bundle_id
	      Look up the kext whose CFBundleIdentifier is bundle_id within the set of known
	      kexts and load it.  See the -d, -e, and -r options for more information.

     -c       Ignore any repository cache files and scan all kext bundles to gather information.
	      If this option is not given, kextload will attempt to use cache files and to create
	      them if they are out of date or don't exist.

     -d extension
	      Add extension to the set of known kexts for resolving dependencies.  This is useful
	      for adding a single kext from a directory while excluding the others.  See the -e
	      and -r options for more information.

     -D       Don't check the kernel for already loaded kexts when resolving dependencies.  This
	      behavior is now the default and so this option is deprecated and redundant.  Note
	      that this can result in load failures if a different version of a dependency is
	      already loaded.  This option is relevant only when loading a kext into the kernel.
	      The -A option overrides this option as it must check the kernel for which kexts are
	      loaded.

     -e       Don't use the contents of /System/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 -d and -r options.

     -h       Print a help message describing each option flag.

     -i       Interactive mode; pause at each stage of loading for user input to continue.  This
	      allows for debugger setup when the kext needs to be debugged during its earliest
	      stages of running.

     -I       (capital i) Interactive mode as -i for the specified kext and all of its dependen-
	      cies.

     -k kernel_file
	      Link against the given kernel_file (default is /mach).  Allowed only with the -n
	      option to generate debug symbols.

     -l       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.

     -L       Same as -r (remains for backward compatibility).

     -m       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 -l and after setting up the
	      debugger.

     -n       Neither load the kext nor send personalities to the kernel.  This option is for use
	      when generating debug symbols only with the -s option, or when validating kexts
	      with the -t option.  See also the -a and - A options.

     -p personality
	      Send only the named personalities from the kext to the kernel. Repeat for each per-
	      sonality desired, or use the -i option to have kextload ask for each personality.

     -q       Quiet mode; print no informational or error messages.  This option excludes -v.  If
	      kextload is run with -q in a way that might require user interaction, as with the
	      -i and -I options, and some uses of -n, the program will silently exit with an
	      error status.

     -r 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 -b
	      option.  This is not recursive; only the directory's immediate contents are
	      scanned.	See also the -c, -d, and -e options.

     -s directory
	      Write all generated symbol files into directory.	The directory must already exist.
	      Symbol files are named after the CFBundleIdentifier of each kexts with a .sym suf-
	      fix appended.

     -t       Perform all possible tests on the named kext(s) 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.

     -v [1-6]
	      Verbose mode; print information about the kext scanning and loading process. Higher
	      levels of verbosity include all lower levels.  The levels of verbose output are
	      these:

	      0    suppresses informational messages (errors are still printed); see also -q

	      1    prints basic kext scanning information

	      2    prints basic load information

	      3    prints detailed kext scanning information

	      4    prints basic information on every kext encountered

	      5    prints detailed information on every kext encountered

	      6    prints detailed load information
	      If -v is not specified only the essential information about the load operation is
	      printed (such as whether the kext was already  loaded).

	      A kext can also specify verbose printing for just itself using the OSBundleDebu-
	      gLevel top-level info dictionary property.  Its values are 1 and 2, for basic and
	      detailed information, respectively.

	      This option excludes - q .

     -x       Run kextload 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, or those in which every personality contains a nonzero IOKitDebug prop-
	      erty, will not load.  This option implies the use of the -c option.

     -z       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       Don't try to resolve dependencies.  This option is allowed only when using the -n
	      and -t options to test a kext for problems.  It is not allowed with the -s 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 kextload.

   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 CFBundleIdentifier.  Adding repository directories with the -r option or individ-
     ual 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 prob-
     lems 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/Exten-
     sions 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 depen-
     dencies.

	       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 auto-
     matically 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 /Sys-
     tem/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 successful
     load.  When not loading, however, it always chooses the most recent versions of any depen-
     dencies.

     If you want to have complete control over the set of extensions used to resolve dependen-
     cies, use the -e, -d, and -r options.  The -e option excludes the standard /Sys-
     tem/Library/Extensions folder, leaving the set of candidate extensions for dependency reso-
     lution 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 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
     kextload on; you can use the -k option to indicate a different kernel 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 personalities and then to ask you for each person-
     ality 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 exe-
     cuting.  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 significant 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.kextcache	 A cache of all kext info dictionaries (plists) for a given
				 directory

DIAGNOSTICS
     kextload exits with a zero status upon success.  Upon failure, it prints an error message
     and continues processing any kexts if possible, then exits with a nonzero status.

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.

Darwin					February 22, 2002				   Darwin
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:39 PM.