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