From: Andrew Cooper <andrew.cooper3@citrix.com>
To: Xen-devel <xen-devel@lists.xenproject.org>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
Wei Liu <wei.liu2@citrix.com>,
Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>,
George Dunlap <George.Dunlap@eu.citrix.com>,
Andrew Cooper <andrew.cooper3@citrix.com>,
Tim Deegan <tim@xen.org>, Julien Grall <julien.grall@arm.com>,
Jan Beulich <JBeulich@suse.com>,
Ian Jackson <ian.jackson@citrix.com>
Subject: [Xen-devel] [PATCH 2/2] docs: Introduce some hypercall page documentation
Date: Thu, 23 May 2019 11:20:16 +0100 [thread overview]
Message-ID: <1558606816-17842-3-git-send-email-andrew.cooper3@citrix.com> (raw)
Message-ID: <20190523102016.c2UWWl4rplGYHJ9n_25xwyyBRhjFe7J3T7I9hVnmkbU@z> (raw)
In-Reply-To: <1558606816-17842-1-git-send-email-andrew.cooper3@citrix.com>
This also introduced the top-level Guest Documentation section.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: George Dunlap <George.Dunlap@eu.citrix.com>
CC: Ian Jackson <ian.jackson@citrix.com>
CC: Jan Beulich <JBeulich@suse.com>
CC: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Tim Deegan <tim@xen.org>
CC: Wei Liu <wei.liu2@citrix.com>
CC: Julien Grall <julien.grall@arm.com>
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@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel
next prev parent reply other threads:[~2019-05-23 10:20 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-05-23 10:20 [PATCH 0/2] Hypercall page docs and code cleanup Andrew Cooper
2019-05-23 10:20 ` [Xen-devel] " Andrew Cooper
2019-05-23 10:20 ` [PATCH 1/2] x86: init_hypercall_page() cleanup Andrew Cooper
2019-05-23 10:20 ` [Xen-devel] " Andrew Cooper
2019-05-23 10:23 ` Wei Liu
2019-05-23 10:23 ` [Xen-devel] " Wei Liu
2019-05-23 10:49 ` Jan Beulich
2019-05-23 10:49 ` [Xen-devel] " Jan Beulich
2019-05-28 5:31 ` Tian, Kevin
2019-05-28 5:31 ` [Xen-devel] " Tian, Kevin
2019-06-19 16:17 ` Woods, Brian
2019-05-23 10:20 ` Andrew Cooper [this message]
2019-05-23 10:20 ` [Xen-devel] [PATCH 2/2] docs: Introduce some hypercall page documentation Andrew Cooper
2019-05-23 10:23 ` Wei Liu
2019-05-23 10:23 ` [Xen-devel] " Wei Liu
2019-05-23 10:56 ` Jan Beulich
2019-05-23 10:56 ` [Xen-devel] " Jan Beulich
2019-05-23 11:01 ` Andrew Cooper
2019-05-23 11:01 ` [Xen-devel] " Andrew Cooper
2019-05-23 11:41 ` Jan Beulich
2019-05-23 11:41 ` [Xen-devel] " Jan Beulich
2019-05-23 12:02 ` Andrew Cooper
2019-05-23 12:02 ` [Xen-devel] " Andrew Cooper
2019-05-23 12:14 ` Jan Beulich
2019-05-23 12:14 ` [Xen-devel] " Jan Beulich
2019-05-29 4:10 ` [PATCH v2 " Andrew Cooper
2019-05-29 4:10 ` [Xen-devel] " Andrew Cooper
[not found] ` <EF573A6C020000F58E2C01CD@prv1-mh.provo.novell.com>
2019-05-29 8:45 ` Jan Beulich
2019-05-29 8:45 ` [Xen-devel] " Jan Beulich
2019-05-29 11:50 ` Andrew Cooper
2019-05-29 11:50 ` [Xen-devel] " Andrew Cooper
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1558606816-17842-3-git-send-email-andrew.cooper3@citrix.com \
--to=andrew.cooper3@citrix.com \
--cc=George.Dunlap@eu.citrix.com \
--cc=JBeulich@suse.com \
--cc=ian.jackson@citrix.com \
--cc=julien.grall@arm.com \
--cc=konrad.wilk@oracle.com \
--cc=sstabellini@kernel.org \
--cc=tim@xen.org \
--cc=wei.liu2@citrix.com \
--cc=xen-devel@lists.xenproject.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).