[Xen-devel] [PATCH 2/2] docs: Introduce some hypercall page documentation

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

This also introduced the top-level Guest Documentation section.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
---
CC: George Dunlap <George.Dunlap@xxxxxxxxxxxxx>
CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
CC: Jan Beulich <JBeulich@xxxxxxxx>
CC: Konrad Rzeszutek Wilk <konrad.wilk@xxxxxxxxxx>
CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
CC: Tim Deegan <tim@xxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
CC: Julien Grall <julien.grall@xxxxxxx>

The rendered version can be viewed at:

https://andrewcoop-xen.readthedocs.io/en/docs-devel/guest-guide/hypercall-abi.html
---
 docs/guest-guide/hypercall-abi.rst | 127 +++++++++++++++++++++++++++++++++++++
 docs/guest-guide/index.rst         |  10 +++
 docs/index.rst                     |  13 ++++
 3 files changed, 150 insertions(+)
 create mode 100644 docs/guest-guide/hypercall-abi.rst
 create mode 100644 docs/guest-guide/index.rst

diff --git a/docs/guest-guide/hypercall-abi.rst 
b/docs/guest-guide/hypercall-abi.rst
new file mode 100644
index 0000000..9862b14
--- /dev/null
+++ b/docs/guest-guide/hypercall-abi.rst
@@ -0,0 +1,127 @@
+Hypercall ABI
+=============
+
+Hypercalls are system calls to Xen.  Two modes of guest operation are
+supported, and up to 6 individual parameters are supported.
+
+Hypercalls may only be issued by kernel-level software [1]_.
+
+Registers
+---------
+
+The registers used for hypercalls depends on the operating mode of the guest.
+
+.. list-table::
+  :header-rows: 1
+
+  * - ABI
+    - Hypercall Index
+    - Parameters (1 - 6)
+    - Result
+
+  * - 64bit
+    - %rax
+    - %rdi %rsi %rdx %r10 %r8 %r9
+    - %rax
+
+  * - 32bit
+    - %eax
+    - %ebx %ecx %edx %esi %edi %ebp
+    - %eax
+
+32 and 64bit PV guests have an ABI fixed by their guest type.  The ABI for an
+HVM guest depends on whether the vCPU is operating in a 64bit segment or not
+[2]_.
+
+
+Parameters
+----------
+
+Different hypercalls take a different number of parameters.  Each hypercall
+potentially clobbers each of its parameter registers; a guest may not rely on
+the parameter registers staying the same.  A debug build of Xen checks this by
+deliberately poisoning the parameter registers before returning back to the
+guest.
+
+
+Mode transfer
+-------------
+
+The exact sequence of instructions required to issue a hypercall differs
+between virtualisation mode and hardware vendor.
+
+.. list-table::
+  :header-rows: 1
+
+  * - Guest
+    - Transfer instruction
+
+  * - 32bit PV
+    - INT $0x82
+
+  * - 64bit PV
+    - SYSCALL
+
+  * - Intel HVM
+    - VMCALL
+
+  * - AMD HVM
+    - VMMCALL
+
+To abstract away the details, Xen implements an interface known as the
+Hypercall Page.  This allows a guest to make a hypercall without needing to
+perform mode-specific or vendor-specific setup.
+
+
+Hypercall Page
+==============
+
+The hypercall page is a page of guest RAM into which Xen will write suitable
+transfer stubs.
+
+Creating a hypercall page is an isolated operation from Xen's point of view.
+It is the guests responsibility to ensure that the hypercall page, once
+written by Xen, is mapped with executable permissions so it may be used.
+Multiple hypercall pages may be created by the guest, if it wishes.
+
+The stubs are arranged by hypercall index, and start on 32-byte boundaries.
+To invoke a specific hypercall, ``call`` the relevant stub [3]_:
+
+.. code-block:: none
+
+  call hypercall_page + index * 32
+
+There result is an ABI which is invariant of the exact operating mode or
+hardware vendor.  This is intended to simplify guest kernel interfaces by
+abstracting away the details of how it is currently running.
+
+
+Creating Hypercall Pages
+------------------------
+
+Guests which are started using the PV boot protocol may set set
+``XEN_ELFNOTE_HYPERCALL_PAGE`` to have the nominated page written as a
+hypercall page during construction.  This mechanism is common for PV guests,
+and allows hypercalls to be issued with no additional setup.
+
+Any guest can locate the Xen CPUID leaves and read the *hypercall transfer
+page* information, which specifies an MSR that can be used to create
+additional hypercall pages.  When a guest physical address is written to the
+MSR, Xen writes a hypercall page into the nominated guest page.  This
+mechanism is common for HVM guests which are typically started via legacy
+means.
+
+
+.. rubric:: Footnotes
+
+.. [1] For HVM guests, ``HVMOP_guest_request_vm_event`` may be configured to
+       be usable from userspace, but this behaviour is not default.
+
+.. [2] 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.
+
+.. [3] ``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
+       implemented as ``ud2a`` to prevent accidental use.
diff --git a/docs/guest-guide/index.rst b/docs/guest-guide/index.rst
new file mode 100644
index 0000000..c657332
--- /dev/null
+++ b/docs/guest-guide/index.rst
@@ -0,0 +1,10 @@
+Guest documentation
+===================
+
+x86
+---
+
+.. toctree::
+  :maxdepth: 2
+
+  hypercall-abi
diff --git a/docs/index.rst b/docs/index.rst
index 9e2e256..31bb892 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,6 +21,19 @@ configure the system.
   admin-guide/index
 
 
+Guest documentation
+-------------------
+
+This documentation concerns the APIs and ABIs available to guests.  It is
+intended for OS developers trying to use a Xen feature, and for Xen developers
+to avoid breaking things.
+
+.. toctree::
+  :maxdepth: 3
+
+  guest-guide/index
+
+
 Hypervisor developer documentation
 ----------------------------------
 
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/mailman/listinfo/xen-devel