| Message ID | 20231006185402.1098400-3-andrew.cooper3@citrix.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs:Clarify that only 5 hypercall parameters are supported | expand |
Hi, > On Oct 7, 2023, at 02:54, Andrew Cooper <andrew.cooper3@citrix.com> wrote: > > From: Michal Orzel <michal.orzel@amd.com> > > The x86 hypercall ABI really used to have 6-argument hypercalls. V4V, the > downstream predecessor to Argo did take 6th args. > > However, the 6th arg being %ebp in the 32bit ABI makes it unusable in > practice, because that's the frame pointer in builds with frame pointers > enabled. Therefore Argo was altered to being a 5-arg hypercall when it was > upstreamed. > > c/s 2f531c122e95 ("x86: limit number of hypercall parameters to 5") removed > the ability for hypercalls to take 6 arguments. > > Update the documentation to match reality. > > Signed-off-by: Michal Orzel <michal.orzel@amd.com> > Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com> Release-acked-by: Henry Wang <Henry.Wang@arm.com> Kind regards, Henry > --- > CC: George Dunlap <George.Dunlap@eu.citrix.com> > CC: Jan Beulich <JBeulich@suse.com> > CC: Stefano Stabellini <sstabellini@kernel.org> > CC: Wei Liu <wl@xen.org> > CC: Julien Grall <julien@xen.org> > CC: Michal Orzel <michal.orzel@amd.com> > CC: Henry Wang <Henry.Wang@arm.com> > > v2: > * Extend with the historical context of how 6-arg hypercalls have come and gone. > --- > docs/guest-guide/x86/hypercall-abi.rst | 15 +++++++++++---- > xen/include/public/arch-x86/xen-x86_32.h | 2 +- > xen/include/public/arch-x86/xen-x86_64.h | 2 +- > 3 files changed, 13 insertions(+), 6 deletions(-) > > diff --git a/docs/guest-guide/x86/hypercall-abi.rst b/docs/guest-guide/x86/hypercall-abi.rst > index 42a820386b68..c7a11a76712f 100644 > --- a/docs/guest-guide/x86/hypercall-abi.rst > +++ b/docs/guest-guide/x86/hypercall-abi.rst > @@ -4,7 +4,7 @@ Hypercall ABI > ============= > > Hypercalls are system calls to Xen. Two modes of guest operation are > -supported, and up to 6 individual parameters are supported. > +supported, and up to 5 individual parameters are supported. > > Hypercalls may only be issued by kernel-level software [#kern]_. > > @@ -18,17 +18,17 @@ The registers used for hypercalls depends on the operating mode of the guest. > > * - ABI > - Hypercall Index > - - Parameters (1 - 6) > + - Parameters (1 - 5) [#params]_ > - Result > > * - 64bit > - RAX > - - RDI RSI RDX R10 R8 R9 > + - RDI RSI RDX R10 R8 > - RAX > > * - 32bit > - EAX > - - EBX ECX EDX ESI EDI EBP > + - EBX ECX EDX ESI EDI > - EAX > > 32 and 64bit PV guests have an ABI fixed by their guest type. The ABI for an > @@ -119,6 +119,13 @@ means. > .. [#kern] For HVM guests, ``HVMOP_guest_request_vm_event`` may be configured > to be usable from userspace, but this behaviour is not default. > > +.. [#params] Xen's ABI used to declare support for 6 hypercall arguments, > + using ``r9`` and ``ebp``. However, such an ABI clobbers the frame pointer > + in the 32bit code and does interact nicely with guest-side debugging. The > + predecessor to ``HYPERCALL_argo_op`` was a 6-argument hypercall, but the > + ABI was intentionally altered when Argo was upstreamed (Xen 4.13) to be the > + 5-argument hypercall it now is. > + > .. [#mode] 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. > diff --git a/xen/include/public/arch-x86/xen-x86_32.h b/xen/include/public/arch-x86/xen-x86_32.h > index 139438e83534..9e3bf06b121e 100644 > --- a/xen/include/public/arch-x86/xen-x86_32.h > +++ b/xen/include/public/arch-x86/xen-x86_32.h > @@ -12,7 +12,7 @@ > > /* > * Hypercall interface: > - * Input: %ebx, %ecx, %edx, %esi, %edi, %ebp (arguments 1-6) > + * Input: %ebx, %ecx, %edx, %esi, %edi (arguments 1-5) > * Output: %eax > * Access is via hypercall page (set up by guest loader or via a Xen MSR): > * call hypercall_page + hypercall-number * 32 > diff --git a/xen/include/public/arch-x86/xen-x86_64.h b/xen/include/public/arch-x86/xen-x86_64.h > index 5d9035ed2230..43f6e3d22001 100644 > --- a/xen/include/public/arch-x86/xen-x86_64.h > +++ b/xen/include/public/arch-x86/xen-x86_64.h > @@ -12,7 +12,7 @@ > > /* > * Hypercall interface: > - * Input: %rdi, %rsi, %rdx, %r10, %r8, %r9 (arguments 1-6) > + * Input: %rdi, %rsi, %rdx, %r10, %r8 (arguments 1-5) > * Output: %rax > * Access is via hypercall page (set up by guest loader or via a Xen MSR): > * call hypercall_page + hypercall-number * 32 > -- > 2.30.2 >
On Fri, Oct 6, 2023 at 4:29 PM Andrew Cooper <andrew.cooper3@citrix.com> wrote: > > From: Michal Orzel <michal.orzel@amd.com> > > The x86 hypercall ABI really used to have 6-argument hypercalls. V4V, the > downstream predecessor to Argo did take 6th args. > > However, the 6th arg being %ebp in the 32bit ABI makes it unusable in > practice, because that's the frame pointer in builds with frame pointers > enabled. Therefore Argo was altered to being a 5-arg hypercall when it was > upstreamed. > > c/s 2f531c122e95 ("x86: limit number of hypercall parameters to 5") removed > the ability for hypercalls to take 6 arguments. > > Update the documentation to match reality. > > Signed-off-by: Michal Orzel <michal.orzel@amd.com> > Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com> > --- > CC: George Dunlap <George.Dunlap@eu.citrix.com> > CC: Jan Beulich <JBeulich@suse.com> > CC: Stefano Stabellini <sstabellini@kernel.org> > CC: Wei Liu <wl@xen.org> > CC: Julien Grall <julien@xen.org> > CC: Michal Orzel <michal.orzel@amd.com> > CC: Henry Wang <Henry.Wang@arm.com> > > v2: > * Extend with the historical context of how 6-arg hypercalls have come and gone. > --- > docs/guest-guide/x86/hypercall-abi.rst | 15 +++++++++++---- > xen/include/public/arch-x86/xen-x86_32.h | 2 +- > xen/include/public/arch-x86/xen-x86_64.h | 2 +- > 3 files changed, 13 insertions(+), 6 deletions(-) > > diff --git a/docs/guest-guide/x86/hypercall-abi.rst b/docs/guest-guide/x86/hypercall-abi.rst > index 42a820386b68..c7a11a76712f 100644 > --- a/docs/guest-guide/x86/hypercall-abi.rst > +++ b/docs/guest-guide/x86/hypercall-abi.rst > @@ -119,6 +119,13 @@ means. > .. [#kern] For HVM guests, ``HVMOP_guest_request_vm_event`` may be configured > to be usable from userspace, but this behaviour is not default. > > +.. [#params] Xen's ABI used to declare support for 6 hypercall arguments, > + using ``r9`` and ``ebp``. However, such an ABI clobbers the frame pointer > + in the 32bit code and does interact nicely with guest-side debugging. The I think you want s/does/does not/. With that, Reviewed-by: Jason Andryuk <jandryuk@gmail.com> > + predecessor to ``HYPERCALL_argo_op`` was a 6-argument hypercall, but the Also, I think it would be worth just naming v4v with "...predecessor to ``HYPERCALL_argo_op``, v4v, was...", so a future reader doesn't have to investigate to find out what the predecessor was. Regards, Jason > + ABI was intentionally altered when Argo was upstreamed (Xen 4.13) to be the > + 5-argument hypercall it now is. > + > .. [#mode] 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.
diff --git a/docs/guest-guide/x86/hypercall-abi.rst b/docs/guest-guide/x86/hypercall-abi.rst index 42a820386b68..c7a11a76712f 100644 --- a/docs/guest-guide/x86/hypercall-abi.rst +++ b/docs/guest-guide/x86/hypercall-abi.rst @@ -4,7 +4,7 @@ Hypercall ABI ============= Hypercalls are system calls to Xen. Two modes of guest operation are -supported, and up to 6 individual parameters are supported. +supported, and up to 5 individual parameters are supported. Hypercalls may only be issued by kernel-level software [#kern]_. @@ -18,17 +18,17 @@ The registers used for hypercalls depends on the operating mode of the guest. * - ABI - Hypercall Index - - Parameters (1 - 6) + - Parameters (1 - 5) [#params]_ - Result * - 64bit - RAX - - RDI RSI RDX R10 R8 R9 + - RDI RSI RDX R10 R8 - RAX * - 32bit - EAX - - EBX ECX EDX ESI EDI EBP + - EBX ECX EDX ESI EDI - EAX 32 and 64bit PV guests have an ABI fixed by their guest type. The ABI for an @@ -119,6 +119,13 @@ means. .. [#kern] For HVM guests, ``HVMOP_guest_request_vm_event`` may be configured to be usable from userspace, but this behaviour is not default. +.. [#params] Xen's ABI used to declare support for 6 hypercall arguments, + using ``r9`` and ``ebp``. However, such an ABI clobbers the frame pointer + in the 32bit code and does interact nicely with guest-side debugging. The + predecessor to ``HYPERCALL_argo_op`` was a 6-argument hypercall, but the + ABI was intentionally altered when Argo was upstreamed (Xen 4.13) to be the + 5-argument hypercall it now is. + .. [#mode] 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. diff --git a/xen/include/public/arch-x86/xen-x86_32.h b/xen/include/public/arch-x86/xen-x86_32.h index 139438e83534..9e3bf06b121e 100644 --- a/xen/include/public/arch-x86/xen-x86_32.h +++ b/xen/include/public/arch-x86/xen-x86_32.h @@ -12,7 +12,7 @@ /* * Hypercall interface: - * Input: %ebx, %ecx, %edx, %esi, %edi, %ebp (arguments 1-6) + * Input: %ebx, %ecx, %edx, %esi, %edi (arguments 1-5) * Output: %eax * Access is via hypercall page (set up by guest loader or via a Xen MSR): * call hypercall_page + hypercall-number * 32 diff --git a/xen/include/public/arch-x86/xen-x86_64.h b/xen/include/public/arch-x86/xen-x86_64.h index 5d9035ed2230..43f6e3d22001 100644 --- a/xen/include/public/arch-x86/xen-x86_64.h +++ b/xen/include/public/arch-x86/xen-x86_64.h @@ -12,7 +12,7 @@ /* * Hypercall interface: - * Input: %rdi, %rsi, %rdx, %r10, %r8, %r9 (arguments 1-6) + * Input: %rdi, %rsi, %rdx, %r10, %r8 (arguments 1-5) * Output: %rax * Access is via hypercall page (set up by guest loader or via a Xen MSR): * call hypercall_page + hypercall-number * 32