| 1 | # -*- Mode: Python -*- |
| 2 | # vim: filetype=python |
| 3 | # |
| 4 | |
| 5 | ## |
| 6 | # ************ |
| 7 | # Transactions |
| 8 | # ************ |
| 9 | ## |
| 10 | |
| 11 | { 'include': 'block-core.json' } |
| 12 | |
| 13 | ## |
| 14 | # @Abort: |
| 15 | # |
| 16 | # This action can be used to test transaction failure. |
| 17 | # |
| 18 | # Since: 1.6 |
| 19 | ## |
| 20 | { 'struct': 'Abort', |
| 21 | 'data': { } } |
| 22 | |
| 23 | ## |
| 24 | # @ActionCompletionMode: |
| 25 | # |
| 26 | # An enumeration of transactional completion modes. |
| 27 | # |
| 28 | # @individual: Do not attempt to cancel any other Actions if any |
| 29 | # Actions fail after the Transaction request succeeds. All |
| 30 | # Actions that can complete successfully will do so without |
| 31 | # waiting on others. This is the default. |
| 32 | # |
| 33 | # @grouped: If any Action fails after the Transaction succeeds, cancel |
| 34 | # all Actions. Actions do not complete until all Actions are |
| 35 | # ready to complete. May be rejected by Actions that do not |
| 36 | # support this completion mode. |
| 37 | # |
| 38 | # Since: 2.5 |
| 39 | ## |
| 40 | { 'enum': 'ActionCompletionMode', |
| 41 | 'data': [ 'individual', 'grouped' ] } |
| 42 | |
| 43 | ## |
| 44 | # @TransactionActionKind: |
| 45 | # |
| 46 | # @abort: Since 1.6 |
| 47 | # |
| 48 | # @block-dirty-bitmap-add: Since 2.5 |
| 49 | # |
| 50 | # @block-dirty-bitmap-remove: Since 4.2 |
| 51 | # |
| 52 | # @block-dirty-bitmap-clear: Since 2.5 |
| 53 | # |
| 54 | # @block-dirty-bitmap-enable: Since 4.0 |
| 55 | # |
| 56 | # @block-dirty-bitmap-disable: Since 4.0 |
| 57 | # |
| 58 | # @block-dirty-bitmap-merge: Since 4.0 |
| 59 | # |
| 60 | # @blockdev-backup: Since 2.3 |
| 61 | # |
| 62 | # @blockdev-snapshot: Since 2.5 |
| 63 | # |
| 64 | # @blockdev-snapshot-internal-sync: Since 1.7 |
| 65 | # |
| 66 | # @blockdev-snapshot-sync: since 1.1 |
| 67 | # |
| 68 | # @drive-backup: Since 1.6 |
| 69 | # |
| 70 | # Features: |
| 71 | # |
| 72 | # @deprecated: Member `drive-backup` is deprecated. Use member |
| 73 | # `blockdev-backup` instead. |
| 74 | # |
| 75 | # Since: 1.1 |
| 76 | ## |
| 77 | { 'enum': 'TransactionActionKind', |
| 78 | 'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove', |
| 79 | 'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable', |
| 80 | 'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge', |
| 81 | 'blockdev-backup', 'blockdev-snapshot', |
| 82 | 'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync', |
| 83 | { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] } |
| 84 | |
| 85 | ## |
| 86 | # @AbortWrapper: |
| 87 | # |
| 88 | # Since: 1.6 |
| 89 | ## |
| 90 | { 'struct': 'AbortWrapper', |
| 91 | 'data': { 'data': 'Abort' } } |
| 92 | |
| 93 | ## |
| 94 | # @BlockDirtyBitmapAddWrapper: |
| 95 | # |
| 96 | # Since: 2.5 |
| 97 | ## |
| 98 | { 'struct': 'BlockDirtyBitmapAddWrapper', |
| 99 | 'data': { 'data': 'BlockDirtyBitmapAdd' } } |
| 100 | |
| 101 | ## |
| 102 | # @BlockDirtyBitmapWrapper: |
| 103 | # |
| 104 | # Since: 2.5 |
| 105 | ## |
| 106 | { 'struct': 'BlockDirtyBitmapWrapper', |
| 107 | 'data': { 'data': 'BlockDirtyBitmap' } } |
| 108 | |
| 109 | ## |
| 110 | # @BlockDirtyBitmapMergeWrapper: |
| 111 | # |
| 112 | # Since: 4.0 |
| 113 | ## |
| 114 | { 'struct': 'BlockDirtyBitmapMergeWrapper', |
| 115 | 'data': { 'data': 'BlockDirtyBitmapMerge' } } |
| 116 | |
| 117 | ## |
| 118 | # @BlockdevBackupWrapper: |
| 119 | # |
| 120 | # Since: 2.3 |
| 121 | ## |
| 122 | { 'struct': 'BlockdevBackupWrapper', |
| 123 | 'data': { 'data': 'BlockdevBackup' } } |
| 124 | |
| 125 | ## |
| 126 | # @BlockdevSnapshotWrapper: |
| 127 | # |
| 128 | # Since: 2.5 |
| 129 | ## |
| 130 | { 'struct': 'BlockdevSnapshotWrapper', |
| 131 | 'data': { 'data': 'BlockdevSnapshot' } } |
| 132 | |
| 133 | ## |
| 134 | # @BlockdevSnapshotInternalWrapper: |
| 135 | # |
| 136 | # Since: 1.7 |
| 137 | ## |
| 138 | { 'struct': 'BlockdevSnapshotInternalWrapper', |
| 139 | 'data': { 'data': 'BlockdevSnapshotInternal' } } |
| 140 | |
| 141 | ## |
| 142 | # @BlockdevSnapshotSyncWrapper: |
| 143 | # |
| 144 | # Since: 1.1 |
| 145 | ## |
| 146 | { 'struct': 'BlockdevSnapshotSyncWrapper', |
| 147 | 'data': { 'data': 'BlockdevSnapshotSync' } } |
| 148 | |
| 149 | ## |
| 150 | # @DriveBackupWrapper: |
| 151 | # |
| 152 | # Since: 1.6 |
| 153 | ## |
| 154 | { 'struct': 'DriveBackupWrapper', |
| 155 | 'data': { 'data': 'DriveBackup' } } |
| 156 | |
| 157 | ## |
| 158 | # @TransactionAction: |
| 159 | # |
| 160 | # A discriminated record of operations that can be performed with |
| 161 | # `transaction`. |
| 162 | # |
| 163 | # @type: the operation to be performed |
| 164 | # |
| 165 | # Since: 1.1 |
| 166 | ## |
| 167 | { 'union': 'TransactionAction', |
| 168 | 'base': { 'type': 'TransactionActionKind' }, |
| 169 | 'discriminator': 'type', |
| 170 | 'data': { |
| 171 | 'abort': 'AbortWrapper', |
| 172 | 'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper', |
| 173 | 'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper', |
| 174 | 'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper', |
| 175 | 'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper', |
| 176 | 'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper', |
| 177 | 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper', |
| 178 | 'blockdev-backup': 'BlockdevBackupWrapper', |
| 179 | 'blockdev-snapshot': 'BlockdevSnapshotWrapper', |
| 180 | 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper', |
| 181 | 'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper', |
| 182 | 'drive-backup': 'DriveBackupWrapper' |
| 183 | } } |
| 184 | |
| 185 | ## |
| 186 | # @TransactionProperties: |
| 187 | # |
| 188 | # Optional arguments to modify the behavior of a Transaction. |
| 189 | # |
| 190 | # @completion-mode: Controls how jobs launched asynchronously by |
| 191 | # Actions will complete or fail as a group. See |
| 192 | # `ActionCompletionMode` for details. |
| 193 | # |
| 194 | # Since: 2.5 |
| 195 | ## |
| 196 | { 'struct': 'TransactionProperties', |
| 197 | 'data': { |
| 198 | '*completion-mode': 'ActionCompletionMode' |
| 199 | } |
| 200 | } |
| 201 | |
| 202 | ## |
| 203 | # @transaction: |
| 204 | # |
| 205 | # Executes a number of transactionable QMP commands atomically. If |
| 206 | # any operation fails, then the entire set of actions will be |
| 207 | # abandoned and the appropriate error returned. |
| 208 | # |
| 209 | # For external snapshots, the dictionary contains the device, the file |
| 210 | # to use for the new snapshot, and the format. The default format, if |
| 211 | # not specified, is qcow2. |
| 212 | # |
| 213 | # Each new snapshot defaults to being created by QEMU (wiping any |
| 214 | # contents if the file already exists), but it is also possible to |
| 215 | # reuse an externally-created file. In the latter case, you should |
| 216 | # ensure that the new image file has the same contents as the current |
| 217 | # one; QEMU cannot perform any meaningful check. Typically this is |
| 218 | # achieved by using the current image file as the backing file for the |
| 219 | # new image. |
| 220 | # |
| 221 | # On failure, the original disks pre-snapshot attempt will be used. |
| 222 | # |
| 223 | # For internal snapshots, the dictionary contains the device and the |
| 224 | # snapshot's name. If an internal snapshot matching name already |
| 225 | # exists, the request will be rejected. Only some image formats |
| 226 | # support it, for example, qcow2, and rbd, |
| 227 | # |
| 228 | # On failure, QEMU will try delete the newly created internal snapshot |
| 229 | # in the transaction. When an I/O error occurs during deletion, the |
| 230 | # user needs to fix it later with qemu-img or other command. |
| 231 | # |
| 232 | # @actions: List of `TransactionAction`; information needed for the |
| 233 | # respective operations. |
| 234 | # |
| 235 | # @properties: structure of additional options to control the |
| 236 | # execution of the transaction. See `TransactionProperties` for |
| 237 | # additional detail. |
| 238 | # |
| 239 | # Errors: |
| 240 | # - Any errors from commands in the transaction |
| 241 | # |
| 242 | # .. note:: The transaction aborts on the first failure. Therefore, |
| 243 | # there will be information on only one failed operation returned |
| 244 | # in an error condition, and subsequent actions will not have been |
| 245 | # attempted. |
| 246 | # |
| 247 | # Since: 1.1 |
| 248 | # |
| 249 | # .. qmp-example:: |
| 250 | # |
| 251 | # -> { "execute": "transaction", |
| 252 | # "arguments": { "actions": [ |
| 253 | # { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", |
| 254 | # "snapshot-file": "/some/place/my-image", |
| 255 | # "format": "qcow2" } }, |
| 256 | # { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", |
| 257 | # "snapshot-file": "/some/place/my-image2", |
| 258 | # "snapshot-node-name": "node3432", |
| 259 | # "mode": "existing", |
| 260 | # "format": "qcow2" } }, |
| 261 | # { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", |
| 262 | # "snapshot-file": "/some/place/my-image2", |
| 263 | # "mode": "existing", |
| 264 | # "format": "qcow2" } }, |
| 265 | # { "type": "blockdev-snapshot-internal-sync", "data" : { |
| 266 | # "device": "ide-hd2", |
| 267 | # "name": "snapshot0" } } ] } } |
| 268 | # <- { "return": {} } |
| 269 | ## |
| 270 | { 'command': 'transaction', |
| 271 | 'data': { 'actions': [ 'TransactionAction' ], |
| 272 | '*properties': 'TransactionProperties' |
| 273 | } |
| 274 | } |