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
58typedef 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 kOSBundleMachOHeadersKey "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 */
267typedef 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 */
608typedef 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 */
654OSKextVersion 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 */
685Boolean 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
701void 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 */
719vm_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 */
730void 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 */
741void 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 */
794uint32_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 */
834OSReturn 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 */
870typedef 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 */
898typedef struct _loaded_kext_summary_header {
899 uint32_t version;
900 uint32_t entry_size;
901 uint32_t numSummaries;
902 uint32_t reserved; /* explicit alignment for gdb */
903 OSKextLoadedKextSummary summaries[0];
904} OSKextLoadedKextSummaryHeader;
905
906/*!
907 * @var gLoadedKextSummaries
908 * @abstract The global pointer to the current set of loaded kext summaries.
909 */
910extern 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 */
919extern 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 */
930void OSKextLoadedKextSummariesUpdated(void);
931
932#ifdef XNU_KERNEL_PRIVATE
933
934extern const vm_allocation_site_t * OSKextGetAllocationSiteForCaller(uintptr_t address);
935extern uint32_t OSKextGetKmodIDForSite(const vm_allocation_site_t * site,
936 char * name, vm_size_t namelen);
937extern void OSKextFreeSite(vm_allocation_site_t * site);
938
939#if CONFIG_IMAGEBOOT
940extern int OSKextGetUUIDForName(const char *, uuid_t);
941#endif
942
943extern vm_tag_t gIOSurfaceTag;
944
945extern void *OSKextKextForAddress(const void *addr);
946
947#endif /* XNU_KERNEL_PRIVATE */
948
949__END_DECLS
950
951#endif /* ! _LIBKERN_OSKEXTLIBPRIVATE_H */
952