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