From mboxrd@z Thu Jan  1 00:00:00 1970
From: Ian Campbell <ian.campbell@citrix.com>
Subject: [PATCH DOCDAY] hcall: markup the event channel
 hypercalls to improve generated docs
Date: Mon, 27 Feb 2012 12:07:11 +0000
Message-ID: <31eb9ee09b726bfab1df.1330344431@cosworth.uk.xensource.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
Return-path: <xen-devel-bounces@lists.xen.org>
List-Unsubscribe: <http://lists.xen.org/cgi-bin/mailman/options/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=unsubscribe>
List-Post: <mailto:xen-devel@lists.xen.org>
List-Help: <mailto:xen-devel-request@lists.xen.org?subject=help>
List-Subscribe: <http://lists.xen.org/cgi-bin/mailman/listinfo/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=subscribe>
Sender: xen-devel-bounces@lists.xen.org
Errors-To: xen-devel-bounces@lists.xen.org
To: xen-devel@lists.xensource.com
Cc: Ian Campbell <ian.campbell@citrix.com>
List-Id: xen-devel@lists.xenproject.org

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1330344234 0
# Node ID 31eb9ee09b726bfab1df49580f024693f4f307ae
# 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 31eb9ee09b72 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:03:54 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,27 @@
 #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).
+ * ` 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 +62,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 +77,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 +100,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 +110,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 +131,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 +143,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 +153,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 +167,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 +183,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 +206,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 +217,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 +229,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 +236,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 31eb9ee09b72 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:03:54 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