xref: /xnu-8792.41.9/libkern/libkern/OSKextLibPrivate.h (revision 5c2921b07a2480ab43ec66f5b9e41cb872bc554f)

/*
 * Copyright (c) 1998-2000 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef _LIBKERN_OSKEXTLIBPRIVATE_H
#define _LIBKERN_OSKEXTLIBPRIVATE_H


#include <sys/cdefs.h>

__BEGIN_DECLS

#include <libkern/OSTypes.h>
#include <mach/kmod.h>

#ifdef KERNEL
#include <mach/vm_types.h>
#endif /* KERNEL */

__END_DECLS

#include <libkern/OSReturn.h>

__BEGIN_DECLS

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Misc Constants
/********************************************************************/
#endif

typedef uint8_t OSKextExcludeLevel;
#define kOSKextExcludeNone  (0)
#define kOSKextExcludeKext  (1)
#define kOSKextExcludeAll   (2)

#define kIOCatalogManagementEntitlement "com.apple.private.security.iocatalog-management"
#define kOSKextCollectionManagementEntitlement "com.apple.private.security.kext-collection-management"
#define kOSKextOnlyBootKCManagementEntitlement "com.apple.private.security.only-bootkc-management"

#define kOSKextCodelessKextLoadAddr (0x7FFFFFFFFFFFFFFFULL)

#if XNU_TARGET_OS_OSX
#define kIOKitDaemonName "kernelmanagerd"
#else
#define kIOKitDaemonName "driverkitd"
#endif /* XNU_TARGET_OS_OSX */

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Kext/OSBundle Property List Keys
/********************************************************************/
#endif

/*!
 * @define   kOSBundleHelperKey
 * @abstract Used by loginwindow.
 */
#define kOSBundleHelperKey      "OSBundleHelper"

/*!
 * @define   kOSBundleDeveloperOnlyKey
 * @abstract A boolean value indicating whether the kext should only load on
 *           Developer devices.
 */
#define kOSBundleDeveloperOnlyKey               "OSBundleDeveloperOnly"

/*!
 * @define   kOSBundleRamDiskOnlyKey
 * @abstract A boolean value indicating whether the kext should only load when
 *           booted from a ram disk.
 */
#define kOSBundleRamDiskOnlyKey         "OSBundleRamDiskOnly"


/*!
 * @define   kAppleSecurityExtensionKey
 * @abstract A boolean value indicating whether the kext registers
 *           MACF hooks.
 */
#define kAppleSecurityExtensionKey      "AppleSecurityExtension"

/*!
 * @define   kAppleKernelExternalComponentKey
 * @abstract A boolean value indicating whether the kext is vending kernel
 *           KPI, and needs special loading behavior.
 */
#define kAppleKernelExternalComponentKey        "AppleKernelExternalComponent"

/*!
 * @define kOSKextInfoPlistDigestKey
 * @abstract SHA-256 data of the kext's Info.plist
 */
#define kOSKextInfoPlistDigestKey       "_InfoPlistDigest"

/*!
 * @define kOSKextBundleCollectionTypeKey
 * @abstract The type of collection in which a kext is linked. Possible
 *           values: kKCTypePrimary, kKCTypeSystem, kKCTypeAuxiliary,
 *                   kKCTypeCodeless
 */
#define kOSKextBundleCollectionTypeKey  "_BundleCollectionType"

/*!
 * @define kOSKextAuxKCAvailabilityKey
 * @abstract boolean value: false if the kext is in the AuxKC and
 *           is not loadable; true otherwise.
 */
#define kOSKextAuxKCAvailabilityKey     "_AuxKCAvailability"


