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 * Counter for pause request. If non-zero, the block job is either paused, 67 * or if busy == true will pause itself as soon as possible. 68 */ 69 int pause_count; 70 71 /** 72 * Set to true if the job is paused by user. Can be unpaused with the 73 * block-job-resume QMP command. 74 */ 75 bool user_paused; 76 77 /** 78 * Set to false by the job while the coroutine has yielded and may be 79 * re-entered by block_job_enter(). There may still be I/O or event loop 80 * activity pending. Accessed under block_job_mutex (in blockjob.c). 81 */ 82 bool busy; 83 84 /** 85 * Set to true by the job while it is in a quiescent state, where 86 * no I/O or event loop activity is pending. 87 */ 88 bool paused; 89 90 /** 91 * Set to true when the job is ready to be completed. 92 */ 93 bool ready; 94 95 /** 96 * Set to true when the job has deferred work to the main loop. 97 */ 98 bool deferred_to_main_loop; 99 100 /** Element of the list of block jobs */ 101 QLIST_ENTRY(BlockJob) job_list; 102 103 /** Status that is published by the query-block-jobs QMP API */ 104 BlockDeviceIoStatus iostatus; 105 106 /** Offset that is published by the query-block-jobs QMP API */ 107 int64_t offset; 108 109 /** Length that is published by the query-block-jobs QMP API */ 110 int64_t len; 111 112 /** Speed that was set with @block_job_set_speed. */ 113 int64_t speed; 114 115 /** The completion function that will be called when the job completes. */ 116 BlockCompletionFunc *cb; 117 118 /** Block other operations when block job is running */ 119 Error *blocker; 120 121 /** BlockDriverStates that are involved in this block job */ 122 GSList *nodes; 123 124 /** The opaque value that is passed to the completion function. */ 125 void *opaque; 126 127 /** Reference count of the block job */ 128 int refcnt; 129 130 /* True if this job has reported completion by calling block_job_completed. 131 */ 132 bool completed; 133 134 /* ret code passed to block_job_completed. 135 */ 136 int ret; 137 138 /** 139 * Timer that is used by @block_job_sleep_ns. Accessed under 140 * block_job_mutex (in blockjob.c). 141 */ 142 QEMUTimer sleep_timer; 143 144 /** Non-NULL if this job is part of a transaction */ 145 BlockJobTxn *txn; 146 QLIST_ENTRY(BlockJob) txn_list; 147 } BlockJob; 148 149 typedef enum BlockJobCreateFlags { 150 BLOCK_JOB_DEFAULT = 0x00, 151 BLOCK_JOB_INTERNAL = 0x01, 152 } BlockJobCreateFlags; 153 154 /** 155 * block_job_next: 156 * @job: A block job, or %NULL. 157 * 158 * Get the next element from the list of block jobs after @job, or the 159 * first one if @job is %NULL. 160 * 161 * Returns the requested job, or %NULL if there are no more jobs left. 162 */ 163 BlockJob *block_job_next(BlockJob *job); 164 165 /** 166 * block_job_get: 167 * @id: The id of the block job. 168 * 169 * Get the block job identified by @id (which must not be %NULL). 170 * 171 * Returns the requested job, or %NULL if it doesn't exist. 172 */ 173 BlockJob *block_job_get(const char *id); 174 175 /** 176 * block_job_add_bdrv: 177 * @job: A block job 178 * @name: The name to assign to the new BdrvChild 179 * @bs: A BlockDriverState that is involved in @job 180 * @perm, @shared_perm: Permissions to request on the node 181 * 182 * Add @bs to the list of BlockDriverState that are involved in 183 * @job. This means that all operations will be blocked on @bs while 184 * @job exists. 185 */ 186 int block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs, 187 uint64_t perm, uint64_t shared_perm, Error **errp); 188 189 /** 190 * block_job_remove_all_bdrv: 191 * @job: The block job 192 * 193 * Remove all BlockDriverStates from the list of nodes that are involved in the 194 * job. This removes the blockers added with block_job_add_bdrv(). 195 */ 196 void block_job_remove_all_bdrv(BlockJob *job); 197 198 /** 199 * block_job_set_speed: 200 * @job: The job to set the speed for. 201 * @speed: The new value 202 * @errp: Error object. 203 * 204 * Set a rate-limiting parameter for the job; the actual meaning may 205 * vary depending on the job type. 206 */ 207 void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp); 208 209 /** 210 * block_job_start: 211 * @job: A job that has not yet been started. 212 * 213 * Begins execution of a block job. 214 * Takes ownership of one reference to the job object. 215 */ 216 void block_job_start(BlockJob *job); 217 218 /** 219 * block_job_cancel: 220 * @job: The job to be canceled. 221 * 222 * Asynchronously cancel the specified job. 223 */ 224 void block_job_cancel(BlockJob *job); 225 226 /** 227 * block_job_complete: 228 * @job: The job to be completed. 229 * @errp: Error object. 230 * 231 * Asynchronously complete the specified job. 232 */ 233 void block_job_complete(BlockJob *job, Error **errp); 234 235 /** 236 * block_job_query: 237 * @job: The job to get information about. 238 * 239 * Return information about a job. 240 */ 241 BlockJobInfo *block_job_query(BlockJob *job, Error **errp); 242 243 /** 244 * block_job_user_pause: 245 * @job: The job to be paused. 246 * 247 * Asynchronously pause the specified job. 248 * Do not allow a resume until a matching call to block_job_user_resume. 249 */ 250 void block_job_user_pause(BlockJob *job); 251 252 /** 253 * block_job_paused: 254 * @job: The job to query. 255 * 256 * Returns true if the job is user-paused. 257 */ 258 bool block_job_user_paused(BlockJob *job); 259 260 /** 261 * block_job_user_resume: 262 * @job: The job to be resumed. 263 * 264 * Resume the specified job. 265 * Must be paired with a preceding block_job_user_pause. 266 */ 267 void block_job_user_resume(BlockJob *job); 268 269 /** 270 * block_job_cancel_sync: 271 * @job: The job to be canceled. 272 * 273 * Synchronously cancel the job. The completion callback is called 274 * before the function returns. The job may actually complete 275 * instead of canceling itself; the circumstances under which this 276 * happens depend on the kind of job that is active. 277 * 278 * Returns the return value from the job if the job actually completed 279 * during the call, or -ECANCELED if it was canceled. 280 */ 281 int block_job_cancel_sync(BlockJob *job); 282 283 /** 284 * block_job_cancel_sync_all: 285 * 286 * Synchronously cancels all jobs using block_job_cancel_sync(). 287 */ 288 void block_job_cancel_sync_all(void); 289 290 /** 291 * block_job_complete_sync: 292 * @job: The job to be completed. 293 * @errp: Error object which may be set by block_job_complete(); this is not 294 * necessarily set on every error, the job return value has to be 295 * checked as well. 296 * 297 * Synchronously complete the job. The completion callback is called before the 298 * function returns, unless it is NULL (which is permissible when using this 299 * function). 300 * 301 * Returns the return value from the job. 302 */ 303 int block_job_complete_sync(BlockJob *job, Error **errp); 304 305 /** 306 * block_job_iostatus_reset: 307 * @job: The job whose I/O status should be reset. 308 * 309 * Reset I/O status on @job and on BlockDriverState objects it uses, 310 * other than job->blk. 311 */ 312 void block_job_iostatus_reset(BlockJob *job); 313 314 /** 315 * block_job_txn_new: 316 * 317 * Allocate and return a new block job transaction. Jobs can be added to the 318 * transaction using block_job_txn_add_job(). 319 * 320 * The transaction is automatically freed when the last job completes or is 321 * cancelled. 322 * 323 * All jobs in the transaction either complete successfully or fail/cancel as a 324 * group. Jobs wait for each other before completing. Cancelling one job 325 * cancels all jobs in the transaction. 326 */ 327 BlockJobTxn *block_job_txn_new(void); 328 329 /** 330 * block_job_ref: 331 * 332 * Add a reference to BlockJob refcnt, it will be decreased with 333 * block_job_unref, and then be freed if it comes to be the last 334 * reference. 335 */ 336 void block_job_ref(BlockJob *job); 337 338 /** 339 * block_job_unref: 340 * 341 * Release a reference that was previously acquired with block_job_ref 342 * or block_job_create. If it's the last reference to the object, it will be 343 * freed. 344 */ 345 void block_job_unref(BlockJob *job); 346 347 /** 348 * block_job_txn_unref: 349 * 350 * Release a reference that was previously acquired with block_job_txn_add_job 351 * or block_job_txn_new. If it's the last reference to the object, it will be 352 * freed. 353 */ 354 void block_job_txn_unref(BlockJobTxn *txn); 355 356 /** 357 * block_job_txn_add_job: 358 * @txn: The transaction (may be NULL) 359 * @job: Job to add to the transaction 360 * 361 * Add @job to the transaction. The @job must not already be in a transaction. 362 * The caller must call either block_job_txn_unref() or block_job_completed() 363 * to release the reference that is automatically grabbed here. 364 */ 365 void block_job_txn_add_job(BlockJobTxn *txn, BlockJob *job); 366 367 /** 368 * block_job_is_internal: 369 * @job: The job to determine if it is user-visible or not. 370 * 371 * Returns true if the job should not be visible to the management layer. 372 */ 373 bool block_job_is_internal(BlockJob *job); 374 375 #endif 376