[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Xen-devel] [PATCH 8 of 8 DOCDAY] docs: hypercall: document mmuext_op using Doxygen



# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# Date 1319633085 -3600
# Node ID 78d2ade5f1fc301ad60eba6343fae78d575c85af
# Parent  1dd6bb4612b4f11bf52fa7ac21321227b6560e0e
docs: hypercall: document mmuext_op using Doxygen

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

diff --git a/docs/hypercall.Doxyfile b/docs/hypercall.Doxyfile
--- a/docs/hypercall.Doxyfile
+++ b/docs/hypercall.Doxyfile
@@ -1369,7 +1369,9 @@ PREDEFINED             = "__XEN_INTERFAC
                          "XEN_GUEST_HANDLE(name)=GUEST_##name *" \
                          "XEN_GUEST_HANDLE_64(name)= GUEST_##name *" \
                          "DEFINE_XEN_GUEST_HANDLE(name)=typedef name 
GUEST_##name;typedef const name GUEST_const_##name" \
-                         "__DEFINE_XEN_GUEST_HANDLE(name,type)=typedef name 
GUEST_##name; typedef const type GUEST_const_##name"
+                         "__DEFINE_XEN_GUEST_HANDLE(name,type)=typedef name 
GUEST_##name; typedef const type GUEST_const_##name" \
+                        "__DOXYGEN__=1" \
+                        "ANON(x)="
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
 # this tag can be used to specify a list of macro names that should be 
expanded.
diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -51,6 +51,11 @@ DEFINE_XEN_GUEST_HANDLE(uint64_t);
 DEFINE_XEN_GUEST_HANDLE(xen_pfn_t);
 #endif
 
+/* Indicates a member which would be anonymous if compilers reliably
+ * supported that kind of thing.
+ */
+#define ANON(x) x
+
 /*
  * HYPERCALLS
  */
@@ -202,107 +207,193 @@ DEFINE_XEN_GUEST_HANDLE(xen_pfn_t);
 #define MMU_MACHPHYS_UPDATE       1 /* ptr = MA of frame to modify entry for */
 #define MMU_PT_UPDATE_PRESERVE_AD 2 /* atomically: *ptr = val | (*ptr&(A|D)) */
 
-/*
- * MMU EXTENDED OPERATIONS
- * 
- * HYPERVISOR_mmuext_op() accepts a list of mmuext_op structures.
- * A foreigndom (FD) can be specified (or DOMID_SELF for none).
- * Where the FD has some effect, it is described below.
- * 
- * cmd: MMUEXT_(UN)PIN_*_TABLE
- * mfn: Machine frame number to be (un)pinned as a p.t. page.
- *      The frame must belong to the FD, if one is specified.
- * 
- * cmd: MMUEXT_NEW_BASEPTR
- * mfn: Machine frame number of new page-table base to install in MMU.
- * 
- * cmd: MMUEXT_NEW_USER_BASEPTR [x86/64 only]
- * mfn: Machine frame number of new page-table base to install in MMU
- *      when in user space.
- * 
- * cmd: MMUEXT_TLB_FLUSH_LOCAL
- * No additional arguments. Flushes local TLB.
- * 
- * cmd: MMUEXT_INVLPG_LOCAL
- * linear_addr: Linear address to be flushed from the local TLB.
- * 
- * cmd: MMUEXT_TLB_FLUSH_MULTI
- * vcpumask: Pointer to bitmap of VCPUs to be flushed.
- * 
- * cmd: MMUEXT_INVLPG_MULTI
- * linear_addr: Linear address to be flushed.
- * vcpumask: Pointer to bitmap of VCPUs to be flushed.
- * 
- * cmd: MMUEXT_TLB_FLUSH_ALL
- * No additional arguments. Flushes all VCPUs' TLBs.
- * 
- * cmd: MMUEXT_INVLPG_ALL
- * linear_addr: Linear address to be flushed from all VCPUs' TLBs.
- * 
- * cmd: MMUEXT_FLUSH_CACHE
- * No additional arguments. Writes back and flushes cache contents.
+/**
+ * \defgroup HYPERVISOR_mmuext_op MMU EXTENDED OPERATIONS
  *
- * cmd: MMUEXT_FLUSH_CACHE_GLOBAL
- * No additional arguments. Writes back and flushes cache contents
- * on all CPUs in the system.
- * 
- * cmd: MMUEXT_SET_LDT
- * linear_addr: Linear address of LDT base (NB. must be page-aligned).
- * nr_ents: Number of entries in LDT.
+ * extended MMU command interface.
  *
- * cmd: MMUEXT_CLEAR_PAGE
- * mfn: Machine frame number to be cleared.
+ * An additional MMU hypercall provides an `extended command'
+ * interface. This provides additional functionality beyond the basic
+ * table updating commands. This hypercall is used to perform
+ * additional MMU operations. These include updating cr3 (or just
+ * re-installing it for a TLB flush), requesting various kinds of TLB
+ * flush, flushing the cache, installing a new LDT, or pinning &
+ * unpinning page-table pages (to ensure their reference count doesnât
+ * drop to zero which would require a revalidation of all entries). Some
+ * of the operations available are restricted to domains with sufficient
+ * system privileges.  It is also possible for privileged domains to
+ * reassign page ownership via an extended MMU operation, although grant
+ * tables are used in- stead of this where possible
+ */
+/**
+ * HYPERVISOR_mmuext_op() accepts a list of extended operations to perform.
  *
- * cmd: MMUEXT_COPY_PAGE
- * mfn: Machine frame number of the destination page.
- * src_mfn: Machine frame number of the source page.
- *
- * cmd: MMUEXT_[UN]MARK_SUPER
- * mfn: Machine frame number of head of superpage to be [un]marked.
+ * \ingroup HYPERVISOR_mmuext_op
+ * \arg \c uops       List of operations to perform.
+ * \arg \c count      Number of operations in \c uops.
+ * \arg \c pdone      An output pointer. \c pdone will be updated to the number
+ *                    of operations which were completed.
+ * \arg \c foreigndom A foreign domain id or \c DOMID_SELF. Where \c foreigndom
+ *                    has some effect it is described in the relevant
+ *                    \c MMUEXT_* documentation.
+ */
+#ifdef __DOXYGEN__
+int HYPERVISOR_mmuext_op(
+    XEN_GUEST_HANDLE(mmuext_op_t) uops,
+    unsigned int count,
+    XEN_GUEST_HANDLE(uint) pdone,
+    unsigned int foreigndom);
+#endif
+
+/** \ingroup HYPERVISOR_mmuext_op
+ * Pin a page as an L1 page-table.
+ * \arg \c mfn Machine frame number to be pinned as an L1 page-table page.
+ *      The frame must belong to the \c foreigndom, if one is specified.
  */
 #define MMUEXT_PIN_L1_TABLE      0
