1 /* 2 * Copyright (c) 2008 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_OSKEXTLIB_H 30 #define _LIBKERN_OSKEXTLIB_H 31 32 #include <sys/cdefs.h> 33 #include <stdint.h> 34 #include <mach/kmod.h> 35 #include <mach/vm_types.h> 36 #include <uuid/uuid.h> 37 38 #ifdef KERNEL 39 #include <libkern/OSTypes.h> 40 #include <libkern/OSReturn.h> 41 #else 42 #include <libkern/OSReturn.h> 43 #endif /* KERNEL */ 44 45 __BEGIN_DECLS 46 47 /*! 48 * @header 49 * 50 * Declares functions, basic return values, and other constants 51 * related to kernel extensions (kexts). 52 */ 53 54 #if PRAGMA_MARK 55 #pragma mark - 56 /********************************************************************/ 57 #pragma mark OSReturn Values for Kernel Extensions 58 /********************************************************************/ 59 #endif 60 /*! 61 * @group OSReturn Values for Kernel Extensions 62 * Many kext-related functions return these values, 63 * as well as those defined under 64 * <code>@link //apple_ref/c/tdef/OSReturn OSReturn@/link</code> 65 * and other variants of <code>kern_return_t</code>. 66 */ 67 68 #ifdef XNU_KERNEL_PRIVATE 69 /********************************************************************* 70 * Check libsyscall/mach/err_libkern.sub when editing or adding 71 * result codes! 72 *********************************************************************/ 73 #endif /* XNU_KERNEL_PRIVATE */ 74 75 #define sub_libkern_kext err_sub(2) 76 #define libkern_kext_err(code) (sys_libkern|sub_libkern_kext|(code)) 77 78 79 /*! 80 * @define kOSKextReturnInternalError 81 * @abstract An internal error in the kext library. 82 * Contrast with <code>@link //apple_ref/c/econst/OSReturnError 83 * OSReturnError@/link</code>. 84 */ 85 #define kOSKextReturnInternalError libkern_kext_err(0x1) 86 87 /*! 88 * @define kOSKextReturnNoMemory 89 * @abstract Memory allocation failed. 90 */ 91 #define kOSKextReturnNoMemory libkern_kext_err(0x2) 92 93 /*! 94 * @define kOSKextReturnNoResources 95 * @abstract Some resource other than memory (such as available load tags) 96 * is exhausted. 97 */ 98 #define kOSKextReturnNoResources libkern_kext_err(0x3) 99 100 /*! 101 * @define kOSKextReturnNotPrivileged 102 * @abstract The caller lacks privileges to perform the requested operation. 103 */ 104 #define kOSKextReturnNotPrivileged libkern_kext_err(0x4) 105 106 /*! 107 * @define kOSKextReturnInvalidArgument 108 * @abstract Invalid argument. 109 */ 110 #define kOSKextReturnInvalidArgument libkern_kext_err(0x5) 111 112 /*! 113 * @define kOSKextReturnNotFound 114 * @abstract Search item not found. 115 */ 116 #define kOSKextReturnNotFound libkern_kext_err(0x6) 117 118 /*! 119 * @define kOSKextReturnBadData 120 * @abstract Malformed data (not used for XML). 121 */ 122 #define kOSKextReturnBadData libkern_kext_err(0x7) 123 124 /*! 125 * @define kOSKextReturnSerialization 126 * @abstract Error converting or (un)serializing URL, string, or XML. 127 */ 128 #define kOSKextReturnSerialization libkern_kext_err(0x8) 129 130 /*! 131 * @define kOSKextReturnUnsupported 132 * @abstract Operation is no longer or not yet supported. 133 */ 134 #define kOSKextReturnUnsupported libkern_kext_err(0x9) 135 136 /*! 137 * @define kOSKextReturnDisabled 138 * @abstract Operation is currently disabled. 139 */ 140 #define kOSKextReturnDisabled libkern_kext_err(0xa) 141 142 /*! 143 * @define kOSKextReturnNotAKext 144 * @abstract Bundle is not a kernel extension. 145 */ 146 #define kOSKextReturnNotAKext libkern_kext_err(0xb) 147 148 /*! 149 * @define kOSKextReturnValidation 150 * @abstract Validation failures encountered; check diagnostics for details. 151 */ 152 #define kOSKextReturnValidation libkern_kext_err(0xc) 153 154 /*! 155 * @define kOSKextReturnAuthentication 156 * @abstract Authetication failures encountered; check diagnostics for details. 157 */ 158 #define kOSKextReturnAuthentication libkern_kext_err(0xd) 159 160 /*! 161 * @define kOSKextReturnDependencies 162 * @abstract Dependency resolution failures encountered; check diagnostics for details. 163 */ 164 #define kOSKextReturnDependencies libkern_kext_err(0xe) 165 166 /*! 167 * @define kOSKextReturnArchNotFound 168 * @abstract Kext does not contain code for the requested architecture. 169 */ 170 #define kOSKextReturnArchNotFound libkern_kext_err(0xf) 171 172 /*! 173 * @define kOSKextReturnCache 174 * @abstract An error occurred processing a system kext cache. 175 */ 176 #define kOSKextReturnCache libkern_kext_err(0x10) 177 178 /*! 179 * @define kOSKextReturnDeferred 180 * @abstract Operation has been posted asynchronously to user space (kernel only). 181 */ 182 #define kOSKextReturnDeferred libkern_kext_err(0x11) 183 184 /*! 185 * @define kOSKextReturnBootLevel 186 * @abstract Kext not loadable or operation not allowed at current boot level. 187 */ 188 #define kOSKextReturnBootLevel libkern_kext_err(0x12) 189 190 /*! 191 * @define kOSKextReturnNotLoadable 192 * @abstract Kext cannot be loaded; check diagnostics for details. 193 */ 194 #define kOSKextReturnNotLoadable libkern_kext_err(0x13) 195 196 /*! 197 * @define kOSKextReturnLoadedVersionDiffers 198 * @abstract A different version (or executable UUID, or executable by checksum) 199 * of the requested kext is already loaded. 200 */ 201 #define kOSKextReturnLoadedVersionDiffers libkern_kext_err(0x14) 202 203 /*! 204 * @define kOSKextReturnDependencyLoadError 205 * @abstract A load error occurred on a dependency of the kext being loaded. 206 */ 207 #define kOSKextReturnDependencyLoadError libkern_kext_err(0x15) 208 209 /*! 210 * @define kOSKextReturnLinkError 211 * @abstract A link failure occured with this kext or a dependency. 212 */ 213 #define kOSKextReturnLinkError libkern_kext_err(0x16) 214 215 /*! 216 * @define kOSKextReturnStartStopError 217 * @abstract The kext start or stop routine returned an error. 218 */ 219 #define kOSKextReturnStartStopError libkern_kext_err(0x17) 220 221 /*! 222 * @define kOSKextReturnInUse 223 * @abstract The kext is currently in use or has outstanding references, 224 * and cannot be unloaded. 225 */ 226 #define kOSKextReturnInUse libkern_kext_err(0x18) 227 228 /*! 229 * @define kOSKextReturnTimeout 230 * @abstract A kext request has timed out. 231 */ 232 #define kOSKextReturnTimeout libkern_kext_err(0x19) 233 234 /*! 235 * @define kOSKextReturnStopping 236 * @abstract The kext is in the process of stopping; requests cannot be made. 237 */ 238 #define kOSKextReturnStopping libkern_kext_err(0x1a) 239 240 /*! 241 * @define kOSKextReturnSystemPolicy 242 * @abstract The kext was prevented from loading due to system policy. 243 */ 244 #define kOSKextReturnSystemPolicy libkern_kext_err(0x1b) 245 246 /*! 247 * @define kOSKextReturnKCLoadFailure 248 * @abstract Loading of the System KC failed 249 */ 250 #define kOSKextReturnKCLoadFailure libkern_kext_err(0x1c) 251 252 /*! 253 * @define kOSKextReturnKCLoadFailureSystemKC 254 * @abstract Loading of the System KC failed 255 * 256 * This a sub-code of kOSKextReturnKCLoadFailure. It can be OR'd together 257 * with: kOSKextReturnKCLoadFailureAuxKC 258 * 259 * If both the System and Aux KCs fail to load, then the error code will be: 260 * libkern_kext_err(0x1f) 261 */ 262 #define kOSKextReturnKCLoadFailureSystemKC libkern_kext_err(0x1d) 263 264 /*! 265 * @define kOSKextReturnKCLoadFailureAuxKC 266 * @abstract Loading of the Aux KC failed 267 * 268 * This a sub-code of kOSKextReturnKCLoadFailure. It can be OR'd together 269 * with: kOSKextReturnKCLoadFailureSystemKC 270 * 271 * If both the System and Aux KCs fail to load, then the error code will be: 272 * libkern_kext_err(0x1f) 273 */ 274 #define kOSKextReturnKCLoadFailureAuxKC libkern_kext_err(0x1e) 275 276 /* next available error is: libkern_kext_err(0x20) */ 277 278 #if PRAGMA_MARK 279 #pragma mark - 280 /********************************************************************/ 281 #pragma mark Kext/OSBundle Property List Keys 282 /********************************************************************/ 283 #endif 284 /*! 285 * @group Kext Property List Keys 286 * These constants cover CFBundle properties defined for kernel extensions. 287 * Because they are used in the kernel, if you want to use one with 288 * CFBundle APIs you'll need to wrap it in a <code>CFSTR()</code> macro. 289 */ 290 291 #ifdef KERNEL 292 /* Define C-string versions of the CFBundle keys for use in the kernel. 293 */ 294 #define kCFBundleIdentifierKey "CFBundleIdentifier" 295 #define kCFBundleIdentifierKernelKey "CFBundleIdentifierKernel" 296 #define kCFBundleVersionKey "CFBundleVersion" 297 #define kCFBundleNameKey "CFBundleName" 298 #define kCFBundleExecutableKey "CFBundleExecutable" 299 #define kCFBundlePackageTypeKey "CFBundlePackageType" 300 #define kCFBundleDriverKitUUIDKey "CFBundleDriverKitUUID" 301 #define kCFBundleDriverKitExecutableKey "CFBundleUEXTExecutable" 302 #endif /* KERNEL */ 303 304 /*! 305 * @define kOSBundleCompatibleVersionKey 306 * @abstract A string giving the backwards-compatible version of a library kext 307 * in extended Mac OS 'vers' format (####.##.##s{1-255} where 's' 308 * is a build stage 'd', 'a', 'b', 'f' or 'fc'). 309 */ 310 #define kOSBundleCompatibleVersionKey "OSBundleCompatibleVersion" 311 312 /*! 313 * @define kOSBundleEnableKextLoggingKey 314 * @abstract Set to true to have the kernel kext logging spec applied 315 * to the kext. 316 * See <code>@link //apple_ref/c/econst/OSKextLogSpec 317 * OSKextLogSpec@/link</code>. 318 */ 319 #define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging" 320 321 /*! 322 * @define kOSBundleIsInterfaceKey 323 * @abstract A boolean value indicating whether the kext executable 324 * contains only symbol references. 325 */ 326 #define kOSBundleIsInterfaceKey "OSBundleIsInterface" 327 328 /*! 329 * @define kOSBundleLibrariesKey 330 * @abstract A dictionary listing link dependencies for this kext. 331 * Keys are bundle identifiers, values are version strings. 332 */ 333 #define kOSBundleLibrariesKey "OSBundleLibraries" 334 335 /*! 336 * @define kOSBundleRequiredKey 337 * @abstract A string indicating in which kinds of startup this kext 338 * may need to load during early startup (before 339 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>). 340 * @discussion 341 * The value is one of: 342 * <ul> 343 * <li>@link kOSBundleRequiredRoot "OSBundleRequiredRoot"@/link</li> 344 * <li>@link kOSBundleRequiredLocalRoot "OSBundleRequiredLocalRoot"@/link</li> 345 * <li>@link kOSBundleRequiredNetworkRoot "OSBundleRequiredNetworkRoot"@/link</li> 346 * <li>@link kOSBundleRequiredSafeBoot "OSBundleRequiredSafeBoot"@/link</li> 347 * <li>@link kOSBundleRequiredConsole "OSBundleRequiredConsole"@/link</li> 348 * </ul> 349 * 350 * Use this property judiciously. 351 * Every kext that declares a value other than "OSBundleRequiredSafeBoot" 352 * increases startup time, as the booter must read it into memory, 353 * or startup kext caches must include it. 354 */ 355 #define kOSBundleRequiredKey "OSBundleRequired" 356 357 /*! 358 * @define kOSBundleRequireExplicitLoadKey 359 * @abstract A boolean value indicating whether the kext requires an 360 * explicit kextload in order to start/match. 361 */ 362 #define kOSBundleRequireExplicitLoadKey "OSBundleRequireExplicitLoad" 363 364 /*! 365 * @define kOSBundleAllowUserLoadKey 366 * @abstract A boolean value indicating whether 367 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code> 368 * will honor a non-root process's request to load a kext. 369 * @discussion 370 * See <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithURL 371 * KextManagerLoadKextWithURL@/link</code> 372 * and <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithIdentifier 373 * KextManagerLoadKextWithIdentifier@/link</code>. 374 */ 375 #define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad" 376 377 /*! 378 * @define kOSBundleAllowUserTerminateKey 379 * @abstract A boolean value indicating whether the kextunload tool 380 * is allowed to issue IOService terminate to classes defined in this kext. 381 * @discussion A boolean value indicating whether the kextunload tool 382 * is allowed to issue IOService terminate to classes defined in this kext. 383 */ 384 #define kOSBundleAllowUserTerminateKey "OSBundleAllowUserTerminate" 385 386 /*! 387 * @define kOSKernelResourceKey 388 * @abstract A boolean value indicating whether the kext represents a built-in 389 * component of the kernel. 390 */ 391 #define kOSKernelResourceKey "OSKernelResource" 392 393 /*! 394 * @define kOSKextVariantOverrideKey 395 * @abstract A dictionary with target names as key and a target-specific variant 396 * name as value. 397 */ 398 #define kOSKextVariantOverrideKey "OSKextVariantOverride" 399 400 /*! 401 * @define kIOKitPersonalitiesKey 402 * @abstract A dictionary of dictionaries used in matching for I/O Kit drivers. 403 */ 404 #define kIOKitPersonalitiesKey "IOKitPersonalities" 405 406 /* 407 * @define kIOPersonalityPublisherKey 408 * @abstract Used in personalities sent to the I/O Kit, 409 * contains the CFBundleIdentifier of the kext 410 * that the personality originated in. 411 */ 412 #define kIOPersonalityPublisherKey "IOPersonalityPublisher" 413 414 #if CONFIG_KEC_FIPS 415 /* 416 * @define kAppleTextHashesKey 417 * @abstract A dictionary conataining hashes for corecrypto kext. 418 */ 419 #define kAppleTextHashesKey "AppleTextHashes" 420 #endif 421 422 /*! 423 * @define kOSMutableSegmentCopy 424 * @abstract A boolean value indicating whether the kext requires a copy of 425 * its mutable segments to be kept in memory, and then reset when the kext 426 * unloads. This should be used with caution as it will increase the 427 * amount of memory used by the kext. 428 */ 429 #define kOSMutableSegmentCopy "OSMutableSegmentCopy" 430 431 432 #if PRAGMA_MARK 433 /********************************************************************/ 434 #pragma mark Kext/OSBundle Property Deprecated Keys 435 /********************************************************************/ 436 #endif 437 /* 438 * @define kOSBundleDebugLevelKey 439 * @abstract 440 * Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard). 441 * Value is an integer from 1-6, corresponding to the verbose levels 442 * of kext tools on those releases. 443 * On 10.6 Snow Leopard, use <code>@link OSKextEnableKextLogging 444 * OSKextEnableKextLogging@/link</code>. 445 */ 446 #define kOSBundleDebugLevelKey "OSBundleDebugLevel" 447 448 /*! 449 * @define kOSBundleSharedExecutableIdentifierKey 450 * @abstract Deprecated (used on some releases of Mac OS X 451 * prior to 10.6 Snow Leopard). 452 * Value is the bundle identifier of the pseudokext 453 * that contains an executable shared by this kext. 454 */ 455 #define kOSBundleSharedExecutableIdentifierKey "OSBundleSharedExecutableIdentifier" 456 457 458 #if PRAGMA_MARK 459 /********************************************************************/ 460 #pragma mark Kext/OSBundle Property List Values 461 /********************************************************************/ 462 #endif 463 464 /*! 465 * @group Kext Property List Values 466 * These constants encompass established values 467 * for kernel extension bundle properties. 468 */ 469 470 /*! 471 * @define kOSKextKernelIdentifier 472 * @abstract 473 * This is the CFBundleIdentifier user for the kernel itself. 474 */ 475 #define kOSKextKernelIdentifier "__kernel__" 476 477 #if CONFIG_SPTM && PRIVATE 478 /*! 479 * @define kOSKextSPTMIdentifier 480 * @abstract 481 * This is the CFBundleIdentifier used by the Secure Page Table Monitor (SPTM). 482 */ 483 #define kOSKextSPTMIdentifier "com.apple.sptm" 484 485 /*! 486 * @define kOSKextTXMIdentifier 487 * @abstract 488 * This is the CFBundleIdentifier used by the Trusted Execution Monitor (TXM). 489 */ 490 #define kOSKextTXMIdentifier "com.apple.txm" 491 #endif /* CONFIG_SPTM */ 492 493 /*! 494 * @define kOSKextBundlePackageTypeKext 495 * @abstract 496 * The bundle type value for Kernel Extensions. 497 */ 498 #define kOSKextBundlePackageTypeKext "KEXT" 499 500 /*! 501 * @define kOSKextBundlePackageTypeDriverKit 502 * @abstract 503 * The bundle type value for Driver Extensions. 504 */ 505 #define kOSKextBundlePackageTypeDriverKit "DEXT" 506 507 /*! 508 * @define kOSBundleRequiredRoot 509 * @abstract 510 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 511 * value indicates that the kext may be needed to mount the root filesystem 512 * whether starting from a local or a network volume. 513 */ 514 #define kOSBundleRequiredRoot "Root" 515 516 /*! 517 * @define kOSBundleRequiredLocalRoot 518 * @abstract 519 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 520 * value indicates that the kext may be needed to mount the root filesystem 521 * when starting from a local disk. 522 */ 523 #define kOSBundleRequiredLocalRoot "Local-Root" 524 525 /*! 526 * @define kOSBundleRequiredNetworkRoot 527 * @abstract 528 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 529 * value indicates that the kext may be needed to mount the root filesystem 530 * when starting over a network connection. 531 */ 532 #define kOSBundleRequiredNetworkRoot "Network-Root" 533 534 /*! 535 * @define kOSBundleRequiredSafeBoot 536 * @abstract 537 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 538 * value indicates that the kext can be loaded during a safe startup. 539 * This value does not normally cause the kext to be read by the booter 540 * or included in startup kext caches. 541 */ 542 #define kOSBundleRequiredSafeBoot "Safe Boot" 543 544 /*! 545 * @define kOSBundleRequiredConsole 546 * @abstract 547 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 548 * value indicates that the kext may be needed for console access 549 * (specifically in a single-user startup when 550 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 551 * does not run) 552 * and should be loaded during early startup. 553 */ 554 #define kOSBundleRequiredConsole "Console" 555 556 /*! 557 * @define kOSBundleRequiredDriverKit 558 * @abstract 559 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 560 * value indicates that the driver extension's (DriverKit driver's) 561 * personalities must be present in the kernel at early boot (specifically 562 * before <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code> starts) 563 * in order to compete with kexts built into the prelinkedkernel. Note that 564 * kextd is still required to launch the user space driver binary. The IOKit 565 * matching will happen during early boot, and the actual driver launch 566 * will happen after kextd starts. 567 */ 568 #define kOSBundleRequiredDriverKit "DriverKit" 569 570 #if PRAGMA_MARK 571 #pragma mark - 572 /********************************************************************/ 573 #pragma mark Kext Information 574 /********************************************************************/ 575 #endif 576 /*! 577 * @group Kext Information 578 * Types, constants, and macros providing a kext with information 579 * about itself. 580 */ 581 582 #ifdef KERNEL 583 /*! 584 * @typedef OSKextLoadTag 585 * 586 * @abstract 587 * A unique identifier assigned to a loaded instanace of a kext. 588 * 589 * @discussion 590 * If a kext is unloaded and later reloaded, the new instance 591 * has a different load tag. 592 * 593 * A kext can get its own load tag in the <code>kmod_info_t</code> 594 * structure passed into its module start routine, as the 595 * <code>id</code> field (cast to this type). 596 * You can use the load tag with the functions 597 * <code>@link OSKextRetainKextWithLoadTag 598 * OSKextRetainKextWithLoadTag@/link</code> and 599 * <code>@link OSKextReleaseKextWithLoadTag 600 * OSKextReleaseKextWithLoadTag@/link</code>. 601 */ 602 #else 603 /*! 604 * @typedef OSKextLoadTag 605 * 606 * @abstract 607 * A unique identifier assigned to a loaded instanace of a kext. 608 * 609 * @discussion 610 * If a kext is unloaded and later reloaded, the new instance 611 * has a different load tag. 612 * 613 * A kext can get its own load tag in the <code>kmod_info_t</code> 614 * structure passed into its module start routine, as the 615 * <code>id</code> field (cast to this type). 616 */ 617 #endif 618 typedef uint32_t OSKextLoadTag; 619 620 /*! 621 * @define kOSKextInvalidLoadTag 622 * 623 * @abstract 624 * A load tag value that will never be used for a loaded kext; 625 * indicates kext not found. 626 */ 627 #define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1)) 628 629 #ifdef KERNEL 630 631 /* Make these visible to kexts only and *not* the kernel. 632 */ 633 #if !XNU_KERNEL_PRIVATE 634 635 /*! 636 * @function OSKextGetCurrentLoadTag 637 * 638 * @abstract 639 * Returns the run-time load tag for the calling kext as an 640 * <code>@link OSKextLoadTag OSKextLoadTag@/link</code>. 641 * 642 * @result 643 * The run-time load tag for the calling kext as an 644 * <code>@link OSKextLoadTag@/link</code>. 645 * 646 * @discussion 647 * The load tag identifies this loaded instance of the kext to the kernel 648 * and to kernel functions that operate on kexts. 649 */ 650 OSKextLoadTag OSKextGetCurrentLoadTag(void); 651 652 /*! 653 * @function OSKextGetCurrentIdentifier 654 * 655 * @abstract 656 * Returns the CFBundleIdentifier for the calling kext as a C string. 657 * 658 * @result 659 * The CFBundleIdentifier for the calling kext as a C string. 660 */ 661 const char * OSKextGetCurrentIdentifier(void); 662 663 /*! 664 * @function OSKextGetCurrentVersionString 665 * 666 * @abstract 667 * Returns the CFBundleVersion for the calling kext as a C string. 668 * 669 * @result 670 * The CFBundleVersion for the calling kext as a C string. 671 */ 672 const char * OSKextGetCurrentVersionString(void); 673 674 #endif /* !XNU_KERNEL_PRIVATE */ 675 676 #if PRAGMA_MARK 677 #pragma mark - 678 /********************************************************************/ 679 #pragma mark Kext Loading C Functions 680 /********************************************************************/ 681 #endif 682 /*! 683 * @group Kext Loading C Functions 684 * Functions for loading and tracking kexts in the kernel. 685 */ 686 687 /*! 688 * @function OSKextLoadKextWithIdentifier 689 * 690 * @abstract 691 * Request that a kext be loaded. 692 * 693 * @param kextIdentifier The bundle identifier of the kext to be loaded. 694 * 695 * @result 696 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 697 * if the kext was loaded (or was already loaded). 698 * <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> 699 * if the kext was not found and a request 700 * was queued to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 701 * Other return values indicate a failure to load the kext. 702 * 703 * @discussion 704 * If a kext is already in the kernel but not loaded, it is loaded immediately. 705 * If it isn't found, an asynchronous load request is 706 * made to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code> 707 * and <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> is returned. 708 * There is no general notification or callback mechanism for load requests. 709 */ 710 OSReturn OSKextLoadKextWithIdentifier(const char * kextIdentifier); 711 712 713 /*! 714 * @function OSKextRetainKextWithLoadTag 715 * 716 * @abstract 717 * Retain a loaded kext based on its load tag, 718 * and enable autounload for that kext. 719 * 720 * @param loadTag The load tag of the kext to be retained. 721 * See <code>@link OSKextGetCurrentLoadTag@/link</code>. 722 * 723 * @result 724 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 725 * if the kext was retained. 726 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound kOSKextReturnNotFound@/link</code> 727 * if the kext was not found. 728 * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument 729 * kOSKextReturnInvalidArgument@/link</code> 730 * if <code>loadTag</code> is 731 * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>. 732 * 733 * @discussion 734 * Retaining a kext prevents it from being unloaded, 735 * either explicitly or automatically, and enables autounload for the kext. 736 * When autounload is enabled, then shortly after the kext's last reference 737 * is dropped, it will be unloaded if there are no outstanding references to it 738 * and there are no instances of its Libkern C++ subclasses (if any). 739 * 740 * Kexts that define subclasses of 741 * <code>@link //apple_ref/doc/class/IOService IOService@/link</code> 742 * have autounload enabled automatically. 743 * Other kexts can use the reference count to manage automatic unload 744 * without having to define and create Libkern C++ objects. 745 * For example, a filesystem kext can retain itself whenever a new mount 746 * is created, and release itself when a mount is removed. 747 * When the last mount is removed, the kext will be unloaded after a brief delay. 748 * 749 * A kext can get its own load tag using the 750 * <code>@link OSKextGetCurrentLoadTag@/link</code>. 751 * 752 * Kexts should not retain and release other kexts; linkage references 753 * are accounted for internally. 754 */ 755 OSReturn OSKextRetainKextWithLoadTag(OSKextLoadTag loadTag); 756 757 758 /*! 759 * @function OSKextReleaseKextWithLoadTag 760 * 761 * @abstract 762 * Release a loaded kext based on its load tag. 763 * 764 * @param loadTag The load tag of the kext to be released. 765 * See <code>@link OSKextGetCurrentLoadTag@/link</code>. 766 * 767 * @result 768 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 769 * if the kext was released. 770 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound 771 * kOSKextReturnNotFound@/link</code> 772 * if the kext was not found. 773 * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument 774 * kOSKextReturnInvalidArgument@/link</code> 775 * if <code>loadTag</code> is 776 * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>. 777 * 778 * @discussion 779 * The kext should have been retained previously via 780 * <code>@link OSKextRetainKextWithLoadTag@/link</code>. 781 * 782 * This function schedules an autounload scan for all kexts. 783 * When that scan occurs, if a kext has autounload enabled, 784 * it will be unloaded if there are no outstanding references to it 785 * and there are no instances of its Libkern C++ classes (if any). 786 * 787 * Kexts that define subclasses of 788 * <code>@link //apple_ref/doc/class/IOService IOService@/link</code> 789 * have autounload enabled automatically. 790 * Other kexts can use the reference count to manage automatic unload 791 * without having to define and create Libkern C++ objects. 792 * For example, a filesystem kext can be retained whenever a new mount 793 * is created, and released when a mount is removed. 794 * When the last mount is removed, the kext will be unloaded after a brief delay. 795 * 796 * While the autounload scan takes place after a delay of at least a minute, 797 * a kext that manages its own reference counts for autounload should 798 * be prepared to have its module stop function called even while the function 799 * calling this function is still running. 800 * 801 * A kext can get its own load tag using the 802 * <code>@link OSKextGetCurrentLoadTag@/link</code>. 803 * 804 * Kexts should not retain and release other kexts; linkage references 805 * are accounted for internally. 806 */ 807 OSReturn OSKextReleaseKextWithLoadTag(OSKextLoadTag loadTag); 808 809 #if PRAGMA_MARK 810 /********************************************************************/ 811 #pragma mark - 812 #pragma mark Kext Requests 813 /********************************************************************/ 814 #endif 815 /*! 816 * @group Kext Requests to User Space 817 * Functions for making requests to kextd in user space. 818 */ 819 820 /*! 821 * @typedef OSKextRequestTag 822 * 823 * @abstract 824 * Identifies a kext request made to user space. 825 */ 826 typedef uint32_t OSKextRequestTag; 827 828 /*! 829 * @define kOSKextRequestTagInvalid 830 * 831 * @abstract 832 * A request tag value that will never be used for a kext request; 833 * indicates failure to create/queue the request. 834 */ 835 #define kOSKextRequestTagInvalid ((OSKextRequestTag)-1) 836 837 /*! 838 * @typedef OSKextRequestResourceCallback 839 * 840 * @abstract 841 * Invoked to provide results for a kext resource request. 842 * 843 * @param requestTag The tag of the request that the callback pertains to. 844 * @param result The result of the request: 845 * <code>@link kOSReturnSuccess 846 * kOSReturnSuccess@/link</code> 847 * if the request was fulfilled; 848 * <code>@link kOSKextReturnTimeout 849 * kOSKextReturnTimeout@/link</code> 850 * if the request has timed out; 851 * <code>@link kOSKextReturnStopping 852 * kOSKextReturnStopping@/link</code> 853 * if the kext containing the callback 854 * address for the kext is being unloaded; 855 * or other values on error. 856 * @param resourceData A pointer to the requested resource data. 857 * Owned by the system; the kext should make a copy 858 * if it needs to keep the data past the callback. 859 * @param resourceDataLength The length of <code>resourceData</code>. 860 * @param context The context pointer originally passed to 861 * <code>@link OSKextRequestResource 862 * OSKextRequestResource@/link</code>. 863 */ 864 typedef void (* OSKextRequestResourceCallback)( 865 OSKextRequestTag requestTag, 866 OSReturn result, 867 const void * resourceData, 868 uint32_t resourceDataLength, 869 void * context); 870 871 /*! 872 * @function OSKextRequestResource 873 * 874 * @abstract 875 * Requests data from a nonlocalized resource file in a kext bundle on disk. 876 * 877 * @param kextIdentifier The CFBundleIdentifier of the kext 878 * from which to read the file. 879 * @param resourceName The name of the resource file to read. 880 * @param callback A pointer to a callback function; the address 881 * must be within a currently-loaded kext. 882 * @param context A pointer to arbitrary run-time data 883 * that will be passed to the callback 884 * when it is invoked. May be <code>NULL</code>. 885 * @param requestTagOut If non-<code>NULL</code>, 886 * filled on success with a tag identifying the 887 * pending request 888 * (or on failure with <code>@link kOSKextRequestTagInvalid 889 * kOSKextRequestTagInvalid@/link</code>; 890 * can be used with 891 * <code>@link OSKextCancelRequest 892 * OSKextCancelRequest@/link</code>. 893 * 894 * @result 895 * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code> 896 * if the request is successfully queued. 897 * <code>@link kOSKextReturnInvalidArgument kOSKextReturnInvalidArgument@/link</code> 898 * if <code>kextIdentifier</code> or <code>resourceName</code> or if 899 * <code>callback</code> is not an address within a loaded kext executable. 900 * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code> 901 * if an unload attempt is being made 902 * on the kext containing <code>callback</code>. 903 * Other <code>OSKextReturn...</code> errors are possible. 904 * 905 * @discussion 906 * This function queues an asynchronous request to the user-space kext daemon 907 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>; 908 * requests for resources early in system startup 909 * will not be fulfilled until that daemon starts. 910 * Requests made by a kext while that kext is loading 911 * (specifically in the kext's module start routine) 912 * will not be fulfilled until after the start routine returns and 913 * the kext is completely loaded. 914 * Kexts requesting resources should be sure to perform appropriate locking 915 * in the callback function. 916 * 917 * Kext resources are stored in the kext's on-disk bundle under the 918 * Resources subdirectory. 919 * See {@linkdoc //apple_ref/doc/uid/10000123i Bundle Programming Guide} 920 * for an overview of bundle structure. 921 * The localization context of the kext daemon 922 * (namely that of the superuser) 923 * will be used in retrieving resources; 924 * kext resources intended for use in the kernel 925 * should generally not be localized. 926 * 927 * <code>callback</code> is guaranteed to be invoked except when: 928 * <ul> 929 * <li>@link OSKextCancelRequest <code>OSKextCancelRequest</code>@/link 930 * is used to cancel the request. 931 * In this case the kext gets the <code>context</code> pointer 932 * and can clean it up.</li> 933 * <li>The request is made during a kext's module start routine 934 * and the start routine returns an error. 935 * In this case, callbacks cannot be safely invoked, so 936 * the kext should clean up all request contexts 937 * when returning the error from the start routine.</li> 938 * </ul> 939 * 940 * Kexts with pending requests are not subject to autounload, 941 * but requests are subject to timeout after a few minutes. 942 * If that amount of time passes with no response from user space, 943 * <code>callback</code> is invoked with a result of. 944 * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code>. 945 * 946 * Kexts that are explicitly unloaded have all pending request callbacks 947 * invoked with a result of 948 * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code>. 949 * The kext must handle these callbacks, 950 * even if its stop routine will prevent unloading. 951 * If the kext does prevent unloading, it can reissue resource requests 952 * outside of the stop function. 953 */ 954 OSReturn OSKextRequestResource( 955 const char * kextIdentifier, 956 const char * resourceName, 957 OSKextRequestResourceCallback callback, 958 void * context, 959 OSKextRequestTag * requestTagOut); 960 961 /*! 962 * @function OSKextCancelRequest 963 * 964 * @abstract 965 * Cancels a pending user-space kext request without invoking the callback. 966 * 967 * @param requestTag A tag identifying a pending request. 968 * @param contextOut If non-<code>NULL</code>, filled with the context pointer 969 * originally passed with the request. 970 * 971 * @result 972 * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code> 973 * if the request is successfully canceled. 974 * <code>@link kOSKextReturnNotFound kOSKextReturnNotFound@/link</code> 975 * if <code>requestTag</code> does not identify any pending request. 976 * Other <code>OSKextReturn...</code> errors are possible. 977 * 978 * @discussion 979 * This function cancels a pending request if it exists, 980 * so that its callback will not be invoked. 981 * It returns in <code>contextOut</code> 982 * the context pointer used to create the request 983 * so that any resources allocated for the request can be cleaned up. 984 * 985 * Kexts do not need to cancel outstanding requests 986 * in their module stop functions; 987 * when a kext is unloaded, all pending request callbacks 988 * are invoked with a result of 989 * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code> 990 * before the stop function is called. 991 */ 992 OSReturn OSKextCancelRequest( 993 OSKextRequestTag requestTag, 994 void ** contextOut); 995 996 997 /*! 998 * @function OSKextGrabPgoData 999 * 1000 * @abstract 1001 * Grab a LLVM profile data buffer from a loaded kext. 1002 * 1003 * @param uuid the uuid identifying the kext to retrieve data from 1004 * @param pSize pointer of where to store the size of the buffer. May be NULL. 1005 * @param pBuffer pointer to the output buffer. May be NULL. 1006 * @param bufferSize size of the buffer pointed to by pBuffer 1007 * @param wait_for_unload (boolean) sleep until the kext is unloaded 1008 * @param metadata (boolean) include metadata footer 1009 * 1010 * @result 1011 * 0 on success 1012 * ENOTSUP if the kext does not have profile data to retrieve. 1013 * ENOTSUP if no kext with the given UUID is found 1014 * ERRORS if the provided buffer is too small 1015 * EIO internal error, such as if __llvm_profile_write_buffer_internal fails 1016 */ 1017 int 1018 OSKextGrabPgoData(uuid_t uuid, 1019 uint64_t *pSize, 1020 char *pBuffer, 1021 uint64_t bufferSize, 1022 int wait_for_unload, 1023 int metadata); 1024 1025 /*! 1026 * @function OSKextResetPgoCountersLock 1027 * 1028 * @abstract 1029 * Call this function before trapping into the debugger to call OSKextResetPgoCounters. 1030 */ 1031 void 1032 OSKextResetPgoCountersLock(void); 1033 1034 /*! 1035 * @function OSKextResetPgoCountersUnlock 1036 * 1037 * @abstract 1038 * Call this function after trapping into the debugger to call OSKextResetPgoCounters. 1039 */ 1040 void 1041 OSKextResetPgoCountersUnlock(void); 1042 1043 /*! 1044 * @function OSKextResetPgoCounters 1045 * 1046 * @abstract Reset the PGO counters for all kexts. Call only from debugger 1047 * context, while holding OSKextResetPgoCountersLock(). 1048 */ 1049 void 1050 OSKextResetPgoCounters(void); 1051 1052 1053 #if PRAGMA_MARK 1054 #pragma mark - 1055 /********************************************************************/ 1056 #pragma mark Weak linking 1057 /********************************************************************/ 1058 #endif 1059 /*! 1060 * @group Weak Linking 1061 * Support for weak references to symbols in kexts. 1062 */ 1063 1064 /*! 1065 * @var gOSKextUnresolved 1066 * 1067 * @abstract 1068 * The value to which a kext's unresolved, weakly-referenced symbols are bound. 1069 * 1070 * @discussion 1071 * A kext must test a weak symbol before using it. A weak symbol 1072 * is only safe to use if it is not equal to <code>gOSKextUnresolved</code>. 1073 * 1074 * Example for a weak symbol named <code>foo</code>: 1075 * <pre> 1076 * @textblock 1077 * if (&foo != gOSKextUnresolved) { 1078 * foo(); 1079 * } else { 1080 * printf("foo() is not supported\n"); 1081 * } 1082 * @/textblock 1083 * </pre> 1084 */ 1085 extern const void * const gOSKextUnresolved; 1086 1087 /*! 1088 * @define OSKextSymbolIsResolved 1089 * 1090 * @abstract 1091 * Checks whether a weakly-referenced symbol has been resolved. 1092 * 1093 * @param weak_sym The weak symbol to be tested for resolution. 1094 * 1095 * @result 1096 * <code>TRUE</code> if weak_sym is resolved, or <code>FALSE</code> 1097 * if weak_sym is unresolved. 1098 * 1099 * @discussion 1100 * This is a convenience macro for testing if weak symbols are resolved. 1101 * 1102 * Example for a weak symbol named <code>foo</code>: 1103 * <pre> 1104 * @textblock 1105 * if (OSKextSymbolIsResolved(foo)) { 1106 * foo(); 1107 * } else { 1108 * printf("foo() is not resolved\n"); 1109 * } 1110 * @/textblock 1111 * </pre> 1112 */ 1113 #define OSKextSymbolIsResolved(weak_sym) \ 1114 (&(weak_sym) != gOSKextUnresolved) 1115 1116 1117 #if CONFIG_KEC_FIPS 1118 1119 #if PRAGMA_MARK 1120 #pragma mark - 1121 /********************************************************************/ 1122 #pragma mark Kernel External Components for FIPS compliance 1123 /********************************************************************/ 1124 #endif 1125 1126 // Kernel External Components for FIPS compliance (KEC_FIPS) 1127 // WARNING - ath_hash is owned by the kernel, do not free 1128 typedef struct AppleTEXTHash { 1129 int ath_version;// version of this structure (value is 1 or 2) 1130 int ath_length; // length of hash data 1131 void * ath_hash; // hash extracted from AppleTextHashes dict 1132 } AppleTEXTHash_t; 1133 #endif // CONFIG_KEC_FIPS 1134 1135 #endif /* KERNEL */ 1136 1137 __END_DECLS 1138 1139 #endif /* _LIBKERN_OSKEXTLIB_H */ 1140