Overview

Declares functions, basic return values, and other constants related to kernel extensions (kexts).

Weak Linking

Group members:

Kext Property List Values

Group members:

OSReturn Values for Kernel Extensions

Group members:

Kext Loading C Functions

Group members:

Kext Information

Group members:

Kext Property List Keys

Group members:

Functions

OSKextCancelRequest

Cancels a pending user-space kext request without invoking the callback.

OSKextGetCurrentIdentifier

Returns the CFBundleIdentifier for the calling kext as a C string.

OSKextGetCurrentLoadTag

Returns the run-time load tag for the calling kext as an OSKextLoadTag.

OSKextGetCurrentVersionString

Returns the CFBundleVersion for the calling kext as a C string.

OSKextLoadKextWithIdentifier

Request that a kext be loaded.

OSKextReleaseKextWithLoadTag

Release a loaded kext based on its load tag.

OSKextRequestResource

Requests data from a nonlocalized resource file in a kext bundle on disk.

OSKextRetainKextWithLoadTag

Retain a loaded kext based on its load tag, and enable autounload for that kext.

Cancels a pending user-space kext request without invoking the callback.

OSReturn OSKextCancelRequest( 
    OSKextRequestTag requestTag, 
    void **contextOut);  

Parameters

Return Value

kOSReturnSuccess if the request is successfully canceled. kOSKextReturnNotFound if requestTag does not identify any pending request. Other OSKextReturn... errors are possible.

Discussion

This function cancels a pending request if it exists, so that its callback will not be invoked. It returns in contextOut 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 kOSKextReturnTimeout before the stop function is called.

Returns the CFBundleIdentifier for the calling kext as a C string.

const char * OSKextGetCurrentIdentifier(
    void);  

Return Value

The CFBundleIdentifier for the calling kext as a C string.

Returns the run-time load tag for the calling kext as an OSKextLoadTag.

OSKextLoadTag OSKextGetCurrentLoadTag(
    void);  

Return Value

The run-time load tag for the calling kext as an OSKextLoadTag.

Discussion

The load tag identifies this loaded instance of the kext to the kernel and to kernel functions that operate on kexts.

Returns the CFBundleVersion for the calling kext as a C string.

const char * OSKextGetCurrentVersionString(
    void);  

Return Value

The CFBundleVersion for the calling kext as a C string.

Request that a kext be loaded.

OSReturn OSKextLoadKextWithIdentifier(
    const char *kextIdentifier);  

Parameters

Return Value

kOSReturnSuccess if the kext was loaded (or was already loaded). kOSKextReturnDeferred if the kext was not found and a request was queued to kextd(8). 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 kextd(8) and kOSKextReturnDeferred is returned. There is no general notification or callback mechanism for load requests.

Release a loaded kext based on its load tag.

OSReturn OSKextReleaseKextWithLoadTag(
    OSKextLoadTag loadTag);  

Parameters

Return Value

kOSReturnSuccess if the kext was released. kOSKextReturnNotFound if the kext was not found. kOSKextReturnInvalidArgument if loadTag is kOSKextInvalidLoadTag.

Discussion

The kext should have been retained previously via OSKextRetainKextWithLoadTag.

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 IOService 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 OSKextGetCurrentLoadTag.

Kexts should not retain and release other kexts; linkage references are accounted for internally.

Requests data from a nonlocalized resource file in a kext bundle on disk.

OSReturn OSKextRequestResource( 
    const char *kextIdentifier, 
    const char *resourceName, 
    OSKextRequestResourceCallback callback, 
    void *context, 
    OSKextRequestTag *requestTagOut);  

Parameters

Return Value

kOSReturnSuccess if the request is successfully queued. kOSKextReturnInvalidArgument if kextIdentifier or resourceName or if callback is not an address within a loaded kext executable. kOSKextReturnStopping if an unload attempt is being made on the kext containing callback. Other OSKextReturn... errors are possible.

Discussion

This function queues a request to the user-space kext daemon kextd(8); 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.

