libkern/libkern/OSKextLib.h

   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
 502 typedef 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  */
 534 OSKextLoadTag 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  */
 545 const 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  */
 556 const 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  */
 594 OSReturn 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  */
 639 OSReturn 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  */
 691 OSReturn 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  */
 710 typedef 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  */
 748 typedef 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  */
 838 OSReturn 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  */
 876 OSReturn 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  */
 913 extern 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
 956 typedef 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 */