1.Dd November 14, 2012 2.Os Darwin 3.Dt KEXTUTIL 8 4.Sh NAME 5.Nm kextutil 6.Nd load, diagnose problems with, and generate symbols for kernel extensions (kexts) 7.Sh SYNOPSIS 8.Nm 9.Op Ar options 10.Op Fl - 11.Op Ar kext 12.Li \&.\|.\|. 13.Sh DESCRIPTION 14The 15.Nm 16program is used to explicitly load kernel extensions (kexts), 17diagnose problems with kexts, 18and to generate symbol files for debugging kexts. 19In order to load a kext into the kernel 20.Nm 21must run as the superuser; 22for all other uses it can run as any user. 23.Pp 24.Nm 25is the developer utility for kext loading in the Darwin OS and 26in Mac OS X. 27Software and installers should use 28.Xr kextload 8 29instead of this program. 30.Pp 31The arguments and options available are these: 32.Bl -tag -width -indent 33.It Ar kext 34The pathname of a kext bundle to load or otherwise use. 35Kexts can also be specified by CFBundleIdentifier with the 36.Fl bundle-id 37option. 38.It Fl a Ar identifier@address , Fl address Ar identifier@address 39Treat the kext whose CFBundleIdenfier is 40.Ar identifier 41as being loaded at 42.Ar address 43when generating symbol files and not loading. 44When generating symbols, 45any dependencies with unspecified addresses are skipped. 46Use this option repeatedly to name every nonkernel dependency 47for which you want symbols. 48This option implies the use of the 49.Fl no-load 50option. See also 51.Fl use-load-addresses 52and 53.Fl no-load . 54.It Fl arch 55Use the specified architecture for generating symbols 56and performing tests. 57If loading into the kernel or getting load addresses from the kernel, 58the specified arch must match that of the running kernel. 59.It Fl A , Fl use-load-addresses 60When generating symbol files and not loading, 61look up all dependency kext addresses within the running kernel. 62This option implies the use of the 63.Fl no-load 64option. See also 65.Fl address 66and 67.Fl no-load . 68.It Fl b Ar identifier , Fl bundle-id Ar identifier 69Look up the kext whose CFBundleIdentifier is 70.Ar identifier 71within the set of known kexts and load it. 72The kext of the highest CFBundleVersion with the given identifier is used; 73in the case of version ties, 74the last such kext specified on the command line is used. 75See the 76.Fl dependency , 77.Fl no-system-extensions , 78and 79.Fl repository 80options for more information. 81.It Fl c , Fl no-caches 82Ignore any repository cache files and scan all kext bundles 83to gather information. 84If this option is not given, 85.Nm 86attempts to use cache files and (when running as root) to create them 87if they are out of date or don't exist. 88.It Fl d Ar kext , Fl dependency Ar kext 89Add 90.Ar kext 91and its plugins to the set of known kexts for resolving dependencies. 92This is useful for adding a single kext from a directory. 93See 94.Dq Explicitly Specifying Dependencies 95for more information, as well as the 96.Fl no-system-extensions 97and 98.Fl repository 99options. 100.It Fl e , Fl no-system-extensions 101Don't use the contents of 102.Pa /System/Library/Extensions/ 103or 104.Pa /Library/Extensions/ 105as the 106default repository of kexts. 107If you use this option you will have to explicitly specify 108all dependencies of the kext being loaded 109or otherwise worked on using the 110.Fl dependency 111and 112.Fl repository 113options. 114See 115.Dq Explicitly Specifying Dependencies 116for more information. 117.It Fl h , Fl help 118Print a help message describing each option flag and exit with a success result, 119regardless of any other options on the command line. 120.It Fl i , interactive 121Interactive mode; pause after loading each specified kext and 122wait for user input to start the kext and 123send its personalities to the kernel. 124This allows for debugger setup when the kext needs 125to be debugged during its earliest stages of running. 126.It Fl I , Fl interactive-all 127Interactive mode, as described above, 128for each specified kext and all of their dependencies. 129.It Fl k Ar kernel_file , Fl kernel Ar kernel_file 130Link against the given 131.Ar kernel_file . 132Allowed only with the 133.Fl no-load 134option to generate debug symbols. 135By default 136.Nm 137attempts to get link symbols from the kernel at /System/Library/Kernels/kernel. 138.It Fl l , Fl load-only 139Load and start the kext only; don't send I/O Kit personalities 140to the kernel to begin matching. 141Matching may still occur if the personalities are present from 142an earlier load operation. 143You may want to use 144.Xr kextunload 8 145before loading a kext with this option. 146.It Fl m , Fl match-only 147Don't load the kext, but do send its personalities to the kernel 148to begin matching. 149Use this option after you have loaded a driver with 150.Fl load-only 151and after setting up the debugger. 152.It Fl n , Fl no-load 153Neither load the kext nor send personalities to the kernel. 154This option is for use when generating debug symbols only 155with the 156.Fl symbols 157option, 158or when diagnosing kexts with the 159.Fl print-diagnostics 160option. 161For convenience in development, this option implies the 162.Fl no-authentication 163option. 164See also the 165.Fl address 166and 167.Fl use-load-addresses 168options. 169.It Fl p Ar personality , Fl personality Ar personality 170Send only the named personalities from the kext to the 171kernel. Repeat for each personality desired, or use the 172.Fl interactive 173option to have 174.Nm 175ask for each personality. 176.It Fl q , Fl quiet 177Quiet mode; print no informational or error messages. 178If 179.Nm 180is run with 181.Fl quiet 182in a way that might require user interaction, 183as with the 184.Fl interactive 185and 186.Fl interactive-all 187options, 188and some uses of 189.Fl no-load , 190the program silently exits with an error status. 191.It Fl r Ar directory , Fl repository Ar directory 192Use 193.Ar directory 194as a repository of kexts. 195This adds to the set of known kexts for resolving dependencies 196or looking up by CFBundleIdentifier when using the 197.Fl bundle-id 198option. 199This is not recursive; only the directory's immediate 200contents (and their plugins) are scanned. 201See 202.Dq Explicitly Specifying Dependencies 203for more information, as well as the 204.Fl dependency 205and 206.Fl no-system-extensions 207options. 208.It Fl s Ar directory , Fl symbols Ar directory 209Write all generated symbol files into 210.Ar directory . 211The directory must already exist. 212Symbol files are named after the CFBundleIdentifier 213of each kext with a 214.Pa .sym 215suffix appended. 216.It Fl t , Fl print-diagnostics 217Perform all possible tests on the specified kexts, 218even with options that implicitly disable some tests, 219and indicate whether the kext is loadable, or if not, what problems it has. 220Note that tests are performed in three stages, validation, 221authentication, and dependency resolution; a failure at any 222stage can make tests in further stages impossible. 223Thus, a kext with validation failures may have unreported 224authentication problems or missing dependencies. 225.It Fl v Li [ 0-6 | 0x#### Ns Li ] , Fl verbose Li [ 0-6 | 0x#### Ns Li ] 226Verbose mode; print information about program operation. 227Higher levels of verbosity include all lower levels. 228By default 229.Nm 230prints only warnings and errors. 231You can specify a level from 0-6, 232or a hexadecimal log specification 233(as described in 234.Xr kext_logging 8 Ns No ). 235The levels of verbose output are: 236.Bl -tag -width "1 (or none)" 237.It 0 238Print only errors (that is, suppress warnings); see also 239.Fl quiet . 240.It 1 (or none) 241Print basic information about program operation. 242.It 2 243Print basic information about the link/load operation. 244.It 3 245Print more information about user-kernel interaction, link/load operation, 246and processing of I/O Kit Personalities. 247.It 4 248Print detailed information about module start and C++ class construction. 249.It 5 250Print internal debug information, including checks for loaded kexts. 251.It 6 252Identical to level 5 but for all kexts read by the program. 253.El 254.Pp 255To ease debug loading of kexts, 256the verbose levels 1-6 in 257.Nm 258implicitly set the 259OSBundleEnableKextLogging 260property for each kext specified on the command line to true. 261See 262.Xr kext_logging 8 263for more information on verbose logging. 264.It Fl x , Fl safe-boot 265Run 266.Nm 267as if in safe boot mode (indicating startup with the Shift key held down). 268Kexts that don't specify a proper value for the OSBundleRequired 269info dictionary property will not load. 270This option implies the use of the 271.Fl no-caches 272option. 273.Pp 274Note that if the system has actually started up in safe boot mode, 275this option is redundant. 276There is no way to simulate non-safe boot mode 277for a system running in safe boot mode. 278.It Fl z , Fl no-authentication 279Don't authenticate kexts. 280This option is for convenience during development, 281and is allowed only for operations 282that don't actually load a kext 283into the kernel (such as when generating symbols). 284.It Fl Z , Fl no-resolve-dependencies 285Don't try to resolve dependencies. 286This option is allowed only when using the 287.Fl no-load 288and 289.Fl print-diagnostics 290options to test a kext for problems. 291It is not allowed with the 292.Fl symbols 293option as generating symbols requires dependencies to be resolved. 294.It Fl - 295End of all options. Only kext names follow. 296.El 297.Sh EXAMPLES 298Here are the common uses and usage patterns for 299.Nm . 300.Ss Basic Loading 301To load a kext you must run 302.Nm 303as the superuser and supply a kext bundle name; 304no options are required: 305.Bd -literal -offset indent 306kextutil TabletDriver.kext 307.Ed 308.Pp 309Alternatively, you can use the 310.Fl bundle-id 311.Li ( Ns Fl b Ns Li ) 312option to specify a kext by its CFBundleIdentifier: 313.Bd -literal -offset indent 314kextutil -b com.mycompany.driver.TabletDriver 315.Ed 316.Pp 317With no additional options 318.Nm 319looks in 320.Pa /System/Library/Extensions/ 321and 322.Pa /Library/Extensions/ 323for a kext 324with the given CFBundleIdentifier. 325Adding repository directories with the 326.Fl repository 327.Li ( Ns Fl r Ns Li ) 328option or individual kexts with the 329.Fl dependency 330.Li ( Ns Fl d Ns Li ) 331option expands the set of kexts that 332.Nm 333looks among: 334.Bd -literal -offset indent 335kextutil -r ${USER}/Library/Extensions TabletDriver.kext 336.Ed 337.Ss Diagnosing Kexts 338.Nm 339prints diagnostic information about kexts by default, 340but some options cause certain tests to be skipped. 341The ensure that all tests are performed, 342use the 343.Fl print-diagnostics 344.Li ( Ns Fl t Ns Li ) 345option. 346.Pp 347The 348.Fl print-diagnostics 349option is typically used with 350.Fl no-load 351.Li ( Ns Fl n Ns Li ) 352after a load failure to pinpoint a problem. 353It can be used with any other set of options, however. 354.Pp 355If you want to validate a kext in isolation, 356as in a build environment where dependencies may not be available, 357you can use the 358.Fl no-system-extensions 359.Li ( Ns Fl e Ns Li ) 360and 361.Fl no-resolve-dependencies 362.Li ( Ns Fl Z Ns Li ) 363options to omit the 364.Pa /System/Library/Extensions/ 365and 366.Pa /Library/Extensions/ 367repositories 368and to suppress dependency resolution, respectively: 369.Bd -literal -offset indent 370kextutil -entZ PacketSniffer.kext 371.Ed 372.Pp 373Only validation and authentication checks are performed. 374.Ss Generating Debug Symbols When Loading 375To generate a symbol file for use with gdb when loading a kext, 376use the 377.Fl symbols 378.Li ( Ns Fl s Ns Li ) 379option to specify a directory where symbol files will be written 380for the kext being loaded and all its dependencies. 381.Bd -literal -offset indent 382kextutil -s ~/ksyms PacketSniffer.kext 383.Ed 384.Pp 385.Ss Generating Debug Symbols For an Already-Loaded Kext 386If you want to generate symbols for a kext that's already loaded, 387whether on the same system or on another, use the 388.Fl symbols 389.Li ( Ns Fl s Ns Li ) 390option along with the 391.Fl no-load 392.Li ( Ns Fl n Ns Li ) 393option. 394Since in this case addresses must be known for the kext and 395all its dependencies, though, you must specify them. 396If you don't indicate them on the command line, 397.Nm 398asks for the load address of each kext needed. 399To get these addresses you can use 400.Xr kextstat 8 401on the machine you're generating symbols for, 402the 403.Xr showallkmods 404.Xr gdb 1 405macro defined by the 406.Pa kgmacros 407file in the Kernel Development Kit, 408or consult a panic backtrace. 409.Bd -literal -offset indent 410kextutil -n -s ~/ksyms GrobbleEthernet.kext 411enter the hexadecimal load addresses for these modules: 412com.apple.iokit.IONetworkingFamily: 0x1001000 413\&.\|.\|. 414.Ed 415.Pp 416Alternatively, if you know the CFBundleIdentifiers 417of all the kexts, you can use the 418.Fl address 419.Li ( Ns Fl a Ns Li ) 420option for each kext (you needn't specify 421.Fl no-load 422when using the 423.Fl address 424option): 425.Bd -literal -offset indent 426kextutil -s ~/ksyms \\ 427 -a com.apple.iokit.IONetworkingFamily@0x1001000 \\ 428 -a com.apple.iokit.IOPCIFamily@0x1004000 \\ 429 -a com.mycompany.driver.GrobbleEthernet@0x1007000 \\ 430 GrobbleEthernet.kext 431.Ed 432.Pp 433Simplest of all, however, provided you can run 434.Nm 435on the same machine as the loaded kext, 436is to use the 437.Fl use-load-addresses 438.Li ( Ns Fl A Ns Li ) 439option, which checks with the kernel for all loaded 440kexts and automatically gets their load addresses. 441.Bd -literal -offset indent 442kextutil -s ~/ksyms -A GrobbleEthernet.kext 443.Ed 444.Pp 445.Ss Explicitly Specifying Dependencies 446Because 447.Nm 448resolves dependencies automatically, 449it's possible that a kext other than the one you 450intend might get used as a dependency 451(as when there are multiple copies of the same version, 452or if you're working with a different version of a kext 453that's already in 454.Pa /System/Library/Extensions/ Ns ). 455By default, when loading a kext into the kernel, 456.Nm 457checks which versions of possible dependencies are already 458loaded in order to assure a successful load. 459When not loading and not using 460.Fl use-load-addresses , 461however, it always chooses the highest 462versions of any dependencies, 463and in the case of a tie it chooses from kexts 464specified on the command line using the 465.Fl dependency 466or 467.Fl repository 468options, 469or as command line arguments (in decreasing order of priority). 470.Pp 471For precise control over the set of extensions 472used to resolve dependencies, 473use the 474.Fl no-system-extensions 475.Li ( Ns Fl e Ns Li ) 476option along with the 477.Fl dependency 478.Li ( Ns Fl d Ns Li ), 479and 480.Fl repository 481.Li ( Ns Fl r Ns Li ) 482options. 483The 484.Fl no-system-extensions 485option excludes the standard 486.Pa /System/Library/Extensions/ 487and 488.Pa /Library/Extensions/ 489directories, 490leaving the set of candidate extensions for dependency resolution 491entirely up to you. 492To specify candidate dependencies you use either 493.Fl dependency 494.Li ( Ns Fl d Ns Li ), 495which names a single kext as a candidate, or 496.Fl repository 497.Li ( Ns Fl r Ns Li ), 498which adds an entire directory of extensions. 499.Bd -literal -offset indent 500kextutil -n -s ~/ksyms -e \\ 501 -d /System/Library/Extensions/System.kext \\ 502 -r ~/TestKexts -d JoystickSupport.kext JoystickDriver.kext 503.Ed 504.Pp 505Note also that if you use 506.Fl no-system-extensions 507.Li ( Ns Fl e Ns Li ), 508you must supply at least some version of 509.Pa System.kext 510in order to supply information about the kernel. 511This should always match the kernel you're linking against, 512which is by default the installed kernel on the machine you're 513using 514.Nm 515on; you can use the 516.Fl kernel 517.Li ( Ns Fl k Ns Li ) 518option to specify a different kernel file. 519You may also need to explicitly specify other library or family kexts. 520.Ss Debug Loading an I/O Kit Driver 521Pure I/O Kit driver kexts have empty module-start routines, 522but trigger matching and driver instance creation on load. 523If you need to debug an I/O Kit driver's early startup code, 524you can load the driver on the target machine without starting matching 525by using the 526.Fl load-only 527.Li ( Ns Fl l Ns Li ) 528option: 529.Bd -literal -offset indent 530kextutil -l DiskController.kext 531.Ed 532.Pp 533Once you have done this, you can use the generated symbol 534file in your debug session to set breakpoints 535and then trigger matching by running 536.Nm 537again on the target machine with the 538.Fl match-only 539.Li ( Ns Fl m Ns Li ) 540option: 541.Bd -literal -offset indent 542kextutil -m DiskController.kext 543.Ed 544.Pp 545You may wish to use the 546.Fl personality 547.Li ( Ns Fl p Ns Li ) 548option as well in order to send selected personalities to the kernel. 549Alternatively, you can use the 550.Fl interactive 551.Li ( Ns Fl i Ns Li ) 552option for the whole process, which causes 553.Nm 554to pause just before loading any personalities and then 555to ask you for each personality whether that one should be sent to the kernel: 556.Bd -literal -offset indent 557kextutil -i DiskController.kext 558DiskController.kext appears to be loadable (not including linkage 559for on-disk libraries). 560Load DiskController.kext and its dependencies into the kernel [Y/n]? y 561Loading DiskController.kext. 562DiskController.kext successfully loaded (or already loaded). 563 564DiskController.kext and its dependencies are now loaded, 565but not started (unless they were already running). 566You may now set breakpoints in the debugger before starting them. 567 568start DiskController.kext [Y/n]? y 569DiskController.kext started. 570send personalities for DiskController.kext [Y/n]? y 571send personality Test Match Personality [Y/n]? y 572.Ed 573.Pp 574.Ss Debug Loading a Kext with a Module-Start Routine 575In order to debug a kext's module-start routine, you must 576use the 577.Fl interactive 578.Li ( Ns Fl i Ns Li ) 579or 580.Fl interactive-all 581.Li ( Ns Fl I Ns Li ) 582option, which pause after loading and before calling the module-start function, 583so that you can set up your debugging session as needed before proceeding. 584.Sh FILES 585.Bl -tag -width "/System/Library/Extensions/" -compact 586.It Pa /System/Library/Extensions/ 587The standard system repository of kernel extensions. 588.It Pa /Library/Extensions/ 589The standard repository of non Apple kernel extensions. 590.It Pa /System/Library/Caches/com.apple.kext.caches/* 591Contains all kext caches for a Mac OS X 10.6 (Snow Leopard) system: prelinked kernel, 592mkext, and system kext info caches. 593.It Pa /System/Library/Kernels/kernel 594The default kernel file. 595.El 596.Sh DIAGNOSTICS 597.Nm 598exits with a zero status upon success. 599Upon failure, it prints an error message 600and continues processing remaining kexts if possible, 601then exits with a nonzero status. 602.Pp 603For a kext to be loadable, it must be valid, authentic, 604have all dependencies met 605(that is, all dependencies must be found and loadable). 606A valid kext has a well formed bundle, info dictionary, and executable. 607An authentic kext's component files are owned by root:wheel, 608with permissions nonwritable by group and other. 609If your kext fails to load, try using the 610.Fl print-diagnostics 611.Li ( Ns Fl t Ns Li ) 612option to print diagnostics related to validation and authentication. 613.Sh BUGS 614Many single-letter options are inconsistent in meaning 615with (or directly contradictory to) the same letter options 616in other kext tools. 617.Sh SEE ALSO 618.Xr kextcache 8 , 619.Xr kextd 8 , 620.Xr kextload 8 , 621.Xr kextstat 8 , 622.Xr kextunload 8 , 623.Xr kext_logging 8 624