xref: /qemu/include/block/block-copy.h (revision cc1838c2)
1 /*
2  * block_copy API
3  *
4  * Copyright (C) 2013 Proxmox Server Solutions
5  * Copyright (c) 2019 Virtuozzo International GmbH.
6  *
7  * Authors:
8  *  Dietmar Maurer (dietmar@proxmox.com)
9  *  Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
10  *
11  * This work is licensed under the terms of the GNU GPL, version 2 or later.
12  * See the COPYING file in the top-level directory.
13  */
14 
15 #ifndef BLOCK_COPY_H
16 #define BLOCK_COPY_H
17 
18 #include "block/block.h"
19 #include "qemu/co-shared-resource.h"
20 
21 /* All APIs are thread-safe */
22 
23 typedef void (*BlockCopyAsyncCallbackFunc)(void *opaque);
24 typedef struct BlockCopyState BlockCopyState;
25 typedef struct BlockCopyCallState BlockCopyCallState;
26 
27 BlockCopyState *block_copy_state_new(BdrvChild *source, BdrvChild *target,
28                                      int64_t cluster_size, bool use_copy_range,
29                                      BdrvRequestFlags write_flags,
30                                      Error **errp);
31 
32 void block_copy_set_progress_meter(BlockCopyState *s, ProgressMeter *pm);
33 
34 void block_copy_state_free(BlockCopyState *s);
35 
36 int64_t block_copy_reset_unallocated(BlockCopyState *s,
37                                      int64_t offset, int64_t *count);
38 
39 int coroutine_fn block_copy(BlockCopyState *s, int64_t offset, int64_t bytes,
40                             bool ignore_ratelimit);
41 
42 /*
43  * Run block-copy in a coroutine, create corresponding BlockCopyCallState
44  * object and return pointer to it. Never returns NULL.
45  *
46  * Caller is responsible to call block_copy_call_free() to free
47  * BlockCopyCallState object.
48  *
49  * @max_workers means maximum of parallel coroutines to execute sub-requests,
50  * must be > 0.
51  *
52  * @max_chunk means maximum length for one IO operation. Zero means unlimited.
53  */
54 BlockCopyCallState *block_copy_async(BlockCopyState *s,
55                                      int64_t offset, int64_t bytes,
56                                      int max_workers, int64_t max_chunk,
57                                      BlockCopyAsyncCallbackFunc cb,
58                                      void *cb_opaque);
59 
60 /*
61  * Free finished BlockCopyCallState. Trying to free running
62  * block-copy will crash.
63  */
64 void block_copy_call_free(BlockCopyCallState *call_state);
65 
66 /*
67  * Note, that block-copy call is marked finished prior to calling
68  * the callback.
69  */
70 bool block_copy_call_finished(BlockCopyCallState *call_state);
71 bool block_copy_call_succeeded(BlockCopyCallState *call_state);
72 bool block_copy_call_failed(BlockCopyCallState *call_state);
73 bool block_copy_call_cancelled(BlockCopyCallState *call_state);
74 int block_copy_call_status(BlockCopyCallState *call_state, bool *error_is_read);
75 
76 void block_copy_set_speed(BlockCopyState *s, uint64_t speed);
77 void block_copy_kick(BlockCopyCallState *call_state);
78 
79 /*
80  * Cancel running block-copy call.
81  *
82  * Cancel leaves block-copy state valid: dirty bits are correct and you may use
83  * cancel + <run block_copy with same parameters> to emulate pause/resume.
84  *
85  * Note also, that the cancel is async: it only marks block-copy call to be
86  * cancelled. So, the call may be cancelled (block_copy_call_cancelled() reports
87  * true) but not yet finished (block_copy_call_finished() reports false).
88  */
89 void block_copy_call_cancel(BlockCopyCallState *call_state);
90 
91 BdrvDirtyBitmap *block_copy_dirty_bitmap(BlockCopyState *s);
92 void block_copy_set_skip_unallocated(BlockCopyState *s, bool skip);
93 
94 #endif /* BLOCK_COPY_H */
95