diff --git a/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt_lib.h b/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt_lib.h new file mode 100644 index 0000000000000000000000000000000000000000..f6a63aa636751f7f662a4f3d0ad78de9708de4fb --- /dev/null +++ b/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/base/vmkapi_mgmt_lib.h @@ -0,0 +1,284 @@ +/* ********************************************************** + * 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_ */ +/** @} */