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 # Since: 1.1
  58 ##
  59 { 'enum': 'TransactionActionKind',
  60   'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove',
  61             'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable',
  62             'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge',
  63             'blockdev-backup', 'blockdev-snapshot',
  64             'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync',
  65             'drive-backup' ] }
  66
  67 ##
  68 # @AbortWrapper:
  69 #
  70 # Since: 1.6
  71 ##
  72 { 'struct': 'AbortWrapper',
  73   'data': { 'data': 'Abort' } }
  74
  75 ##
  76 # @BlockDirtyBitmapAddWrapper:
  77 #
  78 # Since: 2.5
  79 ##
  80 { 'struct': 'BlockDirtyBitmapAddWrapper',
  81   'data': { 'data': 'BlockDirtyBitmapAdd' } }
  82
  83 ##
  84 # @BlockDirtyBitmapWrapper:
  85 #
  86 # Since: 2.5
  87 ##
  88 { 'struct': 'BlockDirtyBitmapWrapper',
  89   'data': { 'data': 'BlockDirtyBitmap' } }
  90
  91 ##
  92 # @BlockDirtyBitmapMergeWrapper:
  93 #
  94 # Since: 4.0
  95 ##
  96 { 'struct': 'BlockDirtyBitmapMergeWrapper',
  97   'data': { 'data': 'BlockDirtyBitmapMerge' } }
  98
  99 ##
 100 # @BlockdevBackupWrapper:
 101 #
 102 # Since: 2.3
 103 ##
 104 { 'struct': 'BlockdevBackupWrapper',
 105   'data': { 'data': 'BlockdevBackup' } }
 106
 107 ##
 108 # @BlockdevSnapshotWrapper:
 109 #
 110 # Since: 2.5
 111 ##
 112 { 'struct': 'BlockdevSnapshotWrapper',
 113   'data': { 'data': 'BlockdevSnapshot' } }
 114
 115 ##
 116 # @BlockdevSnapshotInternalWrapper:
 117 #
 118 # Since: 1.7
 119 ##
 120 { 'struct': 'BlockdevSnapshotInternalWrapper',
 121   'data': { 'data': 'BlockdevSnapshotInternal' } }
 122
 123 ##
 124 # @BlockdevSnapshotSyncWrapper:
 125 #
 126 # Since: 1.1
 127 ##
 128 { 'struct': 'BlockdevSnapshotSyncWrapper',
 129   'data': { 'data': 'BlockdevSnapshotSync' } }
 130
 131 ##
 132 # @DriveBackupWrapper:
 133 #
 134 # Since: 1.6
 135 ##
 136 { 'struct': 'DriveBackupWrapper',
 137   'data': { 'data': 'DriveBackup' } }
 138
 139 ##
 140 # @TransactionAction:
 141 #
 142 # A discriminated record of operations that can be performed with
 143 # @transaction.
 144 #
 145 # Since: 1.1
 146 ##
 147 { 'union': 'TransactionAction',
 148   'base': { 'type': 'TransactionActionKind' },
 149   'discriminator': 'type',
 150   'data': {
 151        'abort': 'AbortWrapper',
 152        'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper',
 153        'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper',
 154        'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper',
 155        'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper',
 156        'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper',
 157        'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper',
 158        'blockdev-backup': 'BlockdevBackupWrapper',
 159        'blockdev-snapshot': 'BlockdevSnapshotWrapper',
 160        'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper',
 161        'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper',
 162        'drive-backup': 'DriveBackupWrapper'
 163    } }
 164
 165 ##
 166 # @TransactionProperties:
 167 #
 168 # Optional arguments to modify the behavior of a Transaction.
 169 #
 170 # @completion-mode: Controls how jobs launched asynchronously by
 171 #                   Actions will complete or fail as a group.
 172 #                   See @ActionCompletionMode for details.
 173 #
 174 # Since: 2.5
 175 ##
 176 { 'struct': 'TransactionProperties',
 177   'data': {
 178        '*completion-mode': 'ActionCompletionMode'
 179   }
 180 }
 181
 182 ##
 183 # @transaction:
 184 #
 185 # Executes a number of transactionable QMP commands atomically. If any
 186 # operation fails, then the entire set of actions will be abandoned and the
 187 # appropriate error returned.
 188 #
 189 # For external snapshots, the dictionary contains the device, the file to use for
 190 # the new snapshot, and the format.  The default format, if not specified, is
 191 # qcow2.
 192 #
 193 # Each new snapshot defaults to being created by QEMU (wiping any
 194 # contents if the file already exists), but it is also possible to reuse
 195 # an externally-created file.  In the latter case, you should ensure that
 196 # the new image file has the same contents as the current one; QEMU cannot
 197 # perform any meaningful check.  Typically this is achieved by using the
 198 # current image file as the backing file for the new image.
 199 #
 200 # On failure, the original disks pre-snapshot attempt will be used.
 201 #
 202 # For internal snapshots, the dictionary contains the device and the
 203 # snapshot's name.  If an internal snapshot matching name already exists,
 204 # the request will be rejected.  Only some image formats support it, for
 205 # example, qcow2, and rbd,
 206 #
 207 # On failure, qemu will try delete the newly created internal snapshot in the
 208 # transaction.  When an I/O error occurs during deletion, the user needs to fix
 209 # it later with qemu-img or other command.
 210 #
 211 # @actions: List of @TransactionAction;
 212 #           information needed for the respective operations.
 213 #
 214 # @properties: structure of additional options to control the
 215 #              execution of the transaction. See @TransactionProperties
 216 #              for additional detail.
 217 #
 218 # Returns: nothing on success
 219 #
 220 #          Errors depend on the operations of the transaction
 221 #
 222 # Note: The transaction aborts on the first failure.  Therefore, there will be
 223 #       information on only one failed operation returned in an error condition, and
 224 #       subsequent actions will not have been attempted.
 225 #
 226 # Since: 1.1
 227 #
 228 # Example:
 229 #
 230 # -> { "execute": "transaction",
 231 #      "arguments": { "actions": [
 232 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
 233 #                                      "snapshot-file": "/some/place/my-image",
 234 #                                      "format": "qcow2" } },
 235 #          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
 236 #                                      "snapshot-file": "/some/place/my-image2",
 237 #                                      "snapshot-node-name": "node3432",
 238 #                                      "mode": "existing",
 239 #                                      "format": "qcow2" } },
 240 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
 241 #                                      "snapshot-file": "/some/place/my-image2",
 242 #                                      "mode": "existing",
 243 #                                      "format": "qcow2" } },
 244 #          { "type": "blockdev-snapshot-internal-sync", "data" : {
 245 #                                      "device": "ide-hd2",
 246 #                                      "name": "snapshot0" } } ] } }
 247 # <- { "return": {} }
 248 #
 249 ##
 250 { 'command': 'transaction',
 251   'data': { 'actions': [ 'TransactionAction' ],
 252             '*properties': 'TransactionProperties'
 253           }
 254 }