]>
Commit | Line | Data |
---|---|---|
2f0c9fe6 PB |
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 | */ | |
175de524 | 25 | |
2f0c9fe6 | 26 | #ifndef BLOCKJOB_H |
175de524 | 27 | #define BLOCKJOB_H |
2f0c9fe6 | 28 | |
737e150e | 29 | #include "block/block.h" |
2f0c9fe6 PB |
30 | |
31 | /** | |
3fc4b10a | 32 | * BlockJobDriver: |
2f0c9fe6 | 33 | * |
3fc4b10a | 34 | * A class type for block job driver. |
2f0c9fe6 | 35 | */ |
3fc4b10a | 36 | typedef struct BlockJobDriver { |
2f0c9fe6 PB |
37 | /** Derived BlockJob struct size */ |
38 | size_t instance_size; | |
39 | ||
40 | /** String describing the operation, part of query-block-jobs QMP API */ | |
79e14bf7 | 41 | BlockJobType job_type; |
2f0c9fe6 PB |
42 | |
43 | /** Optional callback for job types that support setting a speed limit */ | |
44 | void (*set_speed)(BlockJob *job, int64_t speed, Error **errp); | |
aeae883b | 45 | |
3bd293c3 PB |
46 | /** Optional callback for job types that need to forward I/O status reset */ |
47 | void (*iostatus_reset)(BlockJob *job); | |
48 | ||
aeae883b PB |
49 | /** |
50 | * Optional callback for job types whose completion must be triggered | |
51 | * manually. | |
52 | */ | |
53 | void (*complete)(BlockJob *job, Error **errp); | |
57901ecb FZ |
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); | |
fc9c0a9c SH |
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); | |
463e0be1 SH |
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); | |
bae8196d PB |
95 | |
96 | /* | |
97 | * If the callback is not NULL, it will be invoked when the job has to be | |
98 | * synchronously cancelled or completed; it should drain BlockDriverStates | |
99 | * as required to ensure progress. | |
100 | */ | |
101 | void (*drain)(BlockJob *job); | |
3fc4b10a | 102 | } BlockJobDriver; |
2f0c9fe6 PB |
103 | |
104 | /** | |
105 | * BlockJob: | |
106 | * | |
107 | * Long-running operation on a BlockDriverState. | |
108 | */ | |
109 | struct BlockJob { | |
110 | /** The job type, including the job vtable. */ | |
3fc4b10a | 111 | const BlockJobDriver *driver; |
2f0c9fe6 PB |
112 | |
113 | /** The block device on which the job is operating. */ | |
b6d2e599 | 114 | BlockBackend *blk; |
2f0c9fe6 | 115 | |
8ccb9569 | 116 | /** |
559b935f | 117 | * The ID of the block job. May be NULL for internal jobs. |
8ccb9569 KW |
118 | */ |
119 | char *id; | |
120 | ||
2f0c9fe6 PB |
121 | /** |
122 | * The coroutine that executes the job. If not NULL, it is | |
123 | * reentered when busy is false and the job is cancelled. | |
124 | */ | |
125 | Coroutine *co; | |
126 | ||
127 | /** | |
128 | * Set to true if the job should cancel itself. The flag must | |
129 | * always be tested just before toggling the busy flag from false | |
130 | * to true. After a job has been cancelled, it should only yield | |
87f68d31 | 131 | * if #aio_poll will ("sooner or later") reenter the coroutine. |
2f0c9fe6 PB |
132 | */ |
133 | bool cancelled; | |
134 | ||
8acc72a4 | 135 | /** |
751ebd76 FZ |
136 | * Counter for pause request. If non-zero, the block job is either paused, |
137 | * or if busy == true will pause itself as soon as possible. | |
8acc72a4 | 138 | */ |
751ebd76 FZ |
139 | int pause_count; |
140 | ||
141 | /** | |
142 | * Set to true if the job is paused by user. Can be unpaused with the | |
143 | * block-job-resume QMP command. | |
144 | */ | |
145 | bool user_paused; | |
8acc72a4 | 146 | |
2f0c9fe6 | 147 | /** |
fc9c0a9c SH |
148 | * Set to false by the job while the coroutine has yielded and may be |
149 | * re-entered by block_job_enter(). There may still be I/O or event loop | |
150 | * activity pending. | |
2f0c9fe6 PB |
151 | */ |
152 | bool busy; | |
153 | ||
fc9c0a9c SH |
154 | /** |
155 | * Set to true by the job while it is in a quiescent state, where | |
156 | * no I/O or event loop activity is pending. | |
157 | */ | |
158 | bool paused; | |
159 | ||
ef6dbf1e HR |
160 | /** |
161 | * Set to true when the job is ready to be completed. | |
162 | */ | |
163 | bool ready; | |
164 | ||
794f0141 FZ |
165 | /** |
166 | * Set to true when the job has deferred work to the main loop. | |
167 | */ | |
168 | bool deferred_to_main_loop; | |
169 | ||
a7112795 AG |
170 | /** Element of the list of block jobs */ |
171 | QLIST_ENTRY(BlockJob) job_list; | |
172 | ||
32c81a4a PB |
173 | /** Status that is published by the query-block-jobs QMP API */ |
174 | BlockDeviceIoStatus iostatus; | |
175 | ||
2f0c9fe6 PB |
176 | /** Offset that is published by the query-block-jobs QMP API */ |
177 | int64_t offset; | |
178 | ||
179 | /** Length that is published by the query-block-jobs QMP API */ | |
180 | int64_t len; | |
181 | ||
182 | /** Speed that was set with @block_job_set_speed. */ | |
183 | int64_t speed; | |
184 | ||
185 | /** The completion function that will be called when the job completes. */ | |
097310b5 | 186 | BlockCompletionFunc *cb; |
2f0c9fe6 | 187 | |
3718d8ab FZ |
188 | /** Block other operations when block job is running */ |
189 | Error *blocker; | |
190 | ||
23d402d4 AG |
191 | /** BlockDriverStates that are involved in this block job */ |
192 | GSList *nodes; | |
193 | ||
2f0c9fe6 PB |
194 | /** The opaque value that is passed to the completion function. */ |
195 | void *opaque; | |
18930ba3 FZ |
196 | |
197 | /** Reference count of the block job */ | |
198 | int refcnt; | |
a689dbf2 FZ |
199 | |
200 | /* True if this job has reported completion by calling block_job_completed. | |
201 | */ | |
202 | bool completed; | |
203 | ||
204 | /* ret code passed to block_job_completed. | |
205 | */ | |
206 | int ret; | |
207 | ||
c55a832f FZ |
208 | /** Non-NULL if this job is part of a transaction */ |
209 | BlockJobTxn *txn; | |
210 | QLIST_ENTRY(BlockJob) txn_list; | |
2f0c9fe6 PB |
211 | }; |
212 | ||
f81e0b45 JS |
213 | typedef enum BlockJobCreateFlags { |
214 | BLOCK_JOB_DEFAULT = 0x00, | |
215 | BLOCK_JOB_INTERNAL = 0x01, | |
216 | } BlockJobCreateFlags; | |
217 | ||
a7112795 AG |
218 | /** |
219 | * block_job_next: | |
220 | * @job: A block job, or %NULL. | |
221 | * | |
222 | * Get the next element from the list of block jobs after @job, or the | |
223 | * first one if @job is %NULL. | |
224 | * | |
225 | * Returns the requested job, or %NULL if there are no more jobs left. | |
226 | */ | |
227 | BlockJob *block_job_next(BlockJob *job); | |
228 | ||
ffb1f10c AG |
229 | /** |
230 | * block_job_get: | |
231 | * @id: The id of the block job. | |
232 | * | |
233 | * Get the block job identified by @id (which must not be %NULL). | |
234 | * | |
235 | * Returns the requested job, or %NULL if it doesn't exist. | |
236 | */ | |
237 | BlockJob *block_job_get(const char *id); | |
238 | ||
2f0c9fe6 PB |
239 | /** |
240 | * block_job_create: | |
7f0317cf AG |
241 | * @job_id: The id of the newly-created job, or %NULL to have one |
242 | * generated automatically. | |
2f0c9fe6 PB |
243 | * @job_type: The class object for the newly-created job. |
244 | * @bs: The block | |
245 | * @speed: The maximum speed, in bytes per second, or 0 for unlimited. | |
246 | * @cb: Completion function for the job. | |
247 | * @opaque: Opaque pointer value passed to @cb. | |
248 | * @errp: Error object. | |
249 | * | |
250 | * Create a new long-running block device job and return it. The job | |
251 | * will call @cb asynchronously when the job completes. Note that | |
252 | * @bs may have been closed at the time the @cb it is called. If | |
253 | * this is the case, the job may be reported as either cancelled or | |
254 | * completed. | |
255 | * | |
256 | * This function is not part of the public job interface; it should be | |
257 | * called from a wrapper that is specific to the job type. | |
258 | */ | |
7f0317cf | 259 | void *block_job_create(const char *job_id, const BlockJobDriver *driver, |
f81e0b45 | 260 | BlockDriverState *bs, int64_t speed, int flags, |
7f0317cf | 261 | BlockCompletionFunc *cb, void *opaque, Error **errp); |
2f0c9fe6 | 262 | |
23d402d4 AG |
263 | /** |
264 | * block_job_add_bdrv: | |
265 | * @job: A block job | |
266 | * @bs: A BlockDriverState that is involved in @job | |
267 | * | |
268 | * Add @bs to the list of BlockDriverState that are involved in | |
269 | * @job. This means that all operations will be blocked on @bs while | |
270 | * @job exists. | |
271 | */ | |
272 | void block_job_add_bdrv(BlockJob *job, BlockDriverState *bs); | |
273 | ||
2f0c9fe6 PB |
274 | /** |
275 | * block_job_sleep_ns: | |
276 | * @job: The job that calls the function. | |
277 | * @clock: The clock to sleep on. | |
278 | * @ns: How many nanoseconds to stop for. | |
279 | * | |
280 | * Put the job to sleep (assuming that it wasn't canceled) for @ns | |
281 | * nanoseconds. Canceling the job will interrupt the wait immediately. | |
282 | */ | |
7483d1e5 | 283 | void block_job_sleep_ns(BlockJob *job, QEMUClockType type, int64_t ns); |
2f0c9fe6 | 284 | |
dc71ce45 FZ |
285 | /** |
286 | * block_job_yield: | |
287 | * @job: The job that calls the function. | |
288 | * | |
289 | * Yield the block job coroutine. | |
290 | */ | |
291 | void block_job_yield(BlockJob *job); | |
292 | ||
97031164 | 293 | /** |
18930ba3 FZ |
294 | * block_job_ref: |
295 | * @bs: The block device. | |
296 | * | |
297 | * Grab a reference to the block job. Should be paired with block_job_unref. | |
298 | */ | |
299 | void block_job_ref(BlockJob *job); | |
300 | ||
301 | /** | |
302 | * block_job_unref: | |
97031164 TW |
303 | * @bs: The block device. |
304 | * | |
18930ba3 FZ |
305 | * Release reference to the block job and release resources if it is the last |
306 | * reference. | |
97031164 | 307 | */ |
18930ba3 | 308 | void block_job_unref(BlockJob *job); |
97031164 | 309 | |
2f0c9fe6 | 310 | /** |
65f46322 | 311 | * block_job_completed: |
2f0c9fe6 PB |
312 | * @job: The job being completed. |
313 | * @ret: The status code. | |
314 | * | |
315 | * Call the completion function that was registered at creation time, and | |
316 | * free @job. | |
317 | */ | |
65f46322 | 318 | void block_job_completed(BlockJob *job, int ret); |
2f0c9fe6 PB |
319 | |
320 | /** | |
321 | * block_job_set_speed: | |
322 | * @job: The job to set the speed for. | |
323 | * @speed: The new value | |
324 | * @errp: Error object. | |
325 | * | |
326 | * Set a rate-limiting parameter for the job; the actual meaning may | |
327 | * vary depending on the job type. | |
328 | */ | |
329 | void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp); | |
330 | ||
331 | /** | |
332 | * block_job_cancel: | |
333 | * @job: The job to be canceled. | |
334 | * | |
335 | * Asynchronously cancel the specified job. | |
336 | */ | |
337 | void block_job_cancel(BlockJob *job); | |
338 | ||
aeae883b PB |
339 | /** |
340 | * block_job_complete: | |
341 | * @job: The job to be completed. | |
342 | * @errp: Error object. | |
343 | * | |
344 | * Asynchronously complete the specified job. | |
345 | */ | |
346 | void block_job_complete(BlockJob *job, Error **errp); | |
347 | ||
2f0c9fe6 PB |
348 | /** |
349 | * block_job_is_cancelled: | |
350 | * @job: The job being queried. | |
351 | * | |
352 | * Returns whether the job is scheduled for cancellation. | |
353 | */ | |
354 | bool block_job_is_cancelled(BlockJob *job); | |
355 | ||
30e628b7 PB |
356 | /** |
357 | * block_job_query: | |
358 | * @job: The job to get information about. | |
359 | * | |
360 | * Return information about a job. | |
361 | */ | |
559b935f | 362 | BlockJobInfo *block_job_query(BlockJob *job, Error **errp); |
30e628b7 | 363 | |
fc9c0a9c SH |
364 | /** |
365 | * block_job_pause_point: | |
366 | * @job: The job that is ready to pause. | |
367 | * | |
368 | * Pause now if block_job_pause() has been called. Block jobs that perform | |
369 | * lots of I/O must call this between requests so that the job can be paused. | |
370 | */ | |
371 | void coroutine_fn block_job_pause_point(BlockJob *job); | |
372 | ||
8acc72a4 PB |
373 | /** |
374 | * block_job_pause: | |
375 | * @job: The job to be paused. | |
376 | * | |
377 | * Asynchronously pause the specified job. | |
378 | */ | |
379 | void block_job_pause(BlockJob *job); | |
380 | ||
381 | /** | |
382 | * block_job_resume: | |
383 | * @job: The job to be resumed. | |
384 | * | |
751ebd76 | 385 | * Resume the specified job. Must be paired with a preceding block_job_pause. |
8acc72a4 PB |
386 | */ |
387 | void block_job_resume(BlockJob *job); | |
388 | ||
751ebd76 FZ |
389 | /** |
390 | * block_job_enter: | |
391 | * @job: The job to enter. | |
392 | * | |
393 | * Continue the specified job by entering the coroutine. | |
394 | */ | |
395 | void block_job_enter(BlockJob *job); | |
396 | ||
a66a2a36 | 397 | /** |
2f44a08b | 398 | * block_job_event_cancelled: |
a66a2a36 PB |
399 | * @job: The job whose information is requested. |
400 | * | |
bcada37b | 401 | * Send a BLOCK_JOB_CANCELLED event for the specified job. |
a66a2a36 | 402 | */ |
bcada37b WX |
403 | void block_job_event_cancelled(BlockJob *job); |
404 | ||
405 | /** | |
406 | * block_job_ready: | |
407 | * @job: The job which is now ready to complete. | |
408 | * @msg: Error message. Only present on failure. | |
409 | * | |
410 | * Send a BLOCK_JOB_COMPLETED event for the specified job. | |
411 | */ | |
412 | void block_job_event_completed(BlockJob *job, const char *msg); | |
a66a2a36 PB |
413 | |
414 | /** | |
415 | * block_job_ready: | |
416 | * @job: The job which is now ready to complete. | |
417 | * | |
418 | * Send a BLOCK_JOB_READY event for the specified job. | |
419 | */ | |
bcada37b | 420 | void block_job_event_ready(BlockJob *job); |
a66a2a36 | 421 | |
2f0c9fe6 PB |
422 | /** |
423 | * block_job_cancel_sync: | |
424 | * @job: The job to be canceled. | |
425 | * | |
426 | * Synchronously cancel the job. The completion callback is called | |
427 | * before the function returns. The job may actually complete | |
428 | * instead of canceling itself; the circumstances under which this | |
429 | * happens depend on the kind of job that is active. | |
430 | * | |
431 | * Returns the return value from the job if the job actually completed | |
432 | * during the call, or -ECANCELED if it was canceled. | |
433 | */ | |
434 | int block_job_cancel_sync(BlockJob *job); | |
435 | ||
a1a2af07 KW |
436 | /** |
437 | * block_job_cancel_sync_all: | |
438 | * | |
439 | * Synchronously cancels all jobs using block_job_cancel_sync(). | |
440 | */ | |
441 | void block_job_cancel_sync_all(void); | |
442 | ||
345f9e1b HR |
443 | /** |
444 | * block_job_complete_sync: | |
445 | * @job: The job to be completed. | |
446 | * @errp: Error object which may be set by block_job_complete(); this is not | |
447 | * necessarily set on every error, the job return value has to be | |
448 | * checked as well. | |
449 | * | |
450 | * Synchronously complete the job. The completion callback is called before the | |
451 | * function returns, unless it is NULL (which is permissible when using this | |
452 | * function). | |
453 | * | |
454 | * Returns the return value from the job. | |
455 | */ | |
456 | int block_job_complete_sync(BlockJob *job, Error **errp); | |
457 | ||
32c81a4a PB |
458 | /** |
459 | * block_job_iostatus_reset: | |
460 | * @job: The job whose I/O status should be reset. | |
461 | * | |
3bd293c3 | 462 | * Reset I/O status on @job and on BlockDriverState objects it uses, |
e3a4f91b | 463 | * other than job->blk. |
32c81a4a PB |
464 | */ |
465 | void block_job_iostatus_reset(BlockJob *job); | |
466 | ||
467 | /** | |
468 | * block_job_error_action: | |
469 | * @job: The job to signal an error for. | |
32c81a4a PB |
470 | * @on_err: The error action setting. |
471 | * @is_read: Whether the operation was a read. | |
472 | * @error: The error that was reported. | |
473 | * | |
474 | * Report an I/O error for a block job and possibly stop the VM. Return the | |
475 | * action that was selected based on @on_err and @error. | |
476 | */ | |
81e254dc | 477 | BlockErrorAction block_job_error_action(BlockJob *job, BlockdevOnError on_err, |
32c81a4a | 478 | int is_read, int error); |
dec7d421 SH |
479 | |
480 | typedef void BlockJobDeferToMainLoopFn(BlockJob *job, void *opaque); | |
481 | ||
482 | /** | |
483 | * block_job_defer_to_main_loop: | |
484 | * @job: The job | |
485 | * @fn: The function to run in the main loop | |
486 | * @opaque: The opaque value that is passed to @fn | |
487 | * | |
488 | * Execute a given function in the main loop with the BlockDriverState | |
489 | * AioContext acquired. Block jobs must call bdrv_unref(), bdrv_close(), and | |
490 | * anything that uses bdrv_drain_all() in the main loop. | |
491 | * | |
492 | * The @job AioContext is held while @fn executes. | |
493 | */ | |
494 | void block_job_defer_to_main_loop(BlockJob *job, | |
495 | BlockJobDeferToMainLoopFn *fn, | |
496 | void *opaque); | |
497 | ||
c55a832f FZ |
498 | /** |
499 | * block_job_txn_new: | |
500 | * | |
501 | * Allocate and return a new block job transaction. Jobs can be added to the | |
502 | * transaction using block_job_txn_add_job(). | |
503 | * | |
504 | * The transaction is automatically freed when the last job completes or is | |
505 | * cancelled. | |
506 | * | |
507 | * All jobs in the transaction either complete successfully or fail/cancel as a | |
508 | * group. Jobs wait for each other before completing. Cancelling one job | |
509 | * cancels all jobs in the transaction. | |
510 | */ | |
511 | BlockJobTxn *block_job_txn_new(void); | |
512 | ||
513 | /** | |
514 | * block_job_txn_unref: | |
515 | * | |
516 | * Release a reference that was previously acquired with block_job_txn_add_job | |
517 | * or block_job_txn_new. If it's the last reference to the object, it will be | |
518 | * freed. | |
519 | */ | |
520 | void block_job_txn_unref(BlockJobTxn *txn); | |
521 | ||
522 | /** | |
523 | * block_job_txn_add_job: | |
524 | * @txn: The transaction (may be NULL) | |
525 | * @job: Job to add to the transaction | |
526 | * | |
527 | * Add @job to the transaction. The @job must not already be in a transaction. | |
528 | * The caller must call either block_job_txn_unref() or block_job_completed() | |
529 | * to release the reference that is automatically grabbed here. | |
530 | */ | |
531 | void block_job_txn_add_job(BlockJobTxn *txn, BlockJob *job); | |
532 | ||
559b935f JS |
533 | /** |
534 | * block_job_is_internal: | |
535 | * @job: The job to determine if it is user-visible or not. | |
536 | * | |
537 | * Returns true if the job should not be visible to the management layer. | |
538 | */ | |
539 | bool block_job_is_internal(BlockJob *job); | |
540 | ||
2f0c9fe6 | 541 | #endif |