Xen grant tables

Share memory with foreign domains and map foreign grants. More...

Files
file	gnttab.h
	Xen grant table helpers.

Functions
grant_ref_t	gnttab_grant_access (domid_t domid, unsigned long gfn, bool readonly)
	Grant another domain access to a guest frame.
int	gnttab_end_access (grant_ref_t gref)
	Release a grant reference created by gnttab_grant_access().
int32_t	gnttab_alloc_and_grant (void **map, bool readonly)
	Allocate a page and immediately grant access to it.
void *	gnttab_get_pages (unsigned int npages)
	Allocate pages that can host grant mappings.
int	gnttab_put_pages (void *start_addr, unsigned int npages)
	Release pages allocated by gnttab_get_pages().
int	gnttab_map_refs (struct gnttab_map_grant_ref *map_ops, unsigned int count)
	Map one or more foreign grant references.
int	gnttab_unmap_refs (struct gnttab_unmap_grant_ref *unmap_ops, unsigned int count)
	Unmap one or more foreign grant references.
const char *	gnttabop_error (int16_t status)
	Convert a Xen grant-table status into readable text.

Detailed Description

Share memory with foreign domains and map foreign grants.

Function Documentation

gnttab_alloc_and_grant()

int32_t gnttab_alloc_and_grant	(	void **	map,
		bool	readonly )

#include <zephyr/xen/gnttab.h>

Allocate a page and immediately grant access to it.

The caller must release the grant and then k_free() the buffer returned in map once it is no longer needed.

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

[out]	map	Buffer that receives the page base address.
	readonly	Set to true to grant read-only access.

Returns

Grant reference on success, negative errno value on failure.

Return values

-ENOMEM

Page allocation fails.

gnttab_end_access()

int gnttab_end_access

(

grant_ref_t

gref

)

#include <zephyr/xen/gnttab.h>

Release a grant reference created by gnttab_grant_access().

This does NOT free memory that was previously allocated by gnttab_alloc_and_grant().

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

gref	Grant reference to release.

Return values

0	on success.

gnttab_get_pages()

void * gnttab_get_pages

(

unsigned int

npages

)

#include <zephyr/xen/gnttab.h>

Allocate pages that can host grant mappings.

The returned range is suitable for use as host_addr in struct gnttab_map_grant_ref entries. Release it with gnttab_put_pages() after use.

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

npages

Number of pages to allocate.

Returns

Base address of the allocated range, or NULL on failure.

gnttab_grant_access()

grant_ref_t gnttab_grant_access	(	domid_t	domid,
		unsigned long	gfn,
		bool	readonly )

#include <zephyr/xen/gnttab.h>

Grant another domain access to a guest frame.

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

domid	Foreign domain that receives access to the frame.
gfn	Guest frame number to expose.
readonly	Set to true to grant read-only access.

Returns

Grant reference that identifies the new entry.

gnttab_map_refs()

int gnttab_map_refs	(	struct gnttab_map_grant_ref *	map_ops,
		unsigned int	count )

#include <zephyr/xen/gnttab.h>

Map one or more foreign grant references.

The host_addr pages referenced by map_ops must be 4K-aligned and should be obtained from gnttab_get_pages().

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

[in,out]	map_ops	Array of prepared map operations.
	count	Number of entries in map_ops.

Returns

0 on success, negative errno value on failure.

Return values

-EFAULT

Xen extended regions are enabled and a host address is outside them.

Xen also stores a per-entry status code in each map_ops[i].status field.

gnttab_put_pages()

int gnttab_put_pages	(	void *	start_addr,
		unsigned int	npages )

#include <zephyr/xen/gnttab.h>

Release pages allocated by gnttab_get_pages().

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

start_addr	Base address returned by gnttab_get_pages().
npages	Number of pages to release.

Returns

0 on success, negative errno value on failure.

gnttab_unmap_refs()

int gnttab_unmap_refs	(	struct gnttab_unmap_grant_ref *	unmap_ops,
		unsigned int	count )

#include <zephyr/xen/gnttab.h>

Unmap one or more foreign grant references.

Use gnttab_put_pages() afterwards for the pages that were successfully unmapped.

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

[in,out]	unmap_ops	Array of prepared unmap operations.
	count	Number of entries in unmap_ops.

Returns

Value returned by the GNTTABOP_unmap_grant_ref hypercall (0 on success), negative errno value on failure.

Return values

-EFAULT

Xen extended regions are enabled and a host address is outside them.

Xen also stores a per-entry status code in each unmap_ops[i].status field.

gnttabop_error()

const char * gnttabop_error

(

int16_t

status

)

#include <zephyr/xen/gnttab.h>

Convert a Xen grant-table status into readable text.

Attention

Available only when the following Kconfig option is enabled: CONFIG_XEN_GRANT_TABLE.

Parameters

status

Negative GNTST_* status code.

Returns

Pointer to a constant error string.