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 #include <CoreFoundation/CoreFoundation.h> 40 #include <System/libkern/OSReturn.h> 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 #if PRAGMA_MARK 230 #pragma mark - 231 /********************************************************************/ 232 #pragma mark Kext/OSBundle Property List Keys 233 /********************************************************************/ 234 #endif 235 /*! 236 * @group Kext Property List Keys 237 * These constants cover CFBundle properties defined for kernel extensions. 238 * Because they are used in the kernel, if you want to use one with 239 * CFBundle APIs you'll need to wrap it in a <code>CFSTR()</code> macro. 240 */ 241 242 243 /*! 244 * @define kOSBundleCompatibleVersionKey 245 * @abstract A string giving the backwards-compatible version of a library kext 246 * in extended Mac OS 'vers' format (####.##.##s{1-255} where 's' 247 * is a build stage 'd', 'a', 'b', 'f' or 'fc'). 248 */ 249 #define kOSBundleCompatibleVersionKey "OSBundleCompatibleVersion" 250 251 /*! 252 * @define kOSBundleEnableKextLoggingKey 253 * @abstract Set to true to have the kernel kext logging spec applied 254 * to the kext. 255 * See <code>@link //apple_ref/c/econst/OSKextLogSpec 256 * OSKextLogSpec@/link</code>. 257 */ 258 #define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging" 259 260 /*! 261 * @define kOSBundleIsInterfaceKey 262 * @abstract A boolean value indicating whether the kext executable 263 * contains only symbol references. 264 */ 265 #define kOSBundleIsInterfaceKey "OSBundleIsInterface" 266 267 /*! 268 * @define kOSBundleLibrariesKey 269 * @abstract A dictionary listing link dependencies for this kext. 270 * Keys are bundle identifiers, values are version strings. 271 */ 272 #define kOSBundleLibrariesKey "OSBundleLibraries" 273 274 /*! 275 * @define kOSBundleRequiredKey 276 * @abstract A string indicating in which kinds of startup this kext 277 * may need to load during early startup (before 278 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>). 279 * @discussion 280 * The value is one of: 281 * <ul> 282 * <li>@link kOSBundleRequiredRoot "OSBundleRequiredRoot"@/link</li> 283 * <li>@link kOSBundleRequiredLocalRoot "OSBundleRequiredLocalRoot"@/link</li> 284 * <li>@link kOSBundleRequiredNetworkRoot "OSBundleRequiredNetworkRoot"@/link</li> 285 * <li>@link kOSBundleRequiredSafeBoot "OSBundleRequiredSafeBoot"@/link</li> 286 * <li>@link kOSBundleRequiredConsole "OSBundleRequiredConsole"@/link</li> 287 * </ul> 288 * 289 * Use this property judiciously. 290 * Every kext that declares a value other than "OSBundleRequiredSafeBoot" 291 * increases startup time, as the booter must read it into memory, 292 * or startup kext caches must include it. 293 */ 294 #define kOSBundleRequiredKey "OSBundleRequired" 295 296 /*! 297 * @define kOSBundleAllowUserLoadKey 298 * @abstract A boolean value indicating whether 299 * <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code> 300 * will honor a non-root process's request to load a kext. 301 * @discussion 302 * See <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithURL 303 * KextManagerLoadKextWithURL@/link</code> 304 * and <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithIdentifier 305 * KextManagerLoadKextWithIdentifier@/link</code>. 306 */ 307 #define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad" 308 309 /*! 310 * @define kOSKernelResourceKey 311 * @abstract A boolean value indicating whether the kext represents a built-in 312 * component of the kernel. 313 */ 314 #define kOSKernelResourceKey "OSKernelResource" 315 316 /*! 317 * @define kIOKitPersonalitiesKey 318 * @abstract A dictionary of dictionaries used in matching for I/O Kit drivers. 319 */ 320 #define kIOKitPersonalitiesKey "IOKitPersonalities" 321 322 /* 323 * @define kIOPersonalityPublisherKey 324 * @abstract Used in personalities sent to the I/O Kit, 325 * contains the CFBundleIdentifier of the kext 326 * that the personality originated in. 327 */ 328 #define kIOPersonalityPublisherKey "IOPersonalityPublisher" 329 330 #if CONFIG_KEC_FIPS 331 /* 332 * @define kAppleTextHashesKey 333 * @abstract A dictionary conataining hashes for corecrypto kext. 334 */ 335 #define kAppleTextHashesKey "AppleTextHashes" 336 #endif 337 338 339 340 #if PRAGMA_MARK 341 /********************************************************************/ 342 #pragma mark Kext/OSBundle Property Deprecated Keys 343 /********************************************************************/ 344 #endif 345 /* 346 * @define kOSBundleDebugLevelKey 347 * @abstract 348 * Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard). 349 * Value is an integer from 1-6, corresponding to the verbose levels 350 * of kext tools on those releases. 351 * On 10.6 Snow Leopard, use <code>@link OSKextEnableKextLogging 352 * OSKextEnableKextLogging@/link</code>. 353 */ 354 #define kOSBundleDebugLevelKey "OSBundleDebugLevel" 355 356 /*! 357 * @define kOSBundleSharedExecutableIdentifierKey 358 * @abstract Deprecated (used on some releases of Mac OS X 359 * prior to 10.6 Snow Leopard). 360 * Value is the bundle identifier of the pseudokext 361 * that contains an executable shared by this kext. 362 */ 363 #define kOSBundleSharedExecutableIdentifierKey "OSBundleSharedExecutableIdentifier" 364 365 366 #if PRAGMA_MARK 367 /********************************************************************/ 368 #pragma mark Kext/OSBundle Property List Values 369 /********************************************************************/ 370 #endif 371 372 /*! 373 * @group Kext Property List Values 374 * These constants encompass established values 375 * for kernel extension bundle properties. 376 */ 377 378 /*! 379 * @define kOSKextKernelIdentifier 380 * @abstract 381 * This is the CFBundleIdentifier user for the kernel itself. 382 */ 383 #define kOSKextKernelIdentifier "__kernel__" 384 385 /*! 386 * @define kOSBundleRequiredRoot 387 * @abstract 388 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 389 * value indicates that the kext may be needed to mount the root filesystem 390 * whether starting from a local or a network volume. 391 */ 392 #define kOSBundleRequiredRoot "Root" 393 394 /*! 395 * @define kOSBundleRequiredLocalRoot 396 * @abstract 397 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 398 * value indicates that the kext may be needed to mount the root filesystem 399 * when starting from a local disk. 400 */ 401 #define kOSBundleRequiredLocalRoot "Local-Root" 402 403 /*! 404 * @define kOSBundleRequiredNetworkRoot 405 * @abstract 406 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 407 * value indicates that the kext may be needed to mount the root filesystem 408 * when starting over a network connection. 409 */ 410 #define kOSBundleRequiredNetworkRoot "Network-Root" 411 412 /*! 413 * @define kOSBundleRequiredSafeBoot 414 * @abstract 415 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 416 * value indicates that the kext can be loaded during a safe startup. 417 * This value does not normally cause the kext to be read by the booter 418 * or included in startup kext caches. 419 */ 420 #define kOSBundleRequiredSafeBoot "Safe Boot" 421 422 /*! 423 * @define kOSBundleRequiredConsole 424 * @abstract 425 * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code> 426 * value indicates that the kext may be needed for console access 427 * (specifically in a single-user startup when 428 * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>. 429 * does not run) 430 * and should be loaded during early startup. 431 */ 432 #define kOSBundleRequiredConsole "Console" 433 434 435 #if PRAGMA_MARK 436 #pragma mark - 437 /********************************************************************/ 438 #pragma mark Kext Information 439 /********************************************************************/ 440 #endif 441 /*! 442 * @group Kext Information 443 * Types, constants, and macros providing a kext with information 444 * about itself. 445 */ 446 447 /*! 448 * @typedef OSKextLoadTag 449 * 450 * @abstract 451 * A unique identifier assigned to a loaded instanace of a kext. 452 * 453 * @discussion 454 * If a kext is unloaded and later reloaded, the new instance 455 * has a different load tag. 456 * 457 * A kext can get its own load tag in the <code>kmod_info_t</code> 458 * structure passed into its module start routine, as the 459 * <code>id</code> field (cast to this type). 460 */ 461 typedef uint32_t OSKextLoadTag; 462 463 /*! 464 * @define kOSKextInvalidLoadTag 465 * 466 * @abstract 467 * A load tag value that will never be used for a loaded kext; 468 * indicates kext not found. 469 */ 470 #define kOSKextInvalidLoadTag ((OSKextLoadTag)(-1)) 471 472 473 __END_DECLS 474 475 #endif /* _LIBKERN_OSKEXTLIB_H */ 476