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 2f531c122e ("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@amd.com>
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Reviewed-by: Jason Andryuk <jandryuk@gmail.com>
master commit: c035151902
master date: 2023-10-10 10:03:49 +0100

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.

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

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