block: Document BDRV_REQ_WRITE_UNCHANGED support
PATCH 1/1 block: Document BDRV_REQ_WRITE_UNCHANGED support
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.
---
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(-)
include/block/block_int.h +16 -2
@@ -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. */
Signature · 1 line
2.14.3
Quoted 6 lines · Max Reitz
Add
BDRV_REQ_WRITE_UNCHANGEDto the list of flags honored during pwrite andpwrite_zeroes, and also add a note on when you absolutely need to support it.Signed-off-by Max Reitz <[email protected]>---
Thanks, that helps.
Quoted 7 lines
I did not include a note on how this might be useful to protocol drivers, because
BDRV_REQ_WRITE_UNCHANGEDrequests 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.
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org
Quoted 13 lines · Max Reitz
Add
BDRV_REQ_WRITE_UNCHANGEDto the list of flags honored during pwrite andpwrite_zeroes, and also add a note on when you absolutely need to support it.Signed-off-by Max Reitz <[email protected]>---
I did not include a note on how this might be useful to protocol drivers, becauseBDRV_REQ_WRITE_UNCHANGEDrequests 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.)
Quoted 3 lines
--- include/block/block_int.h | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-)
Thanks for the review, applied to my block branch.
Max