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.
-
struct
evtchn_alloc_unbound
¶ EVTCHNOP_alloc_unbound
Definition
struct evtchn_alloc_unbound {
domid_t dom;
domid_t remote_dom;
evtchn_port_t port;
};
Members
dom
- IN parameter
remote_dom
- IN parameter
port
- OUT parameter
Description
Allocate a port in domain <dom> and mark as accepting interdomain bindings from domain <remote_dom>. A fresh port is allocated in <dom> and returned as <port>.
NOTES
- If the caller is unprivileged then <dom> must be DOMID_SELF.
- <remote_dom> may be DOMID_SELF, allowing loopback connections.
-
struct
evtchn_bind_interdomain
¶ EVTCHNOP_bind_interdomain
Definition
struct evtchn_bind_interdomain {
domid_t remote_dom;
evtchn_port_t remote_port;
evtchn_port_t local_port;
};
Members
remote_dom
- IN parameter
remote_port
- IN parameter
local_port
- OUT parameter
Description
Construct an interdomain event channel between the calling domain and <remote_dom>. <remote_dom,remote_port> must identify a port that is unbound and marked as accepting bindings from the calling domain. A fresh port is allocated in the calling domain and returned as <local_port>.
In case the peer domain has already tried to set our event channel pending, before it was bound, EVTCHNOP_bind_interdomain always sets the local event channel pending.
The usual pattern of use, in the guest’s upcall (or subsequent handler) is as follows: (Re-enable the event channel for subsequent signalling and then) check for the existence of whatever condition is being waited for by other means, and take whatever action is needed (if any).
NOTES
- <remote_dom> may be DOMID_SELF, allowing loopback connections.
-
struct
evtchn_bind_virq
¶ EVTCHNOP_bind_virq
Definition
struct evtchn_bind_virq {
uint32_t virq;
uint32_t vcpu;
evtchn_port_t port;
};
Members
virq
- IN parameter, enum virq
vcpu
- IN parameter
port
- OUT parameter
Description
Bind a local event channel to VIRQ <irq> on specified vcpu.
NOTES
- Virtual IRQs are classified as per-vcpu or global. See the VIRQ list in xen.h for the classification of each VIRQ.
- Global VIRQs must be allocated on VCPU0 but can subsequently be re-bound via EVTCHNOP_bind_vcpu.
- Per-vcpu VIRQs may be bound to at most one event channel per vcpu. The allocated event channel is bound to the specified vcpu and the binding cannot be changed.
-
struct
evtchn_bind_pirq
¶ EVTCHNOP_bind_pirq
Definition
struct evtchn_bind_pirq {
uint32_t pirq;
#define BIND_PIRQ__WILL_SHARE 1;
uint32_t flags;
evtchn_port_t port;
};
Members
pirq
- IN parameter
flags
- IN parameter, BIND_PIRQ__*
port
- OUT parameter
Description
Bind a local event channel to a real IRQ (PIRQ <irq>).
NOTES
- A physical IRQ may be bound to at most one event channel per domain.
- Only a sufficiently-privileged domain may bind to a physical IRQ.
-
struct
evtchn_bind_ipi
¶ EVTCHNOP_bind_ipi
Definition
struct evtchn_bind_ipi {
uint32_t vcpu;
evtchn_port_t port;
};
Members
vcpu
- IN parameter
port
- OUT parameter
Description
Bind a local event channel to receive events.
NOTES
- The allocated event channel is bound to the specified vcpu. The binding may not be changed.
-
struct
evtchn_close
¶ EVTCHNOP_close
Definition
struct evtchn_close {
evtchn_port_t port;
};
Members
port
- IN parameter
Description
Close a local event channel <port>. If the channel is interdomain then the remote end is placed in the unbound state (EVTCHNSTAT_unbound), awaiting a new connection.
-
struct
evtchn_send
¶ EVTCHNOP_send
Definition
struct evtchn_send {
evtchn_port_t port;
};
Members
port
- IN parameter
Description
Send an event to the remote end of the channel whose local endpoint is <port>.
-
struct
evtchn_status
¶ EVTCHNOP_status
Definition
struct evtchn_status {
domid_t dom;
evtchn_port_t port;
#define EVTCHNSTAT_closed 0 ;
#define EVTCHNSTAT_unbound 1 ;
#define EVTCHNSTAT_interdomain 2 ;
#define EVTCHNSTAT_pirq 3 ;
#define EVTCHNSTAT_virq 4 ;
#define EVTCHNSTAT_ipi 5 ;
uint32_t status;
uint32_t vcpu;
union {
struct {
domid_t dom;
} unbound;
struct {
domid_t dom;
evtchn_port_t port;
} interdomain;
uint32_t pirq;
uint32_t virq;
} u;
};
Members
dom
- IN parameter
port
- IN parameter
status
- OUT parameter
vcpu
- OUT parameter, VCPU to which this channel is bound
u
- OUT parameter
u.unbound
- EVTCHNSTAT_unbound
u.interdomain
- EVTCHNSTAT_interdomain
u.pirq
- EVTCHNSTAT_pirq
u.virq
- EVTCHNSTAT_virq
Description
EVTCHNOP_status: Get the current status of the communication channel which has an endpoint at <dom, port>.
NOTES
- <dom> may be specified as DOMID_SELF.
- Only a sufficiently-privileged domain may obtain the status of an event channel for which <dom> is not DOMID_SELF.
-
struct
evtchn_bind_vcpu
¶ EVTCHNOP_bind_vcpu
Definition
struct evtchn_bind_vcpu {
evtchn_port_t port;
uint32_t vcpu;
};
Members
port
- IN parameter
vcpu
- IN parameter
Description
Specify which vcpu a channel should notify when an event is pending.
NOTES
- IPI-bound channels always notify the vcpu specified at bind time. This binding cannot be changed.
- Per-VCPU VIRQ channels always notify the vcpu specified at bind time. This binding cannot be changed.
- All other channels notify vcpu0 by default. This default is set when the channel is allocated (a port that is freed and subsequently reused has its binding reset to vcpu0).
-
struct
evtchn_unmask
¶ EVTCHNOP_unmask
Definition
struct evtchn_unmask {
evtchn_port_t port;
};
Members
port
- IN parameter
Description
Unmask the specified local event-channel port and deliver a notification to the appropriate VCPU if an event is pending.
-
struct
evtchn_reset
¶ EVTCHNOP_reset
Definition
struct evtchn_reset {
domid_t dom;
};
Members
dom
- IN parameter
Description
Close all event channels associated with specified domain.
NOTES
- <dom> may be specified as DOMID_SELF.
- Only a sufficiently-privileged domain may specify other than DOMID_SELF.
- Destroys all control blocks and event array, resets event channel operations to 2-level ABI if called with <dom> == DOMID_SELF and FIFO ABI was used. Guests should not bind events during EVTCHNOP_reset call as these events are likely to be lost.
-
struct
evtchn_init_control
¶ EVTCHNOP_init_control
Definition
struct evtchn_init_control {
uint64_t control_gfn;
uint32_t offset;
uint32_t vcpu;
uint8_t link_bits;
uint8_t _pad[7];
};
Members
control_gfn
- IN parameter
offset
- IN parameter
vcpu
- IN parameter
link_bits
- OUT parameter
_pad
- padding
Description
Initialize the control block for the FIFO ABI.
Note
any events that are currently pending will not be resent and will be lost. Guests should call this before binding any event to avoid losing any events.
-
struct
evtchn_expand_array
¶ EVTCHNOP_expand_array
Definition
struct evtchn_expand_array {
uint64_t array_gfn;
};
Members
array_gfn
- IN parameter
Description
Add an additional page to the event array.
-
struct
evtchn_set_priority
¶ EVTCHNOP_set_priority
Definition
struct evtchn_set_priority {
evtchn_port_t port;
uint32_t priority;
};
Members
port
- IN parameter
priority
- IN parameter
Description
Set the priority for an event channel.