libxc/xc_domain_resume: Update comment.

To hopefully clarify what it meant. Also point out that mechanism
by which the return 1 value is done is via an intimate knowledge of the
hypercall ABI (i.e. which register - eax - is the return value).

Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>

diff --git a/tools/libxc/xc_resume.c b/tools/libxc/xc_resume.c
index 87d43242ef360a40272d4ead88b1fee07028a86d..e692b810f78beb8b5d599db9d2185c0f87085252 100644 (file)
--- a/tools/libxc/xc_resume.c
+++ b/tools/libxc/xc_resume.c
@@ -248,11 +248,20 @@ out:
 /*
  * Resume execution of a domain after suspend shutdown.
  * This can happen in one of two ways:
- *  1. Resume with special return code.
- *  2. Reset guest environment so it believes it is resumed in a new
- *     domain context.
+ *  1. (fast=1) Resume the guest without resetting the domain environment.
+ *     The guests's call to SCHEDOP_shutdown(SHUTDOWN_suspend) will return 1.
+ *
+ *  2. (fast=0) Reset guest environment so it believes it is resumed in a new
+ *     domain context. The guests's call to SCHEDOP_shutdown(SHUTDOWN_suspend)
+ *     will return 0.
+ *
+ * (1) should only by used for guests which can handle the special return
+ * code. Also note that the insertion of the return code is quite interesting
+ * and that the guest MUST be paused - otherwise we would be corrupting
+ * the guest vCPU state.
+ *
  * (2) should be used only for guests which cannot handle the special
- * new return code. (1) is always safe (but slower).
+ * new return code - and it is always safe (but slower).
  */
 int xc_domain_resume(xc_interface *xch, uint32_t domid, int fast)
 {