vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/generic/release/base/vmkapi_mgmt.h

/* **********************************************************
 * 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;

/** \brief Opaque session ID assigned during session announcement */
typedef vmk_uint64 vmk_MgmtSessionID;

/**
 * \brief The session ID to send a callback to all current sessions.
 * \note  Using this session ID in the envelope's sessionId member
 *        will send a callback request, via vmk_MgmtCallbackInvoke,
 *        to all current sessions.
 */
#define VMK_MGMT_SESSION_ID_ALL ((vmk_uint64) 0)

/**
 * \brief Addressing information describing a callback invocation.
 * \note  An envelope structure is used both when receiving a callback
 *        (as the second parameter to the kernel callback) and
 *        when sending a callback to user-space from via
 *        vmk_MgmtCallbackInvoke.  When receiving a callback in
 *        the kernel, the envelope describes the session from
 *        which the callback originates and the instance to
 *        which the callback is addressed (if any).  When sending
 *        a callback to user-space, the envelope describes the
 *        session to which the callback should be sent and the
 *        instance from which the callback originates (if any).
 */
typedef struct vmk_MgmtEnvelope {
   /**
    * \brief Instance ID this callback is being sent to or coming from.
    * \note  VMK_MGMT_NO_INSTANCE_ID can be provided if the callback is
    *        not originating from any specific instance or is not
    *        addressed to a specific instance.
    */
   vmk_MgmtInstanceID instanceId;

   /**
    * \brief Session ID this callback is being sent to or coming from.
    * \note  VMK_MGMT_SESSION_ID_ALL can be used to address all
    *        sessions simultaneously from the kernel, but
    *        VMK_MGMT_SESSION_ID_ALL will never be provided as
    *        the session from which a callback originated.
    */
   vmk_MgmtSessionID sessionId;
} vmk_MgmtEnvelope;

/**
 * \brief Cookie information provided to a single callback invocation.
 */
typedef struct vmk_MgmtCookies {
   /**
    * \brief Handle cookie that was provided to vmk_MgmtInit
    */
   vmk_uint64 handleCookie;

   /**
    * \brief Session cookie assigned by session announcement function.
    */
   vmk_uint64 sessionCookie;
} vmk_MgmtCookies;

/**
 ***********************************************************************
 * vmk_MgmtSessionAnnounceFn --                                   */ /**
 *
 * \brief Session-announce function prototype
 *
 * This function runs when a new managing session (usually a user-space
 * program such as a CIM provider) connects to a management handle.
 * You can use this function to initialize per-session state.  To
 * refer to that session state later, assign the state metadata (such
 * as a pointer) to the sessionCookie output parameter.  The
 * sessionCookie will be provided to subsequent callbacks originating
 * from this particular session and to the session cleanup function
 * when the session ends.
 *
 * \param[in]  handle         The handle associated with the session
 *                            being created.
 * \param[in]  handleCookie   The cookie that was provided to
 *                            vmk_MgmtInit.
 * \param[in]  sessionId      A unique identifier for the new session.
 * \param[out] sessionCookie  Optional developer-provided cookie that
 *                            will be provided on subsequent
 *                            callback invocations and to the
 *                            session cleanup function.
 *
 * \retval VMK_OK The session could be established.
 *
 ***********************************************************************
 */
typedef VMK_ReturnStatus
(*vmk_MgmtSessionAnnounceFn)(vmk_MgmtHandle handle,
                             vmk_uint64 handleCookie,
                             vmk_MgmtSessionID sessionId,
                             vmk_uint64 *sessionCookie);

/**
 ***********************************************************************
 * vmk_MgmtSessionCleanupFn --                                    */ /**
 *
 * \brief Session-cleanup function prototype.
 *
 * This function runs when a managing session (usually a user-space
 * program such as a CIM provider) disconnects from the management
 * handle.  Note that if your cleanup function encounters an
 * internal error that prevents it from successfully completing,
 * the management session will still be removed and will not be
 * used again.
 *
 * \note You must not use vmk_MgmtCallbackInvoke() from within
 *       your session-cleanup function to the session that
 *       is being cleaned up.
 *
 * \param[in]  handle         The handle associated with the session
 *                            being cleaned up.
 * \param[in]  handleCookie   The cookie that was provided to
 *                            vmk_MgmtInit.
 * \param[in]  sessionId      A unique identifier for session.
 * \param[in]  sessionCookie  The cookie that was established by the
 *                            announce function when the session
 *                            started.
 *
 * \retval None.
 *
 ***********************************************************************
 */
