[xen stable-4.17] x86: Clarify that only 5 hypercall parameters are supported

[patchbot@xxxxxxx]

commit 6384cdf0c3405a989aa722d0d80847114d35cf8d
Author:     Michal Orzel <michal.orzel@xxxxxxx>
AuthorDate: Tue Nov 14 13:52:01 2023 +0100
Commit:     Jan Beulich <jbeulich@xxxxxxxx>
CommitDate: Tue Nov 14 13:52:01 2023 +0100

    x86: Clarify that only 5 hypercall parameters are supported
    
    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>
    Reviewed-by: Jason Andryuk <jandryuk@xxxxxxxxx>
    master commit: c035151902689aa5a3765aeb16fa52755917b9ca
    master date: 2023-10-10 10:03:49 +0100
---
 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 42a820386b..83890e1cb6 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 not interact nicely with guest-side debugging.
+   ``V4V``, 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 139438e835..9e3bf06b12 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 5d9035ed22..43f6e3d220 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
--
generated by git-patchbot for /home/xen/git/xen.git#stable-4.17