1/**
2 * @file
3 * @section AUTHORS
4 *
5 * Copyright (C) 2010  Rafal Wojtczuk  <rafal@invisiblethingslab.com>
6 *
7 *  Authors:
8 *       Rafal Wojtczuk  <rafal@invisiblethingslab.com>
9 *       Daniel De Graaf <dgdegra@tycho.nsa.gov>
10 *
11 * @section LICENSE
12 *
13 * Permission is hereby granted, free of charge, to any person obtaining a copy
14 * of this software and associated documentation files (the "Software"), to
15 * deal in the Software without restriction, including without limitation the
16 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
17 * sell copies of the Software, and to permit persons to whom the Software is
18 * furnished to do so, subject to the following conditions:
19 *
20 * The above copyright notice and this permission notice shall be included in
21 * all copies or substantial portions of the Software.
22 *
23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29 * DEALINGS IN THE SOFTWARE.
30 *
31 * @section DESCRIPTION
32 *
33 *  Originally borrowed from the Qubes OS Project, http://www.qubes-os.org,
34 *  this code has been substantially rewritten to use the gntdev and gntalloc
35 *  devices instead of raw MFNs and map_foreign_range.
36 *
37 *  This is a library for inter-domain communication.  A standard Xen ring
38 *  buffer is used, with a datagram-based interface built on top.  The grant
39 *  reference and event channels are shared in XenStore under a user-specified
40 *  path.
41 *
42 *  The ring.h macros define an asymmetric interface to a shared data structure
43 *  that assumes all rings reside in a single contiguous memory space. This is
44 *  not suitable for vchan because the interface to the ring is symmetric except
45 *  for the setup. Unlike the producer-consumer rings defined in ring.h, the
46 *  size of the rings used in vchan are determined at execution time instead of
47 *  compile time, so the macros in ring.h cannot be used to access the rings.
48 */
49
50#include <stdint.h>
51#include <sys/types.h>
52
53struct ring_shared {
54	uint32_t cons, prod;
55};
56
57#define VCHAN_NOTIFY_WRITE 0x1
58#define VCHAN_NOTIFY_READ 0x2
59
60/**
61 * vchan_interface: primary shared data structure
62 */
63struct vchan_interface {
64	/**
65	 * Standard consumer/producer interface, one pair per buffer
66	 * left is client write, server read
67	 * right is client read, server write
68	 */
69	struct ring_shared left, right;
70	/**
71	 * size of the rings, which determines their location
72	 * 10   - at offset 1024 in ring's page
73	 * 11   - at offset 2048 in ring's page
74	 * 12+  - uses 2^(N-12) grants to describe the multi-page ring
75	 * These should remain constant once the page is shared.
76	 * Only one of the two orders can be 10 (or 11).
77	 */
78	uint16_t left_order, right_order;
79	/**
80	 * Shutdown detection:
81	 *  0: client (or server) has exited
82	 *  1: client (or server) is connected
83	 *  2: client has not yet connected
84	 */
85	uint8_t cli_live, srv_live;
86	/**
87	 * Notification bits:
88	 *  VCHAN_NOTIFY_WRITE: send notify when data is written
89	 *  VCHAN_NOTIFY_READ: send notify when data is read (consumed)
90	 * cli_notify is used for the client to inform the server of its action
91	 */
92	uint8_t cli_notify, srv_notify;
93	/**
94	 * Grant list: ordering is left, right. Must not extend into actual ring
95	 * or grow beyond the end of the initial shared page.
96	 * These should remain constant once the page is shared, to allow
97	 * for possible remapping by a client that restarts.
98	 */
99	uint32_t grants[0];
100};
101
102