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 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 */