<no title>

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.