qemu/qapi/transaction.json
<<
>>
Prefs
   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 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.
  30#
  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.
  35#
  36# Since: 2.5
  37##
  38{ 'enum': 'ActionCompletionMode',
  39  'data': [ 'individual', 'grouped' ] }
  40
  41##
  42# @TransactionActionKind:
  43#
  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
  56#
  57# Features:
  58# @deprecated: Member @drive-backup is deprecated.  Use member
  59#              @blockdev-backup instead.
  60#
  61# Since: 1.1
  62##
  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' ] } ] }
  70
  71##
  72# @AbortWrapper:
  73#
  74# Since: 1.6
  75##
  76{ 'struct': 'AbortWrapper',
  77  'data': { 'data': 'Abort' } }
  78
  79##
  80# @BlockDirtyBitmapAddWrapper:
  81#
  82# Since: 2.5
  83##
  84{ 'struct': 'BlockDirtyBitmapAddWrapper',
  85  'data': { 'data': 'BlockDirtyBitmapAdd' } }
  86
  87##
  88# @BlockDirtyBitmapWrapper:
  89#
  90# Since: 2.5
  91##
  92{ 'struct': 'BlockDirtyBitmapWrapper',
  93  'data': { 'data': 'BlockDirtyBitmap' } }
  94
  95##
  96# @BlockDirtyBitmapMergeWrapper:
  97#
  98# Since: 4.0
  99##
 100{ 'struct': 'BlockDirtyBitmapMergeWrapper',
 101  'data': { 'data': 'BlockDirtyBitmapMerge' } }
 102
 103##
 104# @BlockdevBackupWrapper:
 105#
 106# Since: 2.3
 107##
 108{ 'struct': 'BlockdevBackupWrapper',
 109  'data': { 'data': 'BlockdevBackup' } }
 110
 111##
 112# @BlockdevSnapshotWrapper:
 113#
 114# Since: 2.5
 115##
 116{ 'struct': 'BlockdevSnapshotWrapper',
 117  'data': { 'data': 'BlockdevSnapshot' } }
 118
 119##
 120# @BlockdevSnapshotInternalWrapper:
 121#
 122# Since: 1.7
 123##
 124{ 'struct': 'BlockdevSnapshotInternalWrapper',
 125  'data': { 'data': 'BlockdevSnapshotInternal' } }
 126
 127##
 128# @BlockdevSnapshotSyncWrapper:
 129#
 130# Since: 1.1
 131##
 132{ 'struct': 'BlockdevSnapshotSyncWrapper',
 133  'data': { 'data': 'BlockdevSnapshotSync' } }
 134
 135##
 136# @DriveBackupWrapper:
 137#
 138# Since: 1.6
 139##
 140{ 'struct': 'DriveBackupWrapper',
 141  'data': { 'data': 'DriveBackup' } }
 142
 143##
 144# @TransactionAction:
 145#
 146# A discriminated record of operations that can be performed with
 147# @transaction.
 148#
 149# Since: 1.1
 150##
 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   } }
 168
 169##
 170# @TransactionProperties:
 171#
 172# Optional arguments to modify the behavior of a Transaction.
 173#
 174# @completion-mode: Controls how jobs launched asynchronously by
 175#                   Actions will complete or fail as a group.
 176#                   See @ActionCompletionMode for details.
 177#
 178# Since: 2.5
 179##
 180{ 'struct': 'TransactionProperties',
 181  'data': {
 182       '*completion-mode': 'ActionCompletionMode'
 183  }
 184}
 185
 186##
 187# @transaction:
 188#
 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.
 192#
 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.
 196#
 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.
 203#
 204# On failure, the original disks pre-snapshot attempt will be used.
 205#
 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,
 210#
 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.
 214#
 215# @actions: List of @TransactionAction;
 216#           information needed for the respective operations.
 217#
 218# @properties: structure of additional options to control the
 219#              execution of the transaction. See @TransactionProperties
 220#              for additional detail.
 221#
 222# Returns: nothing on success
 223#
 224#          Errors depend on the operations of the transaction
 225#
 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.
 229#
 230# Since: 1.1
 231#
 232# Example:
 233#
 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": {} }
 252#
 253##
 254{ 'command': 'transaction',
 255  'data': { 'actions': [ 'TransactionAction' ],
 256            '*properties': 'TransactionProperties'
 257          }
 258}
 259