hw/riscv: Move sifive_u_otp model to hw/misc
[qemu/ar7.git] / qapi / job.json
blob280c2f76f136dc66446863fdb1a5a95a1bd1d846
1 # -*- Mode: Python -*-
2 # vim: filetype=python
4 ##
5 # == Background jobs
6 ##
8 ##
9 # @JobType:
11 # Type of a background job.
13 # @commit: block commit job type, see "block-commit"
15 # @stream: block stream job type, see "block-stream"
17 # @mirror: drive mirror job type, see "drive-mirror"
19 # @backup: drive backup job type, see "drive-backup"
21 # @create: image creation job type, see "blockdev-create" (since 3.0)
23 # @amend: image options amend job type, see "x-blockdev-amend" (since 5.1)
25 # Since: 1.7
27 { 'enum': 'JobType',
28   'data': ['commit', 'stream', 'mirror', 'backup', 'create', 'amend'] }
31 # @JobStatus:
33 # Indicates the present state of a given job in its lifetime.
35 # @undefined: Erroneous, default state. Should not ever be visible.
37 # @created: The job has been created, but not yet started.
39 # @running: The job is currently running.
41 # @paused: The job is running, but paused. The pause may be requested by
42 #          either the QMP user or by internal processes.
44 # @ready: The job is running, but is ready for the user to signal completion.
45 #         This is used for long-running jobs like mirror that are designed to
46 #         run indefinitely.
48 # @standby: The job is ready, but paused. This is nearly identical to @paused.
49 #           The job may return to @ready or otherwise be canceled.
51 # @waiting: The job is waiting for other jobs in the transaction to converge
52 #           to the waiting state. This status will likely not be visible for
53 #           the last job in a transaction.
55 # @pending: The job has finished its work, but has finalization steps that it
56 #           needs to make prior to completing. These changes will require
57 #           manual intervention via @job-finalize if auto-finalize was set to
58 #           false. These pending changes may still fail.
60 # @aborting: The job is in the process of being aborted, and will finish with
61 #            an error. The job will afterwards report that it is @concluded.
62 #            This status may not be visible to the management process.
64 # @concluded: The job has finished all work. If auto-dismiss was set to false,
65 #             the job will remain in the query list until it is dismissed via
66 #             @job-dismiss.
68 # @null: The job is in the process of being dismantled. This state should not
69 #        ever be visible externally.
71 # Since: 2.12
73 { 'enum': 'JobStatus',
74   'data': ['undefined', 'created', 'running', 'paused', 'ready', 'standby',
75            'waiting', 'pending', 'aborting', 'concluded', 'null' ] }
78 # @JobVerb:
80 # Represents command verbs that can be applied to a job.
82 # @cancel: see @job-cancel
84 # @pause: see @job-pause
86 # @resume: see @job-resume
88 # @set-speed: see @block-job-set-speed
90 # @complete: see @job-complete
92 # @dismiss: see @job-dismiss
94 # @finalize: see @job-finalize
96 # Since: 2.12
98 { 'enum': 'JobVerb',
99   'data': ['cancel', 'pause', 'resume', 'set-speed', 'complete', 'dismiss',
100            'finalize' ] }
103 # @JOB_STATUS_CHANGE:
105 # Emitted when a job transitions to a different status.
107 # @id: The job identifier
108 # @status: The new job status
110 # Since: 3.0
112 { 'event': 'JOB_STATUS_CHANGE',
113   'data': { 'id': 'str',
114             'status': 'JobStatus' } }
117 # @job-pause:
119 # Pause an active job.
121 # This command returns immediately after marking the active job for pausing.
122 # Pausing an already paused job is an error.
124 # The job will pause as soon as possible, which means transitioning into the
125 # PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
126 # corresponding JOB_STATUS_CHANGE event will be emitted.
128 # Cancelling a paused job automatically resumes it.
130 # @id: The job identifier.
132 # Since: 3.0
134 { 'command': 'job-pause', 'data': { 'id': 'str' } }
137 # @job-resume:
139 # Resume a paused job.
141 # This command returns immediately after resuming a paused job. Resuming an
142 # already running job is an error.
144 # @id : The job identifier.
146 # Since: 3.0
148 { 'command': 'job-resume', 'data': { 'id': 'str' } }
151 # @job-cancel:
153 # Instruct an active background job to cancel at the next opportunity.
154 # This command returns immediately after marking the active job for
155 # cancellation.
157 # The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
158 # event. Usually, the status will change to ABORTING, but it is possible that
159 # a job successfully completes (e.g. because it was almost done and there was
160 # no opportunity to cancel earlier than completing the job) and transitions to
161 # PENDING instead.
163 # @id: The job identifier.
165 # Since: 3.0
167 { 'command': 'job-cancel', 'data': { 'id': 'str' } }
171 # @job-complete:
173 # Manually trigger completion of an active job in the READY state.
175 # @id: The job identifier.
177 # Since: 3.0
179 { 'command': 'job-complete', 'data': { 'id': 'str' } }
182 # @job-dismiss:
184 # Deletes a job that is in the CONCLUDED state. This command only needs to be
185 # run explicitly for jobs that don't have automatic dismiss enabled.
187 # This command will refuse to operate on any job that has not yet reached its
188 # terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
189 # event, job-cancel or job-complete will still need to be used as appropriate.
191 # @id: The job identifier.
193 # Since: 3.0
195 { 'command': 'job-dismiss', 'data': { 'id': 'str' } }
198 # @job-finalize:
200 # Instructs all jobs in a transaction (or a single job if it is not part of any
201 # transaction) to finalize any graph changes and do any necessary cleanup. This
202 # command requires that all involved jobs are in the PENDING state.
204 # For jobs in a transaction, instructing one job to finalize will force
205 # ALL jobs in the transaction to finalize, so it is only necessary to instruct
206 # a single member job to finalize.
208 # @id: The identifier of any job in the transaction, or of a job that is not
209 #      part of any transaction.
211 # Since: 3.0
213 { 'command': 'job-finalize', 'data': { 'id': 'str' } }
216 # @JobInfo:
218 # Information about a job.
220 # @id: The job identifier
222 # @type: The kind of job that is being performed
224 # @status: Current job state/status
226 # @current-progress: Progress made until now. The unit is arbitrary and the
227 #                    value can only meaningfully be used for the ratio of
228 #                    @current-progress to @total-progress. The value is
229 #                    monotonically increasing.
231 # @total-progress: Estimated @current-progress value at the completion of
232 #                  the job. This value can arbitrarily change while the
233 #                  job is running, in both directions.
235 # @error: If this field is present, the job failed; if it is
236 #         still missing in the CONCLUDED state, this indicates
237 #         successful completion.
239 #         The value is a human-readable error message to describe
240 #         the reason for the job failure. It should not be parsed
241 #         by applications.
243 # Since: 3.0
245 { 'struct': 'JobInfo',
246   'data': { 'id': 'str', 'type': 'JobType', 'status': 'JobStatus',
247             'current-progress': 'int', 'total-progress': 'int',
248             '*error': 'str' } }
251 # @query-jobs:
253 # Return information about jobs.
255 # Returns: a list with a @JobInfo for each active job
257 # Since: 3.0
259 { 'command': 'query-jobs', 'returns': ['JobInfo'] }