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.