[Xen-changelog] [xen-unstable] add a comment for hypercall_xlat_continuation

[Xen patchbot-unstable <patchbot@xxxxxxx>]

# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# Date 1320917059 -3600
# Node ID 073d59fbbbbdcb94e10f4ec7b41fa59e7593b37f
# Parent  f7988da4b6ea6cfed02e9d730f18e640d95c3015
add a comment for hypercall_xlat_continuation

The interface of this function is really rather complex and having reverse
engineered it for the N'th time I think it is time to write things down.

Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
Committed-by: Jan Beulich <jbeulich@xxxxxxxx>
---


diff -r f7988da4b6ea -r 073d59fbbbbd xen/include/xen/compat.h
--- a/xen/include/xen/compat.h  Wed Nov 09 10:37:45 2011 +0100
+++ b/xen/include/xen/compat.h  Thu Nov 10 10:24:19 2011 +0100
@@ -185,6 +185,34 @@
     CHECK_FIELD_COMMON_(k, CHECK_NAME_(k, n ## __ ## f1 ## __ ## f2 ## __ ## \
                                        f3, F2), n, f1.f2.f3)
 
+/*
+ * Translate a native continuation into a compat guest continuation.
+ *
+ * id: If non-NULL then points to an integer N between 0-5. Will be updated
+ * with the value of the N'th argument to the hypercall. The N'th argument must
+ * not be subject to translation (i.e. cannot be referenced by @mask below).
+ * This option is useful for extracting the "op" argument or similar from the
+ * hypercall to enable further xlat processing.
+ *
+ * mask: Specifies which of the hypercall arguments require compat translation.
+ * bit 0 indicates that the 0'th argument requires translation, bit 1 indicates
+ * that the first argument requires translation and so on. Native and compat
+ * values for each translated argument are provided as @varargs (see below).
+ *
+ * varargs: For each bit which is set in @mask the varargs contain a native
+ * value (unsigned long) and a compat value (unsigned int). If the native value
+ * and compat value differ and the N'th argument is equal to the native value
+ * then that argument is replaced by the compat value. If the native and compat
+ * values are equal then no translation takes place. If the N'th argument does
+ * not equal the native value then no translation takes place.
+ *
+ * Any untranslated argument (whether due to not being requested in @mask,
+ * native and compat values being equal or N'th argument not equalling native
+ * value) must be equal in both native and compat representations (i.e. the
+ * native version cannot have any bits > 32 set)
+ *
+ * Return: Number of arguments which were actually translated.
+ */
 int hypercall_xlat_continuation(unsigned int *id, unsigned int mask, ...);
 
 /* In-place translation functons: */

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