block: Introduce 'bdrv_reopen_commit_post' step
[qemu.git] / include / block / block_int.h
1 /*
2 * QEMU System Emulator block driver
3 *
4 * Copyright (c) 2003 Fabrice Bellard
5 *
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:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
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
22 * THE SOFTWARE.
23 */
24 #ifndef BLOCK_INT_H
25 #define BLOCK_INT_H
26
27 #include "block/accounting.h"
28 #include "block/block.h"
29 #include "block/aio-wait.h"
30 #include "qemu/queue.h"
31 #include "qemu/coroutine.h"
32 #include "qemu/stats64.h"
33 #include "qemu/timer.h"
34 #include "qemu/hbitmap.h"
35 #include "block/snapshot.h"
36 #include "qemu/throttle.h"
37
38 #define BLOCK_FLAG_LAZY_REFCOUNTS 8
39
40 #define BLOCK_OPT_SIZE "size"
41 #define BLOCK_OPT_ENCRYPT "encryption"
42 #define BLOCK_OPT_ENCRYPT_FORMAT "encrypt.format"
43 #define BLOCK_OPT_COMPAT6 "compat6"
44 #define BLOCK_OPT_HWVERSION "hwversion"
45 #define BLOCK_OPT_BACKING_FILE "backing_file"
46 #define BLOCK_OPT_BACKING_FMT "backing_fmt"
47 #define BLOCK_OPT_CLUSTER_SIZE "cluster_size"
48 #define BLOCK_OPT_TABLE_SIZE "table_size"
49 #define BLOCK_OPT_PREALLOC "preallocation"
50 #define BLOCK_OPT_SUBFMT "subformat"
51 #define BLOCK_OPT_COMPAT_LEVEL "compat"
52 #define BLOCK_OPT_LAZY_REFCOUNTS "lazy_refcounts"
53 #define BLOCK_OPT_ADAPTER_TYPE "adapter_type"
54 #define BLOCK_OPT_REDUNDANCY "redundancy"
55 #define BLOCK_OPT_NOCOW "nocow"
56 #define BLOCK_OPT_OBJECT_SIZE "object_size"
57 #define BLOCK_OPT_REFCOUNT_BITS "refcount_bits"
58 #define BLOCK_OPT_DATA_FILE "data_file"
59 #define BLOCK_OPT_DATA_FILE_RAW "data_file_raw"
60
61 #define BLOCK_PROBE_BUF_SIZE 512
62
63 enum BdrvTrackedRequestType {
64 BDRV_TRACKED_READ,
65 BDRV_TRACKED_WRITE,
66 BDRV_TRACKED_DISCARD,
67 BDRV_TRACKED_TRUNCATE,
68 };
69
70 typedef struct BdrvTrackedRequest {
71 BlockDriverState *bs;
72 int64_t offset;
73 uint64_t bytes;
74 enum BdrvTrackedRequestType type;
75
76 bool serialising;
77 int64_t overlap_offset;
78 uint64_t overlap_bytes;
79
80 QLIST_ENTRY(BdrvTrackedRequest) list;
81 Coroutine *co; /* owner, used for deadlock detection */
82 CoQueue wait_queue; /* coroutines blocked on this request */
83
84 struct BdrvTrackedRequest *waiting_for;
85 } BdrvTrackedRequest;
86
87 struct BlockDriver {
88 const char *format_name;
89 int instance_size;
90
91 /* set to true if the BlockDriver is a block filter. Block filters pass
92 * certain callbacks that refer to data (see block.c) to their bs->file if
93 * the driver doesn't implement them. Drivers that do not wish to forward
94 * must implement them and return -ENOTSUP.
95 */
96 bool is_filter;
97 /*
98 * Return true if @to_replace can be replaced by a BDS with the
99 * same data as @bs without it affecting @bs's behavior (that is,
100 * without it being visible to @bs's parents).
101 */
102 bool (*bdrv_recurse_can_replace)(BlockDriverState *bs,
103 BlockDriverState *to_replace);
104
105 int (*bdrv_probe)(const uint8_t *buf, int buf_size, const char *filename);
106 int (*bdrv_probe_device)(const char *filename);
107
108 /* Any driver implementing this callback is expected to be able to handle
109 * NULL file names in its .bdrv_open() implementation */
110 void (*bdrv_parse_filename)(const char *filename, QDict *options, Error **errp);
111 /* Drivers not implementing bdrv_parse_filename nor bdrv_open should have
112 * this field set to true, except ones that are defined only by their
113 * child's bs.
114 * An example of the last type will be the quorum block driver.
115 */
116 bool bdrv_needs_filename;
117
118 /* Set if a driver can support backing files */
119 bool supports_backing;
120
121 /* For handling image reopen for split or non-split files */
122 int (*bdrv_reopen_prepare)(BDRVReopenState *reopen_state,
123 BlockReopenQueue *queue, Error **errp);
124 void (*bdrv_reopen_commit)(BDRVReopenState *reopen_state);
125 void (*bdrv_reopen_commit_post)(BDRVReopenState *reopen_state);
126 void (*bdrv_reopen_abort)(BDRVReopenState *reopen_state);
127 void (*bdrv_join_options)(QDict *options, QDict *old_options);
128
129 int (*bdrv_open)(BlockDriverState *bs, QDict *options, int flags,
130 Error **errp);
131
132 /* Protocol drivers should implement this instead of bdrv_open */
133 int (*bdrv_file_open)(BlockDriverState *bs, QDict *options, int flags,
134 Error **errp);
135 void (*bdrv_close)(BlockDriverState *bs);
136 int coroutine_fn (*bdrv_co_create)(BlockdevCreateOptions *opts,
137 Error **errp);
138 int coroutine_fn (*bdrv_co_create_opts)(const char *filename,
139 QemuOpts *opts,
140 Error **errp);
141 int (*bdrv_make_empty)(BlockDriverState *bs);
142
143 /*
144 * Refreshes the bs->exact_filename field. If that is impossible,
145 * bs->exact_filename has to be left empty.
146 */
147 void (*bdrv_refresh_filename)(BlockDriverState *bs);
148
149 /*
150 * Gathers the open options for all children into @target.
151 * A simple format driver (without backing file support) might
152 * implement this function like this:
153 *
154 * QINCREF(bs->file->bs->full_open_options);
155 * qdict_put(target, "file", bs->file->bs->full_open_options);
156 *
157 * If not specified, the generic implementation will simply put
158 * all children's options under their respective name.
159 *
160 * @backing_overridden is true when bs->backing seems not to be
161 * the child that would result from opening bs->backing_file.
162 * Therefore, if it is true, the backing child's options should be
163 * gathered; otherwise, there is no need since the backing child
164 * is the one implied by the image header.
165 *
166 * Note that ideally this function would not be needed. Every
167 * block driver which implements it is probably doing something
168 * shady regarding its runtime option structure.
169 */
170 void (*bdrv_gather_child_options)(BlockDriverState *bs, QDict *target,
171 bool backing_overridden);
172
173 /*
174 * Returns an allocated string which is the directory name of this BDS: It
175 * will be used to make relative filenames absolute by prepending this
176 * function's return value to them.
177 */
178 char *(*bdrv_dirname)(BlockDriverState *bs, Error **errp);
179
180 /* aio */
181 BlockAIOCB *(*bdrv_aio_preadv)(BlockDriverState *bs,
182 uint64_t offset, uint64_t bytes, QEMUIOVector *qiov, int flags,
183 BlockCompletionFunc *cb, void *opaque);
184 BlockAIOCB *(*bdrv_aio_pwritev)(BlockDriverState *bs,
185 uint64_t offset, uint64_t bytes, QEMUIOVector *qiov, int flags,
186 BlockCompletionFunc *cb, void *opaque);
187 BlockAIOCB *(*bdrv_aio_flush)(BlockDriverState *bs,
188 BlockCompletionFunc *cb, void *opaque);
189 BlockAIOCB *(*bdrv_aio_pdiscard)(BlockDriverState *bs,
190 int64_t offset, int bytes,
191 BlockCompletionFunc *cb, void *opaque);
192
193 int coroutine_fn (*bdrv_co_readv)(BlockDriverState *bs,
194 int64_t sector_num, int nb_sectors, QEMUIOVector *qiov);
195
196 /**
197 * @offset: position in bytes to read at
198 * @bytes: number of bytes to read
199 * @qiov: the buffers to fill with read data
200 * @flags: currently unused, always 0
201 *
202 * @offset and @bytes will be a multiple of 'request_alignment',
203 * but the length of individual @qiov elements does not have to
204 * be a multiple.
205 *
206 * @bytes will always equal the total size of @qiov, and will be
207 * no larger than 'max_transfer'.
208 *
209 * The buffer in @qiov may point directly to guest memory.
210 */
211 int coroutine_fn (*bdrv_co_preadv)(BlockDriverState *bs,
212 uint64_t offset, uint64_t bytes, QEMUIOVector *qiov, int flags);
213 int coroutine_fn (*bdrv_co_preadv_part)(BlockDriverState *bs,
214 uint64_t offset, uint64_t bytes,
215 QEMUIOVector *qiov, size_t qiov_offset, int flags);
216 int coroutine_fn (*bdrv_co_writev)(BlockDriverState *bs,
217 int64_t sector_num, int nb_sectors, QEMUIOVector *qiov, int flags);
218 /**
219 * @offset: position in bytes to write at
220 * @bytes: number of bytes to write
221 * @qiov: the buffers containing data to write
222 * @flags: zero or more bits allowed by 'supported_write_flags'
223 *
224 * @offset and @bytes will be a multiple of 'request_alignment',
225 * but the length of individual @qiov elements does not have to
226 * be a multiple.
227 *
228 * @bytes will always equal the total size of @qiov, and will be
229 * no larger than 'max_transfer'.
230 *
231 * The buffer in @qiov may point directly to guest memory.
232 */
233 int coroutine_fn (*bdrv_co_pwritev)(BlockDriverState *bs,
234 uint64_t offset, uint64_t bytes, QEMUIOVector *qiov, int flags);
235 int coroutine_fn (*bdrv_co_pwritev_part)(BlockDriverState *bs,
236 uint64_t offset, uint64_t bytes,
237 QEMUIOVector *qiov, size_t qiov_offset, int flags);
238
239 /*
240 * Efficiently zero a region of the disk image. Typically an image format
241 * would use a compact metadata representation to implement this. This
242 * function pointer may be NULL or return -ENOSUP and .bdrv_co_writev()
243 * will be called instead.
244 */
245 int coroutine_fn (*bdrv_co_pwrite_zeroes)(BlockDriverState *bs,
246 int64_t offset, int bytes, BdrvRequestFlags flags);
247 int coroutine_fn (*bdrv_co_pdiscard)(BlockDriverState *bs,
248 int64_t offset, int bytes);
249
250 /* Map [offset, offset + nbytes) range onto a child of @bs to copy from,
251 * and invoke bdrv_co_copy_range_from(child, ...), or invoke
252 * bdrv_co_copy_range_to() if @bs is the leaf child to copy data from.
253 *
254 * See the comment of bdrv_co_copy_range for the parameter and return value
255 * semantics.
256 */
257 int coroutine_fn (*bdrv_co_copy_range_from)(BlockDriverState *bs,
258 BdrvChild *src,
259 uint64_t offset,
260 BdrvChild *dst,
261 uint64_t dst_offset,
262 uint64_t bytes,
263 BdrvRequestFlags read_flags,
264 BdrvRequestFlags write_flags);
265
266 /* Map [offset, offset + nbytes) range onto a child of bs to copy data to,
267 * and invoke bdrv_co_copy_range_to(child, src, ...), or perform the copy
268 * operation if @bs is the leaf and @src has the same BlockDriver. Return
269 * -ENOTSUP if @bs is the leaf but @src has a different BlockDriver.
270 *
271 * See the comment of bdrv_co_copy_range for the parameter and return value
272 * semantics.
273 */
274 int coroutine_fn (*bdrv_co_copy_range_to)(BlockDriverState *bs,
275 BdrvChild *src,
276 uint64_t src_offset,
277 BdrvChild *dst,
278 uint64_t dst_offset,
279 uint64_t bytes,
280 BdrvRequestFlags read_flags,
281 BdrvRequestFlags write_flags);
282
283 /*
284 * Building block for bdrv_block_status[_above] and
285 * bdrv_is_allocated[_above]. The driver should answer only
286 * according to the current layer, and should only need to set
287 * BDRV_BLOCK_DATA, BDRV_BLOCK_ZERO, BDRV_BLOCK_OFFSET_VALID,
288 * and/or BDRV_BLOCK_RAW; if the current layer defers to a backing
289 * layer, the result should be 0 (and not BDRV_BLOCK_ZERO). See
290 * block.h for the overall meaning of the bits. As a hint, the
291 * flag want_zero is true if the caller cares more about precise
292 * mappings (favor accurate _OFFSET_VALID/_ZERO) or false for
293 * overall allocation (favor larger *pnum, perhaps by reporting
294 * _DATA instead of _ZERO). The block layer guarantees input
295 * clamped to bdrv_getlength() and aligned to request_alignment,
296 * as well as non-NULL pnum, map, and file; in turn, the driver
297 * must return an error or set pnum to an aligned non-zero value.
298 */
299 int coroutine_fn (*bdrv_co_block_status)(BlockDriverState *bs,
300 bool want_zero, int64_t offset, int64_t bytes, int64_t *pnum,
301 int64_t *map, BlockDriverState **file);
302
303 /*
304 * Invalidate any cached meta-data.
305 */
306 void coroutine_fn (*bdrv_co_invalidate_cache)(BlockDriverState *bs,
307 Error **errp);
308 int (*bdrv_inactivate)(BlockDriverState *bs);
309
310 /*
311 * Flushes all data for all layers by calling bdrv_co_flush for underlying
312 * layers, if needed. This function is needed for deterministic
313 * synchronization of the flush finishing callback.
314 */
315 int coroutine_fn (*bdrv_co_flush)(BlockDriverState *bs);
316
317 /*
318 * Flushes all data that was already written to the OS all the way down to
319 * the disk (for example file-posix.c calls fsync()).
320 */
321 int coroutine_fn (*bdrv_co_flush_to_disk)(BlockDriverState *bs);
322
323 /*
324 * Flushes all internal caches to the OS. The data may still sit in a
325 * writeback cache of the host OS, but it will survive a crash of the qemu
326 * process.
327 */
328 int coroutine_fn (*bdrv_co_flush_to_os)(BlockDriverState *bs);
329
330 /*
331 * Drivers setting this field must be able to work with just a plain
332 * filename with '<protocol_name>:' as a prefix, and no other options.
333 * Options may be extracted from the filename by implementing
334 * bdrv_parse_filename.
335 */
336 const char *protocol_name;
337
338 /*
339 * Truncate @bs to @offset bytes using the given @prealloc mode
340 * when growing. Modes other than PREALLOC_MODE_OFF should be
341 * rejected when shrinking @bs.
342 *
343 * If @exact is true, @bs must be resized to exactly @offset.
344 * Otherwise, it is sufficient for @bs (if it is a host block
345 * device and thus there is no way to resize it) to be at least
346 * @offset bytes in length.
347 *
348 * If @exact is true and this function fails but would succeed
349 * with @exact = false, it should return -ENOTSUP.
350 */
351 int coroutine_fn (*bdrv_co_truncate)(BlockDriverState *bs, int64_t offset,
352 bool exact, PreallocMode prealloc,
353 Error **errp);
354
355 int64_t (*bdrv_getlength)(BlockDriverState *bs);
356 bool has_variable_length;
357 int64_t (*bdrv_get_allocated_file_size)(BlockDriverState *bs);
358 BlockMeasureInfo *(*bdrv_measure)(QemuOpts *opts, BlockDriverState *in_bs,
359 Error **errp);
360
361 int coroutine_fn (*bdrv_co_pwritev_compressed)(BlockDriverState *bs,
362 uint64_t offset, uint64_t bytes, QEMUIOVector *qiov);
363 int coroutine_fn (*bdrv_co_pwritev_compressed_part)(BlockDriverState *bs,
364 uint64_t offset, uint64_t bytes, QEMUIOVector *qiov,
365 size_t qiov_offset);
366
367 int (*bdrv_snapshot_create)(BlockDriverState *bs,
368 QEMUSnapshotInfo *sn_info);
369 int (*bdrv_snapshot_goto)(BlockDriverState *bs,
370 const char *snapshot_id);
371 int (*bdrv_snapshot_delete)(BlockDriverState *bs,
372 const char *snapshot_id,
373 const char *name,
374 Error **errp);
375 int (*bdrv_snapshot_list)(BlockDriverState *bs,
376 QEMUSnapshotInfo **psn_info);
377 int (*bdrv_snapshot_load_tmp)(BlockDriverState *bs,
378 const char *snapshot_id,
379 const char *name,
380 Error **errp);
381 int (*bdrv_get_info)(BlockDriverState *bs, BlockDriverInfo *bdi);
382 ImageInfoSpecific *(*bdrv_get_specific_info)(BlockDriverState *bs,
383 Error **errp);
384 BlockStatsSpecific *(*bdrv_get_specific_stats)(BlockDriverState *bs);
385
386 int coroutine_fn (*bdrv_save_vmstate)(BlockDriverState *bs,
387 QEMUIOVector *qiov,
388 int64_t pos);
389 int coroutine_fn (*bdrv_load_vmstate)(BlockDriverState *bs,
390 QEMUIOVector *qiov,
391 int64_t pos);
392
393 int (*bdrv_change_backing_file)(BlockDriverState *bs,
394 const char *backing_file, const char *backing_fmt);
395
396 /* removable device specific */
397 bool (*bdrv_is_inserted)(BlockDriverState *bs);
398 void (*bdrv_eject)(BlockDriverState *bs, bool eject_flag);
399 void (*bdrv_lock_medium)(BlockDriverState *bs, bool locked);
400
401 /* to control generic scsi devices */
402 BlockAIOCB *(*bdrv_aio_ioctl)(BlockDriverState *bs,
403 unsigned long int req, void *buf,
404 BlockCompletionFunc *cb, void *opaque);
405 int coroutine_fn (*bdrv_co_ioctl)(BlockDriverState *bs,
406 unsigned long int req, void *buf);
407
408 /* List of options for creating images, terminated by name == NULL */
409 QemuOptsList *create_opts;
410 /*
411 * If this driver supports reopening images this contains a
412 * NULL-terminated list of the runtime options that can be
413 * modified. If an option in this list is unspecified during
414 * reopen then it _must_ be reset to its default value or return
415 * an error.
416 */
417 const char *const *mutable_opts;
418
419 /*
420 * Returns 0 for completed check, -errno for internal errors.
421 * The check results are stored in result.
422 */
423 int coroutine_fn (*bdrv_co_check)(BlockDriverState *bs,
424 BdrvCheckResult *result,
425 BdrvCheckMode fix);
426
427 int (*bdrv_amend_options)(BlockDriverState *bs, QemuOpts *opts,
428 BlockDriverAmendStatusCB *status_cb,
429 void *cb_opaque,
430 Error **errp);
431
432 void (*bdrv_debug_event)(BlockDriverState *bs, BlkdebugEvent event);
433
434 /* TODO Better pass a option string/QDict/QemuOpts to add any rule? */
435 int (*bdrv_debug_breakpoint)(BlockDriverState *bs, const char *event,
436 const char *tag);
437 int (*bdrv_debug_remove_breakpoint)(BlockDriverState *bs,
438 const char *tag);
439 int (*bdrv_debug_resume)(BlockDriverState *bs, const char *tag);
440 bool (*bdrv_debug_is_suspended)(BlockDriverState *bs, const char *tag);
441
442 void (*bdrv_refresh_limits)(BlockDriverState *bs, Error **errp);
443
444 /*
445 * Returns 1 if newly created images are guaranteed to contain only
446 * zeros, 0 otherwise.
447 * Must return 0 if .bdrv_has_zero_init_truncate() returns 0.
448 */
449 int (*bdrv_has_zero_init)(BlockDriverState *bs);
450
451 /*
452 * Returns 1 if new areas added by growing the image with
453 * PREALLOC_MODE_OFF contain only zeros, 0 otherwise.
454 */
455 int (*bdrv_has_zero_init_truncate)(BlockDriverState *bs);
456
457 /* Remove fd handlers, timers, and other event loop callbacks so the event
458 * loop is no longer in use. Called with no in-flight requests and in
459 * depth-first traversal order with parents before child nodes.
460 */
461 void (*bdrv_detach_aio_context)(BlockDriverState *bs);
462
463 /* Add fd handlers, timers, and other event loop callbacks so I/O requests
464 * can be processed again. Called with no in-flight requests and in
465 * depth-first traversal order with child nodes before parent nodes.
466 */
467 void (*bdrv_attach_aio_context)(BlockDriverState *bs,
468 AioContext *new_context);
469
470 /* io queue for linux-aio */
471 void (*bdrv_io_plug)(BlockDriverState *bs);
472 void (*bdrv_io_unplug)(BlockDriverState *bs);
473
474 /**
475 * Try to get @bs's logical and physical block size.
476 * On success, store them in @bsz and return zero.
477 * On failure, return negative errno.
478 */
479 int (*bdrv_probe_blocksizes)(BlockDriverState *bs, BlockSizes *bsz);
480 /**
481 * Try to get @bs's geometry (cyls, heads, sectors)
482 * On success, store them in @geo and return 0.
483 * On failure return -errno.
484 * Only drivers that want to override guest geometry implement this
485 * callback; see hd_geometry_guess().
486 */
487 int (*bdrv_probe_geometry)(BlockDriverState *bs, HDGeometry *geo);
488
489 /**
490 * bdrv_co_drain_begin is called if implemented in the beginning of a
491 * drain operation to drain and stop any internal sources of requests in
492 * the driver.
493 * bdrv_co_drain_end is called if implemented at the end of the drain.
494 *
495 * They should be used by the driver to e.g. manage scheduled I/O
496 * requests, or toggle an internal state. After the end of the drain new
497 * requests will continue normally.
498 */
499 void coroutine_fn (*bdrv_co_drain_begin)(BlockDriverState *bs);
500 void coroutine_fn (*bdrv_co_drain_end)(BlockDriverState *bs);
501
502 void (*bdrv_add_child)(BlockDriverState *parent, BlockDriverState *child,
503 Error **errp);
504 void (*bdrv_del_child)(BlockDriverState *parent, BdrvChild *child,
505 Error **errp);
506
507 /**
508 * Informs the block driver that a permission change is intended. The
509 * driver checks whether the change is permissible and may take other
510 * preparations for the change (e.g. get file system locks). This operation
511 * is always followed either by a call to either .bdrv_set_perm or
512 * .bdrv_abort_perm_update.
513 *
514 * Checks whether the requested set of cumulative permissions in @perm
515 * can be granted for accessing @bs and whether no other users are using
516 * permissions other than those given in @shared (both arguments take
517 * BLK_PERM_* bitmasks).
518 *
519 * If both conditions are met, 0 is returned. Otherwise, -errno is returned
520 * and errp is set to an error describing the conflict.
521 */
522 int (*bdrv_check_perm)(BlockDriverState *bs, uint64_t perm,
523 uint64_t shared, Error **errp);
524
525 /**
526 * Called to inform the driver that the set of cumulative set of used
527 * permissions for @bs has changed to @perm, and the set of sharable
528 * permission to @shared. The driver can use this to propagate changes to
529 * its children (i.e. request permissions only if a parent actually needs
530 * them).
531 *
532 * This function is only invoked after bdrv_check_perm(), so block drivers
533 * may rely on preparations made in their .bdrv_check_perm implementation.
534 */
535 void (*bdrv_set_perm)(BlockDriverState *bs, uint64_t perm, uint64_t shared);
536
537 /*
538 * Called to inform the driver that after a previous bdrv_check_perm()
539 * call, the permission update is not performed and any preparations made
540 * for it (e.g. taken file locks) need to be undone.
541 *
542 * This function can be called even for nodes that never saw a
543 * bdrv_check_perm() call. It is a no-op then.
544 */
545 void (*bdrv_abort_perm_update)(BlockDriverState *bs);
546
547 /**
548 * Returns in @nperm and @nshared the permissions that the driver for @bs
549 * needs on its child @c, based on the cumulative permissions requested by
550 * the parents in @parent_perm and @parent_shared.
551 *
552 * If @c is NULL, return the permissions for attaching a new child for the
553 * given @role.
554 *
555 * If @reopen_queue is non-NULL, don't return the currently needed
556 * permissions, but those that will be needed after applying the
557 * @reopen_queue.
558 */
559 void (*bdrv_child_perm)(BlockDriverState *bs, BdrvChild *c,
560 const BdrvChildRole *role,
561 BlockReopenQueue *reopen_queue,
562 uint64_t parent_perm, uint64_t parent_shared,
563 uint64_t *nperm, uint64_t *nshared);
564
565 bool (*bdrv_co_can_store_new_dirty_bitmap)(BlockDriverState *bs,
566 const char *name,
567 uint32_t granularity,
568 Error **errp);
569 int (*bdrv_co_remove_persistent_dirty_bitmap)(BlockDriverState *bs,
570 const char *name,
571 Error **errp);
572
573 /**
574 * Register/unregister a buffer for I/O. For example, when the driver is
575 * interested to know the memory areas that will later be used in iovs, so
576 * that it can do IOMMU mapping with VFIO etc., in order to get better
577 * performance. In the case of VFIO drivers, this callback is used to do
578 * DMA mapping for hot buffers.
579 */
580 void (*bdrv_register_buf)(BlockDriverState *bs, void *host, size_t size);
581 void (*bdrv_unregister_buf)(BlockDriverState *bs, void *host);
582 QLIST_ENTRY(BlockDriver) list;
583
584 /* Pointer to a NULL-terminated array of names of strong options
585 * that can be specified for bdrv_open(). A strong option is one
586 * that changes the data of a BDS.
587 * If this pointer is NULL, the array is considered empty.
588 * "filename" and "driver" are always considered strong. */
589 const char *const *strong_runtime_opts;
590 };
591
592 static inline bool block_driver_can_compress(BlockDriver *drv)
593 {
594 return drv->bdrv_co_pwritev_compressed ||
595 drv->bdrv_co_pwritev_compressed_part;
596 }
597
598 typedef struct BlockLimits {
599 /* Alignment requirement, in bytes, for offset/length of I/O
600 * requests. Must be a power of 2 less than INT_MAX; defaults to
601 * 1 for drivers with modern byte interfaces, and to 512
602 * otherwise. */
603 uint32_t request_alignment;
604
605 /* Maximum number of bytes that can be discarded at once (since it
606 * is signed, it must be < 2G, if set). Must be multiple of
607 * pdiscard_alignment, but need not be power of 2. May be 0 if no
608 * inherent 32-bit limit */
609 int32_t max_pdiscard;
610
611 /* Optimal alignment for discard requests in bytes. A power of 2
612 * is best but not mandatory. Must be a multiple of
613 * bl.request_alignment, and must be less than max_pdiscard if
614 * that is set. May be 0 if bl.request_alignment is good enough */
615 uint32_t pdiscard_alignment;
616
617 /* Maximum number of bytes that can zeroized at once (since it is
618 * signed, it must be < 2G, if set). Must be multiple of
619 * pwrite_zeroes_alignment. May be 0 if no inherent 32-bit limit */
620 int32_t max_pwrite_zeroes;
621
622 /* Optimal alignment for write zeroes requests in bytes. A power
623 * of 2 is best but not mandatory. Must be a multiple of
624 * bl.request_alignment, and must be less than max_pwrite_zeroes
625 * if that is set. May be 0 if bl.request_alignment is good
626 * enough */
627 uint32_t pwrite_zeroes_alignment;
628
629 /* Optimal transfer length in bytes. A power of 2 is best but not
630 * mandatory. Must be a multiple of bl.request_alignment, or 0 if
631 * no preferred size */
632 uint32_t opt_transfer;
633
634 /* Maximal transfer length in bytes. Need not be power of 2, but
635 * must be multiple of opt_transfer and bl.request_alignment, or 0
636 * for no 32-bit limit. For now, anything larger than INT_MAX is
637 * clamped down. */
638 uint32_t max_transfer;
639
640 /* memory alignment, in bytes so that no bounce buffer is needed */
641 size_t min_mem_alignment;
642
643 /* memory alignment, in bytes, for bounce buffer */
644 size_t opt_mem_alignment;
645
646 /* maximum number of iovec elements */
647 int max_iov;
648 } BlockLimits;
649
650 typedef struct BdrvOpBlocker BdrvOpBlocker;
651
652 typedef struct BdrvAioNotifier {
653 void (*attached_aio_context)(AioContext *new_context, void *opaque);
654 void (*detach_aio_context)(void *opaque);
655
656 void *opaque;
657 bool deleted;
658
659 QLIST_ENTRY(BdrvAioNotifier) list;
660 } BdrvAioNotifier;
661
662 struct BdrvChildRole {
663 /* If true, bdrv_replace_node() doesn't change the node this BdrvChild
664 * points to. */
665 bool stay_at_node;
666
667 /* If true, the parent is a BlockDriverState and bdrv_next_all_states()
668 * will return it. This information is used for drain_all, where every node
669 * will be drained separately, so the drain only needs to be propagated to
670 * non-BDS parents. */
671 bool parent_is_bds;
672
673 void (*inherit_options)(int *child_flags, QDict *child_options,
674 int parent_flags, QDict *parent_options);
675
676 void (*change_media)(BdrvChild *child, bool load);
677 void (*resize)(BdrvChild *child);
678
679 /* Returns a name that is supposedly more useful for human users than the
680 * node name for identifying the node in question (in particular, a BB
681 * name), or NULL if the parent can't provide a better name. */
682 const char *(*get_name)(BdrvChild *child);
683
684 /* Returns a malloced string that describes the parent of the child for a
685 * human reader. This could be a node-name, BlockBackend name, qdev ID or
686 * QOM path of the device owning the BlockBackend, job type and ID etc. The
687 * caller is responsible for freeing the memory. */
688 char *(*get_parent_desc)(BdrvChild *child);
689
690 /*
691 * If this pair of functions is implemented, the parent doesn't issue new
692 * requests after returning from .drained_begin() until .drained_end() is
693 * called.
694 *
695 * These functions must not change the graph (and therefore also must not
696 * call aio_poll(), which could change the graph indirectly).
697 *
698 * If drained_end() schedules background operations, it must atomically
699 * increment *drained_end_counter for each such operation and atomically
700 * decrement it once the operation has settled.
701 *
702 * Note that this can be nested. If drained_begin() was called twice, new
703 * I/O is allowed only after drained_end() was called twice, too.
704 */
705 void (*drained_begin)(BdrvChild *child);
706 void (*drained_end)(BdrvChild *child, int *drained_end_counter);
707
708 /*
709 * Returns whether the parent has pending requests for the child. This
710 * callback is polled after .drained_begin() has been called until all
711 * activity on the child has stopped.
712 */
713 bool (*drained_poll)(BdrvChild *child);
714
715 /* Notifies the parent that the child has been activated/inactivated (e.g.
716 * when migration is completing) and it can start/stop requesting
717 * permissions and doing I/O on it. */
718 void (*activate)(BdrvChild *child, Error **errp);
719 int (*inactivate)(BdrvChild *child);
720
721 void (*attach)(BdrvChild *child);
722 void (*detach)(BdrvChild *child);
723
724 /* Notifies the parent that the filename of its child has changed (e.g.
725 * because the direct child was removed from the backing chain), so that it
726 * can update its reference. */
727 int (*update_filename)(BdrvChild *child, BlockDriverState *new_base,
728 const char *filename, Error **errp);
729
730 bool (*can_set_aio_ctx)(BdrvChild *child, AioContext *ctx,
731 GSList **ignore, Error **errp);
732 void (*set_aio_ctx)(BdrvChild *child, AioContext *ctx, GSList **ignore);
733 };
734
735 extern const BdrvChildRole child_file;
736 extern const BdrvChildRole child_format;
737 extern const BdrvChildRole child_backing;
738
739 struct BdrvChild {
740 BlockDriverState *bs;
741 char *name;
742 const BdrvChildRole *role;
743 void *opaque;
744
745 /**
746 * Granted permissions for operating on this BdrvChild (BLK_PERM_* bitmask)
747 */
748 uint64_t perm;
749
750 /**
751 * Permissions that can still be granted to other users of @bs while this
752 * BdrvChild is still attached to it. (BLK_PERM_* bitmask)
753 */
754 uint64_t shared_perm;
755
756 /* backup of permissions during permission update procedure */
757 bool has_backup_perm;
758 uint64_t backup_perm;
759 uint64_t backup_shared_perm;
760
761 /*
762 * This link is frozen: the child can neither be replaced nor
763 * detached from the parent.
764 */
765 bool frozen;
766
767 /*
768 * How many times the parent of this child has been drained
769 * (through role->drained_*).
770 * Usually, this is equal to bs->quiesce_counter (potentially
771 * reduced by bdrv_drain_all_count). It may differ while the
772 * child is entering or leaving a drained section.
773 */
774 int parent_quiesce_counter;
775
776 QLIST_ENTRY(BdrvChild) next;
777 QLIST_ENTRY(BdrvChild) next_parent;
778 };
779
780 /*
781 * Note: the function bdrv_append() copies and swaps contents of
782 * BlockDriverStates, so if you add new fields to this struct, please
783 * inspect bdrv_append() to determine if the new fields need to be
784 * copied as well.
785 */
786 struct BlockDriverState {
787 /* Protected by big QEMU lock or read-only after opening. No special
788 * locking needed during I/O...
789 */
790 int open_flags; /* flags used to open the file, re-used for re-open */
791 bool read_only; /* if true, the media is read only */
792 bool encrypted; /* if true, the media is encrypted */
793 bool sg; /* if true, the device is a /dev/sg* */
794 bool probed; /* if true, format was probed rather than specified */
795 bool force_share; /* if true, always allow all shared permissions */
796 bool implicit; /* if true, this filter node was automatically inserted */
797
798 BlockDriver *drv; /* NULL means no media */
799 void *opaque;
800
801 AioContext *aio_context; /* event loop used for fd handlers, timers, etc */
802 /* long-running tasks intended to always use the same AioContext as this
803 * BDS may register themselves in this list to be notified of changes
804 * regarding this BDS's context */
805 QLIST_HEAD(, BdrvAioNotifier) aio_notifiers;
806 bool walking_aio_notifiers; /* to make removal during iteration safe */
807
808 char filename[PATH_MAX];
809 char backing_file[PATH_MAX]; /* if non zero, the image is a diff of
810 this file image */
811 /* The backing filename indicated by the image header; if we ever
812 * open this file, then this is replaced by the resulting BDS's
813 * filename (i.e. after a bdrv_refresh_filename() run). */
814 char auto_backing_file[PATH_MAX];
815 char backing_format[16]; /* if non-zero and backing_file exists */
816
817 QDict *full_open_options;
818 char exact_filename[PATH_MAX];
819
820 BdrvChild *backing;
821 BdrvChild *file;
822
823 /* I/O Limits */
824 BlockLimits bl;
825
826 /* Flags honored during pwrite (so far: BDRV_REQ_FUA,
827 * BDRV_REQ_WRITE_UNCHANGED).
828 * If a driver does not support BDRV_REQ_WRITE_UNCHANGED, those
829 * writes will be issued as normal writes without the flag set.
830 * This is important to note for drivers that do not explicitly
831 * request a WRITE permission for their children and instead take
832 * the same permissions as their parent did (this is commonly what
833 * block filters do). Such drivers have to be aware that the
834 * parent may have taken a WRITE_UNCHANGED permission only and is
835 * issuing such requests. Drivers either must make sure that
836 * these requests do not result in plain WRITE accesses (usually
837 * by supporting BDRV_REQ_WRITE_UNCHANGED, and then forwarding
838 * every incoming write request as-is, including potentially that
839 * flag), or they have to explicitly take the WRITE permission for
840 * their children. */
841 unsigned int supported_write_flags;
842 /* Flags honored during pwrite_zeroes (so far: BDRV_REQ_FUA,
843 * BDRV_REQ_MAY_UNMAP, BDRV_REQ_WRITE_UNCHANGED) */
844 unsigned int supported_zero_flags;
845
846 /* the following member gives a name to every node on the bs graph. */
847 char node_name[32];
848 /* element of the list of named nodes building the graph */
849 QTAILQ_ENTRY(BlockDriverState) node_list;
850 /* element of the list of all BlockDriverStates (all_bdrv_states) */
851 QTAILQ_ENTRY(BlockDriverState) bs_list;
852 /* element of the list of monitor-owned BDS */
853 QTAILQ_ENTRY(BlockDriverState) monitor_list;
854 int refcnt;
855
856 /* operation blockers */
857 QLIST_HEAD(, BdrvOpBlocker) op_blockers[BLOCK_OP_TYPE_MAX];
858
859 /* The node that this node inherited default options from (and a reopen on
860 * which can affect this node by changing these defaults). This is always a
861 * parent node of this node. */
862 BlockDriverState *inherits_from;
863 QLIST_HEAD(, BdrvChild) children;
864 QLIST_HEAD(, BdrvChild) parents;
865
866 QDict *options;
867 QDict *explicit_options;
868 BlockdevDetectZeroesOptions detect_zeroes;
869
870 /* The error object in use for blocking operations on backing_hd */
871 Error *backing_blocker;
872
873 /* Protected by AioContext lock */
874
875 /* If we are reading a disk image, give its size in sectors.
876 * Generally read-only; it is written to by load_snapshot and
877 * save_snaphost, but the block layer is quiescent during those.
878 */
879 int64_t total_sectors;
880
881 /* Callback before write request is processed */
882 NotifierWithReturnList before_write_notifiers;
883
884 /* threshold limit for writes, in bytes. "High water mark". */
885 uint64_t write_threshold_offset;
886 NotifierWithReturn write_threshold_notifier;
887
888 /* Writing to the list requires the BQL _and_ the dirty_bitmap_mutex.
889 * Reading from the list can be done with either the BQL or the
890 * dirty_bitmap_mutex. Modifying a bitmap only requires
891 * dirty_bitmap_mutex. */
892 QemuMutex dirty_bitmap_mutex;
893 QLIST_HEAD(, BdrvDirtyBitmap) dirty_bitmaps;
894
895 /* Offset after the highest byte written to */
896 Stat64 wr_highest_offset;
897
898 /* If true, copy read backing sectors into image. Can be >1 if more
899 * than one client has requested copy-on-read. Accessed with atomic
900 * ops.
901 */
902 int copy_on_read;
903
904 /* number of in-flight requests; overall and serialising.
905 * Accessed with atomic ops.
906 */
907 unsigned int in_flight;
908 unsigned int serialising_in_flight;
909
910 /* counter for nested bdrv_io_plug.
911 * Accessed with atomic ops.
912 */
913 unsigned io_plugged;
914
915 /* do we need to tell the quest if we have a volatile write cache? */
916 int enable_write_cache;
917
918 /* Accessed with atomic ops. */
919 int quiesce_counter;
920 int recursive_quiesce_counter;
921
922 unsigned int write_gen; /* Current data generation */
923
924 /* Protected by reqs_lock. */
925 CoMutex reqs_lock;
926 QLIST_HEAD(, BdrvTrackedRequest) tracked_requests;
927 CoQueue flush_queue; /* Serializing flush queue */
928 bool active_flush_req; /* Flush request in flight? */
929
930 /* Only read/written by whoever has set active_flush_req to true. */
931 unsigned int flushed_gen; /* Flushed write generation */
932
933 /* BdrvChild links to this node may never be frozen */
934 bool never_freeze;
935 };
936
937 struct BlockBackendRootState {
938 int open_flags;
939 bool read_only;
940 BlockdevDetectZeroesOptions detect_zeroes;
941 };
942
943 typedef enum BlockMirrorBackingMode {
944 /* Reuse the existing backing chain from the source for the target.
945 * - sync=full: Set backing BDS to NULL.
946 * - sync=top: Use source's backing BDS.
947 * - sync=none: Use source as the backing BDS. */
948 MIRROR_SOURCE_BACKING_CHAIN,
949
950 /* Open the target's backing chain completely anew */
951 MIRROR_OPEN_BACKING_CHAIN,
952
953 /* Do not change the target's backing BDS after job completion */
954 MIRROR_LEAVE_BACKING_CHAIN,
955 } BlockMirrorBackingMode;
956
957 static inline BlockDriverState *backing_bs(BlockDriverState *bs)
958 {
959 return bs->backing ? bs->backing->bs : NULL;
960 }
961
962
963 /* Essential block drivers which must always be statically linked into qemu, and
964 * which therefore can be accessed without using bdrv_find_format() */
965 extern BlockDriver bdrv_file;
966 extern BlockDriver bdrv_raw;
967 extern BlockDriver bdrv_qcow2;
968
969 int coroutine_fn bdrv_co_preadv(BdrvChild *child,
970 int64_t offset, unsigned int bytes, QEMUIOVector *qiov,
971 BdrvRequestFlags flags);
972 int coroutine_fn bdrv_co_preadv_part(BdrvChild *child,
973 int64_t offset, unsigned int bytes,
974 QEMUIOVector *qiov, size_t qiov_offset, BdrvRequestFlags flags);
975 int coroutine_fn bdrv_co_pwritev(BdrvChild *child,
976 int64_t offset, unsigned int bytes, QEMUIOVector *qiov,
977 BdrvRequestFlags flags);
978 int coroutine_fn bdrv_co_pwritev_part(BdrvChild *child,
979 int64_t offset, unsigned int bytes,
980 QEMUIOVector *qiov, size_t qiov_offset, BdrvRequestFlags flags);
981
982 static inline int coroutine_fn bdrv_co_pread(BdrvChild *child,
983 int64_t offset, unsigned int bytes, void *buf, BdrvRequestFlags flags)
984 {
985 QEMUIOVector qiov = QEMU_IOVEC_INIT_BUF(qiov, buf, bytes);
986
987 return bdrv_co_preadv(child, offset, bytes, &qiov, flags);
988 }
989
990 static inline int coroutine_fn bdrv_co_pwrite(BdrvChild *child,
991 int64_t offset, unsigned int bytes, void *buf, BdrvRequestFlags flags)
992 {
993 QEMUIOVector qiov = QEMU_IOVEC_INIT_BUF(qiov, buf, bytes);
994
995 return bdrv_co_pwritev(child, offset, bytes, &qiov, flags);
996 }
997
998 extern unsigned int bdrv_drain_all_count;
999 void bdrv_apply_subtree_drain(BdrvChild *child, BlockDriverState *new_parent);
1000 void bdrv_unapply_subtree_drain(BdrvChild *child, BlockDriverState *old_parent);
1001
1002 bool coroutine_fn bdrv_mark_request_serialising(BdrvTrackedRequest *req, uint64_t align);
1003 BdrvTrackedRequest *coroutine_fn bdrv_co_get_self_request(BlockDriverState *bs);
1004
1005 int get_tmp_filename(char *filename, int size);
1006 BlockDriver *bdrv_probe_all(const uint8_t *buf, int buf_size,
1007 const char *filename);
1008
1009 void bdrv_parse_filename_strip_prefix(const char *filename, const char *prefix,
1010 QDict *options);
1011
1012
1013 /**
1014 * bdrv_add_before_write_notifier:
1015 *
1016 * Register a callback that is invoked before write requests are processed but
1017 * after any throttling or waiting for overlapping requests.
1018 */
1019 void bdrv_add_before_write_notifier(BlockDriverState *bs,
1020 NotifierWithReturn *notifier);
1021
1022 /**
1023 * bdrv_add_aio_context_notifier:
1024 *
1025 * If a long-running job intends to be always run in the same AioContext as a
1026 * certain BDS, it may use this function to be notified of changes regarding the
1027 * association of the BDS to an AioContext.
1028 *
1029 * attached_aio_context() is called after the target BDS has been attached to a
1030 * new AioContext; detach_aio_context() is called before the target BDS is being
1031 * detached from its old AioContext.
1032 */
1033 void bdrv_add_aio_context_notifier(BlockDriverState *bs,
1034 void (*attached_aio_context)(AioContext *new_context, void *opaque),
1035 void (*detach_aio_context)(void *opaque), void *opaque);
1036
1037 /**
1038 * bdrv_remove_aio_context_notifier:
1039 *
1040 * Unsubscribe of change notifications regarding the BDS's AioContext. The
1041 * parameters given here have to be the same as those given to
1042 * bdrv_add_aio_context_notifier().
1043 */
1044 void bdrv_remove_aio_context_notifier(BlockDriverState *bs,
1045 void (*aio_context_attached)(AioContext *,
1046 void *),
1047 void (*aio_context_detached)(void *),
1048 void *opaque);
1049
1050 /**
1051 * bdrv_wakeup:
1052 * @bs: The BlockDriverState for which an I/O operation has been completed.
1053 *
1054 * Wake up the main thread if it is waiting on BDRV_POLL_WHILE. During
1055 * synchronous I/O on a BlockDriverState that is attached to another
1056 * I/O thread, the main thread lets the I/O thread's event loop run,
1057 * waiting for the I/O operation to complete. A bdrv_wakeup will wake
1058 * up the main thread if necessary.
1059 *
1060 * Manual calls to bdrv_wakeup are rarely necessary, because
1061 * bdrv_dec_in_flight already calls it.
1062 */
1063 void bdrv_wakeup(BlockDriverState *bs);
1064
1065 #ifdef _WIN32
1066 int is_windows_drive(const char *filename);
1067 #endif
1068
1069 /**
1070 * stream_start:
1071 * @job_id: The id of the newly-created job, or %NULL to use the
1072 * device name of @bs.
1073 * @bs: Block device to operate on.
1074 * @base: Block device that will become the new base, or %NULL to
1075 * flatten the whole backing file chain onto @bs.
1076 * @backing_file_str: The file name that will be written to @bs as the
1077 * the new backing file if the job completes. Ignored if @base is %NULL.
1078 * @creation_flags: Flags that control the behavior of the Job lifetime.
1079 * See @BlockJobCreateFlags
1080 * @speed: The maximum speed, in bytes per second, or 0 for unlimited.
1081 * @on_error: The action to take upon error.
1082 * @errp: Error object.
1083 *
1084 * Start a streaming operation on @bs. Clusters that are unallocated
1085 * in @bs, but allocated in any image between @base and @bs (both
1086 * exclusive) will be written to @bs. At the end of a successful
1087 * streaming job, the backing file of @bs will be changed to
1088 * @backing_file_str in the written image and to @base in the live
1089 * BlockDriverState.
1090 */
1091 void stream_start(const char *job_id, BlockDriverState *bs,
1092 BlockDriverState *base, const char *backing_file_str,
1093 int creation_flags, int64_t speed,
1094 BlockdevOnError on_error, Error **errp);
1095
1096 /**
1097 * commit_start:
1098 * @job_id: The id of the newly-created job, or %NULL to use the
1099 * device name of @bs.
1100 * @bs: Active block device.
1101 * @top: Top block device to be committed.
1102 * @base: Block device that will be written into, and become the new top.
1103 * @creation_flags: Flags that control the behavior of the Job lifetime.
1104 * See @BlockJobCreateFlags
1105 * @speed: The maximum speed, in bytes per second, or 0 for unlimited.
1106 * @on_error: The action to take upon error.
1107 * @backing_file_str: String to use as the backing file in @top's overlay
1108 * @filter_node_name: The node name that should be assigned to the filter
1109 * driver that the commit job inserts into the graph above @top. NULL means
1110 * that a node name should be autogenerated.
1111 * @errp: Error object.
1112 *
1113 */
1114 void commit_start(const char *job_id, BlockDriverState *bs,
1115 BlockDriverState *base, BlockDriverState *top,
1116 int creation_flags, int64_t speed,
1117 BlockdevOnError on_error, const char *backing_file_str,
1118 const char *filter_node_name, Error **errp);
1119 /**
1120 * commit_active_start:
1121 * @job_id: The id of the newly-created job, or %NULL to use the
1122 * device name of @bs.
1123 * @bs: Active block device to be committed.
1124 * @base: Block device that will be written into, and become the new top.
1125 * @creation_flags: Flags that control the behavior of the Job lifetime.
1126 * See @BlockJobCreateFlags
1127 * @speed: The maximum speed, in bytes per second, or 0 for unlimited.
1128 * @on_error: The action to take upon error.
1129 * @filter_node_name: The node name that should be assigned to the filter
1130 * driver that the commit job inserts into the graph above @bs. NULL means that
1131 * a node name should be autogenerated.
1132 * @cb: Completion function for the job.
1133 * @opaque: Opaque pointer value passed to @cb.
1134 * @auto_complete: Auto complete the job.
1135 * @errp: Error object.
1136 *
1137 */
1138 BlockJob *commit_active_start(const char *job_id, BlockDriverState *bs,
1139 BlockDriverState *base, int creation_flags,
1140 int64_t speed, BlockdevOnError on_error,
1141 const char *filter_node_name,
1142 BlockCompletionFunc *cb, void *opaque,
1143 bool auto_complete, Error **errp);
1144 /*
1145 * mirror_start:
1146 * @job_id: The id of the newly-created job, or %NULL to use the
1147 * device name of @bs.
1148 * @bs: Block device to operate on.
1149 * @target: Block device to write to.
1150 * @replaces: Block graph node name to replace once the mirror is done. Can
1151 * only be used when full mirroring is selected.
1152 * @creation_flags: Flags that control the behavior of the Job lifetime.
1153 * See @BlockJobCreateFlags
1154 * @speed: The maximum speed, in bytes per second, or 0 for unlimited.
1155 * @granularity: The chosen granularity for the dirty bitmap.
1156 * @buf_size: The amount of data that can be in flight at one time.
1157 * @mode: Whether to collapse all images in the chain to the target.
1158 * @backing_mode: How to establish the target's backing chain after completion.
1159 * @zero_target: Whether the target should be explicitly zero-initialized
1160 * @on_source_error: The action to take upon error reading from the source.
1161 * @on_target_error: The action to take upon error writing to the target.
1162 * @unmap: Whether to unmap target where source sectors only contain zeroes.
1163 * @filter_node_name: The node name that should be assigned to the filter
1164 * driver that the mirror job inserts into the graph above @bs. NULL means that
1165 * a node name should be autogenerated.
1166 * @copy_mode: When to trigger writes to the target.
1167 * @errp: Error object.
1168 *
1169 * Start a mirroring operation on @bs. Clusters that are allocated
1170 * in @bs will be written to @target until the job is cancelled or
1171 * manually completed. At the end of a successful mirroring job,
1172 * @bs will be switched to read from @target.
1173 */
1174 void mirror_start(const char *job_id, BlockDriverState *bs,
1175 BlockDriverState *target, const char *replaces,
1176 int creation_flags, int64_t speed,
1177 uint32_t granularity, int64_t buf_size,
1178 MirrorSyncMode mode, BlockMirrorBackingMode backing_mode,
1179 bool zero_target,
1180 BlockdevOnError on_source_error,
1181 BlockdevOnError on_target_error,
1182 bool unmap, const char *filter_node_name,
1183 MirrorCopyMode copy_mode, Error **errp);
1184
1185 /*
1186 * backup_job_create:
1187 * @job_id: The id of the newly-created job, or %NULL to use the
1188 * device name of @bs.
1189 * @bs: Block device to operate on.
1190 * @target: Block device to write to.
1191 * @speed: The maximum speed, in bytes per second, or 0 for unlimited.
1192 * @sync_mode: What parts of the disk image should be copied to the destination.
1193 * @sync_bitmap: The dirty bitmap if sync_mode is 'bitmap' or 'incremental'
1194 * @bitmap_mode: The bitmap synchronization policy to use.
1195 * @on_source_error: The action to take upon error reading from the source.
1196 * @on_target_error: The action to take upon error writing to the target.
1197 * @creation_flags: Flags that control the behavior of the Job lifetime.
1198 * See @BlockJobCreateFlags
1199 * @cb: Completion function for the job.
1200 * @opaque: Opaque pointer value passed to @cb.
1201 * @txn: Transaction that this job is part of (may be NULL).
1202 *
1203 * Create a backup operation on @bs. Clusters in @bs are written to @target
1204 * until the job is cancelled or manually completed.
1205 */
1206 BlockJob *backup_job_create(const char *job_id, BlockDriverState *bs,
1207 BlockDriverState *target, int64_t speed,
1208 MirrorSyncMode sync_mode,
1209 BdrvDirtyBitmap *sync_bitmap,
1210 BitmapSyncMode bitmap_mode,
1211 bool compress,
1212 const char *filter_node_name,
1213 BlockdevOnError on_source_error,
1214 BlockdevOnError on_target_error,
1215 int creation_flags,
1216 BlockCompletionFunc *cb, void *opaque,
1217 JobTxn *txn, Error **errp);
1218
1219 void hmp_drive_add_node(Monitor *mon, const char *optstr);
1220
1221 BdrvChild *bdrv_root_attach_child(BlockDriverState *child_bs,
1222 const char *child_name,
1223 const BdrvChildRole *child_role,
1224 AioContext *ctx,
1225 uint64_t perm, uint64_t shared_perm,
1226 void *opaque, Error **errp);
1227 void bdrv_root_unref_child(BdrvChild *child);
1228
1229 /**
1230 * Sets a BdrvChild's permissions. Avoid if the parent is a BDS; use
1231 * bdrv_child_refresh_perms() instead and make the parent's
1232 * .bdrv_child_perm() implementation return the correct values.
1233 */
1234 int bdrv_child_try_set_perm(BdrvChild *c, uint64_t perm, uint64_t shared,
1235 Error **errp);
1236
1237 /**
1238 * Calls bs->drv->bdrv_child_perm() and updates the child's permission
1239 * masks with the result.
1240 * Drivers should invoke this function whenever an event occurs that
1241 * makes their .bdrv_child_perm() implementation return different
1242 * values than before, but which will not result in the block layer
1243 * automatically refreshing the permissions.
1244 */
1245 int bdrv_child_refresh_perms(BlockDriverState *bs, BdrvChild *c, Error **errp);
1246
1247 /* Default implementation for BlockDriver.bdrv_child_perm() that can be used by
1248 * block filters: Forward CONSISTENT_READ, WRITE, WRITE_UNCHANGED and RESIZE to
1249 * all children */
1250 void bdrv_filter_default_perms(BlockDriverState *bs, BdrvChild *c,
1251 const BdrvChildRole *role,
1252 BlockReopenQueue *reopen_queue,
1253 uint64_t perm, uint64_t shared,
1254 uint64_t *nperm, uint64_t *nshared);
1255
1256 /* Default implementation for BlockDriver.bdrv_child_perm() that can be used by
1257 * (non-raw) image formats: Like above for bs->backing, but for bs->file it
1258 * requires WRITE | RESIZE for read-write images, always requires
1259 * CONSISTENT_READ and doesn't share WRITE. */
1260 void bdrv_format_default_perms(BlockDriverState *bs, BdrvChild *c,
1261 const BdrvChildRole *role,
1262 BlockReopenQueue *reopen_queue,
1263 uint64_t perm, uint64_t shared,
1264 uint64_t *nperm, uint64_t *nshared);
1265
1266 bool bdrv_recurse_can_replace(BlockDriverState *bs,
1267 BlockDriverState *to_replace);
1268
1269 /*
1270 * Default implementation for drivers to pass bdrv_co_block_status() to
1271 * their file.
1272 */
1273 int coroutine_fn bdrv_co_block_status_from_file(BlockDriverState *bs,
1274 bool want_zero,
1275 int64_t offset,
1276 int64_t bytes,
1277 int64_t *pnum,
1278 int64_t *map,
1279 BlockDriverState **file);
1280 /*
1281 * Default implementation for drivers to pass bdrv_co_block_status() to
1282 * their backing file.
1283 */
1284 int coroutine_fn bdrv_co_block_status_from_backing(BlockDriverState *bs,
1285 bool want_zero,
1286 int64_t offset,
1287 int64_t bytes,
1288 int64_t *pnum,
1289 int64_t *map,
1290 BlockDriverState **file);
1291 const char *bdrv_get_parent_name(const BlockDriverState *bs);
1292 void blk_dev_change_media_cb(BlockBackend *blk, bool load, Error **errp);
1293 bool blk_dev_has_removable_media(BlockBackend *blk);
1294 bool blk_dev_has_tray(BlockBackend *blk);
1295 void blk_dev_eject_request(BlockBackend *blk, bool force);
1296 bool blk_dev_is_tray_open(BlockBackend *blk);
1297 bool blk_dev_is_medium_locked(BlockBackend *blk);
1298
1299 void bdrv_set_dirty(BlockDriverState *bs, int64_t offset, int64_t bytes);
1300
1301 void bdrv_clear_dirty_bitmap(BdrvDirtyBitmap *bitmap, HBitmap **out);
1302 void bdrv_restore_dirty_bitmap(BdrvDirtyBitmap *bitmap, HBitmap *backup);
1303 bool bdrv_dirty_bitmap_merge_internal(BdrvDirtyBitmap *dest,
1304 const BdrvDirtyBitmap *src,
1305 HBitmap **backup, bool lock);
1306
1307 void bdrv_inc_in_flight(BlockDriverState *bs);
1308 void bdrv_dec_in_flight(BlockDriverState *bs);
1309
1310 void blockdev_close_all_bdrv_states(void);
1311
1312 int coroutine_fn bdrv_co_copy_range_from(BdrvChild *src, uint64_t src_offset,
1313 BdrvChild *dst, uint64_t dst_offset,
1314 uint64_t bytes,
1315 BdrvRequestFlags read_flags,
1316 BdrvRequestFlags write_flags);
1317 int coroutine_fn bdrv_co_copy_range_to(BdrvChild *src, uint64_t src_offset,
1318 BdrvChild *dst, uint64_t dst_offset,
1319 uint64_t bytes,
1320 BdrvRequestFlags read_flags,
1321 BdrvRequestFlags write_flags);
1322
1323 int refresh_total_sectors(BlockDriverState *bs, int64_t hint);
1324
1325 #endif /* BLOCK_INT_H */