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 | # |
| 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 | # @TransactionAction: |
| 43 | # |
| 44 | # A discriminated record of operations that can be performed with |
| 45 | # @transaction. Action @type can be: |
| 46 | # |
| 47 | # - @abort: since 1.6 |
| 48 | # - @block-dirty-bitmap-add: since 2.5 |
John Snow | c4e4b0f | 2019-07-29 16:35:54 -0400 | [diff] [blame] | 49 | # - @block-dirty-bitmap-remove: since 4.2 |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 50 | # - @block-dirty-bitmap-clear: since 2.5 |
John Snow | 0e2b7f0 | 2018-12-21 04:35:22 -0500 | [diff] [blame] | 51 | # - @block-dirty-bitmap-enable: since 4.0 |
| 52 | # - @block-dirty-bitmap-disable: since 4.0 |
| 53 | # - @block-dirty-bitmap-merge: since 4.0 |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 54 | # - @blockdev-backup: since 2.3 |
| 55 | # - @blockdev-snapshot: since 2.5 |
| 56 | # - @blockdev-snapshot-internal-sync: since 1.7 |
| 57 | # - @blockdev-snapshot-sync: since 1.1 |
| 58 | # - @drive-backup: since 1.6 |
| 59 | # |
| 60 | # Since: 1.1 |
| 61 | ## |
| 62 | { 'union': 'TransactionAction', |
| 63 | 'data': { |
| 64 | 'abort': 'Abort', |
| 65 | 'block-dirty-bitmap-add': 'BlockDirtyBitmapAdd', |
John Snow | c4e4b0f | 2019-07-29 16:35:54 -0400 | [diff] [blame] | 66 | 'block-dirty-bitmap-remove': 'BlockDirtyBitmap', |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 67 | 'block-dirty-bitmap-clear': 'BlockDirtyBitmap', |
John Snow | 0e2b7f0 | 2018-12-21 04:35:22 -0500 | [diff] [blame] | 68 | 'block-dirty-bitmap-enable': 'BlockDirtyBitmap', |
| 69 | 'block-dirty-bitmap-disable': 'BlockDirtyBitmap', |
| 70 | 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMerge', |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 71 | 'blockdev-backup': 'BlockdevBackup', |
| 72 | 'blockdev-snapshot': 'BlockdevSnapshot', |
| 73 | 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternal', |
| 74 | 'blockdev-snapshot-sync': 'BlockdevSnapshotSync', |
| 75 | 'drive-backup': 'DriveBackup' |
| 76 | } } |
| 77 | |
| 78 | ## |
| 79 | # @TransactionProperties: |
| 80 | # |
| 81 | # Optional arguments to modify the behavior of a Transaction. |
| 82 | # |
| 83 | # @completion-mode: Controls how jobs launched asynchronously by |
| 84 | # Actions will complete or fail as a group. |
| 85 | # See @ActionCompletionMode for details. |
| 86 | # |
| 87 | # Since: 2.5 |
| 88 | ## |
| 89 | { 'struct': 'TransactionProperties', |
| 90 | 'data': { |
| 91 | '*completion-mode': 'ActionCompletionMode' |
| 92 | } |
| 93 | } |
| 94 | |
| 95 | ## |
| 96 | # @transaction: |
| 97 | # |
| 98 | # Executes a number of transactionable QMP commands atomically. If any |
| 99 | # operation fails, then the entire set of actions will be abandoned and the |
| 100 | # appropriate error returned. |
| 101 | # |
| 102 | # For external snapshots, the dictionary contains the device, the file to use for |
| 103 | # the new snapshot, and the format. The default format, if not specified, is |
| 104 | # qcow2. |
| 105 | # |
| 106 | # Each new snapshot defaults to being created by QEMU (wiping any |
| 107 | # contents if the file already exists), but it is also possible to reuse |
| 108 | # an externally-created file. In the latter case, you should ensure that |
| 109 | # the new image file has the same contents as the current one; QEMU cannot |
| 110 | # perform any meaningful check. Typically this is achieved by using the |
| 111 | # current image file as the backing file for the new image. |
| 112 | # |
| 113 | # On failure, the original disks pre-snapshot attempt will be used. |
| 114 | # |
Markus Armbruster | 09ec851 | 2021-05-01 09:57:47 +0200 | [diff] [blame] | 115 | # For internal snapshots, the dictionary contains the device and the |
| 116 | # snapshot's name. If an internal snapshot matching name already exists, |
| 117 | # the request will be rejected. Only some image formats support it, for |
| 118 | # example, qcow2, and rbd, |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 119 | # |
| 120 | # On failure, qemu will try delete the newly created internal snapshot in the |
| 121 | # transaction. When an I/O error occurs during deletion, the user needs to fix |
| 122 | # it later with qemu-img or other command. |
| 123 | # |
| 124 | # @actions: List of @TransactionAction; |
| 125 | # information needed for the respective operations. |
| 126 | # |
| 127 | # @properties: structure of additional options to control the |
| 128 | # execution of the transaction. See @TransactionProperties |
| 129 | # for additional detail. |
| 130 | # |
| 131 | # Returns: nothing on success |
| 132 | # |
| 133 | # Errors depend on the operations of the transaction |
| 134 | # |
| 135 | # Note: The transaction aborts on the first failure. Therefore, there will be |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 136 | # information on only one failed operation returned in an error condition, and |
| 137 | # subsequent actions will not have been attempted. |
Markus Armbruster | fa988e3 | 2017-08-24 21:14:02 +0200 | [diff] [blame] | 138 | # |
| 139 | # Since: 1.1 |
| 140 | # |
| 141 | # Example: |
| 142 | # |
| 143 | # -> { "execute": "transaction", |
| 144 | # "arguments": { "actions": [ |
| 145 | # { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", |
| 146 | # "snapshot-file": "/some/place/my-image", |
| 147 | # "format": "qcow2" } }, |
| 148 | # { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", |
| 149 | # "snapshot-file": "/some/place/my-image2", |
| 150 | # "snapshot-node-name": "node3432", |
| 151 | # "mode": "existing", |
| 152 | # "format": "qcow2" } }, |
| 153 | # { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", |
| 154 | # "snapshot-file": "/some/place/my-image2", |
| 155 | # "mode": "existing", |
| 156 | # "format": "qcow2" } }, |
| 157 | # { "type": "blockdev-snapshot-internal-sync", "data" : { |
| 158 | # "device": "ide-hd2", |
| 159 | # "name": "snapshot0" } } ] } } |
| 160 | # <- { "return": {} } |
| 161 | # |
| 162 | ## |
| 163 | { 'command': 'transaction', |
| 164 | 'data': { 'actions': [ 'TransactionAction' ], |
| 165 | '*properties': 'TransactionProperties' |
| 166 | } |
| 167 | } |