1.. SPDX-License-Identifier: CC-BY-4.0
2
3Hypercall ABI
4=============
5
6Hypercalls are system calls to Xen.  Two modes of guest operation are
7supported, and up to 5 individual parameters are supported.
8
9Hypercalls may only be issued by kernel-level software [#kern]_.
10
11Registers
12---------
13
14The registers used for hypercalls depends on the operating mode of the guest.
15
16.. list-table::
17   :header-rows: 1
18
19   * - ABI
20     - Hypercall Index
21     - Parameters (1 - 5) [#params]_
22     - Result
23
24   * - 64bit
25     - RAX
26     - RDI RSI RDX R10 R8
27     - RAX
28
29   * - 32bit
30     - EAX
31     - EBX ECX EDX ESI EDI
32     - EAX
33
3432 and 64bit PV guests have an ABI fixed by their guest type.  The ABI for an
35HVM guest depends on whether the vCPU is operating in a 64bit segment or not
36[#mode]_.
37
38
39Parameters
40----------
41
42Different hypercalls take a different number of parameters.  Each hypercall
43potentially clobbers each of its parameter registers; a guest may not rely on
44the parameter registers staying the same.  A debug build of Xen checks this by
45deliberately poisoning the parameter registers before returning back to the
46guest.
47
48
49Mode transfer
50-------------
51
52The exact sequence of instructions required to issue a hypercall differs
53between virtualisation mode and hardware vendor.
54
55.. list-table::
56   :header-rows: 1
57
58   * - Guest
59     - Transfer instruction
60
61   * - 32bit PV
62     - INT 0x82
63
64   * - 64bit PV
65     - SYSCALL
66
67   * - Intel HVM
68     - VMCALL
69
70   * - AMD HVM
71     - VMMCALL
72
73To abstract away the details, Xen implements an interface known as the
74Hypercall Page.  This allows a guest to make a hypercall without needing to
75perform mode-specific or vendor-specific setup.
76
77
78Hypercall Page
79==============
80
81The hypercall page is a page of guest RAM into which Xen will write suitable
82transfer stubs.  It is intended as a convenience for guests, but use of the
83hypercall page is not mandatory for making hypercalls to Xen.
84
85Creating a hypercall page is an isolated operation from Xen's point of view.
86It is the guests responsibility to ensure that the hypercall page, once
87written by Xen, is mapped with executable permissions so it may be used.
88Multiple hypercall pages may be created by the guest, if it wishes.
89
90The stubs are arranged by hypercall index, and start on 32-byte boundaries.
91To invoke a specific hypercall, ``call`` the relevant stub [#iret]_:
92
93.. code-block:: none
94
95   call hypercall_page + index * 32
96
97There result is an ABI which is invariant of the exact operating mode or
98hardware vendor.  This is intended to simplify guest kernel interfaces by
99abstracting away the details of how it is currently running.
100
101
102Creating Hypercall Pages
103------------------------
104
105Guests which are started using the PV boot protocol may set set
106``XEN_ELFNOTE_HYPERCALL_PAGE`` to have the nominated page written as a
107hypercall page during construction.  This mechanism is common for PV guests,
108and allows hypercalls to be issued with no additional setup.
109
110Any guest can locate the Xen CPUID leaves and read the *hypercall transfer
111page* information, which specifies an MSR that can be used to create
112additional hypercall pages.  When a guest physical address is written to the
113MSR, Xen writes a hypercall page into the nominated guest page.  This
114mechanism is common for HVM guests which are typically started via legacy
115means.
116
117
118.. rubric:: Footnotes
119
120.. [#kern] For HVM guests, ``HVMOP_guest_request_vm_event`` may be configured
121   to be usable from userspace, but this behaviour is not default.
122
123.. [#params] Xen's ABI used to declare support for 6 hypercall arguments,
124   using ``r9`` and ``ebp``.  However, such an ABI clobbers the frame pointer
125   in the 32bit code and does not interact nicely with guest-side debugging.
126   ``V4V``, the predecessor to ``HYPERCALL_argo_op`` was a 6-argument
127   hypercall, but the ABI was intentionally altered when Argo was upstreamed
128   (Xen 4.13) to be the 5-argument hypercall it now is.
129
130.. [#mode] While it is possible to use compatibility mode segments in a 64bit
131   kernel, hypercalls issues from such a mode will be interpreted with the
132   32bit ABI.  Such a setup is not expected in production scenarios.
133
134.. [#iret] ``HYPERCALL_iret`` is special.  It is only implemented for PV
135   guests and takes all its parameters on the stack.  This stub should be
136   ``jmp``'d to, rather than ``call``'d.  HVM guests have this stub
137   implemented as ``ud2a`` to prevent accidental use.
138