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