FreeBSD/Linux Kernel Cross Reference
sys/libkern/libkern/OSKextLib.h

     /*
      * 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 _LIBKERN_OSKEXTLIB_H
    #define _LIBKERN_OSKEXTLIB_H
    
    #include <sys/cdefs.h>
    __BEGIN_DECLS
    
    #include <stdint.h>
    #include <mach/kmod.h>
    #include <mach/vm_types.h>
    
    #ifdef KERNEL
    #include <libkern/OSTypes.h>
    #include <libkern/OSReturn.h>
    #else
    #include <CoreFoundation/CoreFoundation.h>
    #include <System/libkern/OSReturn.h>
    #endif /* KERNEL */
    
    /*!
     * @header
     *
     * Declares functions, basic return values, and other constants
     * related to kernel extensions (kexts).
     */
    
    #if PRAGMA_MARK
    #pragma mark -
    /********************************************************************/
    #pragma mark OSReturn Values for Kernel Extensions
    /********************************************************************/
    #endif
    /*!
     * @group OSReturn Values for Kernel Extensions
     * Many kext-related functions return these values,
     * as well as those defined under
     * <code>@link //apple_ref/c/tdef/OSReturn OSReturn@/link</code>
     * and other variants of <code>kern_return_t</code>.
     */
    
    #ifdef XNU_KERNEL_PRIVATE
    /*********************************************************************
    * Check libsyscall/mach/err_libkern.sub when editing or adding
    * result codes!
    *********************************************************************/
    #endif /* XNU_KERNEL_PRIVATE */
    
    #define sub_libkern_kext           err_sub(2)
    #define libkern_kext_err(code)     (sys_libkern|sub_libkern_kext|(code))
    
    
    /*!
     * @define   kOSKextReturnInternalError
     * @abstract An internal error in the kext library.
     *           Contrast with <code>@link //apple_ref/c/econst/OSReturnError
     *           OSReturnError@/link</code>.
     */
    #define kOSKextReturnInternalError                   libkern_kext_err(0x1)
    
    /*!
     * @define   kOSKextReturnNoMemory
     * @abstract Memory allocation failed.
     */
    #define kOSKextReturnNoMemory                        libkern_kext_err(0x2)
    
    /*!
     * @define   kOSKextReturnNoResources
     * @abstract Some resource other than memory (such as available load tags)
     *           is exhausted.
     */
    #define kOSKextReturnNoResources                     libkern_kext_err(0x3)
    
   /*!
    * @define   kOSKextReturnNotPrivileged
    * @abstract The caller lacks privileges to perform the requested operation.
    */
   #define kOSKextReturnNotPrivileged                   libkern_kext_err(0x4)
   
   /*!
    * @define   kOSKextReturnInvalidArgument
    * @abstract Invalid argument.
    */
   #define kOSKextReturnInvalidArgument                 libkern_kext_err(0x5)
   
   /*!
    * @define   kOSKextReturnNotFound
    * @abstract Search item not found.
    */
   #define kOSKextReturnNotFound                        libkern_kext_err(0x6)
   
   /*!
    * @define   kOSKextReturnBadData
    * @abstract Malformed data (not used for XML).
    */
   #define kOSKextReturnBadData                         libkern_kext_err(0x7)
   
   /*!
    * @define   kOSKextReturnSerialization
    * @abstract Error converting or (un)serializing URL, string, or XML.
    */
   #define kOSKextReturnSerialization                   libkern_kext_err(0x8)
   
   /*!
    * @define   kOSKextReturnUnsupported
    * @abstract Operation is no longer or not yet supported.
    */
   #define kOSKextReturnUnsupported                     libkern_kext_err(0x9)
   
   /*!
    * @define   kOSKextReturnDisabled
    * @abstract Operation is currently disabled.
    */
   #define kOSKextReturnDisabled                        libkern_kext_err(0xa)
   
   /*!
    * @define   kOSKextReturnNotAKext
    * @abstract Bundle is not a kernel extension.
    */
   #define kOSKextReturnNotAKext                        libkern_kext_err(0xb)
   
   /*!
    * @define   kOSKextReturnValidation
    * @abstract Validation failures encountered; check diagnostics for details.
    */
   #define kOSKextReturnValidation                      libkern_kext_err(0xc)
   
   /*!
    * @define   kOSKextReturnAuthentication
    * @abstract Authetication failures encountered; check diagnostics for details.
    */
   #define kOSKextReturnAuthentication                  libkern_kext_err(0xd)
   
   /*!
    * @define   kOSKextReturnDependencies
    * @abstract Dependency resolution failures encountered; check diagnostics for details.
    */
   #define kOSKextReturnDependencies                    libkern_kext_err(0xe)
   
   /*!
    * @define   kOSKextReturnArchNotFound
    * @abstract Kext does not contain code for the requested architecture.
    */
   #define kOSKextReturnArchNotFound                    libkern_kext_err(0xf)
   
   /*!
    * @define   kOSKextReturnCache
    * @abstract An error occurred processing a system kext cache.
    */
   #define kOSKextReturnCache                           libkern_kext_err(0x10)
   
   /*!
    * @define   kOSKextReturnDeferred
    * @abstract Operation has been posted asynchronously to user space (kernel only).
    */
   #define kOSKextReturnDeferred                        libkern_kext_err(0x11)
   
   /*!
    * @define   kOSKextReturnBootLevel
    * @abstract Kext not loadable or operation not allowed at current boot level.
    */
   #define kOSKextReturnBootLevel                       libkern_kext_err(0x12)
   
   /*!
    * @define   kOSKextReturnNotLoadable
    * @abstract Kext cannot be loaded; check diagnostics for details.
    */
   #define kOSKextReturnNotLoadable                     libkern_kext_err(0x13)
   
   /*!
    * @define   kOSKextReturnLoadedVersionDiffers
    * @abstract A different version (or executable UUID, or executable by checksum)
    *           of the requested kext is already loaded.
    */
   #define kOSKextReturnLoadedVersionDiffers            libkern_kext_err(0x14)
   
   /*!
    * @define   kOSKextReturnDependencyLoadError
    * @abstract A load error occurred on a dependency of the kext being loaded.
    */
   #define kOSKextReturnDependencyLoadError             libkern_kext_err(0x15)
   
   /*!
    * @define   kOSKextReturnLinkError
    * @abstract A link failure occured with this kext or a dependency.
    */
   #define kOSKextReturnLinkError                       libkern_kext_err(0x16)
   
   /*!
    * @define   kOSKextReturnStartStopError
    * @abstract The kext start or stop routine returned an error.
    */
   #define kOSKextReturnStartStopError                  libkern_kext_err(0x17)
   
   /*!
    * @define   kOSKextReturnInUse
    * @abstract The kext is currently in use or has outstanding references,
    *           and cannot be unloaded.
    */
   #define kOSKextReturnInUse                           libkern_kext_err(0x18)
   
   /*!
    * @define   kOSKextReturnTimeout
    * @abstract A kext request has timed out.
    */
   #define kOSKextReturnTimeout                         libkern_kext_err(0x19)
   
   /*!
    * @define   kOSKextReturnStopping
    * @abstract The kext is in the process of stopping; requests cannot be made.
    */
   #define kOSKextReturnStopping                        libkern_kext_err(0x1a)
   
   #if PRAGMA_MARK
   #pragma mark -
   /********************************************************************/
   #pragma mark Kext/OSBundle Property List Keys
   /********************************************************************/
   #endif
   /*!
    * @group Kext Property List Keys
    * These constants cover CFBundle properties defined for kernel extensions.
    * Because they are used in the kernel, if you want to use one with
    * CFBundle APIs you'll need to wrap it in a <code>CFSTR()</code> macro.
    */
   
   #ifdef KERNEL
   /* Define C-string versions of the CFBundle keys for use in the kernel.
    */
   #define kCFBundleIdentifierKey                  "CFBundleIdentifier"
   #define kCFBundleVersionKey                     "CFBundleVersion"
   #define kCFBundleNameKey                        "CFBundleName"
   #define kCFBundleExecutableKey                  "CFBundleExecutable"
   #endif /* KERNEL */
   
   /*!
    * @define   kOSBundleCompatibleVersionKey
    * @abstract A string giving the backwards-compatible version of a library kext
    *           in extended Mac OS 'vers' format (####.##.##s{1-255} where 's'
    *           is a build stage 'd', 'a', 'b', 'f' or 'fc').
    */
   #define kOSBundleCompatibleVersionKey           "OSBundleCompatibleVersion"
   
   /*!
    * @define   kOSBundleEnableKextLoggingKey
    * @abstract Set to true to have the kernel kext logging spec applied
    *           to the kext.
    *           See <code>@link //apple_ref/c/econst/OSKextLogSpec
    *           OSKextLogSpec@/link</code>.
    */
   #define kOSBundleEnableKextLoggingKey           "OSBundleEnableKextLogging"
   
   /*!
    * @define   kOSBundleIsInterfaceKey
    * @abstract A boolean value indicating whether the kext executable
    *           contains only symbol references.
    */
   #define kOSBundleIsInterfaceKey                 "OSBundleIsInterface"
   
   /*!
    * @define   kOSBundleLibrariesKey
    * @abstract A dictionary listing link dependencies for this kext.
    *           Keys are bundle identifiers, values are version strings.
    */
   #define kOSBundleLibrariesKey                   "OSBundleLibraries"
   
   /*!
    * @define   kOSBundleRequiredKey
    * @abstract A string indicating in which kinds of startup this kext
    *           may need to load during early startup (before
    *           <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>).
    * @discussion
    * The value is one of:
    * <ul>
    * <li>@link kOSBundleRequiredRoot "OSBundleRequiredRoot"@/link</li>
    * <li>@link kOSBundleRequiredLocalRoot "OSBundleRequiredLocalRoot"@/link</li>
    * <li>@link kOSBundleRequiredNetworkRoot "OSBundleRequiredNetworkRoot"@/link</li>
    * <li>@link kOSBundleRequiredSafeBoot "OSBundleRequiredSafeBoot"@/link</li>
    * <li>@link kOSBundleRequiredConsole "OSBundleRequiredConsole"@/link</li>
    * </ul>
    *
    * Use this property judiciously.
    * Every kext that declares a value other than "OSBundleRequiredSafeBoot"
    * increases startup time, as the booter must read it into memory,
    * or startup kext caches must include it.
    */
   #define kOSBundleRequiredKey                    "OSBundleRequired"
   
   /*!
    * @define   kOSBundleAllowUserLoadKey
    * @abstract A boolean value indicating whether
    *           <code>@link //apple_ref/doc/man/8/kextd kextcache(8)@/link</code>
    *           will honor a non-root process's request to load a kext.
    * @discussion
    * See <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithURL
    * KextManagerLoadKextWithURL@/link</code>
    * and <code>@link //apple_ref/doc/compositePage/c/func/KextManagerLoadKextWithIdentifier
    * KextManagerLoadKextWithIdentifier@/link</code>.
    */
   #define kOSBundleAllowUserLoadKey               "OSBundleAllowUserLoad"
   
   /*!
    * @define   kOSKernelResourceKey
    * @abstract A boolean value indicating whether the kext represents a built-in
    *           component of the kernel.
    */
   #define kOSKernelResourceKey                    "OSKernelResource"
   
   /*!
    * @define   kIOKitPersonalitiesKey
    * @abstract A dictionary of dictionaries used in matching for I/O Kit drivers.
    */
   #define kIOKitPersonalitiesKey                  "IOKitPersonalities"
   
   /*
    * @define   kIOPersonalityPublisherKey
    * @abstract Used in personalities sent to the I/O Kit,
    *           contains the CFBundleIdentifier of the kext
    *           that the personality originated in.
    */
   #define kIOPersonalityPublisherKey              "IOPersonalityPublisher"
   
   
   #if PRAGMA_MARK
   /********************************************************************/
   #pragma mark Kext/OSBundle Property Deprecated Keys
   /********************************************************************/
   #endif
   /*
    * @define   kOSBundleDebugLevelKey
    * @abstract
    * Deprecated (used on some releases of Mac OS X prior to 10.6 Snow Leopard).
    * Value is an integer from 1-6, corresponding to the verbose levels
    * of kext tools on those releases.
    * On 10.6 Snow Leopard, use <code>@link OSKextEnableKextLogging
    * OSKextEnableKextLogging@/link</code>.
    */
   #define kOSBundleDebugLevelKey                  "OSBundleDebugLevel"
   
   /*!
    * @define   kOSBundleSharedExecutableIdentifierKey
    * @abstract Deprecated (used on some releases of Mac OS X
    *           prior to 10.6 Snow Leopard).
    *           Value is the bundle identifier of the pseudokext
    *           that contains an executable shared by this kext.
    */
   #define kOSBundleSharedExecutableIdentifierKey  "OSBundleSharedExecutableIdentifier"
   
   
   #if PRAGMA_MARK
   /********************************************************************/
   #pragma mark Kext/OSBundle Property List Values
   /********************************************************************/
   #endif
   
   /*!
    * @group Kext Property List Values
    * These constants encompass established values
    * for kernel extension bundle properties.
    */
   
   /*!
   * @define   kOSKextKernelIdentifier
   * @abstract
   * This is the CFBundleIdentifier user for the kernel itself.
   */
   #define kOSKextKernelIdentifier                 "__kernel__"
   
   /*!
   * @define   kOSBundleRequiredRoot
   * @abstract
   * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
   * value indicates that the kext may be needed to mount the root filesystem
   * whether starting from a local or a network volume.
   */
   #define kOSBundleRequiredRoot                   "Root"
   
   /*!
   * @define   kOSBundleRequiredLocalRoot
   * @abstract
   * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
   * value indicates that the kext may be needed to mount the root filesystem
   * when starting from a local disk.
   */
   #define kOSBundleRequiredLocalRoot              "Local-Root"
   
   /*!
   * @define   kOSBundleRequiredNetworkRoot
   * @abstract
   * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
   * value indicates that the kext may be needed to mount the root filesystem
   * when starting over a network connection.
   */
   #define kOSBundleRequiredNetworkRoot            "Network-Root"
   
   /*!
   * @define   kOSBundleRequiredSafeBoot
   * @abstract
   * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
   * value indicates that the kext can be loaded during a safe startup.
   * This value does not normally cause the kext to be read by the booter
   * or included in startup kext caches.
   */
   #define kOSBundleRequiredSafeBoot               "Safe Boot"
   
   /*!
   * @define   kOSBundleRequiredConsole
   * @abstract
   * This <code>@link kOSBundleRequiredKey OSBundleRequired@/link</code>
   * value indicates that the kext may be needed for console access
   * (specifically in a single-user startup when
   * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>.
   * does not run)
   * and should be loaded during early startup.
   */
   #define kOSBundleRequiredConsole                "Console"
   
   
   #if PRAGMA_MARK
   #pragma mark -
   /********************************************************************/
   #pragma mark Kext Information
   /********************************************************************/
   #endif
   /*!
    * @group Kext Information
    * Types, constants, and macros providing a kext with information
    * about itself.
    */
   
   /*!
    * @typedef OSKextLoadTag
    *
    * @abstract
    * A unique identifier assigned to a loaded instanace of a kext.
    *
    * @discussion
    * If a kext is unloaded and later reloaded, the new instance
    * has a different load tag.
    *
    * A kext can get its own load tag in the <code>kmod_info_t</code>
    * structure passed into its module start routine, as the
    * <code>id</code> field (cast to this type).
    * You can use the load tag with the functions
    * <code>@link OSKextRetainKextWithLoadTag
    * OSKextRetainKextWithLoadTag@/link</code> and
    * <code>@link OSKextReleaseKextWithLoadTag
    * OSKextReleaseKextWithLoadTag@/link</code>.
    */
   typedef uint32_t  OSKextLoadTag;
   
   /*!
    * @define kOSKextInvalidLoadTag
    *
    * @abstract
    * A load tag value that will never be used for a loaded kext;
    * indicates kext not found.
    */
   #define  kOSKextInvalidLoadTag  ((OSKextLoadTag)(-1))
   
   
   #ifdef KERNEL
   
   /* Make these visible to kexts only and *not* the kernel.
    */
   #if !XNU_KERNEL_PRIVATE
   
   /*!
    * @function OSKextGetCurrentLoadTag
    *
    * @abstract
    * Returns the run-time load tag for the calling kext as an
    * <code>@link OSKextLoadTag OSKextLoadTag@/link</code>.
    *
    * @result
    * The run-time load tag for the calling kext as an
    * <code>@link OSKextLoadTag@/link</code>.
    *
    * @discussion
    * The load tag identifies this loaded instance of the kext to the kernel
    * and to kernel functions that operate on kexts.
    */
   OSKextLoadTag OSKextGetCurrentLoadTag(void);
   
   /*!
    * @function OSKextGetCurrentIdentifier
    *
    * @abstract
    * Returns the CFBundleIdentifier for the calling kext as a C string.
    *
    * @result
    * The CFBundleIdentifier for the calling kext as a C string.
    */
   const char * OSKextGetCurrentIdentifier(void);
   
   /*!
    * @function OSKextGetCurrentVersionString
    *
    * @abstract
    * Returns the CFBundleVersion for the calling kext as a C string.
    *
    * @result
    * The CFBundleVersion for the calling kext as a C string.
    */
   const char * OSKextGetCurrentVersionString(void);
   
   #endif /* !XNU_KERNEL_PRIVATE */
   
   #if PRAGMA_MARK
   #pragma mark -
   /********************************************************************/
   #pragma mark Kext Loading C Functions
   /********************************************************************/
   #endif
   /*!
    * @group Kext Loading C Functions
    * Functions for loading and tracking kexts in the kernel.
    */
    
   /*!
    * @function OSKextLoadKextWithIdentifier
    *
    * @abstract
    * Request that a kext be loaded.
    *
    * @param  kextIdentifier  The bundle identifier of the kext to be loaded.
    *
    * @result
    * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code>
    * if the kext was loaded (or was already loaded).
    * <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code>
    * if the kext was not found and a request
    * was queued to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>.
    * Other return values indicate a failure to load the kext.
    *
    * @discussion
    * If a kext is already in the kernel but not loaded, it is loaded immediately.
    * If it isn't found, an asynchronous load request is
    * made to <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>
    * and  <code>@link //apple_ref/c/macro/kOSKextReturnDeferred kOSKextReturnDeferred@/link</code> is returned.
    * There is no general notification or callback mechanism for load requests.
    */
   OSReturn OSKextLoadKextWithIdentifier(const char * kextIdentifier);
   
   
   /*!
    * @function OSKextRetainKextWithLoadTag
    *
    * @abstract
    * Retain a loaded kext based on its load tag,
    * and enable autounload for that kext.
    *
    * @param  loadTag   The load tag of the kext to be retained.
    *                   See <code>@link OSKextGetCurrentLoadTag@/link</code>.
    *
    * @result
    * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code>
    * if the kext was retained.
    * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound kOSKextReturnNotFound@/link</code>
    * if the kext was not found.
    * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument
    * kOSKextReturnInvalidArgument@/link</code>
    * if <code>loadTag</code> is
    * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>.
    *
    * @discussion
    * Retaining a kext prevents it from being unloaded,
    * either explicitly or automatically, and enables autounload for the kext.
    * When autounload is enabled, then shortly after the kext's last reference
    * is dropped, it will be unloaded if there are no outstanding references to it
    * and there are no instances of its Libkern C++ subclasses (if any).
    *
    * Kexts that define subclasses of
    * <code>@link //apple_ref/doc/class/IOService IOService@/link</code>
    * have autounload enabled automatically.
    * Other kexts can use the reference count to manage automatic unload
    * without having to define and create Libkern C++ objects.
    * For example, a filesystem kext can retain itself whenever a new mount
    * is created, and release itself when a mount is removed.
    * When the last mount is removed, the kext will be unloaded after a brief delay.
    *
    * A kext can get its own load tag using the
    * <code>@link OSKextGetCurrentLoadTag@/link</code>.
    *
    * Kexts should not retain and release other kexts; linkage references
    * are accounted for internally.
    */
   OSReturn OSKextRetainKextWithLoadTag(OSKextLoadTag loadTag);
   
   
   /*!
    * @function OSKextReleaseKextWithLoadTag
    *
    * @abstract
    * Release a loaded kext based on its load tag.
    *
    * @param  loadTag   The load tag of the kext to be released.
    *                   See <code>@link OSKextGetCurrentLoadTag@/link</code>.
    *
    * @result
    * <code>@link //apple_ref/c/macro/kOSReturnSuccess kOSReturnSuccess@/link</code>
    * if the kext was released.
    * <code>@link //apple_ref/c/macro/kOSKextReturnNotFound
    * kOSKextReturnNotFound@/link</code>
    * if the kext was not found.
    * <code>@link //apple_ref/c/macro/kOSKextReturnInvalidArgument
    * kOSKextReturnInvalidArgument@/link</code>
    * if <code>loadTag</code> is
    * <code>@link kOSKextInvalidLoadTag kOSKextInvalidLoadTag@/link</code>.
    *
    * @discussion
    * The kext should have been retained previously via
    * <code>@link OSKextRetainKextWithLoadTag@/link</code>.
    *
    * This function schedules an autounload scan for all kexts.
    * When that scan occurs, if a kext has autounload enabled,
    * it will be unloaded if there are no outstanding references to it
    * and there are no instances of its Libkern C++ classes (if any).
    *
    * Kexts that define subclasses of
    * <code>@link //apple_ref/doc/class/IOService IOService@/link</code>
    * have autounload enabled automatically.
    * Other kexts can use the reference count to manage automatic unload
    * without having to define and create Libkern C++ objects.
    * For example, a filesystem kext can be retained whenever a new mount
    * is created, and released when a mount is removed.
    * When the last mount is removed, the kext will be unloaded after a brief delay.
    *
    * While the autounload scan takes place after a delay of at least a minute,
    * a kext that manages its own reference counts for autounload should
    * be prepared to have its module stop function called even while the function
    * calling this function is still running.
    *
    * A kext can get its own load tag using the
    * <code>@link OSKextGetCurrentLoadTag@/link</code>.
    *
    * Kexts should not retain and release other kexts; linkage references
    * are accounted for internally.
    */
   OSReturn OSKextReleaseKextWithLoadTag(OSKextLoadTag loadTag);
   
   #if PRAGMA_MARK
   /********************************************************************/
   #pragma mark -
   #pragma mark Kext Requests
   /********************************************************************/
   #endif
   /*!
    * @typedef OSKextRequestTag
    *
    * @abstract
    * Identifies a kext request made to user space.
    */
   typedef uint32_t OSKextRequestTag;
   
   #define kOSKextRequestTagInvalid  ((OSKextRequestTag)-1)
   
   
   /*!
    * @typedef OSKextRequestResourceCallback
    *
    * @abstract
    * Invoked to provide results for a kext resource request.
    *
    * @param  requestTag          The tag of the request that the callback pertains to.
    * @param  result              The result of the request:
    *                             <code>@link kOSReturnSuccess
    *                             kOSReturnSuccess@/link</code>
    *                             if the request was fulfilled;
    *                             <code>@link kOSKextReturnTimeout
    *                             kOSKextReturnTimeout@/link</code>
    *                             if the request has timed out;
    *                             <code>@link kOSKextReturnStopping
    *                             kOSKextReturnStopping@/link</code>
    *                             if the kext containing the callback
    *                             address for the kext is being unloaded;
    *                             or other values on error.
    * @param  resourceData        A pointer to the requested resource data.
    *                             Owned by the system; the kext should make a copy
    *                             if it needs to keep the data past the callback.
    * @param  resourceDataLength  The length of <code>resourceData</code>.
    * @param  context             The context pointer originally passed to
    *                             <code>@link OSKextRequestResource
    *                             OSKextRequestResource@/link</code>.
    */
   typedef void (* OSKextRequestResourceCallback)(
       OSKextRequestTag                requestTag,
       OSReturn                        result,
       const void                    * resourceData,
       uint32_t                        resourceDataLength,
       void                          * context);
   
   /*!
    * @function OSKextRequestResource
    *
    * @abstract
    * Requests data from a nonlocalized resource file in a kext bundle on disk.
    *
    * @param  kextIdentifier  The CFBundleIdentifier of the kext
    *                         from which to read the file.
    * @param  resourceName    The name of the resource file to read.
    * @param  callback        A pointer to a callback function; the address
    *                         must be within a currently-loaded kext.
    * @param  context         A pointer to arbitrary run-time data
    *                         that will be passed to the callback
    *                         when it is invoked. May be <code>NULL</code>.
    * @param  requestTagOut   If non-<code>NULL</code>,
    *                         filled on success with a tag identifying the
    *                         pending request; can be used with
    *                         <code>@link OSKextCancelRequest
    *                         OSKextCancelRequest@/link</code>.
    *
    * @result
    * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code>
    * if the request is successfully queued.
    * <code>@link kOSKextReturnInvalidArgument kOSKextReturnInvalidArgument@/link</code>
    * if <code>kextIdentifier</code> or <code>resourceName</code> or if
    * <code>callback</code> is not an address within a loaded kext executable.
    * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code>
    * if an unload attempt is being made
    * on the kext containing <code>callback</code>.
    * Other <code>OSKextReturn...</code> errors are possible.
    *
    * @discussion
    * This function queues a request to the user-space kext daemon
    * <code>@link //apple_ref/doc/man/8/kextd kextd(8)@/link</code>;
    * requests for resources early in system startup
    * will not be fulfilled until that daemon starts.
    * Note also that the localization context of the kext daemon
    * (namely tha tof the superuser)
    * will be used in retrieving resources;
    * kext resources intended for use in the kernel
    * should generally not be localized.
    *
    * <code>callback</code> is guaranteed to be invoked except when:
    * <ul>
    * <li>@link OSKextCancelRequest <code>OSKextCancelRequest</code>@/link
    *     is used to cancel the request.
    *     In this case the kext gets the <code>context</code> pointer
    *     and can clean it up.</li>
    * <li>The request is made during a kext's module start routine
    *     and the start routine returns an error.
    *     In this case, callbacks cannot be safely invoked, so
    *     the kext should clean up all request contexts
    *     when returning the error from the start routine.</li>
    * </ul>
    *
    * Kexts with pending requests are not subject to autounload,
    * but requests are subject to timeout after a few minutes.
    * If that amount of time passes with no response from user space,
    * <code>callback</code> is invoked with a result of.
    * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code>.
    *
    * Kexts that are explicitly unloaded have all pending request callbacks
    * invoked with a result of
    * <code>@link kOSKextReturnStopping kOSKextReturnStopping@/link</code>.
    * The kext must handle these callbacks,
    * even if its stop routine will prevent unloading.
    * If the kext does prevent unloading, it can reissue resource requests
    * outside of the stop function.
    */
   OSReturn OSKextRequestResource(
       const char                    * kextIdentifier,
       const char                    * resourceName,
       OSKextRequestResourceCallback   callback,
       void                          * context,
       OSKextRequestTag              * requestTagOut);
   
   /*!
    * @function OSKextCancelRequest
    *
    * @abstract
    * Cancels a pending user-space kext request without invoking the callback.
    *
    * @param  requestTag  A tag identifying a pending request.
    * @param  contextOut  If non-<code>NULL</code>, filled with the context pointer
    *                     originally passed with the request.
    *
    * @result
    * <code>@link kOSReturnSuccess kOSReturnSuccess@/link</code>
    * if the request is successfully canceled.
    * <code>@link kOSKextReturnNotFound kOSKextReturnNotFound@/link</code>
    * if <code>requestTag</code> does not identify any pending request.
    * Other <code>OSKextReturn...</code> errors are possible.
    *
    * @discussion
    * This function cancels a pending request if it exists,
    * so that its callback will not be invoked.
    * It returns in <code>contextOut</code>
    * the context pointer used to create the request
    * so that any resources allocated for the request can be cleaned up.
    *
    * Kexts do not need to cancel outstanding requests
    * in their module stop functions;
    * when a kext is unloaded, all pending request callbacks
    * are invoked with a result of
    * <code>@link kOSKextReturnTimeout kOSKextReturnTimeout@/link</code>
    * before the stop function is called.
    */
   OSReturn OSKextCancelRequest(
       OSKextRequestTag    requestTag,
       void             ** contextOut);
   
   
   #if (__x86_64__)
   
   #if PRAGMA_MARK
   #pragma mark -
   /********************************************************************/
   #pragma mark Weak linking
   /********************************************************************/
   #endif
   
   /*!
    * @group Weak Linking
    * Support for weak references to symbols in kexts.
    */
   
   /*!
    * @var gOSKextUnresolved
    *
    * @abstract 
    * The value to which a kext's unresolved, weakly-referenced symbols are bound.
    *
    * @discussion
    * A kext must test a weak symbol before using it.  A weak symbol 
    * is only safe to use if it is not equal to <code>gOSKextUnresolved</code>.
    *
    * Example for a weak symbol named <code>foo</code>:
    * <pre>
    * @textblock
    *      if (&foo != gOSKextUnresolved) {
    *          foo();
    *      } else {
    *          printf("foo() is not supported\n");
    *      }
    * @/textblock
    * </pre>
    */
   extern const void * gOSKextUnresolved;
   
   /*!
    * @define OSKextSymbolIsResolved
    *
    * @abstract 
    * Checks whether a weakly-referenced symbol has been resolved.
    *
    * @param weak_sym   The weak symbol to be tested for resolution.
    *
    * @result 
    * <code>TRUE</code> if weak_sym is resolved, or <code>FALSE</code> 
    * if weak_sym is unresolved.
    *
    * @discussion
    * This is a convenience macro for testing if weak symbols are resolved.
    * 
    * Example for a weak symbol named <code>foo</code>:
    * <pre>
    * @textblock
    *      if (OSKextSymbolIsResolved(foo)) {
    *          foo();
    *      } else {
    *          printf("foo() is not resolved\n");
    *      }
    * @/textblock
    * </pre>
    */
   #define OSKextSymbolIsResolved(weak_sym)        \
       (&(weak_sym) != gOSKextUnresolved)
   
   #endif /* (__x86_64__) */
   
   #endif /* KERNEL */
   
   __END_DECLS
   
   #endif /* _LIBKERN_OSKEXTLIB_H */

Cache object: 3fe258bbb040ac1bbaaa87f4df4338c6