| 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 | |
| 25 | #ifndef BLOCK_INT_GLOBAL_STATE_H |
| 26 | #define BLOCK_INT_GLOBAL_STATE_H |
| 27 | |
| 28 | #include "block/blockjob.h" |
| 29 | #include "block/block_int-common.h" |
| 30 | #include "qemu/hbitmap.h" |
| 31 | #include "qemu/main-loop.h" |
| 32 | |
| 33 | /* |
| 34 | * Global state (GS) API. These functions run under the BQL. |
| 35 | * |
| 36 | * See include/block/block-global-state.h for more information about |
| 37 | * the GS API. |
| 38 | */ |
| 39 | |
| 40 | /** |
| 41 | * stream_start: |
| 42 | * @job_id: The id of the newly-created job, or %NULL to use the |
| 43 | * device name of @bs. |
| 44 | * @bs: Block device to operate on. |
| 45 | * @base: Block device that will become the new base, or %NULL to |
| 46 | * flatten the whole backing file chain onto @bs. |
| 47 | * @backing_file_str: The file name that will be written to @bs as the |
| 48 | * the new backing file if the job completes. Ignored if @base is %NULL. |
| 49 | * @backing_mask_protocol: Replace potential protocol name with 'raw' in |
| 50 | * 'backing file format' header |
| 51 | * @creation_flags: Flags that control the behavior of the Job lifetime. |
| 52 | * See @BlockJobCreateFlags |
| 53 | * @speed: The maximum speed, in bytes per second, or 0 for unlimited. |
| 54 | * @on_error: The action to take upon error. |
| 55 | * @filter_node_name: The node name that should be assigned to the filter |
| 56 | * driver that the stream job inserts into the graph above |
| 57 | * @bs. NULL means that a node name should be autogenerated. |
| 58 | * @errp: Error object. |
| 59 | * |
| 60 | * Start a streaming operation on @bs. Clusters that are unallocated |
| 61 | * in @bs, but allocated in any image between @base and @bs (both |
| 62 | * exclusive) will be written to @bs. At the end of a successful |
| 63 | * streaming job, the backing file of @bs will be changed to |
| 64 | * @backing_file_str in the written image and to @base in the live |
| 65 | * BlockDriverState. |
| 66 | */ |
| 67 | void stream_start(const char *job_id, BlockDriverState *bs, |
| 68 | BlockDriverState *base, const char *backing_file_str, |
| 69 | bool backing_mask_protocol, |
| 70 | BlockDriverState *bottom, |
| 71 | int creation_flags, int64_t speed, |
| 72 | BlockdevOnError on_error, |
| 73 | const char *filter_node_name, |
| 74 | Error **errp); |
| 75 | |
| 76 | /** |
| 77 | * commit_start: |
| 78 | * @job_id: The id of the newly-created job, or %NULL to use the |
| 79 | * device name of @bs. |
| 80 | * @bs: Active block device. |
| 81 | * @top: Top block device to be committed. |
| 82 | * @base: Block device that will be written into, and become the new top. |
| 83 | * @creation_flags: Flags that control the behavior of the Job lifetime. |
| 84 | * See @BlockJobCreateFlags |
| 85 | * @speed: The maximum speed, in bytes per second, or 0 for unlimited. |
| 86 | * @on_error: The action to take upon error. |
| 87 | * @backing_file_str: String to use as the backing file in @top's overlay |
| 88 | * @backing_mask_protocol: Replace potential protocol name with 'raw' in |
| 89 | * 'backing file format' header |
| 90 | * @filter_node_name: The node name that should be assigned to the filter |
| 91 | * driver that the commit job inserts into the graph above @top. NULL means |
| 92 | * that a node name should be autogenerated. |
| 93 | * @errp: Error object. |
| 94 | * |
| 95 | */ |
| 96 | void commit_start(const char *job_id, BlockDriverState *bs, |
| 97 | BlockDriverState *base, BlockDriverState *top, |
| 98 | int creation_flags, int64_t speed, |
| 99 | BlockdevOnError on_error, const char *backing_file_str, |
| 100 | bool backing_mask_protocol, |
| 101 | const char *filter_node_name, Error **errp); |
| 102 | /** |
| 103 | * commit_active_start: |
| 104 | * @job_id: The id of the newly-created job, or %NULL to use the |
| 105 | * device name of @bs. |
| 106 | * @bs: Active block device to be committed. |
| 107 | * @base: Block device that will be written into, and become the new top. |
| 108 | * @creation_flags: Flags that control the behavior of the Job lifetime. |
| 109 | * See @BlockJobCreateFlags |
| 110 | * @speed: The maximum speed, in bytes per second, or 0 for unlimited. |
| 111 | * @on_error: The action to take upon error. |
| 112 | * @filter_node_name: The node name that should be assigned to the filter |
| 113 | * driver that the commit job inserts into the graph above @bs. NULL means that |
| 114 | * a node name should be autogenerated. |
| 115 | * @cb: Completion function for the job. |
| 116 | * @opaque: Opaque pointer value passed to @cb. |
| 117 | * @auto_complete: Auto complete the job. |
| 118 | * @errp: Error object. |
| 119 | * |
| 120 | */ |
| 121 | BlockJob *commit_active_start(const char *job_id, BlockDriverState *bs, |
| 122 | BlockDriverState *base, int creation_flags, |
| 123 | int64_t speed, BlockdevOnError on_error, |
| 124 | const char *filter_node_name, |
| 125 | BlockCompletionFunc *cb, void *opaque, |
| 126 | bool auto_complete, Error **errp); |
| 127 | /* |
| 128 | * mirror_start: |
| 129 | * @job_id: The id of the newly-created job, or %NULL to use the |
| 130 | * device name of @bs. |
| 131 | * @bs: Block device to operate on. |
| 132 | * @target: Block device to write to. |
| 133 | * @replaces: Block graph node name to replace once the mirror is done. Can |
| 134 | * only be used when full mirroring is selected. |
| 135 | * @creation_flags: Flags that control the behavior of the Job lifetime. |
| 136 | * See @BlockJobCreateFlags |
| 137 | * @speed: The maximum speed, in bytes per second, or 0 for unlimited. |
| 138 | * @granularity: The chosen granularity for the dirty bitmap. |
| 139 | * @buf_size: The amount of data that can be in flight at one time. |
| 140 | * @mode: Whether to collapse all images in the chain to the target. |
| 141 | * @backing_mode: How to establish the target's backing chain after completion. |
| 142 | * @target_is_zero: Whether the target already is zero-initialized. |
| 143 | * @on_source_error: The action to take upon error reading from the source. |
| 144 | * @on_target_error: The action to take upon error writing to the target. |
| 145 | * @unmap: Whether to unmap target where source sectors only contain zeroes. |
| 146 | * @filter_node_name: The node name that should be assigned to the filter |
| 147 | * driver that the mirror job inserts into the graph above @bs. NULL means that |
| 148 | * a node name should be autogenerated. |
| 149 | * @copy_mode: When to trigger writes to the target. |
| 150 | * @errp: Error object. |
| 151 | * |
| 152 | * Start a mirroring operation on @bs. Clusters that are allocated |
| 153 | * in @bs will be written to @target until the job is cancelled or |
| 154 | * manually completed. At the end of a successful mirroring job, |
| 155 | * @bs will be switched to read from @target. |
| 156 | */ |
| 157 | void mirror_start(const char *job_id, BlockDriverState *bs, |
| 158 | BlockDriverState *target, const char *replaces, |
| 159 | int creation_flags, int64_t speed, |
| 160 | uint32_t granularity, int64_t buf_size, |
| 161 | MirrorSyncMode mode, BlockMirrorBackingMode backing_mode, |
| 162 | bool target_is_zero, |
| 163 | BlockdevOnError on_source_error, |
| 164 | BlockdevOnError on_target_error, |
| 165 | bool unmap, const char *filter_node_name, |
| 166 | MirrorCopyMode copy_mode, Error **errp); |
| 167 | |
| 168 | /* |
| 169 | * backup_job_create: |
| 170 | * @job_id: The id of the newly-created job, or %NULL to use the |
| 171 | * device name of @bs. |
| 172 | * @bs: Block device to operate on. |
| 173 | * @target: Block device to write to. |
| 174 | * @speed: The maximum speed, in bytes per second, or 0 for unlimited. |
| 175 | * @sync_mode: What parts of the disk image should be copied to the destination. |
| 176 | * @sync_bitmap: The dirty bitmap if sync_mode is 'bitmap' or 'incremental' |
| 177 | * @bitmap_mode: The bitmap synchronization policy to use. |
| 178 | * @perf: Performance options. All actual fields assumed to be present, |
| 179 | * all ".has_*" fields are ignored. |
| 180 | * @on_source_error: The action to take upon error reading from the source. |
| 181 | * @on_target_error: The action to take upon error writing to the target. |
| 182 | * @on_cbw_error: The action to take upon error in copy-before-write operations. |
| 183 | * @creation_flags: Flags that control the behavior of the Job lifetime. |
| 184 | * See @BlockJobCreateFlags |
| 185 | * @cb: Completion function for the job. |
| 186 | * @opaque: Opaque pointer value passed to @cb. |
| 187 | * @txn: Transaction that this job is part of (may be NULL). |
| 188 | * |
| 189 | * Create a backup operation on @bs. Clusters in @bs are written to @target |
| 190 | * until the job is cancelled or manually completed. |
| 191 | */ |
| 192 | BlockJob *backup_job_create(const char *job_id, BlockDriverState *bs, |
| 193 | BlockDriverState *target, int64_t speed, |
| 194 | MirrorSyncMode sync_mode, |
| 195 | BdrvDirtyBitmap *sync_bitmap, |
| 196 | BitmapSyncMode bitmap_mode, |
| 197 | bool compress, bool discard_source, |
| 198 | const char *filter_node_name, |
| 199 | BackupPerf *perf, |
| 200 | BlockdevOnError on_source_error, |
| 201 | BlockdevOnError on_target_error, |
| 202 | OnCbwError on_cbw_error, |
| 203 | int creation_flags, |
| 204 | BlockCompletionFunc *cb, void *opaque, |
| 205 | JobTxn *txn, Error **errp); |
| 206 | |
| 207 | BdrvChild * GRAPH_WRLOCK |
| 208 | bdrv_root_attach_child(BlockDriverState *child_bs, const char *child_name, |
| 209 | const BdrvChildClass *child_class, |
| 210 | BdrvChildRole child_role, |
| 211 | uint64_t perm, uint64_t shared_perm, |
| 212 | void *opaque, Error **errp); |
| 213 | |
| 214 | void GRAPH_WRLOCK bdrv_root_unref_child(BdrvChild *child); |
| 215 | |
| 216 | void GRAPH_RDLOCK bdrv_get_cumulative_perm(BlockDriverState *bs, uint64_t *perm, |
| 217 | uint64_t *shared_perm); |
| 218 | |
| 219 | /** |
| 220 | * Sets a BdrvChild's permissions. Avoid if the parent is a BDS; use |
| 221 | * bdrv_child_refresh_perms() instead and make the parent's |
| 222 | * .bdrv_child_perm() implementation return the correct values. |
| 223 | */ |
| 224 | int GRAPH_RDLOCK |
| 225 | bdrv_child_try_set_perm(BdrvChild *c, uint64_t perm, uint64_t shared, |
| 226 | Error **errp); |
| 227 | |
| 228 | /** |
| 229 | * Calls bs->drv->bdrv_child_perm() and updates the child's permission |
| 230 | * masks with the result. |
| 231 | * Drivers should invoke this function whenever an event occurs that |
| 232 | * makes their .bdrv_child_perm() implementation return different |
| 233 | * values than before, but which will not result in the block layer |
| 234 | * automatically refreshing the permissions. |
| 235 | */ |
| 236 | int GRAPH_RDLOCK |
| 237 | bdrv_child_refresh_perms(BlockDriverState *bs, BdrvChild *c, Error **errp); |
| 238 | |
| 239 | bool GRAPH_RDLOCK bdrv_recurse_can_replace(BlockDriverState *bs, |
| 240 | BlockDriverState *to_replace); |
| 241 | |
| 242 | /* |
| 243 | * Default implementation for BlockDriver.bdrv_child_perm() that can |
| 244 | * be used by block filters and image formats, as long as they use the |
| 245 | * child_of_bds child class and set an appropriate BdrvChildRole. |
| 246 | */ |
| 247 | void bdrv_default_perms(BlockDriverState *bs, BdrvChild *c, |
| 248 | BdrvChildRole role, BlockReopenQueue *reopen_queue, |
| 249 | uint64_t perm, uint64_t shared, |
| 250 | uint64_t *nperm, uint64_t *nshared); |
| 251 | |
| 252 | void blk_dev_change_media_cb(BlockBackend *blk, bool load, Error **errp); |
| 253 | bool blk_dev_has_removable_media(BlockBackend *blk); |
| 254 | void blk_dev_eject_request(BlockBackend *blk, bool force); |
| 255 | bool blk_dev_is_medium_locked(BlockBackend *blk); |
| 256 | |
| 257 | void bdrv_restore_dirty_bitmap(BdrvDirtyBitmap *bitmap, HBitmap *backup); |
| 258 | |
| 259 | void bdrv_set_monitor_owned(BlockDriverState *bs); |
| 260 | |
| 261 | void blockdev_close_all_bdrv_states(void); |
| 262 | |
| 263 | BlockDriverState *bds_tree_init(QDict *bs_opts, Error **errp); |
| 264 | |
| 265 | /** |
| 266 | * Simple implementation of bdrv_co_create_opts for protocol drivers |
| 267 | * which only support creation via opening a file |
| 268 | * (usually existing raw storage device) |
| 269 | */ |
| 270 | int coroutine_fn bdrv_co_create_opts_simple(BlockDriver *drv, |
| 271 | const char *filename, |
| 272 | QemuOpts *opts, |
| 273 | Error **errp); |
| 274 | |
| 275 | BdrvDirtyBitmap *block_dirty_bitmap_lookup(const char *node, |
| 276 | const char *name, |
| 277 | BlockDriverState **pbs, |
| 278 | Error **errp); |
| 279 | BdrvDirtyBitmap *block_dirty_bitmap_merge(const char *node, const char *target, |
| 280 | BlockDirtyBitmapOrStrList *bms, |
| 281 | HBitmap **backup, Error **errp); |
| 282 | BdrvDirtyBitmap *block_dirty_bitmap_remove(const char *node, const char *name, |
| 283 | bool release, |
| 284 | BlockDriverState **bitmap_bs, |
| 285 | Error **errp); |
| 286 | |
| 287 | |
| 288 | BlockDriverState * GRAPH_RDLOCK |
| 289 | bdrv_skip_implicit_filters(BlockDriverState *bs); |
| 290 | |
| 291 | /** |
| 292 | * bdrv_add_aio_context_notifier: |
| 293 | * |
| 294 | * If a long-running job intends to be always run in the same AioContext as a |
| 295 | * certain BDS, it may use this function to be notified of changes regarding the |
| 296 | * association of the BDS to an AioContext. |
| 297 | * |
| 298 | * attached_aio_context() is called after the target BDS has been attached to a |
| 299 | * new AioContext; detach_aio_context() is called before the target BDS is being |
| 300 | * detached from its old AioContext. |
| 301 | */ |
| 302 | void bdrv_add_aio_context_notifier(BlockDriverState *bs, |
| 303 | void (*attached_aio_context)(AioContext *new_context, void *opaque), |
| 304 | void (*detach_aio_context)(void *opaque), void *opaque); |
| 305 | |
| 306 | /** |
| 307 | * bdrv_remove_aio_context_notifier: |
| 308 | * |
| 309 | * Unsubscribe of change notifications regarding the BDS's AioContext. The |
| 310 | * parameters given here have to be the same as those given to |
| 311 | * bdrv_add_aio_context_notifier(). |
| 312 | */ |
| 313 | void bdrv_remove_aio_context_notifier(BlockDriverState *bs, |
| 314 | void (*aio_context_attached)(AioContext *, |
| 315 | void *), |
| 316 | void (*aio_context_detached)(void *), |
| 317 | void *opaque); |
| 318 | |
| 319 | /** |
| 320 | * End all quiescent sections started by bdrv_drain_all_begin(). This is |
| 321 | * needed when deleting a BDS before bdrv_drain_all_end() is called. |
| 322 | * |
| 323 | * NOTE: this is an internal helper for bdrv_close() *only*. No one else |
| 324 | * should call it. |
| 325 | */ |
| 326 | void bdrv_drain_all_end_quiesce(BlockDriverState *bs); |
| 327 | |
| 328 | #endif /* BLOCK_INT_GLOBAL_STATE_H */ |