/*
 * Copyright (c) 2008 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 * 
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef _LIBKERN_KEXT_REQUEST_KEYS_H
#define _LIBKERN_KEXT_REQUEST_KEYS_H

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/*********************************************************************
* This file defines keys (and values) for properties in kext_request
* collections and mkext archives used for loading in the kernel.
* An incoming request is always a serialized XML plist with at least
* a predicate, and optionally a dictionary of arguments.
*
* Some requests generate serialized XML plist responses, while others
* return raw data. See the predicate description for more.
*
* All of these keys are strictly for internal run-time communication
* between IOKitUser's OSKext module and xnu's OSKext class.
* Keys and values may change at any time without notice.
*********************************************************************/

#if PRAGMA_MARK
/********************************************************************/
#pragma mark Top-Level Request Properties
/********************************************************************/
#endif

/* The Predicate Key
 * The value of this key indicates the operation to perform or the
 * information desired.
 */
#define kKextRequestPredicateKey                   "Kext Request Predicate"

/* The Arguments Key
 * The value of this key is a dictionary containing the arguments
 * for the request.
 */
#define kKextRequestArgumentsKey                   "Kext Request Arguments"

#if PRAGMA_MARK
/********************************************************************/
#pragma mark Request Predicates - User-Space to Kernel
/********************************************************************/
#endif

/*********************************************************************
 * Nonprivileged requests from user -> kernel
 *
 * These requests do not require a privileged host port, as they just
 * return information about loaded kexts.
 **********/
 
/* Predicate: Get Loaded Kext Info
 * Argument:  (None)
 * Response:  An array of information about loaded kexts (see OSKextLib.h).
 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
 *
 * Retrieves an array of dictionaries whose properties describe every kext
 * loaded at the time of the call.
 */
#define kKextRequestPredicateGetLoaded             "Get Loaded Kext Info"

/* Predicate: Get Kernel Load Address
 * Argument:  None
 * Response:  OSNumber containing kernel load address.
 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
 *
 * Retrieves the base load address of the running kernel for use in generating
 * debug symbols in user space.
 */
#define kKextRequestPredicateGetKernelLoadAddress  "Get Kernel Load Address"

/* Predicate: Get All Load Requests
 * Argument:  None
 * Response:  A set of bundle identifiers of all requested kext loads..
 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
 *
 * Retrieves the bundle identifiers of all kexts that were requested to be
 * loaded since power on.
 *
 */
#define kKextRequestPredicateGetAllLoadRequests    "Get All Load Requests"


/*********************************************************************
 * Privileged requests from user -> kernel
 *
 * These requests all do something with kexts in the kernel or to
 * the OSKext system overall. The user-space caller of kext_request()
 * must have access to a privileged host port or these requests result
 * in an op_result of kOSKextReturnNotPrivileged.
 **********/
 
/* Predicate: Get Kernel Requests
 * Argument:  (None)
 * Response:  An array of kernel requests (see below).
 * Op result: OSReturn indicating any errors in processing (see OSKextLib.h)
 *
 * Retrieve the list of deferred load (and other) requests from OSKext.
 * This predicate is reserved for kextd, and we may be enforcing access
 * to the kextd process only.
 */
#define kKextRequestPredicateGetKernelRequests     "Get Kernel Requests"

/* Predicate: Load
 * Argument:  kKextRequestArgumentLoadRequestsKey
 * Response:  None (yet, may become an array of log message strings)
 * Op result: OSReturn indicating processing/load+start result (see OSKextLib.h)
 *
 * Load one or more kexts per the load requests in the arguments dict.
 * See kKextRequestArgumentLoadRequestsKey for more info.
 */
#define kKextRequestPredicateLoad                  "Load"

/* Predicate: Start
 * Argument:  kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
 * Response:  None (yet, may become an array of log message strings)
 * Op result: OSReturn indicating start result (see OSKextLib.h)
 *
 * Start a kext by bundle id. If it's already started, returns success.
 * If a kext's dependencies need to be started, they are also started.
 */
#define kKextRequestPredicateStart                 "Start"

/* Predicate: Stop
 * Argument:  kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
 * Response:  None (yet, may become an array of log message strings)
 * Op result: OSReturn indicating stop result (see OSKextLib.h)
 *
 * Stop a kext by bundle id if it can be stoppoed.
 * If it's already stopped, returns success.
 * Does not attempt to stop dependents; that will return an error.
 */
#define kKextRequestPredicateStop                  "Stop"

/* Predicate: Unload
 * Argument:  kKextRequestArgumentBundleIdentifierKey (CFBundleIdentifier)
 * Response:  None (yet, may become an array of log message strings)
 * Op result: OSReturn indicating stop+unload result (see OSKextLib.h)
 *
 * Stop and unload a kext by bundle id if it can be.
 * Does not attempt to stop dependents; that will return an error.
 */
#define kKextRequestPredicateUnload                "Unload"