// properties found in the registry root
#define kOSKernelCPUTypeKey             "OSKernelCPUType"
#define kOSKernelCPUSubtypeKey          "OSKernelCPUSubtype"
#define kOSStartupMkextCRC              "OSStartupMkextCRC"             /* value is 32-bit OSData */
#define kOSPrelinkKextCountKey          "OSPrelinkKextCount"            /* value is 32-bit OSNumber */
#define kOSPrelinkPersonalityCountKey   "OSPrelinkPersonalityCount"     /* value is 32-bit OSNumber */

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Load Info Keys
/********************************************************************/
#endif
/*********************************************************************
* In addition to the keys defined here, you will find:
*   kCFBundleIdentifierKey
*   kCFBundleVersionKey
*   kOSBundleCompatibleVersionKey
*   kOSBundleIsInterfaceKey
*   kOSKernelResourceKey
*********************************************************************/
#define kOSBundleMachOHeadersKey                "OSBundleMachOHeaders"
#define kOSBundleLogStringsKey                  "OSBundleLogStrings"
#define kOSBundleCPUTypeKey                     "OSBundleCPUType"
#define kOSBundleCPUSubtypeKey                  "OSBundleCPUSubtype"
#define kOSBundlePathKey                        "OSBundlePath"
#define kOSBundleExecutablePathKey              "OSBundleExecutablePath"
#define kOSBundleUUIDKey                        "OSBundleUUID"
#define kOSBundleTextUUIDKey                    "OSBundleTextUUID"
#define kOSBundleStartedKey                     "OSBundleStarted"
#define kOSBundlePrelinkedKey                   "OSBundlePrelinked"
#define kOSBundleLoadTagKey                     "OSBundleLoadTag"
#define kOSBundleLoadAddressKey                 "OSBundleLoadAddress"
#define kOSBundleLoadSizeKey                    "OSBundleLoadSize"
#define kOSBundleExecLoadAddressKey             "OSBundleExecLoadAddress"
#define kOSBundleExecLoadSizeKey                "OSBundleExecLoadSize"
#define kOSBundleWiredSizeKey                   "OSBundleWiredSize"
#define kOSBundleDependenciesKey                "OSBundleDependencies"
#define kOSBundleRetainCountKey                 "OSBundleRetainCount"
#define kOSBundleCacheLoadAddressKey            "OSBundleCacheLoadAddress"
// Kernel TEXT encompasses kexts
#define kOSBundleKextsInKernelTextKey           "OSBundleKextsInKernelText"
// OSKextCopyLoadedKextInfo includes non-started kexts when present:
#define kOSBundleAllPrelinkedKey                "OSBundleAllPrelinked"
// OSKextCopyDextsInfo states:
#define kOSBundleDextStateKey                   "OSBundleDextState"
#define kOSBundleDextStateActiveKey             "OSBundleDextStateActive"
#define kOSBundleDextStateActiveLoadedKey       "OSBundleDextStateActiveLoaded"
#define kOSBundleDextStateActiveUnloadedKey     "OSBundleDextStateActiveUnloaded"
#define kOSBundleDextStatePendingUpgradeKey     "OSBundleDextStatePendingUpgrade"


/* Dictionary of metaclass info keyed by classname.
 */
#define kOSBundleClassesKey                     "OSBundleClasses"

#define kOSBundleDextUniqueIdentifierKey        "kOSBundleDextUniqueIdentifier"
/* These are contained in kOSBundleClassesKey. kOSMetaClassSuperclassNameKey
 * may be absent (for the root class).
 */
#define kOSMetaClassNameKey                     "OSMetaClassName"
#define kOSMetaClassSuperclassNameKey           "OSMetaClassSuperclassName"
#define kOSMetaClassTrackingCountKey            "OSMetaClassTrackingCount"

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Kext Collection Type Keys
/********************************************************************/
#endif
#define kKCTypePrimary   "Primary"
#define kKCTypeSystem    "System"
#define kKCTypeAuxiliary "Auxiliary"
#define kKCTypeCodeless  "Codeless"
#define kKCTypeAny       "Any"

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Kext Log Specification
/********************************************************************/
#endif
/*!
 * @group Kext Log Specification
 * Logging levels & flags for kernel extensions.
 * See <code>@link //apple_ref/c/tdef/OSKextLogSpec OSKextLogSpec@/link</code>
 * for an overview.
 */

