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