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