[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL 48/58] block: Update comments on BDRV_BLOCK_* meaning
From: |
Kevin Wolf |
Subject: |
[Qemu-devel] [PULL 48/58] block: Update comments on BDRV_BLOCK_* meanings |
Date: |
Thu, 11 May 2017 16:32:51 +0200 |
From: Eric Blake <address@hidden>
We had some conflicting documentation: a nice 8-way table that
described all possible combinations of DATA, ZERO, and
OFFSET_VALID, contrasted with text that implied that OFFSET_VALID
always meant raw data could be read directly. Furthermore, the
text refers a lot to bs->file, even though the interface was
updated back in 67a0fd2a to let the driver pass back a specific
BDS (not necessarily bs->file). As the 8-way table is the
intended semantics, simplify the rest of the text to get rid of
the confusion.
ALLOCATED is always set by the block layer for convenience (drivers
do not have to worry about it). RAW is used only internally, but
by more than the raw driver. Document these additional items on
the driver callback.
Suggested-by: Max Reitz <address@hidden>
Signed-off-by: Eric Blake <address@hidden>
Reviewed-by: Max Reitz <address@hidden>
Message-id: address@hidden
Signed-off-by: Max Reitz <address@hidden>
---
include/block/block.h | 35 +++++++++++++++++++----------------
include/block/block_int.h | 7 +++++++
2 files changed, 26 insertions(+), 16 deletions(-)
diff --git a/include/block/block.h b/include/block/block.h
index 90932b4..9b355e9 100644
--- a/include/block/block.h
+++ b/include/block/block.h
@@ -121,29 +121,32 @@ typedef struct HDGeometry {
#define BDRV_REQUEST_MAX_BYTES (BDRV_REQUEST_MAX_SECTORS << BDRV_SECTOR_BITS)
/*
- * Allocation status flags
- * BDRV_BLOCK_DATA: data is read from a file returned by bdrv_get_block_status.
- * BDRV_BLOCK_ZERO: sectors read as zero
- * BDRV_BLOCK_OFFSET_VALID: sector stored as raw data in a file returned by
- * bdrv_get_block_status.
+ * Allocation status flags for bdrv_get_block_status() and friends.
+ *
+ * Public flags:
+ * BDRV_BLOCK_DATA: allocation for data at offset is tied to this layer
+ * BDRV_BLOCK_ZERO: offset reads as zero
+ * BDRV_BLOCK_OFFSET_VALID: an associated offset exists for accessing raw data
* BDRV_BLOCK_ALLOCATED: the content of the block is determined by this
- * layer (as opposed to the backing file)
- * BDRV_BLOCK_RAW: used internally to indicate that the request
- * was answered by the raw driver and that one
- * should look in bs->file directly.
+ * layer (short for DATA || ZERO), set by block layer
*
- * If BDRV_BLOCK_OFFSET_VALID is set, bits 9-62 represent the offset in
- * bs->file where sector data can be read from as raw data.
+ * Internal flag:
+ * BDRV_BLOCK_RAW: used internally to indicate that the request was
+ * answered by a passthrough driver such as raw and that the
+ * block layer should recompute the answer from bs->file.
*
- * DATA == 0 && ZERO == 0 means that data is read from backing_hd if present.
+ * If BDRV_BLOCK_OFFSET_VALID is set, bits 9-62 (BDRV_BLOCK_OFFSET_MASK)
+ * represent the offset in the returned BDS that is allocated for the
+ * corresponding raw data; however, whether that offset actually contains
+ * data also depends on BDRV_BLOCK_DATA and BDRV_BLOCK_ZERO, as follows:
*
* DATA ZERO OFFSET_VALID
- * t t t sectors read as zero, bs->file is zero at offset
- * t f t sectors read as valid from bs->file at offset
- * f t t sectors preallocated, read as zero, bs->file not
+ * t t t sectors read as zero, returned file is zero at offset
+ * t f t sectors read as valid from file at offset
+ * f t t sectors preallocated, read as zero, returned file not
* necessarily zero at offset
* f f t sectors preallocated but read from backing_hd,
- * bs->file contains garbage at offset
+ * returned file contains garbage at offset
* t t f sectors preallocated, read as zero, unknown offset
* t f f sectors read from unknown file or offset
* f t f not allocated or unknown offset, read as zero
diff --git a/include/block/block_int.h b/include/block/block_int.h
index 5750a44..8d3724c 100644
--- a/include/block/block_int.h
+++ b/include/block/block_int.h
@@ -165,6 +165,13 @@ struct BlockDriver {
int64_t offset, int count, BdrvRequestFlags flags);
int coroutine_fn (*bdrv_co_pdiscard)(BlockDriverState *bs,
int64_t offset, int count);
+
+ /*
+ * Building block for bdrv_block_status[_above]. The driver should
+ * answer only according to the current layer, and should not
+ * set BDRV_BLOCK_ALLOCATED, but may set BDRV_BLOCK_RAW. See block.h
+ * for the meaning of _DATA, _ZERO, and _OFFSET_VALID.
+ */
int64_t coroutine_fn (*bdrv_co_get_block_status)(BlockDriverState *bs,
int64_t sector_num, int nb_sectors, int *pnum,
BlockDriverState **file);
--
1.8.3.1
- [Qemu-devel] [PULL 40/58] blkdebug: Sanity check block layer guarantees, (continued)
- [Qemu-devel] [PULL 40/58] blkdebug: Sanity check block layer guarantees, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 37/58] qemu-io: Improve alignment checks, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 41/58] blkdebug: Refactor error injection, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 42/58] blkdebug: Add pass-through write_zero and discard support, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 39/58] qemu-io: Switch 'map' output to byte-based reporting, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 43/58] blkdebug: Simplify override logic, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 44/58] blkdebug: Add ability to override unmap geometries, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 47/58] qcow2: Use consistent switch indentation, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 45/58] tests: Add coverage for recent block geometry fixes, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 46/58] qcow2: Nicer variable names in qcow2_update_snapshot_refcount(), Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 48/58] block: Update comments on BDRV_BLOCK_* meanings,
Kevin Wolf <=
- [Qemu-devel] [PULL 49/58] qcow2: Correctly report status of preallocated zero clusters, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 50/58] qcow2: Name typedef for cluster type, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 51/58] qcow2: Make distinction between zero cluster types obvious, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 53/58] iotests: Improve _filter_qemu_img_map, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 52/58] qcow2: Optimize zero_single_l2() to minimize L2 churn, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 56/58] qcow2: Assert that cluster operations are aligned, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 54/58] iotests: Add test 179 to cover write zeroes with unmap, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 55/58] qcow2: Optimize write zero of unaligned tail cluster, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 58/58] MAINTAINERS: Add qemu-progress to the block layer, Kevin Wolf, 2017/05/11
- [Qemu-devel] [PULL 57/58] qcow2: Discard/zero clusters by byte count, Kevin Wolf, 2017/05/11