include/xen/interface/event_channel.h

   1 /* SPDX-License-Identifier: MIT */
   2 /******************************************************************************
   3  * event_channel.h
   4  *
   5  * Event channels between domains.
   6  *
   7  * Copyright (c) 2003-2004, K A Fraser.
   8  */
   9
  10 #ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
  11 #define __XEN_PUBLIC_EVENT_CHANNEL_H__
  12
  13 #include <xen/interface/xen.h>
  14
  15 typedef uint32_t evtchn_port_t;
  16 DEFINE_GUEST_HANDLE(evtchn_port_t);
  17
  18 /*
  19  * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
  20  * accepting interdomain bindings from domain <remote_dom>. A fresh port
  21  * is allocated in <dom> and returned as <port>.
  22  * NOTES:
  23  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
  24  *  2. <rdom> may be DOMID_SELF, allowing loopback connections.
  25  */
  26 #define EVTCHNOP_alloc_unbound    6
  27 struct evtchn_alloc_unbound {
  28         /* IN parameters */
  29         domid_t dom, remote_dom;
  30         /* OUT parameters */
  31         evtchn_port_t port;
  32 };
  33
  34 /*
  35  * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between
  36  * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify
  37  * a port that is unbound and marked as accepting bindings from the calling
  38  * domain. A fresh port is allocated in the calling domain and returned as
  39  * <local_port>.
  40  * NOTES:
  41  *  2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
  42  */
  43 #define EVTCHNOP_bind_interdomain 0
  44 struct evtchn_bind_interdomain {
  45         /* IN parameters. */
  46         domid_t remote_dom;
  47         evtchn_port_t remote_port;
  48         /* OUT parameters. */
  49         evtchn_port_t local_port;
  50 };
  51
  52 /*
  53  * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified
  54  * vcpu.
  55  * NOTES:
  56  *  1. A virtual IRQ may be bound to at most one event channel per vcpu.
  57  *  2. The allocated event channel is bound to the specified vcpu. The binding
  58  *     may not be changed.
  59  */
  60 #define EVTCHNOP_bind_virq        1
  61 struct evtchn_bind_virq {
  62         /* IN parameters. */
  63         uint32_t virq;
  64         uint32_t vcpu;
  65         /* OUT parameters. */
  66         evtchn_port_t port;
  67 };
  68
  69 /*
  70  * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ <irq>.
  71  * NOTES:
  72  *  1. A physical IRQ may be bound to at most one event channel per domain.
  73  *  2. Only a sufficiently-privileged domain may bind to a physical IRQ.
  74  */
  75 #define EVTCHNOP_bind_pirq        2
  76 struct evtchn_bind_pirq {
  77         /* IN parameters. */
  78         uint32_t pirq;
  79 #define BIND_PIRQ__WILL_SHARE 1
  80         uint32_t flags; /* BIND_PIRQ__* */
  81         /* OUT parameters. */
  82         evtchn_port_t port;
  83 };
  84
  85 /*
  86  * EVTCHNOP_bind_ipi: Bind a local event channel to receive events.
  87  * NOTES:
  88  *  1. The allocated event channel is bound to the specified vcpu. The binding
  89  *     may not be changed.
  90  */
  91 #define EVTCHNOP_bind_ipi         7
  92 struct evtchn_bind_ipi {
  93         uint32_t vcpu;
  94         /* OUT parameters. */
  95         evtchn_port_t port;
  96 };
  97
  98 /*
  99  * EVTCHNOP_close: Close a local event channel <port>. If the channel is
 100  * interdomain then the remote end is placed in the unbound state
 101  * (EVTCHNSTAT_unbound), awaiting a new connection.
 102  */
 103 #define EVTCHNOP_close            3
 104 struct evtchn_close {
 105         /* IN parameters. */
 106         evtchn_port_t port;
 107 };
 108
 109 /*
 110  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
 111  * endpoint is <port>.
 112  */
 113 #define EVTCHNOP_send             4
 114 struct evtchn_send {
 115         /* IN parameters. */
 116         evtchn_port_t port;
 117 };
 118
 119 /*
 120  * EVTCHNOP_status: Get the current status of the communication channel which
 121  * has an endpoint at <dom, port>.
 122  * NOTES:
 123  *  1. <dom> may be specified as DOMID_SELF.
 124  *  2. Only a sufficiently-privileged domain may obtain the status of an event
 125  *     channel for which <dom> is not DOMID_SELF.
 126  */
 127 #define EVTCHNOP_status           5
 128 struct evtchn_status {
 129         /* IN parameters */
 130         domid_t  dom;
 131         evtchn_port_t port;
 132         /* OUT parameters */
 133 #define EVTCHNSTAT_closed       0  /* Channel is not in use.                 */
 134 #define EVTCHNSTAT_unbound      1  /* Channel is waiting interdom connection.*/
 135 #define EVTCHNSTAT_interdomain  2  /* Channel is connected to remote domain. */
 136 #define EVTCHNSTAT_pirq         3  /* Channel is bound to a phys IRQ line.   */
 137 #define EVTCHNSTAT_virq         4  /* Channel is bound to a virtual IRQ line */
 138 #define EVTCHNSTAT_ipi          5  /* Channel is bound to a virtual IPI line */
 139         uint32_t status;
 140         uint32_t vcpu;             /* VCPU to which this channel is bound.   */
 141         union {
 142                 struct {
 143                         domid_t dom;
 144                 } unbound; /* EVTCHNSTAT_unbound */
 145                 struct {
 146                         domid_t dom;
 147                         evtchn_port_t port;
 148                 } interdomain; /* EVTCHNSTAT_interdomain */
 149                 uint32_t pirq;      /* EVTCHNSTAT_pirq        */
 150                 uint32_t virq;      /* EVTCHNSTAT_virq        */
 151         } u;
 152 };
 153
 154 /*
 155  * EVTCHNOP_bind_vcpu: Specify which vcpu a channel should notify when an
 156  * event is pending.
 157  * NOTES:
 158  *  1. IPI- and VIRQ-bound channels always notify the vcpu that initialised
 159  *     the binding. This binding cannot be changed.
 160  *  2. All other channels notify vcpu0 by default. This default is set when
 161  *     the channel is allocated (a port that is freed and subsequently reused
 162  *     has its binding reset to vcpu0).
 163  */
 164 #define EVTCHNOP_bind_vcpu        8
 165 struct evtchn_bind_vcpu {
 166         /* IN parameters. */
 167         evtchn_port_t port;
 168         uint32_t vcpu;
 169 };
 170
 171 /*
 172  * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
 173  * a notification to the appropriate VCPU if an event is pending.
 174  */
 175 #define EVTCHNOP_unmask           9
 176 struct evtchn_unmask {
 177         /* IN parameters. */
 178         evtchn_port_t port;
 179 };
 180
 181 /*
 182  * EVTCHNOP_reset: Close all event channels associated with specified domain.
 183  * NOTES:
 184  *  1. <dom> may be specified as DOMID_SELF.
 185  *  2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
 186  */
 187 #define EVTCHNOP_reset           10
 188 struct evtchn_reset {
 189         /* IN parameters. */
 190         domid_t dom;
 191 };
 192 typedef struct evtchn_reset evtchn_reset_t;
 193
 194 /*
 195  * EVTCHNOP_init_control: initialize the control block for the FIFO ABI.
 196  */
 197 #define EVTCHNOP_init_control    11
 198 struct evtchn_init_control {
 199         /* IN parameters. */
 200         uint64_t control_gfn;
 201         uint32_t offset;
 202         uint32_t vcpu;
 203         /* OUT parameters. */
 204         uint8_t link_bits;
 205         uint8_t _pad[7];
 206 };
 207
 208 /*
 209  * EVTCHNOP_expand_array: add an additional page to the event array.
 210  */
 211 #define EVTCHNOP_expand_array    12
 212 struct evtchn_expand_array {
 213         /* IN parameters. */
 214         uint64_t array_gfn;
 215 };
 216
 217 /*
 218  * EVTCHNOP_set_priority: set the priority for an event channel.
 219  */
 220 #define EVTCHNOP_set_priority    13
 221 struct evtchn_set_priority {
 222         /* IN parameters. */
 223         evtchn_port_t port;
 224         uint32_t priority;
 225 };
 226
 227 struct evtchn_op {
 228         uint32_t cmd; /* EVTCHNOP_* */
 229         union {
 230                 struct evtchn_alloc_unbound    alloc_unbound;
 231                 struct evtchn_bind_interdomain bind_interdomain;
 232                 struct evtchn_bind_virq        bind_virq;
 233                 struct evtchn_bind_pirq        bind_pirq;
 234                 struct evtchn_bind_ipi         bind_ipi;
 235                 struct evtchn_close            close;
 236                 struct evtchn_send             send;
 237                 struct evtchn_status           status;
 238                 struct evtchn_bind_vcpu        bind_vcpu;
 239                 struct evtchn_unmask           unmask;
 240         } u;
 241 };
 242 DEFINE_GUEST_HANDLE_STRUCT(evtchn_op);
 243
 244 /*
 245  * 2-level ABI
 246  */
 247
 248 #define EVTCHN_2L_NR_CHANNELS (sizeof(xen_ulong_t) * sizeof(xen_ulong_t) * 64)
 249
 250 /*
 251  * FIFO ABI
 252  */
 253
 254 /* Events may have priorities from 0 (highest) to 15 (lowest). */
 255 #define EVTCHN_FIFO_PRIORITY_MAX     0
 256 #define EVTCHN_FIFO_PRIORITY_DEFAULT 7
 257 #define EVTCHN_FIFO_PRIORITY_MIN     15
 258
 259 #define EVTCHN_FIFO_MAX_QUEUES (EVTCHN_FIFO_PRIORITY_MIN + 1)
 260
 261 typedef uint32_t event_word_t;
 262
 263 #define EVTCHN_FIFO_PENDING 31
 264 #define EVTCHN_FIFO_MASKED  30
 265 #define EVTCHN_FIFO_LINKED  29
 266 #define EVTCHN_FIFO_BUSY    28
 267
 268 #define EVTCHN_FIFO_LINK_BITS 17
 269 #define EVTCHN_FIFO_LINK_MASK ((1 << EVTCHN_FIFO_LINK_BITS) - 1)
 270
 271 #define EVTCHN_FIFO_NR_CHANNELS (1 << EVTCHN_FIFO_LINK_BITS)
 272
 273 struct evtchn_fifo_control_block {
 274         uint32_t     ready;
 275         uint32_t     _rsvd;
 276         event_word_t head[EVTCHN_FIFO_MAX_QUEUES];
 277 };
 278
 279 #endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */