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 
53 void bdrv_init(void);
54 BlockDriver *bdrv_find_protocol(const char *filename,
55                                 bool allow_protocol_prefix,
56                                 Error **errp);
57 BlockDriver *bdrv_find_format(const char *format_name);
58 int bdrv_create(BlockDriver *drv, const char* filename,
59                 QemuOpts *opts, Error **errp);
60 int bdrv_create_file(const char *filename, QemuOpts *opts, Error **errp);
61 
62 BlockDriverState *bdrv_new(void);
63 int bdrv_append(BlockDriverState *bs_new, BlockDriverState *bs_top,
64                 Error **errp);
65 int bdrv_replace_node(BlockDriverState *from, BlockDriverState *to,
66                       Error **errp);
67 int bdrv_replace_child_bs(BdrvChild *child, BlockDriverState *new_bs,
68                           Error **errp);
69 BlockDriverState *bdrv_insert_node(BlockDriverState *bs, QDict *node_options,
70                                    int flags, Error **errp);
71 int bdrv_drop_filter(BlockDriverState *bs, Error **errp);
72 
73 BdrvChild *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);
79 BlockDriverState *bdrv_open_blockdev_ref(BlockdevRef *ref, Error **errp);
80 int bdrv_set_backing_hd(BlockDriverState *bs, BlockDriverState *backing_hd,
81                         Error **errp);
82 int bdrv_open_backing_file(BlockDriverState *bs, QDict *parent_options,
83                            const char *bdref_key, Error **errp);
84 BlockDriverState *bdrv_open(const char *filename, const char *reference,
85                             QDict *options, int flags, Error **errp);
86 BlockDriverState *bdrv_new_open_driver_opts(BlockDriver *drv,
87                                             const char *node_name,
88                                             QDict *options, int flags,
89                                             Error **errp);
90 BlockDriverState *bdrv_new_open_driver(BlockDriver *drv, const char *node_name,
91                                        int flags, Error **errp);
92 BlockReopenQueue *bdrv_reopen_queue(BlockReopenQueue *bs_queue,
93                                     BlockDriverState *bs, QDict *options,
94                                     bool keep_old_opts);
95 void bdrv_reopen_queue_free(BlockReopenQueue *bs_queue);
96 int bdrv_reopen_multiple(BlockReopenQueue *bs_queue, Error **errp);
97 int bdrv_reopen(BlockDriverState *bs, QDict *opts, bool keep_old_opts,
98                 Error **errp);
99 int bdrv_reopen_set_read_only(BlockDriverState *bs, bool read_only,
100                               Error **errp);
101 BlockDriverState *bdrv_find_backing_image(BlockDriverState *bs,
102                                           const char *backing_file);
103 void bdrv_refresh_filename(BlockDriverState *bs);
104 void bdrv_refresh_limits(BlockDriverState *bs, Transaction *tran, Error **errp);
105 int bdrv_commit(BlockDriverState *bs);
106 int bdrv_make_empty(BdrvChild *c, Error **errp);
107 int bdrv_change_backing_file(BlockDriverState *bs, const char *backing_file,
108                              const char *backing_fmt, bool warn);
109 void bdrv_register(BlockDriver *bdrv);
110 int bdrv_drop_intermediate(BlockDriverState *top, BlockDriverState *base,
111                            const char *backing_file_str);
112 BlockDriverState *bdrv_find_overlay(BlockDriverState *active,
113                                     BlockDriverState *bs);
114 BlockDriverState *bdrv_find_base(BlockDriverState *bs);
115 bool bdrv_is_backing_chain_frozen(BlockDriverState *bs, BlockDriverState *base,
116                                   Error **errp);
117 int bdrv_freeze_backing_chain(BlockDriverState *bs, BlockDriverState *base,
118                               Error **errp);
119 void bdrv_unfreeze_backing_chain(BlockDriverState *bs, BlockDriverState *base);
120 
121 /*
122  * The units of offset and total_work_size may be chosen arbitrarily by the
123  * block driver; total_work_size may change during the course of the amendment
124  * operation
125  */
126 typedef void BlockDriverAmendStatusCB(BlockDriverState *bs, int64_t offset,
127                                       int64_t total_work_size, void *opaque);
128 int bdrv_amend_options(BlockDriverState *bs_new, QemuOpts *opts,
129                        BlockDriverAmendStatusCB *status_cb, void *cb_opaque,
130                        bool force,
131                        Error **errp);
132 
133 /* check if a named node can be replaced when doing drive-mirror */
134 BlockDriverState *check_to_replace_node(BlockDriverState *parent_bs,
135                                         const char *node_name, Error **errp);
136 
137 int bdrv_activate(BlockDriverState *bs, Error **errp);
138 void bdrv_activate_all(Error **errp);
139 int bdrv_inactivate_all(void);
140 
141 int bdrv_flush_all(void);
142 void bdrv_close_all(void);
143 void bdrv_drain_all_begin(void);
144 void bdrv_drain_all_end(void);
145 void bdrv_drain_all(void);
146 
147 int bdrv_has_zero_init_1(BlockDriverState *bs);
148 int bdrv_has_zero_init(BlockDriverState *bs);
149 BlockDriverState *bdrv_find_node(const char *node_name);
150 BlockDeviceInfoList *bdrv_named_nodes_list(bool flat, Error **errp);
151 XDbgBlockGraph *bdrv_get_xdbg_block_graph(Error **errp);
152 BlockDriverState *bdrv_lookup_bs(const char *device,
153                                  const char *node_name,
154                                  Error **errp);
155 bool bdrv_chain_contains(BlockDriverState *top, BlockDriverState *base);
156 BlockDriverState *bdrv_next_node(BlockDriverState *bs);
157 BlockDriverState *bdrv_next_all_states(BlockDriverState *bs);
158 
159 typedef struct BdrvNextIterator {
160     enum {
161         BDRV_NEXT_BACKEND_ROOTS,
162         BDRV_NEXT_MONITOR_OWNED,
163     } phase;
164     BlockBackend *blk;
165     BlockDriverState *bs;
166 } BdrvNextIterator;
167 
168 BlockDriverState *bdrv_first(BdrvNextIterator *it);
169 BlockDriverState *bdrv_next(BdrvNextIterator *it);
170 void bdrv_next_cleanup(BdrvNextIterator *it);
171 
172 BlockDriverState *bdrv_next_monitor_owned(BlockDriverState *bs);
173 void bdrv_iterate_format(void (*it)(void *opaque, const char *name),
174                          void *opaque, bool read_only);
175 char *bdrv_get_full_backing_filename(BlockDriverState *bs, Error **errp);
176 char *bdrv_dirname(BlockDriverState *bs, Error **errp);
177 
178 void bdrv_img_create(const char *filename, const char *fmt,
179                      const char *base_filename, const char *base_fmt,
180                      char *options, uint64_t img_size, int flags,
181                      bool quiet, Error **errp);
182 
183 void bdrv_ref(BlockDriverState *bs);
184 void bdrv_unref(BlockDriverState *bs);
185 void bdrv_unref_child(BlockDriverState *parent, BdrvChild *child);
186 BdrvChild *bdrv_attach_child(BlockDriverState *parent_bs,
187                              BlockDriverState *child_bs,
188                              const char *child_name,
189                              const BdrvChildClass *child_class,
190                              BdrvChildRole child_role,
191                              Error **errp);
192 
193 bool bdrv_op_is_blocked(BlockDriverState *bs, BlockOpType op, Error **errp);
194 void bdrv_op_block(BlockDriverState *bs, BlockOpType op, Error *reason);
195 void bdrv_op_unblock(BlockDriverState *bs, BlockOpType op, Error *reason);
196 void bdrv_op_block_all(BlockDriverState *bs, Error *reason);
197 void bdrv_op_unblock_all(BlockDriverState *bs, Error *reason);
198 bool bdrv_op_blocker_is_empty(BlockDriverState *bs);
199 
200 int bdrv_debug_breakpoint(BlockDriverState *bs, const char *event,
201                            const char *tag);
202 int bdrv_debug_remove_breakpoint(BlockDriverState *bs, const char *tag);
203 int bdrv_debug_resume(BlockDriverState *bs, const char *tag);
204 bool bdrv_debug_is_suspended(BlockDriverState *bs, const char *tag);
205 
206 /**
207  * Locks the AioContext of @bs if it's not the current AioContext. This avoids
208  * double locking which could lead to deadlocks: This is a coroutine_fn, so we
209  * know we already own the lock of the current AioContext.
210  *
211  * May only be called in the main thread.
212  */
213 void coroutine_fn bdrv_co_lock(BlockDriverState *bs);
214 
215 /**
216  * Unlocks the AioContext of @bs if it's not the current AioContext.
217  */
218 void coroutine_fn bdrv_co_unlock(BlockDriverState *bs);
219 
220 void bdrv_set_aio_context_ignore(BlockDriverState *bs,
221                                  AioContext *new_context, GSList **ignore);
222 int bdrv_try_set_aio_context(BlockDriverState *bs, AioContext *ctx,
223                              Error **errp);
224 int bdrv_child_try_set_aio_context(BlockDriverState *bs, AioContext *ctx,
225                                    BdrvChild *ignore_child, Error **errp);
226 bool bdrv_child_can_set_aio_context(BdrvChild *c, AioContext *ctx,
227                                     GSList **ignore, Error **errp);
228 bool bdrv_can_set_aio_context(BlockDriverState *bs, AioContext *ctx,
229                               GSList **ignore, Error **errp);
230 AioContext *bdrv_child_get_parent_aio_context(BdrvChild *c);
231 
232 int bdrv_probe_blocksizes(BlockDriverState *bs, BlockSizes *bsz);
233 int bdrv_probe_geometry(BlockDriverState *bs, HDGeometry *geo);
234 
235 void bdrv_add_child(BlockDriverState *parent, BlockDriverState *child,
236                     Error **errp);
237 void bdrv_del_child(BlockDriverState *parent, BdrvChild *child, Error **errp);
238 
239 /**
240  *
241  * bdrv_register_buf/bdrv_unregister_buf:
242  *
243  * Register/unregister a buffer for I/O. For example, VFIO drivers are
244  * interested to know the memory areas that would later be used for I/O, so
245  * that they can prepare IOMMU mapping etc., to get better performance.
246  */
247 void bdrv_register_buf(BlockDriverState *bs, void *host, size_t size);
248 void bdrv_unregister_buf(BlockDriverState *bs, void *host);
249 
250 void bdrv_cancel_in_flight(BlockDriverState *bs);
251 
252 #endif /* BLOCK_GLOBAL_STATE_H */
253