File diff 85642093068c → 91e0d39c9812
BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt_lib.h
Show inline comments
 
new file 100644
 
/* **********************************************************
 
 * Copyright 2012 - 2013 VMware, Inc.  All rights reserved.
 
 * **********************************************************/
 

	
 
/*
 
 * @VMKAPIMOD_LICENSE@
 
 */
 

	
 
/*
 
 *******************************************************************************
 
 * Management Types                                                       */ /**
 
 * \addtogroup Mgmt
 
 *
 
 * User-facing interfaces exported by vmkmgmt_lib, for use when communicating
 
 * with vmkapi modules using vmk_Mgmt APIs.
 
 *
 
 * @{
 
 *******************************************************************************
 
 */
 

	
 
/*
 
 * vmkapi_mgmt_lib.h --
 
 *	user-space declarations for datatypes & functions used to interact
 
 *      with vmkapi modules that use the vmk_Mgmt APIs.  Note that user-space
 
 *      management APIs and user-specific types are prefixed with "vmk_MgmtUser",
 
 *      even when they may be used to invoke actions in the kernel.
 
 */
 

	
 
#ifndef _VMKAPI_MGMT_LIB_H_
 
#define _VMKAPI_MGMT_LIB_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 An opaque handle that is allocated and managed by the library */
 
typedef struct vmkMgmtUserHandleInt * vmk_MgmtUserHandle;
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserInit                                               */ /**
 
 *
 
 * \brief Initialize user-space management of a kernel module.
 
 *
 
 * \note This initializes your application for interaction with a
 
 *       kernel module that has an API signature matching the one you
 
 *       provide here with vmk_MgmtUserInit.  Note that the kernel side
 
 *       of the API must be successfully registered with
 
 *       vmk_MgmtInit prior to attempting to initialize the
 
 *       user-space side.  There can be multiple applications or
 
 *       threads using vmk_MgmtUserInit for the same API signature,
 
 *       but only one kernel module can service that API signature.
 
 *
 
 * \note The signature provided here must be compatible with the
 
 *       signature of the API that has been registered with the kernel.
 
 *       if "vendor" is specified (non-null) in the signature, a
 
 *       connection will only be made if the vendor matches.
 
 *
 
 * \param[in]     sig         The API signature describing the
 
 *                            management operations that can be done.
 
 *                            Must match a signature registered in the
 
 *                            kernel.
 
 * \param[in]     userCookie  A data cookie that will be provided as
 
 *                            the first argument to all user-space
 
 *                            callbacks.
 
 * \param[out]    handle      An opaque handle that will be used for
 
 *                            further interaction with the API.
 
 *
 
 * \retval 0      Initialization succeeded.
 
 * \retval other  A UNIX-style error code.
 
 *
 
 ***********************************************************************
 
 */
 
int
 
vmk_MgmtUserInit(vmk_MgmtApiSignature *sig,
 
                 vmk_uint64 userCookie,
 
                 vmk_MgmtUserHandle *handle);
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserGetInstances                                       */ /**
 
 *
 
 * \brief Get instance information for all kernel-registered instances.
 
 *
 
 * \note  The instanceIds populated in the vmk_MgmtInstances structure
 
 *        can be subsequently used to send a callback request to a
 
 *        specific instance with vmk_MgmtUserCallbackInvoke
 
 *
 
 * \param[in]  handle     Management handle that was initialized
 
 * \param[out] instances  Current instance information for given handle
 
 *
 
 * \retval 0      Succeeded getting instances.
 
 * \retval other  A UNIX-style error code.
 
 *
 
 ***********************************************************************
 
 */
 
int
 
vmk_MgmtUserGetInstances(vmk_MgmtUserHandle handle,
 
                         vmk_MgmtInstances *instances);
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserBegin                                              */ /**
 
 *
 
 * \brief Begin execution of user callbacks.
 
 *
 
 * \note  This call creates a separate thread to monitor incoming
 
 *        callback requests from the kernel for the given management
 
 *        handle and immediately begins execution of those callbacks
 
 *        as they arrive.
 
 * \note  This is not necessary if your application is not meant to
 
 *        handle callbacks delivered from the kernel.
 
 *
 
 *
 
 * param[in] handle   Management handle that was initialized
 
 *
 
 * \retval 0     Succeeded initializing callback execution
 
 * \retval other A UNIX-style error code
 
 *
 
 ***********************************************************************
 
 */
 
int
 
vmk_MgmtUserBegin(vmk_MgmtUserHandle handle);
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserContinue                                           */ /**
 
 *
 
 * \brief Indefinitely continue monitoring and executing incoming kernel
 
 *        callback requests in user space.
 
 *
 
 * \note  vmk_MgmtUserBegin must have been successfully executed prior
 
 *        to calling vmk_MgmtUserContinue.
 
 * \note  Invoking vmk_MgmtUserContinue effectively makes the current
 
 *        (calling) thread run indefinitely, in a monitoring mode.  This
 
 *        is typically used by resident CIM providers.  To terminate
 
 *        monitoring on a particular management handle after
 
 *        vmk_MgmtUserBegin or vmk_MgmtUserContinue has been executed,
 
 *        vmk_MgmtUserEnd.  vmk_MgmtUserContinue does not return until
 
 *        vmk_MgmtUserEnd is separately executed on the same handle
 
 *        from within the same process.  To use vmk_MgmtUserEnd after
 
 *        vmk_MgmtUserContinue, you must create a separate pthread that
 
 *        will invoke vmk_MgmtUserEnd sometime later after your main
 
 *        thread has invoked vmk_MgmtUserContinue.
 
 *
 
 * \param[in] handle   Management handle that was initialized
 
 *
 
 * \retval 0           Execution succeeded and was ended without error.
 
 *                     This will happen at some future moment in time,
 
 *                     after vmk_MgmtUserEnd has been used.
 
 * \retval Other       A UNIX error code.  Execution terminated,
 
 *                     possibly early with error.
 
 *
 
 ***********************************************************************
 
 */
 
