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

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 02/03/2026 11:19 am, Jan Beulich wrote:
> 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@citrix.com>
> Acked-by: Jan Beulich <jbeulich@suse.com>

Thanks.

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

Yes.  From a sentence refactor.  Will drop.

>
>> +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.

UDn and BOUND are strictly faults, not traps.  They're type 3 (hardware
exception) and provide no instruction length.

The simplest implementation of UDn is nothing.  The decoder already
needs a signal for "not an instruction I know" which is wired into #UD. 
All the manual does by defining these "instructions" is promise that
nothing else will be allocated in that opcode space.

BOUND is weird.  I'm not sure what more can be said about it.

Either way, #UD and #BR are not interestingly different from e.g. #PF
from a PV guest's point of view.

>
>> +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?

We could, but does that gain us anything?

For 0x80, we get another vector to use for regular interrupts, but that
doesn't work for the vectors below 0x10.

~Andrew