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. 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 /** Non-NULL if this job is part of a transaction */ 139 BlockJobTxn *txn; 140 QLIST_ENTRY(BlockJob) txn_list; 141 } BlockJob; 142 143 typedef enum BlockJobCreateFlags { 144 BLOCK_JOB_DEFAULT = 0x00, 145 BLOCK_JOB_INTERNAL = 0x01, 146 } BlockJobCreateFlags; 147 148 /** 149 * block_job_next: 150 * @job: A block job, or %NULL. 151 * 152 * Get the next element from the list of block jobs after @job, or the 153 * first one if @job is %NULL. 154 * 155 * Returns the requested job, or %NULL if there are no more jobs left. 156 */ 157 BlockJob *block_job_next(BlockJob *job); 158 159 /** 160 * block_job_get: 161 * @id: The id of the block job. 162 * 163 * Get the block job identified by @id (which must not be %NULL). 164 * 165 * Returns the requested job, or %NULL if it doesn't exist. 166 */ 167 BlockJob *block_job_get(const char *id); 168 169 /** 170 * block_job_add_bdrv: 171 * @job: A block job 172 * @name: The name to assign to the new BdrvChild 173 * @bs: A BlockDriverState that is involved in @job 174 * @perm, @shared_perm: Permissions to request on the node 175 * 176 * Add @bs to the list of BlockDriverState that are involved in 177 * @job. This means that all operations will be blocked on @bs while 178 * @job exists. 179 */ 180 int block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs, 181 uint64_t perm, uint64_t shared_perm, Error **errp); 182 183 /** 184 * block_job_remove_all_bdrv: 185 * @job: The block job 186 * 187 * Remove all BlockDriverStates from the list of nodes that are involved in the 188 * job. This removes the blockers added with block_job_add_bdrv(). 189 */ 190 void block_job_remove_all_bdrv(BlockJob *job); 191 192 /** 193 * block_job_set_speed: 194 * @job: The job to set the speed for. 195 * @speed: The new value 196 * @errp: Error object. 197 * 198 * Set a rate-limiting parameter for the job; the actual meaning may 199 * vary depending on the job type. 200 */ 201 void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp); 202 203 /** 204 * block_job_start: 205 * @job: A job that has not yet been started. 206 * 207 * Begins execution of a block job. 208 * Takes ownership of one reference to the job object. 209 */ 210 void block_job_start(BlockJob *job); 211 212 /** 213 * block_job_cancel: 214 * @job: The job to be canceled. 215 * 216 * Asynchronously cancel the specified job. 217 */ 218 void block_job_cancel(BlockJob *job); 219 220 /** 221 * block_job_complete: 222 * @job: The job to be completed. 223 * @errp: Error object. 224 * 225 * Asynchronously complete the specified job. 226 */ 227 void block_job_complete(BlockJob *job, Error **errp); 228 229 /** 230 * block_job_query: 231 * @job: The job to get information about. 232 * 233 * Return information about a job. 234 */ 235 BlockJobInfo *block_job_query(BlockJob *job, Error **errp); 236 237 /** 238 * block_job_user_pause: 239 * @job: The job to be paused. 240 * 241 * Asynchronously pause the specified job. 242 * Do not allow a resume until a matching call to block_job_user_resume. 243 */ 244 void block_job_user_pause(BlockJob *job); 245 246 /** 247 * block_job_paused: 248 * @job: The job to query. 249 * 250 * Returns true if the job is user-paused. 251 */ 252 bool block_job_user_paused(BlockJob *job); 253 254 /** 255 * block_job_user_resume: 256 * @job: The job to be resumed. 257 * 258 * Resume the specified job. 259 * Must be paired with a preceding block_job_user_pause. 260 */ 261 void block_job_user_resume(BlockJob *job); 262 263 /** 264 * block_job_cancel_sync: 265 * @job: The job to be canceled. 266 * 267 * Synchronously cancel the job. The completion callback is called 268 * before the function returns. The job may actually complete 269 * instead of canceling itself; the circumstances under which this 270 * happens depend on the kind of job that is active. 271 * 272 * Returns the return value from the job if the job actually completed 273 * during the call, or -ECANCELED if it was canceled. 274 */ 275 int block_job_cancel_sync(BlockJob *job); 276 277 /** 278 * block_job_cancel_sync_all: 279 * 280 * Synchronously cancels all jobs using block_job_cancel_sync(). 281 */ 282 void block_job_cancel_sync_all(void); 283 284 /** 285 * block_job_complete_sync: 286 * @job: The job to be completed. 287 * @errp: Error object which may be set by block_job_complete(); this is not 288 * necessarily set on every error, the job return value has to be 289 * checked as well. 290 * 291 * Synchronously complete the job. The completion callback is called before the 292 * function returns, unless it is NULL (which is permissible when using this 293 * function). 294 * 295 * Returns the return value from the job. 296 */ 297 int block_job_complete_sync(BlockJob *job, Error **errp); 298 299 /** 300 * block_job_iostatus_reset: 301 * @job: The job whose I/O status should be reset. 302 * 303 * Reset I/O status on @job and on BlockDriverState objects it uses, 304 * other than job->blk. 305 */ 306 void block_job_iostatus_reset(BlockJob *job); 307 308 /** 309 * block_job_txn_new: 310 * 311 * Allocate and return a new block job transaction. Jobs can be added to the 312 * transaction using block_job_txn_add_job(). 313 * 314 * The transaction is automatically freed when the last job completes or is 315 * cancelled. 316 * 317 * All jobs in the transaction either complete successfully or fail/cancel as a 318 * group. Jobs wait for each other before completing. Cancelling one job 319 * cancels all jobs in the transaction. 320 */ 321 BlockJobTxn *block_job_txn_new(void); 322 323 /** 324 * block_job_ref: 325 * 326 * Add a reference to BlockJob refcnt, it will be decreased with 327 * block_job_unref, and then be freed if it comes to be the last 328 * reference. 329 */ 330 void block_job_ref(BlockJob *job); 331 332 /** 333 * block_job_unref: 334 * 335 * Release a reference that was previously acquired with block_job_ref 336 * or block_job_create. If it's the last reference to the object, it will be 337 * freed. 338 */ 339 void block_job_unref(BlockJob *job); 340 341 /** 342 * block_job_txn_unref: 343 * 344 * Release a reference that was previously acquired with block_job_txn_add_job 345 * or block_job_txn_new. If it's the last reference to the object, it will be 346 * freed. 347 */ 348 void block_job_txn_unref(BlockJobTxn *txn); 349 350 /** 351 * block_job_txn_add_job: 352 * @txn: The transaction (may be NULL) 353 * @job: Job to add to the transaction 354 * 355 * Add @job to the transaction. The @job must not already be in a transaction. 356 * The caller must call either block_job_txn_unref() or block_job_completed() 357 * to release the reference that is automatically grabbed here. 358 */ 359 void block_job_txn_add_job(BlockJobTxn *txn, BlockJob *job); 360 361 /** 362 * block_job_is_internal: 363 * @job: The job to determine if it is user-visible or not. 364 * 365 * Returns true if the job should not be visible to the management layer. 366 */ 367 bool block_job_is_internal(BlockJob *job); 368 369 #endif 370