/*!
 * @typedef  OSKextLogSpec
 * @abstract Describes what a log message applies to,
 *           or a filter that determines which log messages are displayed.
 *
 * @discussion
 * A kext log specification is a 32-bit value used as a desription of
 * what a given log message applies to, or as a filter
 * indicating which log messages are desired and which are not.
 * A log specification has three parts (described in detail shortly):
 * <ul>
 *   <li>A <b>level</b> from 0-7 in the lowest-order nibble (0x7).</li>
 *   <li>A flag bit in the lowest-order nibble (0x8) indicating whether
 *       log messages tied to individual kexts are always printed (1)
 *       or printed only if the kext has an
 *       @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 *       OSBundleEnableKextLogging@/link set to <code>true</code>.
 *   <li>A set of <b>activity flags</b> in the remaining nibbles (0xFFFFFFF0),
 *       which describe areas of activity related to kernel extensions.</li>
 * </ul>
 *
 * You can specify a log spec to most of the kext tools with the -v option
 * and a hex number (rather than the escalating decimal levels 0-6).
 * You can also specify a log spec to the kernel with the "kextlog" boot arg
 * or "debug.kextlog" sysctl.
 *
 * <b>Log Levels</b>
 *
 * The log level spans a range from silent (no log messages)
 * to debuging information:
 *
 * <ol start="0">
 * <li>Silent - Not applicable to messages; as a filter, do not print any log messages.</li>
 * <li>Errors - Log message is an error.
 * <li>Warnings - Log message is a warning.
 * <li>Basic information - Log message is basic success/failure.</li>
 * <li>Progress - Provides high-level information about stages in processing.</li>
 * <li>Step - Provides low-level information about complex operations,
 *          typically about individual kexts.</li>
 * <li>Detail - Provides very low-level information about parts of kexts,
 *          including individual Libkern classes and operations on bundle files.</li>
 * <li>Debug - Very verbose logging about internal activities.</li>
 * </ol>
 *
 * Log messages at
 * <code>@link kOSKextLogErrorLevel kOSKextLogErrorLevel@/link</code> or
 * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code>
 * ignore activity flags and the
 * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 * OSBundleEnableKextLogging@/link property;
 * that is, only the filter level is checked for messages at these levels.
 * Log messages at levels above
 * <code>@link kOSKextLogWarningLevel kOSKextLogWarningLevel@/link</code>
 * are filtered according both to the activity flags in the current filter
 * and to whether the log message is associated with a kext or not.
 * Normally log messages associated with kexts are not printed
 * unless the kext has a
 * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 * OSBundleEnableKextLogging@/link property set to <code>true</code>.
 * If you set the high-order bit of the log level (that is, add 8 to the level),
 * then all kext-specific log messages matching the activity flags are printed.
 * This can be very verbose.
 *
 * <b>Activity Flags</b>
 *
 * Each flag governs a category of activity,
 * such as loading, IPC, or archives; by combining them with bitwise OR,
 * you can choose which messages you wish to see (or when logging messages,
 * which bit flags select your message).
 *
 * <b>Byte 1:</b> <code>0xF0</code> - Basic activities
 * (<code>@link kOSKextLogGeneralFlag kOSKextLogGeneralFlag@/link</code>,
 * <code>@link kOSKextLogLoadFlag kOSKextLogLoadFlag@/link</code>, and
 * <code>@link kOSKextLogArchiveFlag kOSKextLogArchiveFlag@/link</code>).
 *
 * <b>Byte 2:</b> <code>0xF00</code> - Reserved.
 *
 * <b>Byte 4:</b> <code>0xF000</code> - Kext diagnostics
 * (<code>@link kOSKextLogValidationFlag kOSKextLogValidationFlag@/link</code>,
 * <code>@link kOSKextLogAuthenticationFlag kOSKextLogAuthenticationFlag@/link</code>, and
 * <code>@link kOSKextLogDependenciesFlag kOSKextLogDependenciesFlag@/link</code>).
 *
 * <b>Byte 5:</b> <code>0xF00000</code> - Kext access & bookkeeping
 * (<code>@link kOSKextLogDirectoryScanFlag kOSKextLogDirectoryScanFlag@/link</code>,
 * <code>@link kOSKextLogFileAccessFlag kOSKextLogFileAccessFlag@/link</code>,
 * <code>@link kOSKextLogKextBookkeepingFlag kOSKextLogKextBookkeepingFlag@/link </code>).
 *
 * <b>Byte 6:</b> <code>0xF000000</code> - Linking & patching
 * (<code>@link kOSKextLogLinkFlag kOSKextLogLinkFlag@/link</code> and
 * <code>@link kOSKextLogPatchFlag kOSKextLogPatchFlag@/link</code>).
 *
 * <b>Byte 7:</b> <code>0xF0000000</code> - Reserved.
 */
typedef uint32_t OSKextLogSpec;

#if PRAGMA_MARK
/********************************************************************/
#pragma mark Masks
/********************************************************************/
#endif
/*!
 * @define   kOSKextLogLevelMask
 * @abstract Masks the bottom 3 bits of an
 *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code> to extract
 *           the raw level.
 */
#define kOSKextLogLevelMask              ((OSKextLogSpec) 0x00000007)

/*!
 * @define   kOSKextLogKextOrGlobalMask
 * @abstract Determines whether per-kext log messages are output.
 *
 * @discussion
 * In filter specifications, if unset (the usual default),
 * then log messages associated with a kext are only output
 * if the kext has an
 * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 * OSBundleEnableKextLogging@/link
 * property set to <code>true</code>.
 * If set, then all log messages associated with kexts
 * are output.
 *
 * In message specifications, if set it indicates that the message is either
 * not associated with a kext, or is associated with a kext that has an
 * @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 * OSBundleEnableKextLogging@/link
 * property set to <code>true</code>.
 */
