Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
gnttab.h
Go to the documentation of this file.
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
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 */
19grant_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 */
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 */
41int32_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 */
51void *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 */
59void 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 */
73int 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 */
84int 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 */
92const char *gnttabop_error(int16_t status);
93
94#endif /* __XEN_GNTTAB_H__ */
ZTEST_BMEM int count
Definition main.c:33
int gnttab_unmap_refs(struct gnttab_map_grant_ref *unmap_ops, unsigned int count)
int gnttab_end_access(grant_ref_t gref)
void gnttab_put_page(void *page_addr)
int gnttab_map_refs(struct gnttab_map_grant_ref *map_ops, unsigned int count)
void * gnttab_get_page(void)
grant_ref_t gnttab_grant_access(domid_t domid, unsigned long gfn, bool readonly)
const char * gnttabop_error(int16_t status)
int32_t gnttab_alloc_and_grant(void **map, bool readonly)
uint32_t grant_ref_t
Definition grant_table.h:116
__INT32_TYPE__ int32_t
Definition stdint.h:74
__INT16_TYPE__ int16_t
Definition stdint.h:73
Definition grant_table.h:266
uint16_t domid_t
Definition xen.h:217