/* ********************************************************** * 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_ */ /** @} */