#define kOSKextLogKextOrGlobalMask       ((OSKextLogSpec) 0x00000008)


/*!
 * @define   kOSKextLogFlagsMask
 * @abstract Masks the flag bits of an
 *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>.
 */
#define kOSKextLogFlagsMask              ((OSKextLogSpec) 0x0ffffff0)

/*!
 * @define   kOSKextLogFlagsMask
 * @abstract Masks the flag bits of an
 *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>
 *           to which command-line <code>-v</code> levels apply.
 */
#define kOSKextLogVerboseFlagsMask       ((OSKextLogSpec) 0x00000ff0)

/*!
 * @define   kOSKextLogConfigMask
 * @abstract Masks the config bits of an
 *           <code>@link OSKextLogSpec OSKextLogSpec@/link</code>.
 */
#define kOSKextLogConfigMask             ((OSKextLogSpec) 0xf0000000)

#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF - Log Level
/********************************************************************/
#endif

/*!
 * @define   kOSKextLogExplicitLevel
 * @abstract Used when logging a message to overrides the current log filter,
 *           even if it's set to silent for log messages.
 *           This is essentially a pass-through for
 *           unconditional print messages to go
 *           through the logging engine.
 */
#define kOSKextLogExplicitLevel          ((OSKextLogSpec)        0x0)

/*!
 * @define   kOSKextLogErrorLevel
 * @abstract Log messages concerning error conditions in any category.
 */
#define kOSKextLogErrorLevel            ((OSKextLogSpec)        0x1)


/*!
 * @define   kOSKextLogWarningLevel
 * @abstract Log messages concerning warning conditions in any category,
 *           which indicate potential error conditions,
 *           and notices, which may explain unexpected but correct behavior.
 */
#define kOSKextLogWarningLevel          ((OSKextLogSpec)        0x2)


/*!
 * @define   kOSKextLogBasicLevel
 * @abstract Log messages concerning top-level outcome in any category
 *           (kext load/unload, kext cache creation/extration w/# kexts).
 */
#define kOSKextLogBasicLevel           ((OSKextLogSpec)        0x3)


/*!
 * @define   kOSKextLogProgressLevel
 * @abstract Log messages concerning high-level progress in any category,
 *           such as sending a load request to the kernel,
 *           allocation/link/map/start (load operation),
 *           stop/unmap (unload operation), kext added/extracted (archive).
 */
#define kOSKextLogProgressLevel          ((OSKextLogSpec)        0x4)


/*!
 * @define   kOSKextLogStepLevel
 * @abstract Log messages concerning major steps in any category,
 *           such as sending personalities to the IOCatalogue when loading,
 *           detailed IPC with the kernel, or filtering of kexts for an archive.
 */
#define kOSKextLogStepLevel             ((OSKextLogSpec)        0x5)


/*!
 * @define   kOSKextLogDetailLevel
 * @abstract Log messages concerning specific details in any category,
 *           such as classes being registered/unregistered or
 *           operations on indivdual files in a kext.
 */
#define kOSKextLogDetailLevel           ((OSKextLogSpec)        0x6)


/*!
 * @define   kOSKextLogDebugLevel
 * @abstract Log messages concerning very low-level actions that are
 *           useful mainly for debugging the kext system itself.
 */
#define kOSKextLogDebugLevel             ((OSKextLogSpec)        0x7)


#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF0 - General Activity, Load, Kernel IPC, Personalities
/********************************************************************/
#endif

/*!
 * @define   kOSKextLogGeneralFlag
 * @abstract Log messages about general activity in the kext system.
 */
#define kOSKextLogGeneralFlag            ((OSKextLogSpec)       0x10)

/*!
 * @define   kOSKextLogLoadFlag
 * @abstract Log messages regarding kernel extension load, start/stop, or unload activity
 *           in the kernel.
 */
#define kOSKextLogLoadFlag               ((OSKextLogSpec)       0x20)

/*!
 * @define   kOSKextLogIPCFlag
 * @abstract Log messages about any interaction between kernel and user space
 *           regarding kernel extensions.
 */
#define kOSKextLogIPCFlag                ((OSKextLogSpec)       0x40)

/*!
 * @define   kOSKextLogArchiveFlag
 * @abstract Log messages about creating or processing a kext startup cache file
 *           (mkext or prelinked kernel).
 */
#define kOSKextLogArchiveFlag           ((OSKextLogSpec)       0x80)


