[Xen-devel] [PATCH 2 of 3] xenpaging: document p2m_mem_paging functions

[Olaf Hering <olaf@xxxxxxxxx>]

# HG changeset patch
# User Olaf Hering <olaf@xxxxxxxxx>
# Date 1319034159 -7200
# Node ID cc6184fcd784f94165417073935c5fd0c4b4a76e
# Parent  f835012a0c062e70495aa341d41e3970a121bf6a
xenpaging: document p2m_mem_paging functions

Add some documentation for each of the p2m_mem_paging functions to describe
what they ought to do.

Signed-off-by: Olaf Hering <olaf@xxxxxxxxx>

diff -r f835012a0c06 -r cc6184fcd784 xen/arch/x86/mm/p2m.c
--- a/xen/arch/x86/mm/p2m.c
+++ b/xen/arch/x86/mm/p2m.c
@@ -668,6 +668,24 @@ set_shared_p2m_entry(struct domain *d, u
 }
 
 #ifdef __x86_64__
+/**
+ * p2m_mem_paging_nominate - Mark a guest page as to-be-paged-out
+ * @d: guest domain
+ * @gfn: guest page to nominate
+ *
+ * Returns 0 for success or negative errno values if gfn is not pageable.
+ *
+ * p2m_mem_paging_nominate() is called by the pager and checks if a guest page
+ * can be paged out. If the following conditions are met the p2mt will be
+ * changed:
+ * - the gfn is backed by a mfn
+ * - the p2mt of the gfn is pageable
+ * - the mfn is not used for IO
+ * - the mfn has exactly one user and has no special meaning
+ *
+ * Once the p2mt is changed the page is readonly for the guest.  On success the
+ * pager can write the page contents to disk and later evict the page.
+ */
 int p2m_mem_paging_nominate(struct domain *d, unsigned long gfn)
 {
     struct page_info *page;
@@ -714,6 +732,25 @@ int p2m_mem_paging_nominate(struct domai
     return ret;
 }
 
+/**
+ * p2m_mem_paging_evict - Mark a guest page as paged-out
+ * @d: guest domain
+ * @gfn: guest page to evict
+ *
+ * Returns 0 for success or negative errno values if eviction is not possible.
+ *
+ * p2m_mem_paging_evict() is called by the pager and will free a guest page and
+ * release it back to Xen. If the following conditions are met the page can be
+ * freed:
+ * - the gfn is backed by a mfn
+ * - the gfn was nominated
+ * - the mfn has still exactly one user and has no special meaning
+ *
+ * After successful nomination some other process could have mapped the page. 
In
+ * this case eviction can not be done. If the gfn was populated before the 
pager
+ * could evict it, eviction can not be done either. In this case the gfn is
+ * still backed by a mfn.
+ */
 int p2m_mem_paging_evict(struct domain *d, unsigned long gfn)
 {
     struct page_info *page;
@@ -773,6 +810,15 @@ int p2m_mem_paging_evict(struct domain *
     return ret;
 }
 
+/**
+ * p2m_mem_paging_drop_page - Tell pager to drop its reference to a paged page
+ * @d: guest domain
+ * @gfn: guest page to drop
+ *
+ * p2m_mem_paging_drop_page() will notify the pager that a paged-out gfn was
+ * released by the guest. The pager is supposed to drop its reference of the
+ * gfn.
+ */
 void p2m_mem_paging_drop_page(struct domain *d, unsigned long gfn)
 {
     struct vcpu *v = current;
@@ -791,6 +837,27 @@ void p2m_mem_paging_drop_page(struct dom
     }
 }
 
+/**
+ * p2m_mem_paging_populate - Tell pager to populete a paged page
+ * @d: guest domain
+ * @gfn: guest page in paging state
+ *
+ * p2m_mem_paging_populate() will notify the pager that a page in any of the
+ * paging states needs to be written back into the guest.
+ * This function needs to be called whenever gfn_to_mfn() returns any of the 
p2m
+ * paging types because the gfn may not be backed by a mfn.
+ *
+ * The gfn can be in any of the paging states, but the pager needs only be
+ * notified when the gfn is in the paging-out path (paging_out or paged).  This
+ * function may be called more than once from several vcpus. If the vcpu 
belongs
+ * to the guest, the vcpu must be stopped and the pager notified that the vcpu
+ * was stopped. The pager needs to handle several requests for the same gfn.
+ *
+ * If the gfn is not in the paging-out path and the vcpu does not belong to the
+ * guest, nothing needs to be done and the function assumes that a request was
+ * already sent to the pager. In this case the caller has to try again until 
the
+ * gfn is fully paged in again.
+ */
 void p2m_mem_paging_populate(struct domain *d, unsigned long gfn)
 {
     struct vcpu *v = current;
@@ -844,6 +911,17 @@ void p2m_mem_paging_populate(struct doma
     mem_event_put_request(d, &d->mem_paging, &req);
 }
 
+/**
+ * p2m_mem_paging_prep - Allocate a new page for the guest
+ * @d: guest domain
+ * @gfn: guest page in paging state
+ *
+ * p2m_mem_paging_prep() will allocate a new page for the guest if the gfn is
+ * not backed by a mfn. It is called by the pager.
+ * It is required that the gfn was already populated. The gfn may already have 
a
+ * mfn if populate was called for  gfn which was nominated but not evicted. In
+ * this case only the p2mt needs to be forwarded.
+ */
 int p2m_mem_paging_prep(struct domain *d, unsigned long gfn)
 {
     struct page_info *page;
@@ -886,6 +964,21 @@ int p2m_mem_paging_prep(struct domain *d
     return ret;
 }
 
+/**
+ * p2m_mem_paging_resume - Resume guest gfn and vcpus
+ * @d: guest domain
+ * @gfn: guest page in paging state
+ *
+ * p2m_mem_paging_resume() will forward the p2mt of a gfn to ram_rw and all
+ * waiting vcpus will be unpaused again. It is called by the pager.
+ * 
+ * The gfn was previously either evicted and populated, or nominated and
+ * populated. If the page was evicted the p2mt will be p2m_ram_paging_in. If
+ * the page was just nominated the p2mt will be p2m_ram_paging_in_start because
+ * the pager did not call p2m_mem_paging_prep().
+ *
+ * If the gfn was dropped the vcpu needs to be unpaused.
+ */
 void p2m_mem_paging_resume(struct domain *d)
 {
     struct p2m_domain *p2m = p2m_get_hostp2m(d);

_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel