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

  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
  2. <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

  1. <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

  1. Virtual IRQs are classified as per-vcpu or global. See the VIRQ list in xen.h for the classification of each VIRQ.
  2. Global VIRQs must be allocated on VCPU0 but can subsequently be re-bound via EVTCHNOP_bind_vcpu.
  3. 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

  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.
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

  1. 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

  1. <dom> may be specified as DOMID_SELF.
  2. 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

  1. IPI-bound channels always notify the vcpu specified at bind time. This binding cannot be changed.
  2. Per-VCPU VIRQ channels always notify the vcpu specified at bind time. This binding cannot be changed.
  3. 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

  1. <dom> may be specified as DOMID_SELF.
  2. Only a sufficiently-privileged domain may specify other than DOMID_SELF.
  3. 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.