|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-devel] [PATCH DOCDAY] hcall: markup the event channel hypercalls to improve generated docs
# HG changeset patch
# User Ian Campbell <ian.campbell@xxxxxxxxxx>
# 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@xxxxxxxxxx>
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
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |