2 * QEMU System Emulator block driver
4 * Copyright (c) 2003 Fabrice Bellard
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:
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
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
24 #ifndef BLOCK_GLOBAL_STATE_H
25 #define BLOCK_GLOBAL_STATE_H
27 #include "block/block-common.h"
28 #include "qemu/coroutine.h"
29 #include "qemu/transactions.h"
32 * Global state (GS) API. These functions run under the BQL.
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.
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).
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.
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.
56 BlockDriver
*bdrv_find_protocol(const char *filename
,
57 bool allow_protocol_prefix
,
59 BlockDriver
*bdrv_find_format(const char *format_name
);
61 int coroutine_fn GRAPH_UNLOCKED
62 bdrv_co_create(BlockDriver
*drv
, const char *filename
, QemuOpts
*opts
,
65 int co_wrapper
bdrv_create(BlockDriver
*drv
, const char *filename
,
66 QemuOpts
*opts
, Error
**errp
);
68 int coroutine_fn GRAPH_UNLOCKED
69 bdrv_co_create_file(const char *filename
, QemuOpts
*opts
, Error
**errp
);
71 BlockDriverState
*bdrv_new(void);
72 int bdrv_append(BlockDriverState
*bs_new
, BlockDriverState
*bs_top
,
74 int bdrv_replace_node(BlockDriverState
*from
, BlockDriverState
*to
,
76 int bdrv_replace_child_bs(BdrvChild
*child
, BlockDriverState
*new_bs
,
78 BlockDriverState
*bdrv_insert_node(BlockDriverState
*bs
, QDict
*node_options
,
79 int flags
, Error
**errp
);
80 int bdrv_drop_filter(BlockDriverState
*bs
, Error
**errp
);
82 BdrvChild
* no_coroutine_fn
83 bdrv_open_child(const char *filename
, QDict
*options
, const char *bdref_key
,
84 BlockDriverState
*parent
, const BdrvChildClass
*child_class
,
85 BdrvChildRole child_role
, bool allow_none
, Error
**errp
);
87 BdrvChild
* coroutine_fn no_co_wrapper
88 bdrv_co_open_child(const char *filename
, QDict
*options
, const char *bdref_key
,
89 BlockDriverState
*parent
, const BdrvChildClass
*child_class
,
90 BdrvChildRole child_role
, bool allow_none
, Error
**errp
);
92 int bdrv_open_file_child(const char *filename
,
93 QDict
*options
, const char *bdref_key
,
94 BlockDriverState
*parent
, Error
**errp
);
96 BlockDriverState
* no_coroutine_fn
97 bdrv_open_blockdev_ref(BlockdevRef
*ref
, Error
**errp
);
99 BlockDriverState
* coroutine_fn no_co_wrapper
100 bdrv_co_open_blockdev_ref(BlockdevRef
*ref
, Error
**errp
);
102 int bdrv_set_backing_hd(BlockDriverState
*bs
, BlockDriverState
*backing_hd
,
104 int bdrv_set_backing_hd_drained(BlockDriverState
*bs
,
105 BlockDriverState
*backing_hd
,
107 int bdrv_open_backing_file(BlockDriverState
*bs
, QDict
*parent_options
,
108 const char *bdref_key
, Error
**errp
);
110 BlockDriverState
* no_coroutine_fn
111 bdrv_open(const char *filename
, const char *reference
, QDict
*options
,
112 int flags
, Error
**errp
);
114 BlockDriverState
* coroutine_fn no_co_wrapper
115 bdrv_co_open(const char *filename
, const char *reference
,
116 QDict
*options
, int flags
, Error
**errp
);
118 BlockDriverState
*bdrv_new_open_driver_opts(BlockDriver
*drv
,
119 const char *node_name
,
120 QDict
*options
, int flags
,
122 BlockDriverState
*bdrv_new_open_driver(BlockDriver
*drv
, const char *node_name
,
123 int flags
, Error
**errp
);
124 BlockReopenQueue
*bdrv_reopen_queue(BlockReopenQueue
*bs_queue
,
125 BlockDriverState
*bs
, QDict
*options
,
127 void bdrv_reopen_queue_free(BlockReopenQueue
*bs_queue
);
128 int bdrv_reopen_multiple(BlockReopenQueue
*bs_queue
, Error
**errp
);
129 int bdrv_reopen(BlockDriverState
*bs
, QDict
*opts
, bool keep_old_opts
,
131 int bdrv_reopen_set_read_only(BlockDriverState
*bs
, bool read_only
,
133 BlockDriverState
*bdrv_find_backing_image(BlockDriverState
*bs
,
134 const char *backing_file
);
135 void GRAPH_RDLOCK
bdrv_refresh_filename(BlockDriverState
*bs
);
138 bdrv_refresh_limits(BlockDriverState
*bs
, Transaction
*tran
, Error
**errp
);
140 int bdrv_commit(BlockDriverState
*bs
);
141 int GRAPH_RDLOCK
bdrv_make_empty(BdrvChild
*c
, Error
**errp
);
142 int bdrv_change_backing_file(BlockDriverState
*bs
, const char *backing_file
,
143 const char *backing_fmt
, bool warn
);
144 void bdrv_register(BlockDriver
*bdrv
);
145 int bdrv_drop_intermediate(BlockDriverState
*top
, BlockDriverState
*base
,
146 const char *backing_file_str
);
147 BlockDriverState
*bdrv_find_overlay(BlockDriverState
*active
,
148 BlockDriverState
*bs
);
149 BlockDriverState
*bdrv_find_base(BlockDriverState
*bs
);
150 bool bdrv_is_backing_chain_frozen(BlockDriverState
*bs
, BlockDriverState
*base
,
152 int bdrv_freeze_backing_chain(BlockDriverState
*bs
, BlockDriverState
*base
,
154 void bdrv_unfreeze_backing_chain(BlockDriverState
*bs
, BlockDriverState
*base
);
157 * The units of offset and total_work_size may be chosen arbitrarily by the
158 * block driver; total_work_size may change during the course of the amendment
161 typedef void BlockDriverAmendStatusCB(BlockDriverState
*bs
, int64_t offset
,
162 int64_t total_work_size
, void *opaque
);
164 bdrv_amend_options(BlockDriverState
*bs_new
, QemuOpts
*opts
,
165 BlockDriverAmendStatusCB
*status_cb
, void *cb_opaque
,
166 bool force
, Error
**errp
);
168 /* check if a named node can be replaced when doing drive-mirror */
169 BlockDriverState
* GRAPH_RDLOCK
170 check_to_replace_node(BlockDriverState
*parent_bs
, const char *node_name
,
173 int no_coroutine_fn GRAPH_RDLOCK
174 bdrv_activate(BlockDriverState
*bs
, Error
**errp
);
176 int coroutine_fn no_co_wrapper_bdrv_rdlock
177 bdrv_co_activate(BlockDriverState
*bs
, Error
**errp
);
179 void bdrv_activate_all(Error
**errp
);
180 int bdrv_inactivate_all(void);
182 int bdrv_flush_all(void);
183 void bdrv_close_all(void);
184 void bdrv_drain_all_begin(void);
185 void bdrv_drain_all_begin_nopoll(void);
186 void bdrv_drain_all_end(void);
187 void bdrv_drain_all(void);
189 void bdrv_aio_cancel(BlockAIOCB
*acb
);
191 int bdrv_has_zero_init_1(BlockDriverState
*bs
);
192 int bdrv_has_zero_init(BlockDriverState
*bs
);
193 BlockDriverState
*bdrv_find_node(const char *node_name
);
194 BlockDeviceInfoList
*bdrv_named_nodes_list(bool flat
, Error
**errp
);
195 XDbgBlockGraph
* GRAPH_RDLOCK
bdrv_get_xdbg_block_graph(Error
**errp
);
196 BlockDriverState
*bdrv_lookup_bs(const char *device
,
197 const char *node_name
,
199 bool bdrv_chain_contains(BlockDriverState
*top
, BlockDriverState
*base
);
200 BlockDriverState
*bdrv_next_node(BlockDriverState
*bs
);
201 BlockDriverState
*bdrv_next_all_states(BlockDriverState
*bs
);
203 typedef struct BdrvNextIterator
{
205 BDRV_NEXT_BACKEND_ROOTS
,
206 BDRV_NEXT_MONITOR_OWNED
,
209 BlockDriverState
*bs
;
212 BlockDriverState
* GRAPH_RDLOCK
bdrv_first(BdrvNextIterator
*it
);
213 BlockDriverState
* GRAPH_RDLOCK
bdrv_next(BdrvNextIterator
*it
);
214 void bdrv_next_cleanup(BdrvNextIterator
*it
);
216 BlockDriverState
*bdrv_next_monitor_owned(BlockDriverState
*bs
);
217 void bdrv_iterate_format(void (*it
)(void *opaque
, const char *name
),
218 void *opaque
, bool read_only
);
221 bdrv_get_full_backing_filename(BlockDriverState
*bs
, Error
**errp
);
223 char * GRAPH_RDLOCK
bdrv_dirname(BlockDriverState
*bs
, Error
**errp
);
225 void bdrv_img_create(const char *filename
, const char *fmt
,
226 const char *base_filename
, const char *base_fmt
,
227 char *options
, uint64_t img_size
, int flags
,
228 bool quiet
, Error
**errp
);
230 void bdrv_ref(BlockDriverState
*bs
);
231 void no_coroutine_fn
bdrv_unref(BlockDriverState
*bs
);
232 void coroutine_fn no_co_wrapper
bdrv_co_unref(BlockDriverState
*bs
);
233 void GRAPH_WRLOCK
bdrv_schedule_unref(BlockDriverState
*bs
);
236 bdrv_unref_child(BlockDriverState
*parent
, BdrvChild
*child
);
238 void coroutine_fn no_co_wrapper_bdrv_wrlock
239 bdrv_co_unref_child(BlockDriverState
*parent
, BdrvChild
*child
);
241 BdrvChild
* GRAPH_WRLOCK
242 bdrv_attach_child(BlockDriverState
*parent_bs
,
243 BlockDriverState
*child_bs
,
244 const char *child_name
,
245 const BdrvChildClass
*child_class
,
246 BdrvChildRole child_role
,
249 bool bdrv_op_is_blocked(BlockDriverState
*bs
, BlockOpType op
, Error
**errp
);
250 void bdrv_op_block(BlockDriverState
*bs
, BlockOpType op
, Error
*reason
);
251 void bdrv_op_unblock(BlockDriverState
*bs
, BlockOpType op
, Error
*reason
);
252 void bdrv_op_block_all(BlockDriverState
*bs
, Error
*reason
);
253 void bdrv_op_unblock_all(BlockDriverState
*bs
, Error
*reason
);
254 bool bdrv_op_blocker_is_empty(BlockDriverState
*bs
);
256 int bdrv_debug_breakpoint(BlockDriverState
*bs
, const char *event
,
258 int bdrv_debug_remove_breakpoint(BlockDriverState
*bs
, const char *tag
);
259 int bdrv_debug_resume(BlockDriverState
*bs
, const char *tag
);
260 bool bdrv_debug_is_suspended(BlockDriverState
*bs
, const char *tag
);
263 * Locks the AioContext of @bs if it's not the current AioContext. This avoids
264 * double locking which could lead to deadlocks: This is a coroutine_fn, so we
265 * know we already own the lock of the current AioContext.
267 * May only be called in the main thread.
269 void coroutine_fn
bdrv_co_lock(BlockDriverState
*bs
);
272 * Unlocks the AioContext of @bs if it's not the current AioContext.
274 void coroutine_fn
bdrv_co_unlock(BlockDriverState
*bs
);
276 bool bdrv_child_change_aio_context(BdrvChild
*c
, AioContext
*ctx
,
277 GHashTable
*visited
, Transaction
*tran
,
279 int bdrv_try_change_aio_context(BlockDriverState
*bs
, AioContext
*ctx
,
280 BdrvChild
*ignore_child
, Error
**errp
);
282 int bdrv_probe_blocksizes(BlockDriverState
*bs
, BlockSizes
*bsz
);
283 int bdrv_probe_geometry(BlockDriverState
*bs
, HDGeometry
*geo
);
286 bdrv_add_child(BlockDriverState
*parent
, BlockDriverState
*child
, Error
**errp
);
289 bdrv_del_child(BlockDriverState
*parent
, BdrvChild
*child
, Error
**errp
);
293 * bdrv_register_buf/bdrv_unregister_buf:
295 * Register/unregister a buffer for I/O. For example, VFIO drivers are
296 * interested to know the memory areas that would later be used for I/O, so
297 * that they can prepare IOMMU mapping etc., to get better performance.
299 * Buffers must not overlap and they must be unregistered with the same <host,
300 * size> values that they were registered with.
302 * Returns: true on success, false on failure
304 bool bdrv_register_buf(BlockDriverState
*bs
, void *host
, size_t size
,
306 void bdrv_unregister_buf(BlockDriverState
*bs
, void *host
, size_t size
);
308 void bdrv_cancel_in_flight(BlockDriverState
*bs
);
310 #endif /* BLOCK_GLOBAL_STATE_H */