#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF00 - Reserved Verbose Area
/********************************************************************/
#endif
// reserved slot for group               ((OSKextLogSpec)      0x100)
// reserved slot for group               ((OSKextLogSpec)      0x200)
// reserved slot for group               ((OSKextLogSpec)      0x400)
// reserved slot for group               ((OSKextLogSpec)      0x800)

#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF000 - Kext diagnostic activity
/********************************************************************/
#endif

/*!
 * @define   kOSKextLogValidationFlag
 * @abstract Log messages when validating kernel extensions.
 */
#define kOSKextLogValidationFlag         ((OSKextLogSpec)     0x1000)

/*!
 * @define   kOSKextLogAuthenticationFlag
 * @abstract Log messages when autnenticating kernel extension files.
 *           Irrelevant in the kernel.
 */
#define kOSKextLogAuthenticationFlag     ((OSKextLogSpec)     0x2000)

/*!
 * @define   kOSKextLogDependenciesFlag
 * @abstract Log messages when resolving dependencies for a kernel extension.
 */
#define kOSKextLogDependenciesFlag       ((OSKextLogSpec)     0x4000)

// reserved slot for group               ((OSKextLogSpec)     0x8000)

#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF0000 - Archives, caches, directory scan, file access
/********************************************************************/
#endif

/*!
 * @define   kOSKextLogDirectoryScanFlag
 * @abstract Log messages when scanning directories for kernel extensions.
 *           In the kernel logs every booter kext entry processed.
 */
#define kOSKextLogDirectoryScanFlag      ((OSKextLogSpec)    0x10000)

/*!
 * @define   kOSKextLogFileAccessFlag
 * @abstract Log messages when performing any filesystem access (very verbose).
 *           Irrelevant in the kernel.
 */
#define kOSKextLogFileAccessFlag         ((OSKextLogSpec)    0x20000)

/*!
 * @define   kOSKextLogKextBookkeepingFlag
 * @abstract Log messages about internal tracking of kexts. Can be very verbose.
 */
#define kOSKextLogKextBookkeepingFlag    ((OSKextLogSpec)    0x40000)

// reserved slot for group               ((OSKextLogSpec)    0x80000)

#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF00000 - Linking & Patching
/********************************************************************/
#endif

/*!
 * @define   kOSKextLogLinkFlag
 * @abstract Log messages about linking.
 */
#define kOSKextLogLinkFlag               ((OSKextLogSpec)   0x100000)

/*!
 * @define   kOSKextLogPatchFlag
 * @abstract Log messages about patching.
 */
#define kOSKextLogPatchFlag              ((OSKextLogSpec)   0x200000)

// reserved slot for group               ((OSKextLogSpec)   0x400000)
// reserved slot for group               ((OSKextLogSpec)   0x800000)

#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF000000 - Reserved
/********************************************************************/
#endif

// reserved slot for grouping            ((OSKextLogSpec)  0x1000000)
// reserved slot for grouping            ((OSKextLogSpec)  0x2000000)
// reserved slot for grouping            ((OSKextLogSpec)  0x4000000)
// reserved slot for grouping            ((OSKextLogSpec)  0x8000000)


#if PRAGMA_MARK
/********************************************************************/
#pragma mark 0xF0000000 - Config Flags
/********************************************************************/
#endif

// reserved slot for grouping            ((OSKextLogSpec) 0x10000000)
// reserved slot for grouping            ((OSKextLogSpec) 0x20000000)
// reserved slot for grouping            ((OSKextLogSpec) 0x40000000)

#if PRAGMA_MARK
/********************************************************************/
#pragma mark Predefined Specifications
/********************************************************************/
#endif

/*!
 * @define   kOSKextLogSilentFilter
 * @abstract For use in filter specs:
 *           Ignore all log messages with a log level greater than
 *           <code>@link kOSKextLogExplicitLevel kOSKextLogExplicitLevel@/link</code>.
 */
#define kOSKextLogSilentFilter           ((OSKextLogSpec)        0x0)

/*!
 * @define   kOSKextLogShowAllFilter
 * @abstract For use in filter specs:
 *           Print all log messages not associated with a kext or
 *           associated with a kext that has
 *           @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 *           OSBundleEnableKextLogging@/link
 *           set to <code>true</code>.
 */
#define kOSKextLogShowAllFilter          ((OSKextLogSpec) 0x0ffffff7)

/*!
 * @define   kOSKextLogShowAllKextsFilter
 * @abstract For use in filter specs:
 *           Print all log messages has
 *           @link //apple_ref/c/macro/kOSBundleEnableKextLoggingKey
 *           OSBundleEnableKextLogging@/link
 *           set to <code>true</code>.
 */
