thr3ads.net - Xen devel - [Xen-devel] [PATCH] xen: add a comment for hypercall_xlat

If this information is useful, please help other people find it:
Share via:

Ian Campbell

2011-Nov-10 07:57 UTC

[Xen-devel] [PATCH] xen: add a comment for hypercall_xlat_continuation

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320911800 0
# Node ID 3c6eaf62996dd26d7d0a055955d30bc6c7067f91
# Parent  e6af32ecb4483457d5ad9a7b674c18aaf20cc085
xen: 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@citrix.com>

diff -r e6af32ecb448 -r 3c6eaf62996d xen/include/xen/compat.h
--- a/xen/include/xen/compat.h	Tue Oct 18 14:15:09 2011 +0100
+++ b/xen/include/xen/compat.h	Thu Nov 10 07:56:40 2011 +0000
@@ -185,6 +185,34 @@ static inline int name(k xen_ ## n *x, k
     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-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Jan Beulich

2011-Nov-10 09:11 UTC

head link

[Xen-devel] Re: [PATCH] xen: add a comment for hypercall_xlat_continuation

>>> On 10.11.11 at 08:57, Ian Campbell <ian.campbell@citrix.com>
wrote:
> # HG changeset patch
> # User Ian Campbell <ian.campbell@citrix.com>
> # Date 1320911800 0
> # Node ID 3c6eaf62996dd26d7d0a055955d30bc6c7067f91
> # Parent  e6af32ecb4483457d5ad9a7b674c18aaf20cc085
> xen: 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@citrix.com>
Thanks for doing this!
Acked-by: Jan Beulich <jbeulich@suse.com>
> diff -r e6af32ecb448 -r 3c6eaf62996d xen/include/xen/compat.h
> --- a/xen/include/xen/compat.h	Tue Oct 18 14:15:09 2011 +0100
> +++ b/xen/include/xen/compat.h	Thu Nov 10 07:56:40 2011 +0000
> @@ -185,6 +185,34 @@ static inline int name(k xen_ ## n *x, k
>      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-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 09:12 UTC

head link

[Xen-devel] Re: [PATCH] xen: add a comment for hypercall_xlat_continuation

On Thu, 2011-11-10 at 09:11 +0000, Jan Beulich wrote:> >>> On 10.11.11 at 08:57, Ian Campbell
<ian.campbell@citrix.com> wrote:
> > # HG changeset patch
> > # User Ian Campbell <ian.campbell@citrix.com>
> > # Date 1320911800 0
> > # Node ID 3c6eaf62996dd26d7d0a055955d30bc6c7067f91
> > # Parent  e6af32ecb4483457d5ad9a7b674c18aaf20cc085
> > xen: 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@citrix.com>
> 
> Thanks for doing this!
No problem.
> Acked-by: Jan Beulich <jbeulich@suse.com>
Will you commit too?
> 
> > diff -r e6af32ecb448 -r 3c6eaf62996d xen/include/xen/compat.h
> > --- a/xen/include/xen/compat.h	Tue Oct 18 14:15:09 2011 +0100
> > +++ b/xen/include/xen/compat.h	Thu Nov 10 07:56:40 2011 +0000
> > @@ -185,6 +185,34 @@ static inline int name(k xen_ ## n *x, k
> >      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-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Xen devel - Nov 2011 - [PATCH] xen: add a comment for hypercall_xlat_continuation

[Xen-devel] [PATCH] xen: add a comment for hypercall_xlat_continuation

[Xen-devel] Re: [PATCH] xen: add a comment for hypercall_xlat_continuation

[Xen-devel] Re: [PATCH] xen: add a comment for hypercall_xlat_continuation