359 lines
15 KiB
C
359 lines
15 KiB
C
|
/* **********************************************************
|
||
|
|
* 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_ */
|
||
|
|
/** @} */
|