[PATCH] compat: add a little bit of description to xlat.lst

[PATCH] compat: add a little bit of description to xlat.lst

[Jan Beulich]

Requested-by: Roger Pau Monné <roger.pau@citrix.com>
Signed-off-by: Jan Beulich <jbeulich@suse.com>

--- a/xen/include/xlat.lst
+++ b/xen/include/xlat.lst
@@ -1,3 +1,22 @@
+# There are a few fundamentally different strategies for handling compat
+# (sub-)hypercalls:
+#
+# 1) Wrap a translation layer around the native hypercall. Structures involved
+# in this model should use translation (xlat) macros generated by adding
+# !-prefixed lines here.
+#
+# 2) Compile the entire hypercall function a second time, arranging for the
+# compat structures to get used in place of the native ones. There are no xlat
+# macros involved here, all that's needed are correctly translated structures.
+#
+# 3) Adhoc translation, which may or may not involve adding entries here.
+#
+# 4) Any mixture of the above.
+#
+# In all models any structures re-used in their native form should have
+# ?-mark prefixed lines added here, with the resulting checking macros invoked
+# somewhere in the code handling the hypercall or its translation.
+#
 # First column indicator:
 # ! - needs translation
 # ? - needs checking

Re: [PATCH] compat: add a little bit of description to xlat.lst

[Roger Pau Monné]

On Thu, Jul 16, 2020 at 02:21:33PM +0200, Jan Beulich wrote:
> Requested-by: Roger Pau Monné <roger.pau@citrix.com>
> Signed-off-by: Jan Beulich <jbeulich@suse.com>

Reviewed-by: Roger Pau Monné <roger.pau@citrix.com>

Thanks for writing this up!

Re: [PATCH] compat: add a little bit of description to xlat.lst

[Wei Liu]

On Thu, Jul 16, 2020 at 02:21:33PM +0200, Jan Beulich wrote:
> Requested-by: Roger Pau Monné <roger.pau@citrix.com>
> Signed-off-by: Jan Beulich <jbeulich@suse.com>

Acked-by: Wei Liu <wl@xen.org>

This is much appreciated.

> 
> --- a/xen/include/xlat.lst
> +++ b/xen/include/xlat.lst
> @@ -1,3 +1,22 @@
> +# There are a few fundamentally different strategies for handling compat
> +# (sub-)hypercalls:
> +#
> +# 1) Wrap a translation layer around the native hypercall. Structures involved
> +# in this model should use translation (xlat) macros generated by adding
> +# !-prefixed lines here.
> +#
> +# 2) Compile the entire hypercall function a second time, arranging for the
> +# compat structures to get used in place of the native ones. There are no xlat
> +# macros involved here, all that's needed are correctly translated structures.
> +#
> +# 3) Adhoc translation, which may or may not involve adding entries here.
> +#
> +# 4) Any mixture of the above.
> +#
> +# In all models any structures re-used in their native form should have
> +# ?-mark prefixed lines added here, with the resulting checking macros invoked
> +# somewhere in the code handling the hypercall or its translation.
> +#
>  # First column indicator:
>  # ! - needs translation
>  # ? - needs checking