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