#if PRAGMA_MARK
/********************************************************************/
#pragma mark Requests Predicates - Kernel to User Space (kextd)
/********************************************************************/
#endif
/* Predicate: Send Resource
 * Argument:  kKextRequestArgumentRequestTagKey
 * Argument:  kKextRequestArgumentBundleIdentifierKey
 * Argument:  kKextRequestArgumentNameKey
 * Argument:  kKextRequestArgumentValueKey
 * Argument:  kKextRequestArgumentResult
 * Response:  None
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Retrieves a resource file from a kext bundle. The callback corresponding
 * to the request will be invoked.
 */
#define kKextRequestPredicateSendResource          "Send Resource"

/*********************************************************************
 * Kernel Requests: from the kernel or loaded kexts up to kextd
 *
 * These requests come from within the kernel, and kextd retrieves
 * them using kKextRequestPredicateGetKernelRequests.
 **********/
 
/* Predicate: Kext Load Request
 * Argument:  kKextRequestArgumentBundleIdentifierKey
 * Response:  Asynchronous via a kKextRequestPredicateLoad from kextd
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Requests that kextd load the kext with the given identifier.
 * When kexts loads the kext, it informs the IOCatalogue of the load.
 * If the kext cannot be loaded, kextd or OSKext removes its personalities
 * from the kernel.
 */
#define kKextRequestPredicateRequestLoad           "Kext Load Request"

/* Predicate: Kext Load Notification
 * Argument:  kext identifier
 * Response:  None
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Informs kextd that the kernel has successfully loaded and started
 * a kext.
 */
#define kKextRequestPredicateLoadNotification      "Kext Load Notification"

/* Predicate: Kext Unload Notification
 * Argument:  kext identifier
 * Response:  None
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Informs kextd that the kernel has successfully stopped and unloaded
 * a kext.
 */
#define kKextRequestPredicateUnloadNotification    "Kext Unload Notification"

/* Predicate: Prelinked Kernel Request
 * Argument:  None
 * Response:  None
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Notifies kextd that the kernel we booted from was not prelinked, therefore
 * that kextd should try to create a prelinked kernel now.
 */
#define kKextRequestPredicateRequestPrelink        "Kext Prelinked Kernel Request"

/* Predicate: Kext Resource Request
 * Argument:  kKextRequestArgumentRequestTagKey
 * Argument:  kKextRequestArgumentBundleIdentifierKey
 * Argument:  kKextRequestArgumentNameKey
 * Response:  Asynchronous via a kKextRequestPredicateSendResource from kextd
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Requests a resource file from a kext bundle by identifier + filename.
 */
#define kKextRequestPredicateRequestResource       "Kext Resource Request"

/* Predicate: Kext Kextd Exit Request
 * Argument:  None
 * Response:  None
 * Op result: OSReturn indicating result (see OSKextLib.h)
 *
 * Requests kextd exit for system shutdown.
 */
#define kKextRequestPredicateRequestKextdExit    "Kextd Exit"

#if PRAGMA_MARK
/********************************************************************/
#pragma mark -
#pragma mark Generic Request Arguments
/********************************************************************/
#endif
/* Argument:  Kext Load Requests
 * Type:      Array of dictionaries (see Load Request Arguments below)
 * Used by:   kKextRequestPredicateLoad
 *
 * An array of dictionaries, each describing a single load operation to
 * be performed with its options. A kext load request is effectively a
 * nested series requests. Currently only one load request is embedded
 * in a user-space Load request, so the result is unambiguous. We might
 * change this, specifically for kextd, to allow all pending kernel
 * load requests to be rolled up into one blob. Might not be much win
 * in that, however. The nested logic makes the code difficult to read.
 */
#define kKextRequestArgumentLoadRequestsKey        "Kext Load Requests"

/* Argument:  CFBundleIdentifier
 * Type:      String
 * Used by:   several
 *
 * Any request that takes a bundle identifier uses this key.
 */
#define kKextRequestArgumentBundleIdentifierKey    "CFBundleIdentifier"

/* Argument:  OSReturn
 * Type:      Dictionary
 * Used by:   OSKext::copyInfo()
 *
 * Used to specify a subset of all possible info to be returned.
 */
#define kKextRequestArgumentInfoKeysKey          "Kext Request Info Keys"

/* Argument:  OSReturn
 * Type:      Number (OSReturn)
 * Used by:   several
 *
 * Contains the OSReturn/kern_return_t result of the request.
 */
#define kKextRequestArgumentResultKey              "Kext Request Result Code"

/* Argument:  Value
 * Type:      Varies with the predicate
 * Used by:   several
 *
 * Used for all the Set-Enabled predicates, and also for Send Resource (OSData).
 */
#define kKextRequestArgumentValueKey               "Value"

/* Argument:  Filename
 * Type:      String
 * Used by:   kKextRequestPredicateSendResource
 *
 * Names the resource being sent to the kext
 */
