/* * Copyright (c) 2008 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 __OSKEXT_H__ #define __OSKEXT_H__ #include __BEGIN_DECLS #include //#include //#include //#include #include #include // xxx - should I use "Clear" everywhere I use "Flush" /*! * @header * @ignore CF_EXPORT * @ignore * * The OSKext library provides a comprehensive interface for creating, * examining, and loading kernel extensions (kexts). * * NOTICE: This library is neither thread-safe nor garbage-collection * safe. You must use your own locking with threads sharing access to OSKext. * You can not use this library in an application with garbage collection. */ #pragma mark Types and Constants /******************************************************************************* * Types and Constants *******************************************************************************/ /*! * @typedef OSKextRef * @abstract A reference to a kernel extension object. * * @discussion * The OSKextRef type refers to a KXKext object, which represents a kernel * extension bundle on disk, from an archive, or loaded into the kernel. * OSKext is an opaque type that defines the characteristics and behavior of * OSKext objects. * * The kernel counterpart of OSKext is the OSKext libkern C++ class. */ typedef struct __OSKext * OSKextRef ; #define kOSKextBundleExtension "kext" #define kOSKextMkextExtension "mkext" /*! * @typedef OSKextDiagnosticsFlags * @constant kOSKextDiagnosticsFlagAll * @constant kOSKextDiagnosticsFlagValidation * @constant kOSKextDiagnosticsFlagAuthentication * @constant kOSKextDiagnosticsFlagDependencies * @constant kOSKextDiagnosticsFlagWarnings */ enum { kOSKextDiagnosticsFlagNone = (UInt32) 0x0U, kOSKextDiagnosticsFlagValidation = (UInt32) 0x1U, kOSKextDiagnosticsFlagAuthentication = (UInt32) 0x2U, kOSKextDiagnosticsFlagDependencies = (UInt32) 0x4U, kOSKextDiagnosticsFlagWarnings = (UInt32) 0x8U, kOSKextDiagnosticsFlagAll = (UInt32)0xFFFFFFFFU, }; typedef UInt32 OSKextDiagnosticsFlags; typedef UInt64 OSKextLogFlags; typedef SInt64 OSKextVersion; typedef kern_return_t OSReturn; typedef uint8_t OSKextExcludeLevel; #define kOSKextExcludeNone (0) #define kOSKextExcludeKext (1) #define kOSKextExcludeAll (2) /* Top-level keys for diagnostics dicts. See @link OSKextCopyDiagnostics@/link. */ // xxx - not sure we need to include these, but it's convenient const CFStringRef kOSKextDiagnosticsValidationKey; const CFStringRef kOSKextDiagnosticsAuthenticationKey; const CFStringRef kOSKextDiagnosticsLinkLoadKey; const CFStringRef kOSKextDiagnosticsDependenciesKey; const CFStringRef kOSKextDiagnosticsWarningsKey; #pragma mark Basic CF Functions /********************************************************************* * Basic CF Functions *********************************************************************/ /*! * @function OSKextGetTypeID * @abstract Returns the type identifier for the OSKext opaque type. * * @result The type identifier for the OSKext opaque type. */ CF_EXPORT CFTypeID OSKextGetTypeID(void) ; #pragma mark Module Configuration /********************************************************************* * Module Configuration *********************************************************************/ /*! * @function OSKextSetArchitecture * @abstract Sets the architecture used for operations on kexts. * * @param anArch * An NXArchInfo pointer with cputype/subtype or name set. * Ownership remains with the caller. * Pass NULL to set the architecture to taht of the running kernel. * * @result * true if the architecture was set as desired, * false if anArch was not found; * if false, the architecture will now be that * of the running kernel. * xxx - should it just be left unchanged instead? * * @discussion * The kext library uses this architecture for any architecture-specific * operation, such as property lookups * (see @link OSKextGetValueForInfoDictionaryKey@/link), * dependency resolution, executable access during validation and linking. * The kext architecture is initially that of the running kernel (not of * the user-space process). * * This function looks up the system NXArchInfo struct * for the struct passed in, first using the cputype/subtype, and if that fails, * the name. You can therefore use this function to set the architecture * from an architecture name alone by passing an NXArchInfo struct * with the desired name, * but the cputype/subtype set to CPU_TYPE_ANY and CPU_SUBTYPE_ANY. * * Changing the kext architecture causes all kexts to flush their load info * and dependencies with @link OSKextFlushLoadInfo@/link. */ // xxx - should this also have a flushDependenciesFlag? CF_EXPORT Boolean OSKextSetArchitecture(const NXArchInfo * archInfo) ; /*! * @function OSKextGetArchitecture * @abstract Gets the architecutre used for operations on kexts. * * @result * The architecture used for operations on kexts. * The caller does not own the returned pointer and should not free it. * * @discussion * The kext library uses this architecture for any architecture-specific * operation, such as property lookups * (see @link OSKextGetValueForInfoDictionaryKey@/link), * dependency resolution, executable access during validation and linking. * The kext architecture is initially that of the running kernel (not of * the user-space process). */ CF_EXPORT const NXArchInfo * OSKextGetArchitecture(void) ; /*! * @function OSKextGetRunningKernelArchitecture * @abstract Returns the architecture of the running kernel. * * @result * The architecture of the running kernel. * The caller does not own the returned pointer and should not free it. * * @discussion * This function consults the kernel task and returns a pointer to the * NXArchInfo struct representing its architecture. * The running kernel's architecture does not necessarily match that * of user space tasks (for example, a 32-bit user space task could be * running with a 64-bit kernel, or vice-versa). */ CF_EXPORT const NXArchInfo * OSKextGetRunningKernelArchitecture(void) ; /*! @function OSKextGetLogFlags @param kext The kext to get the log flags. Pass NULL to get the global flag. */ CF_EXPORT OSKextLogFlags OSKextGetLogFlags(OSKextRef kext); /*! @function OSKextSetLogFlags */ CF_EXPORT void OSKextSetLogFlags(OSKextRef kext, OSKextLogFlags logFlags); /*! * @typedef OSKextLogFunction * @abstract * Prototype of a callback function used to log messages from the library. * * @param format A printf(3) style format string. * * @discussion * The default log function simply prints to stderrmsgLogSpec has any bits set. * If you set the log function to NULL, * no log messages will be printed. * * Log messages have no trailing newline, to accommodate system log facilities. */ /* xxx - no CF_EXPORT, compiler dies */ typedef void (*OSKextLogFunction)( OSKextLogFlags flags, const char * format, ...) ; /*! * @function OSKextSetLogFunction * @abstract Sets the function called to log messages. * * @param funct The log function to set. * * @discussion * The default log function simply prints to stderr. If you set the * log function to NULL, no log messages will be printed. * * Log messages have no trailing newline, to accommodate system log facilities. */ CF_EXPORT void OSKextSetLogFunction(OSKextLogFunction func) ; /*! * @function OSKextSetSimulatedSafeBoot * @abstract Sets whether safe boot mode is simulated in the library. * * @param flag true to simulate safe boot mode, * false to not simulate. * * @discussion * Kexts without a valid OSBundleRequired property are not allowed to load * by the kernel when the system has started in safe boot mode. * If you turn on simulated safe boot, the kext library can * catch non-loadable kexts and present appropriate diagnostics. */ CF_EXPORT void OSKextSetSimulatedSafeBoot(Boolean flag) ; /*! * @function OSKextGetSimulatedSafeBoot * @abstract Returns whether safe boot mode is simulated in the library. * * @result * true if safe boot mode is being simulated, * false if not. * * @discussion * Kexts without a valid OSBundleRequired property are not allowed to load * by the kernel when the system has started in safe boot mode. * When simulated safe boot is on, the kext library can * catch non-loadable kexts and present appropriate diagnostics. */ CF_EXPORT Boolean OSKextGetSimulatedSafeBoot(void) ; /*! * @function OSKextGetActualSafeBoot * @abstract Returns whether safe boot mode is active. * * @result * true if safe boot mode is active, * false if not. * * @discussion * Kexts without a valid OSBundleRequired property are not allowed to load * by the kernel when the system has started in safe boot mode. * The kext library ignores actual safe boot mode, leaving decisions * regarding safe boot to the kernel. * If you want to analyze kexts in safe boot mode using the library, * call @link OSKextSetSimulatedSafeBoot@/link. */ // xxx - we used to disallow kexts w/debug-log flags in safe boot, too CF_EXPORT Boolean OSKextGetActualSafeBoot(void) ; /*! * @function OSKextGetSystemExtensionsFolderURLs * @abstract Returns the standard system extension folder URLs. * * @result * An array containing the standard system extension folder URLs. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * To open all the kexts normally considered for loading by the system, * pass the return value of this function to * @link OSKextCreateKextsFromURLs@/link. */ CF_EXPORT CFArrayRef OSKextGetSystemExtensionsFolderURLs(void) ; /*! * @function OSKextSetRecordsDiagnostics * @abstract Sets whether kexts record diagnostic information. * * @param flags Indicates which diagnostics to record. * * @discussion * The kext library can record diagnostic information for kexts as * problems are encountered. These diagnostics can consume a fair * amount of memory, and should be generated only when desired. * Recording of diagnostics is set to * @link kOSKextDiagnosticsFlagNone@/link by default. * Use this function to turn diagnostics recording off (or back on) * for particular diagnostic types. * * Turning on diagnostics does not calculate or recalculate * diagnostics. Call the various functions that operate on kexts * to begin accumulating diagnostics. * * Turning diagnostics off does not clear any existing diagnostics. * Use @link OSKextFlushDiagnostics@/link explicitly to clear * any diagnostics currently stored. * * See also @link OSKextCopyDiagnostics@/link, * @link OSKextValidate@/link, * @link OSKextAuthenticate@/link, and * @link OSKextResolveDependencies@/link. */ // Could list a pile of see also's here.... CF_EXPORT void OSKextSetRecordsDiagnostics(OSKextDiagnosticsFlags flags) ; /*! * @function OSKextGetRecordsDiagnostics * @abstract * Returns what kinds of diagnostic information kexts record. * * @result * Flags indicating which types of diagnostics are currently * being recorded. You can bitwise-OR or -AND these with other flags * to add or remove diagnostics being recorded with * @link OSKextSetRecordsDiagnostics@/link. */ CF_EXPORT OSKextDiagnosticsFlags OSKextGetRecordsDiagnostics(void) ; /*! * @function OSKextSetUsesCaches * @abstract Sets whether the kext library uses cache files. * * @param flag * true to use caches, * false to not use caches. * * @discussion * The kext library normally uses caches to speed up reading kexts from * the system extensions folders. * Use this function to turn off use of caches; this will cause reading * of kexts to be dramatically slower. * * See also @link OSKextGetUsesCaches@/link. */ CF_EXPORT void OSKextSetUsesCaches(Boolean flag) ; /*! * @function OSKextGetUsesCaches * @abstract * Returns whether the OSKext library uses cache files. * * @result * true if the library uses caches to speed up reading of kexts, * false if it doesn't. * * @discussion * The kext library normally uses caches to speed up reading kexts from * the system extensions folders. * Use this function to check whether the library is using caches. * * See also @link OSKextGetUsesCaches@/link. */ CF_EXPORT Boolean OSKextGetUsesCaches(void) ; #pragma mark Instance Management /********************************************************************* * Instance Management *********************************************************************/ /*! * @function OSKextCreate * @abstract Read a single kext from an on-disk bundle, without plugins. * * @param allocator * The allocator to use to allocate memory for the new object. * Pass NULL or kCFAllocatorDefault * to use the current default allocator. * @param anURL * The location of the bundle for which to create an OSKext object. * @result * An OSKext object created from the bundle at anURL. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * Returns NULL if there was a memory allocation problem or * if the bundle doesn't exist at anURL (see Discussion). * May return an existing OSKext object with the reference count incremented. * * @discussion * Once a kext has been created, it is cached in memory; the kext bundle cache * is flushed only periodically. OSKextCreate does not check that a cached kext * bundle still exists in the filesystem. If a kext bundle is deleted * from the filesystem, it is therefore possible for OSKextCreate * to return a cached bundle that has actually been deleted. * * OSKext uses a CFBundle briefly during initialization, but in order * to save memory and allow re-reading of kext bundle contents * from disk, does not retain it. Applications can save further memory * by flushing info dictionaries so that they are read from disk again * when needed; see @link OSKextFlushInfoDictionary@/link. */ CF_EXPORT OSKextRef OSKextCreate( CFAllocatorRef allocator, CFURLRef anURL) ; /*! * @function OSKextCreateKextsFromURL * @abstract Reads all kexts at an on-disk URL along with their plugins. * * @param allocator * The allocator to use to allocate memory for the new objects. * Pass NULL or kCFAllocatorDefault * to use the current default allocator. * @param anURL The URL to scan for kernel extensions. * @result * Returns an array containing the kext objects created, * or NULL on failure. * * @discussion * This function scans anURL for kexts. * If anURL represents a kext, * this function reads that kext and its plugins. * If anURL represents a non-kext directory, * this functions scans the directory's immediate contents for kext bundles * and their plugins. It does not scan recursively; only plugins one level * deep are read. * * If given an URL for a kext that is a plugin of another kext, this * function does not scan for further plugins. * * This function does not scan for or read mkext files. Use * @link OSKextCreateKextsFromMkextFile@/link to read an mkext file. * * See @link OSKextCreate OSKextCreate @/link for information * about kext object caching. */ CFArrayRef OSKextCreateKextsFromURL( CFAllocatorRef allocator, CFURLRef anURL) ; /*! * @function OSKextCreateKextsFromURLs * @abstract Reads all kexts at an array on-disk URLs along with their plugins. * * @param allocator * The allocator to use to allocate memory for the new objects. * Pass NULL or kCFAllocatorDefault * to use the current default allocator. * @param arrayOfURLs The URLs to scan for kernel extensions. * @result * Returns an array containing the kext objects created, * or NULL on failure. * * @discussion * This function scans each URL in arrayOfURLs for kexts. * If a given URL represents a kext, * this function reads that kext and its plugins. * If the URL represents a non-kext directory, this functions scans the * directory's immediate contents for kext bundles and their plugins. * It does not scan recursively; only plugins one level deep are read. * * If given an URL for a kext that is a plugin of another kext, this * function does not scan for further plugins. * * This function does not scan for or read mkext files. Use * @link OSKextCreateKextsFromMkextFile@/link to read an mkext file. * * See @link OSKextCreate@/link for discussion about kext object caching. */ CF_EXPORT CFArrayRef OSKextCreateKextsFromURLs( CFAllocatorRef allocator, CFArrayRef arrayOfURLs) ; /*! * @function OSKextGetAllKexts * @abstract * Returns an array containing all of the kexts currently open in the application. * * @result * A CFArray object containing OSKext objects for each open kext * in the application. Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * This function is potentially expensive, so use with care. */ CF_EXPORT CFArrayRef OSKextGetAllKexts(void) ; /*! @function OSKextCopyKextsWithIdentifier */ CF_EXPORT CFArrayRef OSKextCopyKextsWithIdentifier(CFStringRef bundleID); /*! @function OSKextGetKextsWithIdentifiers @discussion Follows Create Rule. */ CF_EXPORT CFArrayRef OSKextGetKextsWithIdentifiers(CFArrayRef bundleIDs); /*! * @function OSKextGetKextWithIdentifierAndVersion * @abstract * Locate a kext given its program-defined identifier and version. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @param aVersion * The version of the kext to locate. * @result * An OSKext object, or NULL if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * For a kext to be located using its identifier and version, * the kext object must have already been created. * See @link OSKextGetKextWithIdentifierAndVersion@/link for more. */ // xxx - check on same-version ordering with folks CF_EXPORT OSKextRef OSKextGetKextWithIdentifierAndVersion( CFStringRef aBundleID, OSKextVersion aVersion) ; /*! * @function OSKextGetKextsWithIdentifier * @abstract Locate all kexts with a given program-defined identifier. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @result * An CFArray of kext objects with the given identifier, * or NULL on error. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * @discussion * This function is useful for locating duplicates of a given kext. * * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT CFArrayRef OSKextCopyKextsWithIdentifier( CFStringRef aBundleID) ; /*! * @function OSKextGetLoadedKextWithIdentifier * @abstract * Locate the loaded kext with a given program-defined identifier. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @result * An OSKext object, or NULL if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link before calling this * function for it to find anything. * * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT OSKextRef OSKextGetLoadedKextWithIdentifier( CFStringRef aBundleID) ; /*! * @function OSKextGetCompatibleKextWithIdentifier * @abstract * Locate the kext with a given program-defined identifier * that is compatible with a requested version. * * @param aBundleID * The identifier of the kext to locate. * Note that identifier names are case-sensitive. * @param requestedVersion * The version that the kext must be compatible with. * @result * An OSKext object, or NULL if the kext was not found. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * A kext is compatible with a version if that version lies between * its CFBundleVersion and its OSBundleCompatibleVersion (inclusive). * * See @link OSKextGetKextWithIdentifier@/link for general information * on looking up kexts by identifier. */ CF_EXPORT OSKextRef OSKextGetCompatibleKextWithIdentifier( CFStringRef aBundleID, OSKextVersion requestedVersion) ; #pragma mark Basic Accessors /********************************************************************* * Basic Accessors *********************************************************************/ /*! * @function OSKextGetURL * @abstract Returns the CFURL of a kext bundle. * * @param aKext The kext to get the URL for. * @result A CFURL object. Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * This function returns the CFURL that aKext * was originally created with. * It should be resolved to its base for comparison with other kext * URLs. */ CF_EXPORT CFURLRef OSKextGetURL(OSKextRef aKext) ; // always absolute /*! * @function OSKextGetIdentifier * @abstract Returns the bundle identifier from a kext's information property list. * * @param aKext The kext to get the identifier for. * @result * A CFString object containing the kext bundle's identifier, * or NULL if none was specified in the information property list. * Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. */ CF_EXPORT CFStringRef OSKextGetIdentifier(OSKextRef aKext) ; /*! * @function OSKextGetValueForInfoDictionaryKey * @abstract * Returns a (possibly architecture-specific) value * in a kext's information dictionary. * * @param aKext The kext to get the property for. * @param key The base key identifying the property. * @result * A value corresponding to key in aKext's * information dictionary. * If available, an architecture-specific value is returned, * otherwise the global value is returned. Ownership follows the * @link //apple_ref/doc/uid/20001148-SW1 Get Rule@/link. * * @discussion * This function first looks for a property value specific to the current kext * architecture, as set with @link OSKextSetArchitecture@/link, * by appending an underscore plus the architecture name to the base key. * If such a value is not found, it looks for the property using the base key. * For example, if the currently set architecture is i386, and * IOKitPersonalities is requested, this function looks up the key * IOKitPersonalities_i386; if that doesn't exist, then it uses * IOKitPersonalities. * * Some properties are not allowed to be made architecture-specific; * if such keys are defined, they are ignored by this function: * * * CFBundleIdentifier * * CFBundleVersion * * CFBundleExecutable * * OSBundleIsInterface * * OSKernelResource * * This function looks up architecture-specific values for generic bundle * properties, such as CFBundlePackageType, but such values are of course * ignored by CFBundle. * * If you want to look up a property with a raw key, get the information * dictionary directly using @link OSKextCopyInfoDictionary@/link or * by opening a CFBundle for the kext's URL. * * This function reads the info dictionary from disk if necessary. * See @link OSKextFlushInfoDictionary@/link. */ CF_EXPORT CFTypeRef OSKextGetValueForInfoDictionaryKey( OSKextRef aKext, CFStringRef key) ; /*! * @function OSKextCopyInfoDictionary * @abstract Returns a copy of a kext's information dictionary. * * @param aKext The kext to get the information dictionary for. * @result * A CFDictionary object containing the data stored in the kext's * information property list. * OSKext may add extra keys to this dictionary for its own use. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * @discussion * This function uses @link IOCFUnserialize@/link to parse the XML * of the info dictionary, in order to match the parsing used in the kernel. */ CF_EXPORT CFMutableDictionaryRef OSKextCopyInfoDictionary(OSKextRef aKext) ; /*! * @function OSKextFlushInfoDictionary * @abstract Releases a kext's info dictionary. * * @param aKext The kext that should release its info dictionary. * If NULL, all open kexts' info dictionaries * are flushed. * * @discussion * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * Flushing info dictionaries also allows kext objects to synchronize * with updates on disk; they will automatically re-sort in the * internal lookup tables to reflect changed versions, for example. * (xxx - well they will! that's not fully implemented yet) * * See also @link OSKextFlushDependencies@/link, * @link OSKextFlushLoadInfo@/link, * and @link OSKextFlushDiagnostics@/link. * * Kext objects created from an mkext cannot flush their info * dictionaries. */ CF_EXPORT void OSKextFlushInfoDictionary(OSKextRef aKext) ; /*! * @function OSKextGetVersion * @abstract Returns the version of a kext. * * @param aKext The kext to get the version for. * @result The version of the kext as a 64-bit integer. * * @discussion * xxx - needs more info on version format * xxx - need to fix definition of OSKextVersion. */ CF_EXPORT OSKextVersion OSKextGetVersion(OSKextRef aKext) ; /*! * @function OSKextGetCompatibleVersion * @abstract Returns the compatible version of a kext * * @param aKext The kext to get the compatible version for. * @result The compatible version of the kext as a 64-bit integer. * * @discussion * This function returns the value of a kext's OSBundleCompatibleVersion * property, parsed into a 64-bit integer that can be compared using * standard integer comparison operators. * * xxx - needs more info on version format, ref to tn: http://developer.apple.com/technotes/tn/tn1132.html */ CF_EXPORT OSKextVersion OSKextGetCompatibleVersion(OSKextRef aKext) ; /*! * @function OSKextCopyUUIDForArchitecture * @abstract * Returns the compiler-generated UUID of a kext for a given architecture. * * @param aKext The kext to get the UUID for. * @param anArch The architecture desired. * Pass NULL to get the UUID for the * current architecture. * @result * A CFData object containing the UUID of the kext's executable * for anArch, or the currently set architecture if * anArch is NULL. * * @discussion * UUIDs are used in addition to bundle versions to check the identify of * kexts loaded in the kernel. */ CF_EXPORT CFDataRef OSKextCopyUUIDForArchitecture(OSKextRef aKext, const NXArchInfo * anArch) ; /*! * @function OSKextIsKernelComponent * @abstract Returns whether a kext represents a kerne programming interface. * * @param aKext The kext to examine. * @result * true if aKext represents * a kerne programming interface, false otherwise. * * @discussion * A small set of kexts represent interfaces built into the kernel that can * be linked against individually. These are commonly known as * kernel programming interfaces (KPIs), * and the kexts containing them as "pseudokexts". * * If a kext is a kernel component, then it is also always an interface * (see @link OSKextIsInterface@/link). */ CF_EXPORT Boolean OSKextIsKernelComponent(OSKextRef aKext) ; /*! * @function OSKextIsInterface * @abstract * Returns whether a kext acts as a linkage subset for another kext, * also known as a symbol set. * * @param aKext The kext to examine. * @result * true if aKext is an interface kext, * false otherwise. * * @discussion * An interface kext has no actual code in its executable, but merely * re-exports a set of symbols (typically a subset) * from those of its dependencies. * * Currently the only interface kexts are the kernel component kexts * the define the kernel programming interfaces for Mac OS X. */ CF_EXPORT Boolean OSKextIsInterface(OSKextRef aKext) ; /*! * @function OSKextIsLibrary * @abstract Returns whether a kext can be declared as a library. * * @param aKext The kext to examine. * @result * true if aKext is a library kext, false * otherwise. * * @discussion * A kext is a library kext if it has a valid OSBundleCompatibleVersion * property. Another kext can link against a library kext by listing * the library's identifier and required version in its OSBundleLibraries * property. */ CF_EXPORT Boolean OSKextIsLibrary(OSKextRef aKext) ; /*! * @function OSKextDeclaresExecutable * @abstract Returns whether a kext declares a CFBundleExecutable property. * * @param aKext The kext to examine. * @result * true if aKext has a nonempty CFBundleExecutable * property, false otherwise. * * @discussion * A kext with an executable is either a loadable kext with actual executable * code, or an interface kext whose executable serves to restrict linkage * to a subset of the symbols of another kext. See @link OSKextIsInterface@/link * for more on the latter type. */ CF_EXPORT Boolean OSKextDeclaresExecutable(OSKextRef aKext) ; /*! * @function OSKextHasLogOrDebugFlags * @abstract * Returns whether a kext has OSBundleEnableKextLogging set to a true value or * any of its IOKitPersonalities has a nonzero IOKitDebug property. * * @param aKext The kext to examine. * @result * true if aKext has a true OSBundleEnableKextLogging * property or if any personality for the currently set architecture has a * nonzero IOKitDebug property, false otherwise. * * @discussion * Kexts built for distribution should not have any logging or debug flags set. */ CF_EXPORT Boolean OSKextHasLogOrDebugFlags(OSKextRef aKext) ; /*! * @function OSKextIsLoadableInSafeBoot * @abstract Returns whether the kernel will load a kext during safe boot. * * @param aKext The kext to examine. * @result * true if the kernel will allow aKext during * safe boot, false otherwise. * * @discussion * A kext is loadable during safe boot if it has an OSBundleRequired * property for the kernel's architecture with a value of * "Root", "Local-Root", "Network-Root", "Console", or "Safe Boot". * * This function does not generally cover the issue of loadability due * to problems with validation, authentication, or dependency resolution. * To determine whether a kext can actually be loaded, use * @link OSKextIsLoadable@/link. */ CF_EXPORT Boolean OSKextIsLoadableInSafeBoot(OSKextRef aKext) ; /*! * @function OSKextCopyArchitectures * @abstract * Returns a list of NXArchInfo structs for the architectures * found in a kext's executable. * * @param aKext The kext to examine. * @result * A NULL-terminated list of NXArchInfo * struct pointers describing * the architectures supported by aKext, * or NULL if aKext has no executable. * The caller is responsible for freeing the list, but not the individual * NXArchInfo pointers. */ CF_EXPORT const NXArchInfo ** OSKextCopyArchitectures(OSKextRef aKext) ; /*! * @function OSKextSupportsArchitecture * @abstract Returns whether a kext has an executable for a given architecture. * * @param aKext The kext to examine. * @param anArch The NXArchInfo description to check. * If NULL, uses the currently set architecture. * @result * true if aKext's executable contains code for * anArch. * * @discussion */ // null for current (NOT host) arch Boolean OSKextSupportsArchitecture(OSKextRef aKext, const NXArchInfo * anArch) ; // if NULL, uses current default /*! * @function OSKextCopyPlugins * @abstract Retrieve the plugins of a kext. * * @param aKext The kext to get plugins for. * @result * An array containing the kexts that are plugins of aKext. * * @discussion * This function scans the plugins folder of aKext * and returns an array of the kexts found. * This may result in the creation of new kext objects. * * If aKext is a plugin of another kext * see @link OSKextIsPlugin@/link), * this function returns an empty array. */ CF_EXPORT CFArrayRef OSKextCopyPlugins(OSKextRef aKext) ; /*! * @function OSKextIsPlugin * @abstract Returns whether a kext is a plugin of some other kext. * * @param aKext The kext to examine. * @result * true if aKext is a plugin of another kext, * false otherwise. * * @discussion * This function uses a simple algorithm that just checks for the substring * ".kext/" in the absolute path leading up to the kext's bundle name. */ CF_EXPORT Boolean OSKextIsPlugin(OSKextRef aKext) ; /*! * @function OSKextCopyContainerForPluginKext * @abstract Returns the kext that is the container for a plugin kext. * * @param aKext The kext to find a parent for. * @result * The kext that contains aKext in its PlugIns folder, * or NULL if aKext is not a plugin. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * * @discussion * This function creates a kext object for the longest portion of the * path leading to aKext, then checks to see whether * aKext is a plugin of that kext by CFBundle's * semantics. If so, that kext is returned. * This may result in the creation of a new kext. */ CF_EXPORT OSKextRef OSKextCopyContainerForPluginKext(OSKextRef aKext) ; /*! * @function OSKextCopyPersonalitiesArray * @abstract Returns the personalities of a kext for the current kext architecture. * * @param aKext The kext to retrieve personalities for. * @result An array of IOKit personality dictionaries. * * @discussion * IOKitPersonalities in kexts require some processing before being sent * to the kernel, and the functions that send personalities expect an array * rather than a dictionary. This function facilitates such use. * * Use @link OSKextGetValueForInfoDictionaryKey@/link to retrieve the raw * personalities dictionary for the current architecture. */ CF_EXPORT CFArrayRef OSKextCopyPersonalitiesArray(OSKextRef aKext) ; // xxx - would it be awful to have a function that takes a CFTypeRef that's // xxx - a single kext, an array of kexts, or NULL for all open kexts? /*! * @function OSKextCopyPersonalitiesOfKexts * @abstract * Returns the personalities of multiple kexts for the current kext architecture. * * @param kextArray The kexts to retrieve personalities for. * Pass NULL to retrieve personalities for all open kexts. * @result An array of IOKit personality dictionaries. * * @discussion * IOKitPersonalities in kexts require some processing before being sent * to the kernel, and the functions that send personalities expect an array * rather than a dictionary. This function facilitates such use. */ CF_EXPORT CFArrayRef OSKextCopyPersonalitiesOfKexts(CFArrayRef kextArray) ; /*! * @function OSKextCopyExecutableForArchitecture * @abstract * Returns a kext's Mach-O executable, thinned to a single architecture * if desired. * * @param aKext The kext to retrieve the executable from. * @param anArch The architecture desired. * Pass NULL to get the whole, unthinned exectuable. * @result * A CFData object containing the code * for the specified architecture, or NULL if it can't be found. * * @discussion * Note that this function does not use the default kext architecture set by * @link OSKextSetArchitecture@/link when given no architecture. */ CF_EXPORT CFDataRef OSKextCopyExecutableForArchitecture(OSKextRef aKext, const NXArchInfo * anArch) ; /*! * @function OSKextCopyResource * @abstract Returns a named resource from a kext's bundle. * * @param aKext The kext to get a resource from. * @param resourceName The name of the requested resource. * @param resourceType The abstract type of the requested resource. * The type is expressed as a filename extension, * such as jpg. * Pass NULL if you don’t need * to search by type. * * @result * A CFData object containing the resource file's contents, * or NULL if the resource can't be found. * * @discussion * For a kext created from an on-disk URL, this function uses CFBundle * semantics to locate the resource file. Note that localized resources * and resource subdirectories are not available to kexts calling * @link //apple_ref/c/func/OSKextRequestResource OSKextRequestResource@/link * from within the kernel (because the process providing them runs as root). * You can store such resources in a kext bundle and use them in applications, * but they will not be available to the kext loaded in kernel. */ CF_EXPORT CFDataRef OSKextCopyResource( OSKextRef aKext, CFStringRef resourceName, CFStringRef resourceType) ; #pragma mark Dependency Resolution /********************************************************************* * Dependency Resolution *********************************************************************/ /*! * @function OSKextResolveDependencies * @abstract Calculate the dependency graph for a kext. * * @param aKext The kext to resolve dependencies for. * @result * true if all dependencies are successfully resolved, * false otherwise. * * @discussion * This function examines the OSBundleLibraries property of aKext * and looks for compatible open kexts. Priority is given to kexts marked as * loaded (see @link OSKextReadLoadedKextInfo@/link and * @link OSKextFlushLoadInfo@/link). Otherwise the most recent * compatible version is used; if multiple kexts with the same identifier and * version exist, the last one created is used. * * Any problems resolving dependencies are stored in a diagnostics dictionary, * which you can retrieve using @link OSKextCopyDiagnostics@/link. * * If a kext's dependencies have already been resolved, this function does * no work and returns true. * If you want to recalculate a kext's dependencies, call * @link OSKextFlushDependencies@/link first. */ // xxx - check on same-version ordering with folks CF_EXPORT Boolean OSKextResolveDependencies(OSKextRef aKext) ; /*! * @function OSKextFlushDependencies * @abstract Clears the dependency graph of a kext. * * @param aKext The kext to flush dependencies for. * Pass NULL to flush dependencies for all kexts. * * @discussion * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * Flushing dependencies is also useful when readling loaded kext * information from the kernel with @link OSKextReadLoadedKextInfo@/link * (in fact, that function takes a flag to do it as part of its work). * Dependency resolution gives priority to kexts marked as loaded, * so it's wise to call flush dependencies before reading load info * and before doing any operation that resolves dependencies. * Conversely, if you want to resolve dependencies without consideration * for which kexts are loaded, call @link OSKextFlushLoadInfo@/link * beforehand (with or without the flag to flush dependencies). * * This function also clears any dependency resolution diagnostics. * See also @link OSKextFlushInfoDictionary@/link, * @link OSKextFlushLoadInfo@/link, * and @link OSKextFlushDiagnostics@/link. */ CF_EXPORT void OSKextFlushDependencies(OSKextRef aKext) ; /*! * @function OSKextCopyDeclaredDependencies * @abstract Returns the kexts identified in a kext's OSBundleLibraries property. * * @param aKext The kext to get dependencies for. * @param needAllFlag If true, the function returns * NULL if any dependency isn't found. * @result * A CFArray containing the kexts found. * If needAllFlag is false, the array may be missing * some kexts. If needAllFlag is true and not all * dependencies are found, this function returns NULL. * * @discussion * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFArrayRef OSKextCopyDeclaredDependencies( OSKextRef aKext, Boolean needAllFlag) ; /*! * @function OSKextCopyLinkDependencies * @abstract Returns the kexts that a kext links directly against. * * @param aKext The kext to get dependencies for. * @param needAllFlag If true, the function returns * NULL if any dependency isn't found. * @result * A CFArray containing the kexts found. * If needAllFlag is false, the array may be missing * some kexts. If needAllFlag is true and not all * dependencies are found, this function returns NULL. * * @discussion * Link dependencies are how loaded kext relationships are tracked * in the kernel (as shown by the kextstat(8) program). * Some library kexts contain no executable, merely collecting sets of * other libraries for convenience or compatiblity purposes. * This function follows through such indirect libraries to find kexts * with executables that aKext will actually link against. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ // xxx - need to insert a manpage link on kextstat CF_EXPORT CFArrayRef OSKextCopyLinkDependencies( OSKextRef aKext, Boolean needAllFlag) ; /*! * @function OSKextCopyLoadList * @abstract * Returns the entire list of kexts in the load graph of a kext * (including that kext). * * @param aKext The kext to get the load list for. * @param needAllFlag If true, the function returns * NULL if any dependency isn't found. * @result * A CFArray containing the kexts found. * If needAllFlag is false, the array may be missing * some kexts. If needAllFlag is true and not all * dependencies are found, this function returns NULL. * * @discussion * The fully-resolved load list represents all the kexts needed to load * aKext into the kernel, in an order guaranteed to work for * sequential starting and matching with IOKit personalities. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFMutableArrayRef OSKextCopyLoadList( OSKextRef aKext, Boolean needAllFlag) ; /*! * @function OSKextCopyLoadListForKexts * @abstract * Returns the entire list of kexts in load order of the merged load graph * of the provided list of kexts (including those kexts). * * @param kexts The kexts to get the load list for. * @param needAllFlag If true, the function returns * NULL if any dependency isn't found. * * @result * A CFArray containing the kexts found. * If needAllFlag is false, the array may be missing * some kexts. If needAllFlag is true and not all * dependencies are found, this function returns NULL. * * @discussion * The fully-resolved load list represents all of the kexts needed to load * every kext in kexts into the kernel, in an order guaranteed to * work for sequential starting and matching with IOKit personalities. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFMutableArrayRef OSKextCopyLoadListForKexts( CFArrayRef kexts, Boolean needAllFlag) ; /*! * @function OSKextCopyAllDependencies * @abstract * Returns all kexts that a given kexts depends on, directly or indirectly. * * @param aKext The kext to get dependencies for. * @param needAllFlag If true, the function returns * NULL if any dependency isn't found. * @result * A CFArray containing the kexts found. * If needAllFlag is false, the array may be missing * some kexts. If needAllFlag is true and not all * dependencies are found, this function returns NULL. * * @discussion * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFMutableArrayRef OSKextCopyAllDependencies( OSKextRef aKext, Boolean needAllFlag) ; /*! * @function OSKextCopyIndirectDependencies * @abstract * Returns all kexts that a given kexts depends on indirectly. * * @param aKext The kext to get dependencies for. * @param needAllFlag If true, the function returns * NULL if any dependency isn't found. * @result * A CFArray containing the kexts found. * If needAllFlag is false, the array may be missing * some kexts. If needAllFlag is true and not all * dependencies are found, this function returns NULL. * * @discussion * Note that the list of indirect dependencies includes all kexts declared * as dependencies by the direct dependencies of aKext - * it may therefore include a direct dependency as well if some other * kext in the load graph declares it. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ // xxx - This one isn't really useful, is it? CFMutableArrayRef OSKextCopyIndirectDependencies( OSKextRef aKext, Boolean needAllFlag) ; /*! * @function OSKextDependsOnKext * @abstract * Returns whether a kext depends on a given library kext, * directly or indirectly. * * @param aKext The kext to examine. * @param libraryKext The possible library kext. * @param directFlag * If true, only checks for a direct declared dependency; * if false check for direct or indirect dependencies. * @result * true if aKext depends on libraryKext, * either directly or indirectly per directFlag. * Returns false otherwise. * * @discussion * This function calls @link OSKextResolveDependencies@/link to find * dependencies. * * This function works with actual dependency resolution, not potential. * If there are multiple kexts with the same bundle identifier, * aKext may not be the one chosen during resolution * and so it might appear that no kexts depend on it, even though they could. */ CF_EXPORT Boolean OSKextDependsOnKext( OSKextRef aKext, OSKextRef libraryKext, Boolean directFlag) ; /*! * @function OSKextCopyDependents * @abstract * Return all kexts that depend on a given kext, directly or indirectly. * * @param aKext The kext to get dependents for. * @param directFlag * true to get only kexts that declare a direct * dependency on aKext, * false to get all dependents, direct or indirect. * @result * An array of all kexts that ultimately depend on aKext, * directly or indirectly according to directFlag. * * @discussion * This function calls @link OSKextResolveDependencies@/link on all open * kexts to find dependencies. This can be somewhat expensive. * * This function works with actual dependency resolution, not potential. * If there are multiple kexts with the same bundle identifier, * aKext may not be the one chosen during resolution * and so it might appear that no kexts depend on it, even though they could. */ CF_EXPORT CFMutableArrayRef OSKextCopyDependents(OSKextRef aKext, Boolean directFlag) ; /*! * @function OSKextIsCompatibleWithVersion * @abstract Returns whether a library kext is compatible with a given version. * * @param aKext The kext to examine. * @param aVersion The kext version to check compatibility with * * @result * truer if aKext has a compatible version and * if aVersion is between the version and compatible version of * aKext (inclusive), false otherwise. * * @discussion */ CF_EXPORT Boolean OSKextIsCompatibleWithVersion( OSKextRef aKext, OSKextVersion aVersion) ; /*! * @function OSKextLogDependencyGraph * @abstract Prints the resolved dependency graph of a kext. * * @param aKext The kext to log the dependency graph of. * @param bundleIDFlag true to log kexts by bundle ID, * false to log them by URL. * @param linkFlag true to log the link graph only, * false to log the full dependency graph. * * @discussion * linkFlag allows you to display the dependencies as they will * be recorded in the kernel when the kext is loaded. * If it is true, then only kexts with executables are included * in the logged dependency graph. If it is false, all kexts * needed to load aKext are included. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT void OSKextLogDependencyGraph(OSKextRef aKext, Boolean bundleIDFlag, Boolean linkFlag) ; /*! * @function OSKextFindLinkDependencies * @abstract Finds kexts that define symbols a kext needs resolved. * * @param aKext The kext to examine. * @param nonKPIFlag * false to look in com.apple.kpi.* kernel component * for kernel symbols; * true to look in com.apple.kernel.* kernel components * instead (not recommended for later versions of Mac OS X). * @param allowUnsupportedFlag * false to skip unsupported libraries in the search; * true to include them. * @param onedefSymbolsOut * A dictionary containing symbols that were found once; * keys are the symbols, values are the kexts defining the key symbol. * Ownership follows the Create Rule. * Pass NULL to not retrieve. * @param undefinedSymbolsOut * A dictionary containing symbols that weren't found; * keys are the symbols, values are undefined. * Ownership follows the Create Rule. * Pass NULL to not retrieve. * @param multiplyDefinedSymbolsOut * A dictionary containing symbols found in multiple library kexts; * keys are the symbols, values are the kexts defining the key symbol. * Ownership follows the Create Rule. * Pass NULL to not retrieve. * @param multipleDefinitionLibraries * A array of all library kexts in which multiply defined symbols * were found; sorted by CFBundleIdentifier. * Ownership follows the Create Rule. * Pass NULL to not retrieve. * @result * An array of kexts that export symbols referenced by aKext, * sorted by CFBundleIdentifier. * * @discussion * This function searches in all open kexts for symbols referenced by * aKext, ignoring the OSBundleLibraries property. * You can use this function to find out what you should list * in a kext's OSBundleLibraries property. * * If undefinedSymbolsOut has a nonzero count, * the symbols named by its keys could not be found in any open kext. * * If multiplyDefinedSymbolsOut has a nonzero count, * some of the result kexts define the same symbol, * and if those duplicates are listed * in OSBundleLibraries a link failure will occur. * You can inspect the contents of multiplyDefinedSymbolsOut * and multipleDefinitionLibraries * by hand to sort out which libraries you should actually declare. * * This function is fairly expensive, as it has to search through all open * kexts' information dictionaries, and all library kexts' executables. */ CFArrayRef OSKextFindLinkDependencies( OSKextRef aKext, Boolean nonKPIFlag, Boolean allowUnsupportedFlag, CFDictionaryRef * undefinedSymbolsOut, CFDictionaryRef * onedefSymbolsOut, CFDictionaryRef * multiplyDefinedSymbolsOut, CFArrayRef * multipleDefinitionLibrariesOut) ; #pragma mark Linking and Loading; Other Kernel Operations /********************************************************************* * Linking and Loading; Other Kernel Operations *********************************************************************/ /*! * @function OSKextLoad * @abstract Loads a kext and its dependencies into the kernel. * * @param aKext The kext to load. * @result * kOSReturnSuccess if aKext is successfully loaded * into the kernel, or was already loaded, or an error result if not. * * @discussion * The calling process must have an effective user ID of 0 (root) * to load kexts into the kernel. * * A kext and all its dependencies must pass all validation and authentication * tests to be loadable. See @link OSKextIsLoadable@/link for more information. * * All kexts loaded into the kernel are started, but IOKit personalities * are not sent to the IOCatalogue. * See @link OSKextSendPersonalitiesToKernel@/link. * * This function calls @link OSKextFlushLoadInfo@/link and clears dependencies * for all open kexts. It then calls @link OSKextCopyLoadList@/link * to find dependencies and @link OSKextReadLoadedKextInfo@/link on the * resulting load list. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextLoad(OSKextRef aKext) ; /*! * @function OSKextLoadWithOptions * @abstract Loads a kext and its dependencies into the kernel. * * @param aKext The kext to load. * @param startExclusion * kOSKextExcludeAll to omit starting aKext * and any of its dependencies not already started, * kOSKextExcludeKext to start the dependencies of * aKext but not aKext itself, * or kOSKextExcludeNone to start all loaded kexts. * @param addPersonalitiesExclusion * kOSKextExcludeAll to omit sending * IOKitPersonalities to the IOCatalogue for aKext * and any of its dependencies * (though they may already be in the IOCatalogue), * kOSKextExcludeKext to send personalities for the * dependencies of aKext but not aKext itself, * or kOSKextExcludeNone to send all personalities. * @param personalityNames * The names of IOKitPersonalities in aKext to send, * addPersonalitiesExclusion allowing. * If NULL all personalities are sent. * This parameter only affects aKext; if dependency * personalities are sent, they are all sent. * @param delayAutounloadFlag * true to cause the kernel's automatic kext unloader * to skip aKext for one cycle, giving extra time * to set up a debug session. false for normal behavior. * * @result * Returns kOSReturnSuccess on success, other values on failure. * * @discussion * This function allows a kext to be loaded but not started or matched * (for IOKit kexts), which is useful in some debug scenarios. * After calling this function, you may need to call @link OSKextStart@/link * to start aKext (along with its dependencies). * You may also need to call @link OSKextSendPersonalitiesToKernel@/link * for any kexts excluded from matching via * addPersonalitiesExclusion. * * The calling process must have an effective user ID of 0 (root) * to load kexts into the kernel. * * A kext and all its dependencies must pass all validation and authentication * tests to be loadable. See @link OSKextIsLoadable@/link for more information. * * This function calls @link OSKextFlushLoadInfo@/link and clears dependencies * for all open kexts. It then calls @link OSKextCopyLoadList@/link * to find dependencies and @link OSKextReadLoadedKextInfo@/link on the * resulting load list. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextLoadWithOptions( OSKextRef aKext, OSKextExcludeLevel startExclusion, OSKextExcludeLevel addPersonalitiesExclusion, CFArrayRef personalityNames, Boolean delayAutounloadFlag) ; /*! * @function OSKextGenerateDebugSymbols * @abstract Generate debug symbols for a kext and its dependencies. * * @param aKext * The kext to generate debug symbols for. * @param kernelImage * The kernel Mach-O or symbol file to use for linking. * If NULL, the running kernel is used. * * @result * A dictionary whose keys are the bundle IDs of the kexts for which symbols * have been generated with ".sym" appended, and whose values are CFData * objects containing the symbol files. Returns NULL on error. * * @discussion * The result includes only non-interface kexts that have an executable * and a load address set. * Load addresses are set by @link OSKextReadLoadedKextInfo@/link or by * @link OSKextSetLoadAddress@/link. * * If using the running kernel for load addresses, the current architecture * set with @link OSKextSetArchitecture@/link must match that of the running * kernel or this function returns NULL. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT CFDictionaryRef OSKextGenerateDebugSymbols( OSKextRef aKext, CFDataRef kernelImage) ; /*! * @function OSKextNeedsLoadAddressForDebugSymbols * @abstract * Returns whether a kext needs a load address set to generate debug symbols. * * @param aKext The kext to examine. * @result * true if aKext needs a load address set * in order to generate debug symbols with * @link OSKextGenerateDebugSymbols@/link, false otherwise. */ CF_EXPORT Boolean OSKextNeedsLoadAddressForDebugSymbols(OSKextRef aKext) ; /*! * @function OSKextUnload * @abstract Unloads a kext from the kernel if possible. * * @param aKext The kext to unload. * @param terminateServiceAndRemovePersonalities * If true, and the kext to unload has no kexts loaded * against it, all IOService objects defined by that kext will be * asked to terminate so that the unload can proceed, and the personalities * for the kext will be removed from the IOCatalogue. * * @result * kOSReturnSuccess on success, an error code * (typically kOSKextReturnInUse) on failure. * * @discussion * The calling process must have an effective user ID of 0 (root) * to unload kexts from the kernel. * A kext cannot be unloaded if it has any loaed dependents. * * See also the @link IOCatalogueTerminate@/link function. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextUnload(OSKextRef aKext, Boolean terminateServiceAndRemovePersonalities) ; /*! * OSKextUnload * @abstract Unloads a kext from the kernel if possible, based on its * CFBundleIdentifier. * * @param kextIdentifier The CFBundleIDentifier of the kext to unload. * @param terminateServiceAndRemovePersonalities * If true, and the kext to unload has no kexts loaded * against it, all IOService objects defined by that kext will be * asked to terminate so that the unload can proceed, and the personalities * for the kext will be removed from the IOCatalogue. * * @result * kOSReturnSuccess on success, an error code * (typically kOSKextReturnInUse) on failure. * * @discussion * The calling process must have an effective user ID of 0 (root) * to unload kexts from the kernel. * A kext cannot be unloaded if it has any loaed dependents. * * See also the @link IOCatalogueTerminate@/link function. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextUnloadKextWithIdentifier(CFStringRef kextIdentifier, Boolean terminateServiceAndRemovePersonalities) ; /*! * @function OSKextIsStarted * @abstract Returns whether a kext loaded in the kernel is started. * * @param aKext The kext to examine. * @result * true if aKext is active and running in the kernel, * false if not loaded or loaded and not started. * * @discussion * This function returns the state recorded the last time * @link OSKextReadLoadedKextInfo@/link was called. */ CF_EXPORT Boolean OSKextIsStarted(OSKextRef aKext) ; /*! * @function OSKextStart * @abstract Starts a kext loaded in the kernel if possible. * * @param aKext The kext to start. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * This function allows an application to start a kext that is loaded * in the kernel (typically via @link OSKextLoadWithOptions@/link), * and any of its dependencies that aren't also started. * If the kext is already started, this does nothing. * * To start a kext means to call its start function, which is distinct from * the start method of an IOService object. * * The calling process must have an effective user ID of 0 (root) * to start kexts in the kernel. // xxx - need to list errors that may be returned */ CF_EXPORT OSReturn OSKextStart(OSKextRef aKext) ; /*! * @function OSKextStop * @abstract Stops a kext loaded in the kernel if possible. * * @param aKext The kext to stop. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * This function allows an application to stop a kext that is loaded * in the kernel without unloading it. This may be useful in certain * debugging scenarios. * * A kext cannot be stopped via this function if it has any dependents * that reference it, any client references within the kernel, * or any instances of libkern/IOKit C++ classes. * * To stop a kext means to call its stop function, which is distinct from * the stop method of an IOService object. * * The calling process must have an effective user ID of 0 (root) * to stop kexts in the kernel. */ // xxx - should it be allowed to stop a kext with dependents that are // xxx - themselves not started? // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextStop(OSKextRef aKext) ; /*! * @function OSKextSendPersonalitiesToKernel * @abstract Sends an array of IOKit personalities to the kernel. * * @param personalities The personalities to send. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * This function simply sends an anonymous array of personalities to the * I/O Kit's IOCatalogue object in the kernel. * You can get personalities from kexts using * @link OSKextCopyPersonalitiesArray@/link or * @link OSKextCopyPersonalitiesOfKexts@/link. * * The calling process must have an effective user ID of 0 (root) * to send personalities to the kernel. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextSendPersonalitiesToKernel(CFArrayRef personalities) ; /*! * @function OSKextSendKextPersonalitiesToKernel * @abstract * Sends the personalities of a single kext to the kernel, optionally * filtered by name. * * @param aKext The kext whose personalities to send. * @param personalityNames * An array of names. Only personalities from aKext * with these names are sent to the kernel. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * If any names in personalityNames are not found, * they are simply skipped rather than causing an error. * * This function may be useful in certain debugging scenarios, * where a particular personality is causing problems. * * The calling process must have an effective user ID of 0 (root) * to send personalities to the kernel. */ // xxx - should names not found cause an error? // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextSendKextPersonalitiesToKernel( OSKextRef aKext, CFArrayRef personalityNames) ; /*! * @function OSKextSendPersonalitiesOfKextsToKernel * Sends the personalities of multiple kext to the kernel in a single * operation. * * @param kextArray The kexts whose personalities to send. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * This function performs one data transfer to the kernel, collecting * all the personalities of the kexts in kextArray. * * The calling process must have an effective user ID of 0 (root) * to send personalities to the kernel. */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextSendPersonalitiesOfKextsToKernel(CFArrayRef kextArray) ; /*! * @function OSKextRemoveKextPersonalitiesFromKernel * Removes all personalities for a kext's bundle identifier from the kernel. * * @param aKext The kext whose personalities to remove. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * This function removes from the kernel's IOCatalogue all personalities * whose CFBundleIdentifiers match that of aKext so that no * further load requests for aKext will be made. This is * typically done when it is discovered that aKext cannot * be loaded from user space (if it fails to load in the kernel, matching * personalities are automatically removed). * * Note that kexts other than aKext might have published * personalities in the IOCatalogue under aKext's identifier. * Such personalities will also be removed, since they trigger load requests * for a kext that cannot be loaded. The OSKext library adds an * IOPersonalityPublisher property to such personalities, that gives the * bundle identifier of the originating kext. * * This function differs from * @link OSKextRemovePersonalitiesForIdentifierFromKernel@/link * by having a kext object to check for logging or other purposes. * * The calling process must have an effective user ID of 0 (root) * to remove personalities from the kernel. */ // xxx - need to list errors that may be returned // xxx - this is a not-so-thin shim over IOCatalogueSendData (kIOCatalogueRemoveDrivers) // xxx - might we just want the function to take a bundle ID? // xxx - does IOCatalogueSendData really require root access? CF_EXPORT OSReturn OSKextRemoveKextPersonalitiesFromKernel(OSKextRef aKext) ; /*! * @function OSKextRemovePersonalitiesForIdentifierFromKernel * Removes all personalities for a given bundle identifier from the kernel. * * @param aBundleID The bundle identifier for which to remove personalities. * @result * kOSReturnSuccess on success, an error code on failure. * * @discussion * This function removes from the kernel's IOCatalogue all personalities * whose CFBundleIdentifiers are aBundleID so that no * further load requests for the kext with that identifier will be made. * This is typically done when it is discovered no kext can be found for * aBundleID. * * This function differs from * @link OSKextRemoveKextPersonalitiesFromKernel@/link * by not having a kext object to check for logging or other purposes. * * The calling process must have an effective user ID of 0 (root) * to remove personalities from the kernel. */ // xxx - need to list errors that may be returned // xxx - this is a not-so-thin shim over IOCatalogueSendData (kIOCatalogueRemoveDrivers) // xxx - I want 2 separate functions for logging; a kext can have flags in it // xxx - does IOCatalogueSendData really require root access? CF_EXPORT OSReturn OSKextRemovePersonalitiesForIdentifierFromKernel(CFStringRef aBundleID) ; /*! * @function OSKextCreateLoadedKextInfo * @abstract Returns information about loaded kexts in a dictionary. * * @param kextIdentifiers An array of kext identifiers to read from the kernel. * Pass NULL to read info for all loaded kexts. * @result * An array of dictionaries containing information about loaded kexts. * * @discussion * This function gets information from the kernel without affecting any * kext objects. If you want to update open kext objects to reflect * whether they are loaded in the kernel, use @link OSKextReadLoadedKextInfo@/link. */ // xxx - need to document the keys from OSKextLib.h. CF_EXPORT CFArrayRef OSKextCreateLoadedKextInfo( CFArrayRef kextIdentifiers) ; /*! * @function OSKextReadLoadedKextInfo * @abstract Updates kext objects with load info from the kernel. * * @param kextIdentifiers An array of kext identifiers to read * from the kernel; * all matching kexts have their load info updated. * Pass NULL to update load info for all kexts. * @param flushDependenciesFlag * true to clear dependency information from kexts, * false to leave it in place. * * @result * kOSReturnSuccess if all information is successfully updated, * an error code otherwise. Specifically, if the current architecture set * by @link OSKextSetArchitecture@/link is not that of the running kernel, * this function returns kOSKextReturnExecutableArchNotFound. * * @discussion * The load status of kexts primarily affects dependency resolution in the * kext library, in that kexts marked as loaded are given priority over * all other kexts of the same identifier. * See @link OSKextResolveDependencies@/link for more. * * This function calls @link OSKextFlushLoadInfo@/link on the kexts, * which clears any previous load info for them * (or for all kexts if kextIdentifiers is NULL). * If flushDependenciesFlag is true, * resolved dependencies (which may not match the loaded kexts * in the kernel) are also flushed. * Load addresses are then set from the kernel, * but dependencies are resolved as needed. * * If flushDependenciesFlag is false, * existing dependency graphs are maintained, allowing you to * check whether the dependencies, as resolved before reading * load information, reflect loaded kexts (by getting the load list * via @link OSKextCopyLoadList@/link and checking the kexts in it * with @link OSKextIsLoaded@/link). */ // xxx - need to list errors that may be returned CF_EXPORT OSReturn OSKextReadLoadedKextInfo( CFArrayRef kexts, Boolean flushDependenciesFlag) ; /*! * @function OSKextIsLoaded * @abstract Returns whether a kext is loaded in the kernel. * * @param aKext The kext to examine. * @result * true if a kext with the same identifier, version, and UUID * as aKext is loaded in the kernel, false otherwise. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link for this flag to be meaningful, * which in turn requires the current library architecture to match that * of the running kernel. * Use @link OSKextOtherVersionIsLoaded@/link to check whether * a different version of aKext is loaded. */ CF_EXPORT Boolean OSKextIsLoaded(OSKextRef aKext) ; /*! * @function OSKextGetLoadAddress * @abstract Returns the actual or simulated kernel load address of a kext. * * @param aKext The kext to examine. * @result * The load address of aKext, whether read from the kernel using * @link OSKextReadLoadedKextInfo@/link or set for symbol generation using * @link OSKextSetLoadAddress@/link. * * @discussion * Load addresses are accessed as 64-bit numbers even for 32-bit architectures; * cast or truncate the value as necessary. * * You must call @link OSKextReadLoadedKextInfo@/link or * @link OSKextSetLoadAddress@/link for the load address to be nonzero. */ CF_EXPORT uint64_t OSKextGetLoadAddress(OSKextRef aKext) ; /*! * @function OSKextSetLoadAddress * @abstract * Sets the simulated kernel load address of a kext for symbol generation. * * @param aKext The kext to set a load address for. * @result * true if the address was set, false if not * (because it's too large for the current architecture). * * @discussion * Load addresses are accessed as 64-bit numbers even for 32-bit architectures. * If you attempt to set a load address that is too large for a 32-bit link, * this function returns false. * See @link OSKextSetArchitecture@/link. * * Setting a load address manually is useful for generating debug symbols * with @link OSKextGenerateDebugSymbols@/link. */ CF_EXPORT Boolean OSKextSetLoadAddress(OSKextRef aKext, uint64_t anAddress) ; /*! * @function OSKextGetLoadTag * @abstract * Returns the load tag of a kext if it's loaded in the kernel. * * @param aKext The kext to examine. * @result * The load tag (also known as the index or kmod id) of aKext, * if it's loaded in the kernel (use @link OSKextIsLoaded@/link to check that). * Returns 0 if aKext is not loaded or if it can't be determined * whether it is loaded. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link for the load tag * to be meaningful, which in turn requires the current library architecture * to match that of the running kernel. * Use @link OSKextIsLoaded@/link to check whether aKext * is loaded. */ CF_EXPORT uint32_t OSKextGetLoadTag(OSKextRef aKext) ; /*! * @function OSKextFlushLoadInfo * @abstract Clears all load and dependency information from a kext. * * @param aKext * The kext to clear. If NULL, all open * kexts have their load info flushed. * @param flushDependenciesFlag * true to clear dependency information from kexts, * false to leave it in place. * * @discussion * Flushing load information releases the internal load information * structs of a kext, including load flags, the bundle executable, * link/load diagnostics, and if flushDependenciesFlag is true, * the dependencies. * * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * Flushing load info is also useful after readling loaded kext * information from the kernel with @link OSKextReadLoadedKextInfo@/link * or after working with executables. Executables in particular * consume a lot of application memory, often unnecessarily, since * the code is loaded and running in the kernel. * * See also @link OSKextFlushInfoDictionaries@/link, * @link OSKextFlushDependencies@/link, * and @link OSKextFlushDiagnostics@/link. */ CF_EXPORT void OSKextFlushLoadInfo( OSKextRef aKext, Boolean flushDependenciesFlag) ; /*! * @function OSKextCopyAllRequestedIdentifiers * @abstract * Copies the list of all unique bundle identifiers of kext load requests * that the kernel has received since power-on. * * @result * A CFArray object, or NULL if the copy failed. * Ownership follows the * @link //apple_ref/doc/uid/20001148-103029 Create Rule@/link. * */ CF_EXPORT CFArrayRef OSKextCopyAllRequestedIdentifiers(void) ; #pragma mark Sanity Checking and Diagnostics /********************************************************************* * Sanity Checking and Diagnostics *********************************************************************/ /*! * @function OSKextParseVersionCFString * @abstract * Parses a kext version from a CFString. * * @param versionString The kext version string to parse. * @result * The numeric rendering of versionString, which can * compared arithmetically with other valid version numbers. * Returns -1 if the version couldn't be parsed. */ CF_EXPORT OSKextVersion OSKextParseVersionCFString(CFStringRef versionString) ; /*! @function OSKextParseVersionString */ CF_EXPORT OSKextVersion OSKextParseVersionString(const char* versionString); CF_EXPORT void OSKextVersionGetString(OSKextVersion version, char* buffer, size_t bufferLength); /*! * @function OSKextValidate * @abstract * Sanity checks a kext's info dictionary and executable for the currently * set architecture. * * @param aKext The kext to validate. * @result * true if aKext passes all validation tests, * false otherwise. * * @discussion * This function forces full validation of a kext, collecting all * errors found in the validation diagnostics if recording is turned on * (with @link OSKextSetRecordsDiagnostics@/link). You can get the diagnostics * using @link OSKextCopyDiagnostics@/link. * * If safe boot is currently simulated (see * @link OSKextSetSimulatedSafeBoot@/link), * any kext not loadable during safe boot will fail validation. */ // compare with CFBundlePreflightExecutable() CF_EXPORT Boolean OSKextValidate(OSKextRef aKext) ; /*! * @function OSKextIsValid * @abstract * Returns whether a kext is valid or not. * * @param aKext The kext to examine. * @result * true if aKext passes all validation tests, * false otherwise. * * @discussion * This function avoids doing full validation if any problems have been * discovered with the kext during other operations. To perform a full * validation of all possible problems, use @link OSKextValidate@/link. */ CF_EXPORT Boolean OSKextIsValid(OSKextRef aKext) ; /*! * @function OSKextValidateDependencies * @abstract Validates all dependencies of a kext. * * @param aKext The kexts whose dependencies to validate. * @result * true if all dependencies of aKext are valid, * false if any of them are not. * * @discussion * This function calls @link OSKextValidate@/link on aKext and * all the current dependencies of aKext. * Use @link OSKextCopyDiagnostics@/link * with a flag of @link kOSKextDiagnosticsFlagDependencies@/link * to get the dependency-resolution failures caused by invalid dependencies. * * If safe boot is currently simulated (see * @link OSKextSetSimulatedSafeBoot@/link), * any kext not loadable during safe boot will fail validation. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT Boolean OSKextValidateDependencies(OSKextRef aKext) ; /*! * @function OSKextAuthenticate * @abstract Authenticates file ownership and permissions of a kext. * * @param aKext The kext to examine. * @result * true if all directories and files in aKext's * bundle or mkext source have secure ownership and permissions, * false if they do not, or if authentication could not be done. * * @discussion * This function forces full authentication of a kext, collecting all * errors found in the authentication diagnostics, collecting all * errors found in the validation diagnostics if recording is turned on * (with @link OSKextSetRecordsDiagnostics@/link). You can get the diagnostics * using @link OSKextCopyDiagnostics@/link. * * For a kext to be loadable into the kernel, it must be owned by * user root, group wheel, and its constituent files and directories * must be nonwritable by group and other. * A kext created from an mkext file uses that mkext file for authentication * (see @link OSKextCreateKextsFromMkextFile@/link. */ CF_EXPORT Boolean OSKextAuthenticate(OSKextRef aKext) ; /*! * @function OSKextIsAuthentic * @abstract * Returns whether a kext is authentic or not. * * @param aKext The kext to examine. * @result * true if aKext passes all authentication tests, * false otherwise. * * @discussion * This function avoids doing full authentication if any problems have been * discovered with the kext during other operations. To perform a full * validation of all possible problems, use @link OSKextValidate@/link. */ CF_EXPORT Boolean OSKextIsAuthentic(OSKextRef aKext) ; /*! * @function OSKextAuthenticateDependencies * @abstract Authenticates all dependencies of a kext. * * @param aKext The kexts whose dependencies to authenticate. * @result * true if all dependencies of aKext are authentic, * false if any of them are not. * * @discussion * This function calls @link OSKextAuthenticate@/link on aKext * and all the current dependencies of aKext. * Use @link OSKextCopyDiagnostics@/link * with a flag of @link kOSKextDiagnosticsFlagDependencies@/link * to get the dependency-resolution failures caused by inauthentic dependencies. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT Boolean OSKextAuthenticateDependencies(OSKextRef aKext) ; /*! * @function OSKextIsLoadable * @abstract * Returns whether a kext appears loadable for the current architecture. * * @param aKext The kext to examine. * @result * true if aKext has no problems with validation, * authentication, or dependency resolution for the current architecture, * and if it's eligible for the current safe boot mode. * Returns false otherwise. * * @discussion * This function resolves dependencies for aKext, * validates and authenticsates aKext and its dependencies, * and if safe boot is simulated also checks the OSBundleRequired property * of aKext and its dependencies. If all these tests pass, * the kext is considered loadable for the current architecture * (which need not match that of the running kernel). * * See @link OSKextSetArchitecture@/link and * @link OSKextSetSimulatedSafeBoot@/link. * * This function calls @link OSKextResolveDependencies@/link to find * dependencies. */ CF_EXPORT Boolean OSKextIsLoadable(OSKextRef aKext) ; /*! * @function OSKextCopyDiagnostics * @abstract Returns diagnostics information for a kext. * * @param aKext The kext to get diagnostics for. * @param typeFlags Flags indicating which diagnostics to retrieve. * @result * A dictionary containing diagnostics for aKext, suitable * for display in an outline view or printout. * * @discussion * You can use this function after validating, authenticating, resolving * dependencies, or generating debug symbols to get all the problems encountered * with those operations. * * The exact keys and values used for diagnostics are for informational purposes * only, are not formally defined, and may change without warning. * * You can use @link OSKextLogDiagnostics@/link to print nicely-formatted * reports of any problems found with kexts. */ // xxx - need to tie in with the kernel & linker to get link failures CFDictionaryRef OSKextCopyDiagnostics(OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) ; /*! * @function OSKextLogDiagnostics * @abstract Logs specified diagnostics for a kext. * * @param aKext The kext to log diagnostics for. * @param typeFlags Flags indicating which diagnostics to log. * * @discussion * You can use this function after validating, authenticating, resolving * dependencies, or generating debug symbols to display all the problems * encountered with those operations. */ CF_EXPORT void OSKextLogDiagnostics( OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) ; /*! * @function OSKextFlushDiagnostics * @abstract Clears all diagnostics information from a kext. * * @param aKext * The kext to clear diagnostics from. * Pass NULL to flush diagnostics from all open kexts. * @param typeFlags Flags indicating which diagnostics to flush. * * @discussion * OSKexts accumulate a fair amount of information as they are created * and used; when many kext objects are created the total memory * consumption can be significant. If an application won't be using * kexts for long periods of time, it can flush this information * to save memory; the information will later be re-read from disk * or recreated as necessary. * * See also @link OSKextFlushInfoDictionaries@/link, * @link OSKextFlushDependencies@/link, * and @link OSKextFlushLoadInfo@/link. */ CF_EXPORT void OSKextFlushDiagnostics(OSKextRef aKext, OSKextDiagnosticsFlags typeFlags) ; #pragma mark Mkext and Prelinked Kernel Files /********************************************************************* * Mkext and Prelinked Kernel Files *********************************************************************/ // xxx - Use "Flag" or "Mask"? typedef uint32_t OSKextRequiredFlags ; #define kOSKextOSBundleRequiredNone 0x0 #define kOSKextOSBundleRequiredRootFlag 0x1ULL #define kOSKextOSBundleRequiredLocalRootFlag 0x1ULL << 1 #define kOSKextOSBundleRequiredNetworkRootFlag 0x1ULL << 2 #define kOSKextOSBundleRequiredSafeBootFlag 0x1ULL << 3 #define kOSKextOSBundleRequiredConsoleFlag 0x1ULL << 4 /*! * @function OSKextIsFromMkext * @abstract Returns whether a kext was created from an mkext archive. * * @param aKext The kext to examine. * @result * true if aKext was created from an mkext archive, * false if it was created from an on-disk bundle. * * @discussion * A kext created from an mkext will have only its info dictionary, executable, * and any resources listed in its the OSBundleStartupResources property. */ CF_EXPORT Boolean OSKextIsFromMkext(OSKextRef aKext) ; /*! * @function OSKextMatchesRequiredFlags * @abstract * Returns whether a kext matches a given set of flags for inclusion in an * mkext archive. * * @param aKext The kext to examine. * @param requiredFlags * Flags indicating which values of OSBundleRequired * are needed. * @result * true if aKext's OSBundleRequired property * matches one of the specified flags, false otherwise. * * @discussion * This function is used to select kexts for inclusion in an mkext archive. * See @link OSKextFilterRequiredKexts@/link and * @link OSKextCreateMkext@/link. */ CF_EXPORT Boolean OSKextMatchesRequiredFlags(OSKextRef aKext, OSKextRequiredFlags requiredFlags) ; /*! * @function OSKextFilterRequiredKexts * @abstract * Filters an array of kexts based on a set of flags * for inclusion in an mkext archive. * * @param kextArray * The kexts to filter. * Pass NULL to filter all open kexts. * @param requiredFlags * Flags indicating which values of OSBundleRequired * are needed. * @result * An array of kexts matching requiredFlags. * * @discussion * This function is used to select kexts for inclusion in an mkext archive. * See @link OSKextCreateMkext@/link. * */ CF_EXPORT CFArrayRef OSKextFilterRequiredKexts(CFArrayRef kextArray, OSKextRequiredFlags requiredFlags) ; /*! * @function OSKextCreateMkext * @abstract Create an mkext file from an array of kexts and set of flags. * * @param allocator * The allocator to use to allocate memory for the new object. * Pass NULL or kCFAllocatorDefault * to use the current default allocator. * @param kextArray * The kexts to include in the mkext. * Pass NULL to use all open kexts. * @param volumeRootURL * If non-NULL, kexts with this URL as a prefix * strip it when saving their paths in the mkext. * This allows creation of mkexts for volumes * other than the current startup volume. * @param requiredFlags * A set of flags that filters kextArray to a subset * of kexts required for specific startup scenarios * (typically local disk vs. network). * @param compressFlag * true to compress data in the mkext, * false to include them at full size. * COMPRESSED MKEXTS ARE NOT SUPPORTED IN THE KERNEL YET. * @result * A CFData object containing the mkext file data on success, * NULL on failure. * * @discussion * This function creates a single-architecture mkext file for the currently * set library architecture (see @link OSKextSetArchitecture@/link). Kexts * with executables lacking code for that architecture are not included. * * If you want to create a multi-architecture mkext, create a set of single * architecture mkext files and use lipo(1) or combine them programmatically. * * This function generates mkext files in a new format that only works on * Mac OS X 10.6 or later. */ // xxx - add a version param and generate old-format mkexts? // xxx - add flag to take only most recent version of a given bundle ID? CF_EXPORT CFDataRef OSKextCreateMkext( CFAllocatorRef allocator, CFArrayRef kextArray, CFURLRef volumeRootURL, OSKextRequiredFlags requiredFlags, Boolean compressFlag) ; /*! * @function OSKextCreateKextsFromMkextFile * @abstract Reads all kexts from an mkext file on disk. * * @param alocator * The allocator to use to allocate memory for the new objects. * Pass NULL or kCFAllocatorDefault * to use the current default allocator. * @param mkextURL * The mkext file URL from which to create kexts. * @result * Returns an array containing the kext objects created, * or NULL on failure. * * @discussion * This function creates kext objects from an mkext file rather than from * bundles on disk. Kexts created with this function are authenticated using * the mkext file at mkextURL. * * A kext created from an mkext has only its info dictionary, executable, * and any resources listed in its the OSBundleStartupResources property. * * Kexts created from an mkext are not uniqued using filesystem URLs, * which belong to bundles actually in the filesystem; * @link OSKextCreate@/link will never return a kext extracted from an mkext * that originally had the URL given (even though the new mkext format * stores that original URL). * This also means that if you open the same mkext file multiple times, * you will create distinct, identical copies of the kexts in that mkext file. */ CF_EXPORT CFArrayRef OSKextCreateKextsFromMkextFile(CFAllocatorRef allocator, CFURLRef mkextURL) ; /*! * @function OSKextCreateKextsFromMkextData * @abstract Reads all kexts from an mkext file in memory. * * @param alocator * The allocator to use to allocate memory for the new objects. * Pass NULL or kCFAllocatorDefault * to use the current default allocator. * @param mkextData * The mkext file data from which to create kexts. * @result * Returns an array containing the kext objects created, * or NULL on failure. * * @discussion * This function creates kext objects from an mkext file in memory * rather than from bundles on disk. Lacking any file in the filesystem, * kexts created with this function can not be authenticated. * * A kext created from an mkext has only its info dictionary, executable, * and any resources listed in its the OSBundleStartupResources property. * * Kexts created from an mkext are not uniqued using filesystem URLs, * which belong to bundles actually in the filesystem; * @link OSKextCreate@/link will never return a kext extracted from an mkext * that originally had the URL given (even though the new mkext format * stores that original URL). * This also means that if you open the same mkext file multiple times, * you will create distinct, identical copies of the kexts in that mkext file. */ CF_EXPORT CFArrayRef OSKextCreateKextsFromMkextData(CFAllocatorRef allocator, CFDataRef mkextData) ; /*! * @function OSKextCreatePrelinkedKernel * @abstract Creates a prelinked kernel from a kernel file and all open kexts. * * @param kernelImage The kernel image to use. * @param kextArray * The kexts to include in the prelinked kernel. * Pass NULL to consult the running kernel * for kexts to include from those open; * the current architecture must match the runninng kernel's. * @param volumeRootURL * If non-NULL, kexts with this URL as a prefix * strip it when saving their paths in the prelinked kernel. * This allows creation of prelinked kernels from folders * other than /System/Library/Extensions. * @param needAllFlag * If true and any kext fails to link, * the skipAuthenticationFlag returns NULL. * @param skipAuthenticationFlag * If true, kexts are not authenticated for inclusion * in the prelinked kernel. * @param printDiagnosticsFlag * If true, problems with the kexts that prevent * inclusion of a kext in the prelinked kernel are logged via * @link OSKextLogDiagnostics OSKextLogDiagnostics@/link. * @param symbolsOut * If non-NULL debug symbols for kernelImage * and all kexts included in the result are returned by reference. * * @result * A CFData object containing the prelinked kernel image based * on the running kernel. * Returns NULL if needAllFlag is true * and any kext fails to link. */ CF_EXPORT CFDataRef OSKextCreatePrelinkedKernel( CFDataRef kernelImage, CFArrayRef kextArray, CFURLRef volumeRootURL, Boolean needAllFlag, Boolean skipAuthenticationFlag, Boolean printDiagnosticsFlag, CFDictionaryRef * symbolsOut) ; /*! * @function OSKextotherCFBundleVersionIsLoaded * @abstract * Returns whether another version of a given kext is loaded in the kernel. * * @param aKext The kext to examine. * @result * true if a kext with the same identifier, * but a different version or UUID * from aKext, is loaded in the kernel. * Returns false if aKext is loaded or if * no kext with the same identifier is loaded. * * @discussion * You must call @link OSKextReadLoadedKextInfo@/link for this flag to be meaningful, * which in turn requires the current library architecture to match that * of the running kernel. * Use @link OSKextIsLoaded@/link to check whether aKext * itself is loaded. */ CF_EXPORT Boolean OSKextotherCFBundleVersionIsLoaded(OSKextRef kext, Boolean* uuidFlag); __END_DECLS #endif /* __OSKEXT_H__ */