1 /* 2 * Declarations for long-running block device operations 3 * 4 * Copyright (c) 2011 IBM Corp. 5 * Copyright (c) 2012 Red Hat, Inc. 6 * 7 * Permission is hereby granted, free of charge, to any person obtaining a copy 8 * of this software and associated documentation files (the "Software"), to deal 9 * in the Software without restriction, including without limitation the rights 10 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 * copies of the Software, and to permit persons to whom the Software is 12 * furnished to do so, subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included in 15 * all copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 20 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 * THE SOFTWARE. 24 */ 25 26 #ifndef BLOCKJOB_H 27 #define BLOCKJOB_H 28 29 #include "block/block.h" 30 31 typedef struct BlockJobDriver BlockJobDriver; 32 typedef struct BlockJobTxn BlockJobTxn; 33 34 /** 35 * BlockJob: 36 * 37 * Long-running operation on a BlockDriverState. 38 */ 39 typedef struct BlockJob { 40 /** The job type, including the job vtable. */ 41 const BlockJobDriver *driver; 42 43 /** The block device on which the job is operating. */ 44 BlockBackend *blk; 45 46 /** 47 * The ID of the block job. May be NULL for internal jobs. 48 */ 49 char *id; 50 51 /** 52 * The coroutine that executes the job. If not NULL, it is 53 * reentered when busy is false and the job is cancelled. 54 */ 55 Coroutine *co; 56 57 /** 58 * Set to true if the job should cancel itself. The flag must 59 * always be tested just before toggling the busy flag from false 60 * to true. After a job has been cancelled, it should only yield 61 * if #aio_poll will ("sooner or later") reenter the coroutine. 62 */ 63 bool cancelled; 64 65 /** 66 * Set to true if the job should abort immediately without waiting 67 * for data to be in sync. 68 */ 69 bool force; 70 71 /** 72 * Counter for pause request. If non-zero, the block job is either paused, 73 * or if busy == true will pause itself as soon as possible. 74 */ 75 int pause_count; 76 77 /** 78 * Set to true if the job is paused by user. Can be unpaused with the 79 * block-job-resume QMP command. 80 */ 81 bool user_paused; 82 83 /** 84 * Set to false by the job while the coroutine has yielded and may be 85 * re-entered by block_job_enter(). There may still be I/O or event loop 86 * activity pending. Accessed under block_job_mutex (in blockjob.c). 87 */ 88 bool busy; 89 90 /** 91 * Set to true by the job while it is in a quiescent state, where 92 * no I/O or event loop activity is pending. 93 */ 94 bool paused; 95 96 /** 97 * Set to true when the job is ready to be completed. 98 */ 99 bool ready; 100 101 /** 102 * Set to true when the job has deferred work to the main loop. 103 */ 104 bool deferred_to_main_loop; 105 106 /** Element of the list of block jobs */ 107 QLIST_ENTRY(BlockJob) job_list; 108 109 /** Status that is published by the query-block-jobs QMP API */ 110 BlockDeviceIoStatus iostatus; 111 112 /** Offset that is published by the query-block-jobs QMP API */ 113 int64_t offset; 114 115 /** Length that is published by the query-block-jobs QMP API */ 116 int64_t len; 117 118 /** Speed that was set with @block_job_set_speed. */ 119 int64_t speed; 120 121 /** The completion function that will be called when the job completes. */ 122 BlockCompletionFunc *cb; 123 124 /** Block other operations when block job is running */ 125 Error *blocker; 126 127 /** BlockDriverStates that are involved in this block job */ 128 GSList *nodes; 129 130 /** The opaque value that is passed to the completion function. */ 131 void *opaque; 132 133 /** Reference count of the block job */ 134 int refcnt; 135 136 /** True when job has reported completion by calling block_job_completed. */ 137 bool completed; 138 139 /** ret code passed to block_job_completed. */ 140 int ret; 141 142 /** 143 * Timer that is used by @block_job_sleep_ns. Accessed under 144 * block_job_mutex (in blockjob.c). 145 */ 146 QEMUTimer sleep_timer; 147 148 /** Current state; See @BlockJobStatus for details. */ 149 BlockJobStatus status; 150 151 /** True if this job should automatically finalize itself */ 152 bool auto_finalize; 153 154 /** True if this job should automatically dismiss itself */ 155 bool auto_dismiss; 156 157 BlockJobTxn *txn; 158 QLIST_ENTRY(BlockJob) txn_list; 159 } BlockJob; 160 161 typedef enum BlockJobCreateFlags { 162 /* Default behavior */ 163 BLOCK_JOB_DEFAULT = 0x00, 164 /* BlockJob is not QMP-created and should not send QMP events */ 165 BLOCK_JOB_INTERNAL = 0x01, 166 /* BlockJob requires manual finalize step */ 167 BLOCK_JOB_MANUAL_FINALIZE = 0x02, 168 /* BlockJob requires manual dismiss step */ 169 BLOCK_JOB_MANUAL_DISMISS = 0x04, 170 } BlockJobCreateFlags; 171 172 /** 173 * block_job_next: 174 * @job: A block job, or %NULL. 175 * 176 * Get the next element from the list of block jobs after @job, or the 177 * first one if @job is %NULL. 178 * 179 * Returns the requested job, or %NULL if there are no more jobs left. 180 */ 181 BlockJob *block_job_next(BlockJob *job); 182 183 /** 184 * block_job_get: 185 * @id: The id of the block job. 186 * 187 * Get the block job identified by @id (which must not be %NULL). 188 * 189 * Returns the requested job, or %NULL if it doesn't exist. 190 */ 191 BlockJob *block_job_get(const char *id); 192 193 /** 194 * block_job_add_bdrv: 195 * @job: A block job 196 * @name: The name to assign to the new BdrvChild 197 * @bs: A BlockDriverState that is involved in @job 198 * @perm, @shared_perm: Permissions to request on the node 199 * 200 * Add @bs to the list of BlockDriverState that are involved in 201 * @job. This means that all operations will be blocked on @bs while 202 * @job exists. 203 */ 204 int block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs, 205 uint64_t perm, uint64_t shared_perm, Error **errp); 206 207 /** 208 * block_job_remove_all_bdrv: 209 * @job: The block job 210 * 211 * Remove all BlockDriverStates from the list of nodes that are involved in the 212 * job. This removes the blockers added with block_job_add_bdrv(). 213 */ 214 void block_job_remove_all_bdrv(BlockJob *job); 215 216 /** 217 * block_job_set_speed: 218 * @job: The job to set the speed for. 219 * @speed: The new value 220 * @errp: Error object. 221 * 222 * Set a rate-limiting parameter for the job; the actual meaning may 223 * vary depending on the job type. 224 */ 225 void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp); 226 227 /** 228 * block_job_start: 229 * @job: A job that has not yet been started. 230 * 231 * Begins execution of a block job. 232 * Takes ownership of one reference to the job object. 233 */ 234 void block_job_start(BlockJob *job); 235 236 /** 237 * block_job_cancel: 238 * @job: The job to be canceled. 239 * @force: Quit a job without waiting for data to be in sync. 240 * 241 * Asynchronously cancel the specified job. 242 */ 243 void block_job_cancel(BlockJob *job, bool force); 244 245 /** 246 * block_job_complete: 247 * @job: The job to be completed. 248 * @errp: Error object. 249 * 250 * Asynchronously complete the specified job. 251 */ 252 void block_job_complete(BlockJob *job, Error **errp); 253 254 255 /** 256 * block_job_finalize: 257 * @job: The job to fully commit and finish. 258 * @errp: Error object. 259 * 260 * For jobs that have finished their work and are pending 261 * awaiting explicit acknowledgement to commit their work, 262 * This will commit that work. 263 * 264 * FIXME: Make the below statement universally true: 265 * For jobs that support the manual workflow mode, all graph 266 * changes that occur as a result will occur after this command 267 * and before a successful reply. 268 */ 269 void block_job_finalize(BlockJob *job, Error **errp); 270 271 /** 272 * block_job_dismiss: 273 * @job: The job to be dismissed. 274 * @errp: Error object. 275 * 276 * Remove a concluded job from the query list. 277 */ 278 void block_job_dismiss(BlockJob **job, Error **errp); 279 280 /** 281 * block_job_query: 282 * @job: The job to get information about. 283 * 284 * Return information about a job. 285 */ 286 BlockJobInfo *block_job_query(BlockJob *job, Error **errp); 287 288 /** 289 * block_job_user_pause: 290 * @job: The job to be paused. 291 * 292 * Asynchronously pause the specified job. 293 * Do not allow a resume until a matching call to block_job_user_resume. 294 */ 295 void block_job_user_pause(BlockJob *job, Error **errp); 296 297 /** 298 * block_job_paused: 299 * @job: The job to query. 300 * 301 * Returns true if the job is user-paused. 302 */ 303 bool block_job_user_paused(BlockJob *job); 304 305 /** 306 * block_job_user_resume: 307 * @job: The job to be resumed. 308 * 309 * Resume the specified job. 310 * Must be paired with a preceding block_job_user_pause. 311 */ 312 void block_job_user_resume(BlockJob *job, Error **errp); 313 314 /** 315 * block_job_user_cancel: 316 * @job: The job to be cancelled. 317 * @force: Quit a job without waiting for data to be in sync. 318 * 319 * Cancels the specified job, but may refuse to do so if the 320 * operation isn't currently meaningful. 321 */ 322 void block_job_user_cancel(BlockJob *job, bool force, Error **errp); 323 324 /** 325 * block_job_cancel_sync: 326 * @job: The job to be canceled. 327 * 328 * Synchronously cancel the job. The completion callback is called 329 * before the function returns. The job may actually complete 330 * instead of canceling itself; the circumstances under which this 331 * happens depend on the kind of job that is active. 332 * 333 * Returns the return value from the job if the job actually completed 334 * during the call, or -ECANCELED if it was canceled. 335 */ 336 int block_job_cancel_sync(BlockJob *job); 337 338 /** 339 * block_job_cancel_sync_all: 340 * 341 * Synchronously cancels all jobs using block_job_cancel_sync(). 342 */ 343 void block_job_cancel_sync_all(void); 344 345 /** 346 * block_job_complete_sync: 347 * @job: The job to be completed. 348 * @errp: Error object which may be set by block_job_complete(); this is not 349 * necessarily set on every error, the job return value has to be 350 * checked as well. 351 * 352 * Synchronously complete the job. The completion callback is called before the 353 * function returns, unless it is NULL (which is permissible when using this 354 * function). 355 * 356 * Returns the return value from the job. 357 */ 358 int block_job_complete_sync(BlockJob *job, Error **errp); 359 360 /** 361 * block_job_iostatus_reset: 362 * @job: The job whose I/O status should be reset. 363 * 364 * Reset I/O status on @job and on BlockDriverState objects it uses, 365 * other than job->blk. 366 */ 367 void block_job_iostatus_reset(BlockJob *job); 368 369 /** 370 * block_job_txn_new: 371 * 372 * Allocate and return a new block job transaction. Jobs can be added to the 373 * transaction using block_job_txn_add_job(). 374 * 375 * The transaction is automatically freed when the last job completes or is 376 * cancelled. 377 * 378 * All jobs in the transaction either complete successfully or fail/cancel as a 379 * group. Jobs wait for each other before completing. Cancelling one job 380 * cancels all jobs in the transaction. 381 */ 382 BlockJobTxn *block_job_txn_new(void); 383 384 /** 385 * block_job_ref: 386 * 387 * Add a reference to BlockJob refcnt, it will be decreased with 388 * block_job_unref, and then be freed if it comes to be the last 389 * reference. 390 */ 391 void block_job_ref(BlockJob *job); 392 393 /** 394 * block_job_unref: 395 * 396 * Release a reference that was previously acquired with block_job_ref 397 * or block_job_create. If it's the last reference to the object, it will be 398 * freed. 399 */ 400 void block_job_unref(BlockJob *job); 401 402 /** 403 * block_job_txn_unref: 404 * 405 * Release a reference that was previously acquired with block_job_txn_add_job 406 * or block_job_txn_new. If it's the last reference to the object, it will be 407 * freed. 408 */ 409 void block_job_txn_unref(BlockJobTxn *txn); 410 411 /** 412 * block_job_txn_add_job: 413 * @txn: The transaction (may be NULL) 414 * @job: Job to add to the transaction 415 * 416 * Add @job to the transaction. The @job must not already be in a transaction. 417 * The caller must call either block_job_txn_unref() or block_job_completed() 418 * to release the reference that is automatically grabbed here. 419 */ 420 void block_job_txn_add_job(BlockJobTxn *txn, BlockJob *job); 421 422 /** 423 * block_job_is_internal: 424 * @job: The job to determine if it is user-visible or not. 425 * 426 * Returns true if the job should not be visible to the management layer. 427 */ 428 bool block_job_is_internal(BlockJob *job); 429 430 #endif 431