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 "qemu/job.h" |
30 | #include "block/block.h" |
31 | #include "qemu/ratelimit.h" |
32 | |
33 | #define BLOCK_JOB_SLICE_TIME 100000000ULL /* ns */ |
34 | |
35 | typedef struct BlockJobDriver BlockJobDriver; |
36 | |
37 | /** |
38 | * BlockJob: |
39 | * |
40 | * Long-running operation on a BlockDriverState. |
41 | */ |
42 | typedef struct BlockJob { |
43 | /** Data belonging to the generic Job infrastructure */ |
44 | Job job; |
45 | |
46 | /** The block device on which the job is operating. */ |
47 | BlockBackend *blk; |
48 | |
49 | /** Status that is published by the query-block-jobs QMP API */ |
50 | BlockDeviceIoStatus iostatus; |
51 | |
52 | /** Speed that was set with @block_job_set_speed. */ |
53 | int64_t speed; |
54 | |
55 | /** Rate limiting data structure for implementing @speed. */ |
56 | RateLimit limit; |
57 | |
58 | /** Block other operations when block job is running */ |
59 | Error *blocker; |
60 | |
61 | /** Called when a cancelled job is finalised. */ |
62 | Notifier finalize_cancelled_notifier; |
63 | |
64 | /** Called when a successfully completed job is finalised. */ |
65 | Notifier finalize_completed_notifier; |
66 | |
67 | /** Called when the job transitions to PENDING */ |
68 | Notifier pending_notifier; |
69 | |
70 | /** Called when the job transitions to READY */ |
71 | Notifier ready_notifier; |
72 | |
73 | /** Called when the job coroutine yields or terminates */ |
74 | Notifier idle_notifier; |
75 | |
76 | /** BlockDriverStates that are involved in this block job */ |
77 | GSList *nodes; |
78 | } BlockJob; |
79 | |
80 | /** |
81 | * block_job_next: |
82 | * @job: A block job, or %NULL. |
83 | * |
84 | * Get the next element from the list of block jobs after @job, or the |
85 | * first one if @job is %NULL. |
86 | * |
87 | * Returns the requested job, or %NULL if there are no more jobs left. |
88 | */ |
89 | BlockJob *block_job_next(BlockJob *job); |
90 | |
91 | /** |
92 | * block_job_get: |
93 | * @id: The id of the block job. |
94 | * |
95 | * Get the block job identified by @id (which must not be %NULL). |
96 | * |
97 | * Returns the requested job, or %NULL if it doesn't exist. |
98 | */ |
99 | BlockJob *block_job_get(const char *id); |
100 | |
101 | /** |
102 | * block_job_add_bdrv: |
103 | * @job: A block job |
104 | * @name: The name to assign to the new BdrvChild |
105 | * @bs: A BlockDriverState that is involved in @job |
106 | * @perm, @shared_perm: Permissions to request on the node |
107 | * |
108 | * Add @bs to the list of BlockDriverState that are involved in |
109 | * @job. This means that all operations will be blocked on @bs while |
110 | * @job exists. |
111 | */ |
112 | int block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs, |
113 | uint64_t perm, uint64_t shared_perm, Error **errp); |
114 | |
115 | /** |
116 | * block_job_remove_all_bdrv: |
117 | * @job: The block job |
118 | * |
119 | * Remove all BlockDriverStates from the list of nodes that are involved in the |
120 | * job. This removes the blockers added with block_job_add_bdrv(). |
121 | */ |
122 | void block_job_remove_all_bdrv(BlockJob *job); |
123 | |
124 | /** |
125 | * block_job_has_bdrv: |
126 | * @job: The block job |
127 | * |
128 | * Searches for @bs in the list of nodes that are involved in the |
129 | * job. |
130 | */ |
131 | bool block_job_has_bdrv(BlockJob *job, BlockDriverState *bs); |
132 | |
133 | /** |
134 | * block_job_set_speed: |
135 | * @job: The job to set the speed for. |
136 | * @speed: The new value |
137 | * @errp: Error object. |
138 | * |
139 | * Set a rate-limiting parameter for the job; the actual meaning may |
140 | * vary depending on the job type. |
141 | */ |
142 | void block_job_set_speed(BlockJob *job, int64_t speed, Error **errp); |
143 | |
144 | /** |
145 | * block_job_query: |
146 | * @job: The job to get information about. |
147 | * |
148 | * Return information about a job. |
149 | */ |
150 | BlockJobInfo *block_job_query(BlockJob *job, Error **errp); |
151 | |
152 | /** |
153 | * block_job_iostatus_reset: |
154 | * @job: The job whose I/O status should be reset. |
155 | * |
156 | * Reset I/O status on @job and on BlockDriverState objects it uses, |
157 | * other than job->blk. |
158 | */ |
159 | void block_job_iostatus_reset(BlockJob *job); |
160 | |
161 | /** |
162 | * block_job_is_internal: |
163 | * @job: The job to determine if it is user-visible or not. |
164 | * |
165 | * Returns true if the job should not be visible to the management layer. |
166 | */ |
167 | bool block_job_is_internal(BlockJob *job); |
168 | |
169 | /** |
170 | * block_job_driver: |
171 | * |
172 | * Returns the driver associated with a block job. |
173 | */ |
174 | const BlockJobDriver *block_job_driver(BlockJob *job); |
175 | |
176 | #endif |
177 | |