1/*
2 * Copyright (c) 2008 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29#ifndef _LIBKERN_KEXT_REQUEST_KEYS_H
30#define _LIBKERN_KEXT_REQUEST_KEYS_H
31
32#ifdef __cplusplus
33extern "C" {
34#endif /* __cplusplus */
35
36/*********************************************************************
37* This file defines keys (and values) for properties in kext_request
38* collections and mkext archives used for loading in the kernel.
39* An incoming request is always a serialized XML plist with at least
40* a predicate, and optionally a dictionary of arguments.
41*
42* Some requests generate serialized XML plist responses, while others
43* return raw data. See the predicate description for more.
44*
45* All of these keys are strictly for internal run-time communication
46* between IOKitUser's OSKext module and xnu's OSKext class.
47* Keys and values may change at any time without notice.
48*********************************************************************/
49
50#if PRAGMA_MARK
51/********************************************************************/
52#pragma mark Top-Level Request Properties
53/********************************************************************/
54#endif
55
56/* The Predicate Key
57 * The value of this key indicates the operation to perform or the
58 * information desired.
59 */
60#define kKextRequestPredicateKey "Kext Request Predicate"
61
62/* The Arguments Key
63 * The value of this key is a dictionary containing the arguments
64 * for the request.
65 */
66#define kKextRequestArgumentsKey "Kext Request Arguments"
67
68#if PRAGMA_MARK
69/********************************************************************/
70#pragma mark Request Predicates - User-Space to Kernel
71/********************************************************************/
72#endif
73
74/*********************************************************************
75 * Nonprivileged requests from user -> kernel
76 *
77 * These requests do not require a privileged host port, as they just
78 * return information about loaded kexts.
79 **********/
80
81/* Predicate: Get Loaded Kext Info
82 * Argument: (None)
83 * Response: An array of information about loaded kexts (see OSKextLib.h).
84 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
85 *
86 * Retrieves an array of dictionaries whose properties describe every kext
87 * loaded at the time of the call.
88 */
89#define kKextRequestPredicateGetLoaded "Get Loaded Kext Info"
90
91/* Predicate: Get Loaded Kext Info By UUID
92 * Argument: (None)
93 * Response: An array of information about loaded kexts (see OSKextLib.h).
94 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
95 *
96 * Retrieves an array of dictionaries whose properties describe every kext
97 * loaded at the time of the call.
98 */
99#define kKextRequestPredicateGetLoadedByUUID "Get Loaded Kext Info By UUID"
100
101/* Predicate: Get Loaded Kext UUID By Address
102 * Argument: An address to lookup
103 * Response: A UUID of the kext
104 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
105 *
106 * Retrieves the uuid of a loaded kext in whose address range the given
107 * lookup address falls into.
108 */
109#define kKextRequestPredicateGetUUIDByAddress "Get Kext UUID by Address"
110
111/* Predicate: Get All Load Requests
112 * Argument: None
113 * Response: A set of bundle identifiers of all requested kext loads..
114 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
115 *
116 * Retrieves the bundle identifiers of all kexts that were requested to be
117 * loaded since power on.
118 *
119 */
120#define kKextRequestPredicateGetAllLoadRequests "Get All Load Requests"
121
122
123/*********************************************************************
124 * Privileged requests from user -> kernel
125 *
126 * These requests all do something with kexts in the kernel or to
127 * the OSKext system overall. The user-space caller of kext_request()
128 * must have access to a privileged host port or these requests result
129 * in an op_result of kOSKextReturnNotPrivileged.
130 **********/
131
132/* Predicate: Get Kernel Requests
133 * Argument: (None)
134 * Response: An array of kernel requests (see below).
135 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
136 *
137 * Retrieve the list of deferred load (and other) requests from OSKext.
138 * This predicate is reserved for kextd, and we may be enforcing access
139 * to the kextd process only.
140 */
141#define kKextRequestPredicateGetKernelRequests "Get Kernel Requests"
142
143/* Predicate: Load
144 * Argument: kKextRequestArgumentLoadRequestsKey
145 * Response: None (yet, may become an array of log message strings)
146 * Op result: OSReturn indicating processing/load+start result (see OSKextLib.h)
147 *
148 * Load one or more kexts per the load requests in the arguments dict.
149 * See kKextRequestArgumentLoadRequestsKey for more info.
150 */
151#define kKextRequestPredicateLoad "Load"
152
153/* Predicate: Start
154 * Argument: kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
155 * Response: None (yet, may become an array of log message strings)
156 * Op result: OSReturn indicating start result (see OSKextLib.h)
157 *
158 * Start a kext by bundle id. If it's already started, returns success.
159 * If a kext's dependencies need to be started, they are also started.
160 */
161#define kKextRequestPredicateStart "Start"
162
163/* Predicate: Stop
164 * Argument: kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
165 * Response: None (yet, may become an array of log message strings)
166 * Op result: OSReturn indicating stop result (see OSKextLib.h)
167 *
168 * Stop a kext by bundle id if it can be stoppoed.
169 * If it's already stopped, returns success.
170 * Does not attempt to stop dependents; that will return an error.
171 */
172#define kKextRequestPredicateStop "Stop"
173
174/* Predicate: Unload
175 * Argument: kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
176 * Response: None (yet, may become an array of log message strings)
177 * Op result: OSReturn indicating stop+unload result (see OSKextLib.h)
178 *
179 * Stop and unload a kext by bundle id if it can be.
180 * Does not attempt to stop dependents; that will return an error.
181 */
182#define kKextRequestPredicateUnload "Unload"
183
184#if PRAGMA_MARK
185/********************************************************************/
186#pragma mark Requests Predicates - Kernel to User Space (kextd)
187/********************************************************************/
188#endif
189/* Predicate: Send Resource
190 * Argument: kKextRequestArgumentRequestTagKey
191 * Argument: kKextRequestArgumentBundleIdentifierKey
192 * Argument: kKextRequestArgumentNameKey
193 * Argument: kKextRequestArgumentValueKey
194 * Argument: kKextRequestArgumentResult
195 * Response: None
196 * Op result: OSReturn indicating result (see OSKextLib.h)
197 *
198 * Retrieves a resource file from a kext bundle. The callback corresponding
199 * to the request will be invoked.
200 */
201#define kKextRequestPredicateSendResource "Send Resource"
202
203/*********************************************************************
204 * Kernel Requests: from the kernel or loaded kexts up to kextd
205 *
206 * These requests come from within the kernel, and kextd retrieves
207 * them using kKextRequestPredicateGetKernelRequests.
208 **********/
209
210/* Predicate: Kext Load Request
211 * Argument: kKextRequestArgumentBundleIdentifierKey
212 * Response: Asynchronous via a kKextRequestPredicateLoad from kextd
213 * Op result: OSReturn indicating result (see OSKextLib.h)
214 *
215 * Requests that kextd load the kext with the given identifier.
216 * When kexts loads the kext, it informs the IOCatalogue of the load.
217 * If the kext cannot be loaded, kextd or OSKext removes its personalities
218 * from the kernel.
219 */
220#define kKextRequestPredicateRequestLoad "Kext Load Request"
221
222/* Predicate: Kext Load Notification
223 * Argument: kext identifier
224 * Response: None
225 * Op result: OSReturn indicating result (see OSKextLib.h)
226 *
227 * Informs kextd that the kernel has successfully loaded and started
228 * a kext.
229 */
230#define kKextRequestPredicateLoadNotification "Kext Load Notification"
231
232/* Predicate: Kext Unload Notification
233 * Argument: kext identifier
234 * Response: None
235 * Op result: OSReturn indicating result (see OSKextLib.h)
236 *
237 * Informs kextd that the kernel has successfully stopped and unloaded
238 * a kext.
239 */
240#define kKextRequestPredicateUnloadNotification "Kext Unload Notification"
241
242/* Predicate: Prelinked Kernel Request
243 * Argument: None
244 * Response: None
245 * Op result: OSReturn indicating result (see OSKextLib.h)
246 *
247 * Notifies kextd that the kernel we booted from was not prelinked, therefore
248 * that kextd should try to create a prelinked kernel now.
249 */
250#define kKextRequestPredicateRequestPrelink "Kext Prelinked Kernel Request"
251
252/* Predicate: Kext Resource Request
253 * Argument: kKextRequestArgumentRequestTagKey
254 * Argument: kKextRequestArgumentBundleIdentifierKey
255 * Argument: kKextRequestArgumentNameKey
256 * Response: Asynchronous via a kKextRequestPredicateSendResource from kextd
257 * Op result: OSReturn indicating result (see OSKextLib.h)
258 *
259 * Requests a resource file from a kext bundle by identifier + filename.
260 */
261#define kKextRequestPredicateRequestResource "Kext Resource Request"
262
263/* Predicate: Kext Kextd Exit Request
264 * Argument: None
265 * Response: None
266 * Op result: OSReturn indicating result (see OSKextLib.h)
267 *
268 * Requests kextd exit for system shutdown.
269 */
270#define kKextRequestPredicateRequestKextdExit "Kextd Exit"
271
272#if PRAGMA_MARK
273/********************************************************************/
274#pragma mark -
275#pragma mark Generic Request Arguments
276/********************************************************************/
277#endif
278/* Argument: Kext Load Requests
279 * Type: Array of dictionaries (see Load Request Arguments below)
280 * Used by: kKextRequestPredicateLoad
281 *
282 * An array of dictionaries, each describing a single load operation to
283 * be performed with its options. A kext load request is effectively a
284 * nested series requests. Currently only one load request is embedded
285 * in a user-space Load request, so the result is unambiguous. We might
286 * change this, specifically for kextd, to allow all pending kernel
287 * load requests to be rolled up into one blob. Might not be much win
288 * in that, however. The nested logic makes the code difficult to read.
289 */
290#define kKextRequestArgumentLoadRequestsKey "Kext Load Requests"
291
292/* Argument: CFBundleIdentifier
293 * Type: String
294 * Used by: several
295 *
296 * Any request that takes a bundle identifier uses this key.
297 */
298#define kKextRequestArgumentBundleIdentifierKey "CFBundleIdentifier"
299
300/* Argument: OSReturn
301 * Type: Dictionary
302 * Used by: OSKext::copyInfo()
303 *
304 * Used to specify a subset of all possible info to be returned.
305 */
306#define kKextRequestArgumentInfoKeysKey "Kext Request Info Keys"
307
308/* Argument: OSReturn
309 * Type: Number (OSReturn)
310 * Used by: several
311 *
312 * Contains the OSReturn/kern_return_t result of the request.
313 */
314#define kKextRequestArgumentResultKey "Kext Request Result Code"
315
316/* Argument: Address
317 * Type: Number (OSReturn)
318 * Used by: OSKextGetUUIDByAddress
319 *
320 * Contains the address that needs to be looked up
321 */
322#define kKextRequestArgumentLookupAddressKey "Kext Request Lookup Address"
323
324/* Argument: Value
325 * Type: Varies with the predicate
326 * Used by: several
327 *
328 * Used for all the Set-Enabled predicates, and also for Send Resource (OSData).
329 */
330#define kKextRequestArgumentValueKey "Value"
331
332/* Argument: Filename
333 * Type: String
334 * Used by: kKextRequestPredicateSendResource
335 *
336 * Names the resource being sent to the kext
337 */
338#define kKextRequestArgumentNameKey "Name"
339
340/* Argument: Filename
341 * Type: Data
342 * Used by: kKextRequestPredicateSendResource
343 *
344 * Contains the contents of the resource file being sent.
345 */
346#define kKextRequestArgumentFileContentsKey "File Contents"
347
348/* Argument: Delay Autounload
349 * Type: Boolean
350 * Default: false
351 *
352 * Normally all kexts loaded are subject to normal autounload behavior:
353 * when no OSMetaClass instances remain for a kext that defines an IOService
354 * subclass, or when a non-IOService kext turns on autounload and its reference
355 * count drops to zero (external) references.
356 *
357 * Setting this property to true in a load request makes the kext being loaded
358 * skip ONE autounload pass, giving about an extra minute of time before the
359 * kext is subject to autounload. This is how kextutil(8) to delays autounload
360 * so that there's more time to set up a debug session.
361 *
362 * Setting this property in any other request causes OSKext::considerUnloads()
363 * to be called before processing the request, ensuring a window where kexts
364 * will not be unloaded. The user-space kext library uses this so that it can
365 * avoid including kexts that are already loaded in a load request.
366 */
367#define kKextRequestArgumentDelayAutounloadKey "Delay Autounload"
368
369#if PRAGMA_MARK
370#pragma mark Load Request Arguments
371#endif
372
373/*********************************************************************
374 * Kext Load Request Properties
375 *
376 * In addition to a bundle identifier, load requests can contain
377 * these optional keys.
378 *
379 * These properties are used primarily by kextutil(8) to alter default
380 * load behavior, but the OSKext user-level library makes them all
381 * available in OSKextLoadWithOptions().
382 **********/
383
384/* Argument: StartExclude
385 * Type: Integer, corresponding to OSKextExcludeLevel
386 * Default: kOSKextExcludeNone if not specified
387 *
388 * Normally all kexts in the load list for a load request are started.
389 * This property is used primarily by kextutil(8) to delay start of
390 * either the primary kext, or the whole load list (any that weren't
391 * already loaded & started).
392 */
393#define kKextRequestArgumentStartExcludeKey "Start Exclude Level"
394
395/* Argument: Start Matching Exclude Level
396 * Type: Integer, corresponding to OSKextExcludeLevel
397 * Default: kOSKextExcludeAll if not specified
398 *
399 * Normally no personalities are sent to the IOCatalogue for a regular
400 * kext load; the assumption is that they are already there and triggered
401 * the load request in the first place.
402 *
403 * This property is used primarily by kextutil(8) to delay matching for
404 * either the primary kext, or the whole load list (any that didn't
405 * already have personalities in the IOCatalogue).
406 */
407#define kKextRequestArgumentStartMatchingExcludeKey "Start Matching Exclude Level"
408
409// see also Delay Autounload
410
411/* Argument: Personality Names
412 * Type: Array of strings
413 * Default: All personalities are used
414 *
415 * Normally when personalities are sent to the IOCatalogue, they are all sent.
416 * This property restricts the personalities sent, for the primary kext
417 * being loaded, to those named. Personalities for dependencies are all sent,
418 * and there is currently no mechanism to filter them.
419 *
420 * This property is used primarily by kextutil(8) to help debug matching
421 * problems.
422 */
423#define kKextRequestArgumentPersonalityNamesKey "Personality Names"
424
425#if PRAGMA_MARK
426#pragma mark Unload Request Arguments
427#endif
428
429/* Argument: Terminate
430 * Type: Boolean
431 * Default: false
432 *
433 * An unload request may optionally specify via this key that all IOService
434 * objects are to be terminated before attempting to unload. Kexts with
435 * dependents will not attempt to terminate and will return kOSKextReturnInUse.
436 */
437#define kKextRequestArgumentTerminateIOServicesKey "Terminate IOServices"
438
439#if PRAGMA_MARK
440#pragma mark Internal Tracking Properties
441#endif
442/*********************************************************************
443 * Internal Tracking Properties
444 **********/
445
446/* Argument: Request Tag
447 * Type: Number (uint32_t)
448 * Used by: internal tracking for requests with callbacks
449 *
450 * Most requests to get resources (files) use this.
451 */
452#define kKextRequestArgumentRequestTagKey "Request Tag"
453
454/* Argument: Request Callback
455 * Type: Data (pointer)
456 * Used by: internal tracking
457 *
458 * Most requests to get resources (files) use this.
459 */
460#define kKextRequestArgumentCallbackKey "Request Callback"
461
462/* Argument: Request context.
463 * Type: OSData (wraps a void *)
464 * Used by: several
465 */
466#define kKextRequestArgumentContextKey "Context"
467
468/* Argument: Request Stale
469 * Type: Boolean
470 * Used by: internal tracking
471 *
472 * _OSKextConsiderUnloads sets this on any callback record lacking
473 * it, and deletes any callback record that has it.
474 */
475#define kKextRequestStaleKey "Request Stale"
476
477#ifdef __cplusplus
478};
479#endif /* __cplusplus */
480
481#endif /* _LIBKERN_KEXT_REQUEST_KEYS_H */
482