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