[Xen-devel] [PATCH] [DOCS/RFC]: Xen: Clarification to terms used in hypervisor memory management

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

RFC: All changes here are subject to my current understanding, which might be 
wrong

Memory management is hard[citation needed].  Furthermore, it isn't helped by
the inconsistent use of terms through the code.

Describe the currently-used terms in more practical terms.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CC: Keir Fraser <keir@xxxxxxx>
CC: Jan Beulich <JBeulich@xxxxxxxx>
CC: Tim Deegan <tim@xxxxxxx>
CC: Ian Campbell <ian.campbell@xxxxxxxxxx>
CC: Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>

---

The term 'pfn' is most little awkward, as it currently has two uses in
different areas of the code.  I would argue that the caller of the pagetable
code ought to know exactly if it dealing with an mfn or a gfn in the
pagetables, at which point pfn from the old point of view becomes redundant.

Alternatively, we could standardise on gmfn/gpfn with the g helping to clarify
what is guest value, but those are longer to type.

After we agree on exact terminology, I plan to introduce TYPE_SAFE()'s of
all (most?) terms to the common code.  From this point, cleanup can start to
happen.
---
 xen/include/xen/mm.h |   50 +++++++++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 21 deletions(-)

diff --git a/xen/include/xen/mm.h b/xen/include/xen/mm.h
index a066363..37bc706 100644
--- a/xen/include/xen/mm.h
+++ b/xen/include/xen/mm.h
@@ -1,28 +1,36 @@
 /******************************************************************************
  * include/xen/mm.h
- * 
+ *
  * Definitions for memory pages, frame numbers, addresses, allocations, etc.
- * 
- * Note that Xen must handle several different physical 'address spaces' and
- * there is a consistent terminology for these:
- * 
- * 1. gpfn/gpaddr: A guest-specific pseudo-physical frame number or address.
- * 2. gmfn/gmaddr: A machine address from the p.o.v. of a particular guest.
- * 3. mfn/maddr:   A real machine frame number or address.
- * 4. pfn/paddr:   Used in 'polymorphic' functions that work across all
- *                 address spaces, depending on context. See the pagetable
- *                 conversion macros in asm-x86/page.h for examples.
- *                 Also 'paddr_t' is big enough to store any physical address.
- * 
- * This scheme provides consistent function and variable names even when
- * different guests are running in different memory-management modes.
- * 1. A guest running in auto-translated mode (e.g., shadow_mode_translate())
- *    will have gpfn == gmfn and gmfn != mfn.
- * 2. A paravirtualised x86 guest will have gpfn != gmfn and gmfn == mfn.
- * 3. A paravirtualised guest with no pseudophysical overlay will have
- *    gpfn == gpmfn == mfn.
- * 
+ *
  * Copyright (c) 2002-2006, K A Fraser <keir@xxxxxxxxxxxxx>
+ *
+ *                         +---------------------+
+ *                          Xen Memory Management
+ *                         +---------------------+
+ *
+ * Xen has to handle many different address spaces.  It is important not to
+ * get these spaces mixed up.  The following is a consistent terminology which
+ * should be adhered to.
+ *
+ * mfn: Machine Frame Number
+ *   The values Xen puts into its own pagetables.  This is the host physical
+ *   memory address space with RAM, MMIO etc.
+ *
+ * gfn: Guest Frame Number
+ *   The values a guest puts in its own pagetables.  For an auto-translated
+ *   guest (hardware assisted with 2nd stage translation, or shadowed), gfn !=
+ *   mfn.  For a non-translated guest which is aware of Xen, gfn == mfn.
+ *
+ * pfn: Pseduophysical Frame Number
+ *   A linear idea of a guest physical address space. For an auto-translated
+ *   guest, pfn == gfn while for a non-translated guest, pfn != gfn.
+ *
+ * NOTE: Areas of the code do not use these terms consistently/correctly.  New
+ * code should use these terms as described here, and over time older code
+ * should be corrected to be consistent.  (TODO: remove me when the code is
+ * believed to be consistent)
+ *
  */
 
 #ifndef __XEN_MM_H__
-- 
1.7.10.4


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel