tools/xenstore: add migration stream extensions for new features

Extend the definition of the Xenstore migration stream to cover new
features:

- per domain features
- extended watches (watch depth)
- per domain quota

Some of those additions (per domain features and extended watches)
require bumping the migration stream version to "2", as usage of those
features will require to transport mandatory new information in the
migration stream.

One note regarding the GLOBAL_QUOTA_DATA record: the split of quota
between global and per-domain ones is meant to support the possibility
to pass on unknown quota settings for newly created domains to other
Xenstore instances:

Imagine Xenstore A knows about global quota g and domain quota d, while
Xenstore B doesn't know both. Initially I'm running Xenstore A on a
host, then I'm live-updating to B.

B gets the information that g is global, and d is per-domain, but has
no other idea what to do with the values of g and d. OTOH it knows that
each new domain should get d with the related value, so it can set d
for each newly created domain.

When B is either downgraded to A again, or a domain is migrated to
another host running A, B can add the quota information of d for all
domains.

Signed-off-by: Juergen Gross <jgross@suse.com>
Reviewed-by: Julien Grall <jgrall@amazon.com>

diff --git a/docs/designs/xenstore-migration.md b/docs/designs/xenstore-migration.md
index efa526f420a03bdc76f0786c730c7ab303e52770..5022268386cb17a6f25f1c781038e68a2273e532 100644 (file)
--- a/docs/designs/xenstore-migration.md
+++ b/docs/designs/xenstore-migration.md
@@ -43,7 +43,14 @@ the setting of the endianness bit.
 |-----------|---------------------------------------------------|
 | `ident`   | 0x78656e73746f7265 ('xenstore' in ASCII)          |
 |           |                                                   |
-| `version` | 0x00000001 (the version of the specification)     |
+| `version` | The version of the specification, defined values: |
+|           | 0x00000001: all fields and records without any    |
+|           |             explicitly mentioned version          |
+|           |             dependency are valid.                 |
+|           | 0x00000002: all fields and records valid for      |
+|           |             version 1 plus fields and records     |
+|           |             explicitly stated to be supported in  |
+|           |             version 2 are valid.                  |
 |           |                                                   |
 | `flags`   | 0 (LSB): Endianness: 0 = little, 1 = big          |
 |           |                                                   |
@@ -65,8 +72,9 @@ Records immediately follow the header and have the following format:
 +-------+-------------------------------------------------------+
 ```
 
-NOTE: padding octets here and in all subsequent format specifications must be
-      written as zero and should be ignored when the stream is read.
+NOTE: padding octets or fields not valid in the used version here and in all
+      subsequent format specifications must be written as zero and should be
+      ignored when the stream is read.
 
 
 | Field  | Description                                          |
@@ -77,7 +85,10 @@ NOTE: padding octets here and in all subsequent format specifications must be
 |        | 0x00000003: WATCH_DATA                               |
 |        | 0x00000004: TRANSACTION_DATA                         |
 |        | 0x00000005: NODE_DATA                                |
-|        | 0x00000006 - 0xFFFFFFFF: reserved for future use     |
+|        | 0x00000006: GLOBAL_QUOTA_DATA                        |
+|        | 0x00000007: DOMAIN_DATA                              |
+|        | 0x00000008: WATCH_DATA_EXTENDED (version 2 and up)   |
+|        | 0x00000009 - 0xFFFFFFFF: reserved for future use     |
 |        |                                                      |
 | `len`  | The length (in octets) of `body`                     |
 |        |                                                      |
@@ -241,9 +252,49 @@ the file descriptor of the socket connection.
 
 ### WATCH_DATA
 
-The image format will contain a `WATCH_DATA` record for each watch registered
-by a connection for which there is `CONNECTION_DATA` record previously present.
+The image format will contain either a `WATCH_DATA` or a `WATCH_DATA_EXTENDED`
+record for each watch registered by a connection for which there is
+`CONNECTION_DATA` record previously present.
 
+```
+    0       1       2       3    octet
++-------+-------+-------+-------+
+| conn-id                       |
++---------------+---------------+
+| wpath-len     | token-len     |
++---------------+---------------+
+| wpath
+...
+| token
+...
+```
+
+
+| Field       | Description                                     |
+|-------------|-------------------------------------------------|
+| `conn-id`   | The connection that issued the `WATCH`          |
+|             | operation [2]                                   |
+|             |                                                 |
+| `wpath-len` | The length (in octets) of `wpath` including the |
+|             | NUL terminator                                  |
+|             |                                                 |
+| `token-len` | The length (in octets) of `token` including the |
+|             | NUL terminator                                  |
+|             |                                                 |
+| `wpath`     | The watch path, as specified in the `WATCH`     |
+|             | operation                                       |
+|             |                                                 |
+| `token`     | The watch identifier token, as specified in the |
+|             | `WATCH` operation                               |
+
+\pagebreak
+
+### WATCH_DATA_EXTENDED
+
+The image format will contain either a `WATCH_DATA` or a `WATCH_DATA_EXTENDED`
+record for each watch registered by a connection for which there is
+`CONNECTION_DATA` record previously present. The `WATCH_DATA_EXTENDED` record
+type is valid only in version 2 and later.
 
 ```
     0       1       2       3    octet
