Line data    Source code

       1            0 : /*
       2              :  * Copyright (c) 2021-2024 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            0 : 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            0 : 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            0 : 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            0 : 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            0 : 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            0 : 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_unmap_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            0 : int gnttab_unmap_refs(struct gnttab_unmap_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            0 : const char *gnttabop_error(int16_t status);
      93              : 
      94              : #endif /* __XEN_GNTTAB_H__ */