int
 
vmk_MgmtUserContinue(vmk_MgmtUserHandle handle);
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserEnd                                                */ /**
 
 *
 
 * \brief Terminate monitoring and execution of kernel-to-user callbacks.
 
 *
 
 * \note  This may be called after either vmk_MgmtUserBegin or
 
 *        vmk_MgmtUserContinue.
 
 * \note  Because vmk_MgmtUserContinue does not return, a separate
 
 *        thread within the same process space is required to invoked
 
 *        vmk_MgmtUserEnd.  The effect of vmk_MgmtUserEnd will be to
 
 *        cease processing of any additional incoming callback requests
 
 *        from the kernel, but the management handle will remain open.
 
 *        Processing of inbound callback requests from the kernel can
 
 *        be resumed if vmk_MgmtUserBegin is subsequently used on the
 
 *        given handle.
 
 *
 
 * \param[in] handle   Management handle that was initialized.
 
 *
 
 * \retval 0           Execution was successfully ended.
 
 * \retval Other       A UNIX-style error code indicating the nature of
 
 *                     an error that was encountered.
 
 *
 
 ***********************************************************************
 
 */
 
int
 
vmk_MgmtUserEnd(vmk_MgmtUserHandle handle);
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserDestroy                                            */ /**
 
 *
 
 * \brief Destroy the user side connection to a management handle.
 
 *
 
 * \note  This will terminate receiving of callback requests from the
 
 *        kernel and terminate the ability to send new callback
 
 *        requests to the kernel.
 
 *
 
 * \param[in] handle   Management handle that was initialized.
 
 *
 
 * \retval 0           Handle was destroyed completely without error.
 
 * \retval Other       A UNIX-style error code indicating the nature
 
 *                     of the failure.  The handle should not be used
 
 *                     again even after a failure, however.
 
 *
 
 ***********************************************************************
 
 */
 
int
 
vmk_MgmtUserDestroy(vmk_MgmtUserHandle handle);
 

	
 
/**
 
 ***********************************************************************
 
 * vmk_MgmtUserCallbackInvoke                                     */ /**
 
 *
 
 * \brief From user space, invoke a callback inside the kernel.
 
 *
 
 * \note  Parameter handling:  For asynchronous callbacks, all
 
 *        parameters are internally copied for delivery to the kernel.
 
 *        For synchronous callbacks, input and input-output parameters
 
 *        are copied internally and delivered to the kernel.  For
 
 *        input-output and output parameters, such parameters are copied
 
 *        from the kernel back to user-space (to the pointer indicated
 
 *        by the corresponding parameter given to this function) after
 
 *        the callback has executed.  In addition to the payload
 
 *        parameters passed here, the receiving callback in the kernel
 
 *        will be provided the kernel-side data cookie that the
 
 *        receiver registered with vmk_MgmtInit and the instanceId
 
 *        specificed here.  If an instanceId is specified, the callback
 
 *        function invoked in the kernel will be the instance-specific
 
 *        callback (if it was specified when the instance was added) or
 
 *        the default callback function registered with the API
 
 *        signature (if no instance-specific callback was specified
 
 *        for this callback when the instance was added).
 
 *
 
 * \param[in] handle      Management handle that was initialized.
 
 * \param[in] instanceId  The unique instance ID to send this callback
 
 *                        to.  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] ...         A variable list of parameters, each one
 
 *                        a (void *) pointer to the parameter
 
 *                        being passed to the callback.  The number
 
 *                        of parameters must match that described for
 
 *                        the given callbackId when the API signature
 
 *                        was registered.
 
 * \retval 0     For asynchronous callbacks, this means that the callback
 
 *               successfully was queued.  For synchronous callbacks,
 
 *               this means that the callback has executed completely.
 
 * \retval Other A UNIX-style error code corresponding to the error
 
 *               encountered when attempting to queue or execute the
 
 *               callback.
 
 * \note  The return value is not a indication or return code of the
 
 *        callback itself.
 
 *
 
 */
 
#define vmk_MgmtUserCallbackInvoke(     \
 
   /* (vmk_MgmtHandle *) */ handle,     \
 
   /* (vmk_uint64)       */ instanceId, \
 
   /* (vmk_uint64)       */ callbackId, \
 
                            ...)        \
 
   vmk_MgmtUserCallbackInvokeInt(handle, instanceId, callbackId, VMK_UTIL_NUM_ARGS(__VA_ARGS__), ##__VA_ARGS__)
 

	
 
/*
 
 ***********************************************************************
 
 * vmk_MgmtUserCallbackInvokeInt --
 
 *
 
 * This is used by vmk_MgmtUserCallbackInvoke().  VMKAPI clients should
 
 * never call this function directly.
 
 * 
 
 ***********************************************************************
 
 */
 
int 
 
vmk_MgmtUserCallbackInvokeInt(vmk_MgmtUserHandle handle,
 
                              vmk_uint64 instanceId,
 
                              vmk_uint64 callbackId,
 
                              vmk_uint32 argCount,
 
                              ...);
 

	
 
#endif /* _VMKAPI_MGMT_LIB_H_ */
 
/** @} */