libkern/libkern/OSKextLibPrivate.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef _LIBKERN_OSKEXTLIBPRIVATE_H
  30 #define _LIBKERN_OSKEXTLIBPRIVATE_H
  31
  32 #include <sys/cdefs.h>
  33 #include <uuid/uuid.h>
  34
  35 __BEGIN_DECLS
  36 #ifdef KERNEL
  37 #include <libkern/OSTypes.h>
  38 #include <mach/kmod.h>
  39 #include <mach/vm_types.h>
  40 #else
  41 #include <CoreFoundation/CoreFoundation.h>
  42 #include <System/mach/kmod.h>
  43 #endif /* KERNEL */
  44 __END_DECLS
  45
  46 #include <libkern/OSReturn.h>
  47
  48 __BEGIN_DECLS
  49
  50 #if PRAGMA_MARK
  51 #pragma mark -
  52 /********************************************************************/
  53 #pragma mark Misc Constants
  54 /********************************************************************/
  55 #endif
  56
  57 typedef uint8_t OSKextExcludeLevel;
  58 #define kOSKextExcludeNone  (0)
  59 #define kOSKextExcludeKext  (1)
  60 #define kOSKextExcludeAll   (2)
  61
  62 #if PRAGMA_MARK
  63 #pragma mark -
  64 /********************************************************************/
  65 #pragma mark Kext/OSBundle Property List Keys
  66 /********************************************************************/
  67 #endif
  68
  69 /*!
  70  * @define   kOSBundleHelperKey
  71  * @abstract Used by loginwindow.
  72  */
  73 #define kOSBundleHelperKey      "OSBundleHelper"
  74
  75 /*!
  76  * @define   kOSBundleDeveloperOnlyKey
  77  * @abstract A boolean value indicating whether the kext should only load on
  78  *           Developer devices.
  79  */
  80 #define kOSBundleDeveloperOnlyKey               "OSBundleDeveloperOnly"
  81
  82 /*!
  83  * @define   kOSBundleRamDiskOnlyKey
  84  * @abstract A boolean value indicating whether the kext should only load when
  85  *           booted from a ram disk.
  86  */
  87 #define kOSBundleRamDiskOnlyKey         "OSBundleRamDiskOnly"
  88
  89
  90 /*!
  91  * @define   kAppleSecurityExtensionKey
  92  * @abstract A boolean value indicating whether the kext registers
  93  *           MACF hooks.
  94  */
  95 #define kAppleSecurityExtensionKey      "AppleSecurityExtension"
  96
  97 /*!
  98  * @define   kAppleKernelExternalComponentKey
  99  * @abstract A boolean value indicating whether the kext is vending kernel
 100  *           KPI, and needs special loading behavior.
 101  */
 102 #define kAppleKernelExternalComponentKey        "AppleKernelExternalComponent"
 103
 104 // properties found in the registry root
 105 #define kOSKernelCPUTypeKey             "OSKernelCPUType"
 106 #define kOSKernelCPUSubtypeKey          "OSKernelCPUSubtype"
 107 #define kOSStartupMkextCRC              "OSStartupMkextCRC"             /* value is 32-bit OSData */
 108 #define kOSPrelinkKextCountKey          "OSPrelinkKextCount"            /* value is 32-bit OSNumber */
 109 #define kOSPrelinkPersonalityCountKey   "OSPrelinkPersonalityCount"     /* value is 32-bit OSNumber */
 110
 111 #if PRAGMA_MARK
 112 #pragma mark -
 113 /********************************************************************/
 114 #pragma mark Load Info Keys
 115 /********************************************************************/
 116 #endif
 117 /*********************************************************************
 118 * In addition to the keys defined here, you will find:
 119 *   kCFBundleIdentifierKey
 120 *   kCFBundleVersionKey
 121 *   kOSBundleCompatibleVersionKey
 122 *   kOSBundleIsInterfaceKey
 123 *   kOSKernelResourceKey
 124 *********************************************************************/
 125 #define kOSBundleMachOHeadersKey                "OSBundleMachOHeaders"
 126 #define kOSBundleCPUTypeKey                     "OSBundleCPUType"
 127 #define kOSBundleCPUSubtypeKey                  "OSBundleCPUSubtype"
 128 #define kOSBundlePathKey                        "OSBundlePath"
 129 #define kOSBundleExecutablePathKey              "OSBundleExecutablePath"
 130 #define kOSBundleUUIDKey                        "OSBundleUUID"
 131 #define kOSBundleStartedKey                     "OSBundleStarted"
 132 #define kOSBundlePrelinkedKey                   "OSBundlePrelinked"
 133 #define kOSBundleLoadTagKey                     "OSBundleLoadTag"
 134 #define kOSBundleLoadAddressKey                 "OSBundleLoadAddress"
 135 #define kOSBundleLoadSizeKey                    "OSBundleLoadSize"
 136 #define kOSBundleWiredSizeKey                   "OSBundleWiredSize"
 137 #define kOSBundleDependenciesKey                "OSBundleDependencies"
 138 #define kOSBundleRetainCountKey                 "OSBundleRetainCount"
 139
 140 /* Dictionary of metaclass info keyed by classname.
 141  */
 142 #define kOSBundleClassesKey                     "OSBundleClasses"
 143
 144 /* These are contained in kOSBundleClassesKey. kOSMetaClassSuperclassNameKey
 145  * may be absent (for the root class).
 146  */
 147 #define kOSMetaClassNameKey                     "OSMetaClassName"
 148 #define kOSMetaClassSuperclassNameKey           "OSMetaClassSuperclassName"
 149 #define kOSMetaClassTrackingCountKey            "OSMetaClassTrackingCount"
 150
 151 #if PRAGMA_MARK
 152 #pragma mark -
 153 /********************************************************************/
 154 #pragma mark Kext Log Specification
 155 /********************************************************************/
 156 #endif
 157 /*!
 158  * @group Kext Log Specification
 159  * Logging levels & flags for kernel extensions.
 160  * See <code>@link //apple_ref/c/tdef/OSKextLogSpec OSKextLogSpec@/link</code>
 161  * for an overview.
 162  */
 163
 164 /*!
 165  * @typedef  OSKextLogSpec
 166  * @abstract Describes what a log message applies to,
 167  *           or a filter that determines which log messages are displayed.
 168  *
 169  * @discussion
 170  * A kext log specification is a 32-bit value used as a desription of
 171  * what a given log message applies to, or as a filter
 172  * indicating which log messages are desired and which are not.
 173  * A log specification has three parts (described in detail shortly):
 174  * <ul>
 175  *   <li>A <b>level</b> from 0-7 in the lowest-order nibble (0x7).</li>
 176  *   <li>A flag bit in the lowest-order nibble (0x8) indicating whether
 177  *       log messages tied to individual kexts are always printed (1)
 178  *       or printed only if the kext has an
 179  *       @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 180  *       OSBundleEnableKextLogging@/link set to <code>true</code>.
 181  *   <li>A set of <b>activity flags</b> in the remaining nibbles (0xFFFFFFF0),
 182  *       which describe areas of activity related to kernel extensions.</li>
 183  * </ul>
 184  *
 185  * You can specify a log spec to most of the kext tools with the -v option
 186  * and a hex number (rather than the escalating decimal levels 0-6).
 187  * You can also specify a log spec to the kernel with the "kextlog" boot arg
 188  * or "debug.kextlog" sysctl.
 189  *
 190  * <b>Log Levels</b>
 191  *
 192  * The log level spans a range from silent (no log messages)
 193  * to debuging information:
 194  *
 195  * <ol start="0">
 196  * <li>Silent - Not applicable to messages; as a filter, do not print any log messages.</li>
 197  * <li>Errors - Log message is an error.
 198  * <li>Warnings - Log message is a warning.
 199  * <li>Basic information - Log message is basic success/failure.</li>
 200  * <li>Progress - Provides high-level information about stages in processing.</li>
 201  * <li>Step - Provides low-level information about complex operations,
 202  *          typically about individual kexts.</li>
 203  * <li>Detail - Provides very low-level information about parts of kexts,
 204  *          including individual Libkern classes and operations on bundle files.</li>
 205  * <li>Debug - Very verbose logging about internal activities.</li>
 206  * </ol>
 207  *
 208  * Log messages at
 209  * <code>@link kOSKextLogErrorLevel kOSKextLogErrorLevel@/link</code> or
 210  * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code>
 211  * ignore activity flags and the
 212  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 213  * OSBundleEnableKextLogging@/link property;
 214  * that is, only the filter level is checked for messages at these levels.
 215  * Log messages at levels above
 216  * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code>
 217  * are filtered according both to the activity flags in the current filter
 218  * and to whether the log message is associated with a kext or not.
 219  * Normally log messages associated with kexts are not printed
 220  * unless the kext has a
 221  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 222  * OSBundleEnableKextLogging@/link property set to <code>true</code>.
 223  * If you set the high-order bit of the log level (that is, add 8 to the level),
 224  * then all kext-specific log messages matching the activity flags are printed.
 225  * This can be very verbose.
 226  *
 227  * <b>Activity Flags</b>
 228  *
 229  * Each flag governs a category of activity,
 230  * such as loading, IPC, or archives; by combining them with bitwise OR,
 231  * you can choose which messages you wish to see (or when logging messages,
 232  * which bit flags select your message).
 233  *
 234  * <b>Byte 1:</b> <code>0xF0</code> - Basic activities
 235  * (<code>@link kOSKextLogGeneralFlag kOSKextLogGeneralFlag@/link</code>,
 236  * <code>@link kOSKextLogLoadFlag kOSKextLogLoadFlag@/link</code>, and
 237  * <code>@link kOSKextLogArchiveFlag kOSKextLogArchiveFlag@/link</code>).
 238  *
 239  * <b>Byte 2:</b> <code>0xF00</code> - Reserved.
 240  *
 241  * <b>Byte 4:</b> <code>0xF000</code> - Kext diagnostics
 242  * (<code>@link kOSKextLogValidationFlag kOSKextLogValidationFlag@/link</code>,
 243  * <code>@link kOSKextLogAuthenticationFlag kOSKextLogAuthenticationFlag@/link</code>, and
 244  * <code>@link kOSKextLogDependenciesFlag kOSKextLogDependenciesFlag@/link</code>).
 245  *
 246  * <b>Byte 5:</b> <code>0xF00000</code> - Kext access & bookkeeping
 247  * (<code>@link kOSKextLogDirectoryScanFlag kOSKextLogDirectoryScanFlag@/link</code>,
 248  * <code>@link kOSKextLogFileAccessFlag kOSKextLogFileAccessFlag@/link</code>,
 249  * <code>@link kOSKextLogKextBookkeepingFlag kOSKextLogKextBookkeepingFlag@/link </code>).
 250  *
 251  * <b>Byte 6:</b> <code>0xF000000</code> - Linking & patching
 252  * (<code>@link kOSKextLogLinkFlag kOSKextLogLinkFlag@/link</code> and
 253  * <code>@link kOSKextLogPatchFlag kOSKextLogPatchFlag@/link</code>).
 254  *
 255  * <b>Byte 7:</b> <code>0xF0000000</code> - Reserved.
 256  */
 257 typedef uint32_t OSKextLogSpec;
 258
 259 #if PRAGMA_MARK
 260 /********************************************************************/
 261 #pragma mark Masks
 262 /********************************************************************/
 263 #endif
 264 /*!
 265  * @define   kOSKextLogLevelMask
 266  * @abstract Masks the bottom 3 bits of an
 267  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code> to extract
 268  *           the raw level.
 269  */
 270 #define kOSKextLogLevelMask              ((OSKextLogSpec) 0x00000007)
 271
 272 /*!
 273  * @define   kOSKextLogKextOrGlobalMask
 274  * @abstract Determines whether per-kext log messages are output.
 275  *
 276  * @discussion
 277  * In filter specifications, if unset (the usual default),
 278  * then log messages associated with a kext are only output
 279  * if the kext has an
 280  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 281  * OSBundleEnableKextLogging@/link
 282  * property set to <code>true</code>.
 283  * If set, then all log messages associated with kexts
 284  * are output.
 285  *
 286  * In message specifications, if set it indicates that the message is either
 287  * not associated with a kext, or is associated with a kext that has an
 288  * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 289  * OSBundleEnableKextLogging@/link
 290  * property set to <code>true</code>.
 291  */
 292 #define kOSKextLogKextOrGlobalMask       ((OSKextLogSpec) 0x00000008)
 293
 294
 295 /*!
 296  * @define   kOSKextLogFlagsMask
 297  * @abstract Masks the flag bits of an
 298  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>.
 299  */
 300 #define kOSKextLogFlagsMask              ((OSKextLogSpec) 0x0ffffff0)
 301
 302 /*!
 303  * @define   kOSKextLogFlagsMask
 304  * @abstract Masks the flag bits of an
 305  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>
 306  *           to which command-line <code>-v</code> levels apply.
 307  */
 308 #define kOSKextLogVerboseFlagsMask       ((OSKextLogSpec) 0x00000ff0)
 309
 310 /*!
 311  * @define   kOSKextLogConfigMask
 312  * @abstract Masks the config bits of an
 313  *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>.
 314  */
 315 #define kOSKextLogConfigMask             ((OSKextLogSpec) 0xf0000000)
 316
 317 #if PRAGMA_MARK
 318 /********************************************************************/
 319 #pragma mark 0xF - Log Level
 320 /********************************************************************/
 321 #endif
 322
 323 /*!
 324  * @define   kOSKextLogExplicitLevel
 325  * @abstract Used when logging a message to overrides the current log filter,
 326  *           even if it's set to silent for log messages.
 327  *           This is essentially a pass-through for
 328  *           unconditional print messages to go
 329  *           through the logging engine.
 330  */
 331 #define kOSKextLogExplicitLevel          ((OSKextLogSpec)        0x0)
 332
 333 /*!
 334  * @define   kOSKextLogErrorLevel
 335  * @abstract Log messages concerning error conditions in any category.
 336  */
 337 #define kOSKextLogErrorLevel            ((OSKextLogSpec)        0x1)
 338
 339
 340 /*!
 341  * @define   kOSKextLogWarningLevel
 342  * @abstract Log messages concerning warning conditions in any category,
 343  *           which indicate potential error conditions,
 344  *           and notices, which may explain unexpected but correct behavior.
 345  */
 346 #define kOSKextLogWarningLevel          ((OSKextLogSpec)        0x2)
 347
 348
 349 /*!
 350  * @define   kOSKextLogBasicLevel
 351  * @abstract Log messages concerning top-level outcome in any category
 352  *           (kext load/unload, kext cache creation/extration w/# kexts).
 353  */
 354 #define kOSKextLogBasicLevel           ((OSKextLogSpec)        0x3)
 355
 356
 357 /*!
 358  * @define   kOSKextLogProgressLevel
 359  * @abstract Log messages concerning high-level progress in any category,
 360  *           such as sending a load request to the kernel,
 361  *           allocation/link/map/start (load operation),
 362  *           stop/unmap (unload operation), kext added/extracted (archive).
 363  */
 364 #define kOSKextLogProgressLevel          ((OSKextLogSpec)        0x4)
 365
 366
 367 /*!
 368  * @define   kOSKextLogStepLevel
 369  * @abstract Log messages concerning major steps in any category,
 370  *           such as sending personalities to the IOCatalogue when loading,
 371  *           detailed IPC with the kernel, or filtering of kexts for an archive.
 372  */
 373 #define kOSKextLogStepLevel             ((OSKextLogSpec)        0x5)
 374
 375
 376 /*!
 377  * @define   kOSKextLogDetailLevel
 378  * @abstract Log messages concerning specific details in any category,
 379  *           such as classes being registered/unregistered or
 380  *           operations on indivdual files in a kext.
 381  */
 382 #define kOSKextLogDetailLevel           ((OSKextLogSpec)        0x6)
 383
 384
 385 /*!
 386  * @define   kOSKextLogDebugLevel
 387  * @abstract Log messages concerning very low-level actions that are
 388  *           useful mainly for debugging the kext system itself.
 389  */
 390 #define kOSKextLogDebugLevel             ((OSKextLogSpec)        0x7)
 391
 392
 393 #if PRAGMA_MARK
 394 /********************************************************************/
 395 #pragma mark 0xF0 - General Activity, Load, Kernel IPC, Personalities
 396 /********************************************************************/
 397 #endif
 398
 399 /*!
 400  * @define   kOSKextLogGeneralFlag
 401  * @abstract Log messages about general activity in the kext system.
 402  */
 403 #define kOSKextLogGeneralFlag            ((OSKextLogSpec)       0x10)
 404
 405 /*!
 406  * @define   kOSKextLogLoadFlag
 407  * @abstract Log messages regarding kernel extension load, start/stop, or unload activity
 408  *           in the kernel.
 409  */
 410 #define kOSKextLogLoadFlag               ((OSKextLogSpec)       0x20)
 411
 412 /*!
 413  * @define   kOSKextLogIPCFlag
 414  * @abstract Log messages about any interaction between kernel and user space
 415  *           regarding kernel extensions.
 416  */
 417 #define kOSKextLogIPCFlag                ((OSKextLogSpec)       0x40)
 418
 419 /*!
 420  * @define   kOSKextLogArchiveFlag
 421  * @abstract Log messages about creating or processing a kext startup cache file
 422  *           (mkext or prelinked kernel).
 423  */
 424 #define kOSKextLogArchiveFlag           ((OSKextLogSpec)       0x80)
 425
 426
 427 #if PRAGMA_MARK
 428 /********************************************************************/
 429 #pragma mark 0xF00 - Reserved Verbose Area
 430 /********************************************************************/
 431 #endif
 432 // reserved slot for group               ((OSKextLogSpec)      0x100)
 433 // reserved slot for group               ((OSKextLogSpec)      0x200)
 434 // reserved slot for group               ((OSKextLogSpec)      0x400)
 435 // reserved slot for group               ((OSKextLogSpec)      0x800)
 436
 437 #if PRAGMA_MARK
 438 /********************************************************************/
 439 #pragma mark 0xF000 - Kext diagnostic activity
 440 /********************************************************************/
 441 #endif
 442
 443 /*!
 444  * @define   kOSKextLogValidationFlag
 445  * @abstract Log messages when validating kernel extensions.
 446  */
 447 #define kOSKextLogValidationFlag         ((OSKextLogSpec)     0x1000)
 448
 449 /*!
 450  * @define   kOSKextLogAuthenticationFlag
 451  * @abstract Log messages when autnenticating kernel extension files.
 452  *           Irrelevant in the kernel.
 453  */
 454 #define kOSKextLogAuthenticationFlag     ((OSKextLogSpec)     0x2000)
 455
 456 /*!
 457  * @define   kOSKextLogDependenciesFlag
 458  * @abstract Log messages when resolving dependencies for a kernel extension.
 459  */
 460 #define kOSKextLogDependenciesFlag       ((OSKextLogSpec)     0x4000)
 461
 462 // reserved slot for group               ((OSKextLogSpec)     0x8000)
 463
 464 #if PRAGMA_MARK
 465 /********************************************************************/
 466 #pragma mark 0xF0000 - Archives, caches, directory scan, file access
 467 /********************************************************************/
 468 #endif
 469
 470 /*!
 471  * @define   kOSKextLogDirectoryScanFlag
 472  * @abstract Log messages when scanning directories for kernel extensions.
 473  *           In the kernel logs every booter kext entry processed.
 474  */
 475 #define kOSKextLogDirectoryScanFlag      ((OSKextLogSpec)    0x10000)
 476
 477 /*!
 478  * @define   kOSKextLogFileAccessFlag
 479  * @abstract Log messages when performing any filesystem access (very verbose).
 480  *           Irrelevant in the kernel.
 481  */
 482 #define kOSKextLogFileAccessFlag         ((OSKextLogSpec)    0x20000)
 483
 484 /*!
 485  * @define   kOSKextLogKextBookkeepingFlag
 486  * @abstract Log messages about internal tracking of kexts. Can be very verbose.
 487  */
 488 #define kOSKextLogKextBookkeepingFlag    ((OSKextLogSpec)    0x40000)
 489
 490 // reserved slot for group               ((OSKextLogSpec)    0x80000)
 491
 492 #if PRAGMA_MARK
 493 /********************************************************************/
 494 #pragma mark 0xF00000 - Linking & Patching
 495 /********************************************************************/
 496 #endif
 497
 498 /*!
 499  * @define   kOSKextLogLinkFlag
 500  * @abstract Log messages about linking.
 501  */
 502 #define kOSKextLogLinkFlag               ((OSKextLogSpec)   0x100000)
 503
 504 /*!
 505  * @define   kOSKextLogPatchFlag
 506  * @abstract Log messages about patching.
 507  */
 508 #define kOSKextLogPatchFlag              ((OSKextLogSpec)   0x200000)
 509
 510 // reserved slot for group               ((OSKextLogSpec)   0x400000)
 511 // reserved slot for group               ((OSKextLogSpec)   0x800000)
 512
 513 #if PRAGMA_MARK
 514 /********************************************************************/
 515 #pragma mark 0xF000000 - Reserved
 516 /********************************************************************/
 517 #endif
 518
 519 // reserved slot for grouping            ((OSKextLogSpec)  0x1000000)
 520 // reserved slot for grouping            ((OSKextLogSpec)  0x2000000)
 521 // reserved slot for grouping            ((OSKextLogSpec)  0x4000000)
 522 // reserved slot for grouping            ((OSKextLogSpec)  0x8000000)
 523
 524
 525 #if PRAGMA_MARK
 526 /********************************************************************/
 527 #pragma mark 0xF0000000 - Config Flags
 528 /********************************************************************/
 529 #endif
 530
 531 // reserved slot for grouping            ((OSKextLogSpec) 0x10000000)
 532 // reserved slot for grouping            ((OSKextLogSpec) 0x20000000)
 533 // reserved slot for grouping            ((OSKextLogSpec) 0x40000000)
 534
 535 #if PRAGMA_MARK
 536 /********************************************************************/
 537 #pragma mark Predefined Specifications
 538 /********************************************************************/
 539 #endif
 540
 541 /*!
 542  * @define   kOSKextLogSilentFilter
 543  * @abstract For use in filter specs:
 544  *           Ignore all log messages with a log level greater than
 545  *           <code>@link kOSKextLogExplicitLevel kOSKextLogExplicitLevel@/link</code>.
 546  */
 547 #define kOSKextLogSilentFilter           ((OSKextLogSpec)        0x0)
 548
 549 /*!
 550  * @define   kOSKextLogShowAllFilter
 551  * @abstract For use in filter specs:
 552  *           Print all log messages not associated with a kext or
 553  *           associated with a kext that has
 554  *           @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 555  *           OSBundleEnableKextLogging@/link
 556  *           set to <code>true</code>.
 557  */
 558 #define kOSKextLogShowAllFilter          ((OSKextLogSpec) 0x0ffffff7)
 559
 560 /*!
 561  * @define   kOSKextLogShowAllKextsFilter
 562  * @abstract For use in filter specs:
 563  *           Print all log messages has
 564  *           @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 565  *           OSBundleEnableKextLogging@/link
 566  *           set to <code>true</code>.
 567  */
 568 #define kOSKextLogShowAllKextsFilter     ((OSKextLogSpec) \
 569                                            (kOSKextLogShowAllFilter | \
 570                                             kOSKextLogKextOrGlobalMask))
 571
 572 #if PRAGMA_MARK
 573 #pragma mark -
 574 /********************************************************************/
 575 #pragma mark Kext Version String Processing
 576 /********************************************************************/
 577 #endif
 578 /*!
 579  * @group Kext Version String Processing
 580  * Functions for working with kext versions and compatible versions.
 581  */
 582
 583 /*!
 584  * @typedef   OSKextVersion
 585  * @abstract  An encoded kext version that can be compared arithmetically.
 586  *
 587  * @discussion
 588  * A value of zero (<code>@link kOSKextVersionUndefined kOSKextVersionUndefined@/link</code>)
 589  * is <i>not</i> equivalent to a version string of "0.0",
 590  * and typically means there is no version specified
 591  * (for example, that there is no CFBundleVersion property at all).
 592  * Values below zero are invalid.
 593  *
 594  * The encoding used is subject to change,
 595  * and should never be saved to permanent storage.
 596  * Always use proper version strings in files and interprocess communication.
 597  */
 598 typedef int64_t OSKextVersion;
 599
 600 /*!
 601  * @define    kOSKextVersionMaxLength
 602  * @abstract  The length of a string buffer
 603  *            guaranteed to be able to hold a kext version.
 604  *
 605  * @discussion
 606  * Kext versions use an extended Mac OS 'vers' format with double the number
 607  * of digits before the build stage: ####.##.##s{1-255} where 's'
 608  * is a build stage 'd', 'a', 'b', 'f' or 'fc'.
 609  */
 610 #define kOSKextVersionMaxLength (20)
 611 // with a few bytes to spare including a nul byte
 612 // xx-review: Should we make this much bigger in case we ever need longer strings?
 613
 614 /*!
 615  * @define    kOSKextVersionUndefined
 616  * @abstract  The undefined version.
 617  *
 618  * @discussion
 619  * This value of <code>@link OSKextVersion OSKextVersion@/link</code> represents the
 620  * lack of a version
 621  * (for example, that there is no CFBundleVersion property at all).
 622  */
 623 #define kOSKextVersionUndefined  (0)
 624
 625 /*!
 626  * @function OSKextParseVersionString
 627  *
 628  * @abstract
 629  * Parses a kext version string into an <code>@link OSKextVersion OSKextVersion@/link</code>.
 630  *
 631  * @param  versionString  The kext version string to parse.
 632  *
 633  * @result
 634  * An encoded kext version that can be compared numerically
 635  * against other encoded kext versions,
 636  * <0 if <code>versionString</code> is <code>NULL</code>, empty,
 637  * or cannot be parsed.
 638  *
 639  * @discussion
 640  * Kext versions use an extended Mac OS 'vers' format with double the number
 641  * of digits before the build stage: ####.##.##s{1-255} where 's'
 642  * is a build stage 'd', 'a', 'b', 'f' or 'fc'.
 643  */
 644 OSKextVersion OSKextParseVersionString(const char * versionString);
 645
 646
 647 /*!
 648  * @function OSKextVersionGetString
 649  *
 650  * @abstract
 651  * Formats an encoded <code>@link OSKextVersion OSKextVersion@/link</code> into a string
 652  * representation.
 653  *
 654  * @param  aVersion
 655  *         The encoded version to format.
 656  * @param  buffer
 657  *         A C string buffer of at least
 658  *         <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code> bytes.
 659  * @param  bufferSize  The size in bytes of <code>buffer</code>.
 660  *
 661  * @result
 662  * <code>TRUE</code> if the encoded version is formatted successfully.
 663  * <code>FALSE</code> if <code>buffer</code> is <code>NULL</code> or
 664  * <code>bufferSize</code> is less than
 665  * <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code>.
 666  *
 667  * @discussion
 668  * The return value strictly indicates whether <code>buffer</code>
 669  * is large enough to hold the result.
 670  * If <code>aVersion</code> is 0, the resulting string is "(missing)".
 671  * If <code>aVersion</code> is less than 0
 672  * or is not a valid kext version encoding,
 673  * the resulting string is "(invalid)".
 674  */
 675 Boolean OSKextVersionGetString(
 676     OSKextVersion   aVersion,
 677     char          * buffer,
 678     uint32_t        bufferSize);
 679
 680
 681 #ifdef KERNEL
 682
 683
 684 #if PRAGMA_MARK
 685 /********************************************************************/
 686 #pragma mark -
 687 #pragma mark Weak linking
 688 /********************************************************************/
 689 #endif
 690 #ifdef XNU_KERNEL_PRIVATE
 691 void kext_weak_symbol_referenced(void);
 692 #endif /* XNU_KERNEL_PRIVATE */
 693
 694 #if PRAGMA_MARK
 695 #pragma mark -
 696 /********************************************************************/
 697 #pragma mark Miscellaneous Kernel-Only Kext Functions
 698 /********************************************************************/
 699 #endif
 700
 701 /*!
 702  * @function kext_get_vm_map
 703  * @abstract Returns the vm_map from which the kext was allocated.
 704  *
 705  * @param info The kmod_info_t structure of the kext.
 706  * @result The vm_map from which the kext was allocated.  This function
 707  * cannot return <code>NULL</code>.
 708  */
 709 vm_map_t kext_get_vm_map(kmod_info_t * info);
 710
 711 #ifdef XNU_KERNEL_PRIVATE
 712
 713 #if CONFIG_DTRACE
 714 /*!
 715  * @function OSKextRegisterKextsWithDTrace
 716  * @abstract
 717  * DTrace calls this once when it has started up so that the kext system
 718  * will register any already-loaded kexts with it.
 719  */
 720 void OSKextRegisterKextsWithDTrace(void);
 721
 722 #endif /* CONFIG_DTRACE */
 723
 724 /*!
 725  * @function kext_dump_panic_lists
 726  * @abstract Prints compacted lists of last unloaded & all loaded kexts
 727  *           during a panic.
 728  *
 729  * @param printf_func The printf-style function to use for output.
 730  */
 731 void kext_dump_panic_lists(int (*printf_func)(const char *fmt, ...));
 732
 733 #endif /* XNU_KERNEL_PRIVATE */
 734
 735 #ifdef XNU_KERNEL_PRIVATE
 736
 737 #if PRAGMA_MARK
 738 #pragma mark -
 739 /********************************************************************/
 740 #pragma mark Kext Loading C Functions
 741 /********************************************************************/
 742 #endif
 743 /*!
 744  * @function OSKextGetLoadTagForBundleIdentifier
 745  * @abstract Look up the load tag for a kext.
 746  *
 747  * @param  kextIdentifier  The bundle identifier of the kext to look up.
 748  * @result
 749  * The load tag of the requested kext, or
 750  * <code>@link //apple_ref/c/macro/kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>
 751  * if the kext was not found.
 752  *
 753  * @discussion
 754  * A load tag uniquely identifies a loaded kext.
 755  * It can be found as the <code>id</code> field of a loaded kext's
 756  * <code>kmod_info_t</code> struct.
 757  *
 758  * Note that a load tag represents a specific loaded instance of a kext.
 759  * If that kext is unloaded, the load tag is no longer a valid reference.
 760  * If the same kext is later reloaded, it will have a new load tag.
 761  *
 762  * You can use the load tag to adjust a kext's reference count
 763  * via
 764  * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag
 765  * OSKextRetainKextWithLoadTag@/link</code>
 766  * and
 767  * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag
 768  * OSKextReleaseKextWithLoadTag@/link</code>,
 769  * so that the kext is automatically unloaded when no references remain,
 770  * or to unload the kext immediately
 771  * with <code>@link //apple_ref/c/func/OSKextUnloadKextWithLoadTag OSKextUnloadKextWithLoadTag@/link</code>.
 772  *
 773  * Those functions are intended for use with non-IOKit kexts
 774  * (specifically, kexts that define no subclasses of
 775  * <code>@link //apple_ref/doc/class/IOServiceIOService@/link</code>).
 776  * Pure IOKit kexts are managed via instance counts
 777  * of their libkern C++ object classes;
 778  * using those functions on them will only interfere with that mechanism.
 779  * If you have a hybrid kext with both IOService subclasses and non-IOKit code,
 780  * however, you may want to use reference counting for the non-IOKit portions:
 781  * that way the kext will only unload automaticaly
 782  * when there are no C++ objects and the kext reference count is zero.
 783  */
 784 uint32_t OSKextGetLoadTagForBundleIdentifier(
 785     const char * kextIdentifier);
 786
 787
 788 /*!
 789  * @function OSKextUnloadKextWithLoadTag
 790  * @abstract Stop and unload a kext based on its load tag.
 791  *
 792  * @param  loadTag   The load tag of the kext to unload.
 793  * @result
 794  * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code>
 795  * if the kext was found and unloaded.
 796  * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound
 797  * kOSKextReturnNotFound@/link</code>
 798  * if the kext was not found.
 799  * <code>@link //apple_ref/c/macro/kOSKextReturnInUse
 800  * kOSKextReturnInUse@/link</code>
 801  * if the kext has outstanding references
 802  * or if there are instances of its libkern C++ subclasses.
 803  * Other return values indicate a failure to unload the kext,
 804  * typically because the module stop routine failed.
 805  *
 806  * @discussion
 807  * A panic will occur if a kext calls this function to unload itself.
 808  * The safest way for a kext to unload itself is to call
 809  * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag
 810  * OSKextRetainKextWithLoadTag@/link</code>
 811  * with its own load tag
 812  * (the <code>id</code> field of its <code>kmod_info_t</code> struct),
 813  * followed by
 814  * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag
 815  * OSKextReleaseKextWithLoadTag@/link</code>;
 816  * this will schedule the kext for unload on a separate thread.
 817  *
 818  * This function can be used when reference-based autounloading is not
 819  * appropriate.
 820  * If a kernel system or kext is already monitoring
 821  * the need for a kext,
 822  * it can simply call this function when it's known that the kext is not needed.
 823  */
 824 OSReturn OSKextUnloadKextWithLoadTag(uint32_t loadTag);
 825
 826 #endif /* XNU_KERNEL_PRIVATE */
 827
 828 #endif /* KERNEL */
 829
 830 #if PRAGMA_MARK
 831 #pragma mark -
 832 /********************************************************************/
 833 #pragma mark Loaded Kext Summary
 834 /********************************************************************/
 835 #endif
 836
 837 /*!
 838  * @define kOSKextLoadedKextSummaryVersion
 839  * @abstract The current version of the loaded kext summary headers.
 840  */
 841 #define kOSKextLoadedKextSummaryVersion 2
 842
 843 /*!
 844  * @typedef OSKextLoadedKextSummary
 845  * @abstract A structure that describes a loaded kext.
 846  *
 847  * @field name The kext's bundle identifier.
 848  * @field uuid The kext's UUID;
 849  * @field address The kext's load address.
 850  * @field size The kext's load size.
 851  * @field version The binary format (OSKextVersion) version of the kext.
 852  * @field loadTag The kext's load tag.
 853  * @field flags Internal tracking flags.
 854  * @field reference_list who this refs (links on).
 855  *
 856  * @discussion
 857  * The OSKextLoadedKextSummary structure contains a basic set of information
 858  * about the kext to facilitate kext debugging and panic debug log output.
 859  */
 860 typedef struct _loaded_kext_summary {
 861     char        name[KMOD_MAX_NAME];
 862     uuid_t      uuid;
 863     uint64_t    address;
 864     uint64_t    size;
 865     uint64_t    version;
 866     uint32_t    loadTag;
 867     uint32_t    flags;
 868     uint64_t    reference_list;
 869 } OSKextLoadedKextSummary;
 870
 871 /*!
 872  * @typedef OSKextLoadedKextSummaryHeader
 873  * @abstract A structure that describes the set of loaded kext summaries.
 874  *
 875  * @field version The version of the loaded kext summary structures.
 876  * @field entry_size The size of each entry in summaries.
 877  * @field numSummaries The number of OSKextLoadedKextSummary structures
 878  *        following the header.
 879  * @field summaries A convenience pointer to the array of summaries following
 880  *        the header.
 881  *
 882  * @discussion
 883  * The OSKextLoadedKextSummaryHeader describes the set of loaded kext summaries
 884  * available for use by the debugger or panic log routine.
 885  * The array of summaries contains one OSKextLoadedKextSummary for every kext
 886  * that declares an executable and is not an interface to the kernel.
 887  */
 888 typedef struct _loaded_kext_summary_header {
 889     uint32_t version;
 890     uint32_t entry_size;
 891     uint32_t numSummaries;
 892     uint32_t reserved; /* explicit alignment for gdb  */
 893     OSKextLoadedKextSummary summaries[0];
 894 } OSKextLoadedKextSummaryHeader;
 895
 896 /*!
 897  * @var gLoadedKextSummaries
 898  * @abstract The global pointer to the current set of loaded kext summaries.
 899  */
 900 extern OSKextLoadedKextSummaryHeader * gLoadedKextSummaries;
 901
 902 /*!
 903  * @function OSKextLoadedKextSummariesUpdated
 904  * @abstract Called when gLoadedKextSummaries has been updated.
 905  *
 906  * @discussion
 907  * gLoadedKextSummaries is updated when a kext is loaded or unloaded.
 908  * When the update is complete, OSKextLoadedKextSummariesUpdated is called.
 909  * gdb can set a breakpoint on this function to detect kext loads and unloads.
 910  */
 911 void OSKextLoadedKextSummariesUpdated(void);
 912
 913 __END_DECLS
 914
 915 #endif /* ! _LIBKERN_OSKEXTLIBPRIVATE_H */