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