LXR qemu/include/block/block-global-state.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_GLOBAL_STATE_H
  25#define BLOCK_GLOBAL_STATE_H
  26
  27#include "block-common.h"
  28
  29/*
  30 * Global state (GS) API. These functions run under the BQL.
  31 *
  32 * If a function modifies the graph, it also uses drain and/or
  33 * aio_context_acquire/release to be sure it has unique access.
  34 * aio_context locking is needed together with BQL because of
  35 * the thread-safe I/O API that concurrently runs and accesses
  36 * the graph without the BQL.
  37 *
  38 * It is important to note that not all of these functions are
  39 * necessarily limited to running under the BQL, but they would
  40 * require additional auditing and many small thread-safety changes
  41 * to move them into the I/O API. Often it's not worth doing that
  42 * work since the APIs are only used with the BQL held at the
  43 * moment, so they have been placed in the GS API (for now).
  44 *
  45 * These functions can call any function from this and other categories
  46 * (I/O, "I/O or GS", Common), but must be invoked only by other GS APIs.
  47 *
  48 * All functions in this header must use the macro
  49 * GLOBAL_STATE_CODE();
  50 * to catch when they are accidentally called without the BQL.
  51 */
  52
  53void bdrv_init(void);
  54BlockDriver *bdrv_find_protocol(const char *filename,
  55                                bool allow_protocol_prefix,
  56                                Error **errp);
  57BlockDriver *bdrv_find_format(const char *format_name);
  58int bdrv_create(BlockDriver *drv, const char* filename,
  59                QemuOpts *opts, Error **errp);
  60int bdrv_create_file(const char *filename, QemuOpts *opts, Error **errp);
  61
  62BlockDriverState *bdrv_new(void);
  63int bdrv_append(BlockDriverState *bs_new, BlockDriverState *bs_top,
  64                Error **errp);
  65int bdrv_replace_node(BlockDriverState *from, BlockDriverState *to,
  66                      Error **errp);
  67int bdrv_replace_child_bs(BdrvChild *child, BlockDriverState *new_bs,
  68                          Error **errp);
  69BlockDriverState *bdrv_insert_node(BlockDriverState *bs, QDict *node_options,
  70                                   int flags, Error **errp);
  71int bdrv_drop_filter(BlockDriverState *bs, Error **errp);
  72
  73BdrvChild *bdrv_open_child(const char *filename,
  74                           QDict *options, const char *bdref_key,
  75                           BlockDriverState *parent,
  76                           const BdrvChildClass *child_class,
  77                           BdrvChildRole child_role,
  78                           bool allow_none, Error **errp);
  79int bdrv_open_file_child(const char *filename,
  80                         QDict *options, const char *bdref_key,
  81                         BlockDriverState *parent, Error **errp);
  82BlockDriverState *bdrv_open_blockdev_ref(BlockdevRef *ref, Error **errp);
  83int bdrv_set_backing_hd(BlockDriverState *bs, BlockDriverState *backing_hd,
  84                        Error **errp);
  85int bdrv_open_backing_file(BlockDriverState *bs, QDict *parent_options,
  86                           const char *bdref_key, Error **errp);
  87BlockDriverState *bdrv_open(const char *filename, const char *reference,
  88                            QDict *options, int flags, Error **errp);
  89BlockDriverState *bdrv_new_open_driver_opts(BlockDriver *drv,
  90                                            const char *node_name,
  91                                            QDict *options, int flags,
  92                                            Error **errp);
  93BlockDriverState *bdrv_new_open_driver(BlockDriver *drv, const char *node_name,
  94                                       int flags, Error **errp);
  95BlockReopenQueue *bdrv_reopen_queue(BlockReopenQueue *bs_queue,
  96                                    BlockDriverState *bs, QDict *options,
  97                                    bool keep_old_opts);
  98void bdrv_reopen_queue_free(BlockReopenQueue *bs_queue);
  99int bdrv_reopen_multiple(BlockReopenQueue *bs_queue, Error **errp);
 100int bdrv_reopen(BlockDriverState *bs, QDict *opts, bool keep_old_opts,
 101                Error **errp);
 102int bdrv_reopen_set_read_only(BlockDriverState *bs, bool read_only,
 103                              Error **errp);
 104BlockDriverState *bdrv_find_backing_image(BlockDriverState *bs,
 105                                          const char *backing_file);
 106void bdrv_refresh_filename(BlockDriverState *bs);
 107void bdrv_refresh_limits(BlockDriverState *bs, Transaction *tran, Error **errp);
 108int bdrv_commit(BlockDriverState *bs);
 109int bdrv_make_empty(BdrvChild *c, Error **errp);
 110int bdrv_change_backing_file(BlockDriverState *bs, const char *backing_file,
 111                             const char *backing_fmt, bool warn);
 112void bdrv_register(BlockDriver *bdrv);
 113int bdrv_drop_intermediate(BlockDriverState *top, BlockDriverState *base,
 114                           const char *backing_file_str);
 115BlockDriverState *bdrv_find_overlay(BlockDriverState *active,
 116                                    BlockDriverState *bs);
 117BlockDriverState *bdrv_find_base(BlockDriverState *bs);
 118bool bdrv_is_backing_chain_frozen(BlockDriverState *bs, BlockDriverState *base,
 119                                  Error **errp);
 120int bdrv_freeze_backing_chain(BlockDriverState *bs, BlockDriverState *base,
 121                              Error **errp);
 122void bdrv_unfreeze_backing_chain(BlockDriverState *bs, BlockDriverState *base);
 123
 124/*
 125 * The units of offset and total_work_size may be chosen arbitrarily by the
 126 * block driver; total_work_size may change during the course of the amendment
 127 * operation
 128 */
 129typedef void BlockDriverAmendStatusCB(BlockDriverState *bs, int64_t offset,
 130                                      int64_t total_work_size, void *opaque);
 131int bdrv_amend_options(BlockDriverState *bs_new, QemuOpts *opts,
 132                       BlockDriverAmendStatusCB *status_cb, void *cb_opaque,
 133                       bool force,
 134                       Error **errp);
 135
 136/* check if a named node can be replaced when doing drive-mirror */
 137BlockDriverState *check_to_replace_node(BlockDriverState *parent_bs,
 138                                        const char *node_name, Error **errp);
 139
 140int bdrv_activate(BlockDriverState *bs, Error **errp);
 141void bdrv_activate_all(Error **errp);
 142int bdrv_inactivate_all(void);
 143
 144int bdrv_flush_all(void);
 145void bdrv_close_all(void);
 146void bdrv_drain_all_begin(void);
 147void bdrv_drain_all_end(void);
 148void bdrv_drain_all(void);
 149
 150int bdrv_has_zero_init_1(BlockDriverState *bs);
 151int bdrv_has_zero_init(BlockDriverState *bs);
 152BlockDriverState *bdrv_find_node(const char *node_name);
 153BlockDeviceInfoList *bdrv_named_nodes_list(bool flat, Error **errp);
 154XDbgBlockGraph *bdrv_get_xdbg_block_graph(Error **errp);
 155BlockDriverState *bdrv_lookup_bs(const char *device,
 156                                 const char *node_name,
 157                                 Error **errp);
 158bool bdrv_chain_contains(BlockDriverState *top, BlockDriverState *base);
 159BlockDriverState *bdrv_next_node(BlockDriverState *bs);
 160BlockDriverState *bdrv_next_all_states(BlockDriverState *bs);
 161
 162typedef struct BdrvNextIterator {
 163    enum {
 164        BDRV_NEXT_BACKEND_ROOTS,
 165        BDRV_NEXT_MONITOR_OWNED,
 166    } phase;
 167    BlockBackend *blk;
 168    BlockDriverState *bs;
 169} BdrvNextIterator;
 170
 171BlockDriverState *bdrv_first(BdrvNextIterator *it);
 172BlockDriverState *bdrv_next(BdrvNextIterator *it);
 173void bdrv_next_cleanup(BdrvNextIterator *it);
 174
 175BlockDriverState *bdrv_next_monitor_owned(BlockDriverState *bs);
 176void bdrv_iterate_format(void (*it)(void *opaque, const char *name),
 177                         void *opaque, bool read_only);
 178char *bdrv_get_full_backing_filename(BlockDriverState *bs, Error **errp);
 179char *bdrv_dirname(BlockDriverState *bs, Error **errp);
 180
 181void bdrv_img_create(const char *filename, const char *fmt,
 182                     const char *base_filename, const char *base_fmt,
 183                     char *options, uint64_t img_size, int flags,
 184                     bool quiet, Error **errp);
 185
 186void bdrv_ref(BlockDriverState *bs);
 187void bdrv_unref(BlockDriverState *bs);
 188void bdrv_unref_child(BlockDriverState *parent, BdrvChild *child);
 189BdrvChild *bdrv_attach_child(BlockDriverState *parent_bs,
 190                             BlockDriverState *child_bs,
 191                             const char *child_name,
 192                             const BdrvChildClass *child_class,
 193                             BdrvChildRole child_role,
 194                             Error **errp);
 195
 196bool bdrv_op_is_blocked(BlockDriverState *bs, BlockOpType op, Error **errp);
 197void bdrv_op_block(BlockDriverState *bs, BlockOpType op, Error *reason);
 198void bdrv_op_unblock(BlockDriverState *bs, BlockOpType op, Error *reason);
 199void bdrv_op_block_all(BlockDriverState *bs, Error *reason);
 200void bdrv_op_unblock_all(BlockDriverState *bs, Error *reason);
 201bool bdrv_op_blocker_is_empty(BlockDriverState *bs);
 202
 203int bdrv_debug_breakpoint(BlockDriverState *bs, const char *event,
 204                           const char *tag);
 205int bdrv_debug_remove_breakpoint(BlockDriverState *bs, const char *tag);
 206int bdrv_debug_resume(BlockDriverState *bs, const char *tag);
 207bool bdrv_debug_is_suspended(BlockDriverState *bs, const char *tag);
 208
 209/**
 210 * Locks the AioContext of @bs if it's not the current AioContext. This avoids
 211 * double locking which could lead to deadlocks: This is a coroutine_fn, so we
 212 * know we already own the lock of the current AioContext.
 213 *
 214 * May only be called in the main thread.
 215 */
 216void coroutine_fn bdrv_co_lock(BlockDriverState *bs);
 217
 218/**
 219 * Unlocks the AioContext of @bs if it's not the current AioContext.
 220 */
 221void coroutine_fn bdrv_co_unlock(BlockDriverState *bs);
 222
 223bool bdrv_child_change_aio_context(BdrvChild *c, AioContext *ctx,
 224                                   GHashTable *visited, Transaction *tran,
 225                                   Error **errp);
 226int bdrv_try_change_aio_context(BlockDriverState *bs, AioContext *ctx,
 227                                BdrvChild *ignore_child, Error **errp);
 228
 229int bdrv_probe_blocksizes(BlockDriverState *bs, BlockSizes *bsz);
 230int bdrv_probe_geometry(BlockDriverState *bs, HDGeometry *geo);
 231
 232void bdrv_add_child(BlockDriverState *parent, BlockDriverState *child,
 233                    Error **errp);
 234void bdrv_del_child(BlockDriverState *parent, BdrvChild *child, Error **errp);
 235
 236/**
 237 *
 238 * bdrv_register_buf/bdrv_unregister_buf:
 239 *
 240 * Register/unregister a buffer for I/O. For example, VFIO drivers are
 241 * interested to know the memory areas that would later be used for I/O, so
 242 * that they can prepare IOMMU mapping etc., to get better performance.
 243 *
 244 * Buffers must not overlap and they must be unregistered with the same <host,
 245 * size> values that they were registered with.
 246 *
 247 * Returns: true on success, false on failure
 248 */
 249bool bdrv_register_buf(BlockDriverState *bs, void *host, size_t size,
 250                       Error **errp);
 251void bdrv_unregister_buf(BlockDriverState *bs, void *host, size_t size);
 252
 253void bdrv_cancel_in_flight(BlockDriverState *bs);
 254
 255#endif /* BLOCK_GLOBAL_STATE_H */
 256