migration: Fix potential race on postcopy_qemufile_src
[qemu/ar7.git] / qapi / transaction.json
blob381a2df78283bb658bf3d181a917f7315808c440
1 # -*- Mode: Python -*-
2 # vim: filetype=python
5 ##
6 # = Transactions
7 ##
9 { 'include': 'block-core.json' }
12 # @Abort:
14 # This action can be used to test transaction failure.
16 # Since: 1.6
18 { 'struct': 'Abort',
19   'data': { } }
22 # @ActionCompletionMode:
24 # An enumeration of Transactional completion modes.
26 # @individual: Do not attempt to cancel any other Actions if any Actions fail
27 #              after the Transaction request succeeds. All Actions that
28 #              can complete successfully will do so without waiting on others.
29 #              This is the default.
31 # @grouped: If any Action fails after the Transaction succeeds, cancel all
32 #           Actions. Actions do not complete until all Actions are ready to
33 #           complete. May be rejected by Actions that do not support this
34 #           completion mode.
36 # Since: 2.5
38 { 'enum': 'ActionCompletionMode',
39   'data': [ 'individual', 'grouped' ] }
42 # @TransactionActionKind:
44 # @abort: Since 1.6
45 # @block-dirty-bitmap-add: Since 2.5
46 # @block-dirty-bitmap-remove: Since 4.2
47 # @block-dirty-bitmap-clear: Since 2.5
48 # @block-dirty-bitmap-enable: Since 4.0
49 # @block-dirty-bitmap-disable: Since 4.0
50 # @block-dirty-bitmap-merge: Since 4.0
51 # @blockdev-backup: Since 2.3
52 # @blockdev-snapshot: Since 2.5
53 # @blockdev-snapshot-internal-sync: Since 1.7
54 # @blockdev-snapshot-sync: since 1.1
55 # @drive-backup: Since 1.6
57 # Features:
58 # @deprecated: Member @drive-backup is deprecated.  Use member
59 #              @blockdev-backup instead.
61 # Since: 1.1
63 { 'enum': 'TransactionActionKind',
64   'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove',
65             'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable',
66             'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge',
67             'blockdev-backup', 'blockdev-snapshot',
68             'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync',
69             { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] }
72 # @AbortWrapper:
74 # Since: 1.6
76 { 'struct': 'AbortWrapper',
77   'data': { 'data': 'Abort' } }
80 # @BlockDirtyBitmapAddWrapper:
82 # Since: 2.5
84 { 'struct': 'BlockDirtyBitmapAddWrapper',
85   'data': { 'data': 'BlockDirtyBitmapAdd' } }
88 # @BlockDirtyBitmapWrapper:
90 # Since: 2.5
92 { 'struct': 'BlockDirtyBitmapWrapper',
93   'data': { 'data': 'BlockDirtyBitmap' } }
96 # @BlockDirtyBitmapMergeWrapper:
98 # Since: 4.0
100 { 'struct': 'BlockDirtyBitmapMergeWrapper',
101   'data': { 'data': 'BlockDirtyBitmapMerge' } }
104 # @BlockdevBackupWrapper:
106 # Since: 2.3
108 { 'struct': 'BlockdevBackupWrapper',
109   'data': { 'data': 'BlockdevBackup' } }
112 # @BlockdevSnapshotWrapper:
114 # Since: 2.5
116 { 'struct': 'BlockdevSnapshotWrapper',
117   'data': { 'data': 'BlockdevSnapshot' } }
120 # @BlockdevSnapshotInternalWrapper:
122 # Since: 1.7
124 { 'struct': 'BlockdevSnapshotInternalWrapper',
125   'data': { 'data': 'BlockdevSnapshotInternal' } }
128 # @BlockdevSnapshotSyncWrapper:
130 # Since: 1.1
132 { 'struct': 'BlockdevSnapshotSyncWrapper',
133   'data': { 'data': 'BlockdevSnapshotSync' } }
136 # @DriveBackupWrapper:
138 # Since: 1.6
140 { 'struct': 'DriveBackupWrapper',
141   'data': { 'data': 'DriveBackup' } }
144 # @TransactionAction:
146 # A discriminated record of operations that can be performed with
147 # @transaction.
149 # Since: 1.1
151 { 'union': 'TransactionAction',
152   'base': { 'type': 'TransactionActionKind' },
153   'discriminator': 'type',
154   'data': {
155        'abort': 'AbortWrapper',
156        'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper',
157        'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper',
158        'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper',
159        'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper',
160        'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper',
161        'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper',
162        'blockdev-backup': 'BlockdevBackupWrapper',
163        'blockdev-snapshot': 'BlockdevSnapshotWrapper',
164        'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper',
165        'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper',
166        'drive-backup': 'DriveBackupWrapper'
167    } }
170 # @TransactionProperties:
172 # Optional arguments to modify the behavior of a Transaction.
174 # @completion-mode: Controls how jobs launched asynchronously by
175 #                   Actions will complete or fail as a group.
176 #                   See @ActionCompletionMode for details.
178 # Since: 2.5
180 { 'struct': 'TransactionProperties',
181   'data': {
182        '*completion-mode': 'ActionCompletionMode'
183   }
187 # @transaction:
189 # Executes a number of transactionable QMP commands atomically. If any
190 # operation fails, then the entire set of actions will be abandoned and the
191 # appropriate error returned.
193 # For external snapshots, the dictionary contains the device, the file to use for
194 # the new snapshot, and the format.  The default format, if not specified, is
195 # qcow2.
197 # Each new snapshot defaults to being created by QEMU (wiping any
198 # contents if the file already exists), but it is also possible to reuse
199 # an externally-created file.  In the latter case, you should ensure that
200 # the new image file has the same contents as the current one; QEMU cannot
201 # perform any meaningful check.  Typically this is achieved by using the
202 # current image file as the backing file for the new image.
204 # On failure, the original disks pre-snapshot attempt will be used.
206 # For internal snapshots, the dictionary contains the device and the
207 # snapshot's name.  If an internal snapshot matching name already exists,
208 # the request will be rejected.  Only some image formats support it, for
209 # example, qcow2, and rbd,
211 # On failure, qemu will try delete the newly created internal snapshot in the
212 # transaction.  When an I/O error occurs during deletion, the user needs to fix
213 # it later with qemu-img or other command.
215 # @actions: List of @TransactionAction;
216 #           information needed for the respective operations.
218 # @properties: structure of additional options to control the
219 #              execution of the transaction. See @TransactionProperties
220 #              for additional detail.
222 # Returns: nothing on success
224 #          Errors depend on the operations of the transaction
226 # Note: The transaction aborts on the first failure.  Therefore, there will be
227 #       information on only one failed operation returned in an error condition, and
228 #       subsequent actions will not have been attempted.
230 # Since: 1.1
232 # Example:
234 # -> { "execute": "transaction",
235 #      "arguments": { "actions": [
236 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
237 #                                      "snapshot-file": "/some/place/my-image",
238 #                                      "format": "qcow2" } },
239 #          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
240 #                                      "snapshot-file": "/some/place/my-image2",
241 #                                      "snapshot-node-name": "node3432",
242 #                                      "mode": "existing",
243 #                                      "format": "qcow2" } },
244 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
245 #                                      "snapshot-file": "/some/place/my-image2",
246 #                                      "mode": "existing",
247 #                                      "format": "qcow2" } },
248 #          { "type": "blockdev-snapshot-internal-sync", "data" : {
249 #                                      "device": "ide-hd2",
250 #                                      "name": "snapshot0" } } ] } }
251 # <- { "return": {} }
254 { 'command': 'transaction',
255   'data': { 'actions': [ 'TransactionAction' ],
256             '*properties': 'TransactionProperties'
257           }