[Xen-devel] [PATCH DOCDAY] hcall: markup the grant table hypercalls to improve generated docs

[Ian Campbell <ian.campbell@xxxxxxxxxx>]

# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# 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@xxxxxxxxxx>

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@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel