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