]>
Commit | Line | Data |
---|---|---|
fa988e39 | 1 | # -*- Mode: Python -*- |
f7160f32 | 2 | # vim: filetype=python |
fa988e39 MA |
3 | # |
4 | ||
5 | ## | |
6 | # = Transactions | |
7 | ## | |
8 | ||
2af282ec | 9 | { 'include': 'block-core.json' } |
fa988e39 MA |
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 | # | |
a937b6aa MA |
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. | |
fa988e39 | 30 | # |
a937b6aa MA |
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. | |
fa988e39 MA |
35 | # |
36 | # Since: 2.5 | |
37 | ## | |
38 | { 'enum': 'ActionCompletionMode', | |
39 | 'data': [ 'individual', 'grouped' ] } | |
40 | ||
277b51fc MA |
41 | ## |
42 | # @TransactionActionKind: | |
43 | # | |
44 | # @abort: Since 1.6 | |
a937b6aa | 45 | # |
277b51fc | 46 | # @block-dirty-bitmap-add: Since 2.5 |
a937b6aa | 47 | # |
277b51fc | 48 | # @block-dirty-bitmap-remove: Since 4.2 |
a937b6aa | 49 | # |
277b51fc | 50 | # @block-dirty-bitmap-clear: Since 2.5 |
a937b6aa | 51 | # |
277b51fc | 52 | # @block-dirty-bitmap-enable: Since 4.0 |
a937b6aa | 53 | # |
277b51fc | 54 | # @block-dirty-bitmap-disable: Since 4.0 |
a937b6aa | 55 | # |
277b51fc | 56 | # @block-dirty-bitmap-merge: Since 4.0 |
a937b6aa | 57 | # |
277b51fc | 58 | # @blockdev-backup: Since 2.3 |
a937b6aa | 59 | # |
277b51fc | 60 | # @blockdev-snapshot: Since 2.5 |
a937b6aa | 61 | # |
277b51fc | 62 | # @blockdev-snapshot-internal-sync: Since 1.7 |
a937b6aa | 63 | # |
277b51fc | 64 | # @blockdev-snapshot-sync: since 1.1 |
a937b6aa | 65 | # |
277b51fc MA |
66 | # @drive-backup: Since 1.6 |
67 | # | |
1084159b | 68 | # Features: |
a937b6aa | 69 | # |
1084159b | 70 | # @deprecated: Member @drive-backup is deprecated. Use member |
a937b6aa | 71 | # @blockdev-backup instead. |
1084159b | 72 | # |
277b51fc MA |
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', | |
1084159b | 81 | { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] } |
277b51fc MA |
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 | ||
fa988e39 MA |
155 | ## |
156 | # @TransactionAction: | |
157 | # | |
158 | # A discriminated record of operations that can be performed with | |
277b51fc | 159 | # @transaction. |
fa988e39 MA |
160 | # |
161 | # Since: 1.1 | |
162 | ## | |
163 | { 'union': 'TransactionAction', | |
277b51fc MA |
164 | 'base': { 'type': 'TransactionActionKind' }, |
165 | 'discriminator': 'type', | |
fa988e39 | 166 | 'data': { |
277b51fc MA |
167 | 'abort': 'AbortWrapper', |
168 | 'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper', | |
169 | 'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper', | |
170 | 'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper', | |
171 | 'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper', | |
172 | 'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper', | |
173 | 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper', | |
174 | 'blockdev-backup': 'BlockdevBackupWrapper', | |
175 | 'blockdev-snapshot': 'BlockdevSnapshotWrapper', | |
176 | 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper', | |
177 | 'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper', | |
178 | 'drive-backup': 'DriveBackupWrapper' | |
fa988e39 MA |
179 | } } |
180 | ||
181 | ## | |
182 | # @TransactionProperties: | |
183 | # | |
184 | # Optional arguments to modify the behavior of a Transaction. | |
185 | # | |
186 | # @completion-mode: Controls how jobs launched asynchronously by | |
a937b6aa MA |
187 | # Actions will complete or fail as a group. See |
188 | # @ActionCompletionMode for details. | |
fa988e39 MA |
189 | # |
190 | # Since: 2.5 | |
191 | ## | |
192 | { 'struct': 'TransactionProperties', | |
193 | 'data': { | |
194 | '*completion-mode': 'ActionCompletionMode' | |
195 | } | |
196 | } | |
197 | ||
198 | ## | |
199 | # @transaction: | |
200 | # | |
a937b6aa MA |
201 | # Executes a number of transactionable QMP commands atomically. If |
202 | # any operation fails, then the entire set of actions will be | |
203 | # abandoned and the appropriate error returned. | |
fa988e39 | 204 | # |
a937b6aa MA |
205 | # For external snapshots, the dictionary contains the device, the file |
206 | # to use for the new snapshot, and the format. The default format, if | |
207 | # not specified, is qcow2. | |
fa988e39 MA |
208 | # |
209 | # Each new snapshot defaults to being created by QEMU (wiping any | |
a937b6aa MA |
210 | # contents if the file already exists), but it is also possible to |
211 | # reuse an externally-created file. In the latter case, you should | |
212 | # ensure that the new image file has the same contents as the current | |
213 | # one; QEMU cannot perform any meaningful check. Typically this is | |
214 | # achieved by using the current image file as the backing file for the | |
215 | # new image. | |
fa988e39 MA |
216 | # |
217 | # On failure, the original disks pre-snapshot attempt will be used. | |
218 | # | |
09ec8517 | 219 | # For internal snapshots, the dictionary contains the device and the |
a937b6aa MA |
220 | # snapshot's name. If an internal snapshot matching name already |
221 | # exists, the request will be rejected. Only some image formats | |
222 | # support it, for example, qcow2, and rbd, | |
fa988e39 | 223 | # |
a937b6aa MA |
224 | # On failure, qemu will try delete the newly created internal snapshot |
225 | # in the transaction. When an I/O error occurs during deletion, the | |
226 | # user needs to fix it later with qemu-img or other command. | |
fa988e39 | 227 | # |
a937b6aa MA |
228 | # @actions: List of @TransactionAction; information needed for the |
229 | # respective operations. | |
fa988e39 MA |
230 | # |
231 | # @properties: structure of additional options to control the | |
a937b6aa MA |
232 | # execution of the transaction. See @TransactionProperties for |
233 | # additional detail. | |
fa988e39 MA |
234 | # |
235 | # Returns: nothing on success | |
236 | # | |
a937b6aa | 237 | # Errors depend on the operations of the transaction |
fa988e39 | 238 | # |
a937b6aa MA |
239 | # Note: The transaction aborts on the first failure. Therefore, there |
240 | # will be information on only one failed operation returned in an | |
241 | # error condition, and subsequent actions will not have been | |
242 | # attempted. | |
fa988e39 MA |
243 | # |
244 | # Since: 1.1 | |
245 | # | |
246 | # Example: | |
247 | # | |
248 | # -> { "execute": "transaction", | |
249 | # "arguments": { "actions": [ | |
250 | # { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", | |
251 | # "snapshot-file": "/some/place/my-image", | |
252 | # "format": "qcow2" } }, | |
253 | # { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", | |
254 | # "snapshot-file": "/some/place/my-image2", | |
255 | # "snapshot-node-name": "node3432", | |
256 | # "mode": "existing", | |
257 | # "format": "qcow2" } }, | |
258 | # { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", | |
259 | # "snapshot-file": "/some/place/my-image2", | |
260 | # "mode": "existing", | |
261 | # "format": "qcow2" } }, | |
262 | # { "type": "blockdev-snapshot-internal-sync", "data" : { | |
263 | # "device": "ide-hd2", | |
264 | # "name": "snapshot0" } } ] } } | |
265 | # <- { "return": {} } | |
fa988e39 MA |
266 | ## |
267 | { 'command': 'transaction', | |
268 | 'data': { 'actions': [ 'TransactionAction' ], | |
269 | '*properties': 'TransactionProperties' | |
270 | } | |
271 | } |