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 39#ifdef KERNEL 40#include <libkern/OSTypes.h> 41#include <libkern/OSReturn.h> 42#else 43#include <CoreFoundation/CoreFoundation.h> 44#include <System/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#if PRAGMA_MARK 241#pragma mark - 242/********************************************************************/ 243#pragma mark Kext/OSBundle Property List Keys 244/********************************************************************/ 245#endif 246/*! 247 * @group Kext Property List Keys 248 * These constants cover CFBundle properties defined for kernel extensions. 249 * Because they are used in the kernel, if you want to use one with 250 * CFBundle APIs you'll need to wrap it in a <code>CFSTR()</code> macro. 251 */ 252 253#ifdef KERNEL 254/* Define C-string versions of the CFBundle keys for use in the kernel. 255 */ 256#define kCFBundleIdentifierKey "CFBundleIdentifier" 257#define kCFBundleVersionKey "CFBundleVersion" 258#define kCFBundleNameKey "CFBundleName" 259#define kCFBundleExecutableKey "CFBundleExecutable" 260#endif /* KERNEL */ 261 262/*! 263 * @define kOSBundleCompatibleVersionKey 264 * @abstract A string giving the backwards-compatible version of a library kext 265 * in extended Mac OS 'vers' format (####.##.##s{1-255} where 's' 266 * is a build stage 'd', 'a', 'b', 'f' or 'fc'). 267 */ 268#define kOSBundleCompatibleVersionKey "OSBundleCompatibleVersion" 269 270/*! 271 * @define kOSBundleEnableKextLoggingKey 272 * @abstract Set to true to have the kernel kext logging spec applied 273 * to the kext. 274 * See <code>@link //apple_ref/c/econst/OSKextLogSpec 275 * OSKextLogSpec@/link</code>. 276 */ 277#define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging" 278 279/*! 280 * @define kOSBundleIsInterfaceKey 281 * @abstract A boolean value indicating whether the kext executable 282 * contains only symbol references. 283 */ 284#define kOSBundleIsInterfaceKey "OSBundleIsInterface" 285 286/*! 287 * @define kOSBundleLibrariesKey 288 * @abstract A dictionary listing link dependencies for this kext. 289 * Keys are bundle identifiers, values are version strings. 290 */ 291#define kOSBundleLibrariesKey "OSBundleLibraries" 292 293/*! 294 * @define kOSBundleRequiredKey 295 * @abstract A string indicating in which kinds of startup this kext 296 * may need to load during early startup (before 297 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>). 298 * @discussion 299 * The value is one of: 300 * <ul> 301 * <li>@link kOSBundleRequiredRoot "OSBundleRequiredRoot"@/link</li> 302 * <li>@link kOSBundleRequiredLocalRoot "OSBundleRequiredLocalRoot"@/link</li> 303 * <li>@link kOSBundleRequiredNetworkRoot "OSBundleRequiredNetworkRoot"@/link</li> 304 * <li>@link kOSBundleRequiredSafeBoot "OSBundleRequiredSafeBoot"@/link</li> 305 * <li>@link kOSBundleRequiredConsole "OSBundleRequiredConsole"@/link</li> 306 * </ul> 307 * 308 * Use this property judiciously. 309 * Every kext that declares a value other than "OSBundleRequiredSafeBoot" 310 * increases startup time, as the booter must read it into memory, 311 * or startup kext caches must include it. 312 */ 313#define kOSBundleRequiredKey "OSBundleRequired" 314 315/*! 316 * @define kOSBundleAllowUserLoadKey 317 * @abstract A boolean value indicating whether 318 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code> 319 * will honor a non-root process's request to load a kext. 320 * @discussion 321 * See <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithURL 322 * KextManagerLoadKextWithURL@/link</code> 323 * and <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithIdentifier 324 * KextManagerLoadKextWithIdentifier@/link</code>. 325 */ 326#define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad" 327 328/*! 329 * @define kOSKernelResourceKey 330 * @abstract A boolean value indicating whether the kext represents a built-in 331 * component of the kernel. 332 */ 333#define kOSKernelResourceKey "OSKernelResource" 334 335/*! 336 * @define kIOKitPersonalitiesKey 337 * @abstract A dictionary of dictionaries used in matching for I/O Kit drivers. 338 */ 339#define kIOKitPersonalitiesKey "IOKitPersonalities" 340 341/* 342 * @define kIOPersonalityPublisherKey 343 * @abstract Used in personalities sent to the I/O Kit, 344 * contains the CFBundleIdentifier of the kext 345 * that the personality originated in. 346 */ 347#define kIOPersonalityPublisherKey "IOPersonalityPublisher" 348 349#if CONFIG_KEC_FIPS 350/* 351 * @define kAppleTextHashesKey 352 * @abstract A dictionary conataining hashes for corecrypto kext. 353 */ 354#define kAppleTextHashesKey "AppleTextHashes" 355#endif 356 357 358 359#if PRAGMA_MARK 360/********************************************************************/ 361#pragma mark Kext/OSBundle Property Deprecated Keys 362/********************************************************************/ 363#endif 364/* 365 * @define kOSBundleDebugLevelKey 366 * @abstract 367 * Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard). 368 * Value is an integer from 1-6, corresponding to the verbose levels 369 * of kext tools on those releases. 370 * On 10.6 Snow Leopard, use <code>@link OSKextEnableKextLogging 371 * OSKextEnableKextLogging@/link</code>. 372 */ 373#define kOSBundleDebugLevelKey "OSBundleDebugLevel" 374 375/*! 376 * @define kOSBundleSharedExecutableIdentifierKey 377 * @abstract Deprecated (used on some releases of Mac OS X 378 * prior to 10.6 Snow Leopard). 379 * Value is the bundle identifier of the pseudokext 380 * that contains an executable shared by this kext. 381 */ 382#define kOSBundleSharedExecutableIdentifierKey "OSBundleSharedExecutableIdentifier" 383 384 385#if PRAGMA_MARK 386/********************************************************************/ 387#pragma mark Kext/OSBundle Property List Values 388/********************************************************************/ 389#endif 390 391/*! 392 * @group Kext Property List Values 393 * These constants encompass established values 394 * for kernel extension bundle properties. 395 */ 396 397/*! 398* @define kOSKextKernelIdentifier 399* @abstract 400* This is the CFBundleIdentifier user for the kernel itself. 401*/ 402#define kOSKextKernelIdentifier "__kernel__" 403 404/*! 405* @define kOSBundleRequiredRoot 406* @abstract 407* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 408* value indicates that the kext may be needed to mount the root filesystem 409* whether starting from a local or a network volume. 410*/ 411#define kOSBundleRequiredRoot "Root" 412 413/*! 414* @define kOSBundleRequiredLocalRoot 415* @abstract 416* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 417* value indicates that the kext may be needed to mount the root filesystem 418* when starting from a local disk. 419*/ 420#define kOSBundleRequiredLocalRoot "Local-Root" 421 422/*! 423* @define kOSBundleRequiredNetworkRoot 424* @abstract 425* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 426* value indicates that the kext may be needed to mount the root filesystem 427* when starting over a network connection. 428*/ 429#define kOSBundleRequiredNetworkRoot "Network-Root" 430 431/*! 432* @define kOSBundleRequiredSafeBoot 433* @abstract 434* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 435* value indicates that the kext can be loaded during a safe startup. 436* This value does not normally cause the kext to be read by the booter 437* or included in startup kext caches. 438*/ 439#define kOSBundleRequiredSafeBoot "Safe Boot" 440 441/*! 442* @define kOSBundleRequiredConsole 443* @abstract 444* This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 445* value indicates that the kext may be needed for console access 446* (specifically in a single-user startup when 447* <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 448* does not run) 449* and should be loaded during early startup. 450*/ 451#define kOSBundleRequiredConsole "Console" 452 453 454#if PRAGMA_MARK 455#pragma mark - 456/********************************************************************/ 457#pragma mark Kext Information 458/********************************************************************/ 459#endif 460/*! 461 * @group Kext Information 462 * Types, constants, and macros providing a kext with information 463 * about itself. 464 */ 465 466#ifdef KERNEL 467/*! 468 * @typedef OSKextLoadTag 469 * 470 * @abstract 471 * A unique identifier assigned to a loaded instanace of a kext. 472 * 473 * @discussion 474 * If a kext is unloaded and later reloaded, the new instance 475 * has a different load tag. 476 * 477 * A kext can get its own load tag in the <code>kmod_info_t</code> 478 * structure passed into its module start routine, as the 479 * <code>id</code> field (cast to this type). 480 * You can use the load tag with the functions 481 * <code>@link OSKextRetainKextWithLoadTag 482 * OSKextRetainKextWithLoadTag@/link</code> and 483 * <code>@link OSKextReleaseKextWithLoadTag 484 * OSKextReleaseKextWithLoadTag@/link</code>. 485 */ 486#else 487/*! 488 * @typedef OSKextLoadTag 489 * 490 * @abstract 491 * A unique identifier assigned to a loaded instanace of a kext. 492 * 493 * @discussion 494 * If a kext is unloaded and later reloaded, the new instance 495 * has a different load tag. 496 * 497 * A kext can get its own load tag in the <code>kmod_info_t</code> 498 * structure passed into its module start routine, as the 499 * <code>id</code> field (cast to this type). 500 */ 501#endif 502typedef uint32_t OSKextLoadTag; 503 504/*! 505 * @define kOSKextInvalidLoadTag 506 * 507 * @abstract 508 * A load tag value that will never be used for a loaded kext; 509 * indicates kext not found. 510 */ 511#define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1)) 512 513#ifdef KERNEL 514 515/* Make these visible to kexts only and *not* the kernel. 516 */ 517#if !XNU_KERNEL_PRIVATE 518 519/*! 520 * @function OSKextGetCurrentLoadTag 521 * 522 * @abstract 523 * Returns the run-time load tag for the calling kext as an 524 * <code>@link OSKextLoadTag OSKextLoadTag@/link</code>. 525 * 526 * @result 527 * The run-time load tag for the calling kext as an 528 * <code>@link OSKextLoadTag@/link</code>. 529 * 530 * @discussion 531 * The load tag identifies this loaded instance of the kext to the kernel 532 * and to kernel functions that operate on kexts. 533 */ 534OSKextLoadTag OSKextGetCurrentLoadTag(void); 535 536/*! 537 * @function OSKextGetCurrentIdentifier 538 * 539 * @abstract 540 * Returns the CFBundleIdentifier for the calling kext as a C string. 541 * 542 * @result 543 * The CFBundleIdentifier for the calling kext as a C string. 544 */ 545const char * OSKextGetCurrentIdentifier(void); 546 547/*! 548 * @function OSKextGetCurrentVersionString 549 * 550 * @abstract 551 * Returns the CFBundleVersion for the calling kext as a C string. 552 * 553 * @result 554 * The CFBundleVersion for the calling kext as a C string. 555 */ 556const char * OSKextGetCurrentVersionString(void); 557 558#endif /* !XNU_KERNEL_PRIVATE */ 559 560#if PRAGMA_MARK 561#pragma mark - 562/********************************************************************/ 563#pragma mark Kext Loading C Functions 564/********************************************************************/ 565#endif 566/*! 567 * @group Kext Loading C Functions 568 * Functions for loading and tracking kexts in the kernel. 569 */ 570 571/*! 572 * @function OSKextLoadKextWithIdentifier 573 * 574 * @abstract 575 * Request that a kext be loaded. 576 * 577 * @param kextIdentifier The bundle identifier of the kext to be loaded. 578 * 579 * @result 580 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 581 * if the kext was loaded (or was already loaded). 582 * <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> 583 * if the kext was not found and a request 584 * was queued to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 585 * Other return values indicate a failure to load the kext. 586 * 587 * @discussion 588 * If a kext is already in the kernel but not loaded, it is loaded immediately. 589 * If it isn't found, an asynchronous load request is 590 * made to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code> 591 * and <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> is returned. 592 * There is no general notification or callback mechanism for load requests. 593 */ 594OSReturn OSKextLoadKextWithIdentifier(const char * kextIdentifier); 595 596 597/*! 598 * @function OSKextRetainKextWithLoadTag 599 * 600 * @abstract 601 * Retain a loaded kext based on its load tag, 602 * and enable autounload for that kext. 603 * 604 * @param loadTag The load tag of the kext to be retained. 605 * See <code>@link OSKextGetCurrentLoadTag@/link</code>. 606 * 607 * @result 608 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 609 * if the kext was retained. 610 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound kOSKextReturnNotFound@/link</code> 611 * if the kext was not found. 612 * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument 613 * kOSKextReturnInvalidArgument@/link</code> 614 * if <code>loadTag</code> is 615 * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>. 616 * 617 * @discussion 618 * Retaining a kext prevents it from being unloaded, 619 * either explicitly or automatically, and enables autounload for the kext. 620 * When autounload is enabled, then shortly after the kext's last reference 621 * is dropped, it will be unloaded if there are no outstanding references to it 622 * and there are no instances of its Libkern C++ subclasses (if any). 623 * 624 * Kexts that define subclasses of 625 * <code>@link //apple_ref/doc/class/IOService IOService@/link</code> 626 * have autounload enabled automatically. 627 * Other kexts can use the reference count to manage automatic unload 628 * without having to define and create Libkern C++ objects. 629 * For example, a filesystem kext can retain itself whenever a new mount 630 * is created, and release itself when a mount is removed. 631 * When the last mount is removed, the kext will be unloaded after a brief delay. 632 * 633 * A kext can get its own load tag using the 634 * <code>@link OSKextGetCurrentLoadTag@/link</code>. 635 * 636 * Kexts should not retain and release other kexts; linkage references 637 * are accounted for internally. 638 */ 639OSReturn OSKextRetainKextWithLoadTag(OSKextLoadTag loadTag); 640 641 642/*! 643 * @function OSKextReleaseKextWithLoadTag 644 * 645 * @abstract 646 * Release a loaded kext based on its load tag. 647 * 648 * @param loadTag The load tag of the kext to be released. 649 * See <code>@link OSKextGetCurrentLoadTag@/link</code>. 650 * 651 * @result 652 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> 653 * if the kext was released. 654 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound 655 * kOSKextReturnNotFound@/link</code> 656 * if the kext was not found. 657 * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument 658 * kOSKextReturnInvalidArgument@/link</code> 659 * if <code>loadTag</code> is 660 * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>. 661 * 662 * @discussion 663 * The kext should have been retained previously via 664 * <code>@link OSKextRetainKextWithLoadTag@/link</code>. 665 * 666 * This function schedules an autounload scan for all kexts. 667 * When that scan occurs, if a kext has autounload enabled, 668 * it will be unloaded if there are no outstanding references to it 669 * and there are no instances of its Libkern C++ classes (if any). 670 * 671 * Kexts that define subclasses of 672 * <code>@link //apple_ref/doc/class/IOService IOService@/link</code> 673 * have autounload enabled automatically. 674 * Other kexts can use the reference count to manage automatic unload 675 * without having to define and create Libkern C++ objects. 676 * For example, a filesystem kext can be retained whenever a new mount 677 * is created, and released when a mount is removed. 678 * When the last mount is removed, the kext will be unloaded after a brief delay. 679 * 680 * While the autounload scan takes place after a delay of at least a minute, 681 * a kext that manages its own reference counts for autounload should 682 * be prepared to have its module stop function called even while the function 683 * calling this function is still running. 684 * 685 * A kext can get its own load tag using the 686 * <code>@link OSKextGetCurrentLoadTag@/link</code>. 687 * 688 * Kexts should not retain and release other kexts; linkage references 689 * are accounted for internally. 690 */ 691OSReturn OSKextReleaseKextWithLoadTag(OSKextLoadTag loadTag); 692 693#if PRAGMA_MARK 694/********************************************************************/ 695#pragma mark - 696#pragma mark Kext Requests 697/********************************************************************/ 698#endif 699/*! 700 * @group Kext Requests to User Space 701 * Functions for making requests to kextd in user space. 702 */ 703 704/*! 705 * @typedef OSKextRequestTag 706 * 707 * @abstract 708 * Identifies a kext request made to user space. 709 */ 710typedef uint32_t OSKextRequestTag; 711 712/*! 713 * @define kOSKextRequestTagInvalid 714 * 715 * @abstract 716 * A request tag value that will never be used for a kext request; 717 * indicates failure to create/queue the request. 718 */ 719#define kOSKextRequestTagInvalid ((OSKextRequestTag)-1) 720 721/*! 722 * @typedef OSKextRequestResourceCallback 723 * 724 * @abstract 725 * Invoked to provide results for a kext resource request. 726 * 727 * @param requestTag The tag of the request that the callback pertains to. 728 * @param result The result of the request: 729 * <code>@link kOSReturnSuccess 730 * kOSReturnSuccess@/link</code> 731 * if the request was fulfilled; 732 * <code>@link kOSKextReturnTimeout 733 * kOSKextReturnTimeout@/link</code> 734 * if the request has timed out; 735 * <code>@link kOSKextReturnStopping 736 * kOSKextReturnStopping@/link</code> 737 * if the kext containing the callback 738 * address for the kext is being unloaded; 739 * or other values on error. 740 * @param resourceData A pointer to the requested resource data. 741 * Owned by the system; the kext should make a copy 742 * if it needs to keep the data past the callback. 743 * @param resourceDataLength The length of <code>resourceData</code>. 744 * @param context The context pointer originally passed to 745 * <code>@link OSKextRequestResource 746 * OSKextRequestResource@/link</code>. 747 */ 748typedef void (* OSKextRequestResourceCallback)( 749 OSKextRequestTag requestTag, 750 OSReturn result, 751 const void * resourceData, 752 uint32_t resourceDataLength, 753 void * context); 754 755/*! 756 * @function OSKextRequestResource 757 * 758 * @abstract 759 * Requests data from a nonlocalized resource file in a kext bundle on disk. 760 * 761 * @param kextIdentifier The CFBundleIdentifier of the kext 762 * from which to read the file. 763 * @param resourceName The name of the resource file to read. 764 * @param callback A pointer to a callback function; the address 765 * must be within a currently-loaded kext. 766 * @param context A pointer to arbitrary run-time data 767 * that will be passed to the callback 768 * when it is invoked. May be <code>NULL</code>. 769 * @param requestTagOut If non-<code>NULL</code>, 770 * filled on success with a tag identifying the 771 * pending request 772 * (or on failure with <code>@link kOSKextRequestTagInvalid 773 * kOSKextRequestTagInvalid@/link</code>; 774 * can be used with 775 * <code>@link OSKextCancelRequest 776 * OSKextCancelRequest@/link</code>. 777 * 778 * @result 779 * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code> 780 * if the request is successfully queued. 781 * <code>@link kOSKextReturnInvalidArgument kOSKextReturnInvalidArgument@/link</code> 782 * if <code>kextIdentifier</code> or <code>resourceName</code> or if 783 * <code>callback</code> is not an address within a loaded kext executable. 784 * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code> 785 * if an unload attempt is being made 786 * on the kext containing <code>callback</code>. 787 * Other <code>OSKextReturn...</code> errors are possible. 788 * 789 * @discussion 790 * This function queues an asynchronous request to the user-space kext daemon 791 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>; 792 * requests for resources early in system startup 793 * will not be fulfilled until that daemon starts. 794 * Requests made by a kext while that kext is loading 795 * (specifically in the kext's module start routine) 796 * will not be fulfilled until after the start routine returns and 797 * the kext is completely loaded. 798 * Kexts requesting resources should be sure to perform appropriate locking 799 * in the callback function. 800 * 801 * Kext resources are stored in the kext's on-disk bundle under the 802 * Resources subdirectory. 803 * See {@linkdoc //apple_ref/doc/uid/10000123i Bundle Programming Guide} 804 * for an overview of bundle structure. 805 * The localization context of the kext daemon 806 * (namely that of the superuser) 807 * will be used in retrieving resources; 808 * kext resources intended for use in the kernel 809 * should generally not be localized. 810 * 811 * <code>callback</code> is guaranteed to be invoked except when: 812 * <ul> 813 * <li>@link OSKextCancelRequest <code>OSKextCancelRequest</code>@/link 814 * is used to cancel the request. 815 * In this case the kext gets the <code>context</code> pointer 816 * and can clean it up.</li> 817 * <li>The request is made during a kext's module start routine 818 * and the start routine returns an error. 819 * In this case, callbacks cannot be safely invoked, so 820 * the kext should clean up all request contexts 821 * when returning the error from the start routine.</li> 822 * </ul> 823 * 824 * Kexts with pending requests are not subject to autounload, 825 * but requests are subject to timeout after a few minutes. 826 * If that amount of time passes with no response from user space, 827 * <code>callback</code> is invoked with a result of. 828 * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code>. 829 * 830 * Kexts that are explicitly unloaded have all pending request callbacks 831 * invoked with a result of 832 * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code>. 833 * The kext must handle these callbacks, 834 * even if its stop routine will prevent unloading. 835 * If the kext does prevent unloading, it can reissue resource requests 836 * outside of the stop function. 837 */ 838OSReturn OSKextRequestResource( 839 const char * kextIdentifier, 840 const char * resourceName, 841 OSKextRequestResourceCallback callback, 842 void * context, 843 OSKextRequestTag * requestTagOut); 844 845/*! 846 * @function OSKextCancelRequest 847 * 848 * @abstract 849 * Cancels a pending user-space kext request without invoking the callback. 850 * 851 * @param requestTag A tag identifying a pending request. 852 * @param contextOut If non-<code>NULL</code>, filled with the context pointer 853 * originally passed with the request. 854 * 855 * @result 856 * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code> 857 * if the request is successfully canceled. 858 * <code>@link kOSKextReturnNotFound kOSKextReturnNotFound@/link</code> 859 * if <code>requestTag</code> does not identify any pending request. 860 * Other <code>OSKextReturn...</code> errors are possible. 861 * 862 * @discussion 863 * This function cancels a pending request if it exists, 864 * so that its callback will not be invoked. 865 * It returns in <code>contextOut</code> 866 * the context pointer used to create the request 867 * so that any resources allocated for the request can be cleaned up. 868 * 869 * Kexts do not need to cancel outstanding requests 870 * in their module stop functions; 871 * when a kext is unloaded, all pending request callbacks 872 * are invoked with a result of 873 * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code> 874 * before the stop function is called. 875 */ 876OSReturn OSKextCancelRequest( 877 OSKextRequestTag requestTag, 878 void ** contextOut); 879 880 881#if PRAGMA_MARK 882#pragma mark - 883/********************************************************************/ 884#pragma mark Weak linking 885/********************************************************************/ 886#endif 887/*! 888 * @group Weak Linking 889 * Support for weak references to symbols in kexts. 890 */ 891 892/*! 893 * @var gOSKextUnresolved 894 * 895 * @abstract 896 * The value to which a kext's unresolved, weakly-referenced symbols are bound. 897 * 898 * @discussion 899 * A kext must test a weak symbol before using it. A weak symbol 900 * is only safe to use if it is not equal to <code>gOSKextUnresolved</code>. 901 * 902 * Example for a weak symbol named <code>foo</code>: 903 * <pre> 904 * @textblock 905 * if (&foo != gOSKextUnresolved) { 906 * foo(); 907 * } else { 908 * printf("foo() is not supported\n"); 909 * } 910 * @/textblock 911 * </pre> 912 */ 913extern const void * gOSKextUnresolved; 914 915/*! 916 * @define OSKextSymbolIsResolved 917 * 918 * @abstract 919 * Checks whether a weakly-referenced symbol has been resolved. 920 * 921 * @param weak_sym The weak symbol to be tested for resolution. 922 * 923 * @result 924 * <code>TRUE</code> if weak_sym is resolved, or <code>FALSE</code> 925 * if weak_sym is unresolved. 926 * 927 * @discussion 928 * This is a convenience macro for testing if weak symbols are resolved. 929 * 930 * Example for a weak symbol named <code>foo</code>: 931 * <pre> 932 * @textblock 933 * if (OSKextSymbolIsResolved(foo)) { 934 * foo(); 935 * } else { 936 * printf("foo() is not resolved\n"); 937 * } 938 * @/textblock 939 * </pre> 940 */ 941#define OSKextSymbolIsResolved(weak_sym) \ 942 (&(weak_sym) != gOSKextUnresolved) 943 944 945#if CONFIG_KEC_FIPS 946 947#if PRAGMA_MARK 948#pragma mark - 949/********************************************************************/ 950#pragma mark Kernel External Components for FIPS compliance 951/********************************************************************/ 952#endif 953 954// Kernel External Components for FIPS compliance (KEC_FIPS) 955// WARNING - ath_hash is owned by the kernel, do not free 956typedef struct AppleTEXTHash { 957 const int ath_version; // version of this structure (value is 1) 958 int ath_length; // length of hash data 959 void * ath_hash; // hash extracted from AppleTextHashes dict 960} AppleTEXTHash_t; 961#endif // CONFIG_KEC_FIPS 962 963#endif /* KERNEL */ 964 965__END_DECLS 966 967#endif /* _LIBKERN_OSKEXTLIB_H */ 968