#define kKextRequestArgumentNameKey                "Name"

/* Argument:  Filename
 * Type:      Data
 * Used by:   kKextRequestPredicateSendResource
 *
 * Contains the contents of the resource file being sent.
 */
#define kKextRequestArgumentFileContentsKey        "File Contents"

/* Argument:  Delay Autounload
 * Type:      Boolean
 * Default:   false
 *
 * Normally all kexts loaded are subject to normal autounload behavior:
 * when no OSMetaClass instances remain for a kext that defines an IOService
 * subclass, or when a non-IOService kext turns on autounload and its reference
 * count drops to zero (external) references.
 *
 * Setting this property to true in a load request makes the kext being loaded
 * skip ONE autounload pass, giving about an extra minute of time before the
 * kext is subject to autounload. This is how kextutil(8) to delays autounload
 * so that there's more time to set up a debug session.
 *
 * Setting this property in any other request causes OSKext::considerUnloads()
 * to be called before processing the request, ensuring a window where kexts
 * will not be unloaded. The user-space kext library uses this so that it can
 * avoid including kexts that are already loaded in a load request.
 */
#define kKextRequestArgumentDelayAutounloadKey         "Delay Autounload"

#if PRAGMA_MARK
#pragma mark Load Request Arguments
#endif

/*********************************************************************
 * Kext Load Request Properties
 *
 * In addition to a bundle identifier, load requests can contain
 * these optional keys.
 *
 * These properties are used primarily by kextutil(8) to alter default
 * load behavior, but the OSKext user-level library makes them all
 * available in OSKextLoadWithOptions().
 **********/
 
/* Argument:  StartExclude
 * Type:      Integer, corresponding to OSKextExcludeLevel
 * Default:   kOSKextExcludeNone if not specified
 *
 * Normally all kexts in the load list for a load request are started.
 * This property is used primarily by kextutil(8) to delay start of
 * either the primary kext, or the whole load list (any that weren't
 * already loaded & started).
 */
#define kKextRequestArgumentStartExcludeKey        "Start Exclude Level"

/* Argument:  Start Matching Exclude Level
 * Type:      Integer, corresponding to OSKextExcludeLevel
 * Default:   kOSKextExcludeAll if not specified
 *
 * Normally no personalities are sent to the IOCatalogue for a regular
 * kext load; the assumption is that they are already there and triggered
 * the load request in the first place.
 *
 * This property is used primarily by kextutil(8) to delay matching for
 * either the primary kext, or the whole load list (any that didn't
 * already have personalities in the IOCatalogue).
 */
#define kKextRequestArgumentStartMatchingExcludeKey    "Start Matching Exclude Level"

// see also Delay Autounload

/* Argument:  Personality Names
 * Type:      Array of strings
 * Default:   All personalities are used
 *
 * Normally when personalities are sent to the IOCatalogue, they are all sent.
 * This property restricts the personalities sent, for the primary kext
 * being loaded, to those named. Personalities for dependencies are all sent,
 * and there is currently no mechanism to filter them.
 *
 * This property is used primarily by kextutil(8) to help debug matching
 * problems.
 */
#define kKextRequestArgumentPersonalityNamesKey        "Personality Names"

#if PRAGMA_MARK
#pragma mark Unload Request Arguments
#endif

/* Argument:  Terminate
 * Type:      Boolean
 * Default:   false
 *
 * An unload request may optionally specify via this key that all IOService
 * objects are to be terminated before attempting to unload. Kexts with
 * dependents will not attempt to terminate and will return kOSKextReturnInUse.
 */
#define kKextRequestArgumentTerminateIOServicesKey     "Terminate IOServices"

#if PRAGMA_MARK
#pragma mark Internal Tracking Properties
#endif
/*********************************************************************
 * Internal Tracking Properties
 **********/

/* Argument:  Request Tag
 * Type:      Number (uint32_t)
 * Used by:   internal tracking for requests with callbacks
 *
 * Most requests to get resources (files) use this.
 */
#define kKextRequestArgumentRequestTagKey              "Request Tag"

/* Argument:  Request Callback
 * Type:      Data (pointer)
 * Used by:   internal tracking
 *
 * Most requests to get resources (files) use this.
 */
#define kKextRequestArgumentCallbackKey                "Request Callback"

/* Argument:  Request context.
 * Type:      OSData (wraps a void *)
 * Used by:   several
 */
#define kKextRequestArgumentContextKey                 "Context"

/* Argument:  Request Stale
 * Type:      Boolean
 * Used by:   internal tracking
 *
 * _OSKextConsiderUnloads sets this on any callback record lacking
 * it, and deletes any callback record that has it.
 */
#define kKextRequestStaleKey                           "Request Stale"

#ifdef __cplusplus
};
#endif /* __cplusplus */

#endif /* _LIBKERN_KEXT_REQUEST_KEYS_H */