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 Image
  92  * Argument:  None
  93  * Response:  Raw bytes + length containing the sanitized image of the kernel.
  94  * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
  95  *
  96  * Retrieves a sanitized image of the running kernel for use in generating
  97  * debug symbols in user space.
  98  */
  99 #define kKextRequestPredicateGetKernelImage    "Get Kernel Image"
 100
 101 /* Predicate: Get Kernel Load Address
 102  * Argument:  None
 103  * Response:  OSNumber containing kernel load address.
 104  * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
 105  *
 106  * Retrieves the base load address of the running kernel for use in generating
 107  * debug symbols in user space.
 108  */
 109 #define kKextRequestPredicateGetKernelLoadAddress  "Get Kernel Load 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:  Value
 317  * Type:      Varies with the predicate
 318  * Used by:   several
 319  *
 320  * Used for all the Set-Enabled predicates, and also for Send Resource (OSData).
 321  */
 322 #define kKextRequestArgumentValueKey               "Value"
 323
 324 /* Argument:  Filename
 325  * Type:      String
 326  * Used by:   kKextRequestPredicateSendResource
 327  *
 328  * Names the resource being sent to the kext
 329  */
 330 #define kKextRequestArgumentNameKey                "Name"
 331
 332 /* Argument:  Filename
 333  * Type:      Data
 334  * Used by:   kKextRequestPredicateSendResource
 335  *
 336  * Contains the contents of the resource file being sent.
 337  */
 338 #define kKextRequestArgumentFileContentsKey        "File Contents"
 339
 340 /* Argument:  Delay Autounload
 341  * Type:      Boolean
 342  * Default:   false
 343  *
 344  * Normally all kexts loaded are subject to normal autounload behavior:
 345  * when no OSMetaClass instances remain for a kext that defines an IOService
 346  * subclass, or when a non-IOService kext turns on autounload and its reference
 347  * count drops to zero (external) references.
 348  *
 349  * Setting this property to true in a load request makes the kext being loaded
 350  * skip ONE autounload pass, giving about an extra minute of time before the
 351  * kext is subject to autounload. This is how kextutil(8) to delays autounload
 352  * so that there's more time to set up a debug session.
 353  *
 354  * Setting this property in any other request causes OSKext::considerUnloads()
 355  * to be called before processing the request, ensuring a window where kexts
 356  * will not be unloaded. The user-space kext library uses this so that it can
 357  * avoid including kexts that are already loaded in a load request.
 358  */
 359 #define kKextRequestArgumentDelayAutounloadKey         "Delay Autounload"
 360
 361 #if PRAGMA_MARK
 362 #pragma mark Load Request Arguments
 363 #endif
 364
 365 /*********************************************************************
 366  * Kext Load Request Properties
 367  *
 368  * In addition to a bundle identifier, load requests can contain
 369  * these optional keys.
 370  *
 371  * These properties are used primarily by kextutil(8) to alter default
 372  * load behavior, but the OSKext user-level library makes them all
 373  * available in OSKextLoadWithOptions().
 374  **********/
 375
 376 /* Argument:  StartExclude
 377  * Type:      Integer, corresponding to OSKextExcludeLevel
 378  * Default:   kOSKextExcludeNone if not specified
 379  *
 380  * Normally all kexts in the load list for a load request are started.
 381  * This property is used primarily by kextutil(8) to delay start of
 382  * either the primary kext, or the whole load list (any that weren't
 383  * already loaded & started).
 384  */
 385 #define kKextRequestArgumentStartExcludeKey        "Start Exclude Level"
 386
 387 /* Argument:  Start Matching Exclude Level
 388  * Type:      Integer, corresponding to OSKextExcludeLevel
 389  * Default:   kOSKextExcludeAll if not specified
 390  *
 391  * Normally no personalities are sent to the IOCatalogue for a regular
 392  * kext load; the assumption is that they are already there and triggered
 393  * the load request in the first place.
 394  *
 395  * This property is used primarily by kextutil(8) to delay matching for
 396  * either the primary kext, or the whole load list (any that didn't
 397  * already have personalities in the IOCatalogue).
 398  */
 399 #define kKextRequestArgumentStartMatchingExcludeKey    "Start Matching Exclude Level"
 400
 401 // see also Delay Autounload
 402
 403 /* Argument:  Personality Names
 404  * Type:      Array of strings
 405  * Default:   All personalities are used
 406  *
 407  * Normally when personalities are sent to the IOCatalogue, they are all sent.
 408  * This property restricts the personalities sent, for the primary kext
 409  * being loaded, to those named. Personalities for dependencies are all sent,
 410  * and there is currently no mechanism to filter them.
 411  *
 412  * This property is used primarily by kextutil(8) to help debug matching
 413  * problems.
 414  */
 415 #define kKextRequestArgumentPersonalityNamesKey        "Personality Names"
 416
 417 #if PRAGMA_MARK
 418 #pragma mark Unload Request Arguments
 419 #endif
 420
 421 /* Argument:  Terminate
 422  * Type:      Boolean
 423  * Default:   false
 424  *
 425  * An unload request may optionally specify via this key that all IOService
 426  * objects are to be terminated before attempting to unload. Kexts with
 427  * dependents will not attempt to terminate and will return kOSKextReturnInUse.
 428  */
 429 #define kKextRequestArgumentTerminateIOServicesKey     "Terminate IOServices"
 430
 431 #if PRAGMA_MARK
 432 #pragma mark Internal Tracking Properties
 433 #endif
 434 /*********************************************************************
 435  * Internal Tracking Properties
 436  **********/
 437
 438 /* Argument:  Request Tag
 439  * Type:      Number (uint32_t)
 440  * Used by:   internal tracking for requests with callbacks
 441  *
 442  * Most requests to get resources (files) use this.
 443  */
 444 #define kKextRequestArgumentRequestTagKey              "Request Tag"
 445
 446 /* Argument:  Request Callback
 447  * Type:      Data (pointer)
 448  * Used by:   internal tracking
 449  *
 450  * Most requests to get resources (files) use this.
 451  */
 452 #define kKextRequestArgumentCallbackKey                "Request Callback"
 453
 454 /* Argument:  Request context.
 455  * Type:      OSData (wraps a void *)
 456  * Used by:   several
 457  */
 458 #define kKextRequestArgumentContextKey                 "Context"
 459
 460 /* Argument:  Request Stale
 461  * Type:      Boolean
 462  * Used by:   internal tracking
 463  *
 464  * _OSKextConsiderUnloads sets this on any callback record lacking
 465  * it, and deletes any callback record that has it.
 466  */
 467 #define kKextRequestStaleKey                           "Request Stale"
 468
 469 #ifdef __cplusplus
 470 };
 471 #endif /* __cplusplus */
 472
 473 #endif /* _LIBKERN_KEXT_REQUEST_KEYS_H */