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: [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) 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
WARNING: multiple messages have this Message-ID (diff)
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: linkBe 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).