docs: update xenstore-migration.md
PATCH v3 1/1 docs: update xenstore-migration.md
Update connection record details:
- make flags common for sockets and domains (makes it easier to have a C union for conn-spec)
- add pending incoming data (needed for handling partially read requests when doing live update)
- add partial response length (needed for proper split to individual responses after live update)
---
V2:
- added out-resp-len to connection record
V3:
- better commit message (Julien Grall)
- same sequence for fields and detailed descriptions (Julien Grall)
- some wording corrected (Paul Durrant)
--- docs/designs/xenstore-migration.md | 72 +++++++++++++++++------------- 1 file changed, 41 insertions(+), 31 deletions(-)
docs/designs/xenstore-migration.md +41 -31
@@ -147,43 +147,60 @@ the domain being migrated. ``` 0 1 2 3 4 5 6 7 octet +-------+-------+-------+-------+-------+-------+-------+-------+ -| conn-id | conn-type | conn-spec +| conn-id | conn-type | flags | ++-------------------------------+---------------+---------------+ +| conn-spec ... -+-------------------------------+-------------------------------+ -| data-len | data -+-------------------------------+ ++---------------+---------------+-------------------------------+ +| in-data-len | out-resp-len | out-data-len | ++---------------+---------------+-------------------------------+ +| data ... ``` -| Field | Description | -|-------------|-------------------------------------------------| -| `conn-id` | A non-zero number used to identify this | -| | connection in subsequent connection-specific | -| | records | -| | | -| `conn-type` | 0x0000: shared ring | -| | 0x0001: socket | -| | 0x0002 - 0xFFFF: reserved for future use | -| | | -| `conn-spec` | See below | -| | | -| `data-len` | The length (in octets) of any pending data not | -| | yet written to the connection | -| | | -| `data` | Pending data (may be empty) | +| Field | Description | +|----------------|----------------------------------------------| +| `conn-id` | A non-zero number used to identify this | +| | connection in subsequent connection-specific | +| | records | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only | +| | | +| `conn-spec` | See below | +| | | +| `in-data-len` | The length (in octets) of any data read | +| | from the connection not yet processed | +| | | +| `out-resp-len` | The length (in octets) of a partial response | +| | not yet written to the connection | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection, including | +| | a partial response (see `out-resp-len`) | +| | | +| `data` | Pending data: first in-data-len octets of | +| | read data, then out-data-len octets of | +| | written data (any of both may be empty) | -The format of `conn-spec` is dependent upon `conn-type`. +In case of live update the connection record for the connection via which +the live update command was issued will contain the response for the live +update command in the pending not yet written data. \pagebreak +The format of `conn-spec` is dependent upon `conn-type`. + For `shared ring` connections it is as follows: ``` 0 1 2 3 4 5 6 7 octet - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | domid | tdomid | evtchn | +-------------------------------+-------------------------------+
@@ -198,8 +215,6 @@ For `shared ring` connections it is as follows: | | it has been subject to an SET_TARGET | | | operation [2] or DOMID_INVALID [3] otherwise | | | | -| `flags` | Must be zero | -| | | | `evtchn` | The port number of the interdomain channel used | | | by `domid` to communicate with xenstored | | | |
@@ -211,8 +226,6 @@ For `socket` connections it is as follows: ``` - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | socket-fd | pad | +-------------------------------+-------------------------------+
@@ -221,9 +234,6 @@ For `socket` connections it is as follows: | Field | Description | |-------------|-------------------------------------------------| -| `flags` | A bit-wise OR of: | -| | 0001: read-only | -| | | | `socket-fd` | The file descriptor of the connected socket | This type of connection is only relevant for live update, where the xenstored
@@ -398,4 +408,4 @@ explanation of node permissions. [3] See https://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/xen.h;hb=HEAD#l612 -[4] https://wiki.xen.org/wiki/XenBus +[4] https://wiki.xen.org/wiki/XenBus
Signature · 1 line
2.26.2
Quoted 11 lines
-----Original Message-----
From: Xen-devel <[email protected]> On Behalf Of Juergen Gross
Sent: 29 May 2020 12:37
To: [email protected]
Cc: Juergen Gross <[email protected]>; Stefano Stabellini <[email protected]>; Julien Grall <[email protected]>; Wei Liu <[email protected]>; Andrew Cooper <[email protected]>; Ian Jackson <[email protected]>; George Dunlap <[email protected]>; Jan Beulich <[email protected]>
Subject: [PATCH v3] docs: update xenstore-migration.mdUpdate connection record details:
Quoted 8 lines
- make flags common for sockets and domains (makes it easier to have a C union for conn-spec)
- add pending incoming data (needed for handling partially read requests when doing live update)
- add partial response length (needed for proper split to individual responses after live update)Signed-off-by Juergen Gross <[email protected]>
LGTM
Quoted 140 lines
---
V2:
- added out-resp-len to connection recordV3:
- better commit message (Julien Grall)
- same sequence for fields and detailed descriptions (Julien Grall)
- some wording corrected (Paul Durrant)Signed-off-by Juergen Gross <[email protected]>--- docs/designs/xenstore-migration.md | 72 +++++++++++++++++------------- 1 file changed, 41 insertions(+), 31 deletions(-)docs/designs/xenstore-migration.md +41
-32@@ -147,43 +147,60 @@ the domain being migrated. ``` 0 1 2 3 4 5 6 7 octet +-------+-------+-------+-------+-------+-------+-------+-------+ -| conn-id | conn-type | conn-spec +| conn-id | conn-type | flags | ++-------------------------------+---------------+---------------+ +| conn-spec -+-------------------------------+-------------------------------+ -| data-len | data -+-------------------------------+ ++---------------+---------------+-------------------------------+ +| in-data-len | out-resp-len | out-data-len | ++---------------+---------------+-------------------------------+ +| data ``` -| Field | Description | -|-------------|-------------------------------------------------| -| `conn-id` | A non-zero number used to identify this | -| | connection in subsequent connection-specific | -| | records | -| | | -| `conn-type` | 0x0000: shared ring | -| | 0x0001: socket | -| | 0x0002 - 0xFFFF: reserved for future use | -| | | -| `conn-spec` | See below | -| | | -| `data-len` | The length (in octets) of any pending data not | -| | yet written to the connection | -| | | -| `data` | Pending data (may be empty) | +| Field | Description | +|----------------|----------------------------------------------| +| `conn-id` | A non-zero number used to identify this | +| | connection in subsequent connection-specific | +| | records | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only | +| | | +| `conn-spec` | See below | +| | | +| `in-data-len` | The length (in octets) of any data read | +| | from the connection not yet processed | +| | | +| `out-resp-len` | The length (in octets) of a partial response | +| | not yet written to the connection | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection, including | +| | a partial response (see `out-resp-len`) | +| | | +| `data` | Pending data: first in-data-len octets of | +| | read data, then out-data-len octets of | +| | written data (any of both may be empty) | -The format of `conn-spec` is dependent upon `conn-type`. +In case of live update the connection record for the connection via which +the live update command was issued will contain the response for the live +update command in the pending not yet written data. \pagebreak +The format of `conn-spec` is dependent upon `conn-type`. + For `shared ring` connections it is as follows: ``` 0 1 2 3 4 5 6 7 octet - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | domid | tdomid | evtchn | +-------------------------------+-------------------------------+@@ -198,8 +215,6 @@ For `shared ring` connections it is as follows: | | it has been subject to an SET_TARGET | | | operation [2] or DOMID_INVALID [3] otherwise | | | | -| `flags` | Must be zero | -| | | | `evtchn` | The port number of the interdomain channel used | | | by `domid` to communicate with xenstored | | | |@@ -211,8 +226,6 @@ For `socket` connections it is as follows: ``` - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | socket-fd | pad | +-------------------------------+-------------------------------+@@ -221,9 +234,6 @@ For `socket` connections it is as follows: | Field | Description | |-------------|-------------------------------------------------| -| `flags` | A bit-wise OR of: | -| | 0001: read-only | -| | | | `socket-fd` | The file descriptor of the connected socket | This type of connection is only relevant for live update, where the xenstored@@ -398,4 +408,4 @@ explanation of node permissions. [3] See https://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/xen.h;hb=HEAD#l612 -[4] https://wiki.xen.org/wiki/XenBus +[4] https://wiki.xen.org/wiki/XenBus --2.26.2
Paul Durrant writes ("RE: [PATCH v3] docs: update xenstore-migration.md"):
Quoted 18 lines
Quoted 18 lines
-----Original Message-----
From: Xen-devel <[email protected]> On Behalf Of Juergen Gross
Sent: 29 May 2020 12:37
To: [email protected]
Cc: Juergen Gross <[email protected]>; Stefano Stabellini <[email protected]>; Julien Grall <[email protected]>; Wei Liu <[email protected]>; Andrew Cooper <[email protected]>; Ian Jackson <[email protected]>; George Dunlap <[email protected]>; Jan Beulich <[email protected]>
Subject: [PATCH v3] docs: update xenstore-migration.mdUpdate connection record details:
- make flags common for sockets and domains (makes it easier to have a C union for conn-spec)
- add pending incoming data (needed for handling partially read requests when doing live update)
- add partial response length (needed for proper split to individual responses after live update)
Quoted 5 lines
Quoted 1 line
Signed-off-by Juergen Gross <[email protected]>LGTM
Reviewed-by Paul Durrant <[email protected]>
Thanks, committed.
Ian.
Hi,
Quoted 10 lines · Juergen Gross
Update connection record details:
- make flags common for sockets and domains (makes it easier to have a C union for conn-spec)
- add pending incoming data (needed for handling partially read requests when doing live update)
- add partial response length (needed for proper split to individual responses after live update)Signed-off-by Juergen Gross <[email protected]>
Cheers,
Quoted 138 lines
---
V2:
- added out-resp-len to connection recordV3:
- better commit message (Julien Grall)
- same sequence for fields and detailed descriptions (Julien Grall)
- some wording corrected (Paul Durrant)Signed-off-by Juergen Gross <[email protected]>--- docs/designs/xenstore-migration.md | 72 +++++++++++++++++------------- 1 file changed, 41 insertions(+), 31 deletions(-)docs/designs/xenstore-migration.md +41
-31@@ -147,43 +147,60 @@ the domain being migrated. ``` 0 1 2 3 4 5 6 7 octet +-------+-------+-------+-------+-------+-------+-------+-------+ -| conn-id | conn-type | conn-spec +| conn-id | conn-type | flags | ++-------------------------------+---------------+---------------+ +| conn-spec -+-------------------------------+-------------------------------+ -| data-len | data -+-------------------------------+ ++---------------+---------------+-------------------------------+ +| in-data-len | out-resp-len | out-data-len | ++---------------+---------------+-------------------------------+ +| data ``` -| Field | Description | -|-------------|-------------------------------------------------| -| `conn-id` | A non-zero number used to identify this | -| | connection in subsequent connection-specific | -| | records | -| | | -| `conn-type` | 0x0000: shared ring | -| | 0x0001: socket | -| | 0x0002 - 0xFFFF: reserved for future use | -| | | -| `conn-spec` | See below | -| | | -| `data-len` | The length (in octets) of any pending data not | -| | yet written to the connection | -| | | -| `data` | Pending data (may be empty) | +| Field | Description | +|----------------|----------------------------------------------| +| `conn-id` | A non-zero number used to identify this | +| | connection in subsequent connection-specific | +| | records | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only | +| | | +| `conn-spec` | See below | +| | | +| `in-data-len` | The length (in octets) of any data read | +| | from the connection not yet processed | +| | | +| `out-resp-len` | The length (in octets) of a partial response | +| | not yet written to the connection | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection, including | +| | a partial response (see `out-resp-len`) | +| | | +| `data` | Pending data: first in-data-len octets of | +| | read data, then out-data-len octets of | +| | written data (any of both may be empty) | -The format of `conn-spec` is dependent upon `conn-type`. +In case of live update the connection record for the connection via which +the live update command was issued will contain the response for the live +update command in the pending not yet written data. \pagebreak +The format of `conn-spec` is dependent upon `conn-type`. + For `shared ring` connections it is as follows: ``` 0 1 2 3 4 5 6 7 octet - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | domid | tdomid | evtchn | +-------------------------------+-------------------------------+@@ -198,8 +215,6 @@ For `shared ring` connections it is as follows: | | it has been subject to an SET_TARGET | | | operation [2] or DOMID_INVALID [3] otherwise | | | | -| `flags` | Must be zero | -| | | | `evtchn` | The port number of the interdomain channel used | | | by `domid` to communicate with xenstored | | | |@@ -211,8 +226,6 @@ For `socket` connections it is as follows: ``` - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | socket-fd | pad | +-------------------------------+-------------------------------+@@ -221,9 +234,6 @@ For `socket` connections it is as follows: | Field | Description | |-------------|-------------------------------------------------| -| `flags` | A bit-wise OR of: | -| | 0001: read-only | -| | | | `socket-fd` | The file descriptor of the connected socket | This type of connection is only relevant for live update, where the xenstored@@ -398,4 +408,4 @@ explanation of node permissions. [3] See https://xenbits.xen.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/xen.h;hb=HEAD#l612 -[4] https://wiki.xen.org/wiki/XenBus +[4] https://wiki.xen.org/wiki/XenBus
Signature · 1 line
Julien Grall