1 /* 2 * Copyright (c) 2021-2022 EPAM Systems 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #ifndef __XEN_GNTTAB_H__ 7 #define __XEN_GNTTAB_H__ 8 9 #include <zephyr/xen/public/grant_table.h> 10 11 /* 12 * Assigns gref and permits access to 4K page for specific domain. 13 * 14 * @param domid - id of the domain you sharing gref with 15 * @param gfn - guest frame number of page, where grant will be located 16 * @param readonly - permit readonly access to shared grant 17 * @return - gref assigned to shared grant 18 */ 19 grant_ref_t gnttab_grant_access(domid_t domid, unsigned long gfn, 20 bool readonly); 21 22 /* 23 * Finished access for previously shared grant. Does NOT 24 * free memory, if it was previously allocated by 25 * gnttab_alloc_and_grant(). 26 * 27 * @param gref - grant reference that need to be closed 28 * @return - zero on success, non-zero on failure 29 */ 30 int gnttab_end_access(grant_ref_t gref); 31 32 /* 33 * Allocates 4K page for grant and share it via returned 34 * gref. Need to k_free memory, which was allocated in 35 * @map parameter after grant releasing. 36 * 37 * @param map - double pointer to memory, where grant will be allocated 38 * @param readonly - permit readonly access to allocated grant 39 * @return - grant ref on success or negative errno on failure 40 */ 41 int32_t gnttab_alloc_and_grant(void **map, bool readonly); 42 43 /* 44 * Provides interface to acquire free page, that can be used for 45 * mapping of foreign frames. Should be freed by gnttab_put_page() 46 * after usage. 47 * 48 * @return - pointer to page start address, that can be used as host_addr 49 * in struct gnttab_map_grant_ref, NULL on error. 50 */ 51 void *gnttab_get_page(void); 52 53 /* 54 * Releases provided page, that was used for mapping foreign grant frame, 55 * should be called after unmapping. 56 * 57 * @param page_addr - pointer to start address of used page. 58 */ 59 void gnttab_put_page(void *page_addr); 60 61 /* 62 * Maps foreign grant ref to Zephyr address space. 63 * 64 * @param map_ops - array of prepared gnttab_map_grant_ref's for mapping 65 * @param count - number of grefs in map_ops array 66 * @return - zero on success or negative errno on failure 67 * also per-page status will be set in map_ops[i].status (GNTST_*) 68 * 69 * To map foreign frame you need 4K-aligned 4K memory page, which will be 70 * used as host_addr for grant mapping - it should be acquired by gnttab_get_page() 71 * function. 72 */ 73 int gnttab_map_refs(struct gnttab_map_grant_ref *map_ops, unsigned int count); 74 75 /* 76 * Unmap foreign grant refs. The gnttab_put_page() should be used after this for 77 * each page, that was successfully unmapped. 78 * 79 * @param unmap_ops - array of prepared gnttab_map_grant_ref's for unmapping 80 * @param count - number of grefs in unmap_ops array 81 * @return - @count on success or negative errno on failure 82 * also per-page status will be set in unmap_ops[i].status (GNTST_*) 83 */ 84 int gnttab_unmap_refs(struct gnttab_map_grant_ref *unmap_ops, unsigned int count); 85 86 /* 87 * Convert grant ref status codes (GNTST_*) to text messages. 88 * 89 * @param status - negative GNTST_* code, that needs to be converted 90 * @return - constant pointer to text message, associated with @status 91 */ 92 const char *gnttabop_error(int16_t status); 93 94 #endif /* __XEN_GNTTAB_H__ */ 95
