Manual Pages for UNIX Darwin command on man kextload

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

NAME

kkeexxttllooaadd - loads, validates, and generates symbols for a kernel exten-

sion (kext)

SYNOPSIS

kkeexxttllooaadd [-hh] [ -vv [0-6] | -qq ] [-tt] [-ii | -II] [-xx] [-zz] [-ee] [-cc] [-DD]

[-kk kernelfile] [-dd extension] ... [-rr directory] ... [ -ll |

-mm | -nn | -AA | -aa kextid@address ] ... [-ss directory]

[-pp personality] ... [-bb bundleid] ... [--] [extension] ...

DESCRIPTION

The kkeexxttllooaadd program is used to explicitly load kernel extensions

(kexts), validate them to see that they can be loaded by other mecha-

nisms, 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 kkeexxttllooaadd must be invoked as the superuser; for all other uses it can be invoked by any user. kkeexxttllooaadd 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. kkeexxttllooaadd 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 specified by CFBundleIdentifier with the -bb option.

-aa kextid@address

Treat the kext whose CFBundleIdenfier is kextid as being loaded at address when generating symbol files and not loading. When generating symbols only, all dependencies must have known addresses. Use this option repeatedly for every nonkernel

dependency. This option implies the use of the -nn option. See

also -AA and -nn.

-AA 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 -nn option. See also -aa and -nn.

-bb bundleid

Look up the kext whose CFBundleIdentifier is bundleid within

the set of known kexts and load it. See the -dd, -ee, and -rr

options for more information.

-cc Ignore any repository cache files and scan all kext bundles to

gather information. If this option is not given, kkeexxttllooaadd will attempt to use cache files and to create them if they are out of date or don't exist.

-dd extension

Add extension to the set of known kexts for resolving dependen-

cies. This is useful for adding a single kext from a directory

while excluding the others. See the -ee and -rr options for more

information.

-DD 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 -AA option overrides this option as it

must check the kernel for which kexts are loaded.

-ee 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 -dd and -rr options.

-hh Print a help message describing each option flag.

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

-II (capital i) Interactive mode as -ii for the specified kext and

all of its dependencies.

-kk kernelfile

Link against the given kernelfile. Allowed only with the -nn

option to generate debug symbols. By default kkeexxttllooaadd attempts to get link symbols from the running kernel, /var/run/mach.sym, and /machkernel, in that order (the UUIDs must match that of the running kernel

for the disk-based files).

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

-LL Same as -rr (remains for backward compatibility).

-mm 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 -ll and after setting up the debugger.

-nn Neither load the kext nor send personalities to the kernel.

This option is for use when generating debug symbols only with

the -ss option, or when validating kexts with the -tt option. See

also the -aa and - A options.

-pp personality

Send only the named personalities from the kext to the kernel.

Repeat for each personality desired, or use the -ii option to

have kkeexxttllooaadd ask for each personality.

-qq Quiet mode; print no informational or error messages. This

option excludes -vv. If kkeexxttllooaadd is run with -qq in a way that

might require user interaction, as with the -ii and -II options,

and some uses of -nn, the program will silently exit with an

error status.

-rr 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 -bb option. This is not recur-

sive; only the directory's immediate contents are scanned. See

also the -cc, -dd, and -ee options.

-ss directory

Write all generated symbol files into directory. The directory

must already exist. Symbol files are named after the CFBundleI-

dentifier of each kexts with a .sym suffix appended.

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

-vv [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 -qq

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 -vv 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 OSBundleDebugLevel top-level info dictionary property. Its

values are 1 and 2, for basic and detailed information, respec-

tively.

This option excludes - q .

-xx Run kkeexxttllooaadd 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 property,

will not load. This option implies the use of the -cc option.

-zz 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).

-ZZ Don't try to resolve dependencies. This option is allowed only

when using the -nn and -tt options to test a kext for problems.

It is not allowed with the -ss option as generating symbols

requires dependencies to be resolved.

-- End of all options. Only kext names follow.

EEXXAAMMPPLLEESS Here are the common uses and usage patterns for kkeexxttllooaadd. BBaassiicc llooaaddiinngg To load a kext you must run kkeexxttllooaadd as the superuser and supply a kext bundle name; no options are required:

kextload TabletDriver.kext

