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