Mailing List Archive

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

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

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);