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 one or more pages that can be used for
      45              :  * mapping of foreign frames. Should be freed by gnttab_put_pages()
      46              :  * after use.
      47              :  *
      48              :  * @param npages - number of pages to allocate.
      49              :  * @return - pointer to page start address, that can be used as host_addr
      50              :  *           in struct gnttab_map_grant_ref, NULL on error.
      51              :  */
      52            0 : void *gnttab_get_pages(unsigned int npages);
      53              : 
      54              : /*
      55              :  * Releases pages that were used for mapping foreign grant frames,
      56              :  * should be called after unmapping.
      57              :  *
      58              :  * @param start_addr - pointer to start address of allocated buffer.
      59              :  * @param npages - number of pages allocated for the buffer.
      60              :  * @return - zero on success, non-zero on failure
      61              :  */
      62            0 : int gnttab_put_pages(void *start_addr, unsigned int npages);
      63              : 
      64              : /*
      65              :  * Maps foreign grant ref to Zephyr address space.
      66              :  *
      67              :  * @param map_ops - array of prepared gnttab_map_grant_ref's for mapping
      68              :  * @param count - number of grefs in map_ops array
      69              :  * @return - zero on success or negative errno on failure
      70              :  *           also per-page status will be set in map_ops[i].status (GNTST_*)
      71              :  *
      72              :  * To map foreign frames you need 4K-aligned memory pages, which will be
      73              :  * used as host_addr for grant mapping - it should be acquired by gnttab_get_pages()
      74              :  * function.
      75              :  */
      76            0 : int gnttab_map_refs(struct gnttab_map_grant_ref *map_ops, unsigned int count);
      77              : 
      78              : /*
      79              :  * Unmap foreign grant refs. The gnttab_put_pages() should be used after this for
      80              :  * pages that were successfully unmapped.
      81              :  *
      82              :  * @param unmap_ops - array of prepared gnttab_unmap_grant_ref's for unmapping
      83              :  * @param count - number of grefs in unmap_ops array
      84              :  * @return - @count on success or negative errno on failure
      85              :  *           also per-page status will be set in unmap_ops[i].status (GNTST_*)
      86              :  */
      87            0 : int gnttab_unmap_refs(struct gnttab_unmap_grant_ref *unmap_ops, unsigned int count);
      88              : 
      89              : /*
      90              :  * Convert grant ref status codes (GNTST_*) to text messages.
      91              :  *
      92              :  * @param status - negative GNTST_* code, that needs to be converted
      93              :  * @return - constant pointer to text message, associated with @status
      94              :  */
      95            0 : const char *gnttabop_error(int16_t status);
      96              : 
      97              : #endif /* __XEN_GNTTAB_H__ */