typedef void
(*vmk_MgmtSessionCleanupFn)(vmk_MgmtHandle handle,
                            vmk_uint64 handleCookie,
                            vmk_MgmtSessionID sessionId,
                            vmk_AddrCookie sessionCookie);


/**
 ***********************************************************************
 * 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 handleCookie);

/**
 ***********************************************************************
 * 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);

/**
 * \brief Properties of a kernel management handle being initialized.
 */
typedef struct vmk_MgmtProps {
   /**
    * \brief Module ID registering this handle.
    */
   vmk_ModuleID modId;

   /**
    * \brief Heap ID used for allocating metadata and parameter data.
    * \note The heap must have sufficient capacity to handle static
    *       allocations associated with metadata overhead and to handle
    *       dynamic allocations associated with backing parameter
    *       data during callback invocations and key-value operations.
    *       The static overhead is approximately 16KB per management
    *       handle plus approximately 2KB per simultaneous
    *       application session (e.g., CIM provider or other
    *       caller of vmk_MgmtUserInit).  The dynamic overhead per
    *       callback invocation is a maximum of 9KB plus the total of
    *       all parameter sizes for that specific callback.  If multiple
    *       concurrent callbacks (or concurrent callbacks of
    *       different type with different parameter sizes) should
    *       be supported, then the heap should be large enough to
    *       handle the simultaneous allocation of those dynamic
    *       allocations while those callbacks are being processed.
    *       Similarly, dynamic overhead for a key-value operation is
    *       approximately 9KB per operation while that operation is
    *       ongoing.  Typically key-value operations are processed
    *       serially from user-space, and only one operation is
    *       ongoing at any given.
    */
   vmk_HeapID heapId;

   /**
    * \brief Signature describing the API being initialized.
    * \note  To be useable, API passed must have an equivalent
    *        signature that is passed to the library interface
    *        in user-space.
    */
   vmk_MgmtApiSignature *sig;

   /**
    * \brief Cleanup function run during management handle teardown.
    * \note  This is optional and may be NULL.
    */
   vmk_MgmtCleanupFn cleanupFn;

   /**
    * \brief Function that runs when a management session starts.
    * \note  This is optional and may be NULL.
    */
   vmk_MgmtSessionAnnounceFn sessionAnnounceFn;

   /**
    * \brief Function that runs when a management session ends.
    * \note  This is optional and may be NULL.
    */
   vmk_MgmtSessionCleanupFn sessionCleanupFn;

   /**
    * \brief Handle-wide cookie that used by subsequent callbacks.
    * \note  This is optional and may be 0.
    */
   vmk_uint64 handleCookie;
} vmk_MgmtProps;


/**
 ***********************************************************************
 * vmk_MgmtInit                                                   */ /**
 *
 * \brief Initialize the kernel side of a user/kernel management API
 *
 * \param[in]     props     The properties describing the API being
 *                          initialized.
 * \param[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_MgmtProps *props,
             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_MgmtEnvelope *envelope,
                          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] envelope   The envelope describing the instanceId from
 *                       which this callback originates and the
 *                       session ID to which this callback should be
 *                       sent.  If this callback should be sent to
 *                       all current sessions, use VMK_MGMT_SESSION_ID_ALL
 *                       as the session ID.  If this callback is not
 *                       instance-specific, use VMK_MGMT_NO_INSTANCE_ID
 *                       as the instance ID.
 *                       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.  Any parameter that is declared
 *    	       	       	 as a vector type must be encapsulated in a
 *    	     	       	 vmk_MgmtVectorParm structure.
 *
 * \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_MgmtEnvelope *) */ envelope,   \
         /* (vmk_uint64)         */ callbackId, \
                                    ...)        \
   vmk_MgmtCallbackInvokeInt(handle, envelope, 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_ */
/** @} */