xen/interface/event_channel.h

0001 /* SPDX-License-Identifier: MIT */
0002 /******************************************************************************
0003  * event_channel.h
0004  *
0005  * Event channels between domains.
0006  *
0007  * Copyright (c) 2003-2004, K A Fraser.
0008  */
0009
0010 #ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
0011 #define __XEN_PUBLIC_EVENT_CHANNEL_H__
0012
0013 #include <xen/interface/xen.h>
0014
0015 typedef uint32_t evtchn_port_t;
0016 DEFINE_GUEST_HANDLE(evtchn_port_t);
0017
0018 /*
0019  * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
0020  * accepting interdomain bindings from domain <remote_dom>. A fresh port
0021  * is allocated in <dom> and returned as <port>.
0022  * NOTES:
0023  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
0024  *  2. <rdom> may be DOMID_SELF, allowing loopback connections.
0025  */
0026 #define EVTCHNOP_alloc_unbound    6
0027 struct evtchn_alloc_unbound {
0028     /* IN parameters */
0029     domid_t dom, remote_dom;
0030     /* OUT parameters */
0031     evtchn_port_t port;
0032 };
0033
0034 /*
0035  * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between
0036  * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify
0037  * a port that is unbound and marked as accepting bindings from the calling
0038  * domain. A fresh port is allocated in the calling domain and returned as
0039  * <local_port>.
0040  * NOTES:
0041  *  2. <remote_dom> may be DOMID_SELF, allowing loopback connections.
0042  */
0043 #define EVTCHNOP_bind_interdomain 0
0044 struct evtchn_bind_interdomain {
0045     /* IN parameters. */
0046     domid_t remote_dom;
0047     evtchn_port_t remote_port;
0048     /* OUT parameters. */
0049     evtchn_port_t local_port;
0050 };
0051
0052 /*
0053  * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified
0054  * vcpu.
0055  * NOTES:
0056  *  1. A virtual IRQ may be bound to at most one event channel per vcpu.
0057  *  2. The allocated event channel is bound to the specified vcpu. The binding
0058  *     may not be changed.
0059  */
0060 #define EVTCHNOP_bind_virq    1
0061 struct evtchn_bind_virq {
0062     /* IN parameters. */
0063     uint32_t virq;
0064     uint32_t vcpu;
0065     /* OUT parameters. */
0066     evtchn_port_t port;
0067 };
0068
0069 /*
0070  * EVTCHNOP_bind_pirq: Bind a local event channel to PIRQ <irq>.
0071  * NOTES:
0072  *  1. A physical IRQ may be bound to at most one event channel per domain.
0073  *  2. Only a sufficiently-privileged domain may bind to a physical IRQ.
0074  */
0075 #define EVTCHNOP_bind_pirq    2
0076 struct evtchn_bind_pirq {
0077     /* IN parameters. */
0078     uint32_t pirq;
0079 #define BIND_PIRQ__WILL_SHARE 1
0080     uint32_t flags; /* BIND_PIRQ__* */
0081     /* OUT parameters. */
0082     evtchn_port_t port;
0083 };
0084
0085 /*
0086  * EVTCHNOP_bind_ipi: Bind a local event channel to receive events.
0087  * NOTES:
0088  *  1. The allocated event channel is bound to the specified vcpu. The binding
0089  *     may not be changed.
0090  */
0091 #define EVTCHNOP_bind_ipi     7
0092 struct evtchn_bind_ipi {
0093     uint32_t vcpu;
0094     /* OUT parameters. */
0095     evtchn_port_t port;
0096 };
0097
0098 /*
0099  * EVTCHNOP_close: Close a local event channel <port>. If the channel is
0100  * interdomain then the remote end is placed in the unbound state
0101  * (EVTCHNSTAT_unbound), awaiting a new connection.
0102  */
0103 #define EVTCHNOP_close        3
0104 struct evtchn_close {
0105     /* IN parameters. */
0106     evtchn_port_t port;
0107 };
0108
0109 /*
0110  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
0111  * endpoint is <port>.
0112  */
0113 #define EVTCHNOP_send         4
0114 struct evtchn_send {
0115     /* IN parameters. */
0116     evtchn_port_t port;
0117 };
0118
0119 /*
0120  * EVTCHNOP_status: Get the current status of the communication channel which
0121  * has an endpoint at <dom, port>.
0122  * NOTES:
0123  *  1. <dom> may be specified as DOMID_SELF.
0124  *  2. Only a sufficiently-privileged domain may obtain the status of an event
0125  *     channel for which <dom> is not DOMID_SELF.
0126  */
0127 #define EVTCHNOP_status       5
0128 struct evtchn_status {
0129     /* IN parameters */
0130     domid_t  dom;
0131     evtchn_port_t port;
0132     /* OUT parameters */
0133 #define EVTCHNSTAT_closed   0  /* Channel is not in use.             */
0134 #define EVTCHNSTAT_unbound  1  /* Channel is waiting interdom connection.*/
0135 #define EVTCHNSTAT_interdomain  2  /* Channel is connected to remote domain. */
0136 #define EVTCHNSTAT_pirq     3  /* Channel is bound to a phys IRQ line.   */
0137 #define EVTCHNSTAT_virq     4  /* Channel is bound to a virtual IRQ line */
0138 #define EVTCHNSTAT_ipi      5  /* Channel is bound to a virtual IPI line */
0139     uint32_t status;
0140     uint32_t vcpu;         /* VCPU to which this channel is bound.   */
0141     union {
0142         struct {
0143             domid_t dom;
0144         } unbound; /* EVTCHNSTAT_unbound */
0145         struct {
0146             domid_t dom;
0147             evtchn_port_t port;
0148         } interdomain; /* EVTCHNSTAT_interdomain */
0149         uint32_t pirq;      /* EVTCHNSTAT_pirq        */
0150         uint32_t virq;      /* EVTCHNSTAT_virq        */
0151     } u;
0152 };
0153
0154 /*
0155  * EVTCHNOP_bind_vcpu: Specify which vcpu a channel should notify when an
0156  * event is pending.
0157  * NOTES:
0158  *  1. IPI- and VIRQ-bound channels always notify the vcpu that initialised
0159  *     the binding. This binding cannot be changed.
0160  *  2. All other channels notify vcpu0 by default. This default is set when
0161  *     the channel is allocated (a port that is freed and subsequently reused
0162  *     has its binding reset to vcpu0).
0163  */
0164 #define EVTCHNOP_bind_vcpu    8
0165 struct evtchn_bind_vcpu {
0166     /* IN parameters. */
0167     evtchn_port_t port;
0168     uint32_t vcpu;
0169 };
0170
0171 /*
0172  * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver
0173  * a notification to the appropriate VCPU if an event is pending.
0174  */
0175 #define EVTCHNOP_unmask       9
0176 struct evtchn_unmask {
0177     /* IN parameters. */
0178     evtchn_port_t port;
0179 };
0180
0181 /*
0182  * EVTCHNOP_reset: Close all event channels associated with specified domain.
0183  * NOTES:
0184  *  1. <dom> may be specified as DOMID_SELF.
0185  *  2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
0186  */
0187 #define EVTCHNOP_reset       10
0188 struct evtchn_reset {
0189     /* IN parameters. */
0190     domid_t dom;
0191 };
0192 typedef struct evtchn_reset evtchn_reset_t;
0193
0194 /*
0195  * EVTCHNOP_init_control: initialize the control block for the FIFO ABI.
0196  */
0197 #define EVTCHNOP_init_control    11
0198 struct evtchn_init_control {
0199     /* IN parameters. */
0200     uint64_t control_gfn;
0201     uint32_t offset;
0202     uint32_t vcpu;
0203     /* OUT parameters. */
0204     uint8_t link_bits;
0205     uint8_t _pad[7];
0206 };
0207
0208 /*
0209  * EVTCHNOP_expand_array: add an additional page to the event array.
0210  */
0211 #define EVTCHNOP_expand_array    12
0212 struct evtchn_expand_array {
0213     /* IN parameters. */
0214     uint64_t array_gfn;
0215 };
0216
0217 /*
0218  * EVTCHNOP_set_priority: set the priority for an event channel.
0219  */
0220 #define EVTCHNOP_set_priority    13
0221 struct evtchn_set_priority {
0222     /* IN parameters. */
0223     evtchn_port_t port;
0224     uint32_t priority;
0225 };
0226
0227 struct evtchn_op {
0228     uint32_t cmd; /* EVTCHNOP_* */
0229     union {
0230         struct evtchn_alloc_unbound    alloc_unbound;
0231         struct evtchn_bind_interdomain bind_interdomain;
0232         struct evtchn_bind_virq        bind_virq;
0233         struct evtchn_bind_pirq        bind_pirq;
0234         struct evtchn_bind_ipi         bind_ipi;
0235         struct evtchn_close        close;
0236         struct evtchn_send         send;
0237         struct evtchn_status           status;
0238         struct evtchn_bind_vcpu        bind_vcpu;
0239         struct evtchn_unmask           unmask;
0240     } u;
0241 };
0242 DEFINE_GUEST_HANDLE_STRUCT(evtchn_op);
0243
0244 /*
0245  * 2-level ABI
0246  */
0247
0248 #define EVTCHN_2L_NR_CHANNELS (sizeof(xen_ulong_t) * sizeof(xen_ulong_t) * 64)
0249
0250 /*
0251  * FIFO ABI
0252  */
0253
0254 /* Events may have priorities from 0 (highest) to 15 (lowest). */
0255 #define EVTCHN_FIFO_PRIORITY_MAX     0
0256 #define EVTCHN_FIFO_PRIORITY_DEFAULT 7
0257 #define EVTCHN_FIFO_PRIORITY_MIN     15
0258
0259 #define EVTCHN_FIFO_MAX_QUEUES (EVTCHN_FIFO_PRIORITY_MIN + 1)
0260
0261 typedef uint32_t event_word_t;
0262
0263 #define EVTCHN_FIFO_PENDING 31
0264 #define EVTCHN_FIFO_MASKED  30
0265 #define EVTCHN_FIFO_LINKED  29
0266 #define EVTCHN_FIFO_BUSY    28
0267
0268 #define EVTCHN_FIFO_LINK_BITS 17
0269 #define EVTCHN_FIFO_LINK_MASK ((1 << EVTCHN_FIFO_LINK_BITS) - 1)
0270
0271 #define EVTCHN_FIFO_NR_CHANNELS (1 << EVTCHN_FIFO_LINK_BITS)
0272
0273 struct evtchn_fifo_control_block {
0274     uint32_t     ready;
0275     uint32_t     _rsvd;
0276     event_word_t head[EVTCHN_FIFO_MAX_QUEUES];
0277 };
0278
0279 #endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */