It has been discovered that VIRQ_ARGO is a 3rd type of VIRQ.  Also, recent
work has prevented global VIRQs from being stolen from the owning domain.

Rewrite the description of VIRQ classifications.  Drop the (DOM0) comment from
the global VIRQs; it's not been true for a long time.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Anthony PERARD <anthony.perard@vates.tech>
CC: Michal Orzel <michal.orzel@amd.com>
CC: Jan Beulich <jbeulich@suse.com>
CC: Julien Grall <julien@xen.org>
CC: Roger Pau Monné <roger.pau@citrix.com>
CC: Stefano Stabellini <sstabellini@kernel.org>
CC: Juergen Gross <jgross@suse.com>
---
 xen/include/public/event_channel.h |  8 +++----
 xen/include/public/xen.h           | 37 +++++++++++++++++++-----------
 2 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/xen/include/public/event_channel.h b/xen/include/public/event_channel.h
index 0d91a1c4afab..c5548d206c74 100644
--- a/xen/include/public/event_channel.h
+++ b/xen/include/public/event_channel.h
@@ -114,10 +114,10 @@ typedef struct evtchn_bind_interdomain evtchn_bind_interdomain_t;
  * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified
  * vcpu.
  * NOTES:
- *  1. Virtual IRQs are classified as per-vcpu or global. See the VIRQ list
- *     in xen.h for the classification of each VIRQ.
- *  2. Global VIRQs must be allocated on VCPU0 but can subsequently be
- *     re-bound via EVTCHNOP_bind_vcpu.
+ *  1. Virtual IRQs are classified as per-vcpu, per-domain or global. See the
+ *     VIRQ list in xen.h for the classification of each VIRQ.
+ *  2. Per-domain and global VIRQs must be allocated on vCPU0 but can
+ *     subsequently be re-bound via EVTCHNOP_bind_vcpu.
  *  3. Per-vcpu VIRQs may be bound to at most one event channel per vcpu.
  *     The allocated event channel is bound to the specified vcpu and the
  *     binding cannot be changed.
diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index e051f989a5ca..75b1c1d597f9 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -159,25 +159,34 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t);
  *
  * Virtual interrupts that a guest OS may receive from Xen.
  *
- * In the side comments, 'V.' denotes a per-VCPU VIRQ while 'G.' denotes a
- * global VIRQ. The former can be bound once per VCPU and cannot be re-bound.
- * The latter can be allocated only once per guest: they must initially be
- * allocated to VCPU0 but can subsequently be re-bound.
+ * There are three types:
+ *
+ * 1. (V) Per-vcpu:
+ *    These can be bound once per vCPU, each using a different evtchn port.
+ *    An evtchn for one vCPU cannot be rebound to a different vCPU.
+ *
+ * 2. (D) Per-domain:
+ *    These can be bound once per domain.  They must be bound on vCPU 0 first,
+ *    but can be rebound to other vCPUs afterwards.
+ *
+ * 3. (G) Global:
+ *    Like per-domain, but can only be bound to a single domain at a time.
+ *    The owning domain must unbind before a new domain can bind.
  */
 /* ` enum virq { */
 #define VIRQ_TIMER      0  /* V. Timebase update, and/or requested timeout.  */
 #define VIRQ_DEBUG      1  /* V. Request guest to dump debug info.           */
-#define VIRQ_CONSOLE    2  /* G. (DOM0) Bytes received on emergency console. */
-#define VIRQ_DOM_EXC    3  /* G. (DOM0) Exceptional event for some domain.   */
-#define VIRQ_TBUF       4  /* G. (DOM0) Trace buffer has records available.  */
-#define VIRQ_DEBUGGER   6  /* G. (DOM0) A domain has paused for debugging.   */
+#define VIRQ_CONSOLE    2  /* G. Bytes received on emergency console.        */
+#define VIRQ_DOM_EXC    3  /* G. Exceptional event for some domain.          */
+#define VIRQ_TBUF       4  /* G. Trace buffer has records available.         */
+#define VIRQ_DEBUGGER   6  /* G. A domain has paused for debugging.          */
 #define VIRQ_XENOPROF   7  /* V. XenOprofile interrupt: new sample available */
-#define VIRQ_CON_RING   8  /* G. (DOM0) Bytes received on console            */
-#define VIRQ_PCPU_STATE 9  /* G. (DOM0) PCPU state changed                   */
-#define VIRQ_MEM_EVENT  10 /* G. (DOM0) A memory event has occurred          */
-#define VIRQ_ARGO       11 /* G. Argo interdomain message notification       */
-#define VIRQ_ENOMEM     12 /* G. (DOM0) Low on heap memory       */
-#define VIRQ_XENPMU     13 /* V.  PMC interrupt                              */
+#define VIRQ_CON_RING   8  /* G. Bytes received on console                   */
+#define VIRQ_PCPU_STATE 9  /* G. PCPU state changed                          */
+#define VIRQ_MEM_EVENT  10 /* G. A memory event has occurred                 */
+#define VIRQ_ARGO       11 /* D. Argo interdomain message notification       */
+#define VIRQ_ENOMEM     12 /* G. Low on heap memory                          */
+#define VIRQ_XENPMU     13 /* V. PMC interrupt                               */
 
 /* Architecture-specific VIRQ definitions. */
 #define VIRQ_ARCH_0    16
-- 
2.39.5

On 07.03.2025 12:49, Andrew Cooper wrote:
> It has been discovered that VIRQ_ARGO is a 3rd type of VIRQ.  Also, recent
> work has prevented global VIRQs from being stolen from the owning domain.
> 
> Rewrite the description of VIRQ classifications.  Drop the (DOM0) comment from
> the global VIRQs; it's not been true for a long time.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

Reviewed-by: Jan Beulich <jbeulich@suse.com>