event_channel.h revision 255040
1181624Skmacy/****************************************************************************** 2181624Skmacy * event_channel.h 3251767Sgibbs * 4181624Skmacy * Event channels between domains. 5251767Sgibbs * 6181624Skmacy * Permission is hereby granted, free of charge, to any person obtaining a copy 7181624Skmacy * of this software and associated documentation files (the "Software"), to 8181624Skmacy * deal in the Software without restriction, including without limitation the 9181624Skmacy * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10181624Skmacy * sell copies of the Software, and to permit persons to whom the Software is 11181624Skmacy * furnished to do so, subject to the following conditions: 12181624Skmacy * 13181624Skmacy * The above copyright notice and this permission notice shall be included in 14181624Skmacy * all copies or substantial portions of the Software. 15181624Skmacy * 16181624Skmacy * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17181624Skmacy * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18181624Skmacy * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19181624Skmacy * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20181624Skmacy * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21181624Skmacy * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 22181624Skmacy * DEALINGS IN THE SOFTWARE. 23181624Skmacy * 24181624Skmacy * Copyright (c) 2003-2004, K A Fraser. 25181624Skmacy */ 26181624Skmacy 27181624Skmacy#ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__ 28181624Skmacy#define __XEN_PUBLIC_EVENT_CHANNEL_H__ 29181624Skmacy 30251767Sgibbs#include "xen.h" 31251767Sgibbs 32181624Skmacy/* 33251767Sgibbs * `incontents 150 evtchn Event Channels 34251767Sgibbs * 35251767Sgibbs * Event channels are the basic primitive provided by Xen for event 36251767Sgibbs * notifications. An event is the Xen equivalent of a hardware 37251767Sgibbs * interrupt. They essentially store one bit of information, the event 38251767Sgibbs * of interest is signalled by transitioning this bit from 0 to 1. 39251767Sgibbs * 40251767Sgibbs * Notifications are received by a guest via an upcall from Xen, 41251767Sgibbs * indicating when an event arrives (setting the bit). Further 42251767Sgibbs * notifications are masked until the bit is cleared again (therefore, 43251767Sgibbs * guests must check the value of the bit after re-enabling event 44251767Sgibbs * delivery to ensure no missed notifications). 45251767Sgibbs * 46251767Sgibbs * Event notifications can be masked by setting a flag; this is 47251767Sgibbs * equivalent to disabling interrupts and can be used to ensure 48251767Sgibbs * atomicity of certain operations in the guest kernel. 49251767Sgibbs * 50251767Sgibbs * Event channels are represented by the evtchn_* fields in 51251767Sgibbs * struct shared_info and struct vcpu_info. 52181624Skmacy */ 53181624Skmacy 54251767Sgibbs/* 55251767Sgibbs * ` enum neg_errnoval 56251767Sgibbs * ` HYPERVISOR_event_channel_op(enum event_channel_op cmd, void *args) 57251767Sgibbs * ` 58251767Sgibbs * @cmd == EVTCHNOP_* (event-channel operation). 59251767Sgibbs * @args == struct evtchn_* Operation-specific extra arguments (NULL if none). 60251767Sgibbs */ 61251767Sgibbs 62251767Sgibbs/* ` enum event_channel_op { // EVTCHNOP_* => struct evtchn_* */ 63251767Sgibbs#define EVTCHNOP_bind_interdomain 0 64251767Sgibbs#define EVTCHNOP_bind_virq 1 65251767Sgibbs#define EVTCHNOP_bind_pirq 2 66251767Sgibbs#define EVTCHNOP_close 3 67251767Sgibbs#define EVTCHNOP_send 4 68251767Sgibbs#define EVTCHNOP_status 5 69251767Sgibbs#define EVTCHNOP_alloc_unbound 6 70251767Sgibbs#define EVTCHNOP_bind_ipi 7 71251767Sgibbs#define EVTCHNOP_bind_vcpu 8 72251767Sgibbs#define EVTCHNOP_unmask 9 73251767Sgibbs#define EVTCHNOP_reset 10 74251767Sgibbs/* ` } */ 75251767Sgibbs 76255040Sgibbs#ifndef __XEN_EVTCHN_PORT_DEFINED__ 77181624Skmacytypedef uint32_t evtchn_port_t; 78181624SkmacyDEFINE_XEN_GUEST_HANDLE(evtchn_port_t); 79255040Sgibbs#define __XEN_EVTCHN_PORT_DEFINED__ 1 80255040Sgibbs#endif 81181624Skmacy 82181624Skmacy/* 83181624Skmacy * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as 84181624Skmacy * accepting interdomain bindings from domain <remote_dom>. A fresh port 85181624Skmacy * is allocated in <dom> and returned as <port>. 86181624Skmacy * NOTES: 87181624Skmacy * 1. If the caller is unprivileged then <dom> must be DOMID_SELF. 88181624Skmacy * 2. <rdom> may be DOMID_SELF, allowing loopback connections. 89181624Skmacy */ 90181624Skmacystruct evtchn_alloc_unbound { 91181624Skmacy /* IN parameters */ 92181624Skmacy domid_t dom, remote_dom; 93181624Skmacy /* OUT parameters */ 94181624Skmacy evtchn_port_t port; 95181624Skmacy}; 96181624Skmacytypedef struct evtchn_alloc_unbound evtchn_alloc_unbound_t; 97181624Skmacy 98181624Skmacy/* 99181624Skmacy * EVTCHNOP_bind_interdomain: Construct an interdomain event channel between 100181624Skmacy * the calling domain and <remote_dom>. <remote_dom,remote_port> must identify 101181624Skmacy * a port that is unbound and marked as accepting bindings from the calling 102181624Skmacy * domain. A fresh port is allocated in the calling domain and returned as 103181624Skmacy * <local_port>. 104181624Skmacy * NOTES: 105251767Sgibbs * 1. <remote_dom> may be DOMID_SELF, allowing loopback connections. 106181624Skmacy */ 107181624Skmacystruct evtchn_bind_interdomain { 108181624Skmacy /* IN parameters. */ 109181624Skmacy domid_t remote_dom; 110181624Skmacy evtchn_port_t remote_port; 111181624Skmacy /* OUT parameters. */ 112181624Skmacy evtchn_port_t local_port; 113181624Skmacy}; 114181624Skmacytypedef struct evtchn_bind_interdomain evtchn_bind_interdomain_t; 115181624Skmacy 116181624Skmacy/* 117181624Skmacy * EVTCHNOP_bind_virq: Bind a local event channel to VIRQ <irq> on specified 118181624Skmacy * vcpu. 119181624Skmacy * NOTES: 120181624Skmacy * 1. Virtual IRQs are classified as per-vcpu or global. See the VIRQ list 121181624Skmacy * in xen.h for the classification of each VIRQ. 122181624Skmacy * 2. Global VIRQs must be allocated on VCPU0 but can subsequently be 123181624Skmacy * re-bound via EVTCHNOP_bind_vcpu. 124181624Skmacy * 3. Per-vcpu VIRQs may be bound to at most one event channel per vcpu. 125181624Skmacy * The allocated event channel is bound to the specified vcpu and the 126181624Skmacy * binding cannot be changed. 127181624Skmacy */ 128181624Skmacystruct evtchn_bind_virq { 129181624Skmacy /* IN parameters. */ 130251767Sgibbs uint32_t virq; /* enum virq */ 131181624Skmacy uint32_t vcpu; 132181624Skmacy /* OUT parameters. */ 133181624Skmacy evtchn_port_t port; 134181624Skmacy}; 135181624Skmacytypedef struct evtchn_bind_virq evtchn_bind_virq_t; 136181624Skmacy 137181624Skmacy/* 138251767Sgibbs * EVTCHNOP_bind_pirq: Bind a local event channel to a real IRQ (PIRQ <irq>). 139181624Skmacy * NOTES: 140181624Skmacy * 1. A physical IRQ may be bound to at most one event channel per domain. 141181624Skmacy * 2. Only a sufficiently-privileged domain may bind to a physical IRQ. 142181624Skmacy */ 143181624Skmacystruct evtchn_bind_pirq { 144181624Skmacy /* IN parameters. */ 145181624Skmacy uint32_t pirq; 146181624Skmacy#define BIND_PIRQ__WILL_SHARE 1 147181624Skmacy uint32_t flags; /* BIND_PIRQ__* */ 148181624Skmacy /* OUT parameters. */ 149181624Skmacy evtchn_port_t port; 150181624Skmacy}; 151181624Skmacytypedef struct evtchn_bind_pirq evtchn_bind_pirq_t; 152181624Skmacy 153181624Skmacy/* 154181624Skmacy * EVTCHNOP_bind_ipi: Bind a local event channel to receive events. 155181624Skmacy * NOTES: 156181624Skmacy * 1. The allocated event channel is bound to the specified vcpu. The binding 157181624Skmacy * may not be changed. 158181624Skmacy */ 159181624Skmacystruct evtchn_bind_ipi { 160181624Skmacy uint32_t vcpu; 161181624Skmacy /* OUT parameters. */ 162181624Skmacy evtchn_port_t port; 163181624Skmacy}; 164181624Skmacytypedef struct evtchn_bind_ipi evtchn_bind_ipi_t; 165181624Skmacy 166181624Skmacy/* 167181624Skmacy * EVTCHNOP_close: Close a local event channel <port>. If the channel is 168181624Skmacy * interdomain then the remote end is placed in the unbound state 169181624Skmacy * (EVTCHNSTAT_unbound), awaiting a new connection. 170181624Skmacy */ 171181624Skmacystruct evtchn_close { 172181624Skmacy /* IN parameters. */ 173181624Skmacy evtchn_port_t port; 174181624Skmacy}; 175181624Skmacytypedef struct evtchn_close evtchn_close_t; 176181624Skmacy 177181624Skmacy/* 178181624Skmacy * EVTCHNOP_send: Send an event to the remote end of the channel whose local 179181624Skmacy * endpoint is <port>. 180181624Skmacy */ 181181624Skmacystruct evtchn_send { 182181624Skmacy /* IN parameters. */ 183181624Skmacy evtchn_port_t port; 184181624Skmacy}; 185181624Skmacytypedef struct evtchn_send evtchn_send_t; 186181624Skmacy 187181624Skmacy/* 188181624Skmacy * EVTCHNOP_status: Get the current status of the communication channel which 189181624Skmacy * has an endpoint at <dom, port>. 190181624Skmacy * NOTES: 191181624Skmacy * 1. <dom> may be specified as DOMID_SELF. 192181624Skmacy * 2. Only a sufficiently-privileged domain may obtain the status of an event 193181624Skmacy * channel for which <dom> is not DOMID_SELF. 194181624Skmacy */ 195181624Skmacystruct evtchn_status { 196181624Skmacy /* IN parameters */ 197181624Skmacy domid_t dom; 198181624Skmacy evtchn_port_t port; 199181624Skmacy /* OUT parameters */ 200181624Skmacy#define EVTCHNSTAT_closed 0 /* Channel is not in use. */ 201181624Skmacy#define EVTCHNSTAT_unbound 1 /* Channel is waiting interdom connection.*/ 202181624Skmacy#define EVTCHNSTAT_interdomain 2 /* Channel is connected to remote domain. */ 203181624Skmacy#define EVTCHNSTAT_pirq 3 /* Channel is bound to a phys IRQ line. */ 204181624Skmacy#define EVTCHNSTAT_virq 4 /* Channel is bound to a virtual IRQ line */ 205181624Skmacy#define EVTCHNSTAT_ipi 5 /* Channel is bound to a virtual IPI line */ 206181624Skmacy uint32_t status; 207181624Skmacy uint32_t vcpu; /* VCPU to which this channel is bound. */ 208181624Skmacy union { 209181624Skmacy struct { 210181624Skmacy domid_t dom; 211251767Sgibbs } unbound; /* EVTCHNSTAT_unbound */ 212181624Skmacy struct { 213181624Skmacy domid_t dom; 214181624Skmacy evtchn_port_t port; 215251767Sgibbs } interdomain; /* EVTCHNSTAT_interdomain */ 216251767Sgibbs uint32_t pirq; /* EVTCHNSTAT_pirq */ 217251767Sgibbs uint32_t virq; /* EVTCHNSTAT_virq */ 218181624Skmacy } u; 219181624Skmacy}; 220181624Skmacytypedef struct evtchn_status evtchn_status_t; 221181624Skmacy 222181624Skmacy/* 223181624Skmacy * EVTCHNOP_bind_vcpu: Specify which vcpu a channel should notify when an 224181624Skmacy * event is pending. 225181624Skmacy * NOTES: 226181624Skmacy * 1. IPI-bound channels always notify the vcpu specified at bind time. 227181624Skmacy * This binding cannot be changed. 228181624Skmacy * 2. Per-VCPU VIRQ channels always notify the vcpu specified at bind time. 229181624Skmacy * This binding cannot be changed. 230181624Skmacy * 3. All other channels notify vcpu0 by default. This default is set when 231181624Skmacy * the channel is allocated (a port that is freed and subsequently reused 232181624Skmacy * has its binding reset to vcpu0). 233181624Skmacy */ 234181624Skmacystruct evtchn_bind_vcpu { 235181624Skmacy /* IN parameters. */ 236181624Skmacy evtchn_port_t port; 237181624Skmacy uint32_t vcpu; 238181624Skmacy}; 239181624Skmacytypedef struct evtchn_bind_vcpu evtchn_bind_vcpu_t; 240181624Skmacy 241181624Skmacy/* 242181624Skmacy * EVTCHNOP_unmask: Unmask the specified local event-channel port and deliver 243181624Skmacy * a notification to the appropriate VCPU if an event is pending. 244181624Skmacy */ 245181624Skmacystruct evtchn_unmask { 246181624Skmacy /* IN parameters. */ 247181624Skmacy evtchn_port_t port; 248181624Skmacy}; 249181624Skmacytypedef struct evtchn_unmask evtchn_unmask_t; 250181624Skmacy 251181624Skmacy/* 252181624Skmacy * EVTCHNOP_reset: Close all event channels associated with specified domain. 253181624Skmacy * NOTES: 254181624Skmacy * 1. <dom> may be specified as DOMID_SELF. 255181624Skmacy * 2. Only a sufficiently-privileged domain may specify other than DOMID_SELF. 256181624Skmacy */ 257181624Skmacystruct evtchn_reset { 258181624Skmacy /* IN parameters. */ 259181624Skmacy domid_t dom; 260181624Skmacy}; 261181624Skmacytypedef struct evtchn_reset evtchn_reset_t; 262181624Skmacy 263181624Skmacy/* 264251767Sgibbs * ` enum neg_errnoval 265251767Sgibbs * ` HYPERVISOR_event_channel_op_compat(struct evtchn_op *op) 266251767Sgibbs * ` 267251767Sgibbs * Superceded by new event_channel_op() hypercall since 0x00030202. 268181624Skmacy */ 269181624Skmacystruct evtchn_op { 270251767Sgibbs uint32_t cmd; /* enum event_channel_op */ 271181624Skmacy union { 272181624Skmacy struct evtchn_alloc_unbound alloc_unbound; 273181624Skmacy struct evtchn_bind_interdomain bind_interdomain; 274181624Skmacy struct evtchn_bind_virq bind_virq; 275181624Skmacy struct evtchn_bind_pirq bind_pirq; 276181624Skmacy struct evtchn_bind_ipi bind_ipi; 277181624Skmacy struct evtchn_close close; 278181624Skmacy struct evtchn_send send; 279181624Skmacy struct evtchn_status status; 280181624Skmacy struct evtchn_bind_vcpu bind_vcpu; 281181624Skmacy struct evtchn_unmask unmask; 282181624Skmacy } u; 283181624Skmacy}; 284181624Skmacytypedef struct evtchn_op evtchn_op_t; 285181624SkmacyDEFINE_XEN_GUEST_HANDLE(evtchn_op_t); 286181624Skmacy 287181624Skmacy#endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */ 288181624Skmacy 289181624Skmacy/* 290181624Skmacy * Local variables: 291181624Skmacy * mode: C 292181624Skmacy * c-set-style: "BSD" 293181624Skmacy * c-basic-offset: 4 294181624Skmacy * tab-width: 4 295181624Skmacy * indent-tabs-mode: nil 296181624Skmacy * End: 297181624Skmacy */ 298