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