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 # @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 }