libkern/libkern/kext_request_keys.h

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