callback is guaranteed to be invoked except when:

• OSKextCancelRequest is used to cancel the request. In this case the kext gets the context pointer and can clean it up.

• 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.

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, callback is invoked with a result of. kOSKextReturnTimeout.

Kexts that are explicitly unloaded have all pending request callbacks invoked with a result of kOSKextReturnStopping. 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.

Retain a loaded kext based on its load tag, and enable autounload for that kext.

OSReturn OSKextRetainKextWithLoadTag(
    OSKextLoadTag loadTag);  

Parameters

Return Value

kOSReturnSuccess if the kext was retained. kOSKextReturnNotFound if the kext was not found. kOSKextReturnInvalidArgument if loadTag is kOSKextInvalidLoadTag.

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 IOService 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 OSKextGetCurrentLoadTag.

Kexts should not retain and release other kexts; linkage references are accounted for internally.

Constants

gOSKextUnresolved

The value to which a kext's unresolved, weakly-referenced symbols are bound.

The value to which a kext's unresolved, weakly-referenced symbols are bound.

extern const void * gOSKextUnresolved;  

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 gOSKextUnresolved.

Example for a weak symbol named foo:

 
      if (&foo != gOSKextUnresolved) {
          foo();
      } else {
          printf("foo() is not supported\n");
      }
 
 

Typedefs

OSKextLoadTag

A unique identifier assigned to a loaded instanace of a kext.

OSKextRequestResourceCallback

Invoked to provide results for a kext resource request.

OSKextRequestTag

Identifies a kext request made to user space.

A unique identifier assigned to a loaded instanace of a kext.

typedef uint32_t OSKextLoadTag;  

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 kmod_info_t structure passed into its module start routine, as the id field (cast to this type). You can use the load tag with the functions OSKextRetainKextWithLoadTag and OSKextReleaseKextWithLoadTag.

Invoked to provide results for a kext resource request.

typedef void ( *OSKextRequestResourceCallback)( 
    OSKextRequestTag requestTag, 
    OSReturn result, 
    const void *resourceData, 
    uint32_t resourceDataLength, 
    void *context);  

Fields

Identifies a kext request made to user space.

typedef uint32_t OSKextRequestTag;  

Macro Definitions

kIOKitPersonalitiesKey

A dictionary of dictionaries used in matching for I/O Kit drivers.

kOSBundleAllowUserLoadKey

A boolean value indicating whether kextcache(8) will honor a non-root process's request to load a kext.

kOSBundleCompatibleVersionKey

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').

kOSBundleEnableKextLoggingKey

Set to true to have the kernel kext logging spec applied to the kext. See OSKextLogSpec.

kOSBundleIsInterfaceKey

A boolean value indicating whether the kext executable contains only symbol references.

kOSBundleLibrariesKey

A dictionary listing link dependencies for this kext. Keys are bundle identifiers, values are version strings.

kOSBundleRequiredConsole

This OSBundleRequired value indicates that the kext may be needed for console access (specifically in a single-user startup when kextd(8). does not run) and should be loaded during early startup.

kOSBundleRequiredKey

A string indicating in which kinds of startup this kext may need to load during early startup (before kextcache(8)).

kOSBundleRequiredLocalRoot

This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem when starting from a local disk.

kOSBundleRequiredNetworkRoot

This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem when starting over a network connection.

kOSBundleRequiredRoot

This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem whether starting from a local or a network volume.

kOSBundleRequiredSafeBoot

This OSBundleRequired 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.

kOSBundleSharedExecutableIdentifierKey

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.

kOSKernelResourceKey

A boolean value indicating whether the kext represents a built-in component of the kernel.

kOSKextInvalidLoadTag

A load tag value that will never be used for a loaded kext; indicates kext not found.

kOSKextKernelIdentifier

This is the CFBundleIdentifier user for the kernel itself.

kOSKextReturnArchNotFound

Kext does not contain code for the requested architecture.

kOSKextReturnAuthentication

Authetication failures encountered; check diagnostics for details.

