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