target/riscv: vmfirst find-first-set mask bit
[qemu.git] / qapi / job.json
1 # -*- Mode: Python -*-
2
3 ##
4 # == Background jobs
5 ##
6
7 ##
8 # @JobType:
9 #
10 # Type of a background job.
11 #
12 # @commit: block commit job type, see "block-commit"
13 #
14 # @stream: block stream job type, see "block-stream"
15 #
16 # @mirror: drive mirror job type, see "drive-mirror"
17 #
18 # @backup: drive backup job type, see "drive-backup"
19 #
20 # @create: image creation job type, see "blockdev-create" (since 3.0)
21 #
22 # Since: 1.7
23 ##
24 { 'enum': 'JobType',
25   'data': ['commit', 'stream', 'mirror', 'backup', 'create'] }
26
27 ##
28 # @JobStatus:
29 #
30 # Indicates the present state of a given job in its lifetime.
31 #
32 # @undefined: Erroneous, default state. Should not ever be visible.
33 #
34 # @created: The job has been created, but not yet started.
35 #
36 # @running: The job is currently running.
37 #
38 # @paused: The job is running, but paused. The pause may be requested by
39 #          either the QMP user or by internal processes.
40 #
41 # @ready: The job is running, but is ready for the user to signal completion.
42 #         This is used for long-running jobs like mirror that are designed to
43 #         run indefinitely.
44 #
45 # @standby: The job is ready, but paused. This is nearly identical to @paused.
46 #           The job may return to @ready or otherwise be canceled.
47 #
48 # @waiting: The job is waiting for other jobs in the transaction to converge
49 #           to the waiting state. This status will likely not be visible for
50 #           the last job in a transaction.
51 #
52 # @pending: The job has finished its work, but has finalization steps that it
53 #           needs to make prior to completing. These changes will require
54 #           manual intervention via @job-finalize if auto-finalize was set to
55 #           false. These pending changes may still fail.
56 #
57 # @aborting: The job is in the process of being aborted, and will finish with
58 #            an error. The job will afterwards report that it is @concluded.
59 #            This status may not be visible to the management process.
60 #
61 # @concluded: The job has finished all work. If auto-dismiss was set to false,
62 #             the job will remain in the query list until it is dismissed via
63 #             @job-dismiss.
64 #
65 # @null: The job is in the process of being dismantled. This state should not
66 #        ever be visible externally.
67 #
68 # Since: 2.12
69 ##
70 { 'enum': 'JobStatus',
71   'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby',
72            'waiting', 'pending', 'aborting', 'concluded', 'null' ] }
73
74 ##
75 # @JobVerb:
76 #
77 # Represents command verbs that can be applied to a job.
78 #
79 # @cancel: see @job-cancel
80 #
81 # @pause: see @job-pause
82 #
83 # @resume: see @job-resume
84 #
85 # @set-speed: see @block-job-set-speed
86 #
87 # @complete: see @job-complete
88 #
89 # @dismiss: see @job-dismiss
90 #
91 # @finalize: see @job-finalize
92 #
93 # Since: 2.12
94 ##
95 { 'enum': 'JobVerb',
96   'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
97            'finalize' ] }
98
99 ##
100 # @JOB_STATUS_CHANGE:
101 #
102 # Emitted when a job transitions to a different status.
103 #
104 # @id: The job identifier
105 # @status: The new job status
106 #
107 # Since: 3.0
108 ##
109 { 'event': 'JOB_STATUS_CHANGE',
110   'data': { 'id': 'str',
111             'status': 'JobStatus' } }
112
113 ##
114 # @job-pause:
115 #
116 # Pause an active job.
117 #
118 # This command returns immediately after marking the active job for pausing.
119 # Pausing an already paused job is an error.
120 #
121 # The job will pause as soon as possible, which means transitioning into the
122 # PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
123 # corresponding JOB_STATUS_CHANGE event will be emitted.
124 #
125 # Cancelling a paused job automatically resumes it.
126 #
127 # @id: The job identifier.
128 #
129 # Since: 3.0
130 ##
131 { 'command': 'job-pause', 'data': { 'id': 'str' } }
132
133 ##
134 # @job-resume:
135 #
136 # Resume a paused job.
137 #
138 # This command returns immediately after resuming a paused job. Resuming an
139 # already running job is an error.
140 #
141 # @id : The job identifier.
142 #
143 # Since: 3.0
144 ##
145 { 'command': 'job-resume', 'data': { 'id': 'str' } }
146
147 ##
148 # @job-cancel:
149 #
150 # Instruct an active background job to cancel at the next opportunity.
151 # This command returns immediately after marking the active job for
152 # cancellation.
153 #
154 # The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
155 # event. Usually, the status will change to ABORTING, but it is possible that
156 # a job successfully completes (e.g. because it was almost done and there was
157 # no opportunity to cancel earlier than completing the job) and transitions to
158 # PENDING instead.
159 #
160 # @id: The job identifier.
161 #
162 # Since: 3.0
163 ##
164 { 'command': 'job-cancel', 'data': { 'id': 'str' } }
165
166
167 ##
168 # @job-complete:
169 #
170 # Manually trigger completion of an active job in the READY state.
171 #
172 # @id: The job identifier.
173 #
174 # Since: 3.0
175 ##
176 { 'command': 'job-complete', 'data': { 'id': 'str' } }
177
178 ##
179 # @job-dismiss:
180 #
181 # Deletes a job that is in the CONCLUDED state. This command only needs to be
182 # run explicitly for jobs that don't have automatic dismiss enabled.
183 #
184 # This command will refuse to operate on any job that has not yet reached its
185 # terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
186 # event, job-cancel or job-complete will still need to be used as appropriate.
187 #
188 # @id: The job identifier.
189 #
190 # Since: 3.0
191 ##
192 { 'command': 'job-dismiss', 'data': { 'id': 'str' } }
193
194 ##
195 # @job-finalize:
196 #
197 # Instructs all jobs in a transaction (or a single job if it is not part of any
198 # transaction) to finalize any graph changes and do any necessary cleanup. This
199 # command requires that all involved jobs are in the PENDING state.
200 #
201 # For jobs in a transaction, instructing one job to finalize will force
202 # ALL jobs in the transaction to finalize, so it is only necessary to instruct
203 # a single member job to finalize.
204 #
205 # @id: The identifier of any job in the transaction, or of a job that is not
206 #      part of any transaction.
207 #
208 # Since: 3.0
209 ##
210 { 'command': 'job-finalize', 'data': { 'id': 'str' } }
211
212 ##
213 # @JobInfo:
214 #
215 # Information about a job.
216 #
217 # @id: The job identifier
218 #
219 # @type: The kind of job that is being performed
220 #
221 # @status: Current job state/status
222 #
223 # @current-progress: Progress made until now. The unit is arbitrary and the
224 #                    value can only meaningfully be used for the ratio of
225 #                    @current-progress to @total-progress. The value is
226 #                    monotonically increasing.
227 #
228 # @total-progress: Estimated @current-progress value at the completion of
229 #                  the job. This value can arbitrarily change while the
230 #                  job is running, in both directions.
231 #
232 # @error: If this field is present, the job failed; if it is
233 #         still missing in the CONCLUDED state, this indicates
234 #         successful completion.
235 #
236 #         The value is a human-readable error message to describe
237 #         the reason for the job failure. It should not be parsed
238 #         by applications.
239 #
240 # Since: 3.0
241 ##
242 { 'struct': 'JobInfo',
243   'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
244             'current-progress': 'int', 'total-progress': 'int',
245             '*error': 'str' } }
246
247 ##
248 # @query-jobs:
249 #
250 # Return information about jobs.
251 #
252 # Returns: a list with a @JobInfo for each active job
253 #
254 # Since: 3.0
255 ##
256 { 'command': 'query-jobs', 'returns': ['JobInfo'] }