Skip to contentSkip to conversation

virtio-blk: clarify semantics of multi-segment discard/write zeroes commands

PATCH In review Stefan Hajnoczi 3 participants 7 messages Feb 26, 2019

lore
Share & tools
lore
#0 lore raw

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
index c5fdc34..7bfcc78 100644
@@ -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]
#1 lore raw
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.

---
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
index c5fdc34..7bfcc78 100644

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]

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

---
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
index c5fdc34..7bfcc78 100644
@@ -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]

#3 lore raw
In reply to Cornelia Huck
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.

---
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
index c5fdc34..7bfcc78 100644
@@ -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:

...

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

---
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
index c5fdc34..7bfcc78 100644
@@ -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.

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

---
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
index c5fdc34..7bfcc78 100644

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/ ?

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

#6 lore raw
In reply to Stefan Hajnoczi
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.

---
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
index c5fdc34..7bfcc78 100644
@@ -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]