1The xenstore ring is a datastructure stored within a single 4KiB page
2shared between the xenstore server and the guest. The ring contains
3two queues of bytes -- one in each direction -- and some signalling
4information. The [xenstore protocol](xenstore.txt) is layered on top of
5the byte streams.
6
7The xenstore ring datastructure
8===============================
9
10The following table describes the ring structure where
11  - offsets and lengths are in bytes;
12  - "Input" is used to describe the data sent to the server; and
13  - "Output" is used to describe the data sent to the domain.
14
15Offset  Length  Description
16-----------------------------------------------------------------
170       1024    Input data
181024    1024    Output data
192048    4       Input consumer offset
202052    4       Input producer offset
212056    4       Output consumer offset
222060    4       Output producer offset
232064    4       Server feature bitmap
242068    4       Connection state
25
26The Input data and Output data are circular buffers. Each buffer is
27associated with a pair of free-running offsets labelled "consumer" and
28"producer".
29
30A "producer" offset is the offset in the byte stream of the next byte
31to be written modulo 2^32. A "consumer" offset is the offset in the byte
32stream of the next byte to be read modulo 2^32. Implementations must
33take care to handle wraparound properly when performing arithmetic with
34these values.
35
36The byte at offset 'x' in the byte stream will be stored at offset
37'x modulo 1024' in the circular buffer.
38
39Implementations may only overwrite previously-written data if it has
40been marked as 'consumed' by the relevant consumer pointer.
41
42When the guest domain is created, there is no outstanding Input or Output
43data. However
44
45  - guests must not assume that producer or consumer pointers start
46    at zero; and
47  - guests must not assume that unused bytes in either the Input or
48    Output data buffers has any particular value.
49
50A xenstore ring is always associated with an event channel. Whenever the
51ring structure is updated the event channel must be signalled. The
52guest and server are free to inspect the contents of the ring at any
53time, not only in response to an event channel event. This implies that
54updates must be ordered carefully to ensure consistency.
55
56The xenstore server may decide to advertise some features via the
57"Server feature bitmap". The server can start advertising features
58at any time by setting bits but it will never stop advertising features
59i.e. bits will never be cleared. The guest is not permitted to write to
60the server feature bitmap. The server features are offered to the guest;
61it is up to the guest whether to use them or not. The guest should ignore
62any unknown feature bits.
63
64The following features are defined:
65
66Mask    Description
67-----------------------------------------------------------------
681       Ring reconnection (see the ring reconnection feature below)
69
70The "Connection state" field is used to request a ring close and reconnect.
71The "Connection state" field only contains valid data if the server has
72advertised the ring reconnection feature. If the feature has been advertised
73then the "Connection state" may take the following values:
74
75Value   Description
76-----------------------------------------------------------------
770       Ring is connected
781       Ring close and reconnect is in progress (see the "ring
79        reconnection feature" described below)
80
81The ring reconnection feature
82=============================
83
84The ring reconnection feature allows the guest to ask the server to
85reset the ring to a valid initial state i.e. one in which the Input
86and Output queues contain no data and there are no outstanding requests,
87watches or transactions.
88
89The ring reconnection feature is only available if the 'Ring reconnection'
90feature bit has been set by the server in the "Server feature bitmap".
91If a server supports ring reconnection, it will guarantee to advertise
92the feature before producing or consuming any data from the Input or Output
93queues.
94
95Assuming the server has advertised the feature, the guest can initiate
96a reconnection by setting the the Connection state to 1 ("Ring close
97and reconnect is in progress") and signalling the event channel.
98The guest must now ignore all fields except the Connection state and
99wait for it to be set to 0 ("Ring is connected")
100
101The server will guarantee to
102
103  - drop any partially read or written higher-level
104    [xenstore protocol](xenstore.txt) packets it may have;
105  - empty the Input and Output queues in the xenstore ring;
106  - discard any in-flight requests
107  - discard any watches associated with the connection
108  - discard any transactions associated with the connection
109  - set the Connection state to 0 ("Ring is connected"); and
110  - signal the event channel.
111
112From the point of view of the guest, the connection has been reset on a
113packet boundary.
114
115Note that only the guest may set the Connection state to 1 and only the
116server may set it back to 0.
117