include/xen/interface/event_channel.h

   1 /******************************************************************************
   2  * event_channel.h
   3  *
   4  * Event channels between domains.
   5  *
   6  * Copyright (c) 2003-2004, K A Fraser.
   7  */
   8
   9 #ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
  10 #define __XEN_PUBLIC_EVENT_CHANNEL_H__
  11
  12 /*
  13  * Prototype for this hypercall is:
  14  *  int event_channel_op(int cmd, void *args)
  15  * @cmd  == EVTCHNOP_??? (event-channel operation).
  16  * @args == Operation-specific extra arguments (NULL if none).
  17  */
  18
  19 typedef uint32_t evtchn_port_t;
  20 DEFINE_XEN_GUEST_HANDLE(evtchn_port_t);
  21
  22 /*
  23  * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
  24  * accepting interdomain bindings from domain <remote_dom>. A fresh port
  25  * is allocated in <dom> and returned as <port>.
  26  * NOTES:
  27  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
  28  *  2. <rdom> may be DOMID_SELF, allowing loopback connections.
  29  */
  30 #define EVTCHNOP_alloc_unbound    6
  31 struct evtchn_alloc_unbound {
  32     /* IN parameters */
  33     domid_t dom, remote_dom;
  34     /* OUT parameters */
  35     evtchn_port_t port;
  36 };
  37 typedef struct evtchn_alloc_unbound evtchn_alloc_unbound_t;
  38
  39 /*
  40  * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between
  41  * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify
  42  * a port that is unbound and marked as accepting bindings from the calling
  43  * domain. A fresh port is allocated in the calling domain and returned as
  44  * <local_port>.
  45  * NOTES:
  46  *  2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
  47  */
  48 #define EVTCHNOP_bind_interdomain 0
  49 struct evtchn_bind_interdomain {
  50     /* IN parameters. */
  51     domid_t remote_dom;
  52     evtchn_port_t remote_port;
  53     /* OUT parameters. */
  54     evtchn_port_t local_port;
  55 };
  56 typedef struct evtchn_bind_interdomain evtchn_bind_interdomain_t;
  57
  58 /*
  59  * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified
  60  * vcpu.
  61  * NOTES:
  62  *  1. Virtual IRQs are classified as per-vcpu or global. See the VIRQ list
  63  *     in xen.h for the classification of each VIRQ.
  64  *  2. Global VIRQs must be allocated on VCPU0 but can subsequently be
  65  *     re-bound via EVTCHNOP_bind_vcpu.
  66  *  3. Per-vcpu VIRQs may be bound to at most one event channel per vcpu.
  67  *     The allocated event channel is bound to the specified vcpu and the
  68  *     binding cannot be changed.
  69  */
  70 #define EVTCHNOP_bind_virq        1
  71 struct evtchn_bind_virq {
  72     /* IN parameters. */
  73     uint32_t virq;
  74     uint32_t vcpu;
  75     /* OUT parameters. */
  76     evtchn_port_t port;
  77 };
  78 typedef struct evtchn_bind_virq evtchn_bind_virq_t;
  79
  80 /*
  81  * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ <irq>.
  82  * NOTES:
  83  *  1. A physical IRQ may be bound to at most one event channel per domain.
  84  *  2. Only a sufficiently-privileged domain may bind to a physical IRQ.
  85  */
  86 #define EVTCHNOP_bind_pirq        2
  87 struct evtchn_bind_pirq {
  88     /* IN parameters. */
  89     uint32_t pirq;
  90 #define BIND_PIRQ__WILL_SHARE 1
  91     uint32_t flags; /* BIND_PIRQ__* */
  92     /* OUT parameters. */
  93     evtchn_port_t port;
  94 };
  95 typedef struct evtchn_bind_pirq evtchn_bind_pirq_t;
  96
  97 /*
  98  * EVTCHNOP_bind_ipi: Bind a local event channel to receive events.
  99  * NOTES:
 100  *  1. The allocated event channel is bound to the specified vcpu. The binding
 101  *     may not be changed.
 102  */
 103 #define EVTCHNOP_bind_ipi         7
 104 struct evtchn_bind_ipi {
 105     uint32_t vcpu;
 106     /* OUT parameters. */
 107     evtchn_port_t port;
 108 };
 109 typedef struct evtchn_bind_ipi evtchn_bind_ipi_t;
 110
 111 /*
 112  * EVTCHNOP_close: Close a local event channel <port>. If the channel is
 113  * interdomain then the remote end is placed in the unbound state
 114  * (EVTCHNSTAT_unbound), awaiting a new connection.
 115  */
 116 #define EVTCHNOP_close            3
 117 struct evtchn_close {
 118     /* IN parameters. */
 119     evtchn_port_t port;
 120 };
 121 typedef struct evtchn_close evtchn_close_t;
 122
 123 /*
 124  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
 125  * endpoint is <port>.
 126  */
 127 #define EVTCHNOP_send             4
 128 struct evtchn_send {
 129     /* IN parameters. */
 130     evtchn_port_t port;
 131 };
 132 typedef struct evtchn_send evtchn_send_t;
 133
 134 /*
 135  * EVTCHNOP_status: Get the current status of the communication channel which
 136  * has an endpoint at <dom, port>.
 137  * NOTES:
 138  *  1. <dom> may be specified as DOMID_SELF.
 139  *  2. Only a sufficiently-privileged domain may obtain the status of an event
 140  *     channel for which <dom> is not DOMID_SELF.
 141  */
 142 #define EVTCHNOP_status           5
 143 struct evtchn_status {
 144     /* IN parameters */
 145     domid_t  dom;
 146     evtchn_port_t port;
 147     /* OUT parameters */
 148 #define EVTCHNSTAT_closed       0  /* Channel is not in use.                 */
 149 #define EVTCHNSTAT_unbound      1  /* Channel is waiting interdom connection.*/
 150 #define EVTCHNSTAT_interdomain  2  /* Channel is connected to remote domain. */
 151 #define EVTCHNSTAT_pirq         3  /* Channel is bound to a phys IRQ line.   */
 152 #define EVTCHNSTAT_virq         4  /* Channel is bound to a virtual IRQ line */
 153 #define EVTCHNSTAT_ipi          5  /* Channel is bound to a virtual IPI line */
 154     uint32_t status;
 155     uint32_t vcpu;                 /* VCPU to which this channel is bound.   */
 156     union {
 157         struct {
 158             domid_t dom;
 159         } unbound; /* EVTCHNSTAT_unbound */
 160         struct {
 161             domid_t dom;
 162             evtchn_port_t port;
 163         } interdomain; /* EVTCHNSTAT_interdomain */
 164         uint32_t pirq;      /* EVTCHNSTAT_pirq        */
 165         uint32_t virq;      /* EVTCHNSTAT_virq        */
 166     } u;
 167 };
 168 typedef struct evtchn_status evtchn_status_t;
 169
 170 /*
 171  * EVTCHNOP_bind_vcpu: Specify which vcpu a channel should notify when an
 172  * event is pending.
 173  * NOTES:
 174  *  1. IPI-bound channels always notify the vcpu specified at bind time.
 175  *     This binding cannot be changed.
 176  *  2. Per-VCPU VIRQ channels always notify the vcpu specified at bind time.
 177  *     This binding cannot be changed.
 178  *  3. All other channels notify vcpu0 by default. This default is set when
 179  *     the channel is allocated (a port that is freed and subsequently reused
 180  *     has its binding reset to vcpu0).
 181  */
 182 #define EVTCHNOP_bind_vcpu        8
 183 struct evtchn_bind_vcpu {
 184     /* IN parameters. */
 185     evtchn_port_t port;
 186     uint32_t vcpu;
 187 };
 188 typedef struct evtchn_bind_vcpu evtchn_bind_vcpu_t;
 189
 190 /*
 191  * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
 192  * a notification to the appropriate VCPU if an event is pending.
 193  */
 194 #define EVTCHNOP_unmask           9
 195 struct evtchn_unmask {
 196     /* IN parameters. */
 197     evtchn_port_t port;
 198 };
 199 typedef struct evtchn_unmask evtchn_unmask_t;
 200
 201 /*
 202  * Argument to event_channel_op_compat() hypercall. Superceded by new
 203  * event_channel_op() hypercall since 0x00030202.
 204  */
 205 struct evtchn_op {
 206     uint32_t cmd; /* EVTCHNOP_* */
 207     union {
 208         struct evtchn_alloc_unbound    alloc_unbound;
 209         struct evtchn_bind_interdomain bind_interdomain;
 210         struct evtchn_bind_virq        bind_virq;
 211         struct evtchn_bind_pirq        bind_pirq;
 212         struct evtchn_bind_ipi         bind_ipi;
 213         struct evtchn_close            close;
 214         struct evtchn_send             send;
 215         struct evtchn_status           status;
 216         struct evtchn_bind_vcpu        bind_vcpu;
 217         struct evtchn_unmask           unmask;
 218     } u;
 219 };
 220 typedef struct evtchn_op evtchn_op_t;
 221 DEFINE_XEN_GUEST_HANDLE(evtchn_op_t);
 222
 223 #endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */
 224
 225 /*
 226  * Local variables:
 227  * mode: C
 228  * c-set-style: "BSD"
 229  * c-basic-offset: 4
 230  * tab-width: 4
 231  * indent-tabs-mode: nil
 232  * End:
 233  */