[Qemu-devel] [PATCH] block: Document BDRV_REQ_WRITE_UNCHANGED support

[Qemu-devel] [PATCH] block: Document BDRV_REQ_WRITE_UNCHANGED support

[Max Reitz]

Add BDRV_REQ_WRITE_UNCHANGED to the list of flags honored during pwrite
and pwrite_zeroes, and also add a note on when you absolutely need to
support it.

Signed-off-by: Max Reitz <mreitz@redhat.com>
---
I did not include a note on how this might be useful to protocol
drivers, because BDRV_REQ_WRITE_UNCHANGED requests will usually not end
up on the protocol level anyway.
(I suppose it would be possible in theory if a protocol driver reports a
 certain range as unallocated and the user installs a copy-on-read
 driver on top, but I think every protocol driver currently reports
 everything as allocated.)
---
 include/block/block_int.h | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/include/block/block_int.h b/include/block/block_int.h
index e3d6219f4e..76b589da57 100644
--- a/include/block/block_int.h
+++ b/include/block/block_int.h
@@ -656,10 +656,24 @@ struct BlockDriverState {
     /* I/O Limits */
     BlockLimits bl;
 
-    /* Flags honored during pwrite (so far: BDRV_REQ_FUA) */
+    /* Flags honored during pwrite (so far: BDRV_REQ_FUA,
+     * BDRV_REQ_WRITE_UNCHANGED).
+     * If a driver does not support BDRV_REQ_WRITE_UNCHANGED, those
+     * writes will be issued as normal writes without the flag set.
+     * This is important to note for drivers that do not explicitly
+     * request a WRITE permission for their children and instead take
+     * the same permissions as their parent did (this is commonly what
+     * block filters do).  Such drivers have to be aware that the
+     * parent may have taken a WRITE_UNCHANGED permission only and is
+     * issuing such requests.  Drivers either must make sure that
+     * these requests do not result in plain WRITE accesses (usually
+     * by supporting BDRV_REQ_WRITE_UNCHANGED, and then forwarding
+     * every incoming write request as-is, including potentially that
+     * flag), or they have to explicitly take the WRITE permission for
+     * their children. */
     unsigned int supported_write_flags;
     /* Flags honored during pwrite_zeroes (so far: BDRV_REQ_FUA,
-     * BDRV_REQ_MAY_UNMAP) */
+     * BDRV_REQ_MAY_UNMAP, BDRV_REQ_WRITE_UNCHANGED) */
     unsigned int supported_zero_flags;
 
     /* the following member gives a name to every node on the bs graph. */
-- 
2.14.3

Re: [Qemu-devel] [PATCH] block: Document BDRV_REQ_WRITE_UNCHANGED support

[Eric Blake]

On 05/02/2018 09:03 AM, Max Reitz wrote:
> Add BDRV_REQ_WRITE_UNCHANGED to the list of flags honored during pwrite
> and pwrite_zeroes, and also add a note on when you absolutely need to
> support it.
> 
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> ---

Thanks, that helps.

Reviewed-by: Eric Blake <eblake@redhat.com>

> I did not include a note on how this might be useful to protocol
> drivers, because BDRV_REQ_WRITE_UNCHANGED requests will usually not end
> up on the protocol level anyway.
> (I suppose it would be possible in theory if a protocol driver reports a
>   certain range as unallocated and the user installs a copy-on-read
>   driver on top, but I think every protocol driver currently reports
>   everything as allocated.)

It doesn't help that I still haven't revisited an audit of whether all 
the protocol drivers have a sane status return to begin with (fallout 
from Kevin's review of my byte-based block status that landed in 2.12). 
But that doesn't hold up this patch.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH] block: Document BDRV_REQ_WRITE_UNCHANGED support

[Max Reitz]

[-- Attachment #1: Type: text/plain, Size: 864 bytes --]

On 2018-05-02 16:03, Max Reitz wrote:
> Add BDRV_REQ_WRITE_UNCHANGED to the list of flags honored during pwrite
> and pwrite_zeroes, and also add a note on when you absolutely need to
> support it.
> 
> Signed-off-by: Max Reitz <mreitz@redhat.com>
> ---
> I did not include a note on how this might be useful to protocol
> drivers, because BDRV_REQ_WRITE_UNCHANGED requests will usually not end
> up on the protocol level anyway.
> (I suppose it would be possible in theory if a protocol driver reports a
>  certain range as unallocated and the user installs a copy-on-read
>  driver on top, but I think every protocol driver currently reports
>  everything as allocated.)
> ---
>  include/block/block_int.h | 18 ++++++++++++++++--
>  1 file changed, 16 insertions(+), 2 deletions(-)

Thanks for the review, applied to my block branch.

Max


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]