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