docs/hypercall-abi: Add a footnote about SYSCALL

[PATCH] docs/hypercall-abi: Add a footnote about SYSCALL

Posted by Andrew Cooper 1 day, 13 hours ago

Given that we explicitly support guests making hypercalls without the
use of the hypercall page (for CFI and speculative safety reasons), note
explicitly that %rcx/%r11 need preserving/clobbering around SYSCALL.

Reported-by: Jan Beulich <jbeulich@suse.com>
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Jan Beulich <jbeulich@suse.com>
CC: Roger Pau Monné <roger.pau@citrix.com>

I've avoided mentioning FRED seeing as Xen (now) maintains legacy
behaviour.
---
 docs/guest-guide/x86/hypercall-abi.rst | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/docs/guest-guide/x86/hypercall-abi.rst b/docs/guest-guide/x86/hypercall-abi.rst
index e52ed453bcab..ffcf9b1b6d84 100644
--- a/docs/guest-guide/x86/hypercall-abi.rst
+++ b/docs/guest-guide/x86/hypercall-abi.rst
@@ -62,7 +62,7 @@ between virtualisation mode and hardware vendor.
      - INT 0x82
 
    * - 64bit PV
-     - SYSCALL
+     - SYSCALL [#syscall]_
 
    * - Intel HVM
      - VMCALL
@@ -138,6 +138,10 @@ means.
    kernel, hypercalls issues from such a mode will be interpreted with the
    32bit ABI.  Such a setup is not expected in production scenarios.
 
+.. [#syscall] The ``SYSCALL`` instruction modifies ``%rcx`` and ``%r11``.
+   These registers want spilling or marking as clobbered if invoking the
+   hypercall without the use of the hypercall page.
+
 .. [#iret] ``HYPERCALL_iret`` is special.  It is only implemented for PV
    guests and takes all its parameters on the stack.  This stub should be
    ``jmp``'d to, rather than ``call``'d.  HVM guests have this stub
-- 
2.34.1

Re: [PATCH] docs/hypercall-abi: Add a footnote about SYSCALL

Posted by Jan Beulich 1 day, 13 hours ago

On 31.03.2026 10:40, Andrew Cooper wrote:
> @@ -138,6 +138,10 @@ means.
>     kernel, hypercalls issues from such a mode will be interpreted with the
>     32bit ABI.  Such a setup is not expected in production scenarios.
>  
> +.. [#syscall] The ``SYSCALL`` instruction modifies ``%rcx`` and ``%r11``.
> +   These registers want spilling or marking as clobbered if invoking the
> +   hypercall without the use of the hypercall page.

For most hypercalls this is sufficient, but ...

>  .. [#iret] ``HYPERCALL_iret`` is special.  It is only implemented for PV
>     guests and takes all its parameters on the stack.  This stub should be
>     ``jmp``'d to, rather than ``call``'d.  HVM guests have this stub

... for this one merely marking as clobbered isn't an option, aiui. It needs
the two registers put on the stack, and in a specific order. At least as long
as VGCF_in_syscall is clear in the stack frame.

Jan