1 | /* |
2 | * Copyright (c) 1998-2000 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_OSKEXTLIBPRIVATE_H |
30 | #define _LIBKERN_OSKEXTLIBPRIVATE_H |
31 | |
32 | |
33 | #include <sys/cdefs.h> |
34 | #include <uuid/uuid.h> |
35 | |
36 | __BEGIN_DECLS |
37 | #ifdef KERNEL |
38 | #include <libkern/OSTypes.h> |
39 | #include <mach/kmod.h> |
40 | #include <mach/vm_types.h> |
41 | #else |
42 | #include <CoreFoundation/CoreFoundation.h> |
43 | #include <mach/kmod.h> |
44 | #endif /* KERNEL */ |
45 | __END_DECLS |
46 | |
47 | #include <libkern/OSReturn.h> |
48 | |
49 | __BEGIN_DECLS |
50 | |
51 | #if PRAGMA_MARK |
52 | #pragma mark - |
53 | /********************************************************************/ |
54 | #pragma mark Misc Constants |
55 | /********************************************************************/ |
56 | #endif |
57 | |
58 | typedef uint8_t OSKextExcludeLevel; |
59 | #define kOSKextExcludeNone (0) |
60 | #define kOSKextExcludeKext (1) |
61 | #define kOSKextExcludeAll (2) |
62 | |
63 | #if PRAGMA_MARK |
64 | #pragma mark - |
65 | /********************************************************************/ |
66 | #pragma mark Kext/OSBundle Property List Keys |
67 | /********************************************************************/ |
68 | #endif |
69 | |
70 | /*! |
71 | * @define kOSBundleHelperKey |
72 | * @abstract Used by loginwindow. |
73 | */ |
74 | #define kOSBundleHelperKey "OSBundleHelper" |
75 | |
76 | /*! |
77 | * @define kOSBundleDeveloperOnlyKey |
78 | * @abstract A boolean value indicating whether the kext should only load on |
79 | * Developer devices. |
80 | */ |
81 | #define kOSBundleDeveloperOnlyKey "OSBundleDeveloperOnly" |
82 | |
83 | /*! |
84 | * @define kOSBundleRamDiskOnlyKey |
85 | * @abstract A boolean value indicating whether the kext should only load when |
86 | * booted from a ram disk. |
87 | */ |
88 | #define kOSBundleRamDiskOnlyKey "OSBundleRamDiskOnly" |
89 | |
90 | |
91 | /*! |
92 | * @define kAppleSecurityExtensionKey |
93 | * @abstract A boolean value indicating whether the kext registers |
94 | * MACF hooks. |
95 | */ |
96 | #define kAppleSecurityExtensionKey "AppleSecurityExtension" |
97 | |
98 | /*! |
99 | * @define kAppleKernelExternalComponentKey |
100 | * @abstract A boolean value indicating whether the kext is vending kernel |
101 | * KPI, and needs special loading behavior. |
102 | */ |
103 | #define kAppleKernelExternalComponentKey "AppleKernelExternalComponent" |
104 | |
105 | // properties found in the registry root |
106 | #define kOSKernelCPUTypeKey "OSKernelCPUType" |
107 | #define kOSKernelCPUSubtypeKey "OSKernelCPUSubtype" |
108 | #define kOSStartupMkextCRC "OSStartupMkextCRC" /* value is 32-bit OSData */ |
109 | #define kOSPrelinkKextCountKey "OSPrelinkKextCount" /* value is 32-bit OSNumber */ |
110 | #define kOSPrelinkPersonalityCountKey "OSPrelinkPersonalityCount" /* value is 32-bit OSNumber */ |
111 | |
112 | #if PRAGMA_MARK |
113 | #pragma mark - |
114 | /********************************************************************/ |
115 | #pragma mark Load Info Keys |
116 | /********************************************************************/ |
117 | #endif |
118 | /********************************************************************* |
119 | * In addition to the keys defined here, you will find: |
120 | * kCFBundleIdentifierKey |
121 | * kCFBundleVersionKey |
122 | * kOSBundleCompatibleVersionKey |
123 | * kOSBundleIsInterfaceKey |
124 | * kOSKernelResourceKey |
125 | *********************************************************************/ |
126 | #define "OSBundleMachOHeaders" |
127 | #define kOSBundleLogStringsKey "OSBundleLogStrings" |
128 | #define kOSBundleCPUTypeKey "OSBundleCPUType" |
129 | #define kOSBundleCPUSubtypeKey "OSBundleCPUSubtype" |
130 | #define kOSBundlePathKey "OSBundlePath" |
131 | #define kOSBundleExecutablePathKey "OSBundleExecutablePath" |
132 | #define kOSBundleUUIDKey "OSBundleUUID" |
133 | #define kOSBundleTextUUIDKey "OSBundleTextUUID" |
134 | #define kOSBundleStartedKey "OSBundleStarted" |
135 | #define kOSBundlePrelinkedKey "OSBundlePrelinked" |
136 | #define kOSBundleLoadTagKey "OSBundleLoadTag" |
137 | #define kOSBundleLoadAddressKey "OSBundleLoadAddress" |
138 | #define kOSBundleLoadSizeKey "OSBundleLoadSize" |
139 | #define kOSBundleExecLoadAddressKey "OSBundleExecLoadAddress" |
140 | #define kOSBundleExecLoadSizeKey "OSBundleExecLoadSize" |
141 | #define kOSBundleWiredSizeKey "OSBundleWiredSize" |
142 | #define kOSBundleDependenciesKey "OSBundleDependencies" |
143 | #define kOSBundleRetainCountKey "OSBundleRetainCount" |
144 | #define kOSBundleCacheLoadAddressKey "OSBundleCacheLoadAddress" |
145 | // Kernel TEXT encompasses kexts |
146 | #define kOSBundleKextsInKernelTextKey "OSBundleKextsInKernelText" |
147 | // OSKextCopyLoadedKextInfo includes non-started kexts when present: |
148 | #define kOSBundleAllPrelinkedKey "OSBundleAllPrelinked" |
149 | |
150 | /* Dictionary of metaclass info keyed by classname. |
151 | */ |
152 | #define kOSBundleClassesKey "OSBundleClasses" |
153 | |
154 | /* These are contained in kOSBundleClassesKey. kOSMetaClassSuperclassNameKey |
155 | * may be absent (for the root class). |
156 | */ |
157 | #define kOSMetaClassNameKey "OSMetaClassName" |
158 | #define kOSMetaClassSuperclassNameKey "OSMetaClassSuperclassName" |
159 | #define kOSMetaClassTrackingCountKey "OSMetaClassTrackingCount" |
160 | |
161 | #if PRAGMA_MARK |
162 | #pragma mark - |
163 | /********************************************************************/ |
164 | #pragma mark Kext Log Specification |
165 | /********************************************************************/ |
166 | #endif |
167 | /*! |
168 | * @group Kext Log Specification |
169 | * Logging levels & flags for kernel extensions. |
170 | * See <code>@link //apple_ref/c/tdef/OSKextLogSpec OSKextLogSpec@/link</code> |
171 | * for an overview. |
172 | */ |
173 | |
174 | /*! |
175 | * @typedef OSKextLogSpec |
176 | * @abstract Describes what a log message applies to, |
177 | * or a filter that determines which log messages are displayed. |
178 | * |
179 | * @discussion |
180 | * A kext log specification is a 32-bit value used as a desription of |
181 | * what a given log message applies to, or as a filter |
182 | * indicating which log messages are desired and which are not. |
183 | * A log specification has three parts (described in detail shortly): |
184 | * <ul> |
185 | * <li>A <b>level</b> from 0-7 in the lowest-order nibble (0x7).</li> |
186 | * <li>A flag bit in the lowest-order nibble (0x8) indicating whether |
187 | * log messages tied to individual kexts are always printed (1) |
188 | * or printed only if the kext has an |
189 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
190 | * OSBundleEnableKextLogging@/link set to <code>true</code>. |
191 | * <li>A set of <b>activity flags</b> in the remaining nibbles (0xFFFFFFF0), |
192 | * which describe areas of activity related to kernel extensions.</li> |
193 | * </ul> |
194 | * |
195 | * You can specify a log spec to most of the kext tools with the -v option |
196 | * and a hex number (rather than the escalating decimal levels 0-6). |
197 | * You can also specify a log spec to the kernel with the "kextlog" boot arg |
198 | * or "debug.kextlog" sysctl. |
199 | * |
200 | * <b>Log Levels</b> |
201 | * |
202 | * The log level spans a range from silent (no log messages) |
203 | * to debuging information: |
204 | * |
205 | * <ol start="0"> |
206 | * <li>Silent - Not applicable to messages; as a filter, do not print any log messages.</li> |
207 | * <li>Errors - Log message is an error. |
208 | * <li>Warnings - Log message is a warning. |
209 | * <li>Basic information - Log message is basic success/failure.</li> |
210 | * <li>Progress - Provides high-level information about stages in processing.</li> |
211 | * <li>Step - Provides low-level information about complex operations, |
212 | * typically about individual kexts.</li> |
213 | * <li>Detail - Provides very low-level information about parts of kexts, |
214 | * including individual Libkern classes and operations on bundle files.</li> |
215 | * <li>Debug - Very verbose logging about internal activities.</li> |
216 | * </ol> |
217 | * |
218 | * Log messages at |
219 | * <code>@link kOSKextLogErrorLevel kOSKextLogErrorLevel@/link</code> or |
220 | * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code> |
221 | * ignore activity flags and the |
222 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
223 | * OSBundleEnableKextLogging@/link property; |
224 | * that is, only the filter level is checked for messages at these levels. |
225 | * Log messages at levels above |
226 | * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code> |
227 | * are filtered according both to the activity flags in the current filter |
228 | * and to whether the log message is associated with a kext or not. |
229 | * Normally log messages associated with kexts are not printed |
230 | * unless the kext has a |
231 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
232 | * OSBundleEnableKextLogging@/link property set to <code>true</code>. |
233 | * If you set the high-order bit of the log level (that is, add 8 to the level), |
234 | * then all kext-specific log messages matching the activity flags are printed. |
235 | * This can be very verbose. |
236 | * |
237 | * <b>Activity Flags</b> |
238 | * |
239 | * Each flag governs a category of activity, |
240 | * such as loading, IPC, or archives; by combining them with bitwise OR, |
241 | * you can choose which messages you wish to see (or when logging messages, |
242 | * which bit flags select your message). |
243 | * |
244 | * <b>Byte 1:</b> <code>0xF0</code> - Basic activities |
245 | * (<code>@link kOSKextLogGeneralFlag kOSKextLogGeneralFlag@/link</code>, |
246 | * <code>@link kOSKextLogLoadFlag kOSKextLogLoadFlag@/link</code>, and |
247 | * <code>@link kOSKextLogArchiveFlag kOSKextLogArchiveFlag@/link</code>). |
248 | * |
249 | * <b>Byte 2:</b> <code>0xF00</code> - Reserved. |
250 | * |
251 | * <b>Byte 4:</b> <code>0xF000</code> - Kext diagnostics |
252 | * (<code>@link kOSKextLogValidationFlag kOSKextLogValidationFlag@/link</code>, |
253 | * <code>@link kOSKextLogAuthenticationFlag kOSKextLogAuthenticationFlag@/link</code>, and |
254 | * <code>@link kOSKextLogDependenciesFlag kOSKextLogDependenciesFlag@/link</code>). |
255 | * |
256 | * <b>Byte 5:</b> <code>0xF00000</code> - Kext access & bookkeeping |
257 | * (<code>@link kOSKextLogDirectoryScanFlag kOSKextLogDirectoryScanFlag@/link</code>, |
258 | * <code>@link kOSKextLogFileAccessFlag kOSKextLogFileAccessFlag@/link</code>, |
259 | * <code>@link kOSKextLogKextBookkeepingFlag kOSKextLogKextBookkeepingFlag@/link </code>). |
260 | * |
261 | * <b>Byte 6:</b> <code>0xF000000</code> - Linking & patching |
262 | * (<code>@link kOSKextLogLinkFlag kOSKextLogLinkFlag@/link</code> and |
263 | * <code>@link kOSKextLogPatchFlag kOSKextLogPatchFlag@/link</code>). |
264 | * |
265 | * <b>Byte 7:</b> <code>0xF0000000</code> - Reserved. |
266 | */ |
267 | typedef uint32_t OSKextLogSpec; |
268 | |
269 | #if PRAGMA_MARK |
270 | /********************************************************************/ |
271 | #pragma mark Masks |
272 | /********************************************************************/ |
273 | #endif |
274 | /*! |
275 | * @define kOSKextLogLevelMask |
276 | * @abstract Masks the bottom 3 bits of an |
277 | * <code>@link OSKextLogSpec OSKextLogSpec@/link</code> to extract |
278 | * the raw level. |
279 | */ |
280 | #define kOSKextLogLevelMask ((OSKextLogSpec) 0x00000007) |
281 | |
282 | /*! |
283 | * @define kOSKextLogKextOrGlobalMask |
284 | * @abstract Determines whether per-kext log messages are output. |
285 | * |
286 | * @discussion |
287 | * In filter specifications, if unset (the usual default), |
288 | * then log messages associated with a kext are only output |
289 | * if the kext has an |
290 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
291 | * OSBundleEnableKextLogging@/link |
292 | * property set to <code>true</code>. |
293 | * If set, then all log messages associated with kexts |
294 | * are output. |
295 | * |
296 | * In message specifications, if set it indicates that the message is either |
297 | * not associated with a kext, or is associated with a kext that has an |
298 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
299 | * OSBundleEnableKextLogging@/link |
300 | * property set to <code>true</code>. |
301 | */ |
302 | #define kOSKextLogKextOrGlobalMask ((OSKextLogSpec) 0x00000008) |
303 | |
304 | |
305 | /*! |
306 | * @define kOSKextLogFlagsMask |
307 | * @abstract Masks the flag bits of an |
308 | * <code>@link OSKextLogSpec OSKextLogSpec@/link</code>. |
309 | */ |
310 | #define kOSKextLogFlagsMask ((OSKextLogSpec) 0x0ffffff0) |
311 | |
312 | /*! |
313 | * @define kOSKextLogFlagsMask |
314 | * @abstract Masks the flag bits of an |
315 | * <code>@link OSKextLogSpec OSKextLogSpec@/link</code> |
316 | * to which command-line <code>-v</code> levels apply. |
317 | */ |
318 | #define kOSKextLogVerboseFlagsMask ((OSKextLogSpec) 0x00000ff0) |
319 | |
320 | /*! |
321 | * @define kOSKextLogConfigMask |
322 | * @abstract Masks the config bits of an |
323 | * <code>@link OSKextLogSpec OSKextLogSpec@/link</code>. |
324 | */ |
325 | #define kOSKextLogConfigMask ((OSKextLogSpec) 0xf0000000) |
326 | |
327 | #if PRAGMA_MARK |
328 | /********************************************************************/ |
329 | #pragma mark 0xF - Log Level |
330 | /********************************************************************/ |
331 | #endif |
332 | |
333 | /*! |
334 | * @define kOSKextLogExplicitLevel |
335 | * @abstract Used when logging a message to overrides the current log filter, |
336 | * even if it's set to silent for log messages. |
337 | * This is essentially a pass-through for |
338 | * unconditional print messages to go |
339 | * through the logging engine. |
340 | */ |
341 | #define kOSKextLogExplicitLevel ((OSKextLogSpec) 0x0) |
342 | |
343 | /*! |
344 | * @define kOSKextLogErrorLevel |
345 | * @abstract Log messages concerning error conditions in any category. |
346 | */ |
347 | #define kOSKextLogErrorLevel ((OSKextLogSpec) 0x1) |
348 | |
349 | |
350 | /*! |
351 | * @define kOSKextLogWarningLevel |
352 | * @abstract Log messages concerning warning conditions in any category, |
353 | * which indicate potential error conditions, |
354 | * and notices, which may explain unexpected but correct behavior. |
355 | */ |
356 | #define kOSKextLogWarningLevel ((OSKextLogSpec) 0x2) |
357 | |
358 | |
359 | /*! |
360 | * @define kOSKextLogBasicLevel |
361 | * @abstract Log messages concerning top-level outcome in any category |
362 | * (kext load/unload, kext cache creation/extration w/# kexts). |
363 | */ |
364 | #define kOSKextLogBasicLevel ((OSKextLogSpec) 0x3) |
365 | |
366 | |
367 | /*! |
368 | * @define kOSKextLogProgressLevel |
369 | * @abstract Log messages concerning high-level progress in any category, |
370 | * such as sending a load request to the kernel, |
371 | * allocation/link/map/start (load operation), |
372 | * stop/unmap (unload operation), kext added/extracted (archive). |
373 | */ |
374 | #define kOSKextLogProgressLevel ((OSKextLogSpec) 0x4) |
375 | |
376 | |
377 | /*! |
378 | * @define kOSKextLogStepLevel |
379 | * @abstract Log messages concerning major steps in any category, |
380 | * such as sending personalities to the IOCatalogue when loading, |
381 | * detailed IPC with the kernel, or filtering of kexts for an archive. |
382 | */ |
383 | #define kOSKextLogStepLevel ((OSKextLogSpec) 0x5) |
384 | |
385 | |
386 | /*! |
387 | * @define kOSKextLogDetailLevel |
388 | * @abstract Log messages concerning specific details in any category, |
389 | * such as classes being registered/unregistered or |
390 | * operations on indivdual files in a kext. |
391 | */ |
392 | #define kOSKextLogDetailLevel ((OSKextLogSpec) 0x6) |
393 | |
394 | |
395 | /*! |
396 | * @define kOSKextLogDebugLevel |
397 | * @abstract Log messages concerning very low-level actions that are |
398 | * useful mainly for debugging the kext system itself. |
399 | */ |
400 | #define kOSKextLogDebugLevel ((OSKextLogSpec) 0x7) |
401 | |
402 | |
403 | #if PRAGMA_MARK |
404 | /********************************************************************/ |
405 | #pragma mark 0xF0 - General Activity, Load, Kernel IPC, Personalities |
406 | /********************************************************************/ |
407 | #endif |
408 | |
409 | /*! |
410 | * @define kOSKextLogGeneralFlag |
411 | * @abstract Log messages about general activity in the kext system. |
412 | */ |
413 | #define kOSKextLogGeneralFlag ((OSKextLogSpec) 0x10) |
414 | |
415 | /*! |
416 | * @define kOSKextLogLoadFlag |
417 | * @abstract Log messages regarding kernel extension load, start/stop, or unload activity |
418 | * in the kernel. |
419 | */ |
420 | #define kOSKextLogLoadFlag ((OSKextLogSpec) 0x20) |
421 | |
422 | /*! |
423 | * @define kOSKextLogIPCFlag |
424 | * @abstract Log messages about any interaction between kernel and user space |
425 | * regarding kernel extensions. |
426 | */ |
427 | #define kOSKextLogIPCFlag ((OSKextLogSpec) 0x40) |
428 | |
429 | /*! |
430 | * @define kOSKextLogArchiveFlag |
431 | * @abstract Log messages about creating or processing a kext startup cache file |
432 | * (mkext or prelinked kernel). |
433 | */ |
434 | #define kOSKextLogArchiveFlag ((OSKextLogSpec) 0x80) |
435 | |
436 | |
437 | #if PRAGMA_MARK |
438 | /********************************************************************/ |
439 | #pragma mark 0xF00 - Reserved Verbose Area |
440 | /********************************************************************/ |
441 | #endif |
442 | // reserved slot for group ((OSKextLogSpec) 0x100) |
443 | // reserved slot for group ((OSKextLogSpec) 0x200) |
444 | // reserved slot for group ((OSKextLogSpec) 0x400) |
445 | // reserved slot for group ((OSKextLogSpec) 0x800) |
446 | |
447 | #if PRAGMA_MARK |
448 | /********************************************************************/ |
449 | #pragma mark 0xF000 - Kext diagnostic activity |
450 | /********************************************************************/ |
451 | #endif |
452 | |
453 | /*! |
454 | * @define kOSKextLogValidationFlag |
455 | * @abstract Log messages when validating kernel extensions. |
456 | */ |
457 | #define kOSKextLogValidationFlag ((OSKextLogSpec) 0x1000) |
458 | |
459 | /*! |
460 | * @define kOSKextLogAuthenticationFlag |
461 | * @abstract Log messages when autnenticating kernel extension files. |
462 | * Irrelevant in the kernel. |
463 | */ |
464 | #define kOSKextLogAuthenticationFlag ((OSKextLogSpec) 0x2000) |
465 | |
466 | /*! |
467 | * @define kOSKextLogDependenciesFlag |
468 | * @abstract Log messages when resolving dependencies for a kernel extension. |
469 | */ |
470 | #define kOSKextLogDependenciesFlag ((OSKextLogSpec) 0x4000) |
471 | |
472 | // reserved slot for group ((OSKextLogSpec) 0x8000) |
473 | |
474 | #if PRAGMA_MARK |
475 | /********************************************************************/ |
476 | #pragma mark 0xF0000 - Archives, caches, directory scan, file access |
477 | /********************************************************************/ |
478 | #endif |
479 | |
480 | /*! |
481 | * @define kOSKextLogDirectoryScanFlag |
482 | * @abstract Log messages when scanning directories for kernel extensions. |
483 | * In the kernel logs every booter kext entry processed. |
484 | */ |
485 | #define kOSKextLogDirectoryScanFlag ((OSKextLogSpec) 0x10000) |
486 | |
487 | /*! |
488 | * @define kOSKextLogFileAccessFlag |
489 | * @abstract Log messages when performing any filesystem access (very verbose). |
490 | * Irrelevant in the kernel. |
491 | */ |
492 | #define kOSKextLogFileAccessFlag ((OSKextLogSpec) 0x20000) |
493 | |
494 | /*! |
495 | * @define kOSKextLogKextBookkeepingFlag |
496 | * @abstract Log messages about internal tracking of kexts. Can be very verbose. |
497 | */ |
498 | #define kOSKextLogKextBookkeepingFlag ((OSKextLogSpec) 0x40000) |
499 | |
500 | // reserved slot for group ((OSKextLogSpec) 0x80000) |
501 | |
502 | #if PRAGMA_MARK |
503 | /********************************************************************/ |
504 | #pragma mark 0xF00000 - Linking & Patching |
505 | /********************************************************************/ |
506 | #endif |
507 | |
508 | /*! |
509 | * @define kOSKextLogLinkFlag |
510 | * @abstract Log messages about linking. |
511 | */ |
512 | #define kOSKextLogLinkFlag ((OSKextLogSpec) 0x100000) |
513 | |
514 | /*! |
515 | * @define kOSKextLogPatchFlag |
516 | * @abstract Log messages about patching. |
517 | */ |
518 | #define kOSKextLogPatchFlag ((OSKextLogSpec) 0x200000) |
519 | |
520 | // reserved slot for group ((OSKextLogSpec) 0x400000) |
521 | // reserved slot for group ((OSKextLogSpec) 0x800000) |
522 | |
523 | #if PRAGMA_MARK |
524 | /********************************************************************/ |
525 | #pragma mark 0xF000000 - Reserved |
526 | /********************************************************************/ |
527 | #endif |
528 | |
529 | // reserved slot for grouping ((OSKextLogSpec) 0x1000000) |
530 | // reserved slot for grouping ((OSKextLogSpec) 0x2000000) |
531 | // reserved slot for grouping ((OSKextLogSpec) 0x4000000) |
532 | // reserved slot for grouping ((OSKextLogSpec) 0x8000000) |
533 | |
534 | |
535 | #if PRAGMA_MARK |
536 | /********************************************************************/ |
537 | #pragma mark 0xF0000000 - Config Flags |
538 | /********************************************************************/ |
539 | #endif |
540 | |
541 | // reserved slot for grouping ((OSKextLogSpec) 0x10000000) |
542 | // reserved slot for grouping ((OSKextLogSpec) 0x20000000) |
543 | // reserved slot for grouping ((OSKextLogSpec) 0x40000000) |
544 | |
545 | #if PRAGMA_MARK |
546 | /********************************************************************/ |
547 | #pragma mark Predefined Specifications |
548 | /********************************************************************/ |
549 | #endif |
550 | |
551 | /*! |
552 | * @define kOSKextLogSilentFilter |
553 | * @abstract For use in filter specs: |
554 | * Ignore all log messages with a log level greater than |
555 | * <code>@link kOSKextLogExplicitLevel kOSKextLogExplicitLevel@/link</code>. |
556 | */ |
557 | #define kOSKextLogSilentFilter ((OSKextLogSpec) 0x0) |
558 | |
559 | /*! |
560 | * @define kOSKextLogShowAllFilter |
561 | * @abstract For use in filter specs: |
562 | * Print all log messages not associated with a kext or |
563 | * associated with a kext that has |
564 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
565 | * OSBundleEnableKextLogging@/link |
566 | * set to <code>true</code>. |
567 | */ |
568 | #define kOSKextLogShowAllFilter ((OSKextLogSpec) 0x0ffffff7) |
569 | |
570 | /*! |
571 | * @define kOSKextLogShowAllKextsFilter |
572 | * @abstract For use in filter specs: |
573 | * Print all log messages has |
574 | * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey |
575 | * OSBundleEnableKextLogging@/link |
576 | * set to <code>true</code>. |
577 | */ |
578 | #define kOSKextLogShowAllKextsFilter ((OSKextLogSpec) \ |
579 | (kOSKextLogShowAllFilter | \ |
580 | kOSKextLogKextOrGlobalMask)) |
581 | |
582 | #if PRAGMA_MARK |
583 | #pragma mark - |
584 | /********************************************************************/ |
585 | #pragma mark Kext Version String Processing |
586 | /********************************************************************/ |
587 | #endif |
588 | /*! |
589 | * @group Kext Version String Processing |
590 | * Functions for working with kext versions and compatible versions. |
591 | */ |
592 | |
593 | /*! |
594 | * @typedef OSKextVersion |
595 | * @abstract An encoded kext version that can be compared arithmetically. |
596 | * |
597 | * @discussion |
598 | * A value of zero (<code>@link kOSKextVersionUndefined kOSKextVersionUndefined@/link</code>) |
599 | * is <i>not</i> equivalent to a version string of "0.0", |
600 | * and typically means there is no version specified |
601 | * (for example, that there is no CFBundleVersion property at all). |
602 | * Values below zero are invalid. |
603 | * |
604 | * The encoding used is subject to change, |
605 | * and should never be saved to permanent storage. |
606 | * Always use proper version strings in files and interprocess communication. |
607 | */ |
608 | typedef int64_t OSKextVersion; |
609 | |
610 | /*! |
611 | * @define kOSKextVersionMaxLength |
612 | * @abstract The length of a string buffer |
613 | * guaranteed to be able to hold a kext version. |
614 | * |
615 | * @discussion |
616 | * Kext versions use an extended Mac OS 'vers' format with double the number |
617 | * of digits before the build stage: ####.##.##s{1-255} where 's' |
618 | * is a build stage 'd', 'a', 'b', 'f' or 'fc'. |
619 | */ |
620 | #define kOSKextVersionMaxLength (20) |
621 | // with a few bytes to spare including a nul byte |
622 | // xx-review: Should we make this much bigger in case we ever need longer strings? |
623 | |
624 | /*! |
625 | * @define kOSKextVersionUndefined |
626 | * @abstract The undefined version. |
627 | * |
628 | * @discussion |
629 | * This value of <code>@link OSKextVersion OSKextVersion@/link</code> represents the |
630 | * lack of a version |
631 | * (for example, that there is no CFBundleVersion property at all). |
632 | */ |
633 | #define kOSKextVersionUndefined (0) |
634 | |
635 | /*! |
636 | * @function OSKextParseVersionString |
637 | * |
638 | * @abstract |
639 | * Parses a kext version string into an <code>@link OSKextVersion OSKextVersion@/link</code>. |
640 | * |
641 | * @param versionString The kext version string to parse. |
642 | * |
643 | * @result |
644 | * An encoded kext version that can be compared numerically |
645 | * against other encoded kext versions, |
646 | * <0 if <code>versionString</code> is <code>NULL</code>, empty, |
647 | * or cannot be parsed. |
648 | * |
649 | * @discussion |
650 | * Kext versions use an extended Mac OS 'vers' format with double the number |
651 | * of digits before the build stage: ####.##.##s{1-255} where 's' |
652 | * is a build stage 'd', 'a', 'b', 'f' or 'fc'. |
653 | */ |
654 | OSKextVersion OSKextParseVersionString(const char * versionString); |
655 | |
656 | |
657 | /*! |
658 | * @function OSKextVersionGetString |
659 | * |
660 | * @abstract |
661 | * Formats an encoded <code>@link OSKextVersion OSKextVersion@/link</code> into a string |
662 | * representation. |
663 | * |
664 | * @param aVersion |
665 | * The encoded version to format. |
666 | * @param buffer |
667 | * A C string buffer of at least |
668 | * <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code> bytes. |
669 | * @param bufferSize The size in bytes of <code>buffer</code>. |
670 | * |
671 | * @result |
672 | * <code>TRUE</code> if the encoded version is formatted successfully. |
673 | * <code>FALSE</code> if <code>buffer</code> is <code>NULL</code> or |
674 | * <code>bufferSize</code> is less than |
675 | * <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code>. |
676 | * |
677 | * @discussion |
678 | * The return value strictly indicates whether <code>buffer</code> |
679 | * is large enough to hold the result. |
680 | * If <code>aVersion</code> is 0, the resulting string is "(missing)". |
681 | * If <code>aVersion</code> is less than 0 |
682 | * or is not a valid kext version encoding, |
683 | * the resulting string is "(invalid)". |
684 | */ |
685 | Boolean OSKextVersionGetString( |
686 | OSKextVersion aVersion, |
687 | char * buffer, |
688 | uint32_t bufferSize); |
689 | |
690 | |
691 | #ifdef KERNEL |
692 | |
693 | |
694 | #if PRAGMA_MARK |
695 | /********************************************************************/ |
696 | #pragma mark - |
697 | #pragma mark Weak linking |
698 | /********************************************************************/ |
699 | #endif |
700 | #ifdef XNU_KERNEL_PRIVATE |
701 | void kext_weak_symbol_referenced(void); |
702 | #endif /* XNU_KERNEL_PRIVATE */ |
703 | |
704 | #if PRAGMA_MARK |
705 | #pragma mark - |
706 | /********************************************************************/ |
707 | #pragma mark Miscellaneous Kernel-Only Kext Functions |
708 | /********************************************************************/ |
709 | #endif |
710 | |
711 | /*! |
712 | * @function kext_get_vm_map |
713 | * @abstract Returns the vm_map from which the kext was allocated. |
714 | * |
715 | * @param info The kmod_info_t structure of the kext. |
716 | * @result The vm_map from which the kext was allocated. This function |
717 | * cannot return <code>NULL</code>. |
718 | */ |
719 | vm_map_t kext_get_vm_map(kmod_info_t * info); |
720 | |
721 | #ifdef XNU_KERNEL_PRIVATE |
722 | |
723 | #if CONFIG_DTRACE |
724 | /*! |
725 | * @function OSKextRegisterKextsWithDTrace |
726 | * @abstract |
727 | * DTrace calls this once when it has started up so that the kext system |
728 | * will register any already-loaded kexts with it. |
729 | */ |
730 | void OSKextRegisterKextsWithDTrace(void); |
731 | |
732 | #endif /* CONFIG_DTRACE */ |
733 | |
734 | /*! |
735 | * @function kext_dump_panic_lists |
736 | * @abstract Prints compacted lists of last unloaded & all loaded kexts |
737 | * during a panic. |
738 | * |
739 | * @param printf_func The printf-style function to use for output. |
740 | */ |
741 | void kext_dump_panic_lists(int (*printf_func)(const char *fmt, ...)); |
742 | |
743 | #endif /* XNU_KERNEL_PRIVATE */ |
744 | |
745 | #ifdef XNU_KERNEL_PRIVATE |
746 | |
747 | #if PRAGMA_MARK |
748 | #pragma mark - |
749 | /********************************************************************/ |
750 | #pragma mark Kext Loading C Functions |
751 | /********************************************************************/ |
752 | #endif |
753 | /*! |
754 | * @function OSKextGetLoadTagForBundleIdentifier |
755 | * @abstract Look up the load tag for a kext. |
756 | * |
757 | * @param kextIdentifier The bundle identifier of the kext to look up. |
758 | * @result |
759 | * The load tag of the requested kext, or |
760 | * <code>@link //apple_ref/c/macro/kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code> |
761 | * if the kext was not found. |
762 | * |
763 | * @discussion |
764 | * A load tag uniquely identifies a loaded kext. |
765 | * It can be found as the <code>id</code> field of a loaded kext's |
766 | * <code>kmod_info_t</code> struct. |
767 | * |
768 | * Note that a load tag represents a specific loaded instance of a kext. |
769 | * If that kext is unloaded, the load tag is no longer a valid reference. |
770 | * If the same kext is later reloaded, it will have a new load tag. |
771 | * |
772 | * You can use the load tag to adjust a kext's reference count |
773 | * via |
774 | * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag |
775 | * OSKextRetainKextWithLoadTag@/link</code> |
776 | * and |
777 | * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag |
778 | * OSKextReleaseKextWithLoadTag@/link</code>, |
779 | * so that the kext is automatically unloaded when no references remain, |
780 | * or to unload the kext immediately |
781 | * with <code>@link //apple_ref/c/func/OSKextUnloadKextWithLoadTag OSKextUnloadKextWithLoadTag@/link</code>. |
782 | * |
783 | * Those functions are intended for use with non-IOKit kexts |
784 | * (specifically, kexts that define no subclasses of |
785 | * <code>@link //apple_ref/doc/class/IOServiceIOService@/link</code>). |
786 | * Pure IOKit kexts are managed via instance counts |
787 | * of their libkern C++ object classes; |
788 | * using those functions on them will only interfere with that mechanism. |
789 | * If you have a hybrid kext with both IOService subclasses and non-IOKit code, |
790 | * however, you may want to use reference counting for the non-IOKit portions: |
791 | * that way the kext will only unload automaticaly |
792 | * when there are no C++ objects and the kext reference count is zero. |
793 | */ |
794 | uint32_t OSKextGetLoadTagForBundleIdentifier( |
795 | const char * kextIdentifier); |
796 | |
797 | |
798 | /*! |
799 | * @function OSKextUnloadKextWithLoadTag |
800 | * @abstract Stop and unload a kext based on its load tag. |
801 | * |
802 | * @param loadTag The load tag of the kext to unload. |
803 | * @result |
804 | * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code> |
805 | * if the kext was found and unloaded. |
806 | * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound |
807 | * kOSKextReturnNotFound@/link</code> |
808 | * if the kext was not found. |
809 | * <code>@link //apple_ref/c/macro/kOSKextReturnInUse |
810 | * kOSKextReturnInUse@/link</code> |
811 | * if the kext has outstanding references |
812 | * or if there are instances of its libkern C++ subclasses. |
813 | * Other return values indicate a failure to unload the kext, |
814 | * typically because the module stop routine failed. |
815 | * |
816 | * @discussion |
817 | * A panic will occur if a kext calls this function to unload itself. |
818 | * The safest way for a kext to unload itself is to call |
819 | * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag |
820 | * OSKextRetainKextWithLoadTag@/link</code> |
821 | * with its own load tag |
822 | * (the <code>id</code> field of its <code>kmod_info_t</code> struct), |
823 | * followed by |
824 | * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag |
825 | * OSKextReleaseKextWithLoadTag@/link</code>; |
826 | * this will schedule the kext for unload on a separate thread. |
827 | * |
828 | * This function can be used when reference-based autounloading is not |
829 | * appropriate. |
830 | * If a kernel system or kext is already monitoring |
831 | * the need for a kext, |
832 | * it can simply call this function when it's known that the kext is not needed. |
833 | */ |
834 | OSReturn OSKextUnloadKextWithLoadTag(uint32_t loadTag); |
835 | |
836 | #endif /* XNU_KERNEL_PRIVATE */ |
837 | |
838 | #endif /* KERNEL */ |
839 | |
840 | #if PRAGMA_MARK |
841 | #pragma mark - |
842 | /********************************************************************/ |
843 | #pragma mark Loaded Kext Summary |
844 | /********************************************************************/ |
845 | #endif |
846 | |
847 | /*! |
848 | * @define kOSKextLoadedKextSummaryVersion |
849 | * @abstract The current version of the loaded kext summary headers. |
850 | */ |
851 | #define kOSKextLoadedKextSummaryVersion 2 |
852 | |
853 | /*! |
854 | * @typedef OSKextLoadedKextSummary |
855 | * @abstract A structure that describes a loaded kext. |
856 | * |
857 | * @field name The kext's bundle identifier. |
858 | * @field uuid The kext's UUID; |
859 | * @field address The kext's load address. |
860 | * @field size The kext's load size. |
861 | * @field version The binary format (OSKextVersion) version of the kext. |
862 | * @field loadTag The kext's load tag. |
863 | * @field flags Internal tracking flags. |
864 | * @field reference_list who this refs (links on). |
865 | * |
866 | * @discussion |
867 | * The OSKextLoadedKextSummary structure contains a basic set of information |
868 | * about the kext to facilitate kext debugging and panic debug log output. |
869 | */ |
870 | typedef struct _loaded_kext_summary { |
871 | char name[KMOD_MAX_NAME]; |
872 | uuid_t uuid; |
873 | uint64_t address; |
874 | uint64_t size; |
875 | uint64_t version; |
876 | uint32_t loadTag; |
877 | uint32_t flags; |
878 | uint64_t reference_list; |
879 | } OSKextLoadedKextSummary; |
880 | |
881 | /*! |
882 | * @typedef OSKextLoadedKextSummaryHeader |
883 | * @abstract A structure that describes the set of loaded kext summaries. |
884 | * |
885 | * @field version The version of the loaded kext summary structures. |
886 | * @field entry_size The size of each entry in summaries. |
887 | * @field numSummaries The number of OSKextLoadedKextSummary structures |
888 | * following the header. |
889 | * @field summaries A convenience pointer to the array of summaries following |
890 | * the header. |
891 | * |
892 | * @discussion |
893 | * The OSKextLoadedKextSummaryHeader describes the set of loaded kext summaries |
894 | * available for use by the debugger or panic log routine. |
895 | * The array of summaries contains one OSKextLoadedKextSummary for every kext |
896 | * that declares an executable and is not an interface to the kernel. |
897 | */ |
898 | typedef struct { |
899 | uint32_t ; |
900 | uint32_t ; |
901 | uint32_t ; |
902 | uint32_t ; /* explicit alignment for gdb */ |
903 | OSKextLoadedKextSummary [0]; |
904 | } ; |
905 | |
906 | /*! |
907 | * @var gLoadedKextSummaries |
908 | * @abstract The global pointer to the current set of loaded kext summaries. |
909 | */ |
910 | extern OSKextLoadedKextSummaryHeader * gLoadedKextSummaries; |
911 | |
912 | /*! |
913 | * @var gLoadedKextSummariesTimestamp |
914 | * |
915 | * @abstract This will be set to mach_absolute_time() around updates to |
916 | * gLoadedKextSummaries. Ie. immediately before gLoadedKextSummaries is set to |
917 | * zero, and immediately after it is set to a new value. |
918 | */ |
919 | extern uint64_t gLoadedKextSummariesTimestamp; |
920 | |
921 | /*! |
922 | * @function OSKextLoadedKextSummariesUpdated |
923 | * @abstract Called when gLoadedKextSummaries has been updated. |
924 | * |
925 | * @discussion |
926 | * gLoadedKextSummaries is updated when a kext is loaded or unloaded. |
927 | * When the update is complete, OSKextLoadedKextSummariesUpdated is called. |
928 | * gdb can set a breakpoint on this function to detect kext loads and unloads. |
929 | */ |
930 | void OSKextLoadedKextSummariesUpdated(void); |
931 | |
932 | #ifdef XNU_KERNEL_PRIVATE |
933 | |
934 | extern const vm_allocation_site_t * OSKextGetAllocationSiteForCaller(uintptr_t address); |
935 | extern uint32_t OSKextGetKmodIDForSite(const vm_allocation_site_t * site, |
936 | char * name, vm_size_t namelen); |
937 | extern void OSKextFreeSite(vm_allocation_site_t * site); |
938 | |
939 | #if CONFIG_IMAGEBOOT |
940 | extern int OSKextGetUUIDForName(const char *, uuid_t); |
941 | #endif |
942 | |
943 | extern vm_tag_t gIOSurfaceTag; |
944 | |
945 | extern void *OSKextKextForAddress(const void *addr); |
946 | |
947 | #endif /* XNU_KERNEL_PRIVATE */ |
948 | |
949 | __END_DECLS |
950 | |
951 | #endif /* ! _LIBKERN_OSKEXTLIBPRIVATE_H */ |
952 | |