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 /** 32 * BlockJobDriver: 33 * 34 * A class type for block job driver. 35 */ 36 typedef struct BlockJobDriver { 37 /** Derived BlockJob struct size */ 38 size_t instance_size; 39 40 /** String describing the operation, part of query-block-jobs QMP API */ 41 BlockJobType job_type; 42 43 /** Optional callback for job types that support setting a speed limit */ 44 void (*set_speed)(BlockJob *job, int64_t speed, Error **errp); 45 46 /** Optional callback for job types that need to forward I/O status reset */ 47 void (*iostatus_reset)(BlockJob *job); 48 49 /** 50 * Optional callback for job types whose completion must be triggered 51 * manually. 52 */ 53 void (*complete)(BlockJob *job, Error **errp); 54 55 /** 56 * If the callback is not NULL, it will be invoked when all the jobs 57 * belonging to the same transaction complete; or upon this job's 58 * completion if it is not in a transaction. Skipped if NULL. 59 * 60 * All jobs will complete with a call to either .commit() or .abort() but 61 * never both. 62 */ 63 void (*commit)(BlockJob *job); 64 65 /** 66 * If the callback is not NULL, it will be invoked when any job in the 67 * same transaction fails; or upon this job's failure (due to error or 68 * cancellation) if it is not in a transaction. Skipped if NULL. 69 * 70 * All jobs will complete with a call to either .commit() or .abort() but 71 * never both. 72 */ 73 void (*abort)(BlockJob *job); 74 75 /** 76 * If the callback is not NULL, it will be invoked when the job transitions 77 * into the paused state. Paused jobs must not perform any asynchronous 78 * I/O or event loop activity. This callback is used to quiesce jobs. 79 */ 80 void coroutine_fn (*pause)(BlockJob *job); 81 82 /** 83 * If the callback is not NULL, it will be invoked when the job transitions 84 * out of the paused state. Any asynchronous I/O or event loop activity 85 * should be restarted from this callback. 86 */ 87 void coroutine_fn (*resume)(BlockJob *job); 88 89 /* 90 * If the callback is not NULL, it will be invoked before the job is 91 * resumed in a new AioContext. This is the place to move any resources 92 * besides job->blk to the new AioContext. 93 */ 94 void (*attached_aio_context)(BlockJob *job, AioContext *new_context); 95 } BlockJobDriver; 96 97 /** 98 * BlockJob: 99 * 100 * Long-running operation on a BlockDriverState. 101 */ 102 struct BlockJob { 103 /** The job type, including the job vtable. */ 104 const BlockJobDriver *driver; 105 106 /** The block device on which the job is operating. */ 107 BlockBackend *blk; 108 109 /** 110 * The ID of the block job. Currently the BlockBackend name of the BDS 111 * owning the job at the time when the job is started. 112 * 113 * TODO Decouple block job IDs from BlockBackend names 114 */ 115 char *id; 116 117 /** 118 * The coroutine that executes the job. If not NULL, it is 119 * reentered when busy is false and the job is cancelled. 120 */ 121 Coroutine *co; 122 123 /** 124 * Set to true if the job should cancel itself. The flag must 125 * always be tested just before toggling the busy flag from false 126 * to true. After a job has been cancelled, it should only yield 127 * if #aio_poll will ("sooner or later") reenter the coroutine. 128 */ 129 bool cancelled; 130 131 /** 132 * Counter for pause request. If non-zero, the block job is either paused, 133 * or if busy == true will pause itself as soon as possible. 134 */ 135 int pause_count; 136 137 /** 138 * Set to true if the job is paused by user. Can be unpaused with the 139 * block-job-resume QMP command. 140 */ 141 bool user_paused; 142 143 /** 144 * Set to false by the job while the coroutine has yielded and may be 145 * re-entered by block_job_enter(). There may still be I/O or event loop 146 * activity pending. 147 */ 148 bool busy; 149 150 /** 151 * Set to true by the job while it is in a quiescent state, where 152 * no I/O or event loop activity is pending. 153 */ 154 bool paused; 155 156 /** 157 * Set to true when the job is ready to be completed. 158 */ 159 bool ready; 160 161 /** 162 * Set to true when the job has deferred work to the main loop. 163 */ 164 bool deferred_to_main_loop; 165 166 /** Element of the list of block jobs */ 167 QLIST_ENTRY(BlockJob) job_list; 168 169 /** Status that is published by the query-block-jobs QMP API */ 170 BlockDeviceIoStatus iostatus; 171 172 /** Offset that is published by the query-block-jobs QMP API */ 173 int64_t offset; 174 175 /** Length that is published by the query-block-jobs QMP API */ 176 int64_t len; 177 178 /** Speed that was set with @block_job_set_speed. */ 179 int64_t speed; 180 181 /** The completion function that will be called when the job completes. */ 182 BlockCompletionFunc *cb; 183 184 /** Block other operations when block job is running */ 185 Error *blocker; 186 187 /** The opaque value that is passed to the completion function. */ 188 void *opaque; 189 190 /** Reference count of the block job */ 191 int refcnt; 192 193 /* True if this job has reported completion by calling block_job_completed. 194 */ 195 bool completed; 196 197 /* ret code passed to block_job_completed. 198 */ 199 int ret; 200 201 /** Non-NULL if this job is part of a transaction */ 202 BlockJobTxn *txn; 203 QLIST_ENTRY(BlockJob) txn_list; 204 }; 205 206 /** 207 * block_job_next: 208 * @job: A block job, or %NULL. 209 * 210 * Get the next element from the list of block jobs after @job, or the 211 * first one if @job is %NULL. 212 * 213 * Returns the requested job, or %NULL if there are no more jobs left. 214 */ 215 BlockJob *block_job_next(BlockJob *job); 216 217 /** 218 * block_job_create: 219 * @job_type: The class object for the newly-created job. 220 * @bs: The block 221 * @speed: The maximum speed, in bytes per second, or 0 for unlimited. 222 * @cb: Completion function for the job. 223 * @opaque: Opaque pointer value passed to @cb. 224 * @errp: Error object. 225 * 226 * Create a new long-running block device job and return it. The job 227 * will call @cb asynchronously when the job completes. Note that 228 * @bs may have been closed at the time the @cb it is called. If 229 * this is the case, the job may be reported as either cancelled or 230 * completed. 231 * 232 * This function is not part of the public job interface; it should be 233 * called from a wrapper that is specific to the job type. 234 */ 235 void *block_job_create(const BlockJobDriver *driver, BlockDriverState *bs, 236 int64_t speed, BlockCompletionFunc *cb, 237 void *opaque, Error **errp); 238 239 /** 240 * block_job_sleep_ns: 241 * @job: The job that calls the function. 242 * @clock: The clock to sleep on. 243 * @ns: How many nanoseconds to stop for. 244 * 245 * Put the job to sleep (assuming that it wasn't canceled) for @ns 246 * nanoseconds. Canceling the job will interrupt the wait immediately. 247 */ 248 void block_job_sleep_ns(BlockJob *job, QEMUClockType type, int64_t ns); 249 250 /** 251 * block_job_yield: 252 * @job: The job that calls the function. 253 * 254 * Yield the block job coroutine. 255 */ 256 void block_job_yield(BlockJob *job); 257 258 /** 259 * block_job_ref: 260 * @bs: The block device. 261 * 262 * Grab a reference to the block job. Should be paired with block_job_unref. 263 */ 264 void block_job_ref(BlockJob *job); 265 266 /** 267 * block_job_unref: 268 * @bs: The block device. 269 * 270 * Release reference to the block job and release resources if it is the last 271 * reference. 272 */ 273 void block_job_unref(BlockJob *job); 274 275 /** 276 * block_job_completed: 277 * @job: The job being completed. 278 * @ret: The status code. 279 * 280 * Call the completion function that was registered at creation time, and 281 * free @job. 282 */ 283 void block_job_completed(BlockJob *job, int ret); 284 285 /** 286 * block_job_set_speed: 287 * @job: The job to set the speed for. 288 * @speed: The new value 289 * @errp: Error object. 290 * 291 * Set a rate-limiting parameter for the job; the actual meaning may 292 * vary depending on the job type. 293 */ 294 void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp); 295 296 /** 297 * block_job_cancel: 298 * @job: The job to be canceled. 299 * 300 * Asynchronously cancel the specified job. 301 */ 302 void block_job_cancel(BlockJob *job); 303 304 /** 305 * block_job_complete: 306 * @job: The job to be completed. 307 * @errp: Error object. 308 * 309 * Asynchronously complete the specified job. 310 */ 311 void block_job_complete(BlockJob *job, Error **errp); 312 313 /** 314 * block_job_is_cancelled: 315 * @job: The job being queried. 316 * 317 * Returns whether the job is scheduled for cancellation. 318 */ 319 bool block_job_is_cancelled(BlockJob *job); 320 321 /** 322 * block_job_query: 323 * @job: The job to get information about. 324 * 325 * Return information about a job. 326 */ 327 BlockJobInfo *block_job_query(BlockJob *job); 328 329 /** 330 * block_job_pause_point: 331 * @job: The job that is ready to pause. 332 * 333 * Pause now if block_job_pause() has been called. Block jobs that perform 334 * lots of I/O must call this between requests so that the job can be paused. 335 */ 336 void coroutine_fn block_job_pause_point(BlockJob *job); 337 338 /** 339 * block_job_pause: 340 * @job: The job to be paused. 341 * 342 * Asynchronously pause the specified job. 343 */ 344 void block_job_pause(BlockJob *job); 345 346 /** 347 * block_job_resume: 348 * @job: The job to be resumed. 349 * 350 * Resume the specified job. Must be paired with a preceding block_job_pause. 351 */ 352 void block_job_resume(BlockJob *job); 353 354 /** 355 * block_job_enter: 356 * @job: The job to enter. 357 * 358 * Continue the specified job by entering the coroutine. 359 */ 360 void block_job_enter(BlockJob *job); 361 362 /** 363 * block_job_event_cancelled: 364 * @job: The job whose information is requested. 365 * 366 * Send a BLOCK_JOB_CANCELLED event for the specified job. 367 */ 368 void block_job_event_cancelled(BlockJob *job); 369 370 /** 371 * block_job_ready: 372 * @job: The job which is now ready to complete. 373 * @msg: Error message. Only present on failure. 374 * 375 * Send a BLOCK_JOB_COMPLETED event for the specified job. 376 */ 377 void block_job_event_completed(BlockJob *job, const char *msg); 378 379 /** 380 * block_job_ready: 381 * @job: The job which is now ready to complete. 382 * 383 * Send a BLOCK_JOB_READY event for the specified job. 384 */ 385 void block_job_event_ready(BlockJob *job); 386 387 /** 388 * block_job_cancel_sync: 389 * @job: The job to be canceled. 390 * 391 * Synchronously cancel the job. The completion callback is called 392 * before the function returns. The job may actually complete 393 * instead of canceling itself; the circumstances under which this 394 * happens depend on the kind of job that is active. 395 * 396 * Returns the return value from the job if the job actually completed 397 * during the call, or -ECANCELED if it was canceled. 398 */ 399 int block_job_cancel_sync(BlockJob *job); 400 401 /** 402 * block_job_cancel_sync_all: 403 * 404 * Synchronously cancels all jobs using block_job_cancel_sync(). 405 */ 406 void block_job_cancel_sync_all(void); 407 408 /** 409 * block_job_complete_sync: 410 * @job: The job to be completed. 411 * @errp: Error object which may be set by block_job_complete(); this is not 412 * necessarily set on every error, the job return value has to be 413 * checked as well. 414 * 415 * Synchronously complete the job. The completion callback is called before the 416 * function returns, unless it is NULL (which is permissible when using this 417 * function). 418 * 419 * Returns the return value from the job. 420 */ 421 int block_job_complete_sync(BlockJob *job, Error **errp); 422 423 /** 424 * block_job_iostatus_reset: 425 * @job: The job whose I/O status should be reset. 426 * 427 * Reset I/O status on @job and on BlockDriverState objects it uses, 428 * other than job->blk. 429 */ 430 void block_job_iostatus_reset(BlockJob *job); 431 432 /** 433 * block_job_error_action: 434 * @job: The job to signal an error for. 435 * @on_err: The error action setting. 436 * @is_read: Whether the operation was a read. 437 * @error: The error that was reported. 438 * 439 * Report an I/O error for a block job and possibly stop the VM. Return the 440 * action that was selected based on @on_err and @error. 441 */ 442 BlockErrorAction block_job_error_action(BlockJob *job, BlockdevOnError on_err, 443 int is_read, int error); 444 445 typedef void BlockJobDeferToMainLoopFn(BlockJob *job, void *opaque); 446 447 /** 448 * block_job_defer_to_main_loop: 449 * @job: The job 450 * @fn: The function to run in the main loop 451 * @opaque: The opaque value that is passed to @fn 452 * 453 * Execute a given function in the main loop with the BlockDriverState 454 * AioContext acquired. Block jobs must call bdrv_unref(), bdrv_close(), and 455 * anything that uses bdrv_drain_all() in the main loop. 456 * 457 * The @job AioContext is held while @fn executes. 458 */ 459 void block_job_defer_to_main_loop(BlockJob *job, 460 BlockJobDeferToMainLoopFn *fn, 461 void *opaque); 462 463 /** 464 * block_job_txn_new: 465 * 466 * Allocate and return a new block job transaction. Jobs can be added to the 467 * transaction using block_job_txn_add_job(). 468 * 469 * The transaction is automatically freed when the last job completes or is 470 * cancelled. 471 * 472 * All jobs in the transaction either complete successfully or fail/cancel as a 473 * group. Jobs wait for each other before completing. Cancelling one job 474 * cancels all jobs in the transaction. 475 */ 476 BlockJobTxn *block_job_txn_new(void); 477 478 /** 479 * block_job_txn_unref: 480 * 481 * Release a reference that was previously acquired with block_job_txn_add_job 482 * or block_job_txn_new. If it's the last reference to the object, it will be 483 * freed. 484 */ 485 void block_job_txn_unref(BlockJobTxn *txn); 486 487 /** 488 * block_job_txn_add_job: 489 * @txn: The transaction (may be NULL) 490 * @job: Job to add to the transaction 491 * 492 * Add @job to the transaction. The @job must not already be in a transaction. 493 * The caller must call either block_job_txn_unref() or block_job_completed() 494 * to release the reference that is automatically grabbed here. 495 */ 496 void block_job_txn_add_job(BlockJobTxn *txn, BlockJob *job); 497 498 #endif 499