#define kOSKextLogShowAllKextsFilter     ((OSKextLogSpec) \
	                                   (kOSKextLogShowAllFilter | \
	                                    kOSKextLogKextOrGlobalMask))

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Kext Version String Processing
/********************************************************************/
#endif
/*!
 * @group Kext Version String Processing
 * Functions for working with kext versions and compatible versions.
 */

/*!
 * @typedef   OSKextVersion
 * @abstract  An encoded kext version that can be compared arithmetically.
 *
 * @discussion
 * A value of zero (<code>@link kOSKextVersionUndefined kOSKextVersionUndefined@/link</code>)
 * is <i>not</i> equivalent to a version string of "0.0",
 * and typically means there is no version specified
 * (for example, that there is no CFBundleVersion property at all).
 * Values below zero are invalid.
 *
 * The encoding used is subject to change,
 * and should never be saved to permanent storage.
 * Always use proper version strings in files and interprocess communication.
 */
typedef int64_t OSKextVersion;

/*!
 * @define    kOSKextVersionMaxLength
 * @abstract  The length of a string buffer
 *            guaranteed to be able to hold a kext version.
 *
 * @discussion
 * Kext versions use an extended Mac OS 'vers' format with double the number
 * of digits before the build stage: ####.##.##s{1-255} where 's'
 * is a build stage 'd', 'a', 'b', 'f' or 'fc'.
 */
#define kOSKextVersionMaxLength (20)
// with a few bytes to spare including a nul byte
// xx-review: Should we make this much bigger in case we ever need longer strings?

/*!
 * @define    kOSKextVersionUndefined
 * @abstract  The undefined version.
 *
 * @discussion
 * This value of <code>@link OSKextVersion OSKextVersion@/link</code> represents the
 * lack of a version
 * (for example, that there is no CFBundleVersion property at all).
 */
#define kOSKextVersionUndefined  (0)

/*!
 * @function OSKextParseVersionString
 *
 * @abstract
 * Parses a kext version string into an <code>@link OSKextVersion OSKextVersion@/link</code>.
 *
 * @param  versionString  The kext version string to parse.
 *
 * @result
 * An encoded kext version that can be compared numerically
 * against other encoded kext versions,
 * <0 if <code>versionString</code> is <code>NULL</code>, empty,
 * or cannot be parsed.
 *
 * @discussion
 * Kext versions use an extended Mac OS 'vers' format with double the number
 * of digits before the build stage: ####.##.##s{1-255} where 's'
 * is a build stage 'd', 'a', 'b', 'f' or 'fc'.
 */
OSKextVersion OSKextParseVersionString(const char * versionString);


/*!
 * @function OSKextVersionGetString
 *
 * @abstract
 * Formats an encoded <code>@link OSKextVersion OSKextVersion@/link</code> into a string
 * representation.
 *
 * @param  aVersion
 *         The encoded version to format.
 * @param  buffer
 *         A C string buffer of at least
 *         <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code> bytes.
 * @param  bufferSize  The size in bytes of <code>buffer</code>.
 *
 * @result
 * <code>TRUE</code> if the encoded version is formatted successfully.
 * <code>FALSE</code> if <code>buffer</code> is <code>NULL</code> or
 * <code>bufferSize</code> is less than
 * <code>@link kOSKextVersionMaxLength kOSKextVersionMaxLength@/link</code>.
 *
 * @discussion
 * The return value strictly indicates whether <code>buffer</code>
 * is large enough to hold the result.
 * If <code>aVersion</code> is 0, the resulting string is "(missing)".
 * If <code>aVersion</code> is less than 0
 * or is not a valid kext version encoding,
 * the resulting string is "(invalid)".
 */
Boolean OSKextVersionGetString(
	OSKextVersion   aVersion,
	char          * buffer,
	uint32_t        bufferSize);


#define KOSBundleDextUniqueIdentifierMaxLength (1024)

#ifdef KERNEL


#if PRAGMA_MARK
/********************************************************************/
#pragma mark -
#pragma mark Weak linking
/********************************************************************/
#endif
#ifdef XNU_KERNEL_PRIVATE
void kext_weak_symbol_referenced(void) __abortlike;
#endif /* XNU_KERNEL_PRIVATE */

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Miscellaneous Kernel-Only Kext Functions
/********************************************************************/
#endif

/*!
 * @function kext_get_vm_map
 * @abstract Returns the vm_map from which the kext was allocated.
 *
 * @param info The kmod_info_t structure of the kext.
 * @result The vm_map from which the kext was allocated.  This function
 * cannot return <code>NULL</code>.
 */
