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