Line data    Source code

       1           0 : /*
       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           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_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           0 : 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           0 : const char *gnttabop_error(int16_t status);
      93             : 
      94             : #endif /* __XEN_GNTTAB_H__ */