2 * QEMU System Emulator block driver
4 * Copyright (c) 2003 Fabrice Bellard
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24 #ifndef BLOCK_COMMON_H
25 #define BLOCK_COMMON_H
27 #include "qapi/qapi-types-block-core.h"
28 #include "qemu/queue.h"
31 * co_wrapper{*}: Function specifiers used by block-coroutine-wrapper.py
33 * Function specifiers, which do nothing but mark functions to be
34 * generated by scripts/block-coroutine-wrapper.py
36 * Usage: read docs/devel/block-coroutine-wrapper.rst
38 * There are 4 kind of specifiers:
39 * - co_wrapper functions can be called by only non-coroutine context, because
40 * they always generate a new coroutine.
41 * - co_wrapper_mixed functions can be called by both coroutine and
42 * non-coroutine context.
43 * - co_wrapper_bdrv_rdlock are co_wrapper functions but automatically take and
44 * release the graph rdlock when creating a new coroutine
45 * - co_wrapper_mixed_bdrv_rdlock are co_wrapper_mixed functions but
46 * automatically take and release the graph rdlock when creating a new
50 #define co_wrapper_mixed
51 #define co_wrapper_bdrv_rdlock
52 #define co_wrapper_mixed_bdrv_rdlock
54 #include "block/blockjob.h"
57 typedef struct BlockDriver BlockDriver
;
58 typedef struct BdrvChild BdrvChild
;
59 typedef struct BdrvChildClass BdrvChildClass
;
61 typedef struct BlockDriverInfo
{
62 /* in bytes, 0 if irrelevant */
64 /* offset at which the VM state can be saved (0 if not possible) */
65 int64_t vm_state_offset
;
68 * True if this block driver only supports compressed writes
70 bool needs_compressed_writes
;
73 typedef struct BlockFragInfo
{
74 uint64_t allocated_clusters
;
75 uint64_t total_clusters
;
76 uint64_t fragmented_clusters
;
77 uint64_t compressed_clusters
;
81 BDRV_REQ_COPY_ON_READ
= 0x1,
82 BDRV_REQ_ZERO_WRITE
= 0x2,
85 * The BDRV_REQ_MAY_UNMAP flag is used in write_zeroes requests to indicate
86 * that the block driver should unmap (discard) blocks if it is guaranteed
87 * that the result will read back as zeroes. The flag is only passed to the
88 * driver if the block device is opened with BDRV_O_UNMAP.
90 BDRV_REQ_MAY_UNMAP
= 0x4,
93 * An optimization hint when all QEMUIOVector elements are within
94 * previously registered bdrv_register_buf() memory ranges.
96 * Code that replaces the user's QEMUIOVector elements with bounce buffers
97 * must take care to clear this flag.
99 BDRV_REQ_REGISTERED_BUF
= 0x8,
102 BDRV_REQ_WRITE_COMPRESSED
= 0x20,
105 * Signifies that this write request will not change the visible disk
108 BDRV_REQ_WRITE_UNCHANGED
= 0x40,
111 * Forces request serialisation. Use only with write requests.
113 BDRV_REQ_SERIALISING
= 0x80,
116 * Execute the request only if the operation can be offloaded or otherwise
117 * be executed efficiently, but return an error instead of using a slow
120 BDRV_REQ_NO_FALLBACK
= 0x100,
123 * BDRV_REQ_PREFETCH makes sense only in the context of copy-on-read
124 * (i.e., together with the BDRV_REQ_COPY_ON_READ flag or when a COR
125 * filter is involved), in which case it signals that the COR operation
126 * need not read the data into memory (qiov) but only ensure they are
127 * copied to the top layer (i.e., that COR operation is done).
129 BDRV_REQ_PREFETCH
= 0x200,
132 * If we need to wait for other requests, just fail immediately. Used
133 * only together with BDRV_REQ_SERIALISING. Used only with requests aligned
134 * to request_alignment (corresponding assertions are in block/io.c).
136 BDRV_REQ_NO_WAIT
= 0x400,
138 /* Mask of valid flags */
139 BDRV_REQ_MASK
= 0x7ff,
142 #define BDRV_O_NO_SHARE 0x0001 /* don't share permissions */
143 #define BDRV_O_RDWR 0x0002
144 #define BDRV_O_RESIZE 0x0004 /* request permission for resizing the node */
145 #define BDRV_O_SNAPSHOT 0x0008 /* open the file read only and save
146 writes in a snapshot */
147 #define BDRV_O_TEMPORARY 0x0010 /* delete the file after use */
148 #define BDRV_O_NOCACHE 0x0020 /* do not use the host page cache */
149 #define BDRV_O_NATIVE_AIO 0x0080 /* use native AIO instead of the
151 #define BDRV_O_NO_BACKING 0x0100 /* don't open the backing file */
152 #define BDRV_O_NO_FLUSH 0x0200 /* disable flushing on this disk */
153 #define BDRV_O_COPY_ON_READ 0x0400 /* copy read backing sectors into image */
154 #define BDRV_O_INACTIVE 0x0800 /* consistency hint for migration handoff */
155 #define BDRV_O_CHECK 0x1000 /* open solely for consistency check */
156 #define BDRV_O_ALLOW_RDWR 0x2000 /* allow reopen to change from r/o to r/w */
157 #define BDRV_O_UNMAP 0x4000 /* execute guest UNMAP/TRIM operations */
158 #define BDRV_O_PROTOCOL 0x8000 /* if no block driver is explicitly given:
159 select an appropriate protocol driver,
160 ignoring the format layer */
161 #define BDRV_O_NO_IO 0x10000 /* don't initialize for I/O */
162 #define BDRV_O_AUTO_RDONLY 0x20000 /* degrade to read-only if opening
164 #define BDRV_O_IO_URING 0x40000 /* use io_uring instead of the thread pool */
166 #define BDRV_O_CACHE_MASK (BDRV_O_NOCACHE | BDRV_O_NO_FLUSH)
169 /* Option names of options parsed by the block layer */
171 #define BDRV_OPT_CACHE_WB "cache.writeback"
172 #define BDRV_OPT_CACHE_DIRECT "cache.direct"
173 #define BDRV_OPT_CACHE_NO_FLUSH "cache.no-flush"
174 #define BDRV_OPT_READ_ONLY "read-only"
175 #define BDRV_OPT_AUTO_READ_ONLY "auto-read-only"
176 #define BDRV_OPT_DISCARD "discard"
177 #define BDRV_OPT_FORCE_SHARE "force-share"
180 #define BDRV_SECTOR_BITS 9
181 #define BDRV_SECTOR_SIZE (1ULL << BDRV_SECTOR_BITS)
183 #define BDRV_REQUEST_MAX_SECTORS MIN_CONST(SIZE_MAX >> BDRV_SECTOR_BITS, \
184 INT_MAX >> BDRV_SECTOR_BITS)
185 #define BDRV_REQUEST_MAX_BYTES (BDRV_REQUEST_MAX_SECTORS << BDRV_SECTOR_BITS)
188 * We want allow aligning requests and disk length up to any 32bit alignment
189 * and don't afraid of overflow.
190 * To achieve it, and in the same time use some pretty number as maximum disk
191 * size, let's define maximum "length" (a limit for any offset/bytes request and
192 * for disk size) to be the greatest power of 2 less than INT64_MAX.
194 #define BDRV_MAX_ALIGNMENT (1L << 30)
195 #define BDRV_MAX_LENGTH (QEMU_ALIGN_DOWN(INT64_MAX, BDRV_MAX_ALIGNMENT))
198 * Allocation status flags for bdrv_block_status() and friends.
201 * BDRV_BLOCK_DATA: allocation for data at offset is tied to this layer
202 * BDRV_BLOCK_ZERO: offset reads as zero
203 * BDRV_BLOCK_OFFSET_VALID: an associated offset exists for accessing raw data
204 * BDRV_BLOCK_ALLOCATED: the content of the block is determined by this
205 * layer rather than any backing, set by block layer
206 * BDRV_BLOCK_EOF: the returned pnum covers through end of file for this
207 * layer, set by block layer
210 * BDRV_BLOCK_RAW: for use by passthrough drivers, such as raw, to request
211 * that the block layer recompute the answer from the returned
212 * BDS; must be accompanied by just BDRV_BLOCK_OFFSET_VALID.
213 * BDRV_BLOCK_RECURSE: request that the block layer will recursively search for
214 * zeroes in file child of current block node inside
215 * returned region. Only valid together with both
216 * BDRV_BLOCK_DATA and BDRV_BLOCK_OFFSET_VALID. Should not
217 * appear with BDRV_BLOCK_ZERO.
219 * If BDRV_BLOCK_OFFSET_VALID is set, the map parameter represents the
220 * host offset within the returned BDS that is allocated for the
221 * corresponding raw guest data. However, whether that offset
222 * actually contains data also depends on BDRV_BLOCK_DATA, as follows:
224 * DATA ZERO OFFSET_VALID
225 * t t t sectors read as zero, returned file is zero at offset
226 * t f t sectors read as valid from file at offset
227 * f t t sectors preallocated, read as zero, returned file not
228 * necessarily zero at offset
229 * f f t sectors preallocated but read from backing_hd,
230 * returned file contains garbage at offset
231 * t t f sectors preallocated, read as zero, unknown offset
232 * t f f sectors read from unknown file or offset
233 * f t f not allocated or unknown offset, read as zero
234 * f f f not allocated or unknown offset, read from backing_hd
236 #define BDRV_BLOCK_DATA 0x01
237 #define BDRV_BLOCK_ZERO 0x02
238 #define BDRV_BLOCK_OFFSET_VALID 0x04
239 #define BDRV_BLOCK_RAW 0x08
240 #define BDRV_BLOCK_ALLOCATED 0x10
241 #define BDRV_BLOCK_EOF 0x20
242 #define BDRV_BLOCK_RECURSE 0x40
244 typedef QTAILQ_HEAD(BlockReopenQueue
, BlockReopenQueueEntry
) BlockReopenQueue
;
246 typedef struct BDRVReopenState
{
247 BlockDriverState
*bs
;
249 BlockdevDetectZeroesOptions detect_zeroes
;
250 bool backing_missing
;
251 BlockDriverState
*old_backing_bs
; /* keep pointer for permissions update */
252 BlockDriverState
*old_file_bs
; /* keep pointer for permissions update */
254 QDict
*explicit_options
;
259 * Block operation types
261 typedef enum BlockOpType
{
262 BLOCK_OP_TYPE_BACKUP_SOURCE
,
263 BLOCK_OP_TYPE_BACKUP_TARGET
,
264 BLOCK_OP_TYPE_CHANGE
,
265 BLOCK_OP_TYPE_COMMIT_SOURCE
,
266 BLOCK_OP_TYPE_COMMIT_TARGET
,
267 BLOCK_OP_TYPE_DATAPLANE
,
268 BLOCK_OP_TYPE_DRIVE_DEL
,
270 BLOCK_OP_TYPE_EXTERNAL_SNAPSHOT
,
271 BLOCK_OP_TYPE_INTERNAL_SNAPSHOT
,
272 BLOCK_OP_TYPE_INTERNAL_SNAPSHOT_DELETE
,
273 BLOCK_OP_TYPE_MIRROR_SOURCE
,
274 BLOCK_OP_TYPE_MIRROR_TARGET
,
275 BLOCK_OP_TYPE_RESIZE
,
276 BLOCK_OP_TYPE_STREAM
,
277 BLOCK_OP_TYPE_REPLACE
,
281 /* Block node permission constants */
284 * A user that has the "permission" of consistent reads is guaranteed that
285 * their view of the contents of the block device is complete and
286 * self-consistent, representing the contents of a disk at a specific
289 * For most block devices (including their backing files) this is true, but
290 * the property cannot be maintained in a few situations like for
291 * intermediate nodes of a commit block job.
293 BLK_PERM_CONSISTENT_READ
= 0x01,
295 /** This permission is required to change the visible disk contents. */
296 BLK_PERM_WRITE
= 0x02,
299 * This permission (which is weaker than BLK_PERM_WRITE) is both enough and
300 * required for writes to the block node when the caller promises that
301 * the visible disk content doesn't change.
303 * As the BLK_PERM_WRITE permission is strictly stronger, either is
304 * sufficient to perform an unchanging write.
306 BLK_PERM_WRITE_UNCHANGED
= 0x04,
308 /** This permission is required to change the size of a block node. */
309 BLK_PERM_RESIZE
= 0x08,
312 * There was a now-removed bit BLK_PERM_GRAPH_MOD, with value of 0x10. QEMU
313 * 6.1 and earlier may still lock the corresponding byte in block/file-posix
314 * locking. So, implementing some new permission should be very careful to
315 * not interfere with this old unused thing.
320 DEFAULT_PERM_PASSTHROUGH
= BLK_PERM_CONSISTENT_READ
322 | BLK_PERM_WRITE_UNCHANGED
325 DEFAULT_PERM_UNCHANGED
= BLK_PERM_ALL
& ~DEFAULT_PERM_PASSTHROUGH
,
329 * Flags that parent nodes assign to child nodes to specify what kind of
332 * At least one of DATA, METADATA, FILTERED, or COW must be set for
336 * = Connection with bs->children, bs->file and bs->backing fields =
340 * Filter drivers have drv->is_filter = true.
342 * Filter node has exactly one FILTERED|PRIMARY child, and may have other
343 * children which must not have these bits (one example is the
344 * copy-before-write filter, which also has its target DATA child).
346 * Filter nodes never have COW children.
348 * For most filters, the filtered child is linked in bs->file, bs->backing is
349 * NULL. For some filters (as an exception), it is the other way around; those
350 * drivers will have drv->filtered_child_is_backing set to true (see that
351 * field’s documentation for what drivers this concerns)
353 * 2. "raw" driver (block/raw-format.c)
355 * Formally it's not a filter (drv->is_filter = false)
357 * bs->backing is always NULL
359 * Only has one child, linked in bs->file. Its role is either FILTERED|PRIMARY
360 * (like filter) or DATA|PRIMARY depending on options.
364 * Don't have any FILTERED children.
366 * May have at most one COW child. In this case it's linked in bs->backing.
367 * Otherwise bs->backing is NULL. COW child is never PRIMARY.
369 * May have at most one PRIMARY child. In this case it's linked in bs->file.
370 * Otherwise bs->file is NULL.
372 * May also have some other children that don't have the PRIMARY or COW bit set.
374 enum BdrvChildRoleBits
{
376 * This child stores data.
377 * Any node may have an arbitrary number of such children.
379 BDRV_CHILD_DATA
= (1 << 0),
382 * This child stores metadata.
383 * Any node may have an arbitrary number of metadata-storing
386 BDRV_CHILD_METADATA
= (1 << 1),
389 * A child that always presents exactly the same visible data as
390 * the parent, e.g. by virtue of the parent forwarding all reads
392 * This flag is mutually exclusive with DATA, METADATA, and COW.
393 * Any node may have at most one filtered child at a time.
395 BDRV_CHILD_FILTERED
= (1 << 2),
398 * Child from which to read all data that isn't allocated in the
399 * parent (i.e., the backing child); such data is copied to the
400 * parent through COW (and optionally COR).
401 * This field is mutually exclusive with DATA, METADATA, and
403 * Any node may have at most one such backing child at a time.
405 BDRV_CHILD_COW
= (1 << 3),
408 * The primary child. For most drivers, this is the child whose
409 * filename applies best to the parent node.
410 * Any node may have at most one primary child at a time.
412 BDRV_CHILD_PRIMARY
= (1 << 4),
414 /* Useful combination of flags */
415 BDRV_CHILD_IMAGE
= BDRV_CHILD_DATA
416 | BDRV_CHILD_METADATA
417 | BDRV_CHILD_PRIMARY
,
420 /* Mask of BdrvChildRoleBits values */
421 typedef unsigned int BdrvChildRole
;
423 typedef struct BdrvCheckResult
{
427 int corruptions_fixed
;
429 int64_t image_end_offset
;
438 typedef struct BlockSizes
{
443 typedef struct HDGeometry
{
450 * Common functions that are neither I/O nor Global State.
452 * These functions must never call any function from other categories
453 * (I/O, "I/O or GS", Global State) except this one, but can be invoked by
457 char *bdrv_perm_names(uint64_t perm
);
458 uint64_t bdrv_qapi_perm_to_blk_perm(BlockPermission qapi_perm
);
460 void bdrv_init_with_whitelist(void);
461 bool bdrv_uses_whitelist(void);
462 int bdrv_is_whitelisted(BlockDriver
*drv
, bool read_only
);
464 int bdrv_parse_aio(const char *mode
, int *flags
);
465 int bdrv_parse_cache_mode(const char *mode
, int *flags
, bool *writethrough
);
466 int bdrv_parse_discard_flags(const char *mode
, int *flags
);
468 int path_has_protocol(const char *path
);
469 int path_is_absolute(const char *path
);
470 char *path_combine(const char *base_path
, const char *filename
);
472 char *bdrv_get_full_backing_filename_from_filename(const char *backed
,
476 #endif /* BLOCK_COMMON_H */