Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 1 | # -*- Mode: Python -*- |
Andrea Bolognani | f7160f3 | 2020-07-29 20:50:24 +0200 | [diff] [blame] | 2 | # vim: filetype=python |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 3 | # |
| 4 | |
| 5 | ## |
| 6 | # = Transactions |
| 7 | ## |
| 8 | |
Kevin Wolf | 2af282e | 2020-02-24 15:30:08 +0100 | [diff] [blame] | 9 | { 'include': 'block-core.json' } |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 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 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 30 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 35 | # |
| 36 | # Since: 2.5 |
| 37 | ## |
| 38 | { 'enum': 'ActionCompletionMode', |
| 39 | 'data': [ 'individual', 'grouped' ] } |
| 40 | |
| 41 | ## |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 42 | # @TransactionActionKind: |
| 43 | # |
| 44 | # @abort: Since 1.6 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 45 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 46 | # @block-dirty-bitmap-add: Since 2.5 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 47 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 48 | # @block-dirty-bitmap-remove: Since 4.2 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 49 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 50 | # @block-dirty-bitmap-clear: Since 2.5 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 51 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 52 | # @block-dirty-bitmap-enable: Since 4.0 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 53 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 54 | # @block-dirty-bitmap-disable: Since 4.0 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 55 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 56 | # @block-dirty-bitmap-merge: Since 4.0 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 57 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 58 | # @blockdev-backup: Since 2.3 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 59 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 60 | # @blockdev-snapshot: Since 2.5 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 61 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 62 | # @blockdev-snapshot-internal-sync: Since 1.7 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 63 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 64 | # @blockdev-snapshot-sync: since 1.1 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 65 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 66 | # @drive-backup: Since 1.6 |
| 67 | # |
Vladimir Sementsov-Ogievskiy | 1084159 | 2021-11-04 09:58:11 +0100 | [diff] [blame] | 68 | # Features: |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 69 | # |
Vladimir Sementsov-Ogievskiy | 1084159 | 2021-11-04 09:58:11 +0100 | [diff] [blame] | 70 | # @deprecated: Member @drive-backup is deprecated. Use member |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 71 | # @blockdev-backup instead. |
Vladimir Sementsov-Ogievskiy | 1084159 | 2021-11-04 09:58:11 +0100 | [diff] [blame] | 72 | # |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 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', |
Vladimir Sementsov-Ogievskiy | 1084159 | 2021-11-04 09:58:11 +0100 | [diff] [blame] | 81 | { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] } |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 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 | ## |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 156 | # @TransactionAction: |
| 157 | # |
| 158 | # A discriminated record of operations that can be performed with |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 159 | # @transaction. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 160 | # |
Markus Armbruster | 89a2273 | 2024-02-05 08:47:09 +0100 | [diff] [blame] | 161 | # @type: the operation to be performed |
| 162 | # |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 163 | # Since: 1.1 |
| 164 | ## |
| 165 | { 'union': 'TransactionAction', |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 166 | 'base': { 'type': 'TransactionActionKind' }, |
| 167 | 'discriminator': 'type', |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 168 | 'data': { |
Markus Armbruster | 277b51f | 2021-09-17 16:31:21 +0200 | [diff] [blame] | 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' |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 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 |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 189 | # Actions will complete or fail as a group. See |
| 190 | # @ActionCompletionMode for details. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 191 | # |
| 192 | # Since: 2.5 |
| 193 | ## |
| 194 | { 'struct': 'TransactionProperties', |
| 195 | 'data': { |
| 196 | '*completion-mode': 'ActionCompletionMode' |
| 197 | } |
| 198 | } |
| 199 | |
| 200 | ## |
| 201 | # @transaction: |
| 202 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 206 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 210 | # |
| 211 | # Each new snapshot defaults to being created by QEMU (wiping any |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 218 | # |
| 219 | # On failure, the original disks pre-snapshot attempt will be used. |
| 220 | # |
Markus Armbruster | 09ec851 | 2021-05-01 09:57:47 +0200 | [diff] [blame] | 221 | # For internal snapshots, the dictionary contains the device and the |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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, |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 225 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 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. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 229 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 230 | # @actions: List of @TransactionAction; information needed for the |
| 231 | # respective operations. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 232 | # |
| 233 | # @properties: structure of additional options to control the |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 234 | # execution of the transaction. See @TransactionProperties for |
| 235 | # additional detail. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 236 | # |
Markus Armbruster | 2746f06 | 2024-02-27 12:39:12 +0100 | [diff] [blame] | 237 | # Errors: |
John Snow | b32a6b6 | 2024-06-26 18:21:15 -0400 | [diff] [blame] | 238 | # - Any errors from commands in the transaction |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 239 | # |
John Snow | d461c27 | 2024-06-26 18:21:16 -0400 | [diff] [blame] | 240 | # .. note:: The transaction aborts on the first failure. Therefore, |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 241 | # there will be information on only one failed operation returned |
| 242 | # in an error condition, and subsequent actions will not have been |
John Snow | d461c27 | 2024-06-26 18:21:16 -0400 | [diff] [blame] | 243 | # attempted. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 244 | # |
| 245 | # Since: 1.1 |
| 246 | # |
John Snow | 14b48aa | 2024-07-16 22:13:08 -0400 | [diff] [blame] | 247 | # .. qmp-example:: |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 248 | # |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 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": {} } |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 267 | ## |
| 268 | { 'command': 'transaction', |
| 269 | 'data': { 'actions': [ 'TransactionAction' ], |
| 270 | '*properties': 'TransactionProperties' |
| 271 | } |
| 272 | } |