xref: /openbmc/qemu/qapi/transaction.json (revision 01bed0ff)
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4
5##
6# = Transactions
7##
8
9{ 'include': 'block-core.json' }
10
11##
12# @Abort:
13#
14# This action can be used to test transaction failure.
15#
16# Since: 1.6
17##
18{ 'struct': 'Abort',
19  'data': { } }
20
21##
22# @ActionCompletionMode:
23#
24# An enumeration of Transactional completion modes.
25#
26# @individual: Do not attempt to cancel any other Actions if any
27#     Actions fail after the Transaction request succeeds.  All
28#     Actions that can complete successfully will do so without
29#     waiting on others.  This is the default.
30#
31# @grouped: If any Action fails after the Transaction succeeds, cancel
32#     all Actions.  Actions do not complete until all Actions are
33#     ready to complete.  May be rejected by Actions that do not
34#     support this completion mode.
35#
36# Since: 2.5
37##
38{ 'enum': 'ActionCompletionMode',
39  'data': [ 'individual', 'grouped' ] }
40
41##
42# @TransactionActionKind:
43#
44# @abort: Since 1.6
45#
46# @block-dirty-bitmap-add: Since 2.5
47#
48# @block-dirty-bitmap-remove: Since 4.2
49#
50# @block-dirty-bitmap-clear: Since 2.5
51#
52# @block-dirty-bitmap-enable: Since 4.0
53#
54# @block-dirty-bitmap-disable: Since 4.0
55#
56# @block-dirty-bitmap-merge: Since 4.0
57#
58# @blockdev-backup: Since 2.3
59#
60# @blockdev-snapshot: Since 2.5
61#
62# @blockdev-snapshot-internal-sync: Since 1.7
63#
64# @blockdev-snapshot-sync: since 1.1
65#
66# @drive-backup: Since 1.6
67#
68# Features:
69#
70# @deprecated: Member @drive-backup is deprecated.  Use member
71#     @blockdev-backup instead.
72#
73# Since: 1.1
74##
75{ 'enum': 'TransactionActionKind',
76  'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove',
77            'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable',
78            'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge',
79            'blockdev-backup', 'blockdev-snapshot',
80            'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync',
81            { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] }
82
83##
84# @AbortWrapper:
85#
86# Since: 1.6
87##
88{ 'struct': 'AbortWrapper',
89  'data': { 'data': 'Abort' } }
90
91##
92# @BlockDirtyBitmapAddWrapper:
93#
94# Since: 2.5
95##
96{ 'struct': 'BlockDirtyBitmapAddWrapper',
97  'data': { 'data': 'BlockDirtyBitmapAdd' } }
98
99##
100# @BlockDirtyBitmapWrapper:
101#
102# Since: 2.5
103##
104{ 'struct': 'BlockDirtyBitmapWrapper',
105  'data': { 'data': 'BlockDirtyBitmap' } }
106
107##
108# @BlockDirtyBitmapMergeWrapper:
109#
110# Since: 4.0
111##
112{ 'struct': 'BlockDirtyBitmapMergeWrapper',
113  'data': { 'data': 'BlockDirtyBitmapMerge' } }
114
115##
116# @BlockdevBackupWrapper:
117#
118# Since: 2.3
119##
120{ 'struct': 'BlockdevBackupWrapper',
121  'data': { 'data': 'BlockdevBackup' } }
122
123##
124# @BlockdevSnapshotWrapper:
125#
126# Since: 2.5
127##
128{ 'struct': 'BlockdevSnapshotWrapper',
129  'data': { 'data': 'BlockdevSnapshot' } }
130
131##
132# @BlockdevSnapshotInternalWrapper:
133#
134# Since: 1.7
135##
136{ 'struct': 'BlockdevSnapshotInternalWrapper',
137  'data': { 'data': 'BlockdevSnapshotInternal' } }
138
139##
140# @BlockdevSnapshotSyncWrapper:
141#
142# Since: 1.1
143##
144{ 'struct': 'BlockdevSnapshotSyncWrapper',
145  'data': { 'data': 'BlockdevSnapshotSync' } }
146
147##
148# @DriveBackupWrapper:
149#
150# Since: 1.6
151##
152{ 'struct': 'DriveBackupWrapper',
153  'data': { 'data': 'DriveBackup' } }
154
155##
156# @TransactionAction:
157#
158# A discriminated record of operations that can be performed with
159# @transaction.
160#
161# @type: the operation to be performed
162#
163# Since: 1.1
164##
165{ 'union': 'TransactionAction',
166  'base': { 'type': 'TransactionActionKind' },
167  'discriminator': 'type',
168  'data': {
169       'abort': 'AbortWrapper',
170       'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper',
171       'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper',
172       'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper',
173       'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper',
174       'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper',
175       'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper',
176       'blockdev-backup': 'BlockdevBackupWrapper',
177       'blockdev-snapshot': 'BlockdevSnapshotWrapper',
178       'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper',
179       'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper',
180       'drive-backup': 'DriveBackupWrapper'
181   } }
182
183##
184# @TransactionProperties:
185#
186# Optional arguments to modify the behavior of a Transaction.
187#
188# @completion-mode: Controls how jobs launched asynchronously by
189#     Actions will complete or fail as a group.  See
190#     @ActionCompletionMode for details.
191#
192# Since: 2.5
193##
194{ 'struct': 'TransactionProperties',
195  'data': {
196       '*completion-mode': 'ActionCompletionMode'
197  }
198}
199
200##
201# @transaction:
202#
203# Executes a number of transactionable QMP commands atomically.  If
204# any operation fails, then the entire set of actions will be
205# abandoned and the appropriate error returned.
206#
207# For external snapshots, the dictionary contains the device, the file
208# to use for the new snapshot, and the format.  The default format, if
209# not specified, is qcow2.
210#
211# Each new snapshot defaults to being created by QEMU (wiping any
212# contents if the file already exists), but it is also possible to
213# reuse an externally-created file.  In the latter case, you should
214# ensure that the new image file has the same contents as the current
215# one; QEMU cannot perform any meaningful check.  Typically this is
216# achieved by using the current image file as the backing file for the
217# new image.
218#
219# On failure, the original disks pre-snapshot attempt will be used.
220#
221# For internal snapshots, the dictionary contains the device and the
222# snapshot's name.  If an internal snapshot matching name already
223# exists, the request will be rejected.  Only some image formats
224# support it, for example, qcow2, and rbd,
225#
226# On failure, qemu will try delete the newly created internal snapshot
227# in the transaction.  When an I/O error occurs during deletion, the
228# user needs to fix it later with qemu-img or other command.
229#
230# @actions: List of @TransactionAction; information needed for the
231#     respective operations.
232#
233# @properties: structure of additional options to control the
234#     execution of the transaction.  See @TransactionProperties for
235#     additional detail.
236#
237# Errors:
238#     - Any errors from commands in the transaction
239#
240# .. note:: The transaction aborts on the first failure.  Therefore,
241#    there will be information on only one failed operation returned
242#    in an error condition, and subsequent actions will not have been
243#    attempted.
244#
245# Since: 1.1
246#
247# .. qmp-example::
248#
249#     -> { "execute": "transaction",
250#          "arguments": { "actions": [
251#              { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
252#                                          "snapshot-file": "/some/place/my-image",
253#                                          "format": "qcow2" } },
254#              { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
255#                                          "snapshot-file": "/some/place/my-image2",
256#                                          "snapshot-node-name": "node3432",
257#                                          "mode": "existing",
258#                                          "format": "qcow2" } },
259#              { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
260#                                          "snapshot-file": "/some/place/my-image2",
261#                                          "mode": "existing",
262#                                          "format": "qcow2" } },
263#              { "type": "blockdev-snapshot-internal-sync", "data" : {
264#                                          "device": "ide-hd2",
265#                                          "name": "snapshot0" } } ] } }
266#     <- { "return": {} }
267##
268{ 'command': 'transaction',
269  'data': { 'actions': [ 'TransactionAction' ],
270            '*properties': 'TransactionProperties'
271          }
272}
273