Files
@ d0a14f973771
Branch filter:
Location: vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public/vmkernel64/release/base/vmkapi_entropy.h
d0a14f973771
8.1 KiB
text/x-chdr
ESXi-5.0-U1
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 | /* **********************************************************
* Copyright 1998 - 2009 VMware, Inc. All rights reserved.
* **********************************************************/
/*
* @VMKAPIMOD_LICENSE@
*/
/*
***********************************************************************
* Entropy */ /**
* \addtogroup Core
* @{
* \defgroup Entropy Entropy
*
* These interfaces to deal with entropy in vmkernel.
*
* Two types of interfaces are provided:
* \li To provide various types of entropy directly to the VMkernel
* and device drivers (as opposed to via reads to /dev/{,u}random).
* \li To allow VMkernel and device drivers to submit hardware entropy.
*
* @{
***********************************************************************
*/
#ifndef _VMKAPI_ENTROPY_H_
#define _VMKAPI_ENTROPY_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 */
typedef enum {
VMK_ENTROPY_HARDWARE_INTERRUPT = 0,
VMK_ENTROPY_HARDWARE_RNG = 1,
VMK_ENTROPY_KEYBOARD = 2,
VMK_ENTROPY_MOUSE = 3,
VMK_ENTROPY_OTHER_HID = 4,
VMK_ENTROPY_STORAGE = 5,
VMK_ENTROPY_SOURCE_LIMIT = VMK_ENTROPY_STORAGE
} vmk_EntropySource;
typedef enum {
VMK_ENTROPY_HARDWARE = 0,
VMK_ENTROPY_HARDWARE_NON_BLOCKING = 1,
VMK_ENTROPY_SOFTWARE = 2,
VMK_ENTROPY_SOFTWARE_ONLY = 3,
VMK_ENTROPY_TYPE_LIMIT = VMK_ENTROPY_SOFTWARE_ONLY
} vmk_EntropyType;
/*
***********************************************************************
*
* Entropy Modules export two types of interfaces:
*
*
*
***********************************************************************
*/
/*
***********************************************************************
* vmk_AddEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Submit hardware entropy to the entropy driver.
*
* \note Callbacks of this type may not block.
*
* vmk_AddEntropyFunctions transfer hardware entropy to an entropy module
* and are guaranteed to be non-blocking and have minimal overhead.
* There is no return status because for security reasons any failure is
* cloaked from all callers who lack privilege to know entropy status
* \param[in] typeSpecificInfo Source specific info (example: interrupt vector)
*
* \retval none; caller has no need to know success/failure and cannot be told.
*
***********************************************************************
*/
typedef void (*vmk_AddEntropyFunction)(int sourceSpecificInfo);
/*
***********************************************************************
* vmk_GetEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Retrieve entropy from the entropy driver.
*
* \note Callbacks of this type may not block.
*
* vmk_GetEntropyFunctions return various types of entropy:
* VMK_ENTROPY_HARDWARE always returns VMK_OK but may block
* VMK_ENTROPY_HARDWARE_NON_BLOCKING may return VMK_FAILURE but wont block
* VMK_ENTROPY_SOFTWARE always returns VMK_OK and wont block
* VMK_ENTROPY_SOFTWARE_ONLY always returns VMK_OK and wont block
*
* Note: SOFTWARE entropy may include (and thus consume) HARDWARE
* entropy but SOFTWARE_ONLY entropy is guaranteed not to.
*
* \param[in,out] entropy Buffer to store retrieved entropy
* \param[in] bytesRequested Amount of entropy requested
* \param[out] bytesReturned Amount of entropy actually returned
*
* \retval VMK_OK All requested bytes of entropy returned
* \retval VMK_FAILURE Less than all requested bytes of entropy returned
*
***********************************************************************
*/
typedef VMK_ReturnStatus (*vmk_GetEntropyFunction)(void *entropy,
int bytesRequested,
int *bytesReturned);
/*
***********************************************************************
* vmk_RegisterAddEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Register a function to be used to submit hardware entropy to the
* entropy driver.
*
* \note This function will not block.
*
* \param[in] moduleID Module ID of the entropy module
* \param[in] function Function to call when various hardware events occur
* (e.g., hardware interrupts)
* \param[in] source Type of hardware entropy
*
* \retval VMK_OK Add entropy function was sucessfully registered.
* \retval VMK_FAILURE Add entropy function was not registered.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_RegisterAddEntropyFunction(
vmk_ModuleID moduleID,
vmk_AddEntropyFunction function,
vmk_EntropySource source);
/*
***********************************************************************
* vmk_RegisterGetEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Register an entropy function to be used to obtain hardware
* or software entropy from an external entropy pool.
*
* \note This function will not block.
*
* \param[in] moduleID Module ID of the entropy module
* \param[in] function Function that returns entropy
* \param[in] type Type of entropy (e.g., hardware)
*
* \retval VMK_OK Entropy function was sucessfully registered.
* \retval VMK_FAILURE Entropy function was not registered.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_RegisterGetEntropyFunction(
vmk_ModuleID moduleID,
vmk_GetEntropyFunction function,
vmk_EntropyType type);
/*
***********************************************************************
* vmk_GetRegisteredGetEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Get a registered get entropy function to be used to obtain hardware
* or software entropy from an external entropy pool. Note that this
* function must be called with VMKMODCALL
*
* \note This function will not block.
*
* \param[out] *moduleID Module ID of the entropy module providing the function
* \param[out] *function Function that returns entropy
* \param[in] type Type of entropy desired (e.g., hardware)
*
* \retval VMK_OK Entropy function was sucessfully found and returned.
* \retval VMK_FAILURE Entropy function was not found.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_GetRegisteredEntropyFunction(
vmk_ModuleID *moduleID,
vmk_GetEntropyFunction *function,
vmk_EntropyType type);
/*
***********************************************************************
* vmk_UnregisterAddEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Unregister a submit entropy function (removes for all sources
* of entropy)
*
* \note This function will not block.
*
* \param[in] moduleID Module ID of the entropy module
* \param[in] function Function to unregister
*
* \retval VMK_OK Add entropy function was sucessfully unregistered.
* \retval VMK_FAILURE Add entropy function was not unregistered.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_UnregisterAddEntropyFunction(
vmk_ModuleID moduleID,
vmk_AddEntropyFunction function);
/*
***********************************************************************
* vmk_UnregisterGetEntropyFunction -- */ /**
*
* \ingroup Entropy
* \brief Unregister an entropy function (removes for all types of entropy)
*
* \note This function will not block.
*
* \param[in] moduleID Module ID of the entropy module
* \param[in] function Function that returns entropy
*
* \retval VMK_OK Entropy function was sucessfully unregistered.
* \retval VMK_FAILURE Entropy function was not unregistered.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_UnregisterGetEntropyFunction(
vmk_ModuleID moduleID,
vmk_GetEntropyFunction function);
#endif /* _VMKAPI_ENTROPY_H_ */
/** @} */
/** @} */
|