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