From: Michal Orzel <[email protected]>
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 <[email protected]>
Signed-off-by: Andrew Cooper <[email protected]>
---
CC: George Dunlap <[email protected]>
CC: Jan Beulich <[email protected]>
CC: Stefano Stabellini <[email protected]>
CC: Wei Liu <[email protected]>
CC: Julien Grall <[email protected]>
CC: Michal Orzel <[email protected]>
CC: Henry Wang <[email protected]>
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
