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 __BEGIN_DECLS 34 35 #include <stdint.h> 36 #include <mach/kmod.h> 37 #include <mach/vm_types.h> 38 #include <uuid/uuid.h> 39 40 #ifdef KERNEL 41 #include <libkern/OSTypes.h> 42 #include <libkern/OSReturn.h> 43 #else 44 #include <libkern/OSReturn.h> 45 #endif /* KERNEL */ 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 478 /*! 479 * @define kOSKextBundlePackageTypeKext 480 * @abstract 481 * The bundle type value for Kernel Extensions. 482 */ 483 #define kOSKextBundlePackageTypeKext "KEXT" 484 485 /*! 486 * @define kOSKextBundlePackageTypeDriverKit 487 * @abstract 488 * The bundle type value for Driver Extensions. 489 */ 490 #define kOSKextBundlePackageTypeDriverKit "DEXT" 491 492 /*! 493 * @define kOSBundleRequiredRoot 494 * @abstract 495 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 496 * value indicates that the kext may be needed to mount the root filesystem 497 * whether starting from a local or a network volume. 498 */ 499 #define kOSBundleRequiredRoot "Root" 500 501 /*! 502 * @define kOSBundleRequiredLocalRoot 503 * @abstract 504 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 505 * value indicates that the kext may be needed to mount the root filesystem 506 * when starting from a local disk. 507 */ 508 #define kOSBundleRequiredLocalRoot "Local-Root" 509 510 /*! 511 * @define kOSBundleRequiredNetworkRoot 512 * @abstract 513 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 514 * value indicates that the kext may be needed to mount the root filesystem 515 * when starting over a network connection. 516 */ 517 #define kOSBundleRequiredNetworkRoot "Network-Root" 518 519 /*! 520 * @define kOSBundleRequiredSafeBoot 521 * @abstract 522 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 523 * value indicates that the kext can be loaded during a safe startup. 524 * This value does not normally cause the kext to be read by the booter 525 * or included in startup kext caches. 526 */ 527 #define kOSBundleRequiredSafeBoot "Safe Boot" 528 529 /*! 530 * @define kOSBundleRequiredConsole 531 * @abstract 532 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 533 * value indicates that the kext may be needed for console access 534 * (specifically in a single-user startup when 535 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 536 * does not run) 537 * and should be loaded during early startup. 538 */ 539 #define kOSBundleRequiredConsole "Console" 540 541 /*! 542 * @define kOSBundleRequiredDriverKit 543 * @abstract 544 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 545 * value indicates that the driver extension's (DriverKit driver's) 546 * personalities must be present in the kernel at early boot (specifically 547 * before <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code> starts) 548 * in order to compete with kexts built into the prelinkedkernel. Note that 549 * kextd is still required to launch the user space driver binary. The IOKit 550 * matching will happen during early boot, and the actual driver launch 551 * will happen after kextd starts. 552 */ 553 #define kOSBundleRequiredDriverKit "DriverKit" 554 555 #if PRAGMA_MARK 556 #pragma mark - 557 /********************************************************************/ 558 #pragma mark Kext Information 559 /********************************************************************/ 560 #endif 561 /*! 562 * @group Kext Information 563 * Types, constants, and macros providing a kext with information 564 * about itself. 565 */ 566 567 #ifdef KERNEL 568 /*! 569 * @typedef OSKextLoadTag 570 * 571 * @abstract 572 * A unique identifier assigned to a loaded instanace of a kext. 573 * 574 * @discussion 575 * If a kext is unloaded and later reloaded, the new instance 576 * has a different load tag. 577 * 578 * A kext can get its own load tag in the <code>kmod_info_t</code> 579 * structure passed into its module start routine, as the 580 * <code>id</code> field (cast to this type). 581 * You can use the load tag with the functions 582 * <code>@link OSKextRetainKextWithLoadTag 583 * OSKextRetainKextWithLoadTag@/link</code> and 584 * <code>@link OSKextReleaseKextWithLoadTag 585 * OSKextReleaseKextWithLoadTag@/link</code>. 586 */ 587 #else 588 /*! 589 * @typedef OSKextLoadTag 590 * 591 * @abstract 592 * A unique identifier assigned to a loaded instanace of a kext. 593 * 594 * @discussion 595 * If a kext is unloaded and later reloaded, the new instance 596 * has a different load tag. 597 * 598 * A kext can get its own load tag in the <code>kmod_info_t</code> 599 * structure passed into its module start routine, as the 600 * <code>id</code> field (cast to this type). 601 */ 602 #endif 603 typedef uint32_t OSKextLoadTag; 604 605 /*! 606 * @define kOSKextInvalidLoadTag 607 * 608 * @abstract 609 * A load tag value that will never be used for a loaded kext; 610 * indicates kext not found. 611 */ 612 #define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1)) 613 614 #ifdef KERNEL 615 616 /* Make these visible to kexts only and *not* the kernel. 617 */ 618 #if !XNU_KERNEL_PRIVATE 619 620 /*! 621 * @function OSKextGetCurrentLoadTag 622 * 623 * @abstract 624 * Returns the run-time load tag for the calling kext as an 625 * <code>@link OSKextLoadTag OSKextLoadTag@/link</code>. 626 * 627 * @result 628 * The run-time load tag for the calling kext as an 629 * <code>@link OSKextLoadTag@/link</code>. 630 * 631 * @discussion 632 * The load tag identifies this loaded instance of the kext to the kernel 633 * and to kernel functions that operate on kexts. 634 */ 635 OSKextLoadTag OSKextGetCurrentLoadTag(void); 636 637 /*! 638 * @function OSKextGetCurrentIdentifier 639 * 640 * @abstract 641 * Returns the CFBundleIdentifier for the calling kext as a C string. 642 * 643 * @result 644 * The CFBundleIdentifier for the calling kext as a C string. 645 */ 646 const char * OSKextGetCurrentIdentifier(void); 647 648 /*! 649 * @function OSKextGetCurrentVersionString 650 * 651 * @abstract 652 * Returns the CFBundleVersion for the calling kext as a C string. 653 * 654 * @result 655 * The CFBundleVersion for the calling kext as a C string. 656 */ 657 const char * OSKextGetCurrentVersionString(void); 658 659 #endif /* !XNU_KERNEL_PRIVATE */ 660 661 #if PRAGMA_MARK 662 #pragma mark - 663 /********************************************************************/ 664 #pragma mark Kext Loading C Functions 665 /********************************************************************/ 666 #endif 667 /*! 668 * @group Kext Loading C Functions 669 * Functions for loading and tracking kexts in the kernel. 670 */ 671 672 /*! 673 * @function OSKextLoadKextWithIdentifier 674 * 675 * @abstract 676 * Request that a kext be loaded. 677 * 678 * @param kextIdentifier The bundle identifier of the kext to be loaded. 679 * 680 * @result 681 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 682 * if the kext was loaded (or was already loaded). 683 * <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> 684 * if the kext was not found and a request 685 * was queued to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 686 * Other return values indicate a failure to load the kext. 687 * 688 * @discussion 689 * If a kext is already in the kernel but not loaded, it is loaded immediately. 690 * If it isn't found, an asynchronous load request is 691 * made to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code> 692 * and <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> is returned. 693 * There is no general notification or callback mechanism for load requests. 694 */ 695 OSReturn OSKextLoadKextWithIdentifier(const char * kextIdentifier); 696 697 698 /*! 699 * @function OSKextRetainKextWithLoadTag 700 * 701 * @abstract 702 * Retain a loaded kext based on its load tag, 703 * and enable autounload for that kext. 704 * 705 * @param loadTag The load tag of the kext to be retained. 706 * See <code>@link OSKextGetCurrentLoadTag@/link</code>. 707 * 708 * @result 709 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 710 * if the kext was retained. 711 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound kOSKextReturnNotFound@/link</code> 712 * if the kext was not found. 713 * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument 714 * kOSKextReturnInvalidArgument@/link</code> 715 * if <code>loadTag</code> is 716 * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>. 717 * 718 * @discussion 719 * Retaining a kext prevents it from being unloaded, 720 * either explicitly or automatically, and enables autounload for the kext. 721 * When autounload is enabled, then shortly after the kext's last reference 722 * is dropped, it will be unloaded if there are no outstanding references to it 723 * and there are no instances of its Libkern C++ subclasses (if any). 724 * 725 * Kexts that define subclasses of 726 * <code>@link //apple_ref/doc/class/IOService IOService@/link</code> 727 * have autounload enabled automatically. 728 * Other kexts can use the reference count to manage automatic unload 729 * without having to define and create Libkern C++ objects. 730 * For example, a filesystem kext can retain itself whenever a new mount 731 * is created, and release itself when a mount is removed. 732 * When the last mount is removed, the kext will be unloaded after a brief delay. 733 * 734 * A kext can get its own load tag using the 735 * <code>@link OSKextGetCurrentLoadTag@/link</code>. 736 * 737 * Kexts should not retain and release other kexts; linkage references 738 * are accounted for internally. 739 */ 740 OSReturn OSKextRetainKextWithLoadTag(OSKextLoadTag loadTag); 741 742 743 /*! 744 * @function OSKextReleaseKextWithLoadTag 745 * 746 * @abstract 747 * Release a loaded kext based on its load tag. 748 * 749 * @param loadTag The load tag of the kext to be released. 750 * See <code>@link OSKextGetCurrentLoadTag@/link</code>. 751 * 752 * @result 753 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 754 * if the kext was released. 755 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound 756 * kOSKextReturnNotFound@/link</code> 757 * if the kext was not found. 758 * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument 759 * kOSKextReturnInvalidArgument@/link</code> 760 * if <code>loadTag</code> is 761 * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>. 762 * 763 * @discussion 764 * The kext should have been retained previously via 765 * <code>@link OSKextRetainKextWithLoadTag@/link</code>. 766 * 767 * This function schedules an autounload scan for all kexts. 768 * When that scan occurs, if a kext has autounload enabled, 769 * it will be unloaded if there are no outstanding references to it 770 * and there are no instances of its Libkern C++ classes (if any). 771 * 772 * Kexts that define subclasses of 773 * <code>@link //apple_ref/doc/class/IOService IOService@/link</code> 774 * have autounload enabled automatically. 775 * Other kexts can use the reference count to manage automatic unload 776 * without having to define and create Libkern C++ objects. 777 * For example, a filesystem kext can be retained whenever a new mount 778 * is created, and released when a mount is removed. 779 * When the last mount is removed, the kext will be unloaded after a brief delay. 780 * 781 * While the autounload scan takes place after a delay of at least a minute, 782 * a kext that manages its own reference counts for autounload should 783 * be prepared to have its module stop function called even while the function 784 * calling this function is still running. 785 * 786 * A kext can get its own load tag using the 787 * <code>@link OSKextGetCurrentLoadTag@/link</code>. 788 * 789 * Kexts should not retain and release other kexts; linkage references 790 * are accounted for internally. 791 */ 792 OSReturn OSKextReleaseKextWithLoadTag(OSKextLoadTag loadTag); 793 794 #if PRAGMA_MARK 795 /********************************************************************/ 796 #pragma mark - 797 #pragma mark Kext Requests 798 /********************************************************************/ 799 #endif 800 /*! 801 * @group Kext Requests to User Space 802 * Functions for making requests to kextd in user space. 803 */ 804 805 /*! 806 * @typedef OSKextRequestTag 807 * 808 * @abstract 809 * Identifies a kext request made to user space. 810 */ 811 typedef uint32_t OSKextRequestTag; 812 813 /*! 814 * @define kOSKextRequestTagInvalid 815 * 816 * @abstract 817 * A request tag value that will never be used for a kext request; 818 * indicates failure to create/queue the request. 819 */ 820 #define kOSKextRequestTagInvalid ((OSKextRequestTag)-1) 821 822 /*! 823 * @typedef OSKextRequestResourceCallback 824 * 825 * @abstract 826 * Invoked to provide results for a kext resource request. 827 * 828 * @param requestTag The tag of the request that the callback pertains to. 829 * @param result The result of the request: 830 * <code>@link kOSReturnSuccess 831 * kOSReturnSuccess@/link</code> 832 * if the request was fulfilled; 833 * <code>@link kOSKextReturnTimeout 834 * kOSKextReturnTimeout@/link</code> 835 * if the request has timed out; 836 * <code>@link kOSKextReturnStopping 837 * kOSKextReturnStopping@/link</code> 838 * if the kext containing the callback 839 * address for the kext is being unloaded; 840 * or other values on error. 841 * @param resourceData A pointer to the requested resource data. 842 * Owned by the system; the kext should make a copy 843 * if it needs to keep the data past the callback. 844 * @param resourceDataLength The length of <code>resourceData</code>. 845 * @param context The context pointer originally passed to 846 * <code>@link OSKextRequestResource 847 * OSKextRequestResource@/link</code>. 848 */ 849 typedef void (* OSKextRequestResourceCallback)( 850 OSKextRequestTag requestTag, 851 OSReturn result, 852 const void * resourceData, 853 uint32_t resourceDataLength, 854 void * context); 855 856 /*! 857 * @function OSKextRequestResource 858 * 859 * @abstract 860 * Requests data from a nonlocalized resource file in a kext bundle on disk. 861 * 862 * @param kextIdentifier The CFBundleIdentifier of the kext 863 * from which to read the file. 864 * @param resourceName The name of the resource file to read. 865 * @param callback A pointer to a callback function; the address 866 * must be within a currently-loaded kext. 867 * @param context A pointer to arbitrary run-time data 868 * that will be passed to the callback 869 * when it is invoked. May be <code>NULL</code>. 870 * @param requestTagOut If non-<code>NULL</code>, 871 * filled on success with a tag identifying the 872 * pending request 873 * (or on failure with <code>@link kOSKextRequestTagInvalid 874 * kOSKextRequestTagInvalid@/link</code>; 875 * can be used with 876 * <code>@link OSKextCancelRequest 877 * OSKextCancelRequest@/link</code>. 878 * 879 * @result 880 * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code> 881 * if the request is successfully queued. 882 * <code>@link kOSKextReturnInvalidArgument kOSKextReturnInvalidArgument@/link</code> 883 * if <code>kextIdentifier</code> or <code>resourceName</code> or if 884 * <code>callback</code> is not an address within a loaded kext executable. 885 * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code> 886 * if an unload attempt is being made 887 * on the kext containing <code>callback</code>. 888 * Other <code>OSKextReturn...</code> errors are possible. 889 * 890 * @discussion 891 * This function queues an asynchronous request to the user-space kext daemon 892 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>; 893 * requests for resources early in system startup 894 * will not be fulfilled until that daemon starts. 895 * Requests made by a kext while that kext is loading 896 * (specifically in the kext's module start routine) 897 * will not be fulfilled until after the start routine returns and 898 * the kext is completely loaded. 899 * Kexts requesting resources should be sure to perform appropriate locking 900 * in the callback function. 901 * 902 * Kext resources are stored in the kext's on-disk bundle under the 903 * Resources subdirectory. 904 * See {@linkdoc //apple_ref/doc/uid/10000123i Bundle Programming Guide} 905 * for an overview of bundle structure. 906 * The localization context of the kext daemon 907 * (namely that of the superuser) 908 * will be used in retrieving resources; 909 * kext resources intended for use in the kernel 910 * should generally not be localized. 911 * 912 * <code>callback</code> is guaranteed to be invoked except when: 913 * <ul> 914 * <li>@link OSKextCancelRequest <code>OSKextCancelRequest</code>@/link 915 * is used to cancel the request. 916 * In this case the kext gets the <code>context</code> pointer 917 * and can clean it up.</li> 918 * <li>The request is made during a kext's module start routine 919 * and the start routine returns an error. 920 * In this case, callbacks cannot be safely invoked, so 921 * the kext should clean up all request contexts 922 * when returning the error from the start routine.</li> 923 * </ul> 924 * 925 * Kexts with pending requests are not subject to autounload, 926 * but requests are subject to timeout after a few minutes. 927 * If that amount of time passes with no response from user space, 928 * <code>callback</code> is invoked with a result of. 929 * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code>. 930 * 931 * Kexts that are explicitly unloaded have all pending request callbacks 932 * invoked with a result of 933 * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code>. 934 * The kext must handle these callbacks, 935 * even if its stop routine will prevent unloading. 936 * If the kext does prevent unloading, it can reissue resource requests 937 * outside of the stop function. 938 */ 939 OSReturn OSKextRequestResource( 940 const char * kextIdentifier, 941 const char * resourceName, 942 OSKextRequestResourceCallback callback, 943 void * context, 944 OSKextRequestTag * requestTagOut); 945 946 /*! 947 * @function OSKextCancelRequest 948 * 949 * @abstract 950 * Cancels a pending user-space kext request without invoking the callback. 951 * 952 * @param requestTag A tag identifying a pending request. 953 * @param contextOut If non-<code>NULL</code>, filled with the context pointer 954 * originally passed with the request. 955 * 956 * @result 957 * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code> 958 * if the request is successfully canceled. 959 * <code>@link kOSKextReturnNotFound kOSKextReturnNotFound@/link</code> 960 * if <code>requestTag</code> does not identify any pending request. 961 * Other <code>OSKextReturn...</code> errors are possible. 962 * 963 * @discussion 964 * This function cancels a pending request if it exists, 965 * so that its callback will not be invoked. 966 * It returns in <code>contextOut</code> 967 * the context pointer used to create the request 968 * so that any resources allocated for the request can be cleaned up. 969 * 970 * Kexts do not need to cancel outstanding requests 971 * in their module stop functions; 972 * when a kext is unloaded, all pending request callbacks 973 * are invoked with a result of 974 * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code> 975 * before the stop function is called. 976 */ 977 OSReturn OSKextCancelRequest( 978 OSKextRequestTag requestTag, 979 void ** contextOut); 980 981 982 /*! 983 * @function OSKextGrabPgoData 984 * 985 * @abstract 986 * Grab a LLVM profile data buffer from a loaded kext. 987 * 988 * @param uuid the uuid identifying the kext to retrieve data from 989 * @param pSize pointer of where to store the size of the buffer. May be NULL. 990 * @param pBuffer pointer to the output buffer. May be NULL. 991 * @param bufferSize size of the buffer pointed to by pBuffer 992 * @param wait_for_unload (boolean) sleep until the kext is unloaded 993 * @param metadata (boolean) include metadata footer 994 * 995 * @result 996 * 0 on success 997 * ENOTSUP if the kext does not have profile data to retrieve. 998 * ENOTSUP if no kext with the given UUID is found 999 * ERRORS if the provided buffer is too small 1000 * EIO internal error, such as if __llvm_profile_write_buffer_internal fails 1001 */ 1002 int 1003 OSKextGrabPgoData(uuid_t uuid, 1004 uint64_t *pSize, 1005 char *pBuffer, 1006 uint64_t bufferSize, 1007 int wait_for_unload, 1008 int metadata); 1009 1010 /*! 1011 * @function OSKextResetPgoCountersLock 1012 * 1013 * @abstract 1014 * Call this function before trapping into the debugger to call OSKextResetPgoCounters. 1015 */ 1016 void 1017 OSKextResetPgoCountersLock(void); 1018 1019 /*! 1020 * @function OSKextResetPgoCountersUnlock 1021 * 1022 * @abstract 1023 * Call this function after trapping into the debugger to call OSKextResetPgoCounters. 1024 */ 1025 void 1026 OSKextResetPgoCountersUnlock(void); 1027 1028 /*! 1029 * @function OSKextResetPgoCounters 1030 * 1031 * @abstract Reset the PGO counters for all kexts. Call only from debugger 1032 * context, while holding OSKextResetPgoCountersLock(). 1033 */ 1034 void 1035 OSKextResetPgoCounters(void); 1036 1037 1038 #if PRAGMA_MARK 1039 #pragma mark - 1040 /********************************************************************/ 1041 #pragma mark Weak linking 1042 /********************************************************************/ 1043 #endif 1044 /*! 1045 * @group Weak Linking 1046 * Support for weak references to symbols in kexts. 1047 */ 1048 1049 /*! 1050 * @var gOSKextUnresolved 1051 * 1052 * @abstract 1053 * The value to which a kext's unresolved, weakly-referenced symbols are bound. 1054 * 1055 * @discussion 1056 * A kext must test a weak symbol before using it. A weak symbol 1057 * is only safe to use if it is not equal to <code>gOSKextUnresolved</code>. 1058 * 1059 * Example for a weak symbol named <code>foo</code>: 1060 * <pre> 1061 * @textblock 1062 * if (&foo != gOSKextUnresolved) { 1063 * foo(); 1064 * } else { 1065 * printf("foo() is not supported\n"); 1066 * } 1067 * @/textblock 1068 * </pre> 1069 */ 1070 extern const void * const gOSKextUnresolved; 1071 1072 /*! 1073 * @define OSKextSymbolIsResolved 1074 * 1075 * @abstract 1076 * Checks whether a weakly-referenced symbol has been resolved. 1077 * 1078 * @param weak_sym The weak symbol to be tested for resolution. 1079 * 1080 * @result 1081 * <code>TRUE</code> if weak_sym is resolved, or <code>FALSE</code> 1082 * if weak_sym is unresolved. 1083 * 1084 * @discussion 1085 * This is a convenience macro for testing if weak symbols are resolved. 1086 * 1087 * Example for a weak symbol named <code>foo</code>: 1088 * <pre> 1089 * @textblock 1090 * if (OSKextSymbolIsResolved(foo)) { 1091 * foo(); 1092 * } else { 1093 * printf("foo() is not resolved\n"); 1094 * } 1095 * @/textblock 1096 * </pre> 1097 */ 1098 #define OSKextSymbolIsResolved(weak_sym) \ 1099 (&(weak_sym) != gOSKextUnresolved) 1100 1101 1102 #if CONFIG_KEC_FIPS 1103 1104 #if PRAGMA_MARK 1105 #pragma mark - 1106 /********************************************************************/ 1107 #pragma mark Kernel External Components for FIPS compliance 1108 /********************************************************************/ 1109 #endif 1110 1111 // Kernel External Components for FIPS compliance (KEC_FIPS) 1112 // WARNING - ath_hash is owned by the kernel, do not free 1113 typedef struct AppleTEXTHash { 1114 int ath_version;// version of this structure (value is 1 or 2) 1115 int ath_length; // length of hash data 1116 void * ath_hash; // hash extracted from AppleTextHashes dict 1117 } AppleTEXTHash_t; 1118 #endif // CONFIG_KEC_FIPS 1119 1120 #endif /* KERNEL */ 1121 1122 __END_DECLS 1123 1124 #endif /* _LIBKERN_OSKEXTLIB_H */ 1125