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 bdrv_replace_child_bs(BdrvChild *child, BlockDriverState *new_bs,
78                           Error **errp);
79 BlockDriverState *bdrv_insert_node(BlockDriverState *bs, QDict *node_options,
80                                    int flags, Error **errp);
81 int bdrv_drop_filter(BlockDriverState *bs, Error **errp);
82 
83 BdrvChild * no_coroutine_fn
84 bdrv_open_child(const char *filename, QDict *options, const char *bdref_key,
85                 BlockDriverState *parent, const BdrvChildClass *child_class,
86                 BdrvChildRole child_role, bool allow_none, Error **errp);
87 
88 BdrvChild * coroutine_fn no_co_wrapper
89 bdrv_co_open_child(const char *filename, QDict *options, const char *bdref_key,
90                 BlockDriverState *parent, const BdrvChildClass *child_class,
91                 BdrvChildRole child_role, bool allow_none, Error **errp);
92 
93 int bdrv_open_file_child(const char *filename,
94                          QDict *options, const char *bdref_key,
95                          BlockDriverState *parent, Error **errp);
96 
97 BlockDriverState * no_coroutine_fn
98 bdrv_open_blockdev_ref(BlockdevRef *ref, Error **errp);
99 
100 BlockDriverState * coroutine_fn no_co_wrapper
101 bdrv_co_open_blockdev_ref(BlockdevRef *ref, Error **errp);
102 
103 int bdrv_set_backing_hd(BlockDriverState *bs, BlockDriverState *backing_hd,
104                         Error **errp);
105 int GRAPH_WRLOCK
106 bdrv_set_backing_hd_drained(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 *bdrv_reopen_queue(BlockReopenQueue *bs_queue,
127                                     BlockDriverState *bs, QDict *options,
128                                     bool keep_old_opts);
129 void bdrv_reopen_queue_free(BlockReopenQueue *bs_queue);
130 int bdrv_reopen_multiple(BlockReopenQueue *bs_queue, Error **errp);
131 int bdrv_reopen(BlockDriverState *bs, QDict *opts, bool keep_old_opts,
132                 Error **errp);
133 int bdrv_reopen_set_read_only(BlockDriverState *bs, bool read_only,
134                               Error **errp);
135 BlockDriverState *bdrv_find_backing_image(BlockDriverState *bs,
136                                           const char *backing_file);
137 void GRAPH_RDLOCK bdrv_refresh_filename(BlockDriverState *bs);
138 
139 void GRAPH_RDLOCK
140 bdrv_refresh_limits(BlockDriverState *bs, Transaction *tran, Error **errp);
141 
142 int bdrv_commit(BlockDriverState *bs);
143 int GRAPH_RDLOCK bdrv_make_empty(BdrvChild *c, Error **errp);
144 
145 void bdrv_register(BlockDriver *bdrv);
146 int bdrv_drop_intermediate(BlockDriverState *top, BlockDriverState *base,
147                            const char *backing_file_str,
148                            bool backing_mask_protocol);
149 
150 BlockDriverState * GRAPH_RDLOCK
151 bdrv_find_overlay(BlockDriverState *active, BlockDriverState *bs);
152 
153 BlockDriverState * GRAPH_RDLOCK bdrv_find_base(BlockDriverState *bs);
154 
155 int GRAPH_RDLOCK
156 bdrv_freeze_backing_chain(BlockDriverState *bs, BlockDriverState *base,
157                           Error **errp);
158 void GRAPH_RDLOCK
159 bdrv_unfreeze_backing_chain(BlockDriverState *bs, BlockDriverState *base);
160 
161 /*
162  * The units of offset and total_work_size may be chosen arbitrarily by the
163  * block driver; total_work_size may change during the course of the amendment
164  * operation
165  */
166 typedef void BlockDriverAmendStatusCB(BlockDriverState *bs, int64_t offset,
167                                       int64_t total_work_size, void *opaque);
168 int GRAPH_RDLOCK
169 bdrv_amend_options(BlockDriverState *bs_new, QemuOpts *opts,
170                    BlockDriverAmendStatusCB *status_cb, void *cb_opaque,
171                    bool force, Error **errp);
172 
173 /* check if a named node can be replaced when doing drive-mirror */
174 BlockDriverState * GRAPH_RDLOCK
175 check_to_replace_node(BlockDriverState *parent_bs, const char *node_name,
176                       Error **errp);
177 
178 int no_coroutine_fn GRAPH_RDLOCK
179 bdrv_activate(BlockDriverState *bs, Error **errp);
180 
181 int coroutine_fn no_co_wrapper_bdrv_rdlock
182 bdrv_co_activate(BlockDriverState *bs, Error **errp);
183 
184 void bdrv_activate_all(Error **errp);
185 int bdrv_inactivate_all(void);
186 
187 int bdrv_flush_all(void);
188 void bdrv_close_all(void);
189 void bdrv_drain_all_begin(void);
190 void bdrv_drain_all_begin_nopoll(void);
191 void bdrv_drain_all_end(void);
192 void bdrv_drain_all(void);
193 
194 void bdrv_aio_cancel(BlockAIOCB *acb);
195 
196 int bdrv_has_zero_init_1(BlockDriverState *bs);
197 int coroutine_mixed_fn GRAPH_RDLOCK bdrv_has_zero_init(BlockDriverState *bs);
198 BlockDriverState *bdrv_find_node(const char *node_name);
199 BlockDeviceInfoList *bdrv_named_nodes_list(bool flat, Error **errp);
200 XDbgBlockGraph * GRAPH_RDLOCK bdrv_get_xdbg_block_graph(Error **errp);
201 BlockDriverState *bdrv_lookup_bs(const char *device,
202                                  const char *node_name,
203                                  Error **errp);
204 bool GRAPH_RDLOCK
205 bdrv_chain_contains(BlockDriverState *top, BlockDriverState *base);
206 
207 BlockDriverState *bdrv_next_node(BlockDriverState *bs);
208 BlockDriverState *bdrv_next_all_states(BlockDriverState *bs);
209 
210 typedef struct BdrvNextIterator {
211     enum {
212         BDRV_NEXT_BACKEND_ROOTS,
213         BDRV_NEXT_MONITOR_OWNED,
214     } phase;
215     BlockBackend *blk;
216     BlockDriverState *bs;
217 } BdrvNextIterator;
218 
219 BlockDriverState * GRAPH_RDLOCK bdrv_first(BdrvNextIterator *it);
220 BlockDriverState * GRAPH_RDLOCK bdrv_next(BdrvNextIterator *it);
221 void bdrv_next_cleanup(BdrvNextIterator *it);
222 
223 BlockDriverState *bdrv_next_monitor_owned(BlockDriverState *bs);
224 void bdrv_iterate_format(void (*it)(void *opaque, const char *name),
225                          void *opaque, bool read_only);
226 
227 char * GRAPH_RDLOCK
228 bdrv_get_full_backing_filename(BlockDriverState *bs, Error **errp);
229 
230 char * GRAPH_RDLOCK bdrv_dirname(BlockDriverState *bs, Error **errp);
231 
232 void bdrv_img_create(const char *filename, const char *fmt,
233                      const char *base_filename, const char *base_fmt,
234                      char *options, uint64_t img_size, int flags,
235                      bool quiet, Error **errp);
236 
237 void bdrv_ref(BlockDriverState *bs);
238 void no_coroutine_fn bdrv_unref(BlockDriverState *bs);
239 void coroutine_fn no_co_wrapper bdrv_co_unref(BlockDriverState *bs);
240 void GRAPH_WRLOCK bdrv_schedule_unref(BlockDriverState *bs);
241 
242 void GRAPH_WRLOCK
243 bdrv_unref_child(BlockDriverState *parent, BdrvChild *child);
244 
245 void coroutine_fn no_co_wrapper_bdrv_wrlock
246 bdrv_co_unref_child(BlockDriverState *parent, BdrvChild *child);
247 
248 BdrvChild * GRAPH_WRLOCK
249 bdrv_attach_child(BlockDriverState *parent_bs,
250                   BlockDriverState *child_bs,
251                   const char *child_name,
252                   const BdrvChildClass *child_class,
253                   BdrvChildRole child_role,
254                   Error **errp);
255 
256 bool GRAPH_RDLOCK
257 bdrv_op_is_blocked(BlockDriverState *bs, BlockOpType op, Error **errp);
258 
259 void bdrv_op_block(BlockDriverState *bs, BlockOpType op, Error *reason);
260 void bdrv_op_unblock(BlockDriverState *bs, BlockOpType op, Error *reason);
261 void bdrv_op_block_all(BlockDriverState *bs, Error *reason);
262 void bdrv_op_unblock_all(BlockDriverState *bs, Error *reason);
263 bool bdrv_op_blocker_is_empty(BlockDriverState *bs);
264 
265 int bdrv_debug_breakpoint(BlockDriverState *bs, const char *event,
266                            const char *tag);
267 int bdrv_debug_remove_breakpoint(BlockDriverState *bs, const char *tag);
268 int bdrv_debug_resume(BlockDriverState *bs, const char *tag);
269 bool bdrv_debug_is_suspended(BlockDriverState *bs, const char *tag);
270 
271 bool bdrv_child_change_aio_context(BdrvChild *c, AioContext *ctx,
272                                    GHashTable *visited, Transaction *tran,
273                                    Error **errp);
274 int bdrv_try_change_aio_context(BlockDriverState *bs, AioContext *ctx,
275                                 BdrvChild *ignore_child, Error **errp);
276 
277 int GRAPH_RDLOCK bdrv_probe_blocksizes(BlockDriverState *bs, BlockSizes *bsz);
278 int bdrv_probe_geometry(BlockDriverState *bs, HDGeometry *geo);
279 
280 void GRAPH_WRLOCK
281 bdrv_add_child(BlockDriverState *parent, BlockDriverState *child, Error **errp);
282 
283 void GRAPH_WRLOCK
284 bdrv_del_child(BlockDriverState *parent, BdrvChild *child, Error **errp);
285 
286 /**
287  *
288  * bdrv_register_buf/bdrv_unregister_buf:
289  *
290  * Register/unregister a buffer for I/O. For example, VFIO drivers are
291  * interested to know the memory areas that would later be used for I/O, so
292  * that they can prepare IOMMU mapping etc., to get better performance.
293  *
294  * Buffers must not overlap and they must be unregistered with the same <host,
295  * size> values that they were registered with.
296  *
297  * Returns: true on success, false on failure
298  */
299 bool bdrv_register_buf(BlockDriverState *bs, void *host, size_t size,
300                        Error **errp);
301 void bdrv_unregister_buf(BlockDriverState *bs, void *host, size_t size);
302 
303 void bdrv_cancel_in_flight(BlockDriverState *bs);
304 
305 #endif /* BLOCK_GLOBAL_STATE_H */
306