kOSKextReturnBadData

Malformed data (not used for XML).

kOSKextReturnBootLevel

Kext not loadable or operation not allowed at current boot level.

kOSKextReturnCache

An error occurred processing a system kext cache.

kOSKextReturnDeferred

Operation has been posted asynchronously to user space (kernel only).

kOSKextReturnDependencies

Dependency resolution failures encountered; check diagnostics for details.

kOSKextReturnDependencyLoadError

A load error occurred on a dependency of the kext being loaded.

kOSKextReturnDisabled

Operation is currently disabled.

kOSKextReturnInternalError

An internal error in the kext library. Contrast with OSReturnError.

kOSKextReturnInUse

The kext is currently in use or has outstanding references, and cannot be unloaded.

kOSKextReturnInvalidArgument

Invalid argument.

kOSKextReturnLinkError

A link failure occured with this kext or a dependency.

kOSKextReturnLoadedVersionDiffers

A different version (or executable UUID, or executable by checksum) of the requested kext is already loaded.

kOSKextReturnNoMemory

Memory allocation failed.

kOSKextReturnNoResources

Some resource other than memory (such as available load tags) is exhausted.

kOSKextReturnNotAKext

Bundle is not a kernel extension.

kOSKextReturnNotFound

Search item not found.

kOSKextReturnNotLoadable

Kext cannot be loaded; check diagnostics for details.

kOSKextReturnNotPrivileged

The caller lacks privileges to perform the requested operation.

kOSKextReturnSerialization

Error converting or (un)serializing URL, string, or XML.

kOSKextReturnStartStopError

The kext start or stop routine returned an error.

kOSKextReturnStopping

The kext is in the process of stopping; requests cannot be made.

kOSKextReturnTimeout

A kext request has timed out.

kOSKextReturnUnsupported

Operation is no longer or not yet supported.

kOSKextReturnValidation

Validation failures encountered; check diagnostics for details.

OSKextSymbolIsResolved

Checks whether a weakly-referenced symbol has been resolved.

A dictionary of dictionaries used in matching for I/O Kit drivers.

#define kIOKitPersonalitiesKey "IOKitPersonalities" 

A boolean value indicating whether kextcache(8) will honor a non-root process's request to load a kext.

#define kOSBundleAllowUserLoadKey "OSBundleAllowUserLoad" 

Discussion

See KextManagerLoadKextWithURL and KextManagerLoadKextWithIdentifier.

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" 

Set to true to have the kernel kext logging spec applied to the kext. See OSKextLogSpec.

#define kOSBundleEnableKextLoggingKey "OSBundleEnableKextLogging" 

A boolean value indicating whether the kext executable contains only symbol references.

#define kOSBundleIsInterfaceKey "OSBundleIsInterface" 

A dictionary listing link dependencies for this kext. Keys are bundle identifiers, values are version strings.

#define kOSBundleLibrariesKey "OSBundleLibraries" 

This OSBundleRequired value indicates that the kext may be needed for console access (specifically in a single-user startup when kextd(8). does not run) and should be loaded during early startup.

#define kOSBundleRequiredConsole "Console" 

A string indicating in which kinds of startup this kext may need to load during early startup (before kextcache(8)).

#define kOSBundleRequiredKey "OSBundleRequired" 

Discussion

The value is one of:

• "OSBundleRequiredRoot"

• "OSBundleRequiredLocalRoot"

• "OSBundleRequiredNetworkRoot"

• "OSBundleRequiredSafeBoot"

• "OSBundleRequiredConsole"

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.

This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem when starting from a local disk.

#define kOSBundleRequiredLocalRoot "Local-Root" 

This OSBundleRequired value indicates that the kext may be needed to mount the root filesystem when starting over a network connection.

#define kOSBundleRequiredNetworkRoot "Network-Root" 

This OSBundleRequired 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" 

This OSBundleRequired 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" 

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" 

A boolean value indicating whether the kext represents a built-in component of the kernel.

