Files
@ d6b9b2ac5869
Branch filter:
Location: vmkdrivers/BLD/build/HEADERS/vmkapi-current-all-public-bincomp/vmkernel64/release/core/vmkapi_mapping.h
d6b9b2ac5869
8.9 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 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | /* **********************************************************
* Copyright 2010 VMware, Inc. All rights reserved.
* **********************************************************/
/*
* @VMKAPIMOD_LICENSE@
*/
/*
******************************************************************************
* Mapping */ /**
*
* \addtogroup Core
* @{
* \defgroup Mapping Mapping
*
* \brief Interfaces and definitions to map machine page ranges into a virtual
* address space.
*
* The VMKAPI mapping interfaces allow a user to map one or more machine page
* ranges into a virtually contiguous mapping. The mappings are globally visible
* on every PCPU.
*
* \par Example 1 - Map MPN 12-13 read-only and unmap the mapping:
*
* \code
* vmk_MapRequest mRequest;
* vmk_MpnRange mRange;
* vmk_VA va;
*
* mRange.startMPN = 12;
* mRange.numPages = 2;
* mRequest.mapType = VMK_MAPTYPE_DEFAULT;
* mRequest.mapAttrs = VMK_MAPATTRS_READONLY;
* mRequest.numElements = 1;
* mRequest.mpnRanges = &mRange;
* mRequest.reservation = NULL;
* status = vmk_Map(<myModuleID>, &mRequest, &va);
* if (status == VMK_OK) {
* vmk_Unmap(va);
* }
* \endcode
*
* If status is VMK_OK then va will contain the starting virtual
* address of the mapping for MPNs 12-13.
*
* \par Example 2 - Map MPN [6-20] and [42-50] read-write
*
* \code
* vmk_MapRequest mRequest;
* vmk_MpnRange mRange[2];
* vmk_VA va;
*
* mRange[0].startMPN = 6;
* mRange[0].numPages = 15;
* mRange[1].startMPN = 42;
* mRange[1].numPages = 9;
* mRequest.mapType = VMK_MAPTYPE_DEFAULT;
* mRequest.mapAttrs = VMK_MAPATTRS_READWRITE | VMK_MAPATTRS_MIGHTCHANGE;
* mRequest.numElements = 2;
* mRequest.mpnRanges = &mRange;
* mRequest.reservation = NULL;
* status = vmk_Map(<myModuleID>, &mRequest, &va);
* if (status == VMK_OK) {
* status = vmk_MapChangeAttributes(va, VMK_MAPATTRS_EXECUTABLE);
* vmk_Unmap(va);
* }
* \endcode
*
* if status is VMK_OK then va will contain the starting virtual
* address of the mapping for MPNs [6-20],[42-50]. If vmk_Map completed
* successfully we change the mapping to be read-only, executable instead of
* read-write. Since we are not using the mapping afterwards we don't have to
* check the return value of vmk_MapChangeAttributes and we'll just unmap the
* mapping instead.
*
* To map device memory, map type must be VMK_MAPTYPE_DEVICE and an IO
* reservation handle obtained from the IOResource interface must be provided
* in the map request.
* @{
******************************************************************************
*/
#ifndef _VMKAPI_CORE_MAPPING_H_
#define _VMKAPI_CORE_MAPPING_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 MPN Range
*
* Used to describe a physically contiguous block of machine pages.
*/
typedef struct vmk_MpnRange {
/** Page number of the first machine page in the range to be mapped */
vmk_MPN startMPN;
/** Total number of pages in the range */
vmk_uint32 numPages;
} vmk_MpnRange;
/**
* \brief Map type
*
* Type of memory being mapped.
*/
typedef enum {
/** Undefined map type */
VMK_MAPTYPE_NONE = 0,
/** Default: machine memory */
VMK_MAPTYPE_DEFAULT = 1,
/** Device memory */
VMK_MAPTYPE_DEVICE = 2,
} vmk_MapRequestType;
/**
* \brief Mapping Attributes
*
* Mapping attributes are used to specify special attributes for a mapping
* operation. If no special attributes are specified then the mappings will be
* not executable and read-only. A user is allowed to combine multiple
* attributes with a binary OR operation e.g (VMK_MAPATTRS_READWRITE |
* VMK_MAPATTRS_EXECUTABLE).
*/
typedef vmk_uint64 vmk_MapAttrs;
/**
* \brief Map pages read-only.
*
* Establishing read-only mappings is very fast since it usually doesn't require
* any CPU cache invalidation
*/
#define VMK_MAPATTRS_READONLY (0)
/** Map all page ranges read- and writeable */
#define VMK_MAPATTRS_READWRITE (1<<0)
/**
* \brief Map all page ranges executable.
*
* This causes ESX to not set the no-executable (NX) bit for all mapped ranges.
* Please note that ESX has an extensive module loading interface that should
* usually be sufficient for any on-the-fly code additions that migh be needed.
*/
#define VMK_MAPATTRS_EXECUTABLE (1<<1)
/**
* \brief Map pages as write-combined.
*
* Please make sure that you consult the x86 architecture manuals about the
* interactions between write combined page table attributes and memory typed
* registers before using this attribute.
*/
#define VMK_MAPATTRS_WRITECOMBINE (1<<2)
/**
* \brief Mark page table entries as uncached
*
* Page table entries for the mapping will not be cached in the TLB. Use this
* attribute with caution it will cause a noticable slow down when accessing the
* mapped pages. Usually this attribute is only needed when mapping 'special'
* pages e.g. memory backed device registers.
*/
#define VMK_MAPATTRS_UNCACHED (1<<3)
/**
* \brief User of the mapping might use vmk_MapChangeAttributes
*
* Needed if a user of the mapping might use vmk_MapChangeAttributes on the
* mapping.
*/
#define VMK_MAPATTRS_MIGHTCHANGE (1<<4)
/**
* \brief Map Request Descriptor
*
* This struct describes a mapping request for a virtually contiguous mapping of
* one or multiple machine page ranges. The user provides a filled in mpnRanges
* array of size numElements.
*/
typedef struct vmk_MapRequest {
/** Type of memory being mapped */
vmk_MapRequestType mapType;
/** Attributes for the mapping */
vmk_MapAttrs mapAttrs;
/** Number of elements in the vmk_MpnRange array */
vmk_uint32 numElements;
/** Array of numElements vmk_MpnRanges */
vmk_MpnRange *mpnRanges;
/** IO reservation handle if mapping device memory */
vmk_IOReservation reservation;
} vmk_MapRequest;
/*
******************************************************************************
* vmk_Map -- */ /**
*
* \brief Map the provided machine address ranges to a virtual address
*
* This function establishes a globally visible virtual contiguous mapping for
* the provided machine page address ranges.
*
* \param[in] moduleID Module ID of the caller
* \param[in] mapRequest Pointer to a mapRequest struct.
* \param[out] va If the function completes successfully ESX will
* fill va with the starting virtual address of
* the mapping.
*
* \return VMK_OK if the range was successfully mapped, error code otherwise.
*
* \note This function is only callable from a regular execution context.
* \note Mapping requests are accounted against the caller's module. During
* module removal the module has to release all previously acquired
* mappings. Establishing read-only mappings for one machine address
* range is significantly faster than all other mapping operations.
* \note This function will not block.
*
******************************************************************************
*/
VMK_ReturnStatus
vmk_Map(vmk_ModuleID moduleID,
vmk_MapRequest *mapRequest,
vmk_VA *va);
/*
******************************************************************************
* vmk_Unmap -- */ /**
*
* \brief Unmap a mapping created by vmk_Map
*
* \param[in] va Virtual address previously returned by vmk_Map
*
* \note This function is only callable from a regular execution context
* \note This function will not block.
*
******************************************************************************
*/
void
vmk_Unmap(vmk_VA va);
/*
******************************************************************************
* vmk_MapChangeAttributes -- */ /**
*
* \brief Change the mapping attributes of a mapping created via vmk_Map
*
* This function changes the attributes of a mapping that has previously been
* created via vmk_Map.
*
* \param[in] va Virtual address previously returned by vmk_Map
* \param[in] attrs New attributes for the mapping
*
* \return VMK_OK if the range was successfully mapped, error code otherwise.
*
* \note This function is only callable from a regular execution context.
* \note This function only operates on mappings that were mapped with the
* VMK_MAPATTRS_MIGHTCHANGE flag.
* \note Changing the attributes of a mapping has significant costs and should
* not be done on a fast path.
* \note This function will not block.
*
******************************************************************************
*/
VMK_ReturnStatus
vmk_MapChangeAttributes(vmk_VA va,
vmk_MapAttrs attrs);
#endif
/** @} */
/** @} */
|