diff --git a/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt.h b/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt.h new file mode 100644 index 0000000000000000000000000000000000000000..243331937f9855c5954d905049096f186ea4f3de --- /dev/null +++ b/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt.h @@ -0,0 +1,358 @@ +/* ********************************************************** + * Copyright 2012 - 2013 VMware, Inc. All rights reserved. + * **********************************************************/ + +/* + * @VMKAPIMOD_LICENSE@ + */ + +/* + *********************************************************************** + * Management Interfaces */ /** + * \defgroup Mgmt Management + * + * Interfaces that allow management of vmkapi modules (runtime + * parameterization, notifications to modules from user space and + * to user space from modules). + * + * @{ + *********************************************************************** + */ + +/* + * vmkapi_mgmt.h -- + * + * vmkernel declarations for datatypes & functions used for + * enabling per-module management APIs between user-space and + * vmkernel modules. + */ + + + +#ifndef _VMKAPI_MGMT_H_ +#define _VMKAPI_MGMT_H_ + +/** \cond never */ +#ifndef VMK_HEADER_INCLUDED_FROM_VMKAPI_H +#error This vmkapi file should never be included directly but only via vmkapi.h +#endif +/** \endcond never */ + +#include "base/vmkapi_mgmt_types.h" + +/** \brief Opaque generic handle allocated by the API */ +typedef struct vmkMgmtHandleInt * vmk_MgmtHandle; + +/** + *********************************************************************** + * vmk_MgmtCleanupFn -- */ /** + * + * \brief Prototype for a management interface's cleanup callback. + * + * \param[in] private Optional cookie data to be used by the callback, + * as was originally provided to vmk_MgmtInit(). + * + *********************************************************************** + */ +typedef void (*vmk_MgmtCleanupFn)(vmk_uint64 cookie); + +/** + *********************************************************************** + * vmk_MgmtKeyGetFn -- */ /** + * + * \brief Prototype for get-key function. + * + * \note This prototype is for a module-supplied "get" function + * for fetching a key's value, for a key that was registered + * using vmk_MgmtAddKey. + * + * \param[in] cookie Cookie supplied with vmk_MgmtInit. + * \param[out] keyVal Value of the key that was read. The type of + * pointer this represents depends on the type + * of key that was added using this function. + * + * \retval VMK_OK The 'get' function executed correctly. + * This is not an indicator of the success or failure of + * the operations in the function, but merely that they + * ran. + * + *********************************************************************** + */ +typedef VMK_ReturnStatus (*vmk_MgmtKeyGetFn)(vmk_uint64 cookie, + void *keyVal); + +/** + *********************************************************************** + * vmk_MgmtKeySetFn -- */ /** + * + * \brief Prototype for set-key function. + * + * \note This prototype is for a module-supplied "set" function + * for storing a key's value, for a key that was registered + * using vmk_MgmtAddKey. + * + * \param[in] cookie Cookie supplied with vmk_MgmtKeyValueInit. + * \param[in] keyVal Value of the key to set. The type of + * pointer this represents depends on the type + * of key that was added using this function. + * + * \retval VMK_OK The 'set' function executed correctly. + * This is not an indicator of the success or failure of + * the operations in the function, but merely that they + * ran. + * + *********************************************************************** + */ +typedef VMK_ReturnStatus (*vmk_MgmtKeySetFn)(vmk_uint64 cookie, + void *keyVal); + +/** + *********************************************************************** + * vmk_MgmtInit */ /** + * + * \brief Initialize the kernel side of a user/kernel management API + * + * \note The API passed must have an equivalent signature that is passed + * to the library interface in userland. + * + * \param[in] modId The module ID of the kernel module registering + * the API. + * \param[in] heapId The heap ID to use for allocating temporary + * metadata and parameter passing in event delivery. + * \param[in] sig The API signature of the API being registered. + * Callbacks 0 through VMK_MGMT_RESERVED_CALLBACKS + * are reserved and may not be used. + * \param[in] cleanupFn Optional cleanup function that is executed + * after the last in-flight operation + * concludes. Note that in-flight management + * operations can be going on during a vmk_MgmtDestroy. + * \param[in] cookie A data cookie that will be provided as the + * first argument to all kernel-space callbacks + * and the cleanup function that are invoked. + * \param[in,out] handle The handle that will be allocated for accessing + * this API. + * + * \retval VMK_OK Initialization succeeded. + * \retval VMK_BAD_PARAM Either the modId or signature were invalid. + * \retval VMK_NO_MEMORY Internal metadata for operation could not be + * allocated. + * + *********************************************************************** + */ +VMK_ReturnStatus +vmk_MgmtInit(vmk_ModuleID modId, + vmk_HeapID heapId, + vmk_MgmtApiSignature *sig, + vmk_MgmtCleanupFn cleanupFn, + vmk_uint64 cookie, + vmk_MgmtHandle *handle); + +/** + *********************************************************************** + * vmk_MgmtRegisterInstanceCallbacks */ /** + * + * \brief Register instance-specific management callbacks. + * + * \note This API registers an instance and instance-specific callbacks + * that will be associated with a given management handle. If + * you provide instance-specific callbacks, those callbacks will + * be invoked instead of the default corresponding callbacks that + * were originally registered with the handle. Note that it is + * valid to supply a subset of instance-specific callbacks + * (or even none). + * + * \param[in] handle The management handle that was initialized. + * \param[in] instanceId The unique instance that will have its + * callbacks registered. Must be unique for + * the current handle, and must not be 0. + * \param[in] modId The modId of the module where the + * callbacks reside. + * \param[in] heapId The heapId from the module where the + * callbacks reside. + * \param[in] displayName The name that will be displayed for + * this instance when it's listed. + * \param[in] numCallbacks The number of instance-specific + * callbacks that are being registered. 0 + * is valid, if the instance does not + * supply instance-specific callbacks. + * \param[in] callbacks The callback information for each + * instance-specific callback, corresponding + * to callbacks that override those + * registered in the API signature + * for this handle. + * + * \retval VMK_OK Initialization succeeded. + * \retval VMK_BAD_PARAM Parameters couldn't be validated. + * \retval VMK_NO_MEMORY Internal metadata for operation could not be + * allocated. + * + *********************************************************************** + */ +VMK_ReturnStatus +vmk_MgmtRegisterInstanceCallbacks(vmk_MgmtHandle handle, + vmk_uint64 instanceId, + vmk_ModuleID modId, + vmk_HeapID heapId, + vmk_Name *displayName, + vmk_uint32 numCallbacks, + vmk_MgmtCallbackInfo *callbacks); + +/** + *********************************************************************** + * vmk_MgmtUnregisterInstanceCallbacks */ /** + * + * \brief Unregister an instance from being management handle. + * + * \param[in] handle The management handle that was initialized + * and to which this instance is associated. + * \param[in] instanceId The unique instance that was already + * registered for management. + * + * \retval VMK_OK Unregistration succeeded. + * \retval VMK_BAD_PARAM The instance was not already registered. + * + *********************************************************************** + */ +VMK_ReturnStatus +vmk_MgmtUnregisterInstanceCallbacks(vmk_MgmtHandle handle, + vmk_uint64 instanceId); + + +/** + *********************************************************************** + * vmk_MgmtDestroy */ /** + * + * \brief Destroy the kernel side of a user/kernel management API + * + * \param[in] handle The handle that was passed and initialized with + * vmk_MgmtInit + * + * \note The heap that was passed to vmk_MgmtInit should not be + * destroyed until all access to the management channel has stopped, + * and thus the cleanup function has run. If you call + * vmk_MgmtDestroy during module-unload, you are assured that the + * management channel is not in use & thus you can safely destroy + * the heap immediately. + * + * \retval VMK_BAD_PARAM The API has already been destroyed or has + * already been requested to be destroyed. + * \retval VMK_OK The API will be destroyed once all in-flight + * operations conclude (may be immediate, if + * none are currently in-flight). + * + *********************************************************************** + */ +VMK_ReturnStatus +vmk_MgmtDestroy(vmk_MgmtHandle handle); + +/* + *********************************************************************** + * vmk_MgmtCallbackInvokeInt -- + * + * This is used by vmk_MgmtCallbackInvoke(). VMKAPI clients should + * never call this function directly. + * + *********************************************************************** + */ + +/** \cond nodoc */ +VMK_ReturnStatus +vmk_MgmtCallbackInvokeInt(vmk_MgmtHandle handle, + vmk_uint64 instanceId, + vmk_uint64 callbackId, + vmk_uint32 argCount, + ...); +/** \endcond */ + + +/** + *********************************************************************** + * vmk_MgmtCallbackInvoke */ /** + * + * \brief Invoke a user-space callback that has zero or more parameters. + * \note The callback will be asynchronously delivered to user-space, + * but only if there currently is a user-space process associated + * with this management handle that is listening for callback + * requests. This call does not block. + * \note Parameters are immediately copied for delivery. Sizes are + * determined by the API signature that was registered with + * vmk_MgmtInit. Additionally, the data cookie that was + * registered with the receiver (in user space) will be provided + * as the first argument to the callback that is delivered in + * user space. + * + * \param[in] handle The handle that was passed and initialized with + * vmk_MgmtInit + * \param[in] instanceId The unique instance ID from which this callback + * is originating. If this is not an instance- + * specific invocation, use VMK_MGMT_NO_INSTANCE_ID. + * \param[in] callbackId The unique ID corresponding to the callback to + * invoke, as registered with the API signature. + * \param[in] ... Pointers to the parameters to copy and pass. + * The number of parameters passed here must match + * the number used by the callback indicated by + * callbackId. + * + * \retval VMK_OK The callback was prepared for delivery. This + does not indicate that it has run, however. + * \retval VMK_BAD_PARAM The callback or number of parameters supplied + * was invalid. + * \retval VMK_NO_MEMORY Temporary storage required to deliver the event + * was unavailable. + * \retval VMK_NOT_FOUND There is no listening user-space process + * running that can receive this callback request. + * + *********************************************************************** + */ + +#define vmk_MgmtCallbackInvoke( \ + /* (vmk_MgmtHandle) */ handle, \ + /* (vmk_uint64) */ instanceId, \ + /* (vmk_uint64) */ callbackId, \ + ...) \ + vmk_MgmtCallbackInvokeInt(handle, instanceId, callbackId, VMK_UTIL_NUM_ARGS(__VA_ARGS__), ##__VA_ARGS__) + +/** + *********************************************************************** + * vmk_MgmtAddKey */ /** + * + * \brief Add a key to be managed as a key-value pair. + * + * \note This creates a key-value pair that can be managed using + * the vmkmgmt_keyval utility. The name of the management + * handle that was initialized is the name of the key-value + * instance that would be the "instance" argument to + * vmkmgmt_keyval. For the get and set functions registered + * here, the cookie that is given back is the cookie that + * was initialized with vmk_MgmtInit. + * + * \param[in] handle The handle that was initialized by + * vmk_MgmtInit. + * \param[in] keyType The type of the key being added. + * \param[in] keyName The name of the key being added. Must be + * unique compared to other registered + * keys for this management handle. + * \param[in] getFn The function that will be used to get the key + * value at runtime. + * \param[in] setFn The function that will be used to set the key + * value at runtime. + * + * \note Both the getFn and setFn must be provided. + * + * \retval VMK_OK The key was added. + * \retval VMK_BAD_PARAM A bad parameter was given. + * \retval VMK_NO_MEMORY Memory was not available to allocate the required + * metadata structures. + * + *********************************************************************** + */ +VMK_ReturnStatus +vmk_MgmtAddKey(vmk_MgmtHandle handle, + vmk_MgmtKeyType keyType, + vmk_Name *keyName, + vmk_MgmtKeyGetFn getFn, + vmk_MgmtKeySetFn setFn); + + +#endif /* _VMKAPI_MGMT_H_ */ +/** @} */