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