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