Re: [PATCH v4 02/14] docs/guest-guide: Describe the PV traps and entrypoints ABI

[Jan Beulich <jbeulich@xxxxxxxx>]

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 <andrew.cooper3@xxxxxxxxxx>

Acked-by: Jan Beulich <jbeulich@xxxxxxxx>

> --- /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