libkern/OSKextLib.h Kernel.framework

Define C-string versions of the CFBundle keys for use in the kernel.

#define kCFBundleIdentifierKey "CFBundleIdentifier"

OSKextLoadTag OSKextGetCurrentLoadTag(void)

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

const char * OSKextGetCurrentIdentifier(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 * OSKextGetCurrentVersionString(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.

OSReturn OSKextLoadKextWithIdentifier(const char * kextIdentifier)

@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 OSKextRetainKextWithLoadTag(OSKextLoadTag loadTag)

@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 OSKextReleaseKextWithLoadTag(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.

@typedef OSKextRequestTag @abstract Identifies a kext request made to user space.

typedef uint32_t OSKextRequestTag

@define kOSKextRequestTagInvalid @abstract A request tag value that will never be used for a kext request; indicates failure to create/queue the request.

#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 (*)(OSKextRequestTag, OSReturn, const void *, uint32_t, void *) OSKextRequestResourceCallback;

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

@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 (or on failure with <code>@link kOSKextRequestTagInvalid kOSKextRequestTagInvalid@/link</code>; 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 an asynchronous 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. Requests made by a kext while that kext is loading (specifically in the kext's module start routine) will not be fulfilled until after the start routine returns and the kext is completely loaded. Kexts requesting resources should be sure to perform appropriate locking in the callback function. Kext resources are stored in the kext's on-disk bundle under the Resources subdirectory. See {@linkdoc //apple_ref/doc/uid/10000123i Bundle Programming Guide} for an overview of bundle structure. The localization context of the kext daemon (namely that of 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 OSKextCancelRequest(OSKextRequestTag requestTag, void ** contextOut)

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

int OSKextGrabPgoData(
	uuid_t uuid,
	uint64_t *pSize,
	char *pBuffer,
	uint64_t bufferSize,
	int wait_for_unload,
	int metadata
)

@function OSKextGrabPgoData @abstract Grab a LLVM profile data buffer from a loaded kext. @param uuid the uuid identifying the kext to retrieve data from @param pSize pointer of where to store the size of the buffer. May be NULL. @param pBuffer pointer to the output buffer. May be NULL. @param bufferSize size of the buffer pointed to by pBuffer @param wait_for_unload (boolean) sleep until the kext is unloaded @param metadata (boolean) include metadata footer @result 0 on success ENOTSUP if the kext does not have profile data to retrieve. ENOTSUP if no kext with the given UUID is found ERRORS if the provided buffer is too small EIO internal error, such as if __llvm_profile_write_buffer_internal fails

void OSKextResetPgoCountersLock(void)

@function OSKextResetPgoCountersLock @abstract Call this function before trapping into the debugger to call OSKextResetPgoCounters.

void OSKextResetPgoCountersUnlock(void)

@function OSKextResetPgoCountersUnlock @abstract Call this function after trapping into the debugger to call OSKextResetPgoCounters.

void OSKextResetPgoCounters(void)

@function OSKextResetPgoCounters @abstract Reset the PGO counters for all kexts. Call only from debugger context, while holding OSKextResetPgoCountersLock().

@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 * const 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)