docs: update xenstore-migration.md
PATCH v2 1/1 docs: update xenstore-migration.md
Update connection record details: make flags common for sockets and domains, and add pending incoming data.
---
V2:
- added out-resp-len to connection record
--- docs/designs/xenstore-migration.md | 71 +++++++++++++++++------------- 1 file changed, 40 insertions(+), 31 deletions(-)
docs/designs/xenstore-migration.md +40 -31
@@ -147,43 +147,59 @@ 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 | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | | +| `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 (included | +| | in the following `out-data-len`) | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection | +| | | +| `data` | Pending data, first read data, then 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 write 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 +214,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 +225,6 @@ For `socket` connections it is as follows: ``` - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | socket-fd | pad | +-------------------------------+-------------------------------+
@@ -221,9 +233,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 +407,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
Hi Juergen,
Quoted 16 lines · Juergen Gross
-| 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) |
Quoted 8 lines
+| Field | Description | +|----------------|----------------------------------------------| +| `conn-id` | A non-zero number used to identify this | +| | connection in subsequent connection-specific | +| | records | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only |
NIT: It is a bit odd the flags is in the header after conn-type and described before.
Quoted 5 lines
+| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | |
Quoted 8 lines
+| `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 (included | +| | in the following `out-data-len`) |
This seems to come from nowhere. It would be good to explain in the commit message why this is necessary.
Quoted 3 lines
+| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection |
Cheers,
Signature · 1 line
Julien Grall
Quoted 28 lines · Julien Grall
Hi Juergen,
Quoted 16 lines · Juergen Gross
-| 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) |Quoted 8 lines
+| Field | Description | +|----------------|----------------------------------------------| +| `conn-id` | A non-zero number used to identify this | +| | connection in subsequent connection-specific | +| | records | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only |
Quoted 1 line
NIT: It is a bit odd the flags is in the header after
conn-typeand described before.
Okay, I'll swap the descriptions.
Quoted 15 lines
Quoted 14 lines
+| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | | +| `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 (included | +| | in the following `out-data-len`) |
Quoted 1 line
This seems to come from nowhere. It would be good to explain in the commit message why this is necessary.
Okay.
Juergen
Quoted 63 lines
-----Original Message-----
From: Xen-devel <[email protected]> On Behalf Of Juergen Gross
Sent: 28 May 2020 09:22
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 v2] docs: update xenstore-migration.mdUpdate connection record details: make flags common for sockets and domains, and add pending incoming data.
Signed-off-by Juergen Gross <[email protected]>---
V2:
- added out-resp-len to connection record--- docs/designs/xenstore-migration.md | 71 +++++++++++++++++------------- 1 file changed, 40 insertions(+), 31 deletions(-)docs/designs/xenstore-migration.md +10
-20@@ -147,43 +147,59 @@ 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 |
docs/designs/xenstore-migration.md the domain being migrated. · line 174
Quoted 10 lines
docs/designs/xenstore-migration.md +10
-0+| | connection in subsequent connection-specific | +| | records | +| | | +| `flags` | A bit-wise OR of: | +| | 0001: read-only | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | |
Agreed with Julien... the above two would be better swapped to match the order of the fields in the record.
Quoted 11 lines
+| `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 (included | +| | in the following `out-data-len`) | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection |
So, IIUC out-data-len is inclusive of out-resp-len?
Quoted 3 lines
+| | | +| `data` | Pending data, first read data, then written | +| | data (any of both may be empty) |
Perhaps be more explicit here:
"Pending data: first in-data-len octets of read data, then out-data-len octets of written data"
docs/designs/xenstore-migration.md the domain being migrated. · line 192
Quoted 5 lines
docs/designs/xenstore-migration.md +3
-1-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 write data.
s/write/written for consistency I think.
Paul
Quoted 53 lines
\pagebreak
docs/designs/xenstore-migration.md +3
-11+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 +214,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 +225,6 @@ For `socket` connections it is as follows: ``` - +-------+-------+ - | flags | +---------------+---------------+---------------+---------------+ | socket-fd | pad | +-------------------------------+-------------------------------+@@ -221,9 +233,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 +407,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
Quoted 67 lines · Paul Durrant
Quoted 67 lines
-----Original Message-----
From: Xen-devel <[email protected]> On Behalf Of Juergen Gross
Sent: 28 May 2020 09:22
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 v2] docs: update xenstore-migration.mdUpdate connection record details: make flags common for sockets and domains, and add pending incoming data.
Signed-off-by Juergen Gross <[email protected]>---
V2:
- added out-resp-len to connection record--- docs/designs/xenstore-migration.md | 71 +++++++++++++++++------------- 1 file changed, 40 insertions(+), 31 deletions(-)docs/designs/xenstore-migration.md +14
-20@@ -147,43 +147,59 @@ 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 | +| | | +| `flags` | A bit-wise OR of: |
Quoted 8 lines
Quoted 6 lines
+| | 0001: read-only | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | |Agreed with Julien... the above two would be better swapped to match the order of the fields in the record.
Yes.
Quoted 13 lines
Quoted 12 lines
+| `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 (included | +| | in the following `out-data-len`) | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection |
Quoted 1 line
So, IIUC out-data-len is inclusive of out-resp-len?
Yes.
Quoted 8 lines
Quoted 4 lines
+| | | +| `data` | Pending data, first read data, then written | +| | data (any of both may be empty) |Perhaps be more explicit here:
"Pending data: first in-data-len octets of read data, then out-data-len octets of written data"
Okay.
Quoted 8 lines
docs/designs/xenstore-migration.md the domain being migrated. · line 192
Quoted 6 lines
docs/designs/xenstore-migration.md +3
-1-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 write data.s/write/written for consistency I think.
I'll use "... in the pending not yet written data".
Juergen
Quoted 120 lines
-----Original Message-----
From: Jürgen Groß <[email protected]>
Sent: 28 May 2020 09:59
To: [email protected]; [email protected]
Cc: '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: Re: [PATCH v2] docs: update xenstore-migration.mdQuoted 7 lines · Paul Durrant
Quoted 7 lines
-----Original Message-----
From: Xen-devel <[email protected]> On Behalf Of Juergen Gross
Sent: 28 May 2020 09:22
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 BeulichQuoted 60 lines
Quoted 60 lines
Subject: [PATCH v2] docs: update xenstore-migration.md
Update connection record details: make flags common for sockets and domains, and add pending incoming data.
Signed-off-by Juergen Gross <[email protected]>---
V2:
- added out-resp-len to connection record--- docs/designs/xenstore-migration.md | 71 +++++++++++++++++------------- 1 file changed, 40 insertions(+), 31 deletions(-)docs/designs/xenstore-migration.md +14
-20@@ -147,43 +147,59 @@ 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 | +| | | +| `flags` | A bit-wise OR of: |Quoted 8 lines
Quoted 6 lines
+| | 0001: read-only | +| | | +| `conn-type` | 0x0000: shared ring | +| | 0x0001: socket | +| | 0x0002 - 0xFFFF: reserved for future use | +| | |Agreed with Julien... the above two would be better swapped to match the order of the fields in the
record.
Yes.
Quoted 13 lines
Quoted 12 lines
+| `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 (included | +| | in the following `out-data-len`) | +| | | +| `out-data-len` | The length (in octets) of any pending data | +| | not yet written to the connection |Quoted 1 line
So, IIUC out-data-len is inclusive of out-resp-len?
Yes.
Quoted 8 lines
Quoted 4 lines
+| | | +| `data` | Pending data, first read data, then written | +| | data (any of both may be empty) |Perhaps be more explicit here:
"Pending data: first in-data-len octets of read data, then out-data-len octets of written data"
Okay.
Quoted 2 lines
Quoted 2 lines
Quoted 9 lines
Quoted 6 lines
docs/designs/xenstore-migration.md the domain being migrated. · line 192
Quoted 4 lines
docs/designs/xenstore-migration.md +3
-1-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 write data.s/write/written for consistency I think.
I'll use "... in the pending not yet written data".
Ok.
Paul
Quoted 2 lines
Juergen