mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 02:01:24 +01:00
Juergen Gross
3a2feae17e
Add documentation for an extension of the WATCH command used to limit the scope of watched paths. Additionally it enables to receive more information in the events related to special watches (@introduceDomain or @releaseDomain). Signed-off-by: Juergen Gross <jgross@suse.com> Reviewed-by: Julien Grall <jgrall@amazon.com>
160 lines
6.9 KiB
Plaintext
160 lines
6.9 KiB
Plaintext
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.
|