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