1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
The xenstore ring is a datastructure stored within a single 4KiB page
shared between the xenstore server and the guest. The ring contains
two queues of bytes -- one in each direction -- and some signalling
information. The [xenstore protocol](xenstore.txt) is layered on top of
the byte streams.
The xenstore ring datastructure
===============================
The following table describes the ring structure where
- offsets and lengths are in bytes;
- "Input" is used to describe the data sent to the server; and
- "Output" is used to describe the data sent to the domain.
Offset Length Description
-----------------------------------------------------------------
0 1024 Input data
1024 1024 Output data
2048 4 Input consumer offset
2052 4 Input producer offset
2056 4 Output consumer offset
2060 4 Output producer offset
2064 4 Server feature bitmap
2068 4 Connection state
2072 4 Connection error indicator
The Input data and Output data are circular buffers. Each buffer is
associated with a pair of free-running offsets labelled "consumer" and
"producer".
A "producer" offset is the offset in the byte stream of the next byte
to be written modulo 2^32. A "consumer" offset is the offset in the byte
stream of the next byte to be read modulo 2^32. Implementations must
take care to handle wraparound properly when performing arithmetic with
these values.
The byte at offset 'x' in the byte stream will be stored at offset
'x modulo 1024' in the circular buffer.
Implementations may only overwrite previously-written data if it has
been marked as 'consumed' by the relevant consumer pointer.
When the guest domain is created, there is no outstanding Input or Output
data. However
- guests must not assume that producer or consumer pointers start
at zero; and
- guests must not assume that unused bytes in either the Input or
Output data buffers has any particular value.
A xenstore ring is always associated with an event channel. Whenever the
ring structure is updated the event channel must be signalled. The
guest and server are free to inspect the contents of the ring at any
time, not only in response to an event channel event. This implies that
updates must be ordered carefully to ensure consistency.
The xenstore server may decide to advertise some features via the
"Server feature bitmap". The server can start advertising features
at any time by setting bits but it will never stop advertising features
i.e. bits will never be cleared. The guest is not permitted to write to
the server feature bitmap. The server features are offered to the guest;
it is up to the guest whether to use them or not. The guest should ignore
any unknown feature bits.
The following features are defined (bit number 0 is equivalent to a mask
value of 1):
Bit Description
-----------------------------------------------------------------
0 Ring reconnection (see the ring reconnection feature below)
1 Connection error indicator (see connection error feature below)
2 WATCH can take a third parameter limiting its scope
The "Connection state" field is used to request a ring close and reconnect.
The "Connection state" field only contains valid data if the server has
advertised the ring reconnection feature. If the feature has been advertised
then the "Connection state" may take the following values:
Value Description
-----------------------------------------------------------------
0 Ring is connected
1 Ring close and reconnect is in progress (see the "ring
reconnection feature" described below)
The "Connection error indicator" is used to let the server indicate it has
detected some error that led to deactivation of the connection by the server.
If the feature has been advertised then the "Connection error indicator" may
take the following values (new values might be added in future without them
being advertised as a new feature):
Value Description
-----------------------------------------------------------------
0 No error, connection is valid
1 Communication problems (event channel not functional)
2 Inconsistent producer or consumer offset
3 Protocol violation (client data package too long)
The ring reconnection feature
=============================
The ring reconnection feature allows the guest to ask the server to
reset the ring to a valid initial state i.e. one in which the Input
and Output queues contain no data and there are no outstanding requests,
watches or transactions.
The ring reconnection feature is only available if the 'Ring reconnection'
feature bit has been set by the server in the "Server feature bitmap".
If a server supports ring reconnection, it will guarantee to advertise
the feature before producing or consuming any data from the Input or Output
queues.
Assuming the server has advertised the feature, the guest can initiate
a reconnection by setting the the Connection state to 1 ("Ring close
and reconnect is in progress") and signalling the event channel.
The guest must now ignore all fields except the Connection state and
wait for it to be set to 0 ("Ring is connected").
In certain circumstances (e.g. dom0less guests with PV drivers support)
it is possible for the guest to find the Connection state already set to
1 by someone else during xenstore initialization. In that case, like in
the previous case, the guest must ignore all fields except the
Connection state and wait for it to be set to 0 before proceeding.
The server will guarantee to
- drop any partially read or written higher-level
[xenstore protocol](xenstore.txt) packets it may have;
- empty the Input and Output queues in the xenstore ring;
- discard any in-flight requests
- discard any watches associated with the connection
- discard any transactions associated with the connection
- set the Connection state to 0 ("Ring is connected"); and
- signal the event channel.
From the point of view of the guest, the connection has been reset on a
packet boundary.
Note that only the guest may set the Connection state to 1 and only the
server may set it back to 0.
The connection error feature
============================
The connection error feature allows the server to signal error conditions
leading to a stop of the communication with the client. In case such an error
condition has occurred, the server will set the appropriate error condition in
the Connection error indicator and will stop communication with the client.
Any value different from 0 is indicating an error. The value used is meant
just for diagnostic purposes. A client reading the error value should be
prepared to see values not described here, as new error cases might be added
in future.
The server will discard any already read or written packets, in-flight
requests, watches and transactions associated with the connection.
Depending on the error cause it might be possible that a reconnect via the
ring reconnection feature (if present) can be performed. There is no guarantee
this will succeed.
|
