@samitouri / QOSamiQemu
Code Commits Issues Pulls Sessions CI/CD
master
master
h 240 lines 6.53 KB
Raw
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 "qapi/qapi-types-block-core.h"
30 #include "qemu/job.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 /**
44 * Data belonging to the generic Job infrastructure.
45 * Protected by job mutex.
46 */
47 Job job;
48
49 /**
50 * Status that is published by the query-block-jobs QMP API.
51 * Protected by job mutex.
52 */
53 BlockDeviceIoStatus iostatus;
54
55 /**
56 * Speed that was set with @block_job_set_speed.
57 * Always modified and read under the BQL (GLOBAL_STATE_CODE).
58 */
59 int64_t speed;
60
61 /**
62 * Rate limiting data structure for implementing @speed.
63 * RateLimit API is thread-safe.
64 */
65 RateLimit limit;
66
67 /**
68 * Block other operations when block job is running.
69 * Always modified and read under the BQL (GLOBAL_STATE_CODE).
70 */
71 Error *blocker;
72
73 /** All notifiers are set once in block_job_create() and never modified. */
74
75 /** Called when a cancelled job is finalised. */
76 Notifier finalize_cancelled_notifier;
77
78 /** Called when a successfully completed job is finalised. */
79 Notifier finalize_completed_notifier;
80
81 /** Called when the job transitions to PENDING */
82 Notifier pending_notifier;
83
84 /** Called when the job transitions to READY */
85 Notifier ready_notifier;
86
87 /** Called when the job coroutine yields or terminates */
88 Notifier idle_notifier;
89
90 /**
91 * BlockDriverStates that are involved in this block job.
92 * Always modified and read under the BQL (GLOBAL_STATE_CODE).
93 */
94 GSList *nodes;
95 } BlockJob;
96
97 /*
98 * Global state (GS) API. These functions run under the BQL.
99 *
100 * See include/block/block-global-state.h for more information about
101 * the GS API.
102 */
103
104 /**
105 * block_job_next_locked:
106 * @job: A block job, or %NULL.
107 *
108 * Get the next element from the list of block jobs after @job, or the
109 * first one if @job is %NULL.
110 *
111 * Returns the requested job, or %NULL if there are no more jobs left.
112 * Called with job lock held.
113 */
114 BlockJob *block_job_next_locked(BlockJob *job);
115
116 /**
117 * block_job_get:
118 * @id: The id of the block job.
119 *
120 * Get the block job identified by @id (which must not be %NULL).
121 *
122 * Returns the requested job, or %NULL if it doesn't exist.
123 * Called with job lock *not* held.
124 */
125 BlockJob *block_job_get(const char *id);
126
127 /* Same as block_job_get(), but called with job lock held. */
128 BlockJob *block_job_get_locked(const char *id);
129
130 /**
131 * block_job_add_bdrv:
132 * @job: A block job
133 * @name: The name to assign to the new BdrvChild
134 * @bs: A BlockDriverState that is involved in @job
135 * @perm, @shared_perm: Permissions to request on the node
136 *
137 * Add @bs to the list of BlockDriverState that are involved in
138 * @job. This means that all operations will be blocked on @bs while
139 * @job exists.
140 *
141 * All block nodes must be drained.
142 */
143 int GRAPH_WRLOCK
144 block_job_add_bdrv(BlockJob *job, const char *name, BlockDriverState *bs,
145 uint64_t perm, uint64_t shared_perm, Error **errp);
146
147 /**
148 * block_job_remove_all_bdrv:
149 * @job: The block job
150 *
151 * Remove all BlockDriverStates from the list of nodes that are involved in the
152 * job. This removes the blockers added with block_job_add_bdrv().
153 */
154 void GRAPH_UNLOCKED block_job_remove_all_bdrv(BlockJob *job);
155
156 /**
157 * block_job_has_bdrv:
158 * @job: The block job
159 *
160 * Searches for @bs in the list of nodes that are involved in the
161 * job.
162 */
163 bool block_job_has_bdrv(BlockJob *job, BlockDriverState *bs);
164
165 /**
166 * block_job_set_speed_locked:
167 * @job: The job to set the speed for.
168 * @speed: The new value
169 * @errp: Error object.
170 *
171 * Set a rate-limiting parameter for the job; the actual meaning may
172 * vary depending on the job type.
173 *
174 * Called with job lock held, but might release it temporarily.
175 */
176 bool block_job_set_speed_locked(BlockJob *job, int64_t speed, Error **errp);
177
178 /**
179 * block_job_change_locked:
180 * @job: The job to change.
181 * @opts: The new options.
182 * @errp: Error object.
183 *
184 * Change the job according to opts.
185 */
186 void block_job_change_locked(BlockJob *job, BlockJobChangeOptions *opts,
187 Error **errp);
188
189 /**
190 * block_job_query_locked:
191 * @job: The job to get information about.
192 *
193 * Return information about a job.
194 *
195 * Called with job lock held.
196 */
197 BlockJobInfo *block_job_query_locked(BlockJob *job, Error **errp);
198
199 /**
200 * block_job_iostatus_reset_locked:
201 * @job: The job whose I/O status should be reset.
202 *
203 * Reset I/O status on @job and on BlockDriverState objects it uses,
204 * other than job->blk.
205 *
206 * Called with job lock held.
207 */
208 void block_job_iostatus_reset_locked(BlockJob *job);
209
210 /*
211 * block_job_get_aio_context:
212 *
213 * Returns aio context associated with a block job.
214 */
215 AioContext *block_job_get_aio_context(BlockJob *job);
216
217
218 /*
219 * Common functions that are neither I/O nor Global State.
220 *
221 * See include/block/block-common.h for more information about
222 * the Common API.
223 */
224
225 /**
226 * block_job_is_internal:
227 * @job: The job to determine if it is user-visible or not.
228 *
229 * Returns true if the job should not be visible to the management layer.
230 */
231 bool block_job_is_internal(BlockJob *job);
232
233 /**
234 * block_job_driver:
235 *
236 * Returns the driver associated with a block job.
237 */
238 const BlockJobDriver *block_job_driver(BlockJob *job);
239
240 #endif