Files
@ d6b9b2ac5869
Branch filter:
Location: vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/core/vmkapi_pcpustorage.h
d6b9b2ac5869
8.4 KiB
text/x-chdr
ESXi-5.5-U2
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 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 | /* **********************************************************
* Copyright 2010 VMware, Inc. All rights reserved.
* **********************************************************/
/*
* @VMKAPIMOD_LICENSE@
*/
/*
***********************************************************************
* Per-PCPU Storage */ /**
* \addtogroup Core
* @{
* \defgroup PCPUStorage Per-PCPU Storage
* @{
*
* The per-PCPU storage system allows the allocation of a portion of
* memory for each PCPU on the system. A handle is provided when
* the storage is created and a pointer to the memory for a particular
* PCPU can be looked up. That pointer must be released when no longer
* used to ensure proper reference counting.
*
***********************************************************************
*/
#ifndef _VMKAPI_PCPUSTORAGE_H_
#define _VMKAPI_PCPUSTORAGE_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 */
/**
* \brief Opaque handle for a per-pcpu storage region.
*/
typedef struct vmk_PCPUStorageHandleInt *vmk_PCPUStorageHandle;
/**
* \brief PCPU storage allocation type.
*/
typedef enum {
/** Storage mostly intended for read access. */
VMK_PCPU_STORAGE_TYPE_READ = 0,
/** Storage intented for read and write access, but mostly from local PCPU. */
VMK_PCPU_STORAGE_TYPE_WRITE_LOCAL = 1,
/** Storage intented for read and write access from any PCPU. */
VMK_PCPU_STORAGE_TYPE_WRITE_REMOTE = 2,
/** Marker for last type. */
VMK_PCPU_STORAGE_TYPE_MAX = 3,
} vmk_PCPUStorageType;
/*
***********************************************************************
* vmk_PCPUStorageConstructor -- */ /**
*
* \brief Object constructor - optional user defined callback function.
*
* The constructor runs for each PCPU's storage area when the area
* is allocated. The return value may be used to indicate that
* initializing the storage failed.
*
* \note A callback of this type must not block or call any API
* functions that may block.
*
* \param[in] pcpu PCPU number whose storage is being constructed.
* \param[in] object Pointer to the storage for the object.
* \param[in] size Size of object in bytes.
* \param[in] arg User-provided argument.
*
* \retval VMK_OK Indicates object construction has succeeded.
* \retval Other Indicates that object construction failed. If object
* construction fails during storage allocation, the
* allocation will fail, and all constructed objects
* will be destroyed.
*
***********************************************************************
*/
typedef VMK_ReturnStatus (*vmk_PCPUStorageConstructor)(vmk_PCPUID pcpu,
void *object,
vmk_ByteCountSmall size,
vmk_AddrCookie arg);
/*
***********************************************************************
* vmk_PCPUStorageDestructor -- */ /**
*
* \brief Object destructor - optional user defined callback function.
*
* The destructor runs for each PCPU's storage area before the area
* is freed.
*
* \note A callback of this type must not block or call any API
* functions that may block.
*
* \param[in] pcpu PCPU number whose storage is being constructed.
* \param[in] object Pointer to the storage for the object.
* \param[in] size Size of object in bytes.
* \param[in] arg User-provided argument.
*
***********************************************************************
*/
typedef void (*vmk_PCPUStorageDestructor)(vmk_PCPUID pcpu,
void *object,
vmk_ByteCountSmall size,
vmk_AddrCookie arg);
/**
* \brief PCPU storage allocation properties structure.
*
* Allocation properties for a per-PCPU storage allocation.
*/
typedef struct {
/** \brief Type of PCPU storage allocation. */
vmk_PCPUStorageType type;
/** \brief Allocating module ID. */
vmk_ModuleID moduleID;
/** \brief Name of this storage. */
vmk_Name name;
/** \brief Size of the allocation, in bytes. */
vmk_ByteCountSmall size;
/** \brief Alignment of the allocation, in bytes. */
vmk_ByteCountSmall align;
/**
* \brief Object constructor.
*
* If set to NULL, the memory will be initialized to 0.
*/
vmk_PCPUStorageConstructor constructor;
/**
* \brief Object destructor.
*
* Set to NULL if no destructor is desired.
*/
vmk_PCPUStorageDestructor destructor;
/** \brief Client-specified argument for destructor and constructor. */
vmk_AddrCookie arg;
} vmk_PCPUStorageProps;
#define VMK_PCPU_STORAGE_HANDLE_INVALID ((vmk_PCPUStorageHandle) -1)
/*
***********************************************************************
* vmk_PCPUStorageCreate -- */ /**
*
* \brief Create a new per-pcpu storage area.
*
* Creates a new per-pcpu storage area of the specified size and
* alignment.
*
* \note This function will not block.
*
* \param[in] props Properties for the allocation.
* \param[out] handle Lookup handle.
*
* \retval VMK_OK Memory was allocated and constructed.
* \retval VMK_NO_MEMORY Not enough space was available for this
* operation.
* \retval VMK_BAD_PARAM A bad parameter was provided.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_PCPUStorageCreate(vmk_PCPUStorageProps *props,
vmk_PCPUStorageHandle *handle);
/*
***********************************************************************
* vmk_PCPUStorageDestroy -- */ /**
*
* \brief Delete an existing per-pcpu storage area.
*
* Deletes the per-pcpu storage area identified by handle.
*
* \note This function will not block.
*
* \param[in] handle Handle previously created by
* vmk_PCPUStorageCreate().
*
* \retval VMK_OK The storage associated with handle was
* deleted.
* \retval VMK_BAD_PARAM handle was invalid
*
***********************************************************************
*/
VMK_ReturnStatus vmk_PCPUStorageDestroy(vmk_PCPUStorageHandle handle);
/*
***********************************************************************
* vmk_PCPUStorageLookUp -- */ /**
*
* \brief Returns a pointer to a PCPU's per-PCPU storage.
*
* Retrieves the storage associated with handle for the PCPU.
* This object must subsequently be released with
* vmk_PCPUStorageRelease() after using the returned object. A handle
* cannot be destroyed until the pointer is released.
*
* \note This function will not block.
*
* \param[in] pcpu PCPU whose storage element will be returned.
* \param[in] handle Handle to look up.
* \param[out] object Pointer to the per-PCPU storage.
*
* \retval VMK_OK The returned object is valid to use.
* \retval VMK_BAD_PARAM PCPU or Handle was invalid
*
***********************************************************************
*/
VMK_ReturnStatus vmk_PCPUStorageLookUp(vmk_PCPUID pcpu,
vmk_PCPUStorageHandle handle,
void **object);
/*
***********************************************************************
* vmk_PCPUStorageRelease -- */ /**
*
* \brief Releases a previously retrieved per-pcpu storage pointer.
*
* Releases a pointer previous acquired with vmk_PCPUStorageLookUp.
* Each pointer acquired with vmk_PCPUStorageLookUp must be
* subsequently released by vmk_PCPUStorageRelease.
*
* \note This function will not block.
*
* \param[in] handle Handle that was looked up.
* \param[in] object Pointer that was retrieved.
*
* \retval VMK_OK The object was released.
* \retval VMK_BAD_PARAM PCPU or Handle was invalid.
*
***********************************************************************
*/
VMK_ReturnStatus vmk_PCPUStorageRelease(vmk_PCPUStorageHandle handle,
void *object);
#endif /* _VMKAPI_PCPUSTORAGE_H_ */
/** @} */
/** @} */
|