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