+/** \ingroup HYPERVISOR_mmuext_op
+ * Pin a page as an L2 page-table.
+ * \arg \c mfn Machine frame number to be pinned as an L2 page-table page.
+ *      The frame must belong to the \c foreigndom, if one is specified.
+ */
 #define MMUEXT_PIN_L2_TABLE      1
+/** \ingroup HYPERVISOR_mmuext_op
+ * Pin a page as an L3 page-table.
+ * \arg \c mfn Machine frame number to be pinned as an L3 page-table page.
+ *      The frame must belong to the \c foreigndom, if one is specified.
+ */
 #define MMUEXT_PIN_L3_TABLE      2
+/** \ingroup HYPERVISOR_mmuext_op
+ * Pin a page as an L4 page-table.
+ * \arg \c mfn Machine frame number to be pinned as an L4 page-table page.
+ *      The frame must belong to the \c foreigndom, if one is specified.
+ */
 #define MMUEXT_PIN_L4_TABLE      3
+/** \ingroup HYPERVISOR_mmuext_op
+ * Unpin a page as a page-table.
+ * \arg \c mfn Machine frame number to be unpinned as a page-table page.
+ *      The frame must belong to the \c foreigndom, if one is specified.
+ */
 #define MMUEXT_UNPIN_TABLE       4
+/** \ingroup HYPERVISOR_mmuext_op
+ * Install a new page-table base.
+ * \arg \c mfn Machine frame number of new page-table base to install in MMU.
+ */
 #define MMUEXT_NEW_BASEPTR       5
+/** \ingroup HYPERVISOR_mmuext_op
+ * Flushes local TLB.
+ * No additional arguments.
+ */
 #define MMUEXT_TLB_FLUSH_LOCAL   6
+/** \ingroup HYPERVISOR_mmuext_op
+ * Flush a specific page from local TLB by linear address.
+ * \arg \c linear_addr Linear address to be flushed from the local TLB.
+ */
 #define MMUEXT_INVLPG_LOCAL      7
+/** \ingroup HYPERVISOR_mmuext_op
+ * Flush a subset of VCPUs' TLBs.
+ * \arg \c vcpumask Pointer to bitmap of VCPUs to be flushed.
+ */
 #define MMUEXT_TLB_FLUSH_MULTI   8
+/** \ingroup HYPERVISOR_mmuext_op
+ * Flush a specific page from subset of VCPUs' TLBs by linear address.
+ * \arg \c linear_addr Linear address to be flushed.
+ * \arg \c vcpumask Pointer to bitmap of VCPUs to be flushed.
+ */
 #define MMUEXT_INVLPG_MULTI      9
