OSKextLib.h (19327B) - Raw
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 #include <stdint.h> 34 #include <mach/kmod.h> 35 #include <mach/vm_types.h> 36 #include <uuid/uuid.h> 37 38 #include <libkern/OSReturn.h> 39 40 __BEGIN_DECLS 41 42 /*! 43 * @header 44 * 45 * Declares functions, basic return values, and other constants 46 * related to kernel extensions (kexts). 47 */ 48 49 #if PRAGMA_MARK 50 #pragma mark - 51 /********************************************************************/ 52 #pragma mark OSReturn Values for Kernel Extensions 53 /********************************************************************/ 54 #endif 55 /*! 56 * @group OSReturn Values for Kernel Extensions 57 * Many kext-related functions return these values, 58 * as well as those defined under 59 * <code>@link //apple_ref/c/tdef/OSReturn OSReturn@/link</code> 60 * and other variants of <code>kern_return_t</code>. 61 */ 62 63 64 #define sub_libkern_kext err_sub(2) 65 #define libkern_kext_err(code) (sys_libkern|sub_libkern_kext|(code)) 66 67 68 /*! 69 * @define kOSKextReturnInternalError 70 * @abstract An internal error in the kext library. 71 * Contrast with <code>@link //apple_ref/c/econst/OSReturnError 72 * OSReturnError@/link</code>. 73 */ 74 #define kOSKextReturnInternalError libkern_kext_err(0x1) 75 76 /*! 77 * @define kOSKextReturnNoMemory 78 * @abstract Memory allocation failed. 79 */ 80 #define kOSKextReturnNoMemory libkern_kext_err(0x2) 81 82 /*! 83 * @define kOSKextReturnNoResources 84 * @abstract Some resource other than memory (such as available load tags) 85 * is exhausted. 86 */ 87 #define kOSKextReturnNoResources libkern_kext_err(0x3) 88 89 /*! 90 * @define kOSKextReturnNotPrivileged 91 * @abstract The caller lacks privileges to perform the requested operation. 92 */ 93 #define kOSKextReturnNotPrivileged libkern_kext_err(0x4) 94 95 /*! 96 * @define kOSKextReturnInvalidArgument 97 * @abstract Invalid argument. 98 */ 99 #define kOSKextReturnInvalidArgument libkern_kext_err(0x5) 100 101 /*! 102 * @define kOSKextReturnNotFound 103 * @abstract Search item not found. 104 */ 105 #define kOSKextReturnNotFound libkern_kext_err(0x6) 106 107 /*! 108 * @define kOSKextReturnBadData 109 * @abstract Malformed data (not used for XML). 110 */ 111 #define kOSKextReturnBadData libkern_kext_err(0x7) 112 113 /*! 114 * @define kOSKextReturnSerialization 115 * @abstract Error converting or (un)serializing URL, string, or XML. 116 */ 117 #define kOSKextReturnSerialization libkern_kext_err(0x8) 118 119 /*! 120 * @define kOSKextReturnUnsupported 121 * @abstract Operation is no longer or not yet supported. 122 */ 123 #define kOSKextReturnUnsupported libkern_kext_err(0x9) 124 125 /*! 126 * @define kOSKextReturnDisabled 127 * @abstract Operation is currently disabled. 128 */ 129 #define kOSKextReturnDisabled libkern_kext_err(0xa) 130 131 /*! 132 * @define kOSKextReturnNotAKext 133 * @abstract Bundle is not a kernel extension. 134 */ 135 #define kOSKextReturnNotAKext libkern_kext_err(0xb) 136 137 /*! 138 * @define kOSKextReturnValidation 139 * @abstract Validation failures encountered; check diagnostics for details. 140 */ 141 #define kOSKextReturnValidation libkern_kext_err(0xc) 142 143 /*! 144 * @define kOSKextReturnAuthentication 145 * @abstract Authetication failures encountered; check diagnostics for details. 146 */ 147 #define kOSKextReturnAuthentication libkern_kext_err(0xd) 148 149 /*! 150 * @define kOSKextReturnDependencies 151 * @abstract Dependency resolution failures encountered; check diagnostics for details. 152 */ 153 #define kOSKextReturnDependencies libkern_kext_err(0xe) 154 155 /*! 156 * @define kOSKextReturnArchNotFound 157 * @abstract Kext does not contain code for the requested architecture. 158 */ 159 #define kOSKextReturnArchNotFound libkern_kext_err(0xf) 160 161 /*! 162 * @define kOSKextReturnCache 163 * @abstract An error occurred processing a system kext cache. 164 */ 165 #define kOSKextReturnCache libkern_kext_err(0x10) 166 167 /*! 168 * @define kOSKextReturnDeferred 169 * @abstract Operation has been posted asynchronously to user space (kernel only). 170 */ 171 #define kOSKextReturnDeferred libkern_kext_err(0x11) 172 173 /*! 174 * @define kOSKextReturnBootLevel 175 * @abstract Kext not loadable or operation not allowed at current boot level. 176 */ 177 #define kOSKextReturnBootLevel libkern_kext_err(0x12) 178 179 /*! 180 * @define kOSKextReturnNotLoadable 181 * @abstract Kext cannot be loaded; check diagnostics for details. 182 */ 183 #define kOSKextReturnNotLoadable libkern_kext_err(0x13) 184 185 /*! 186 * @define kOSKextReturnLoadedVersionDiffers 187 * @abstract A different version (or executable UUID, or executable by checksum) 188 * of the requested kext is already loaded. 189 */ 190 #define kOSKextReturnLoadedVersionDiffers libkern_kext_err(0x14) 191 192 /*! 193 * @define kOSKextReturnDependencyLoadError 194 * @abstract A load error occurred on a dependency of the kext being loaded. 195 */ 196 #define kOSKextReturnDependencyLoadError libkern_kext_err(0x15) 197 198 /*! 199 * @define kOSKextReturnLinkError 200 * @abstract A link failure occured with this kext or a dependency. 201 */ 202 #define kOSKextReturnLinkError libkern_kext_err(0x16) 203 204 /*! 205 * @define kOSKextReturnStartStopError 206 * @abstract The kext start or stop routine returned an error. 207 */ 208 #define kOSKextReturnStartStopError libkern_kext_err(0x17) 209 210 /*! 211 * @define kOSKextReturnInUse 212 * @abstract The kext is currently in use or has outstanding references, 213 * and cannot be unloaded. 214 */ 215 #define kOSKextReturnInUse libkern_kext_err(0x18) 216 217 /*! 218 * @define kOSKextReturnTimeout 219 * @abstract A kext request has timed out. 220 */ 221 #define kOSKextReturnTimeout libkern_kext_err(0x19) 222 223 /*! 224 * @define kOSKextReturnStopping 225 * @abstract The kext is in the process of stopping; requests cannot be made. 226 */ 227 #define kOSKextReturnStopping libkern_kext_err(0x1a) 228 229 /*! 230 * @define kOSKextReturnSystemPolicy 231 * @abstract The kext was prevented from loading due to system policy. 232 */ 233 #define kOSKextReturnSystemPolicy libkern_kext_err(0x1b) 234 235 /*! 236 * @define kOSKextReturnKCLoadFailure 237 * @abstract Loading of the System KC failed 238 */ 239 #define kOSKextReturnKCLoadFailure libkern_kext_err(0x1c) 240 241 /*! 242 * @define kOSKextReturnKCLoadFailureSystemKC 243 * @abstract Loading of the System KC failed 244 * 245 * This a sub-code of kOSKextReturnKCLoadFailure. It can be OR'd together 246 * with: kOSKextReturnKCLoadFailureAuxKC 247 * 248 * If both the System and Aux KCs fail to load, then the error code will be: 249 * libkern_kext_err(0x1f) 250 */ 251 #define kOSKextReturnKCLoadFailureSystemKC libkern_kext_err(0x1d) 252 253 /*! 254 * @define kOSKextReturnKCLoadFailureAuxKC 255 * @abstract Loading of the Aux KC failed 256 * 257 * This a sub-code of kOSKextReturnKCLoadFailure. It can be OR'd together 258 * with: kOSKextReturnKCLoadFailureSystemKC 259 * 260 * If both the System and Aux KCs fail to load, then the error code will be: 261 * libkern_kext_err(0x1f) 262 */ 263 #define kOSKextReturnKCLoadFailureAuxKC libkern_kext_err(0x1e) 264 265 /* next available error is: libkern_kext_err(0x20) */ 266 267 #if PRAGMA_MARK 268 #pragma mark - 269 /********************************************************************/ 270 #pragma mark Kext/OSBundle Property List Keys 271 /********************************************************************/ 272 #endif 273 /*! 274 * @group Kext Property List Keys 275 * These constants cover CFBundle properties defined for kernel extensions. 276 * Because they are used in the kernel, if you want to use one with 277 * CFBundle APIs you'll need to wrap it in a <code>CFSTR()</code> macro. 278 */ 279 280 281 /*! 282 * @define kOSBundleCompatibleVersionKey 283 * @abstract A string giving the backwards-compatible version of a library kext 284 * in extended Mac OS 'vers' format (####.##.##s{1-255} where 's' 285 * is a build stage 'd', 'a', 'b', 'f' or 'fc'). 286 */ 287 #define kOSBundleCompatibleVersionKey "OSBundleCompatibleVersion" 288 289 /*! 290 * @define kOSBundleEnableKextLoggingKey 291 * @abstract Set to true to have the kernel kext logging spec applied 292 * to the kext. 293 * See <code>@link //apple_ref/c/econst/OSKextLogSpec 294 * OSKextLogSpec@/link</code>. 295 */ 296 #define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging" 297 298 /*! 299 * @define kOSBundleIsInterfaceKey 300 * @abstract A boolean value indicating whether the kext executable 301 * contains only symbol references. 302 */ 303 #define kOSBundleIsInterfaceKey "OSBundleIsInterface" 304 305 /*! 306 * @define kOSBundleLibrariesKey 307 * @abstract A dictionary listing link dependencies for this kext. 308 * Keys are bundle identifiers, values are version strings. 309 */ 310 #define kOSBundleLibrariesKey "OSBundleLibraries" 311 312 /*! 313 * @define kOSBundleRequiredKey 314 * @abstract A string indicating in which kinds of startup this kext 315 * may need to load during early startup (before 316 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>). 317 * @discussion 318 * The value is one of: 319 * <ul> 320 * <li>@link kOSBundleRequiredRoot "OSBundleRequiredRoot"@/link</li> 321 * <li>@link kOSBundleRequiredLocalRoot "OSBundleRequiredLocalRoot"@/link</li> 322 * <li>@link kOSBundleRequiredNetworkRoot "OSBundleRequiredNetworkRoot"@/link</li> 323 * <li>@link kOSBundleRequiredSafeBoot "OSBundleRequiredSafeBoot"@/link</li> 324 * <li>@link kOSBundleRequiredConsole "OSBundleRequiredConsole"@/link</li> 325 * </ul> 326 * 327 * Use this property judiciously. 328 * Every kext that declares a value other than "OSBundleRequiredSafeBoot" 329 * increases startup time, as the booter must read it into memory, 330 * or startup kext caches must include it. 331 */ 332 #define kOSBundleRequiredKey "OSBundleRequired" 333 334 /*! 335 * @define kOSBundleRequireExplicitLoadKey 336 * @abstract A boolean value indicating whether the kext requires an 337 * explicit kextload in order to start/match. 338 */ 339 #define kOSBundleRequireExplicitLoadKey "OSBundleRequireExplicitLoad" 340 341 /*! 342 * @define kOSBundleAllowUserLoadKey 343 * @abstract A boolean value indicating whether 344 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code> 345 * will honor a non-root process's request to load a kext. 346 * @discussion 347 * See <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithURL 348 * KextManagerLoadKextWithURL@/link</code> 349 * and <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithIdentifier 350 * KextManagerLoadKextWithIdentifier@/link</code>. 351 */ 352 #define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad" 353 354 /*! 355 * @define kOSBundleAllowUserTerminateKey 356 * @abstract A boolean value indicating whether the kextunload tool 357 * is allowed to issue IOService terminate to classes defined in this kext. 358 * @discussion A boolean value indicating whether the kextunload tool 359 * is allowed to issue IOService terminate to classes defined in this kext. 360 */ 361 #define kOSBundleAllowUserTerminateKey "OSBundleAllowUserTerminate" 362 363 /*! 364 * @define kOSKernelResourceKey 365 * @abstract A boolean value indicating whether the kext represents a built-in 366 * component of the kernel. 367 */ 368 #define kOSKernelResourceKey "OSKernelResource" 369 370 /*! 371 * @define kOSKextVariantOverrideKey 372 * @abstract A dictionary with target names as key and a target-specific variant 373 * name as value. 374 */ 375 #define kOSKextVariantOverrideKey "OSKextVariantOverride" 376 377 /*! 378 * @define kIOKitPersonalitiesKey 379 * @abstract A dictionary of dictionaries used in matching for I/O Kit drivers. 380 */ 381 #define kIOKitPersonalitiesKey "IOKitPersonalities" 382 383 /* 384 * @define kIOPersonalityPublisherKey 385 * @abstract Used in personalities sent to the I/O Kit, 386 * contains the CFBundleIdentifier of the kext 387 * that the personality originated in. 388 */ 389 #define kIOPersonalityPublisherKey "IOPersonalityPublisher" 390 391 #if CONFIG_KEC_FIPS 392 /* 393 * @define kAppleTextHashesKey 394 * @abstract A dictionary conataining hashes for corecrypto kext. 395 */ 396 #define kAppleTextHashesKey "AppleTextHashes" 397 #endif 398 399 /*! 400 * @define kOSMutableSegmentCopy 401 * @abstract A boolean value indicating whether the kext requires a copy of 402 * its mutable segments to be kept in memory, and then reset when the kext 403 * unloads. This should be used with caution as it will increase the 404 * amount of memory used by the kext. 405 */ 406 #define kOSMutableSegmentCopy "OSMutableSegmentCopy" 407 408 409 #if PRAGMA_MARK 410 /********************************************************************/ 411 #pragma mark Kext/OSBundle Property Deprecated Keys 412 /********************************************************************/ 413 #endif 414 /* 415 * @define kOSBundleDebugLevelKey 416 * @abstract 417 * Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard). 418 * Value is an integer from 1-6, corresponding to the verbose levels 419 * of kext tools on those releases. 420 * On 10.6 Snow Leopard, use <code>@link OSKextEnableKextLogging 421 * OSKextEnableKextLogging@/link</code>. 422 */ 423 #define kOSBundleDebugLevelKey "OSBundleDebugLevel" 424 425 /*! 426 * @define kOSBundleSharedExecutableIdentifierKey 427 * @abstract Deprecated (used on some releases of Mac OS X 428 * prior to 10.6 Snow Leopard). 429 * Value is the bundle identifier of the pseudokext 430 * that contains an executable shared by this kext. 431 */ 432 #define kOSBundleSharedExecutableIdentifierKey "OSBundleSharedExecutableIdentifier" 433 434 435 #if PRAGMA_MARK 436 /********************************************************************/ 437 #pragma mark Kext/OSBundle Property List Values 438 /********************************************************************/ 439 #endif 440 441 /*! 442 * @group Kext Property List Values 443 * These constants encompass established values 444 * for kernel extension bundle properties. 445 */ 446 447 /*! 448 * @define kOSKextKernelIdentifier 449 * @abstract 450 * This is the CFBundleIdentifier user for the kernel itself. 451 */ 452 #define kOSKextKernelIdentifier "__kernel__" 453 454 455 /*! 456 * @define kOSKextBundlePackageTypeKext 457 * @abstract 458 * The bundle type value for Kernel Extensions. 459 */ 460 #define kOSKextBundlePackageTypeKext "KEXT" 461 462 /*! 463 * @define kOSKextBundlePackageTypeDriverKit 464 * @abstract 465 * The bundle type value for Driver Extensions. 466 */ 467 #define kOSKextBundlePackageTypeDriverKit "DEXT" 468 469 /*! 470 * @define kOSBundleRequiredRoot 471 * @abstract 472 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 473 * value indicates that the kext may be needed to mount the root filesystem 474 * whether starting from a local or a network volume. 475 */ 476 #define kOSBundleRequiredRoot "Root" 477 478 /*! 479 * @define kOSBundleRequiredLocalRoot 480 * @abstract 481 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 482 * value indicates that the kext may be needed to mount the root filesystem 483 * when starting from a local disk. 484 */ 485 #define kOSBundleRequiredLocalRoot "Local-Root" 486 487 /*! 488 * @define kOSBundleRequiredNetworkRoot 489 * @abstract 490 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 491 * value indicates that the kext may be needed to mount the root filesystem 492 * when starting over a network connection. 493 */ 494 #define kOSBundleRequiredNetworkRoot "Network-Root" 495 496 /*! 497 * @define kOSBundleRequiredSafeBoot 498 * @abstract 499 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 500 * value indicates that the kext can be loaded during a safe startup. 501 * This value does not normally cause the kext to be read by the booter 502 * or included in startup kext caches. 503 */ 504 #define kOSBundleRequiredSafeBoot "Safe Boot" 505 506 /*! 507 * @define kOSBundleRequiredConsole 508 * @abstract 509 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 510 * value indicates that the kext may be needed for console access 511 * (specifically in a single-user startup when 512 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 513 * does not run) 514 * and should be loaded during early startup. 515 */ 516 #define kOSBundleRequiredConsole "Console" 517 518 /*! 519 * @define kOSBundleRequiredDriverKit 520 * @abstract 521 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 522 * value indicates that the driver extension's (DriverKit driver's) 523 * personalities must be present in the kernel at early boot (specifically 524 * before <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code> starts) 525 * in order to compete with kexts built into the prelinkedkernel. Note that 526 * kextd is still required to launch the user space driver binary. The IOKit 527 * matching will happen during early boot, and the actual driver launch 528 * will happen after kextd starts. 529 */ 530 #define kOSBundleRequiredDriverKit "DriverKit" 531 532 #if PRAGMA_MARK 533 #pragma mark - 534 /********************************************************************/ 535 #pragma mark Kext Information 536 /********************************************************************/ 537 #endif 538 /*! 539 * @group Kext Information 540 * Types, constants, and macros providing a kext with information 541 * about itself. 542 */ 543 544 /*! 545 * @typedef OSKextLoadTag 546 * 547 * @abstract 548 * A unique identifier assigned to a loaded instanace of a kext. 549 * 550 * @discussion 551 * If a kext is unloaded and later reloaded, the new instance 552 * has a different load tag. 553 * 554 * A kext can get its own load tag in the <code>kmod_info_t</code> 555 * structure passed into its module start routine, as the 556 * <code>id</code> field (cast to this type). 557 */ 558 typedef uint32_t OSKextLoadTag; 559 560 /*! 561 * @define kOSKextInvalidLoadTag 562 * 563 * @abstract 564 * A load tag value that will never be used for a loaded kext; 565 * indicates kext not found. 566 */ 567 #define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1)) 568 569 570 __END_DECLS 571 572 #endif /* _LIBKERN_OSKEXTLIB_H */