github.com/jlmucb/cloudproxy@v0.0.0-20170830161738-b5aa0b619bc4/cpvmm/vmm/include/memory_address_mapper_api.h (about) 1 /* 2 * Copyright (c) 2013 Intel Corporation 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * Unless required by applicable law or agreed to in writing, software 9 * distributed under the License is distributed on an "AS IS" BASIS, 10 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11 * See the License for the specific language governing permissions and 12 * limitations under the License. 13 */ 14 15 16 // API description of Memory Address Mapper 17 18 #ifndef MEMORY_ADDRESS_MAPPER_API_H 19 #define MEMORY_ADDRESS_MAPPER_API_H 20 21 #include <vmm_defs.h> 22 23 24 typedef void* MAM_HANDLE; 25 #define MAM_INVALID_HANDLE ((MAM_HANDLE)NULL) 26 27 typedef UINT64 MAM_MEMORY_RANGES_ITERATOR; 28 #define MAM_INVALID_MEMORY_RANGES_ITERATOR (~((UINT64)0x0)) 29 30 typedef union MAM_ATTRIBUTES_U { 31 32 UINT32 uint32; 33 34 struct { 35 UINT32 36 writable :1, 37 user :1, 38 executable :1, 39 global :1, 40 pat_index :3, 41 tmsl :1, 42 noaccess :1, 43 reserved :23; // must be zero 44 } paging_attr; 45 46 struct { 47 UINT32 48 readable :1, 49 writable :1, 50 executable :1, 51 igmt :1, 52 emt :3, 53 suppress_ve:1, 54 reserved :24; // must be zero 55 } ept_attr; 56 57 struct { 58 UINT32 59 readable :1, 60 writable :1, 61 snoop :1, 62 tm :1, 63 reserved :28; // must be zero 64 } vtdpt_attr; 65 66 } MAM_ATTRIBUTES; 67 68 extern const MAM_ATTRIBUTES mam_no_attributes; 69 extern MAM_ATTRIBUTES mam_rwx_attrs; 70 extern MAM_ATTRIBUTES mam_rw_attrs; 71 extern MAM_ATTRIBUTES mam_ro_attrs; 72 73 #define EPT_NO_PERM 0x0 //no rwx 74 #define EPT_WO_PERM 0x2 //write only no rx 75 #define EPT_XO_PERM 0x4 //exec no rw 76 #define EPT_WX_PERM 0x6 //write exec no r 77 78 #define MAM_NO_ATTRIBUTES mam_no_attributes 79 80 typedef UINT32 MAM_MAPPING_RESULT; 81 #define MAM_MAPPING_SUCCESSFUL ((MAM_MAPPING_RESULT)0x0) 82 #define MAM_UNKNOWN_MAPPING ((MAM_MAPPING_RESULT)0x7fffffff) 83 84 85 /* Function: mam_create_mapping 86 * Description: This function should be called in order to 87 * create new mapping. 88 * Afterwards the mapping may be filled by using functions 89 * "mam_insert_range" and "mam_insert_not_existing_range". 90 * Input: inner_level_attributes - attributes for inner levels (relevant for 91 * hardware compliant mappings) 92 * If attributes are not relevant, use MAM_NO_ATTRIBUTES 93 * as the value 94 * Output: Handle which will be used in all other functions. 95 */ 96 MAM_HANDLE mam_create_mapping(MAM_ATTRIBUTES inner_level_attributes); 97 98 99 /* Function: mam_destroy_mapping 100 * Description: Destroys all data structures relevant to particular 101 * mapping. 102 * Input: handle created by "mam_create_mapping". 103 */ 104 void mam_destroy_mapping(IN MAM_HANDLE mam_handle); 105 106 /* Function: mam_clone 107 * Description: Clone the existing mapping. 108 * Input: handle created by "mam_create_mapping". 109 */ 110 MAM_HANDLE mam_clone(IN MAM_HANDLE mam_handle); 111 112 /* Function: mam_get_mapping 113 * Description: return the information inserted by "mam_insert_range" and 114 * "mam_insert_not_existing_range" functions. 115 * Input: mam_handle - handle created by "mam_create_mapping"; 116 * src_addr - source address 117 * Return Value: 118 * - MAM_MAPPING_SUCCESSFUL in this case there are additional output parameters: 119 * tgt_addr and attrs 120 * - MAM_UNKNOWN_MAPPING in case when query is performed and address 121 * that was never inserted neither by "mam_insert_range" nor by 122 * "mam_insert_not_existing_range" functions. 123 * - other value of type MAM_MAPPING_RESULT in case when query is performed 124 * for address which was updated by "mam_insert_not_existing_range" before 125 * with this value as "reason" parameter. 126 * Output: 127 * - tgt_addr - mapped address in case when "Return Value" is MAM_MAPPING_SUCCESSFUL 128 * - attrs - attributes of mapped address when "Return Value" is MAM_MAPPING_SUCCESSFUL 129 */ 130 MAM_MAPPING_RESULT mam_get_mapping(IN MAM_HANDLE mam_handle, 131 IN UINT64 src_addr, OUT UINT64* tgt_addr, 132 OUT MAM_ATTRIBUTES* attrs); 133 134 135 /* Function: mam_insert_range 136 * Description: Inserts new mapping into the data structures. It is 137 * possible to overwrite existing mappings. For example, 138 * create 4G of identical mapping: 139 * mam_insert_range(handle, 0, 0, 4G, attrs) 140 * then overwrite some range in the middle: 141 * mam_insert_range(handle, src, tgt, 1M, other_attrs) 142 * Input: mam_handle - handle created by "mam_create_mapping"; 143 * src_addr - source address 144 * tgt_addr - target address 145 * size - size of the range 146 * attrs - attributes 147 * Return value: - TRUE in case of success, the query done by "mam_get_mapping" function 148 * on any src_addr inside the mapped range will be successful and return 149 * value will be MAM_MAPPING_SUCCESSFUL. 150 * - FALSE when there was not enough memory to allocate for internal data 151 * structures, hence the mapping wasn't successful. In this case the internal 152 * mapping may be partial, i.e. only part of the requested range will be mapped, 153 * and the remaining part will remain with previous information. 154 */ 155 BOOLEAN mam_insert_range(IN MAM_HANDLE mam_handle, IN UINT64 src_addr, 156 IN UINT64 tgt_addr, IN UINT64 size, 157 IN MAM_ATTRIBUTES attrs); 158 159 160 /* Function: mam_insert_not_existing_range 161 * Description: Inserts new information (reason) or overwrites existing 162 * one: why the current range is unmapped. It is possible 163 * to overwrite the existing information in a similar way 164 * as with "mam_insert_range" function. 165 * Input: mam_handle - handle created by "mam_create_mapping"; 166 * src_addr - source address 167 * size - size of the range 168 * reason - this value will be returned by "mam_get_mapping" function 169 * on any query inside the range. This value should be defined 170 * by client and it mustn't be equal to one of the predefined 171 * values: "MAM_MAPPING_SUCCESSFUL" and "MAM_UNKNOWN_MAPPING" 172 * Return value: - TRUE in case of success, the query done by "mam_get_mapping" function 173 * on any src_addr inside the mapped range will return the "reason". 174 * - FALSE when there was not enough memory to allocate for internal data 175 * structures, hence the mapping wasn't successful. In this case the internal 176 * mapping may be partial, i.e. only part of the requested range will be mapped, 177 * and the remaining part will remain with previous information. 178 */ 179 BOOLEAN mam_insert_not_existing_range(IN MAM_HANDLE mam_handle, 180 IN UINT64 src_addr, IN UINT64 size, 181 IN MAM_MAPPING_RESULT reason); 182 183 184 /* Function: mam_add_permissions_to_existing_mapping 185 * Description: This function enables adding permissions to already existing ones. If mapping doesn't exist 186 * nothing will happen. Note that "pat_index" for page tables attributes and "emt" for ept attributes 187 * should be "0" in added attributes. Otherwise the updated pat_index or "emt" will be updated in a way 188 * that is not expected by the caller. 189 * Input: mam_handle - handle created by "mam_create_mapping"; 190 * src_addr - source address 191 * size - 192 * attrs - attributes to add. 193 * Return value: - TRUE in this case of success. In this case there is additional output parameter 194 * - FALSE in case of insufficient memory. 195 */ 196 BOOLEAN mam_add_permissions_to_existing_mapping(IN MAM_HANDLE mam_handle, 197 IN UINT64 src_addr, IN UINT64 size, 198 IN MAM_ATTRIBUTES attrs); 199 200 201 /* Function: mam_remove_permissions_from_existing_mapping 202 * Description: This function enables removing permissions to already existing mappings. If mapping doesn't exist 203 * nothing will happen. Note that "pat_index" for page tables attributes and "emt" for ept attributes 204 * should be "0" in removed attributes. Otherwise the updated pat_index or "emt" will be updated in a way 205 * that is not expected by the caller. 206 * Input: nam_handle - handle created by "mam_create_mapping"; 207 * src_addr - source address 208 * size - 209 * attrs - attributes to remove. 210 * Return value: - TRUE in this case of success. In this case there is additional output parameter 211 * first_table_out - Host Physical Address of first table (PML4T). 212 * - FALSE in case of insufficient memory. 213 */ 214 BOOLEAN mam_remove_permissions_from_existing_mapping(IN MAM_HANDLE mam_handle, 215 IN UINT64 src_addr, IN UINT64 size, 216 IN MAM_ATTRIBUTES attrs); 217 218 /* Function: mam_convert_to_64bit_page_tables 219 * Description: This functions converts internal optimized mapping to 64 bits page Tables. 220 * From now on there is no way back to optimized mapping. 221 * All the operations will be performed on unoptimized mapping. 222 * Input: mam_handle - handle created by "mam_create_mapping"; 223 * Return value: - TRUE in this case of success. In this case there is additional output parameter 224 * first_table_out - Host Physical Address of first table (PML4T). 225 * - FALSE in case of insufficient memory. 226 */ 227 BOOLEAN mam_convert_to_64bit_page_tables(IN MAM_HANDLE mam_handle, 228 OUT UINT64* pml4t_hpa); 229 230 /* Function: mam_convert_to_32bit_pae_page_tables 231 * Description: This functions converts internal optimized mapping to 32 bit PAE page tables. 232 * From now on there is no way back to optimized mapping. 233 * All the operations will be performed on unoptimized mapping. 234 * Input: mam_handle - handle created by "gam_create_mapping"; 235 * Return value: - TRUE in this case of success. In this case there is additional output parameter 236 * first_table_out - Host Physical Address of first table (PDPT). 237 * - FALSE in case of insufficient memory. 238 */ 239 BOOLEAN mam_convert_to_32bit_pae_page_tables(IN MAM_HANDLE mam_handle, 240 OUT UINT32* pdpt_hpa); 241 242 /* Function: mam_get_memory_ranges_iterator 243 * Description: This function returns the iterator, using which it is possible to iterate 244 * over existing mappings. 245 * Input: mam_handle - handle created by "mam_create_mapping"; 246 * Ret value: - Iterator value. NULL iterator has value: MAM_INVALID_MEMORY_RANGES_ITERATOR 247 */ 248 MAM_MEMORY_RANGES_ITERATOR mam_get_memory_ranges_iterator(IN MAM_HANDLE mam_handle); 249 250 251 /* Function: mam_get_range_details_from_iterator 252 * Description: Use this function in order to retrieve the details of memory range pointed by iterator. 253 * Input: mam_handle - handle created by "mam_create_mapping"; 254 * iter - iterator value 255 * Output: src_addr - source address of the existing mapping range. In case 256 * the "iter" has MAM_INVALID_MEMORY_RANGES_ITERATOR value, src_addr will 257 * have 0xfffffffffffffff value. 258 * size - size of the range. In case the "iter" has MAM_INVALID_MEMORY_RANGES_ITERATOR 259 * value, size will be 0. 260 * Ret value: - new iterator. 261 */ 262 MAM_MEMORY_RANGES_ITERATOR mam_get_range_details_from_iterator( 263 IN MAM_HANDLE mam_handle, 264 IN MAM_MEMORY_RANGES_ITERATOR iter, 265 OUT UINT64* src_addr, OUT UINT64* size); 266 #ifdef INCLUDE_UNUSED_CODE 267 /* Function: mam_iterator_get_next 268 * Description: Use this function in order to advance iterator to the next range. 269 * Input: mam_handle - handle created by "mam_create_mapping"; 270 * iter - iterator value 271 * Ret value: - new iterator. 272 */ 273 MAM_MEMORY_RANGES_ITERATOR mam_iterator_get_next(IN MAM_HANDLE mam_handle, 274 MAM_MEMORY_RANGES_ITERATOR iter); 275 #endif 276 277 /* Function: mam_get_range_start_address_from_iterator 278 * Description: Use this function in order to retrieve the source address of the range pointed by iterator. 279 * Input: mam_handle - handle created by "mam_create_mapping"; 280 * iter - iterator value 281 * Ret value: - address. In case when iterator has value MAM_INVALID_MEMORY_RANGES_ITERATOR, the 0xffffffffffffffff is 282 * returned. 283 */ 284 UINT64 mam_get_range_start_address_from_iterator(IN MAM_HANDLE mam_handle, 285 MAM_MEMORY_RANGES_ITERATOR iter); 286 287 typedef UINT32 MAM_EPT_SUPER_PAGE_SUPPORT; 288 #define MAM_EPT_NO_SUPER_PAGE_SUPPORT 0x0 289 #define MAM_EPT_SUPPORT_2MB_PAGE 0x1 290 #define MAM_EPT_SUPPORT_1GB_PAGE 0x2 291 #define MAM_EPT_SUPPORT_512_GB_PAGE 0x4 292 293 typedef enum { 294 MAM_EPT_21_BITS_GAW = 0, 295 MAM_EPT_30_BITS_GAW, 296 MAM_EPT_39_BITS_GAW, 297 MAM_EPT_48_BITS_GAW 298 } MAM_EPT_SUPPORTED_GAW; 299 300 301 /* Function: mam_convert_to_ept 302 * Description: This functions converts internal optimized mapping to ept. 303 * From now on there is no way back to optimized mapping. 304 * All the operations will be performed on unoptimized mapping. 305 * Input: mam_handle - handle created by "mam_create_mapping"; 306 * ept_super_page_support - information of which super page can be supported by hardware (bitmask) 307 * ept_supported_gaw - Information of how many internal level should there be. 308 * Note that this information should be compliant with one which will be 309 * recorded in EPTR!!! 310 * ept_hw_ve_support - Hardware #VE support flag 311 * Return value: - TRUE in this case of success. In this case there is additional output parameter 312 * first_table_out - Host Physical Address of first table. 313 * - FALSE in case of insufficient memory. 314 */ 315 BOOLEAN mam_convert_to_ept(IN MAM_HANDLE mam_handle, 316 IN MAM_EPT_SUPER_PAGE_SUPPORT ept_super_page_support, 317 IN MAM_EPT_SUPPORTED_GAW ept_supported_gaw, 318 IN BOOLEAN ept_hw_ve_support, OUT UINT64* first_table_hpa); 319 320 typedef UINT8 MAM_VTDPT_SUPER_PAGE_SUPPORT; 321 #define MAM_VTDPT_SUPPORT_2MB_PAGE 0x1 322 #define MAM_VTDPT_SUPPORT_1GB_PAGE 0x2 323 #define MAM_VTDPT_SUPPORT_512_GB_PAGE 0x4 324 325 typedef UINT8 MAM_VTDPT_SNOOP_BEHAVIOR; 326 typedef UINT8 MAM_VTDPT_TRANS_MAPPING; 327 328 typedef enum { 329 MAM_VTDPT_21_BITS_GAW = 0, 330 MAM_VTDPT_30_BITS_GAW, 331 MAM_VTDPT_39_BITS_GAW, 332 MAM_VTDPT_48_BITS_GAW 333 } MAM_VTDPT_SUPPORTED_GAW; 334 335 /* Function: mam_convert_to_vtdpt 336 * Description: This functions converts internal optimized mapping to VT-d page table. 337 * From now on there is no way back to optimized mapping. 338 * All the operations will be performed on unoptimized mapping. 339 * Input: mam_handle - handle created by "mam_create_mapping"; 340 * vtdpt_super_page_support - information of which super page can be supported by hardware (bitmask) 341 * vtdpt_snoop_behavior - snoop behavior supported by the hardware, treated as reserved: 342 * 1. Always in non-leaf entries 343 * 2. In leaf entries, as hardware implementations reporting SC (Snoop Control) 344 * as clear in the extended capability register 345 * vtdpt_trans_mapping - transient mapping supported by hardware, treated as reserved: 346 * 1. Always in non-leaf entries 347 * 2. In leaf entries, as hardware implementations reporting CH (Caching Hints) 348 * and Device-IOTLB (DI) fields as clear in the extended capability register 349 * vtdpt_supported_gaw - Information of how many internal level supported by the hardware 350 * Return value: - TRUE in this case of success. In this case there is additional output parameter 351 * first_table_out - Host Physical Address of first table. 352 * - FALSE in case of insufficient memory. 353 */ 354 BOOLEAN mam_convert_to_vtdpt(IN MAM_HANDLE mam_handle, 355 IN MAM_VTDPT_SUPER_PAGE_SUPPORT vtdpt_super_page_support, 356 IN MAM_VTDPT_SNOOP_BEHAVIOR vtdpt_snoop_behavior, 357 IN MAM_VTDPT_TRANS_MAPPING vtdpt_trans_mapping, 358 IN UINT32 sagaw_index_bit, OUT UINT64* first_table_hpa); 359 360 void mam_print_page_usage(IN MAM_HANDLE mam_handle); 361 362 #endif