#define kOSKernelResourceKey "OSKernelResource" 

A load tag value that will never be used for a loaded kext; indicates kext not found.

#define kOSKextInvalidLoadTag  

This is the CFBundleIdentifier user for the kernel itself.

#define kOSKextKernelIdentifier "__kernel__" 

Kext does not contain code for the requested architecture.

#define kOSKextReturnArchNotFound libkern_kext_err(0xf) 

Authetication failures encountered; check diagnostics for details.

#define kOSKextReturnAuthentication libkern_kext_err(0xd) 

Malformed data (not used for XML).

#define kOSKextReturnBadData libkern_kext_err(0x7) 

Kext not loadable or operation not allowed at current boot level.

#define kOSKextReturnBootLevel libkern_kext_err(0x12) 

An error occurred processing a system kext cache.

#define kOSKextReturnCache libkern_kext_err(0x10) 

Operation has been posted asynchronously to user space (kernel only).

#define kOSKextReturnDeferred libkern_kext_err(0x11) 

Dependency resolution failures encountered; check diagnostics for details.

#define kOSKextReturnDependencies libkern_kext_err(0xe) 

A load error occurred on a dependency of the kext being loaded.

#define kOSKextReturnDependencyLoadError libkern_kext_err(0x15) 

Operation is currently disabled.

#define kOSKextReturnDisabled libkern_kext_err(0xa) 

An internal error in the kext library. Contrast with OSReturnError.

#define kOSKextReturnInternalError libkern_kext_err(0x1) 

The kext is currently in use or has outstanding references, and cannot be unloaded.

#define kOSKextReturnInUse libkern_kext_err(0x18) 

Invalid argument.

#define kOSKextReturnInvalidArgument libkern_kext_err(0x5) 

A link failure occured with this kext or a dependency.

#define kOSKextReturnLinkError libkern_kext_err(0x16) 

A different version (or executable UUID, or executable by checksum) of the requested kext is already loaded.

#define kOSKextReturnLoadedVersionDiffers libkern_kext_err(0x14) 

Memory allocation failed.

#define kOSKextReturnNoMemory libkern_kext_err(0x2) 

Some resource other than memory (such as available load tags) is exhausted.

#define kOSKextReturnNoResources libkern_kext_err(0x3) 

Bundle is not a kernel extension.

#define kOSKextReturnNotAKext libkern_kext_err(0xb) 

Search item not found.

#define kOSKextReturnNotFound libkern_kext_err(0x6) 

Kext cannot be loaded; check diagnostics for details.

#define kOSKextReturnNotLoadable libkern_kext_err(0x13) 

The caller lacks privileges to perform the requested operation.

#define kOSKextReturnNotPrivileged libkern_kext_err(0x4) 

Error converting or (un)serializing URL, string, or XML.

#define kOSKextReturnSerialization libkern_kext_err(0x8) 

The kext start or stop routine returned an error.

#define kOSKextReturnStartStopError libkern_kext_err(0x17) 

The kext is in the process of stopping; requests cannot be made.

#define kOSKextReturnStopping libkern_kext_err(0x1a) 

A kext request has timed out.

#define kOSKextReturnTimeout libkern_kext_err(0x19) 

Operation is no longer or not yet supported.

#define kOSKextReturnUnsupported libkern_kext_err(0x9) 

Validation failures encountered; check diagnostics for details.

#define kOSKextReturnValidation libkern_kext_err(0xc) 

Checks whether a weakly-referenced symbol has been resolved.

#define OSKextSymbolIsResolved(weak_sym) \ 
    (&(weak_sym) != gOSKextUnresolved) 

Parameters

Return Value

TRUE if weak_sym is resolved, or FALSE if weak_sym is unresolved.

Discussion

This is a convenience macro for testing if weak symbols are resolved.

Example for a weak symbol named foo:

 
      if (OSKextSymbolIsResolved(foo)) {
          foo();
      } else {
          printf("foo() is not resolved\n");
      }
 
 

Last Updated: 2010-07-29