qapi/transaction.json

   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 # Since: 1.1
 162 ##
 163 { 'union': 'TransactionAction',
 164   'base': { 'type': 'TransactionActionKind' },
 165   'discriminator': 'type',
 166   'data': {
 167        'abort': 'AbortWrapper',
 168        'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper',
 169        'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper',
 170        'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper',
 171        'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper',
 172        'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper',
 173        'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper',
 174        'blockdev-backup': 'BlockdevBackupWrapper',
 175        'blockdev-snapshot': 'BlockdevSnapshotWrapper',
 176        'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper',
 177        'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper',
 178        'drive-backup': 'DriveBackupWrapper'
 179    } }
 180
 181 ##
 182 # @TransactionProperties:
 183 #
 184 # Optional arguments to modify the behavior of a Transaction.
 185 #
 186 # @completion-mode: Controls how jobs launched asynchronously by
 187 #     Actions will complete or fail as a group.  See
 188 #     @ActionCompletionMode for details.
 189 #
 190 # Since: 2.5
 191 ##
 192 { 'struct': 'TransactionProperties',
 193   'data': {
 194        '*completion-mode': 'ActionCompletionMode'
 195   }
 196 }
 197
 198 ##
 199 # @transaction:
 200 #
 201 # Executes a number of transactionable QMP commands atomically.  If
 202 # any operation fails, then the entire set of actions will be
 203 # abandoned and the appropriate error returned.
 204 #
 205 # For external snapshots, the dictionary contains the device, the file
 206 # to use for the new snapshot, and the format.  The default format, if
 207 # not specified, is qcow2.
 208 #
 209 # Each new snapshot defaults to being created by QEMU (wiping any
 210 # contents if the file already exists), but it is also possible to
 211 # reuse an externally-created file.  In the latter case, you should
 212 # ensure that the new image file has the same contents as the current
 213 # one; QEMU cannot perform any meaningful check.  Typically this is
 214 # achieved by using the current image file as the backing file for the
 215 # new image.
 216 #
 217 # On failure, the original disks pre-snapshot attempt will be used.
 218 #
 219 # For internal snapshots, the dictionary contains the device and the
 220 # snapshot's name.  If an internal snapshot matching name already
 221 # exists, the request will be rejected.  Only some image formats
 222 # support it, for example, qcow2, and rbd,
 223 #
 224 # On failure, qemu will try delete the newly created internal snapshot
 225 # in the transaction.  When an I/O error occurs during deletion, the
 226 # user needs to fix it later with qemu-img or other command.
 227 #
 228 # @actions: List of @TransactionAction; information needed for the
 229 #     respective operations.
 230 #
 231 # @properties: structure of additional options to control the
 232 #     execution of the transaction.  See @TransactionProperties for
 233 #     additional detail.
 234 #
 235 # Returns: nothing on success
 236 #
 237 #     Errors depend on the operations of the transaction
 238 #
 239 # Note: The transaction aborts on the first failure.  Therefore, there
 240 #     will be information on only one failed operation returned in an
 241 #     error condition, and subsequent actions will not have been
 242 #     attempted.
 243 #
 244 # Since: 1.1
 245 #
 246 # Example:
 247 #
 248 # -> { "execute": "transaction",
 249 #      "arguments": { "actions": [
 250 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
 251 #                                      "snapshot-file": "/some/place/my-image",
 252 #                                      "format": "qcow2" } },
 253 #          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
 254 #                                      "snapshot-file": "/some/place/my-image2",
 255 #                                      "snapshot-node-name": "node3432",
 256 #                                      "mode": "existing",
 257 #                                      "format": "qcow2" } },
 258 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
 259 #                                      "snapshot-file": "/some/place/my-image2",
 260 #                                      "mode": "existing",
 261 #                                      "format": "qcow2" } },
 262 #          { "type": "blockdev-snapshot-internal-sync", "data" : {
 263 #                                      "device": "ide-hd2",
 264 #                                      "name": "snapshot0" } } ] } }
 265 # <- { "return": {} }
 266 ##
 267 { 'command': 'transaction',
 268   'data': { 'actions': [ 'TransactionAction' ],
 269             '*properties': 'TransactionProperties'
 270           }
 271 }