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 |
33 | extern "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 | |