virtio-blk: clarify semantics of multi-segment discard/write zeroes commands
PATCH 1/1 virtio-blk: clarify semantics of multi-segment discard/write zeroes commands
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
---
I would like to request a vote on this.
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)
content.tex +21 -2
@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes). -The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form: \begin{lstlisting} struct virtio_blk_discard_write_zeroes {
@@ -3997,6 +3999,10 @@ error or VIRTIO_BLK_S_UNSUPP for a request unsupported by device: #define VIRTIO_BLK_S_UNSUPP 2 \end{lstlisting} +The status of individual segments is indeterminate when a discard or write zero +command produces VIRTIO_BLK_S_IOERR. A segment may have completed +successfully, failed, or not been processed by the device. + \drivernormative{\subsubsection}{Device Operation}{Device Types / Block Device / Device Operation} A driver MUST NOT submit a request which would cause a read or write
@@ -4014,6 +4020,14 @@ The length of \field{data} MUST be a multiple of the size of struct virtio_blk_discard_write_zeroes for VIRTIO_BLK_T_DISCARD and VIRTIO_BLK_T_WRITE_ZEROES requests. +VIRTIO_BLK_T_DISCARD requests MUST NOT contain more than +\field{max_discard_seg} struct virtio_blk_discard_write_zeroes segments in +\field{data}. + +VIRTIO_BLK_T_WRITE_ZEROES requests MUST NOT contain more than +\field{max_write_zeroes_seg} struct virtio_blk_discard_write_zeroes segments in +\field{data}. + If the VIRTIO_BLK_F_CONFIG_WCE feature is negotiated, the driver MAY switch to writethrough or writeback mode by writing respectively 0 and 1 to the \field{writeback} field. After writing a 0 to \field{writeback},
@@ -4024,6 +4038,11 @@ The \field{unmap} bit MUST be zero for discard commands. The driver MUST NOT assume anything about the data returned by read requests after a range of sectors has been discarded. +A driver MUST NOT assume that individual segments in a multi-segment +VIRTIO_BLK_T_DISCARD or VIRTIO_BLK_T_WRITE_ZEROES request completed +successfully, failed, or were processed by the device at all if the request +failed with VIRTIO_BLK_S_IOERR. + \devicenormative{\subsubsection}{Device Operation}{Device Types / Block Device / Device Operation} A device MUST set the \field{status} byte to VIRTIO_BLK_S_IOERR
Signature · 6 lines
2.20.1 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 7 lines · On Tue, 26 Feb 2019 16:25:53 +0000 Stefan Hajnoczi <[email protected]> wrote:
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
Signed-off-by Stefan Hajnoczi <[email protected]>---
I would like to request a vote on this.
Only one minor nit from me, below.
Quoted 9 lines
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)content.tex +0
-0
content.tex read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT · line 3973
Quoted 9 lines
content.tex +4
-2@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes). -The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form:
Maybe s/of form/of the form/ ?
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 25 lines · On Tue, 26 Feb 2019 18:09:03 +0100 Cornelia Huck <[email protected]> wrote:
Quoted 7 lines · On Tue, 26 Feb 2019 16:25:53 +0000 Stefan Hajnoczi <[email protected]> wrote:
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
Signed-off-by Stefan Hajnoczi <[email protected]>---
I would like to request a vote on this.Only one minor nit from me, below.
Quoted 12 lines
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)content.tex +0
-0@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes).
Quoted 8 lines
content.tex read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT · line 3973
Quoted 6 lines
content.tex +4
-2-The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form:Maybe s/of form/of the form/ ?
...and that is certainly a non-material change we could do on top.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
Quoted 25 lines · Cornelia Huck
Quoted 7 lines · On Tue, 26 Feb 2019 16:25:53 +0000 Stefan Hajnoczi <[email protected]> wrote:
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
Signed-off-by Stefan Hajnoczi <[email protected]>---
I would like to request a vote on this.Only one minor nit from me, below.
Quoted 12 lines
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)content.tex +0
-0@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes).
Quoted 8 lines
content.tex read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT · line 3973
Quoted 6 lines
content.tex +4
-2-The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form:Maybe s/of form/of the form/ ?
I wanted to stay consistent with the existing text above it:
The driver queues requests to the virtqueue, and they are used by the device (not necessarily in order). Each request is of form:
...
Quoted 35 lines · On Tue, 26 Feb 2019 17:44:16 +0000 Stefan Hajnoczi <[email protected]> wrote:
Quoted 25 lines · Cornelia Huck
Quoted 7 lines · On Tue, 26 Feb 2019 16:25:53 +0000 Stefan Hajnoczi <[email protected]> wrote:
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
Signed-off-by Stefan Hajnoczi <[email protected]>---
I would like to request a vote on this.Only one minor nit from me, below.
Quoted 12 lines
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)content.tex +0
-0@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes).Quoted 8 lines
content.tex read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT · line 3973
Quoted 6 lines
content.tex +4
-2-The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form:Maybe s/of form/of the form/ ?
Quoted 6 lines
I wanted to stay consistent with the existing text above it:
The driver queues requests to the virtqueue, and they are used by the device (not necessarily in order). Each request is of form:
...
Fine with me as well.
Quoted 38 lines · Cornelia Huck
Quoted 35 lines · On Tue, 26 Feb 2019 17:44:16 +0000 Stefan Hajnoczi <[email protected]> wrote:
Quoted 33 lines · Cornelia Huck
Quoted 7 lines · On Tue, 26 Feb 2019 16:25:53 +0000 Stefan Hajnoczi <[email protected]> wrote:
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
Signed-off-by Stefan Hajnoczi <[email protected]>---
I would like to request a vote on this.Only one minor nit from me, below.
Quoted 9 lines
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)content.tex +0
-0content.tex read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT · line 3973
Quoted 9 lines
content.tex +4
-2@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes). -The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form:Maybe s/of form/of the form/ ?
Quoted 8 lines
Quoted 6 lines
I wanted to stay consistent with the existing text above it:
The driver queues requests to the virtqueue, and they are used by the device (not necessarily in order). Each request is of form:
...
Fine with me as well.
Okay, great! Let's leave it as-is.
Stefan
Quoted 35 lines · Stefan Hajnoczi
Quoted 25 lines · Cornelia Huck
Quoted 7 lines · On Tue, 26 Feb 2019 16:25:53 +0000 Stefan Hajnoczi <[email protected]> wrote:
Describe the failure case and maximum number of segments in a multi-segment discard/write zeroes command.
Signed-off-by Stefan Hajnoczi <[email protected]>---
I would like to request a vote on this.Only one minor nit from me, below.
Quoted 12 lines
content.tex | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-)content.tex +0
-0@@ -3967,8 +3967,10 @@ read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT requests write the contents of \field{data} to the block device (in multiples of 512 bytes).Quoted 8 lines
content.tex read from the block device (in multiples of 512 bytes). VIRTIO_BLK_T_OUT · line 3973
Quoted 6 lines
content.tex +4
-2-The \field{data} used for discard or write zeroes command is described -by one or more virtio_blk_discard_write_zeroes structs: +The \field{data} used for discard or write zeroes commands consists of one or +more segments. The maximum number of segments is \field{max_discard_seg} for +discard commands and \field{max_write_zeroes_seg} for write zeroes commands. +Each segment is of form:Maybe s/of form/of the form/ ?
Quoted 6 lines
I wanted to stay consistent with the existing text above it:
The driver queues requests to the virtqueue, and they are used by the device (not necessarily in order). Each request is of form:
...
OK so I will cancel the vote on this version for now?
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]