Ian Campbell
2012-Feb-27 15:46 UTC
[PATCH DOCDAY] hcall: markup the grant table hypercalls to improve generated docs
# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1330357554 0
# Node ID da2738f5050d9487313f29f4a069a8a2bacb6b55
# Parent b6a3a0d68c91ce8fa6023aee3046efd3866942df
hcall: markup the grant table hypercalls to improve generated docs
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>
diff -r b6a3a0d68c91 -r da2738f5050d xen/include/public/grant_table.h
--- a/xen/include/public/grant_table.h Mon Feb 27 12:36:47 2012 +0000
+++ b/xen/include/public/grant_table.h Mon Feb 27 15:45:54 2012 +0000
@@ -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
* 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_gra
* 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_tab
* 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_tabl
* 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_
#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_siz
* 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
* 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_versi
* 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_statu
* 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_gran
/*
* 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_gran
#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", \
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel
Keir Fraser
2012-Feb-27 18:55 UTC
Re: [PATCH DOCDAY] hcall: markup the grant table hypercalls to improve generated docs
On 27/02/2012 15:46, "Ian Campbell" <ian.campbell@citrix.com> wrote:> # HG changeset patch# User Ian Campbell <ian.campbell@citrix.com> # Date> 1330357554 0# Node ID da2738f5050d9487313f29f4a069a8a2bacb6b55 # Parent> b6a3a0d68c91ce8fa6023aee3046efd3866942dfhcall: markup the grant table> hypercalls to improve generated docsAs part of this I looked through the> relevant chapter from interfaces.tex (from4.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>
Ian Jackson
2012-Mar-01 16:53 UTC
Re: [PATCH DOCDAY] hcall: markup the grant table hypercalls to improve generated docs
Ian Campbell writes ("[Xen-devel] [PATCH DOCDAY] hcall: markup the grant
table hypercalls to improve generated docs"):> hcall: markup the grant table hypercalls to improve generated docs
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>