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 *  This library is free software; you can redistribute it and/or
14 *  modify it under the terms of the GNU Lesser General Public
15 *  License as published by the Free Software Foundation; either
16 *  version 2.1 of the License, or (at your option) any later version.
17 *
18 *  This library is distributed in the hope that it will be useful,
19 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
20 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21 *  Lesser General Public License for more details.
22 *
23 *  You should have received a copy of the GNU Lesser General Public
24 *  License along with this library; If not, see <http://www.gnu.org/licenses/>.
25 *
26 * @section DESCRIPTION
27 *
28 *  Originally borrowed from the Qubes OS Project, http://www.qubes-os.org,
29 *  this code has been substantially rewritten to use the gntdev and gntalloc
30 *  devices instead of raw MFNs and map_foreign_range.
31 *
32 *  This is a library for inter-domain communication.  A standard Xen ring
33 *  buffer is used, with a datagram-based interface built on top.  The grant
34 *  reference and event channels are shared in XenStore under a user-specified
35 *  path.
36 *
37 *  The ring.h macros define an asymmetric interface to a shared data structure
38 *  that assumes all rings reside in a single contiguous memory space. This is
39 *  not suitable for vchan because the interface to the ring is symmetric except
40 *  for the setup. Unlike the producer-consumer rings defined in ring.h, the
41 *  size of the rings used in vchan are determined at execution time instead of
42 *  compile time, so the macros in ring.h cannot be used to access the rings.
43 */
44
45#include <stdint.h>
46#include <sys/types.h>
47
48struct ring_shared {
49	uint32_t cons, prod;
50};
51
52#define VCHAN_NOTIFY_WRITE 0x1
53#define VCHAN_NOTIFY_READ 0x2
54
55/**
56 * vchan_interface: primary shared data structure
57 */
58struct vchan_interface {
59	/**
60	 * Standard consumer/producer interface, one pair per buffer
61	 * left is client write, server read
62	 * right is client read, server write
63	 */
64	struct ring_shared left, right;
65	/**
66	 * size of the rings, which determines their location
67	 * 10   - at offset 1024 in ring's page
68	 * 11   - at offset 2048 in ring's page
69	 * 12+  - uses 2^(N-12) grants to describe the multi-page ring
70	 * These should remain constant once the page is shared.
71	 * Only one of the two orders can be 10 (or 11).
72	 */
73	uint16_t left_order, right_order;
74	/**
75	 * Shutdown detection:
76	 *  0: client (or server) has exited
77	 *  1: client (or server) is connected
78	 *  2: client has not yet connected
79	 */
80	uint8_t cli_live, srv_live;
81	/**
82	 * Notification bits:
83	 *  VCHAN_NOTIFY_WRITE: send notify when data is written
84	 *  VCHAN_NOTIFY_READ: send notify when data is read (consumed)
85	 * cli_notify is used for the client to inform the server of its action
86	 */
87	uint8_t cli_notify, srv_notify;
88	/**
89	 * Grant list: ordering is left, right. Must not extend into actual ring
90	 * or grow beyond the end of the initial shared page.
91	 * These should remain constant once the page is shared, to allow
92	 * for possible remapping by a client that restarts.
93	 */
94	uint32_t grants[0];
95};
96
97