Skip to contentSkip to conversation

docs: update xenstore-migration.md

PATCH Superseded Juergen Gross 3 participants 6 messages May 28, 2020

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

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
index 34a2afd17e..5736bbad94 100644
@@ -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
\ No newline at end of file
+[4] https://wiki.xen.org/wiki/XenBus
Signature · 1 line
2.26.2
#1 lore raw

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
#2 lore raw
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-type and 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

#3 lore raw
In reply to Juergen Gross
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.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 +10 -20
index 34a2afd17e..5736bbad94 100644
@@ -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
\ No newline at end of file
+[4] https://wiki.xen.org/wiki/XenBus
--

2.26.2

#4 lore raw
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.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 +14 -20
index 34a2afd17e..5736bbad94 100644
@@ -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

#5 lore raw
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.md

Quoted 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 Beulich

<[email protected]>

Quoted 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.

---
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
index 34a2afd17e..5736bbad94 100644
@@ -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