On 28.02.2026 00:16, Andrew Cooper wrote: > ... seeing as I've had to thoroughly reverse engineer it for FRED and make > tweaks in places. > > Signed-off-by: Andrew Cooper <[email protected]>
Acked-by: Jan Beulich <[email protected]> > --- /dev/null > +++ b/docs/guest-guide/x86/pv-traps.rst > @@ -0,0 +1,123 @@ > +.. SPDX-License-Identifier: CC-BY-4.0 > + > +PV Traps and Entrypoints > +======================== > + > +.. note:: > + > + The details here are specific to 64bit builds of Xen. Details for 32bit > + builds of Xen, are different and not discussed further. Nit: Stray comma? > +PV guests are subject to Xen's linkage setup for events (interrupts, > +exceptions and system calls). x86's IDT architecture and limitations are the > +majority influence on the PV ABI. > + > +All external interrupts are routed to PV guests via the :term:`Event Channel` > +interface, and not discussed further here. > + > +What remain are exceptions, and the instructions which cause a control > +transfers. In the x86 architecture, the instructions relevant for PV guests > +are: > + > + * ``INT3``, which generates ``#BP``. > + > + * ``INTO``, which generates ``#OF`` only if the overflow flag is set. It is > + only usable in compatibility mode, and will ``#UD`` in 64bit mode. > + > + * ``CALL (far)`` referencing a gate in the GDT. > + > + * ``INT $N``, which invokes an arbitrary IDT gate. These four instructions > + so far all check the gate DPL and will ``#GP`` otherwise. > + > + * ``INT1``, also known as ``ICEBP``, which generates ``#DB``. This > + instruction does *not* check DPL, and can be used unconditionally by > + userspace. > + > + * ``SYSCALL``, which enters CPL0 as configured by the ``{C,L,}STAR`` MSRs. > + It is usable if enabled by ``MSR_EFER.SCE``, and will ``#UD`` otherwise. > + On Intel parts, ``SYSCALL`` is unusable outside of 64bit mode. > + > + * ``SYSENTER``, which enters CPL0 as configured by the ``SEP`` MSRs. It is > + usable if enabled by ``MSR_SYSENTER_CS`` having a non-NUL selector, and > + will ``#GP`` otherwise. On AMD parts, ``SYSENTER`` is unusable in Long > + mode. The UD<n> family of insns is kind of a hybrid: They explicitly generate #UD, and hence do a control transfer. Same for at least BOUND. It's not quite clear whether they should be enumerated here as well. > +Xen's configuration > +------------------- > + > +Xen maintains a complete IDT, with most gates configured with DPL0. This > +causes most ``INT $N`` instructions to ``#GP``. This allows Xen to emulate > +the instruction, referring to the guest kernels vDPL choice. > + > + * Vectors 3 ``#BP`` and 4 ``#OF`` are DPL3, in order to allow the ``INT3`` > + and ``INTO`` instructions to function in userspace. > + > + * Vector 0x80 is DPL3 in order to implement the legacy system call fastpath > + commonly found in UNIXes. Much like we make this DPL0 when PV=n, should we perhaps make vectors 3 and 4 DPL0 as well in that case (just for formality's sake)? Maybe 4, like 9, would even want to be an autogen entry point then? Jan
