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 All Load Requests
92 * Argument:  None
93 * Response:  A set of bundle identifiers of all requested kext loads..
94 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
95 *
96 * Retrieves the bundle identifiers of all kexts that were requested to be
97 * loaded since power on.
98 *
99 */
100#define kKextRequestPredicateGetAllLoadRequests    "Get All Load Requests"
101
102
103/*********************************************************************
104 * Privileged requests from user -> kernel
105 *
106 * These requests all do something with kexts in the kernel or to
107 * the OSKext system overall. The user-space caller of kext_request()
108 * must have access to a privileged host port or these requests result
109 * in an op_result of kOSKextReturnNotPrivileged.
110 **********/
111
112/* Predicate: Get Kernel Requests
113 * Argument:  (None)
114 * Response:  An array of kernel requests (see below).
115 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
116 *
117 * Retrieve the list of deferred load (and other) requests from OSKext.
118 * This predicate is reserved for kextd, and we may be enforcing access
119 * to the kextd process only.
120 */
121#define kKextRequestPredicateGetKernelRequests     "Get Kernel Requests"
122
123/* Predicate: Load
124 * Argument:  kKextRequestArgumentLoadRequestsKey
125 * Response:  None (yet, may become an array of log message strings)
126 * Op result: OSReturn indicating processing/load+start result (see OSKextLib.h)
127 *
128 * Load one or more kexts per the load requests in the arguments dict.
129 * See kKextRequestArgumentLoadRequestsKey for more info.
130 */
131#define kKextRequestPredicateLoad                  "Load"
132
133/* Predicate: Start
134 * Argument:  kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
135 * Response:  None (yet, may become an array of log message strings)
136 * Op result: OSReturn indicating start result (see OSKextLib.h)
137 *
138 * Start a kext by bundle id. If it's already started, returns success.
139 * If a kext's dependencies need to be started, they are also started.
140 */
141#define kKextRequestPredicateStart                 "Start"
142
143/* Predicate: Stop
144 * Argument:  kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
145 * Response:  None (yet, may become an array of log message strings)
146 * Op result: OSReturn indicating stop result (see OSKextLib.h)
147 *
148 * Stop a kext by bundle id if it can be stoppoed.
149 * If it's already stopped, returns success.
150 * Does not attempt to stop dependents; that will return an error.
151 */
152#define kKextRequestPredicateStop                  "Stop"
153
154/* Predicate: Unload
155 * Argument:  kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
156 * Response:  None (yet, may become an array of log message strings)
157 * Op result: OSReturn indicating stop+unload result (see OSKextLib.h)
158 *
159 * Stop and unload a kext by bundle id if it can be.
160 * Does not attempt to stop dependents; that will return an error.
161 */
162#define kKextRequestPredicateUnload                "Unload"
163
164#if PRAGMA_MARK
165/********************************************************************/
166#pragma mark Requests Predicates - Kernel to User Space (kextd)
167/********************************************************************/
168#endif
169/* Predicate: Send Resource
170 * Argument:  kKextRequestArgumentRequestTagKey
171 * Argument:  kKextRequestArgumentBundleIdentifierKey
172 * Argument:  kKextRequestArgumentNameKey
173 * Argument:  kKextRequestArgumentValueKey
174 * Argument:  kKextRequestArgumentResult
175 * Response:  None
176 * Op result: OSReturn indicating result (see OSKextLib.h)
177 *
178 * Retrieves a resource file from a kext bundle. The callback corresponding
179 * to the request will be invoked.
180 */
181#define kKextRequestPredicateSendResource          "Send Resource"
182
183/*********************************************************************
184 * Kernel Requests: from the kernel or loaded kexts up to kextd
185 *
186 * These requests come from within the kernel, and kextd retrieves
187 * them using kKextRequestPredicateGetKernelRequests.
188 **********/
189
190/* Predicate: Kext Load Request
191 * Argument:  kKextRequestArgumentBundleIdentifierKey
192 * Response:  Asynchronous via a kKextRequestPredicateLoad from kextd
193 * Op result: OSReturn indicating result (see OSKextLib.h)
194 *
195 * Requests that kextd load the kext with the given identifier.
196 * When kexts loads the kext, it informs the IOCatalogue of the load.
197 * If the kext cannot be loaded, kextd or OSKext removes its personalities
198 * from the kernel.
199 */
200#define kKextRequestPredicateRequestLoad           "Kext Load Request"
201
202/* Predicate: Kext Load Notification
203 * Argument:  kext identifier
204 * Response:  None
205 * Op result: OSReturn indicating result (see OSKextLib.h)
206 *
207 * Informs kextd that the kernel has successfully loaded and started
208 * a kext.
209 */
210#define kKextRequestPredicateLoadNotification      "Kext Load Notification"
211
212/* Predicate: Kext Unload Notification
213 * Argument:  kext identifier
214 * Response:  None
215 * Op result: OSReturn indicating result (see OSKextLib.h)
216 *
217 * Informs kextd that the kernel has successfully stopped and unloaded
218 * a kext.
219 */
220#define kKextRequestPredicateUnloadNotification    "Kext Unload Notification"
221
222/* Predicate: Prelinked Kernel Request
223 * Argument:  None
224 * Response:  None
225 * Op result: OSReturn indicating result (see OSKextLib.h)
226 *
227 * Notifies kextd that the kernel we booted from was not prelinked, therefore
228 * that kextd should try to create a prelinked kernel now.
229 */
230#define kKextRequestPredicateRequestPrelink        "Kext Prelinked Kernel Request"
231
232/* Predicate: Kext Resource Request
233 * Argument:  kKextRequestArgumentRequestTagKey
234 * Argument:  kKextRequestArgumentBundleIdentifierKey
235 * Argument:  kKextRequestArgumentNameKey
236 * Response:  Asynchronous via a kKextRequestPredicateSendResource from kextd
237 * Op result: OSReturn indicating result (see OSKextLib.h)
238 *
239 * Requests a resource file from a kext bundle by identifier + filename.
240 */
241#define kKextRequestPredicateRequestResource       "Kext Resource Request"
242
243/* Predicate: Kext Kextd Exit Request
244 * Argument:  None
245 * Response:  None
246 * Op result: OSReturn indicating result (see OSKextLib.h)
247 *
248 * Requests kextd exit for system shutdown.
249 */
250#define kKextRequestPredicateRequestKextdExit    "Kextd Exit"
251
252#if PRAGMA_MARK
253/********************************************************************/
254#pragma mark -
255#pragma mark Generic Request Arguments
256/********************************************************************/
257#endif
258/* Argument:  Kext Load Requests
259 * Type:      Array of dictionaries (see Load Request Arguments below)
260 * Used by:   kKextRequestPredicateLoad
261 *
262 * An array of dictionaries, each describing a single load operation to
263 * be performed with its options. A kext load request is effectively a
264 * nested series requests. Currently only one load request is embedded
265 * in a user-space Load request, so the result is unambiguous. We might
266 * change this, specifically for kextd, to allow all pending kernel
267 * load requests to be rolled up into one blob. Might not be much win
268 * in that, however. The nested logic makes the code difficult to read.
269 */
270#define kKextRequestArgumentLoadRequestsKey        "Kext Load Requests"
271
272/* Argument:  CFBundleIdentifier
273 * Type:      String
274 * Used by:   several
275 *
276 * Any request that takes a bundle identifier uses this key.
277 */
278#define kKextRequestArgumentBundleIdentifierKey    "CFBundleIdentifier"
279
280/* Argument:  OSReturn
281 * Type:      Dictionary
282 * Used by:   OSKext::copyInfo()
283 *
284 * Used to specify a subset of all possible info to be returned.
285 */
286#define kKextRequestArgumentInfoKeysKey          "Kext Request Info Keys"
287
288/* Argument:  OSReturn
289 * Type:      Number (OSReturn)
290 * Used by:   several
291 *
292 * Contains the OSReturn/kern_return_t result of the request.
293 */
294#define kKextRequestArgumentResultKey              "Kext Request Result Code"
295
296/* Argument:  Value
297 * Type:      Varies with the predicate
298 * Used by:   several
299 *
300 * Used for all the Set-Enabled predicates, and also for Send Resource (OSData).
301 */
302#define kKextRequestArgumentValueKey               "Value"
303
304/* Argument:  Filename
305 * Type:      String
306 * Used by:   kKextRequestPredicateSendResource
307 *
308 * Names the resource being sent to the kext
309 */
310#define kKextRequestArgumentNameKey                "Name"
311
312/* Argument:  Filename
313 * Type:      Data
314 * Used by:   kKextRequestPredicateSendResource
315 *
316 * Contains the contents of the resource file being sent.
317 */
318#define kKextRequestArgumentFileContentsKey        "File Contents"
319
320/* Argument:  Delay Autounload
321 * Type:      Boolean
322 * Default:   false
323 *
324 * Normally all kexts loaded are subject to normal autounload behavior:
325 * when no OSMetaClass instances remain for a kext that defines an IOService
326 * subclass, or when a non-IOService kext turns on autounload and its reference
327 * count drops to zero (external) references.
328 *
329 * Setting this property to true in a load request makes the kext being loaded
330 * skip ONE autounload pass, giving about an extra minute of time before the
331 * kext is subject to autounload. This is how kextutil(8) to delays autounload
332 * so that there's more time to set up a debug session.
333 *
334 * Setting this property in any other request causes OSKext::considerUnloads()
335 * to be called before processing the request, ensuring a window where kexts
336 * will not be unloaded. The user-space kext library uses this so that it can
337 * avoid including kexts that are already loaded in a load request.
338 */
339#define kKextRequestArgumentDelayAutounloadKey         "Delay Autounload"
340
341#if PRAGMA_MARK
342#pragma mark Load Request Arguments
343#endif
344
345/*********************************************************************
346 * Kext Load Request Properties
347 *
348 * In addition to a bundle identifier, load requests can contain
349 * these optional keys.
350 *
351 * These properties are used primarily by kextutil(8) to alter default
352 * load behavior, but the OSKext user-level library makes them all
353 * available in OSKextLoadWithOptions().
354 **********/
355
356/* Argument:  StartExclude
357 * Type:      Integer, corresponding to OSKextExcludeLevel
358 * Default:   kOSKextExcludeNone if not specified
359 *
360 * Normally all kexts in the load list for a load request are started.
361 * This property is used primarily by kextutil(8) to delay start of
362 * either the primary kext, or the whole load list (any that weren't
363 * already loaded & started).
364 */
365#define kKextRequestArgumentStartExcludeKey        "Start Exclude Level"
366
367/* Argument:  Start Matching Exclude Level
368 * Type:      Integer, corresponding to OSKextExcludeLevel
369 * Default:   kOSKextExcludeAll if not specified
370 *
371 * Normally no personalities are sent to the IOCatalogue for a regular
372 * kext load; the assumption is that they are already there and triggered
373 * the load request in the first place.
374 *
375 * This property is used primarily by kextutil(8) to delay matching for
376 * either the primary kext, or the whole load list (any that didn't
377 * already have personalities in the IOCatalogue).
378 */
379#define kKextRequestArgumentStartMatchingExcludeKey    "Start Matching Exclude Level"
380
381// see also Delay Autounload
382
383/* Argument:  Personality Names
384 * Type:      Array of strings
385 * Default:   All personalities are used
386 *
387 * Normally when personalities are sent to the IOCatalogue, they are all sent.
388 * This property restricts the personalities sent, for the primary kext
389 * being loaded, to those named. Personalities for dependencies are all sent,
390 * and there is currently no mechanism to filter them.
391 *
392 * This property is used primarily by kextutil(8) to help debug matching
393 * problems.
394 */
395#define kKextRequestArgumentPersonalityNamesKey        "Personality Names"
396
397#if PRAGMA_MARK
398#pragma mark Unload Request Arguments
399#endif
400
401/* Argument:  Terminate
402 * Type:      Boolean
403 * Default:   false
404 *
405 * An unload request may optionally specify via this key that all IOService
406 * objects are to be terminated before attempting to unload. Kexts with
407 * dependents will not attempt to terminate and will return kOSKextReturnInUse.
408 */
409#define kKextRequestArgumentTerminateIOServicesKey     "Terminate IOServices"
410
411#if PRAGMA_MARK
412#pragma mark Internal Tracking Properties
413#endif
414/*********************************************************************
415 * Internal Tracking Properties
416 **********/
417
418/* Argument:  Request Tag
419 * Type:      Number (uint32_t)
420 * Used by:   internal tracking for requests with callbacks
421 *
422 * Most requests to get resources (files) use this.
423 */
424#define kKextRequestArgumentRequestTagKey              "Request Tag"
425
426/* Argument:  Request Callback
427 * Type:      Data (pointer)
428 * Used by:   internal tracking
429 *
430 * Most requests to get resources (files) use this.
431 */
432#define kKextRequestArgumentCallbackKey                "Request Callback"
433
434/* Argument:  Request context.
435 * Type:      OSData (wraps a void *)
436 * Used by:   several
437 */
438#define kKextRequestArgumentContextKey                 "Context"
439
440/* Argument:  Request Stale
441 * Type:      Boolean
442 * Used by:   internal tracking
443 *
444 * _OSKextConsiderUnloads sets this on any callback record lacking
445 * it, and deletes any callback record that has it.
446 */
447#define kKextRequestStaleKey                           "Request Stale"
448
449#ifdef __cplusplus
450};
451#endif /* __cplusplus */
452
453#endif /* _LIBKERN_KEXT_REQUEST_KEYS_H */
454