Alternatively, you can use the -bb option to specify a kext by its

CFBundleIdentifier:

kextload -b com.mycompany.driver.TabletDriver

With no additional options kkeexxttllooaadd will look in /System/Library/Exten-

sions for a kext with the given CFBundleIdentifier. Adding repository

directories with the -rr option or individual kexts with the -dd option

expands the set of kexts that kkeexxttllooaadd 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 -xx 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.)

VVaalliiddaattiinngg KKeexxttss

The -tt option causes kkeexxttllooaadd to perform all possible validation and

authentication checks on the specified kexts and to attempt to resolve their dependencies. If there are any problems with the specified kexts, kkeexxttllooaadd prints a list of the problems.

The -tt option is typically used with -nn 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 -ee and -ZZ

options to omit the /System/Library/Extensions repository and to suppress dependency resolution, respectively:

kextload -entZ PacketSniffer.kext

Only validation and authentication checks will be performed. GGeenneerraattiinngg DDeebbuugg SSyymmbboollss WWhheenn LLooaaddiinngg To generate a symbol file for use with gdb when loading a kext, use the

-ss option to specify a directory where symbol files will be written for

the kext being loaded and all its dependencies.

kextload -s ~/ksyms PacketSniffer.kext

GGeenneerraattiinngg DDeebbuugg SSyymmbboollss FFoorr aann AAllrreeaaddyy-LLooaaddeedd KKeexxtt

If you want to generate symbols for a kext that's already loaded, whether

on the same system or on another, use the -ss option along with the -nn

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, kkeexxttllooaadd will ask you for the load address of

each kext needed. Use kextstat(8) on the machine you're generating sym-

bols 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 -aa option for each kext (you needn't specify -nn when using

the -aa 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 kkeexxttllooaadd on the same

machine as the loaded kext, is to use the -AA option, which checks with

the kernel for all loaded kexts and automatically gets their load addresses.

kextload -s ~/ksyms -A GrobbleEthernet.kext

EExxpplliicciittllyy SSppeecciiffyyiinngg DDeeppeennddeenncciieess Because kkeexxttllooaadd 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 ver-

sion of a kext that's already installed in /System/Library/Extensions). By default, when loading a kext into the kernel kkeexxttllooaadd 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 dependencies. If you want to have complete control over the set of extensions used to

resolve dependencies, use the -ee, -dd, and -rr options. The -ee option

excludes the standard /System/Library/Extensions folder, leaving the set of candidate extensions for dependency resolution entirely up to you. To

specify candidate dependencies you use either -dd, which names a single

kext as a candidate, or -rr, 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 -ee, you must supply some version of the Sys-

tem.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 kkeexxttllooaadd on; you

can use the -kk option to indicate a different kernel file.

DDeebbuugg-LLooaaddiinngg aann II//OO KKiitt DDrriivveerr

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 -ll 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

kkeexxttllooaadd again on the target machine with the -mm option:

kextload -m DiskController.kext

You may wish to use the -pp option as well in order to send selected per-

sonalities to the kernel. Alternatively, you can use the -ii option for

the whole process, which causes kkeexxttllooaadd to pause just before loading any personalities and then to ask you for each personality whether that one should be sent to the kernel:

kextload -i DiskController.kext

DDeebbuugg-LLooaaddiinngg aa nnoonn-II//OO KKiitt KKeexxtt

A non-I/O Kit kext doesn't have a personality-matching phase of loading;

it just starts executing. In order to debug a non-I/O Kit kext's startup

code, you must use the -ii or -II option, which pauses loading at each sig-

nificant 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/Caches/* Cache files for a given directory of kernel extensions

/var/run/mach.sym The symbol file for the running kernel, writ-

ten by kextd(8) at system startup. /machkernel The default kernel file, used for linking as a last resort. DIAGNOSTICS kkeexxttllooaadd 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.

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 -tt option to print diagnostics related to validation and

authentication. Also, of course, the executable must contain code for the host machine's architecture and link successfully. However, since this is expensive to do, these checks are not made unless the kext is actually being linked. You can confirm these aspects of loadability by attempting to generate

symbol files using the -ss option.

BUGS

Upon encountering a kext with validation errors, kkeexxttllooaadd typically prints an error message about that kext, even if it isn't involved in the load request. Darwin February 22, 2002 Darwin