1.Dd March 6, 2009 2.Os Darwin 3.Dt KEXT_LOGGING 8 4.Sh NAME 5.Nm kext logging 6.Nd verbose/logging flags for kernel extensions (kexts) in the kernel and command-line utilities 7.Sh DESCRIPTION 8The kext management facilities of Mac OS X 9allow for logging of kext activity at all system levels, 10from the kernel to the user-space kext daemon and most command-line kext tools. 11The 12.Fl verbose 13.Li ( Ns Fl v Ns Li ) 14flag of the tools provides a simple system of levels that apply a set 15of lower level binary logging flags appropriate to each tool, 16for maximally useful verbose output. 17The binary log specification is used for kernel logging 18and is also available for use with the 19.Fl verbose 20option when you need precise control over logging. 21.Sh ENABLING LOGGING 22For command-line tools the 23.Fl verbose 24.Li ( Ns Fl v Ns Li ) 25and 26.Fl quiet 27.Li ( Ns Fl q Ns Li ) 28flags control verbose output. 29The 30.Fl verbose 31flag accepts a decimal level from 0-6 or a hexadecimal log specification, 32both described below. 33The 34.Fl verbose 35flag temporarily sets the log spec within the kernel, 36and captures any log messages from the kernel to print along with the tool's own log messages. 37.Pp 38If you wish to alter the logging behavior of 39.Xr kextd 8 , 40you will need to edit its 41.Xr launchd.plist 5 42file in 43.Pa /System/Library/LaunchdDaemons/com.apple.kextd.plist . 44.Pp 45To enable kernel kext logging (in 46.Pa /var/log/kernel.log ) 47on a long-term basis, 48use the 49.Sy kextlog 50boot arg or 51.Xr sysctl 8 52parameter. 53You can set it as root using 54.Xr nvram 8 55like so: 56.Bd -literal -offset indent 57.Li "nvram boot-args=" Ns Qo kextlog=0x Ns Ar logspec Ar other_boot_args Ns Qc 58.Ed 59.Pp 60where 61.Ar logspec 62is a hexadecimal log specification, 63as described below under 64.Dq BINARY LOG SPECIFICATION . 65.Pp 66.Em Caution: 67Enabling logging at a high level via boot arg can greatly slow down system startup time. 68.Pp 69To change the 70.Sy kextlog 71setting at any time use 72.Xr sysctl 8 : 73.Bd -literal -offset indent 74.Li "sysctl -w debug.kextlog=0x" Ns Ar logspec 75.Ed 76.Sh VERBOSE LEVELS 77As mentioned, for the command-line kext tools you use the 78.Fl verbose 79.Li ( Ns Fl v Ns Li ) 80flag, 81which takes an optional argument that is either a decimal level from 0-6, 82or a hexadecimal log specification (described under 83.Do BINARY LOG SPECIFICATION Dc Ns ). 84The details of each level vary by tool, but in general they are: 85.Bl -tag -width "1 (or none)" 86.It 0 87Errors only (that is, suppress warnings). 88Tools with a 89.Fl verbose 90flag also support a 91.Fl quiet 92flag to suppress all output. 93.It 1 (or none) 94Basic information about program operation. 95.It 2 96Basic information about program progress, including files created. 97.It 3 98Information about individual kexts, link/load operation, 99and processing of I/O Kit personalities. 100.It 4 101Detailed information about kext operations, 102including C++ class construction/destruction, 103and for archives, 104about compression and architectures processed. 105.It 5 106Debug-level information about internal operations. 107.It 6 108Identical to level 5 but with bit 0x8 turned on 109(see the hecadecimal log specification for details). 110.El 111.Sh BINARY LOG SPECIFICATION 112The binary log specification is a 32-bit value comprising a log level with a bitmask 113divided into several regions from the least-significant nibble 114(corresponding to digits from right to left in a hexadecimal representation). 115This table describes the regions and bits used; 116unlisted regions and bits are reserved for future use: 117.Bl -tag -width "Nibbles 1-2" 118.It Nibble 0 119The log level, from 0-7. 120Each level includes all levels below it. 121This is generally two higher than the decimal level specified with 122.Fl verbose . 123.Bl -inset 124.It Em "Log level 0" - 125Silent. 126.It Em "Log level 1" - 127Errors. 128.It Em "Log level 2" - 129Warnings. 130.It Em "Log level 3" - 131Basic outcome/result. 132.It Em "Log level 4" - 133Operation progress. 134.It Em "Log level 5" - 135Steps in a given operation. 136.It Em "Log level 6" - 137Detailed logging. 138.It Em "Log level 7" - 139Debug level logging. 140.El 141.Pp 142In addition, bit 0x8 of this nibble controls 143whether kext-specific log messages are always printed. 144.Xr kextcache 8 145and 146.Xr kextunload 8 147turn this bit on with their 148.Fl verbose 149flag. 150See 151.Dq PER-KEXT LOGGING 152for more information. 153.It Nibbles 1-2 154Activity flags relevant to general tool use, as in development scenarios. 155The 156.Fl verbose 157flag always includes these. 1588 bits total. 159.Bl -inset 160.It Em "Nibble 1, Bit 0 (0x10)" - 161General activity. 162.It Em "Nibble 1, Bit 1 (0x20)" - 163Load activity. 164.It Em "Nibble 1, Bit 2 (0x40)" - 165IPC and load settings. 166.It Em "Nibble 1, Bit 3 (0x80)" - 167Archive processing. 168.It Em "Nibble 2" - 169Reserved. 170.El 171.It Nibbles 3-7 172Activity flags for internal operations, 173for debugging the kext management system itself. 174These are available only when using a hexadecimal log specification; 175the 176.Fl verbose 177flag never includes these. 17820 bits total. 179.Bl -inset 180.It Em "Nibble 3, Bit 0 (0x1000)" - 181Kext validation. 182.It Em "Nibble 3, Bit 1 (0x2000)" - 183Kext authentication. 184.It Em "Nibble 3, Bit 2 (0x4000)" - 185Kext dependency resolution. 186.It Em "Nibble 4, Bit 0 (0x10000)" - 187Directory scan (booter data scan in the kernel). 188.It Em "Nibble 4, Bit 1 (0x20000)" - 189File I/O. 190.It Em "Nibble 4, Bit 2 (0x40000)" - 191Kext bookkeeping. 192.It Em "Nibble 5, Bit 0 (0x100000)" - 193Link activity. 194.It Em "Nibble 5, Bit 1 (0x200000)" - 195C++ patching activity. 196.It Em "Nibbles 6-7" - 197Reserved. 198.El 199.El 200.Sh PER-KEXT LOGGING 201Many log messages apply to the kext being processed. 202The kernel and most of the command-line kext tools do not log 203these messages by default. 204You can enable these messages for an individual kext 205by specifying an OSBundleEnableKextLogging 206property in its 207.Pa Info.plist 208file with a boolean value of true. 209For convenience, 210.Xr kextutil 8 211automatically sets this property for the kexts it is loading. 212.Pp 213You can activate all per-kext log messages using 214level 6 with the 215.Fl verbose 216flag or by turning on bit 0x8 in a hexadecimal log specification. 217For convenience, 218.Xr kextcache 8 219and 220.Xr kextunload 8 221do this for all verbose levels of their 222.Fl verbose 223flag. 224.Sh MAPPING VERBOSE LEVELS TO LOG SPECIFICATIONS 225Here is a list of the exact hecadecimal log specifications 226applied by each of the 227.Fl verbose 228levels: 229.Bl -tag -width "1 (or none)" 230.It 0 231equivalent to 0x0 for all tools. 232.It (default level) 233equivalent to 0xff2, 2340xff9 for 235.Xr kextcache 8 236and 237.Xr kextunload 8 , 2380xff3 for 239.Xr kextd 8 240and for 241.Xr kextcache 8 242spawned by 243.Xr kextd 8 . 244.It 1 (or none) 245equivalent to 0xff3, or 0xffa for 246.Xr kextcache 8 247and 248.Xr kextunload 8 . 249.It 2 250equivalent to 0xff4, or 0xffb for 251.Xr kextcache 8 252and 253.Xr kextunload 8 . 254.It 3 255equivalent to 0xff5, or 0xffc for 256.Xr kextcache 8 257and 258.Xr kextunload 8 . 259.It 4 260equivalent to 0xff6, or 0xffd for 261.Xr kextcache 8 262and 263.Xr kextunload 8 . 264.It 5 265equivalent to 0xff7, or 0xffe for 266.Xr kextcache 8 267and 268.Xr kextunload 8 . 269.It 6 270equivalent to 0xfff for all tools. 271.El 272.Sh FILES 273.Bl -tag -width "/var/log/kernel.log" 274.It Pa /var/log/kernel.log 275The kernel log file, where kernel kext activity is logged. 276.It Pa /var/log/system.log 277The system log file, where 278.Xr kextd 8 279activity is logged. 280.It Pa /System/Library/LaunchdDaemons/com.apple.kextd.plist 281Edit this 282.Xr launchd.plist 5 283file to specify verbose logging for 284.Xr kextd 8 . 285.El 286.Sh SEE ALSO 287.Xr syslog 1 , 288.Xr kextcache 8 , 289.Xr kextd 8 , 290.Xr kextlibs 8 , 291.Xr kextload 8 , 292.Xr kextunload 8 , 293.Xr kextutil 8