]> git.proxmox.com Git - mirror_qemu.git/blob - include/block/block-io.h
Merge tag 'pull-ufs-20231013' of https://gitlab.com/jeuk20.kim/qemu into staging
[mirror_qemu.git] / include / block / block-io.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_IO_H
25 #define BLOCK_IO_H
26
27 #include "block/aio-wait.h"
28 #include "block/block-common.h"
29 #include "qemu/coroutine.h"
30 #include "qemu/iov.h"
31
32 /*
33 * I/O API functions. These functions are thread-safe, and therefore
34 * can run in any thread as long as the thread has called
35 * aio_context_acquire/release().
36 *
37 * These functions can only call functions from I/O and Common categories,
38 * but can be invoked by GS, "I/O or GS" and I/O APIs.
39 *
40 * All functions in this category must use the macro
41 * IO_CODE();
42 * to catch when they are accidentally called by the wrong API.
43 */
44
45 int co_wrapper_mixed_bdrv_rdlock
46 bdrv_pwrite_zeroes(BdrvChild *child, int64_t offset, int64_t bytes,
47 BdrvRequestFlags flags);
48
49 int bdrv_make_zero(BdrvChild *child, BdrvRequestFlags flags);
50
51 int co_wrapper_mixed_bdrv_rdlock
52 bdrv_pread(BdrvChild *child, int64_t offset, int64_t bytes, void *buf,
53 BdrvRequestFlags flags);
54
55 int co_wrapper_mixed_bdrv_rdlock
56 bdrv_pwrite(BdrvChild *child, int64_t offset,int64_t bytes,
57 const void *buf, BdrvRequestFlags flags);
58
59 int co_wrapper_mixed_bdrv_rdlock
60 bdrv_pwrite_sync(BdrvChild *child, int64_t offset, int64_t bytes,
61 const void *buf, BdrvRequestFlags flags);
62
63 int coroutine_fn GRAPH_RDLOCK
64 bdrv_co_pwrite_sync(BdrvChild *child, int64_t offset, int64_t bytes,
65 const void *buf, BdrvRequestFlags flags);
66
67 /*
68 * Efficiently zero a region of the disk image. Note that this is a regular
69 * I/O request like read or write and should have a reasonable size. This
70 * function is not suitable for zeroing the entire image in a single request
71 * because it may allocate memory for the entire region.
72 */
73 int coroutine_fn GRAPH_RDLOCK
74 bdrv_co_pwrite_zeroes(BdrvChild *child, int64_t offset, int64_t bytes,
75 BdrvRequestFlags flags);
76
77 int coroutine_fn GRAPH_RDLOCK
78 bdrv_co_truncate(BdrvChild *child, int64_t offset, bool exact,
79 PreallocMode prealloc, BdrvRequestFlags flags, Error **errp);
80
81 int64_t coroutine_fn GRAPH_RDLOCK bdrv_co_nb_sectors(BlockDriverState *bs);
82 int64_t coroutine_mixed_fn bdrv_nb_sectors(BlockDriverState *bs);
83
84 int64_t coroutine_fn GRAPH_RDLOCK bdrv_co_getlength(BlockDriverState *bs);
85 int64_t co_wrapper_mixed_bdrv_rdlock bdrv_getlength(BlockDriverState *bs);
86
87 int64_t coroutine_fn GRAPH_RDLOCK
88 bdrv_co_get_allocated_file_size(BlockDriverState *bs);
89
90 int64_t co_wrapper_bdrv_rdlock
91 bdrv_get_allocated_file_size(BlockDriverState *bs);
92
93 BlockMeasureInfo *bdrv_measure(BlockDriver *drv, QemuOpts *opts,
94 BlockDriverState *in_bs, Error **errp);
95
96 int coroutine_fn GRAPH_RDLOCK
97 bdrv_co_delete_file(BlockDriverState *bs, Error **errp);
98
99 void coroutine_fn GRAPH_RDLOCK
100 bdrv_co_delete_file_noerr(BlockDriverState *bs);
101
102
103 /* async block I/O */
104 void bdrv_aio_cancel_async(BlockAIOCB *acb);
105
106 /* sg packet commands */
107 int coroutine_fn GRAPH_RDLOCK
108 bdrv_co_ioctl(BlockDriverState *bs, int req, void *buf);
109
110 /* Ensure contents are flushed to disk. */
111 int coroutine_fn GRAPH_RDLOCK bdrv_co_flush(BlockDriverState *bs);
112
113 int coroutine_fn GRAPH_RDLOCK bdrv_co_pdiscard(BdrvChild *child, int64_t offset,
114 int64_t bytes);
115
116 /* Report zone information of zone block device. */
117 int coroutine_fn GRAPH_RDLOCK bdrv_co_zone_report(BlockDriverState *bs,
118 int64_t offset,
119 unsigned int *nr_zones,
120 BlockZoneDescriptor *zones);
121 int coroutine_fn GRAPH_RDLOCK bdrv_co_zone_mgmt(BlockDriverState *bs,
122 BlockZoneOp op,
123 int64_t offset, int64_t len);
124 int coroutine_fn GRAPH_RDLOCK bdrv_co_zone_append(BlockDriverState *bs,
125 int64_t *offset,
126 QEMUIOVector *qiov,
127 BdrvRequestFlags flags);
128
129 bool bdrv_can_write_zeroes_with_unmap(BlockDriverState *bs);
130
131 int coroutine_fn GRAPH_RDLOCK
132 bdrv_co_block_status(BlockDriverState *bs, int64_t offset, int64_t bytes,
133 int64_t *pnum, int64_t *map, BlockDriverState **file);
134 int co_wrapper_mixed_bdrv_rdlock
135 bdrv_block_status(BlockDriverState *bs, int64_t offset, int64_t bytes,
136 int64_t *pnum, int64_t *map, BlockDriverState **file);
137
138 int coroutine_fn GRAPH_RDLOCK
139 bdrv_co_block_status_above(BlockDriverState *bs, BlockDriverState *base,
140 int64_t offset, int64_t bytes, int64_t *pnum,
141 int64_t *map, BlockDriverState **file);
142 int co_wrapper_mixed_bdrv_rdlock
143 bdrv_block_status_above(BlockDriverState *bs, BlockDriverState *base,
144 int64_t offset, int64_t bytes, int64_t *pnum,
145 int64_t *map, BlockDriverState **file);
146
147 int coroutine_fn GRAPH_RDLOCK
148 bdrv_co_is_allocated(BlockDriverState *bs, int64_t offset, int64_t bytes,
149 int64_t *pnum);
150 int co_wrapper_mixed_bdrv_rdlock
151 bdrv_is_allocated(BlockDriverState *bs, int64_t offset,
152 int64_t bytes, int64_t *pnum);
153
154 int coroutine_fn GRAPH_RDLOCK
155 bdrv_co_is_allocated_above(BlockDriverState *top, BlockDriverState *base,
156 bool include_base, int64_t offset, int64_t bytes,
157 int64_t *pnum);
158 int co_wrapper_mixed_bdrv_rdlock
159 bdrv_is_allocated_above(BlockDriverState *bs, BlockDriverState *base,
160 bool include_base, int64_t offset,
161 int64_t bytes, int64_t *pnum);
162
163 int coroutine_fn GRAPH_RDLOCK
164 bdrv_co_is_zero_fast(BlockDriverState *bs, int64_t offset, int64_t bytes);
165
166 int GRAPH_RDLOCK
167 bdrv_apply_auto_read_only(BlockDriverState *bs, const char *errmsg,
168 Error **errp);
169
170 bool bdrv_is_read_only(BlockDriverState *bs);
171 bool bdrv_is_writable(BlockDriverState *bs);
172 bool bdrv_is_sg(BlockDriverState *bs);
173 int bdrv_get_flags(BlockDriverState *bs);
174
175 bool coroutine_fn GRAPH_RDLOCK bdrv_co_is_inserted(BlockDriverState *bs);
176 bool co_wrapper_bdrv_rdlock bdrv_is_inserted(BlockDriverState *bs);
177
178 void coroutine_fn GRAPH_RDLOCK
179 bdrv_co_lock_medium(BlockDriverState *bs, bool locked);
180
181 void coroutine_fn GRAPH_RDLOCK
182 bdrv_co_eject(BlockDriverState *bs, bool eject_flag);
183
184 const char *bdrv_get_format_name(BlockDriverState *bs);
185
186 bool bdrv_supports_compressed_writes(BlockDriverState *bs);
187 const char *bdrv_get_node_name(const BlockDriverState *bs);
188
189 const char * GRAPH_RDLOCK
190 bdrv_get_device_name(const BlockDriverState *bs);
191
192 const char * GRAPH_RDLOCK
193 bdrv_get_device_or_node_name(const BlockDriverState *bs);
194
195 int coroutine_fn GRAPH_RDLOCK
196 bdrv_co_get_info(BlockDriverState *bs, BlockDriverInfo *bdi);
197
198 int co_wrapper_mixed_bdrv_rdlock
199 bdrv_get_info(BlockDriverState *bs, BlockDriverInfo *bdi);
200
201 ImageInfoSpecific * GRAPH_RDLOCK
202 bdrv_get_specific_info(BlockDriverState *bs, Error **errp);
203
204 BlockStatsSpecific *bdrv_get_specific_stats(BlockDriverState *bs);
205 void bdrv_round_to_subclusters(BlockDriverState *bs,
206 int64_t offset, int64_t bytes,
207 int64_t *cluster_offset,
208 int64_t *cluster_bytes);
209
210 void bdrv_get_backing_filename(BlockDriverState *bs,
211 char *filename, int filename_size);
212
213 int bdrv_save_vmstate(BlockDriverState *bs, const uint8_t *buf,
214 int64_t pos, int size);
215
216 int bdrv_load_vmstate(BlockDriverState *bs, uint8_t *buf,
217 int64_t pos, int size);
218
219 /*
220 * Returns the alignment in bytes that is required so that no bounce buffer
221 * is required throughout the stack
222 */
223 size_t bdrv_min_mem_align(BlockDriverState *bs);
224 /* Returns optimal alignment in bytes for bounce buffer */
225 size_t bdrv_opt_mem_align(BlockDriverState *bs);
226 void *qemu_blockalign(BlockDriverState *bs, size_t size);
227 void *qemu_blockalign0(BlockDriverState *bs, size_t size);
228 void *qemu_try_blockalign(BlockDriverState *bs, size_t size);
229 void *qemu_try_blockalign0(BlockDriverState *bs, size_t size);
230
231 void bdrv_enable_copy_on_read(BlockDriverState *bs);
232 void bdrv_disable_copy_on_read(BlockDriverState *bs);
233
234 void coroutine_fn GRAPH_RDLOCK
235 bdrv_co_debug_event(BlockDriverState *bs, BlkdebugEvent event);
236
237 void co_wrapper_mixed_bdrv_rdlock
238 bdrv_debug_event(BlockDriverState *bs, BlkdebugEvent event);
239
240 #define BLKDBG_CO_EVENT(child, evt) \
241 do { \
242 if (child) { \
243 bdrv_co_debug_event(child->bs, evt); \
244 } \
245 } while (0)
246
247 #define BLKDBG_EVENT(child, evt) \
248 do { \
249 if (child) { \
250 bdrv_debug_event(child->bs, evt); \
251 } \
252 } while (0)
253
254 /**
255 * bdrv_get_aio_context:
256 *
257 * Returns: the currently bound #AioContext
258 */
259 AioContext *bdrv_get_aio_context(BlockDriverState *bs);
260
261 AioContext *bdrv_child_get_parent_aio_context(BdrvChild *c);
262
263 /**
264 * Move the current coroutine to the AioContext of @bs and return the old
265 * AioContext of the coroutine. Increase bs->in_flight so that draining @bs
266 * will wait for the operation to proceed until the corresponding
267 * bdrv_co_leave().
268 *
269 * Consequently, you can't call drain inside a bdrv_co_enter/leave() section as
270 * this will deadlock.
271 */
272 AioContext *coroutine_fn bdrv_co_enter(BlockDriverState *bs);
273
274 /**
275 * Ends a section started by bdrv_co_enter(). Move the current coroutine back
276 * to old_ctx and decrease bs->in_flight again.
277 */
278 void coroutine_fn bdrv_co_leave(BlockDriverState *bs, AioContext *old_ctx);
279
280 AioContext *child_of_bds_get_parent_aio_context(BdrvChild *c);
281
282 bool coroutine_fn GRAPH_RDLOCK
283 bdrv_co_can_store_new_dirty_bitmap(BlockDriverState *bs, const char *name,
284 uint32_t granularity, Error **errp);
285 bool co_wrapper_bdrv_rdlock
286 bdrv_can_store_new_dirty_bitmap(BlockDriverState *bs, const char *name,
287 uint32_t granularity, Error **errp);
288
289 /**
290 *
291 * bdrv_co_copy_range:
292 *
293 * Do offloaded copy between two children. If the operation is not implemented
294 * by the driver, or if the backend storage doesn't support it, a negative
295 * error code will be returned.
296 *
297 * Note: block layer doesn't emulate or fallback to a bounce buffer approach
298 * because usually the caller shouldn't attempt offloaded copy any more (e.g.
299 * calling copy_file_range(2)) after the first error, thus it should fall back
300 * to a read+write path in the caller level.
301 *
302 * @src: Source child to copy data from
303 * @src_offset: offset in @src image to read data
304 * @dst: Destination child to copy data to
305 * @dst_offset: offset in @dst image to write data
306 * @bytes: number of bytes to copy
307 * @flags: request flags. Supported flags:
308 * BDRV_REQ_ZERO_WRITE - treat the @src range as zero data and do zero
309 * write on @dst as if bdrv_co_pwrite_zeroes is
310 * called. Used to simplify caller code, or
311 * during BlockDriver.bdrv_co_copy_range_from()
312 * recursion.
313 * BDRV_REQ_NO_SERIALISING - do not serialize with other overlapping
314 * requests currently in flight.
315 *
316 * Returns: 0 if succeeded; negative error code if failed.
317 **/
318 int coroutine_fn GRAPH_RDLOCK
319 bdrv_co_copy_range(BdrvChild *src, int64_t src_offset,
320 BdrvChild *dst, int64_t dst_offset,
321 int64_t bytes, BdrvRequestFlags read_flags,
322 BdrvRequestFlags write_flags);
323
324 /*
325 * "I/O or GS" API functions. These functions can run without
326 * the BQL, but only in one specific iothread/main loop.
327 *
328 * More specifically, these functions use BDRV_POLL_WHILE(bs), which
329 * requires the caller to be either in the main thread and hold
330 * the BlockdriverState (bs) AioContext lock, or directly in the
331 * home thread that runs the bs AioContext. Calling them from
332 * another thread in another AioContext would cause deadlocks.
333 *
334 * Therefore, these functions are not proper I/O, because they
335 * can't run in *any* iothreads, but only in a specific one.
336 *
337 * These functions can call any function from I/O, Common and this
338 * categories, but must be invoked only by other "I/O or GS" and GS APIs.
339 *
340 * All functions in this category must use the macro
341 * IO_OR_GS_CODE();
342 * to catch when they are accidentally called by the wrong API.
343 */
344
345 #define BDRV_POLL_WHILE(bs, cond) ({ \
346 BlockDriverState *bs_ = (bs); \
347 IO_OR_GS_CODE(); \
348 AIO_WAIT_WHILE(bdrv_get_aio_context(bs_), \
349 cond); })
350
351 void bdrv_drain(BlockDriverState *bs);
352
353 int co_wrapper_mixed_bdrv_rdlock
354 bdrv_truncate(BdrvChild *child, int64_t offset, bool exact,
355 PreallocMode prealloc, BdrvRequestFlags flags, Error **errp);
356
357 int co_wrapper_mixed_bdrv_rdlock
358 bdrv_check(BlockDriverState *bs, BdrvCheckResult *res, BdrvCheckMode fix);
359
360 /* Invalidate any cached metadata used by image formats */
361 int co_wrapper_mixed_bdrv_rdlock
362 bdrv_invalidate_cache(BlockDriverState *bs, Error **errp);
363
364 int co_wrapper_mixed_bdrv_rdlock bdrv_flush(BlockDriverState *bs);
365
366 int co_wrapper_mixed_bdrv_rdlock
367 bdrv_pdiscard(BdrvChild *child, int64_t offset, int64_t bytes);
368
369 int co_wrapper_mixed_bdrv_rdlock
370 bdrv_readv_vmstate(BlockDriverState *bs, QEMUIOVector *qiov, int64_t pos);
371
372 int co_wrapper_mixed_bdrv_rdlock
373 bdrv_writev_vmstate(BlockDriverState *bs, QEMUIOVector *qiov, int64_t pos);
374
375 /**
376 * bdrv_parent_drained_begin_single:
377 *
378 * Begin a quiesced section for the parent of @c.
379 */
380 void GRAPH_RDLOCK bdrv_parent_drained_begin_single(BdrvChild *c);
381
382 /**
383 * bdrv_parent_drained_poll_single:
384 *
385 * Returns true if there is any pending activity to cease before @c can be
386 * called quiesced, false otherwise.
387 */
388 bool GRAPH_RDLOCK bdrv_parent_drained_poll_single(BdrvChild *c);
389
390 /**
391 * bdrv_parent_drained_end_single:
392 *
393 * End a quiesced section for the parent of @c.
394 */
395 void GRAPH_RDLOCK bdrv_parent_drained_end_single(BdrvChild *c);
396
397 /**
398 * bdrv_drain_poll:
399 *
400 * Poll for pending requests in @bs and its parents (except for @ignore_parent).
401 *
402 * If @ignore_bds_parents is true, parents that are BlockDriverStates must
403 * ignore the drain request because they will be drained separately (used for
404 * drain_all).
405 *
406 * This is part of bdrv_drained_begin.
407 */
408 bool GRAPH_RDLOCK
409 bdrv_drain_poll(BlockDriverState *bs, BdrvChild *ignore_parent,
410 bool ignore_bds_parents);
411
412 /**
413 * bdrv_drained_begin:
414 *
415 * Begin a quiesced section for exclusive access to the BDS, by disabling
416 * external request sources including NBD server, block jobs, and device model.
417 *
418 * This function can only be invoked by the main loop or a coroutine
419 * (regardless of the AioContext where it is running).
420 * If the coroutine is running in an Iothread AioContext, this function will
421 * just schedule a BH to run in the main loop.
422 * However, it cannot be directly called by an Iothread.
423 *
424 * This function can be recursive.
425 */
426 void bdrv_drained_begin(BlockDriverState *bs);
427
428 /**
429 * bdrv_do_drained_begin_quiesce:
430 *
431 * Quiesces a BDS like bdrv_drained_begin(), but does not wait for already
432 * running requests to complete.
433 */
434 void bdrv_do_drained_begin_quiesce(BlockDriverState *bs, BdrvChild *parent);
435
436 /**
437 * bdrv_drained_end:
438 *
439 * End a quiescent section started by bdrv_drained_begin().
440 *
441 * This function can only be invoked by the main loop or a coroutine
442 * (regardless of the AioContext where it is running).
443 * If the coroutine is running in an Iothread AioContext, this function will
444 * just schedule a BH to run in the main loop.
445 * However, it cannot be directly called by an Iothread.
446 */
447 void bdrv_drained_end(BlockDriverState *bs);
448
449 #endif /* BLOCK_IO_H */