vm_map_t kext_get_vm_map(kmod_info_t * info);

#ifdef XNU_KERNEL_PRIVATE

#if CONFIG_DTRACE
/*!
 * @function OSKextRegisterKextsWithDTrace
 * @abstract
 * DTrace calls this once when it has started up so that the kext system
 * will register any already-loaded kexts with it.
 */
void OSKextRegisterKextsWithDTrace(void);

#endif /* CONFIG_DTRACE */

/*!
 * @function kext_dump_panic_lists
 * @abstract Prints compacted lists of last unloaded & all loaded kexts
 *           during a panic.
 *
 * @param printf_func The printf-style function to use for output.
 */
void kext_dump_panic_lists(int (*printf_func)(const char *fmt, ...));

#endif /* XNU_KERNEL_PRIVATE */

#ifdef XNU_KERNEL_PRIVATE

/*!
 * @define kOSKextReceiptQueried
 * @abstract Whether or not the kext receipt has been successfully loaded.
 */
#define kOSKextReceiptQueried  "OSKextReceiptQueried"

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Kext Loading C Functions
/********************************************************************/
#endif
/*!
 * @function OSKextGetLoadTagForBundleIdentifier
 * @abstract Look up the load tag for a kext.
 *
 * @param  kextIdentifier  The bundle identifier of the kext to look up.
 * @result
 * The load tag of the requested kext, or
 * <code>@link //apple_ref/c/macro/kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>
 * if the kext was not found.
 *
 * @discussion
 * A load tag uniquely identifies a loaded kext.
 * It can be found as the <code>id</code> field of a loaded kext's
 * <code>kmod_info_t</code> struct.
 *
 * Note that a load tag represents a specific loaded instance of a kext.
 * If that kext is unloaded, the load tag is no longer a valid reference.
 * If the same kext is later reloaded, it will have a new load tag.
 *
 * You can use the load tag to adjust a kext's reference count
 * via
 * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag
 * OSKextRetainKextWithLoadTag@/link</code>
 * and
 * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag
 * OSKextReleaseKextWithLoadTag@/link</code>,
 * so that the kext is automatically unloaded when no references remain,
 * or to unload the kext immediately
 * with <code>@link //apple_ref/c/func/OSKextUnloadKextWithLoadTag OSKextUnloadKextWithLoadTag@/link</code>.
 *
 * Those functions are intended for use with non-IOKit kexts
 * (specifically, kexts that define no subclasses of
 * <code>@link //apple_ref/doc/class/IOServiceIOService@/link</code>).
 * Pure IOKit kexts are managed via instance counts
 * of their libkern C++ object classes;
 * using those functions on them will only interfere with that mechanism.
 * If you have a hybrid kext with both IOService subclasses and non-IOKit code,
 * however, you may want to use reference counting for the non-IOKit portions:
 * that way the kext will only unload automaticaly
 * when there are no C++ objects and the kext reference count is zero.
 */
uint32_t OSKextGetLoadTagForBundleIdentifier(
	const char * kextIdentifier);


/*!
 * @function OSKextUnloadKextWithLoadTag
 * @abstract Stop and unload a kext based on its load tag.
 *
 * @param  loadTag   The load tag of the kext to unload.
 * @result
 * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code>
 * if the kext was found and unloaded.
 * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound
 * kOSKextReturnNotFound@/link</code>
 * if the kext was not found.
 * <code>@link //apple_ref/c/macro/kOSKextReturnInUse
 * kOSKextReturnInUse@/link</code>
 * if the kext has outstanding references
 * or if there are instances of its libkern C++ subclasses.
 * Other return values indicate a failure to unload the kext,
 * typically because the module stop routine failed.
 *
 * @discussion
 * A panic will occur if a kext calls this function to unload itself.
 * The safest way for a kext to unload itself is to call
 * <code>@link //apple_ref/c/func/OSKextRetainKextWithLoadTag
 * OSKextRetainKextWithLoadTag@/link</code>
 * with its own load tag
 * (the <code>id</code> field of its <code>kmod_info_t</code> struct),
 * followed by
 * <code>@link //apple_ref/c/func/OSKextReleaseKextWithLoadTag
 * OSKextReleaseKextWithLoadTag@/link</code>;
 * this will schedule the kext for unload on a separate thread.
 *
 * This function can be used when reference-based autounloading is not
 * appropriate.
 * If a kernel system or kext is already monitoring
 * the need for a kext,
 * it can simply call this function when it's known that the kext is not needed.
 */
OSReturn OSKextUnloadKextWithLoadTag(uint32_t loadTag);

#endif /* XNU_KERNEL_PRIVATE */

