docs: document/mark-up SCHEDOP_*

The biggest subtlety here is there additional argument when op ==
SCHEDOP_shutdown and reason == SHUTDOWN_suspend and its interpretation by
xc_domain_{save,restore}. Add some clarifying comments to libxc as well.

This patch moves some structs around but there is no functional change
other than improved documentation.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>

1 files changed, 8 insertions, 2 deletions

diff --git a/tools/libxc/xc_domain_restore.c b/tools/libxc/xc_domain_restore.c
index a85a0413d6..02bfa1c163 100644
--- a/tools/libxc/xc_domain_restore.c
+++ b/tools/libxc/xc_domain_restore.c
@@ -1967,8 +1967,14 @@ int xc_domain_restore(xc_interface *xch, int io_fd, uint32_t dom,
         if ( i == 0 )
         {
             /*
-             * Uncanonicalise the suspend-record frame number and poke
-             * resume record.
+             * Uncanonicalise the start info frame number and poke in
+             * updated values into the start info itself.
+             *
+             * The start info MFN is the 3rd argument to the
+             * HYPERVISOR_sched_op hypercall when op==SCHEDOP_shutdown
+             * and reason==SHUTDOWN_suspend, it is canonicalised in
+             * xc_domain_save and therefore the PFN is found in the
+             * edx register.
              */
             pfn = GET_FIELD(ctxt, user_regs.edx);
             if ( (pfn >= dinfo->p2m_size) ||