Re: [PATCH for-4.18 v2 2/2] x86: Clarify that only 5 hypercall parameters are supported

[Henry Wang <Henry.Wang@xxxxxxx>]

Hi,

> On Oct 7, 2023, at 02:54, Andrew Cooper <andrew.cooper3@xxxxxxxxxx> wrote:
> 
> From: Michal Orzel <michal.orzel@xxxxxxx>
> 
> The x86 hypercall ABI really used to have 6-argument hypercalls.  V4V, the
> downstream predecessor to Argo did take 6th args.
> 
> However, the 6th arg being %ebp in the 32bit ABI makes it unusable in
> practice, because that's the frame pointer in builds with frame pointers
> enabled.  Therefore Argo was altered to being a 5-arg hypercall when it was
> upstreamed.
> 
> c/s 2f531c122e95 ("x86: limit number of hypercall parameters to 5") removed
> the ability for hypercalls to take 6 arguments.
> 
> Update the documentation to match reality.
> 
> Signed-off-by: Michal Orzel <michal.orzel@xxxxxxx>
> Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>

Release-acked-by: Henry Wang <Henry.Wang@xxxxxxx>

Kind regards,
Henry

> ---
> CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx>
> CC: Jan Beulich <JBeulich@xxxxxxxx>
> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
> CC: Wei Liu <wl@xxxxxxx>
> CC: Julien Grall <julien@xxxxxxx>
> CC: Michal Orzel <michal.orzel@xxxxxxx>
> CC: Henry Wang <Henry.Wang@xxxxxxx>
> 
> v2:
> * Extend with the historical context of how 6-arg hypercalls have come and 
> gone.
> ---
> docs/guest-guide/x86/hypercall-abi.rst   | 15 +++++++++++----
> xen/include/public/arch-x86/xen-x86_32.h |  2 +-
> xen/include/public/arch-x86/xen-x86_64.h |  2 +-
> 3 files changed, 13 insertions(+), 6 deletions(-)
> 
> diff --git a/docs/guest-guide/x86/hypercall-abi.rst 
> b/docs/guest-guide/x86/hypercall-abi.rst
> index 42a820386b68..c7a11a76712f 100644
> --- a/docs/guest-guide/x86/hypercall-abi.rst
> +++ b/docs/guest-guide/x86/hypercall-abi.rst
> @@ -4,7 +4,7 @@ Hypercall ABI
> =============
> 
> Hypercalls are system calls to Xen.  Two modes of guest operation are
> -supported, and up to 6 individual parameters are supported.
> +supported, and up to 5 individual parameters are supported.
> 
> Hypercalls may only be issued by kernel-level software [#kern]_.
> 
> @@ -18,17 +18,17 @@ The registers used for hypercalls depends on the 
> operating mode of the guest.
> 
>    * - ABI
>      - Hypercall Index
> -     - Parameters (1 - 6)
> +     - Parameters (1 - 5) [#params]_
>      - Result
> 
>    * - 64bit
>      - RAX
> -     - RDI RSI RDX R10 R8 R9
> +     - RDI RSI RDX R10 R8
>      - RAX
> 
>    * - 32bit
>      - EAX
> -     - EBX ECX EDX ESI EDI EBP
> +     - EBX ECX EDX ESI EDI
>      - EAX
> 
> 32 and 64bit PV guests have an ABI fixed by their guest type.  The ABI for an
> @@ -119,6 +119,13 @@ means.
> .. [#kern] For HVM guests, ``HVMOP_guest_request_vm_event`` may be configured
>    to be usable from userspace, but this behaviour is not default.
> 
> +.. [#params] Xen's ABI used to declare support for 6 hypercall arguments,
> +   using ``r9`` and ``ebp``.  However, such an ABI clobbers the frame pointer
> +   in the 32bit code and does interact nicely with guest-side debugging.  The
> +   predecessor to ``HYPERCALL_argo_op`` was a 6-argument hypercall, but the
> +   ABI was intentionally altered when Argo was upstreamed (Xen 4.13) to be 
> the
> +   5-argument hypercall it now is.
> +
> .. [#mode] While it is possible to use compatibility mode segments in a 64bit
>    kernel, hypercalls issues from such a mode will be interpreted with the
>    32bit ABI.  Such a setup is not expected in production scenarios.
> diff --git a/xen/include/public/arch-x86/xen-x86_32.h 
> b/xen/include/public/arch-x86/xen-x86_32.h
> index 139438e83534..9e3bf06b121e 100644
> --- a/xen/include/public/arch-x86/xen-x86_32.h
> +++ b/xen/include/public/arch-x86/xen-x86_32.h
> @@ -12,7 +12,7 @@
> 
> /*
>  * Hypercall interface:
> - *  Input:  %ebx, %ecx, %edx, %esi, %edi, %ebp (arguments 1-6)
> + *  Input:  %ebx, %ecx, %edx, %esi, %edi (arguments 1-5)
>  *  Output: %eax
>  * Access is via hypercall page (set up by guest loader or via a Xen MSR):
>  *  call hypercall_page + hypercall-number * 32
> diff --git a/xen/include/public/arch-x86/xen-x86_64.h 
> b/xen/include/public/arch-x86/xen-x86_64.h
> index 5d9035ed2230..43f6e3d22001 100644
> --- a/xen/include/public/arch-x86/xen-x86_64.h
> +++ b/xen/include/public/arch-x86/xen-x86_64.h
> @@ -12,7 +12,7 @@
> 
> /*
>  * Hypercall interface:
> - *  Input:  %rdi, %rsi, %rdx, %r10, %r8, %r9 (arguments 1-6)
> + *  Input:  %rdi, %rsi, %rdx, %r10, %r8 (arguments 1-5)
>  *  Output: %rax
>  * Access is via hypercall page (set up by guest loader or via a Xen MSR):
>  *  call hypercall_page + hypercall-number * 32
> -- 
> 2.30.2
>