1 /******************************************************************************
2  * event_channel.h
3  *
4  * Event channels between domains.
5  *
6  * SPDX-License-Identifier: MIT
7  *
8  * Copyright (c) 2003-2004, K A Fraser.
9  */
10 
11 #ifndef __XEN_PUBLIC_EVENT_CHANNEL_H__
12 #define __XEN_PUBLIC_EVENT_CHANNEL_H__
13 
14 #include "xen.h"
15 
16 /*
17  * `incontents 150 evtchn Event Channels
18  *
19  * Event channels are the basic primitive provided by Xen for event
20  * notifications. An event is the Xen equivalent of a hardware
21  * interrupt. They essentially store one bit of information, the event
22  * of interest is signalled by transitioning this bit from 0 to 1.
23  *
24  * Notifications are received by a guest via an upcall from Xen,
25  * indicating when an event arrives (setting the bit). Further
26  * notifications are masked until the bit is cleared again (therefore,
27  * guests must check the value of the bit after re-enabling event
28  * delivery to ensure no missed notifications).
29  *
30  * Event notifications can be masked by setting a flag; this is
31  * equivalent to disabling interrupts and can be used to ensure
32  * atomicity of certain operations in the guest kernel.
33  *
34  * Event channels are represented by the evtchn_* fields in
35  * struct shared_info and struct vcpu_info.
36  */
37 
38 /*
39  * ` enum neg_errnoval
40  * ` HYPERVISOR_event_channel_op(enum event_channel_op cmd, VOID *args)
41  * `
42  * @cmd  == EVTCHNOP_* (event-channel operation).
43  * @args == struct evtchn_* Operation-specific extra arguments (NULL if none).
44  */
45 
46 /* ` enum event_channel_op { // EVTCHNOP_* => struct evtchn_* */
47 #define EVTCHNOP_close            3
48 #define EVTCHNOP_send             4
49 #define EVTCHNOP_alloc_unbound    6
50 /* ` } */
51 
52 typedef UINT32 evtchn_port_t;
53 DEFINE_XEN_GUEST_HANDLE(evtchn_port_t);
54 
55 /*
56  * EVTCHNOP_alloc_unbound: Allocate a port in domain <dom> and mark as
57  * accepting interdomain bindings from domain <remote_dom>. A fresh port
58  * is allocated in <dom> and returned as <port>.
59  * NOTES:
60  *  1. If the caller is unprivileged then <dom> must be DOMID_SELF.
61  *  2. <rdom> may be DOMID_SELF, allowing loopback connections.
62  */
63 struct evtchn_alloc_unbound {
64     /* IN parameters */
65     domid_t dom, remote_dom;
66     /* OUT parameters */
67     evtchn_port_t port;
68 };
69 typedef struct evtchn_alloc_unbound evtchn_alloc_unbound_t;
70 
71 /*
72  * EVTCHNOP_close: Close a local event channel <port>. If the channel is
73  * interdomain then the remote end is placed in the unbound state
74  * (EVTCHNSTAT_unbound), awaiting a new connection.
75  */
76 struct evtchn_close {
77     /* IN parameters. */
78     evtchn_port_t port;
79 };
80 typedef struct evtchn_close evtchn_close_t;
81 
82 /*
83  * EVTCHNOP_send: Send an event to the remote end of the channel whose local
84  * endpoint is <port>.
85  */
86 struct evtchn_send {
87     /* IN parameters. */
88     evtchn_port_t port;
89 };
90 typedef struct evtchn_send evtchn_send_t;
91 
92 #endif /* __XEN_PUBLIC_EVENT_CHANNEL_H__ */
93 
94 /*
95  * Local variables:
96  * mode: C
97  * c-file-style: "BSD"
98  * c-basic-offset: 4
99  * tab-width: 4
100  * indent-tabs-mode: nil
101  * End:
102  */
103