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