@@ -252,6 +303,8 @@ by a connection for which there is `CONNECTION_DATA` record previously present.
 +---------------+---------------+
 | wpath-len     | token-len     |
 +---------------+---------------+
+| depth         | pad           |
++---------------+---------------+
 | wpath
 ...
 | token
@@ -270,6 +323,10 @@ by a connection for which there is `CONNECTION_DATA` record previously present.
 | `token-len` | The length (in octets) of `token` including the |
 |             | NUL terminator                                  |
 |             |                                                 |
+| `depth`     | The number of directory levels below the        |
+|             | watched path to consider for a match.           |
+|             | A value of 0xffff is used for unlimited depth.  |
+|             |                                                 |
 | `wpath`     | The watch path, as specified in the `WATCH`     |
 |             | operation                                       |
 |             |                                                 |
@@ -406,6 +463,102 @@ A node permission specifier has the following format:
 Note that perm1 defines the domain owning the node. See [4] for more
 explanation of node permissions.
 
+\pagebreak
+
+### GLOBAL_QUOTA_DATA
+
+This record is only relevant for live update. It contains the global settings
+of xenstored quota.
+
+```
+    0       1       2       3    octet
++-------+-------+-------+-------+
+| n-dom-quota   | n-glob-quota  |
++---------------+---------------+
+| quota-val 1                   |
++-------------------------------+
+...
++-------------------------------+
+| quota-val N                   |
++-------------------------------+
+| quota-names
+...
+```
+
+
+| Field          | Description                                  |
+|----------------|----------------------------------------------|
+| `n-dom-quota`  | Number of quota values which apply per       |
+|                | domain by default.                                      |
+|                |                                              |
+| `n-glob-quota` | Number of quota values which apply globally  |
+|                | only.                                        |
+|                |                                              |
+| `quota-val`    | Quota values, first the ones applying per    |
+|                | domain, then the ones applying globally. A   |
+|                | value of 0 has the semantics of "unlimited". |
+|                |                                              |
+| `quota-names`  | 0 delimited strings of the quota names in    |
+|                | the same sequence as the `quota-val` values. |
+
+
+Allowed quota names are those explicitly named in [2] for the `GET_QUOTA`
+and `SET_QUOTA` commands, plus implementation specific ones. Quota names not
+recognized by the receiving side should not have any effect on behavior for
+the receiving side (they can be ignored or preserved for inclusion in
+future live migration/update streams).
+
+\pagebreak
+
+### DOMAIN_DATA
+
+This record is optional and can be present once for each domain.
+
+
+```
+    0       1       2       3     octet
++-------+-------+-------+-------+
+| domain-id     | n-quota       |
++---------------+---------------+
+| features                      |
++-------------------------------+
+| quota-val 1                   |
++-------------------------------+
+...
++-------------------------------+
+| quota-val N                   |
++-------------------------------+
+| quota-names
+...
+```
+
+
+| Field          | Description                                  |
+|----------------|----------------------------------------------|
+| `domain-id`    | The domain-id of the domain this record      |
+|                | belongs to.                                  |
+|                |                                              |
+| `n-quota`      | Number of quota values.                      |
+|                |                                              |
+| `features`     | Value of the feature field visible by the    |
+|                | guest at offset 2064 of the ring page.       |
+|                | Only valid for version 2 and later.          |
+|                |                                              |
+| `quota-val`    | Quota values, a value of 0 has the semantics |
+|                | "unlimited".                                 |
+|                |                                              |
+| `quota-names`  | 0 delimited strings of the quota names in    |
+|                | the same sequence as the `quota-val` values. |
+
+Allowed quota names are those explicitly named in [2] for the `GET_QUOTA`
+and `SET_QUOTA` commands, plus implementation specific ones. Quota names not
+recognized by the receiving side should not have any effect on behavior for
+the receiving side (they can be ignored or preserved for inclusion in
+future live migration/update streams).
+
+\pagebreak
+
+
 * * *
 
 [1] See https://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=docs/designs/non-cooperative-migration.md