diff options
author | Ian Campbell <ian.campbell@citrix.com> | 2012-03-01 16:03:21 +0000 |
---|---|---|
committer | Ian Campbell <ian.campbell@citrix.com> | 2012-03-01 16:03:21 +0000 |
commit | e00fc7b748c70ada44bab4bd8e108cc1a7494d95 (patch) | |
tree | 9a3d0549389cd4afc822a90e089cce2268fcaf14 /xen/include/public/event_channel.h | |
parent | 2131e4744b591ef304e4ee2dd0d3c6891ad659b9 (diff) | |
download | xen-e00fc7b748c70ada44bab4bd8e108cc1a7494d95.tar.gz xen-e00fc7b748c70ada44bab4bd8e108cc1a7494d95.tar.bz2 xen-e00fc7b748c70ada44bab4bd8e108cc1a7494d95.zip |
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>
Acked-by: Keir Fraser <keir@xen.org>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Diffstat (limited to 'xen/include/public/event_channel.h')
-rw-r--r-- | xen/include/public/event_channel.h | 82 |
1 files changed, 55 insertions, 27 deletions
diff --git a/xen/include/public/event_channel.h b/xen/include/public/event_channel.h index 03d4ce7a4d..07ff32194b 100644 --- a/xen/include/public/event_channel.h +++ b/xen/include/public/event_channel.h @@ -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 evtchn_alloc_unbound_t; * 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 evtchn_bind_interdomain_t; * 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_bind_pirq_t; * 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_bind_ipi_t; * 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_t; * 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_status_t; * 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_bind_vcpu_t; * 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_unmask_t; * 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; |