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 */
558typedef 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 */