2 * Declarations for long-running block device operations
4 * Copyright (c) 2011 IBM Corp.
5 * Copyright (c) 2012 Red Hat, Inc.
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:
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
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
29 #include "block/block.h"
30 #include "qemu/ratelimit.h"
32 #define BLOCK_JOB_SLICE_TIME 100000000ULL /* ns */
34 typedef struct BlockJobDriver BlockJobDriver
;
35 typedef struct BlockJobTxn BlockJobTxn
;
40 * Long-running operation on a BlockDriverState.
42 typedef struct BlockJob
{
43 /** The job type, including the job vtable. */
44 const BlockJobDriver
*driver
;
46 /** The block device on which the job is operating. */
50 * The ID of the block job. May be NULL for internal jobs.
55 * The coroutine that executes the job. If not NULL, it is
56 * reentered when busy is false and the job is cancelled.
61 * Set to true if the job should cancel itself. The flag must
62 * always be tested just before toggling the busy flag from false
63 * to true. After a job has been cancelled, it should only yield
64 * if #aio_poll will ("sooner or later") reenter the coroutine.
69 * Set to true if the job should abort immediately without waiting
70 * for data to be in sync.
75 * Counter for pause request. If non-zero, the block job is either paused,
76 * or if busy == true will pause itself as soon as possible.
81 * Set to true if the job is paused by user. Can be unpaused with the
82 * block-job-resume QMP command.
87 * Set to false by the job while the coroutine has yielded and may be
88 * re-entered by block_job_enter(). There may still be I/O or event loop
89 * activity pending. Accessed under block_job_mutex (in blockjob.c).
94 * Set to true by the job while it is in a quiescent state, where
95 * no I/O or event loop activity is pending.
100 * Set to true when the job is ready to be completed.
105 * Set to true when the job has deferred work to the main loop.
107 bool deferred_to_main_loop
;
109 /** Element of the list of block jobs */
110 QLIST_ENTRY(BlockJob
) job_list
;
112 /** Status that is published by the query-block-jobs QMP API */
113 BlockDeviceIoStatus iostatus
;
115 /** Offset that is published by the query-block-jobs QMP API */
118 /** Length that is published by the query-block-jobs QMP API */
121 /** Speed that was set with @block_job_set_speed. */
124 /** Rate limiting data structure for implementing @speed. */
127 /** The completion function that will be called when the job completes. */
128 BlockCompletionFunc
*cb
;
130 /** Block other operations when block job is running */
133 /** BlockDriverStates that are involved in this block job */
136 /** The opaque value that is passed to the completion function. */
139 /** Reference count of the block job */
142 /** True when job has reported completion by calling block_job_completed. */
145 /** ret code passed to block_job_completed. */
149 * Timer that is used by @block_job_sleep_ns. Accessed under
150 * block_job_mutex (in blockjob.c).
152 QEMUTimer sleep_timer
;
154 /** Current state; See @BlockJobStatus for details. */
155 BlockJobStatus status
;
157 /** True if this job should automatically finalize itself */
160 /** True if this job should automatically dismiss itself */
164 QLIST_ENTRY(BlockJob
) txn_list
;
167 typedef enum BlockJobCreateFlags
{
168 /* Default behavior */
169 BLOCK_JOB_DEFAULT
= 0x00,
170 /* BlockJob is not QMP-created and should not send QMP events */
171 BLOCK_JOB_INTERNAL
= 0x01,
172 /* BlockJob requires manual finalize step */
173 BLOCK_JOB_MANUAL_FINALIZE
= 0x02,
174 /* BlockJob requires manual dismiss step */
175 BLOCK_JOB_MANUAL_DISMISS
= 0x04,
176 } BlockJobCreateFlags
;
180 * @job: A block job, or %NULL.
182 * Get the next element from the list of block jobs after @job, or the
183 * first one if @job is %NULL.
185 * Returns the requested job, or %NULL if there are no more jobs left.
187 BlockJob
*block_job_next(BlockJob
*job
);
191 * @id: The id of the block job.
193 * Get the block job identified by @id (which must not be %NULL).
195 * Returns the requested job, or %NULL if it doesn't exist.
197 BlockJob
*block_job_get(const char *id
);
200 * block_job_add_bdrv:
202 * @name: The name to assign to the new BdrvChild
203 * @bs: A BlockDriverState that is involved in @job
204 * @perm, @shared_perm: Permissions to request on the node
206 * Add @bs to the list of BlockDriverState that are involved in
207 * @job. This means that all operations will be blocked on @bs while
210 int block_job_add_bdrv(BlockJob
*job
, const char *name
, BlockDriverState
*bs
,
211 uint64_t perm
, uint64_t shared_perm
, Error
**errp
);
214 * block_job_remove_all_bdrv:
215 * @job: The block job
217 * Remove all BlockDriverStates from the list of nodes that are involved in the
218 * job. This removes the blockers added with block_job_add_bdrv().
220 void block_job_remove_all_bdrv(BlockJob
*job
);
223 * block_job_set_speed:
224 * @job: The job to set the speed for.
225 * @speed: The new value
226 * @errp: Error object.
228 * Set a rate-limiting parameter for the job; the actual meaning may
229 * vary depending on the job type.
231 void block_job_set_speed(BlockJob
*job
, int64_t speed
, Error
**errp
);
235 * @job: A job that has not yet been started.
237 * Begins execution of a block job.
238 * Takes ownership of one reference to the job object.
240 void block_job_start(BlockJob
*job
);
244 * @job: The job to be canceled.
245 * @force: Quit a job without waiting for data to be in sync.
247 * Asynchronously cancel the specified job.
249 void block_job_cancel(BlockJob
*job
, bool force
);
252 * block_job_complete:
253 * @job: The job to be completed.
254 * @errp: Error object.
256 * Asynchronously complete the specified job.
258 void block_job_complete(BlockJob
*job
, Error
**errp
);
262 * block_job_finalize:
263 * @job: The job to fully commit and finish.
264 * @errp: Error object.
266 * For jobs that have finished their work and are pending
267 * awaiting explicit acknowledgement to commit their work,
268 * This will commit that work.
270 * FIXME: Make the below statement universally true:
271 * For jobs that support the manual workflow mode, all graph
272 * changes that occur as a result will occur after this command
273 * and before a successful reply.
275 void block_job_finalize(BlockJob
*job
, Error
**errp
);
279 * @job: The job to be dismissed.
280 * @errp: Error object.
282 * Remove a concluded job from the query list.
284 void block_job_dismiss(BlockJob
**job
, Error
**errp
);
287 * block_job_progress_update:
288 * @job: The job that has made progress
289 * @done: How much progress the job made
291 * Updates the progress counter of the job.
293 void block_job_progress_update(BlockJob
*job
, uint64_t done
);
296 * block_job_progress_set_remaining:
297 * @job: The job whose expected progress end value is set
298 * @remaining: Expected end value of the progress counter of the job
300 * Sets the expected end value of the progress counter of a job so that a
301 * completion percentage can be calculated when the progress is updated.
303 void block_job_progress_set_remaining(BlockJob
*job
, uint64_t remaining
);
307 * @job: The job to get information about.
309 * Return information about a job.
311 BlockJobInfo
*block_job_query(BlockJob
*job
, Error
**errp
);
314 * block_job_user_pause:
315 * @job: The job to be paused.
317 * Asynchronously pause the specified job.
318 * Do not allow a resume until a matching call to block_job_user_resume.
320 void block_job_user_pause(BlockJob
*job
, Error
**errp
);
324 * @job: The job to query.
326 * Returns true if the job is user-paused.
328 bool block_job_user_paused(BlockJob
*job
);
331 * block_job_user_resume:
332 * @job: The job to be resumed.
334 * Resume the specified job.
335 * Must be paired with a preceding block_job_user_pause.
337 void block_job_user_resume(BlockJob
*job
, Error
**errp
);
340 * block_job_user_cancel:
341 * @job: The job to be cancelled.
342 * @force: Quit a job without waiting for data to be in sync.
344 * Cancels the specified job, but may refuse to do so if the
345 * operation isn't currently meaningful.
347 void block_job_user_cancel(BlockJob
*job
, bool force
, Error
**errp
);
350 * block_job_cancel_sync:
351 * @job: The job to be canceled.
353 * Synchronously cancel the job. The completion callback is called
354 * before the function returns. The job may actually complete
355 * instead of canceling itself; the circumstances under which this
356 * happens depend on the kind of job that is active.
358 * Returns the return value from the job if the job actually completed
359 * during the call, or -ECANCELED if it was canceled.
361 int block_job_cancel_sync(BlockJob
*job
);
364 * block_job_cancel_sync_all:
366 * Synchronously cancels all jobs using block_job_cancel_sync().
368 void block_job_cancel_sync_all(void);
371 * block_job_complete_sync:
372 * @job: The job to be completed.
373 * @errp: Error object which may be set by block_job_complete(); this is not
374 * necessarily set on every error, the job return value has to be
377 * Synchronously complete the job. The completion callback is called before the
378 * function returns, unless it is NULL (which is permissible when using this
381 * Returns the return value from the job.
383 int block_job_complete_sync(BlockJob
*job
, Error
**errp
);
386 * block_job_iostatus_reset:
387 * @job: The job whose I/O status should be reset.
389 * Reset I/O status on @job and on BlockDriverState objects it uses,
390 * other than job->blk.
392 void block_job_iostatus_reset(BlockJob
*job
);
397 * Allocate and return a new block job transaction. Jobs can be added to the
398 * transaction using block_job_txn_add_job().
400 * The transaction is automatically freed when the last job completes or is
403 * All jobs in the transaction either complete successfully or fail/cancel as a
404 * group. Jobs wait for each other before completing. Cancelling one job
405 * cancels all jobs in the transaction.
407 BlockJobTxn
*block_job_txn_new(void);
412 * Add a reference to BlockJob refcnt, it will be decreased with
413 * block_job_unref, and then be freed if it comes to be the last
416 void block_job_ref(BlockJob
*job
);
421 * Release a reference that was previously acquired with block_job_ref
422 * or block_job_create. If it's the last reference to the object, it will be
425 void block_job_unref(BlockJob
*job
);
428 * block_job_txn_unref:
430 * Release a reference that was previously acquired with block_job_txn_add_job
431 * or block_job_txn_new. If it's the last reference to the object, it will be
434 void block_job_txn_unref(BlockJobTxn
*txn
);
437 * block_job_txn_add_job:
438 * @txn: The transaction (may be NULL)
439 * @job: Job to add to the transaction
441 * Add @job to the transaction. The @job must not already be in a transaction.
442 * The caller must call either block_job_txn_unref() or block_job_completed()
443 * to release the reference that is automatically grabbed here.
445 void block_job_txn_add_job(BlockJobTxn
*txn
, BlockJob
*job
);
448 * block_job_is_internal:
449 * @job: The job to determine if it is user-visible or not.
451 * Returns true if the job should not be visible to the management layer.
453 bool block_job_is_internal(BlockJob
*job
);
458 * Returns the driver associated with a block job.
460 const BlockJobDriver
*block_job_driver(BlockJob
*job
);