+/** \ingroup HYPERVISOR_mmuext_op
+ * Flush all CPUs' TLBs.
+ * No additional arguments.
+ */
 #define MMUEXT_TLB_FLUSH_ALL    10
+/** \ingroup HYPERVISOR_mmuext_op
+ * Flush a specific page form all VCPUs' TLBs by linear address.
+ * \arg \c linear_addr Linear address to be flushed from all VCPUs' TLBs.
+ */
 #define MMUEXT_INVLPG_ALL       11
+/** \ingroup HYPERVISOR_mmuext_op
+ * Writes back and flushes cache contents.
+ * No additional arguments.
+ *
+ */
 #define MMUEXT_FLUSH_CACHE      12
+/** \ingroup HYPERVISOR_mmuext_op
+ * Set the LDT [x86 only].
+ * \arg \c linear_addr Linear address of LDT base (NB. must be page-aligned).
+ * \arg \c nr_ents Number of entries in LDT.
+ */
 #define MMUEXT_SET_LDT          13
+/** \ingroup HYPERVISOR_mmuext_op
+ * Install a new user page-table base [x86/64 only].
+ * \arg \c mfn: Machine frame number of new page-table base to install in MMU
+ *      when in user space.
+ */
 #define MMUEXT_NEW_USER_BASEPTR 15
+/** \ingroup HYPERVISOR_mmuext_op
+ * Clear a page of memory.
+ * \arg \c mfn Machine frame number to be cleared.
+ */
 #define MMUEXT_CLEAR_PAGE       16
+/** \ingroup HYPERVISOR_mmuext_op
+ * Copy a page.
+ * \arg \c mfn Machine frame number of the destination page.
+ * \arg \c src_mfn Machine frame number of the source page.
+ */
 #define MMUEXT_COPY_PAGE        17
+/** \ingroup HYPERVISOR_mmuext_op
+ * Writes back and flushes cache contents on all CPUs in the system.
+ * No additional arguments.
+ */
 #define MMUEXT_FLUSH_CACHE_GLOBAL 18
+/** \ingroup HYPERVISOR_mmuext_op
+ * Mark a page as a super-page.
+ * mfn: Machine frame number of head of superpage to be marked.
+ */
 #define MMUEXT_MARK_SUPER       19
+/** \ingroup HYPERVISOR_mmuext_op
+ * Unmark a page as a super-page.
+ * mfn: Machine frame number of head of superpage to be unmarked.
+ */
 #define MMUEXT_UNMARK_SUPER     20
 
 #ifndef __ASSEMBLY__
+/** \ingroup HYPERVISOR_mmuext_op
+ *
+ * struct mmuext_op is passed as the \c uop argument to HYPERVISOR_mmuext_op()
+ */
 struct mmuext_op {
+    /**
+     * Subcommand, one of MMUEXT_*. The specific command defines
+     * which of the union members (if any) are used.
+     */
     unsigned int cmd;
     union {
-        /* [UN]PIN_TABLE, NEW_BASEPTR, NEW_USER_BASEPTR
-         * CLEAR_PAGE, COPY_PAGE, [UN]MARK_SUPER */
+        /**
+         * A machine frame number to act upon. Users include [UN]PIN_TABLE,
+         * NEW_BASEPTR, NEW_USER_BASEPTR, CLEAR_PAGE, COPY_PAGE, 
[UN]MARK_SUPER.
+         */
         xen_pfn_t     mfn;
-        /* INVLPG_LOCAL, INVLPG_ALL, SET_LDT */
+        /**
+         * A linear address to act upon. Users include INVLPG_LOCAL, 
INVLPG_ALL,
+         * SET_LDT.
+         */
         unsigned long linear_addr;
-    } arg1;
+    } ANON(arg1);
     union {
-        /* SET_LDT */
+        /** The number of LDT entries passed to SET_LDT in linear_addr. */
         unsigned int nr_ents;
-        /* TLB_FLUSH_MULTI, INVLPG_MULTI */
+        /**
+         * A mask of VCPUs to operate on. Users include TLB_FLUSH_MULTI and
+         * INVLPG_MULTI.
+         */
 #if __XEN_INTERFACE_VERSION__ >= 0x00030205
         XEN_GUEST_HANDLE(const_void) vcpumask;
 #else
         const void *vcpumask;
 #endif
-        /* COPY_PAGE */
+        /** The source machine-frame to COPY_PAGE. */
         xen_pfn_t src_mfn;
-    } arg2;
+    } ANON(arg2);
 };
 typedef struct mmuext_op mmuext_op_t;
 DEFINE_XEN_GUEST_HANDLE(mmuext_op_t);
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.