xen-project/xen
1
0 Fork 1
mirror of https://github.com/xen-project/xen.git synced 2026-10-30 03:00:05 +01:00
Code Issues Activity

hcall: markup the grant table hypercalls to improve generated docs

Browse Source 
As part of this I looked through the relevant chapter from interfaces.tex (from
4.1, deleted in unstable) to ensure no critical information was missing.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Keir Fraser <keir@xen.org>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>
This commit is contained in:
Ian Campbell committed 2012-03-27 11:13:58 +01:00
1 parent ebe5e56248
commit 7db7844927
1 file changed
+76 -34
Download Patch File Download Diff File Expand all files Collapse all files
xen/include/public/grant_table.h
+76 -34
View File
@@ -1,9 +1,9 @@
/******************************************************************************
* grant_table.h
*
*
* Interface for granting foreign access to page frames, and receiving
* page-ownership transfers.
*
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to
* deal in the Software without restriction, including without limitation the
@@ -30,17 +30,41 @@
#include "xen.h"
/*
* `incontents 150 gnttab Grant Tables
*
* Xen's grant tables provide a generic mechanism to memory sharing
* between domains. This shared memory interface underpins the split
* device drivers for block and network IO.
*
* Each domain has its own grant table. This is a data structure that
* is shared with Xen; it allows the domain to tell Xen what kind of
* permissions other domains have on its pages. Entries in the grant
* table are identified by grant references. A grant reference is an
* integer, which indexes into the grant table. It acts as a
* capability which the grantee can use to perform operations on the
* granter’s memory.
*
* This capability-based system allows shared-memory communications
* between unprivileged domains. A grant reference also encapsulates
* the details of a shared page, removing the need for a domain to
* know the real machine address of a page it is sharing. This makes
* it possible to share memory correctly with domains running in
* fully virtualised memory.
*/
/***********************************
* GRANT TABLE REPRESENTATION
*/
/* Some rough guidelines on accessing and updating grant-table entries
* in a concurrency-safe manner. For more information, Linux contains a
* reference implementation for guest OSes (arch/xen/kernel/grant_table.c).
*
* reference implementation for guest OSes (drivers/xen/grant_table.c, see
* http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob;f=drivers/xen/grant-table.c;hb=HEAD
*
* NB. WMB is a no-op on current-generation x86 processors. However, a
* compiler barrier will still be required.
*
*
* Introducing a valid entry into the grant table:
* 1. Write ent->domid.
* 2. Write ent->frame:
@@ -49,7 +73,7 @@
* frame, or zero if none.
* 3. Write memory barrier (WMB).
* 4. Write ent->flags, inc. valid type.
*
*
* Invalidating an unused GTF_permit_access entry:
* 1. flags = ent->flags.
* 2. Observe that !(flags & (GTF_reading|GTF_writing)).
@@ -61,7 +85,7 @@
* This cannot be done directly. Request assistance from the domain controller
* which can set a timeout on the use of a grant entry and take necessary
* action. (NB. This is not yet implemented!).
*
*
* Invalidating an unused GTF_accept_transfer entry:
* 1. flags = ent->flags.
* 2. Observe that !(flags & GTF_transfer_committed). [*]
@@ -79,7 +103,7 @@
*
* Changing a GTF_permit_access from writable to read-only:
* Use SMP-safe CMPXCHG to set GTF_readonly, while checking !GTF_writing.
*
*
* Changing a GTF_permit_access from read-only to writable:
* Use SMP-safe bit-setting instruction.
*/
@@ -261,6 +285,33 @@ typedef uint16_t grant_status_t;
* GRANT TABLE QUERIES AND USES
*/
/* ` enum neg_errnoval
* ` HYPERVISOR_grant_table_op(enum grant_table_op cmd,
* ` void *args,
* ` unsigned int count)
* `
*
* @args points to an array of a per-command data structure. The array
* has @count members
*/
/* ` enum grant_table_op { // GNTTABOP_* => struct gnttab_* */
#define GNTTABOP_map_grant_ref 0
#define GNTTABOP_unmap_grant_ref 1
#define GNTTABOP_setup_table 2
#define GNTTABOP_dump_table 3
#define GNTTABOP_transfer 4
#define GNTTABOP_copy 5
#define GNTTABOP_query_size 6
#define GNTTABOP_unmap_and_replace 7
#if __XEN_INTERFACE_VERSION__ >= 0x0003020a
#define GNTTABOP_set_version 8
#define GNTTABOP_get_status_frames 9
#define GNTTABOP_get_version 10
#define GNTTABOP_swap_grant_ref 11
#endif /* __XEN_INTERFACE_VERSION__ */
/* ` } */
/*
* Handle to track a mapping created via a grant reference.
*/
@@ -277,13 +328,12 @@ typedef uint32_t grant_handle_t;
* 2. If GNTMAP_host_map is specified then a mapping will be added at
* either a host virtual address in the current address space, or at
* a PTE at the specified machine address. The type of mapping to
* perform is selected through the GNTMAP_contains_pte flag, and the
* perform is selected through the GNTMAP_contains_pte flag, and the
* address is specified in <host_addr>.
* 3. Mappings should only be destroyed via GNTTABOP_unmap_grant_ref. If a
* host mapping is destroyed by other means then it is *NOT* guaranteed
* to be accounted to the correct grant reference!
*/
#define GNTTABOP_map_grant_ref 0
struct gnttab_map_grant_ref {
/* IN parameters. */
uint64_t host_addr;
@@ -291,7 +341,7 @@ struct gnttab_map_grant_ref {
grant_ref_t ref;
domid_t dom;
/* OUT parameters. */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
grant_handle_t handle;
uint64_t dev_bus_addr;
};
@@ -309,14 +359,13 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_map_grant_ref_t);
* 3. After executing a batch of unmaps, it is guaranteed that no stale
* mappings will remain in the device or host TLBs.
*/
#define GNTTABOP_unmap_grant_ref 1
struct gnttab_unmap_grant_ref {
/* IN parameters. */
uint64_t host_addr;
uint64_t dev_bus_addr;
grant_handle_t handle;
/* OUT parameters. */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
};
typedef struct gnttab_unmap_grant_ref gnttab_unmap_grant_ref_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t);
@@ -330,13 +379,12 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_grant_ref_t);
* 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
* 3. Xen may not support more than a single grant-table page per domain.
*/
#define GNTTABOP_setup_table 2
struct gnttab_setup_table {
/* IN parameters. */
domid_t dom;
uint32_t nr_frames;
/* OUT parameters. */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
XEN_GUEST_HANDLE(ulong) frame_list;
};
typedef struct gnttab_setup_table gnttab_setup_table_t;
@@ -346,12 +394,11 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_setup_table_t);
* GNTTABOP_dump_table: Dump the contents of the grant table to the
* xen console. Debugging use only.
*/
#define GNTTABOP_dump_table 3
struct gnttab_dump_table {
/* IN parameters. */
domid_t dom;
/* OUT parameters. */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
};
typedef struct gnttab_dump_table gnttab_dump_table_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
@@ -360,11 +407,10 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_dump_table_t);
* GNTTABOP_transfer_grant_ref: Transfer <frame> to a foreign domain. The
* foreign domain has previously registered its interest in the transfer via
* <domid, ref>.
*
*
* Note that, even if the transfer fails, the specified page no longer belongs
* to the calling domain *unless* the error is GNTST_bad_page.
*/
#define GNTTABOP_transfer 4
struct gnttab_transfer {
/* IN parameters. */
xen_pfn_t mfn;
@@ -400,10 +446,9 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_transfer_t);
#define _GNTCOPY_dest_gref (1)
#define GNTCOPY_dest_gref (1<<_GNTCOPY_dest_gref)
#define _GNTCOPY_can_fail (2)
#define GNTCOPY_can_fail (1<<_GNTCOPY_can_fail)
#define GNTCOPY_can_fail (1<<_GNTCOPY_can_fail)
#define GNTTABOP_copy 5
typedef struct gnttab_copy {
struct gnttab_copy {
/* IN parameters. */
struct {
union {
@@ -417,7 +462,8 @@ typedef struct gnttab_copy {
uint16_t flags; /* GNTCOPY_* */
/* OUT parameters. */
int16_t status;
} gnttab_copy_t;
};
typedef struct gnttab_copy gnttab_copy_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_copy_t);
/*
@@ -427,14 +473,13 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_copy_t);
* 1. <dom> may be specified as DOMID_SELF.
* 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
*/
#define GNTTABOP_query_size 6
struct gnttab_query_size {
/* IN parameters. */
domid_t dom;
/* OUT parameters. */
uint32_t nr_frames;
uint32_t max_nr_frames;
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
};
typedef struct gnttab_query_size gnttab_query_size_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_query_size_t);
@@ -450,14 +495,13 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_query_size_t);
* 2. After executing a batch of unmaps, it is guaranteed that no stale
* mappings will remain in the device or host TLBs.
*/
#define GNTTABOP_unmap_and_replace 7
struct gnttab_unmap_and_replace {
/* IN parameters. */
uint64_t host_addr;
uint64_t new_addr;
grant_handle_t handle;
/* OUT parameters. */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
};
typedef struct gnttab_unmap_and_replace gnttab_unmap_and_replace_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_and_replace_t);
@@ -470,7 +514,6 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_unmap_and_replace_t);
* are activated; otherwise, the domain will be stuck with version 1.
* The only defined versions are 1 and 2.
*/
#define GNTTABOP_set_version 8
struct gnttab_set_version {
/* IN/OUT parameters */
uint32_t version;
@@ -491,13 +534,12 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_set_version_t);
* 1. <dom> may be specified as DOMID_SELF.
* 2. Only a sufficiently-privileged domain may specify <dom> != DOMID_SELF.
*/
#define GNTTABOP_get_status_frames 9
struct gnttab_get_status_frames {
/* IN parameters. */
uint32_t nr_frames;
domid_t dom;
/* OUT parameters. */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
XEN_GUEST_HANDLE(uint64_t) frame_list;
};
typedef struct gnttab_get_status_frames gnttab_get_status_frames_t;
@@ -507,7 +549,6 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_get_status_frames_t);
* GNTTABOP_get_version: Get the grant table version which is in
* effect for domain <dom>.
*/
#define GNTTABOP_get_version 10
struct gnttab_get_version {
/* IN parameters */
domid_t dom;
@@ -518,16 +559,15 @@ struct gnttab_get_version {
typedef struct gnttab_get_version gnttab_get_version_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_get_version_t);
/*
/*
* GNTTABOP_swap_grant_ref: Swap the contents of two grant entries.
*/
#define GNTTABOP_swap_grant_ref 11
struct gnttab_swap_grant_ref {
/* IN parameters */
grant_ref_t ref_a;
grant_ref_t ref_b;
/* OUT parameters */
int16_t status; /* GNTST_* */
int16_t status; /* => enum grant_status */
};
typedef struct gnttab_swap_grant_ref gnttab_swap_grant_ref_t;
DEFINE_XEN_GUEST_HANDLE(gnttab_swap_grant_ref_t);
@@ -575,6 +615,7 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_swap_grant_ref_t);
/*
* Values for error status returns. All errors are -ve.
*/
/* ` enum grant_status { */
#define GNTST_okay (0) /* Normal return. */
#define GNTST_general_error (-1) /* General undefined error. */
#define GNTST_bad_domain (-2) /* Unrecognsed domain id. */
@@ -588,6 +629,7 @@ DEFINE_XEN_GUEST_HANDLE(gnttab_swap_grant_ref_t);
#define GNTST_bad_copy_arg (-10) /* copy arguments cross page boundary. */
#define GNTST_address_too_big (-11) /* transfer page address too large. */
#define GNTST_eagain (-12) /* Operation not done; try again. */
/* ` } */
#define GNTTABOP_error_msgs { \
"okay", \
Reference in new issue
xen-project/xen
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.

The note is not visible to the blocked user.