#endif /* KERNEL */

#if PRAGMA_MARK
#pragma mark -
/********************************************************************/
#pragma mark Loaded Kext Summary
/********************************************************************/
#endif

/*!
 * @define kOSKextLoadedKextSummaryVersion
 * @abstract The current version of the loaded kext summary headers.
 */
#define kOSKextLoadedKextSummaryVersion 2

/*!
 * @typedef OSKextLoadedKextSummary
 * @abstract A structure that describes a loaded kext.
 *
 * @field name The kext's bundle identifier.
 * @field uuid The kext's UUID;
 * @field address The kext's load address.
 * @field size The kext's load size.
 * @field version The binary format (OSKextVersion) version of the kext.
 * @field loadTag The kext's load tag.
 * @field flags Internal tracking flags.
 * @field reference_list who this refs (links on).
 * @field text_exec_address The address of the __TEXT_EXEC segment (if it exists), otherwise __TEXT
 * @field text_exec_size The size of the segment pointed to by text_address
 *
 * @discussion
 * The OSKextLoadedKextSummary structure contains a basic set of information
 * about the kext to facilitate kext debugging and panic debug log output.
 */
typedef struct _loaded_kext_summary {
	char        name[KMOD_MAX_NAME];
	uuid_t      uuid;
	uint64_t    address;
	uint64_t    size;
	uint64_t    version;
	uint32_t    loadTag;
	uint32_t    flags;
	uint64_t    reference_list;
	uint64_t    text_exec_address;
	size_t      text_exec_size;
} OSKextLoadedKextSummary;

/*!
 * @typedef OSKextLoadedKextSummaryHeader
 * @abstract A structure that describes the set of loaded kext summaries.
 *
 * @field version The version of the loaded kext summary structures.
 * @field entry_size The size of each entry in summaries.
 * @field numSummaries The number of OSKextLoadedKextSummary structures
 *        following the header.
 * @field summaries A convenience pointer to the array of summaries following
 *        the header.
 *
 * @discussion
 * The OSKextLoadedKextSummaryHeader describes the set of loaded kext summaries
 * available for use by the debugger or panic log routine.
 * The array of summaries contains one OSKextLoadedKextSummary for every kext
 * that declares an executable and is not an interface to the kernel.
 */
typedef struct _loaded_kext_summary_header {
	uint32_t version;
	uint32_t entry_size;
	uint32_t numSummaries;
	uint32_t reserved; /* explicit alignment for gdb  */
	OSKextLoadedKextSummary summaries[0];
} OSKextLoadedKextSummaryHeader;

/*!
 * @var gLoadedKextSummaries
 * @abstract The global pointer to the current set of loaded kext summaries.
 */
extern OSKextLoadedKextSummaryHeader * gLoadedKextSummaries;

/*!
 * @var gLoadedKextSummariesTimestamp
 *
 * @abstract This will be set to mach_absolute_time() around updates to
 * gLoadedKextSummaries.  Ie. immediately before gLoadedKextSummaries is set to
 * zero, and immediately after it is set to a new value.
 */
extern uint64_t gLoadedKextSummariesTimestamp;

/*!
 * @function OSKextLoadedKextSummariesUpdated
 * @abstract Called when gLoadedKextSummaries has been updated.
 *
 * @discussion
 * gLoadedKextSummaries is updated when a kext is loaded or unloaded.
 * When the update is complete, OSKextLoadedKextSummariesUpdated is called.
 * gdb can set a breakpoint on this function to detect kext loads and unloads.
 */
void OSKextLoadedKextSummariesUpdated(void);

#ifdef XNU_KERNEL_PRIVATE

extern const vm_allocation_site_t * OSKextGetAllocationSiteForCaller(uintptr_t address);
extern uint32_t                     OSKextGetKmodIDForSite(const vm_allocation_site_t * site,
    char * name, vm_size_t namelen);
extern void                         OSKextFreeSite(vm_allocation_site_t * site);

extern kern_return_t                OSKextSetReceiptQueried(void);

#if DEVELOPMENT || DEBUG
extern void                         OSKextGetRefGrpForCaller(uintptr_t address,
    void (^)(struct os_refgrp *));
#endif

#if CONFIG_IMAGEBOOT
extern int OSKextGetUUIDForName(const char *, uuid_t);
#endif

extern vm_tag_t gIOSurfaceTag;

extern void *OSKextKextForAddress(const void *addr);

#endif /* XNU_KERNEL_PRIVATE */

__END_DECLS

#endif /* ! _LIBKERN_OSKEXTLIBPRIVATE_H */