Re: [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs

[Ian Campbell <Ian.Campbell@citrix.com>]

On Mon, 2012-02-27 at 12:07 +0000, Ian Campbell wrote:
> As part of this I looked through the relevant chapter from interfaces.tex (from
> 4.1, deleted in unstable) to ensure no critical information was missing.

Actually, the intro from that chapter is interesting/useful and I missed
it. Here's a new version with it included.

8<-------------------------------------

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1330346207 0
# Node ID b6a3a0d68c91ce8fa6023aee3046efd3866942df
# Parent  71159fb049f253030c3820c260d092d4aec6b166
hcall: markup the event channel hypercalls to improve generated docs

As part of this I looked through the relevant chapter from interfaces.tex (from
4.1, deleted in unstable) to ensure no critical information was missing.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 71159fb049f2 -r b6a3a0d68c91 xen/include/public/event_channel.h
--- a/xen/include/public/event_channel.h	Fri Feb 24 11:46:32 2012 +0100
+++ b/xen/include/public/event_channel.h	Mon Feb 27 12:36:47 2012 +0000
@@ -1,8 +1,8 @@
 /******************************************************************************
  * event_channel.h
- * 
+ *
  * Event channels between domains.
- * 
+ *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to
  * deal in the Software without restriction, including without limitation the
@@ -30,12 +30,49 @@
 #include "xen.h"
 
 /*
- * Prototype for this hypercall is:
- *  int event_channel_op(int cmd, void *args)
- * @cmd  == EVTCHNOP_??? (event-channel operation).
- * @args == Operation-specific extra arguments (NULL if none).
+ * `incontents 150 evtchn Event Channels
+ *
+ * Event channels are the basic primitive provided by Xen for event
+ * notifications. An event is the Xen equivalent of a hardware
+ * interrupt. They essentially store one bit of information, the event
+ * of interest is signalled by transitioning this bit from 0 to 1.
+ *
+ * Notifications are received by a guest via an upcall from Xen,
+ * indicating when an event arrives (setting the bit). Further
+ * notifications are masked until the bit is cleared again (therefore,
+ * guests must check the value of the bit after re-enabling event
+ * delivery to ensure no missed notifications).
+ *
+ * Event notifications can be masked by setting a flag; this is
+ * equivalent to disabling interrupts and can be used to ensure
+ * atomicity of certain operations in the guest kernel.
+ *
+ * Event channels are represented by the evtchn_* fields in
+ * struct shared_info and struct vcpu_info.
  */
 
+/*
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_event_channel_op(enum event_channel_op cmd, void *args)
+ * `
+ * @cmd  == EVTCHNOP_* (event-channel operation).
+ * @args == struct evtchn_* Operation-specific extra arguments (NULL if none).
+ */
+
+/* ` enum event_channel_op { // EVTCHNOP_* => struct evtchn_* */
+#define EVTCHNOP_bind_interdomain 0
+#define EVTCHNOP_bind_virq        1
+#define EVTCHNOP_bind_pirq        2
+#define EVTCHNOP_close            3
+#define EVTCHNOP_send             4
+#define EVTCHNOP_status           5
+#define EVTCHNOP_alloc_unbound    6
+#define EVTCHNOP_bind_ipi         7
+#define EVTCHNOP_bind_vcpu        8
+#define EVTCHNOP_unmask           9
+#define EVTCHNOP_reset           10
+/* ` } */
+
 typedef uint32_t evtchn_port_t;
 DEFINE_XEN_GUEST_HANDLE(evtchn_port_t);
 
@@ -47,7 +84,6 @@ DEFINE_XEN_GUEST_HANDLE(evtchn_port_t);
  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
  *  2. <rdom> may be DOMID_SELF, allowing loopback connections.
  */
-#define EVTCHNOP_alloc_unbound    6
 struct evtchn_alloc_unbound {
     /* IN parameters */
     domid_t dom, remote_dom;
@@ -63,9 +99,8 @@ typedef struct evtchn_alloc_unbound evtc
  * domain. A fresh port is allocated in the calling domain and returned as
  * <local_port>.
  * NOTES:
- *  2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
+ *  1. <remote_dom> may be DOMID_SELF, allowing loopback connections.
  */
-#define EVTCHNOP_bind_interdomain 0
 struct evtchn_bind_interdomain {
     /* IN parameters. */
     domid_t remote_dom;
@@ -87,10 +122,9 @@ typedef struct evtchn_bind_interdomain e
  *     The allocated event channel is bound to the specified vcpu and the
  *     binding cannot be changed.
  */
-#define EVTCHNOP_bind_virq        1
 struct evtchn_bind_virq {
     /* IN parameters. */
-    uint32_t virq;
+    uint32_t virq; /* enum virq */
     uint32_t vcpu;
     /* OUT parameters. */
     evtchn_port_t port;
@@ -98,12 +132,11 @@ struct evtchn_bind_virq {
 typedef struct evtchn_bind_virq evtchn_bind_virq_t;
 
 /*
- * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ <irq>.
+ * EVTCHNOP_bind_pirq: Bind a local event channel to a real IRQ (PIRQ <irq>).
  * NOTES:
  *  1. A physical IRQ may be bound to at most one event channel per domain.
  *  2. Only a sufficiently-privileged domain may bind to a physical IRQ.
  */
-#define EVTCHNOP_bind_pirq        2
 struct evtchn_bind_pirq {
     /* IN parameters. */
     uint32_t pirq;
@@ -120,7 +153,6 @@ typedef struct evtchn_bind_pirq evtchn_b
  *  1. The allocated event channel is bound to the specified vcpu. The binding
  *     may not be changed.
  */
-#define EVTCHNOP_bind_ipi         7
 struct evtchn_bind_ipi {
     uint32_t vcpu;
     /* OUT parameters. */
@@ -133,7 +165,6 @@ typedef struct evtchn_bind_ipi evtchn_bi
  * interdomain then the remote end is placed in the unbound state
  * (EVTCHNSTAT_unbound), awaiting a new connection.
  */
-#define EVTCHNOP_close            3
 struct evtchn_close {
     /* IN parameters. */
     evtchn_port_t port;
@@ -144,7 +175,6 @@ typedef struct evtchn_close evtchn_close
  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
  * endpoint is <port>.
  */
-#define EVTCHNOP_send             4
 struct evtchn_send {
     /* IN parameters. */
     evtchn_port_t port;
@@ -159,7 +189,6 @@ typedef struct evtchn_send evtchn_send_t
  *  2. Only a sufficiently-privileged domain may obtain the status of an event
  *     channel for which <dom> is not DOMID_SELF.
  */
-#define EVTCHNOP_status           5
 struct evtchn_status {
     /* IN parameters */
     domid_t  dom;
@@ -176,13 +205,13 @@ struct evtchn_status {
     union {
         struct {
             domid_t dom;
-        } unbound; /* EVTCHNSTAT_unbound */
+        } unbound;                 /* EVTCHNSTAT_unbound */
         struct {
             domid_t dom;
             evtchn_port_t port;
-        } interdomain; /* EVTCHNSTAT_interdomain */
-        uint32_t pirq;      /* EVTCHNSTAT_pirq        */
-        uint32_t virq;      /* EVTCHNSTAT_virq        */
+        } interdomain;             /* EVTCHNSTAT_interdomain */
+        uint32_t pirq;             /* EVTCHNSTAT_pirq        */
+        uint32_t virq;             /* EVTCHNSTAT_virq        */
     } u;
 };
 typedef struct evtchn_status evtchn_status_t;
@@ -199,7 +228,6 @@ typedef struct evtchn_status evtchn_stat
  *     the channel is allocated (a port that is freed and subsequently reused
  *     has its binding reset to vcpu0).
  */
-#define EVTCHNOP_bind_vcpu        8
 struct evtchn_bind_vcpu {
     /* IN parameters. */
     evtchn_port_t port;
@@ -211,7 +239,6 @@ typedef struct evtchn_bind_vcpu evtchn_b
  * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
  * a notification to the appropriate VCPU if an event is pending.
  */
-#define EVTCHNOP_unmask           9
 struct evtchn_unmask {
     /* IN parameters. */
     evtchn_port_t port;
@@ -224,7 +251,6 @@ typedef struct evtchn_unmask evtchn_unma
  *  1. <dom> may be specified as DOMID_SELF.
  *  2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
  */
-#define EVTCHNOP_reset           10
 struct evtchn_reset {
     /* IN parameters. */
     domid_t dom;
@@ -232,11 +258,13 @@ struct evtchn_reset {
 typedef struct evtchn_reset evtchn_reset_t;
 
 /*
- * Argument to event_channel_op_compat() hypercall. Superceded by new
- * event_channel_op() hypercall since 0x00030202.
+ * ` enum neg_errnoval
+ * ` HYPERVISOR_event_channel_op_compat(struct evtchn_op *op)
+ * `
+ * Superceded by new event_channel_op() hypercall since 0x00030202.
  */
 struct evtchn_op {
-    uint32_t cmd; /* EVTCHNOP_* */
+    uint32_t cmd; /* enum event_channel_op */
     union {
         struct evtchn_alloc_unbound    alloc_unbound;
         struct evtchn_bind_interdomain bind_interdomain;
diff -r 71159fb049f2 -r b6a3a0d68c91 xen/include/public/xen.h
--- a/xen/include/public/xen.h	Fri Feb 24 11:46:32 2012 +0100
+++ b/xen/include/public/xen.h	Mon Feb 27 12:36:47 2012 +0000
@@ -146,6 +146,7 @@ DEFINE_XEN_GUEST_HANDLE(xen_pfn_t);
  * The latter can be allocated only once per guest: they must initially be
  * allocated to VCPU0 but can subsequently be re-bound.
  */
+/* ` 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. */
@@ -167,6 +168,7 @@ DEFINE_XEN_GUEST_HANDLE(xen_pfn_t);
 #define VIRQ_ARCH_5    21
 #define VIRQ_ARCH_6    22
 #define VIRQ_ARCH_7    23
+/* ` } */
 
 #define NR_VIRQS       24