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 |
509 | typedef 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 | */ |
541 | OSKextLoadTag 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 | */ |
552 | const 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 | */ |
563 | const 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 | */ |
601 | OSReturn 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 | */ |
646 | OSReturn 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 | */ |
698 | OSReturn 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 | */ |
717 | typedef 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 | */ |
755 | typedef 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 | */ |
845 | OSReturn 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 | */ |
883 | OSReturn 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 | */ |
908 | int |
909 | OSKextGrabPgoData(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 | */ |
922 | void |
923 | OSKextResetPgoCountersLock(void); |
924 | |
925 | /*! |
926 | * @function OSKextResetPgoCountersUnlock |
927 | * |
928 | * @abstract |
929 | * Call this function after trapping into the debugger to call OSKextResetPgoCounters. |
930 | */ |
931 | void |
932 | OSKextResetPgoCountersUnlock(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 | */ |
940 | void |
941 | OSKextResetPgoCounters(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 | */ |
976 | extern 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 |
1019 | typedef 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 | |