Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2021-09-25-v2' into staging
[qemu.git] / qapi / block-core.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3
4 ##
5 # == Block core (VM unrelated)
6 ##
7
8 { 'include': 'common.json' }
9 { 'include': 'crypto.json' }
10 { 'include': 'job.json' }
11 { 'include': 'sockets.json' }
12
13 ##
14 # @SnapshotInfo:
15 #
16 # @id: unique snapshot id
17 #
18 # @name: user chosen name
19 #
20 # @vm-state-size: size of the VM state
21 #
22 # @date-sec: UTC date of the snapshot in seconds
23 #
24 # @date-nsec: fractional part in nano seconds to be used with date-sec
25 #
26 # @vm-clock-sec: VM clock relative to boot in seconds
27 #
28 # @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec
29 #
30 # @icount: Current instruction count. Appears when execution record/replay
31 #          is enabled. Used for "time-traveling" to match the moment
32 #          in the recorded execution with the snapshots. This counter may
33 #          be obtained through @query-replay command (since 5.2)
34 #
35 # Since: 1.3
36 #
37 ##
38 { 'struct': 'SnapshotInfo',
39   'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int',
40             'date-sec': 'int', 'date-nsec': 'int',
41             'vm-clock-sec': 'int', 'vm-clock-nsec': 'int',
42             '*icount': 'int' } }
43
44 ##
45 # @ImageInfoSpecificQCow2EncryptionBase:
46 #
47 # @format: The encryption format
48 #
49 # Since: 2.10
50 ##
51 { 'struct': 'ImageInfoSpecificQCow2EncryptionBase',
52   'data': { 'format': 'BlockdevQcow2EncryptionFormat'}}
53
54 ##
55 # @ImageInfoSpecificQCow2Encryption:
56 #
57 # Since: 2.10
58 ##
59 { 'union': 'ImageInfoSpecificQCow2Encryption',
60   'base': 'ImageInfoSpecificQCow2EncryptionBase',
61   'discriminator': 'format',
62   'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
63
64 ##
65 # @ImageInfoSpecificQCow2:
66 #
67 # @compat: compatibility level
68 #
69 # @data-file: the filename of the external data file that is stored in the
70 #             image and used as a default for opening the image (since: 4.0)
71 #
72 # @data-file-raw: True if the external data file must stay valid as a
73 #                 standalone (read-only) raw image without looking at qcow2
74 #                 metadata (since: 4.0)
75 #
76 # @extended-l2: true if the image has extended L2 entries; only valid for
77 #               compat >= 1.1 (since 5.2)
78 #
79 # @lazy-refcounts: on or off; only valid for compat >= 1.1
80 #
81 # @corrupt: true if the image has been marked corrupt; only valid for
82 #           compat >= 1.1 (since 2.2)
83 #
84 # @refcount-bits: width of a refcount entry in bits (since 2.3)
85 #
86 # @encrypt: details about encryption parameters; only set if image
87 #           is encrypted (since 2.10)
88 #
89 # @bitmaps: A list of qcow2 bitmap details (since 4.0)
90 #
91 # @compression-type: the image cluster compression method (since 5.1)
92 #
93 # Since: 1.7
94 ##
95 { 'struct': 'ImageInfoSpecificQCow2',
96   'data': {
97       'compat': 'str',
98       '*data-file': 'str',
99       '*data-file-raw': 'bool',
100       '*extended-l2': 'bool',
101       '*lazy-refcounts': 'bool',
102       '*corrupt': 'bool',
103       'refcount-bits': 'int',
104       '*encrypt': 'ImageInfoSpecificQCow2Encryption',
105       '*bitmaps': ['Qcow2BitmapInfo'],
106       'compression-type': 'Qcow2CompressionType'
107   } }
108
109 ##
110 # @ImageInfoSpecificVmdk:
111 #
112 # @create-type: The create type of VMDK image
113 #
114 # @cid: Content id of image
115 #
116 # @parent-cid: Parent VMDK image's cid
117 #
118 # @extents: List of extent files
119 #
120 # Since: 1.7
121 ##
122 { 'struct': 'ImageInfoSpecificVmdk',
123   'data': {
124       'create-type': 'str',
125       'cid': 'int',
126       'parent-cid': 'int',
127       'extents': ['ImageInfo']
128   } }
129
130 ##
131 # @ImageInfoSpecific:
132 #
133 # A discriminated record of image format specific information structures.
134 #
135 # Since: 1.7
136 ##
137 { 'union': 'ImageInfoSpecific',
138   'data': {
139       'qcow2': 'ImageInfoSpecificQCow2',
140       'vmdk': 'ImageInfoSpecificVmdk',
141       # If we need to add block driver specific parameters for
142       # LUKS in future, then we'll subclass QCryptoBlockInfoLUKS
143       # to define a ImageInfoSpecificLUKS
144       'luks': 'QCryptoBlockInfoLUKS'
145   } }
146
147 ##
148 # @ImageInfo:
149 #
150 # Information about a QEMU image file
151 #
152 # @filename: name of the image file
153 #
154 # @format: format of the image file
155 #
156 # @virtual-size: maximum capacity in bytes of the image
157 #
158 # @actual-size: actual size on disk in bytes of the image
159 #
160 # @dirty-flag: true if image is not cleanly closed
161 #
162 # @cluster-size: size of a cluster in bytes
163 #
164 # @encrypted: true if the image is encrypted
165 #
166 # @compressed: true if the image is compressed (Since 1.7)
167 #
168 # @backing-filename: name of the backing file
169 #
170 # @full-backing-filename: full path of the backing file
171 #
172 # @backing-filename-format: the format of the backing file
173 #
174 # @snapshots: list of VM snapshots
175 #
176 # @backing-image: info of the backing image (since 1.6)
177 #
178 # @format-specific: structure supplying additional format-specific
179 #                   information (since 1.7)
180 #
181 # Since: 1.3
182 #
183 ##
184 { 'struct': 'ImageInfo',
185   'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool',
186            '*actual-size': 'int', 'virtual-size': 'int',
187            '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool',
188            '*backing-filename': 'str', '*full-backing-filename': 'str',
189            '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'],
190            '*backing-image': 'ImageInfo',
191            '*format-specific': 'ImageInfoSpecific' } }
192
193 ##
194 # @ImageCheck:
195 #
196 # Information about a QEMU image file check
197 #
198 # @filename: name of the image file checked
199 #
200 # @format: format of the image file checked
201 #
202 # @check-errors: number of unexpected errors occurred during check
203 #
204 # @image-end-offset: offset (in bytes) where the image ends, this
205 #                    field is present if the driver for the image format
206 #                    supports it
207 #
208 # @corruptions: number of corruptions found during the check if any
209 #
210 # @leaks: number of leaks found during the check if any
211 #
212 # @corruptions-fixed: number of corruptions fixed during the check
213 #                     if any
214 #
215 # @leaks-fixed: number of leaks fixed during the check if any
216 #
217 # @total-clusters: total number of clusters, this field is present
218 #                  if the driver for the image format supports it
219 #
220 # @allocated-clusters: total number of allocated clusters, this
221 #                      field is present if the driver for the image format
222 #                      supports it
223 #
224 # @fragmented-clusters: total number of fragmented clusters, this
225 #                       field is present if the driver for the image format
226 #                       supports it
227 #
228 # @compressed-clusters: total number of compressed clusters, this
229 #                       field is present if the driver for the image format
230 #                       supports it
231 #
232 # Since: 1.4
233 #
234 ##
235 { 'struct': 'ImageCheck',
236   'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int',
237            '*image-end-offset': 'int', '*corruptions': 'int', '*leaks': 'int',
238            '*corruptions-fixed': 'int', '*leaks-fixed': 'int',
239            '*total-clusters': 'int', '*allocated-clusters': 'int',
240            '*fragmented-clusters': 'int', '*compressed-clusters': 'int' } }
241
242 ##
243 # @MapEntry:
244 #
245 # Mapping information from a virtual block range to a host file range
246 #
247 # @start: virtual (guest) offset of the first byte described by this
248 #         entry
249 #
250 # @length: the number of bytes of the mapped virtual range
251 #
252 # @data: reading the image will actually read data from a file (in
253 #        particular, if @offset is present this means that the sectors
254 #        are not simply preallocated, but contain actual data in raw
255 #        format)
256 #
257 # @zero: whether the virtual blocks read as zeroes
258 #
259 # @depth: number of layers (0 = top image, 1 = top image's backing
260 #         file, ..., n - 1 = bottom image (where n is the number of
261 #         images in the chain)) before reaching one for which the
262 #         range is allocated
263 #
264 # @offset: if present, the image file stores the data for this range
265 #          in raw format at the given (host) offset
266 #
267 # @filename: filename that is referred to by @offset
268 #
269 # Since: 2.6
270 #
271 ##
272 { 'struct': 'MapEntry',
273   'data': {'start': 'int', 'length': 'int', 'data': 'bool',
274            'zero': 'bool', 'depth': 'int', '*offset': 'int',
275            '*filename': 'str' } }
276
277 ##
278 # @BlockdevCacheInfo:
279 #
280 # Cache mode information for a block device
281 #
282 # @writeback:   true if writeback mode is enabled
283 # @direct:      true if the host page cache is bypassed (O_DIRECT)
284 # @no-flush:    true if flush requests are ignored for the device
285 #
286 # Since: 2.3
287 ##
288 { 'struct': 'BlockdevCacheInfo',
289   'data': { 'writeback': 'bool',
290             'direct': 'bool',
291             'no-flush': 'bool' } }
292
293 ##
294 # @BlockDeviceInfo:
295 #
296 # Information about the backing device for a block device.
297 #
298 # @file: the filename of the backing device
299 #
300 # @node-name: the name of the block driver node (Since 2.0)
301 #
302 # @ro: true if the backing device was open read-only
303 #
304 # @drv: the name of the block format used to open the backing device. As of
305 #       0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
306 #       'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
307 #       'http', 'https', 'luks', 'nbd', 'parallels', 'qcow',
308 #       'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat'
309 #       2.2: 'archipelago' added, 'cow' dropped
310 #       2.3: 'host_floppy' deprecated
311 #       2.5: 'host_floppy' dropped
312 #       2.6: 'luks' added
313 #       2.8: 'replication' added, 'tftp' dropped
314 #       2.9: 'archipelago' dropped
315 #
316 # @backing_file: the name of the backing file (for copy-on-write)
317 #
318 # @backing_file_depth: number of files in the backing file chain (since: 1.2)
319 #
320 # @encrypted: true if the backing device is encrypted
321 #
322 # @detect_zeroes: detect and optimize zero writes (Since 2.1)
323 #
324 # @bps: total throughput limit in bytes per second is specified
325 #
326 # @bps_rd: read throughput limit in bytes per second is specified
327 #
328 # @bps_wr: write throughput limit in bytes per second is specified
329 #
330 # @iops: total I/O operations per second is specified
331 #
332 # @iops_rd: read I/O operations per second is specified
333 #
334 # @iops_wr: write I/O operations per second is specified
335 #
336 # @image: the info of image used (since: 1.6)
337 #
338 # @bps_max: total throughput limit during bursts,
339 #                     in bytes (Since 1.7)
340 #
341 # @bps_rd_max: read throughput limit during bursts,
342 #                        in bytes (Since 1.7)
343 #
344 # @bps_wr_max: write throughput limit during bursts,
345 #                        in bytes (Since 1.7)
346 #
347 # @iops_max: total I/O operations per second during bursts,
348 #                      in bytes (Since 1.7)
349 #
350 # @iops_rd_max: read I/O operations per second during bursts,
351 #                         in bytes (Since 1.7)
352 #
353 # @iops_wr_max: write I/O operations per second during bursts,
354 #                         in bytes (Since 1.7)
355 #
356 # @bps_max_length: maximum length of the @bps_max burst
357 #                            period, in seconds. (Since 2.6)
358 #
359 # @bps_rd_max_length: maximum length of the @bps_rd_max
360 #                               burst period, in seconds. (Since 2.6)
361 #
362 # @bps_wr_max_length: maximum length of the @bps_wr_max
363 #                               burst period, in seconds. (Since 2.6)
364 #
365 # @iops_max_length: maximum length of the @iops burst
366 #                             period, in seconds. (Since 2.6)
367 #
368 # @iops_rd_max_length: maximum length of the @iops_rd_max
369 #                                burst period, in seconds. (Since 2.6)
370 #
371 # @iops_wr_max_length: maximum length of the @iops_wr_max
372 #                                burst period, in seconds. (Since 2.6)
373 #
374 # @iops_size: an I/O size in bytes (Since 1.7)
375 #
376 # @group: throttle group name (Since 2.4)
377 #
378 # @cache: the cache mode used for the block device (since: 2.3)
379 #
380 # @write_threshold: configured write threshold for the device.
381 #                   0 if disabled. (Since 2.3)
382 #
383 # @dirty-bitmaps: dirty bitmaps information (only present if node
384 #                 has one or more dirty bitmaps) (Since 4.2)
385 #
386 # Since: 0.14
387 #
388 ##
389 { 'struct': 'BlockDeviceInfo',
390   'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str',
391             '*backing_file': 'str', 'backing_file_depth': 'int',
392             'encrypted': 'bool',
393             'detect_zeroes': 'BlockdevDetectZeroesOptions',
394             'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
395             'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
396             'image': 'ImageInfo',
397             '*bps_max': 'int', '*bps_rd_max': 'int',
398             '*bps_wr_max': 'int', '*iops_max': 'int',
399             '*iops_rd_max': 'int', '*iops_wr_max': 'int',
400             '*bps_max_length': 'int', '*bps_rd_max_length': 'int',
401             '*bps_wr_max_length': 'int', '*iops_max_length': 'int',
402             '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int',
403             '*iops_size': 'int', '*group': 'str', 'cache': 'BlockdevCacheInfo',
404             'write_threshold': 'int', '*dirty-bitmaps': ['BlockDirtyInfo'] } }
405
406 ##
407 # @BlockDeviceIoStatus:
408 #
409 # An enumeration of block device I/O status.
410 #
411 # @ok: The last I/O operation has succeeded
412 #
413 # @failed: The last I/O operation has failed
414 #
415 # @nospace: The last I/O operation has failed due to a no-space condition
416 #
417 # Since: 1.0
418 ##
419 { 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
420
421 ##
422 # @BlockDirtyInfo:
423 #
424 # Block dirty bitmap information.
425 #
426 # @name: the name of the dirty bitmap (Since 2.4)
427 #
428 # @count: number of dirty bytes according to the dirty bitmap
429 #
430 # @granularity: granularity of the dirty bitmap in bytes (since 1.4)
431 #
432 # @recording: true if the bitmap is recording new writes from the guest.
433 #             Replaces `active` and `disabled` statuses. (since 4.0)
434 #
435 # @busy: true if the bitmap is in-use by some operation (NBD or jobs)
436 #        and cannot be modified via QMP or used by another operation.
437 #        Replaces `locked` and `frozen` statuses. (since 4.0)
438 #
439 # @persistent: true if the bitmap was stored on disk, is scheduled to be stored
440 #              on disk, or both. (since 4.0)
441 #
442 # @inconsistent: true if this is a persistent bitmap that was improperly
443 #                stored. Implies @persistent to be true; @recording and
444 #                @busy to be false. This bitmap cannot be used. To remove
445 #                it, use @block-dirty-bitmap-remove. (Since 4.0)
446 #
447 # Since: 1.3
448 ##
449 { 'struct': 'BlockDirtyInfo',
450   'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32',
451            'recording': 'bool', 'busy': 'bool',
452            'persistent': 'bool', '*inconsistent': 'bool' } }
453
454 ##
455 # @Qcow2BitmapInfoFlags:
456 #
457 # An enumeration of flags that a bitmap can report to the user.
458 #
459 # @in-use: This flag is set by any process actively modifying the qcow2 file,
460 #          and cleared when the updated bitmap is flushed to the qcow2 image.
461 #          The presence of this flag in an offline image means that the bitmap
462 #          was not saved correctly after its last usage, and may contain
463 #          inconsistent data.
464 #
465 # @auto: The bitmap must reflect all changes of the virtual disk by any
466 #        application that would write to this qcow2 file.
467 #
468 # Since: 4.0
469 ##
470 { 'enum': 'Qcow2BitmapInfoFlags',
471   'data': ['in-use', 'auto'] }
472
473 ##
474 # @Qcow2BitmapInfo:
475 #
476 # Qcow2 bitmap information.
477 #
478 # @name: the name of the bitmap
479 #
480 # @granularity: granularity of the bitmap in bytes
481 #
482 # @flags: flags of the bitmap
483 #
484 # Since: 4.0
485 ##
486 { 'struct': 'Qcow2BitmapInfo',
487   'data': {'name': 'str', 'granularity': 'uint32',
488            'flags': ['Qcow2BitmapInfoFlags'] } }
489
490 ##
491 # @BlockLatencyHistogramInfo:
492 #
493 # Block latency histogram.
494 #
495 # @boundaries: list of interval boundary values in nanoseconds, all greater
496 #              than zero and in ascending order.
497 #              For example, the list [10, 50, 100] produces the following
498 #              histogram intervals: [0, 10), [10, 50), [50, 100), [100, +inf).
499 #
500 # @bins: list of io request counts corresponding to histogram intervals.
501 #        len(@bins) = len(@boundaries) + 1
502 #        For the example above, @bins may be something like [3, 1, 5, 2],
503 #        and corresponding histogram looks like:
504 #
505 # ::
506 #
507 #        5|           *
508 #        4|           *
509 #        3| *         *
510 #        2| *         *    *
511 #        1| *    *    *    *
512 #         +------------------
513 #             10   50   100
514 #
515 # Since: 4.0
516 ##
517 { 'struct': 'BlockLatencyHistogramInfo',
518   'data': {'boundaries': ['uint64'], 'bins': ['uint64'] } }
519
520 ##
521 # @BlockInfo:
522 #
523 # Block device information.  This structure describes a virtual device and
524 # the backing device associated with it.
525 #
526 # @device: The device name associated with the virtual device.
527 #
528 # @qdev: The qdev ID, or if no ID is assigned, the QOM path of the block
529 #        device. (since 2.10)
530 #
531 # @type: This field is returned only for compatibility reasons, it should
532 #        not be used (always returns 'unknown')
533 #
534 # @removable: True if the device supports removable media.
535 #
536 # @locked: True if the guest has locked this device from having its media
537 #          removed
538 #
539 # @tray_open: True if the device's tray is open
540 #             (only present if it has a tray)
541 #
542 # @io-status: @BlockDeviceIoStatus. Only present if the device
543 #             supports it and the VM is configured to stop on errors
544 #             (supported device models: virtio-blk, IDE, SCSI except
545 #             scsi-generic)
546 #
547 # @inserted: @BlockDeviceInfo describing the device if media is
548 #            present
549 #
550 # Since:  0.14
551 ##
552 { 'struct': 'BlockInfo',
553   'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool',
554            'locked': 'bool', '*inserted': 'BlockDeviceInfo',
555            '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus' } }
556
557 ##
558 # @BlockMeasureInfo:
559 #
560 # Image file size calculation information.  This structure describes the size
561 # requirements for creating a new image file.
562 #
563 # The size requirements depend on the new image file format.  File size always
564 # equals virtual disk size for the 'raw' format, even for sparse POSIX files.
565 # Compact formats such as 'qcow2' represent unallocated and zero regions
566 # efficiently so file size may be smaller than virtual disk size.
567 #
568 # The values are upper bounds that are guaranteed to fit the new image file.
569 # Subsequent modification, such as internal snapshot or further bitmap
570 # creation, may require additional space and is not covered here.
571 #
572 # @required: Size required for a new image file, in bytes, when copying just
573 #            allocated guest-visible contents.
574 #
575 # @fully-allocated: Image file size, in bytes, once data has been written
576 #                   to all sectors, when copying just guest-visible contents.
577 #
578 # @bitmaps: Additional size required if all the top-level bitmap metadata
579 #           in the source image were to be copied to the destination,
580 #           present only when source and destination both support
581 #           persistent bitmaps. (since 5.1)
582 #
583 # Since: 2.10
584 ##
585 { 'struct': 'BlockMeasureInfo',
586   'data': {'required': 'int', 'fully-allocated': 'int', '*bitmaps': 'int'} }
587
588 ##
589 # @query-block:
590 #
591 # Get a list of BlockInfo for all virtual block devices.
592 #
593 # Returns: a list of @BlockInfo describing each virtual block device. Filter
594 #          nodes that were created implicitly are skipped over.
595 #
596 # Since: 0.14
597 #
598 # Example:
599 #
600 # -> { "execute": "query-block" }
601 # <- {
602 #       "return":[
603 #          {
604 #             "io-status": "ok",
605 #             "device":"ide0-hd0",
606 #             "locked":false,
607 #             "removable":false,
608 #             "inserted":{
609 #                "ro":false,
610 #                "drv":"qcow2",
611 #                "encrypted":false,
612 #                "file":"disks/test.qcow2",
613 #                "backing_file_depth":1,
614 #                "bps":1000000,
615 #                "bps_rd":0,
616 #                "bps_wr":0,
617 #                "iops":1000000,
618 #                "iops_rd":0,
619 #                "iops_wr":0,
620 #                "bps_max": 8000000,
621 #                "bps_rd_max": 0,
622 #                "bps_wr_max": 0,
623 #                "iops_max": 0,
624 #                "iops_rd_max": 0,
625 #                "iops_wr_max": 0,
626 #                "iops_size": 0,
627 #                "detect_zeroes": "on",
628 #                "write_threshold": 0,
629 #                "image":{
630 #                   "filename":"disks/test.qcow2",
631 #                   "format":"qcow2",
632 #                   "virtual-size":2048000,
633 #                   "backing_file":"base.qcow2",
634 #                   "full-backing-filename":"disks/base.qcow2",
635 #                   "backing-filename-format":"qcow2",
636 #                   "snapshots":[
637 #                      {
638 #                         "id": "1",
639 #                         "name": "snapshot1",
640 #                         "vm-state-size": 0,
641 #                         "date-sec": 10000200,
642 #                         "date-nsec": 12,
643 #                         "vm-clock-sec": 206,
644 #                         "vm-clock-nsec": 30
645 #                      }
646 #                   ],
647 #                   "backing-image":{
648 #                       "filename":"disks/base.qcow2",
649 #                       "format":"qcow2",
650 #                       "virtual-size":2048000
651 #                   }
652 #                }
653 #             },
654 #             "qdev": "ide_disk",
655 #             "type":"unknown"
656 #          },
657 #          {
658 #             "io-status": "ok",
659 #             "device":"ide1-cd0",
660 #             "locked":false,
661 #             "removable":true,
662 #             "qdev": "/machine/unattached/device[23]",
663 #             "tray_open": false,
664 #             "type":"unknown"
665 #          },
666 #          {
667 #             "device":"floppy0",
668 #             "locked":false,
669 #             "removable":true,
670 #             "qdev": "/machine/unattached/device[20]",
671 #             "type":"unknown"
672 #          },
673 #          {
674 #             "device":"sd0",
675 #             "locked":false,
676 #             "removable":true,
677 #             "type":"unknown"
678 #          }
679 #       ]
680 #    }
681 #
682 ##
683 { 'command': 'query-block', 'returns': ['BlockInfo'] }
684
685
686 ##
687 # @BlockDeviceTimedStats:
688 #
689 # Statistics of a block device during a given interval of time.
690 #
691 # @interval_length: Interval used for calculating the statistics,
692 #                   in seconds.
693 #
694 # @min_rd_latency_ns: Minimum latency of read operations in the
695 #                     defined interval, in nanoseconds.
696 #
697 # @min_wr_latency_ns: Minimum latency of write operations in the
698 #                     defined interval, in nanoseconds.
699 #
700 # @min_flush_latency_ns: Minimum latency of flush operations in the
701 #                        defined interval, in nanoseconds.
702 #
703 # @max_rd_latency_ns: Maximum latency of read operations in the
704 #                     defined interval, in nanoseconds.
705 #
706 # @max_wr_latency_ns: Maximum latency of write operations in the
707 #                     defined interval, in nanoseconds.
708 #
709 # @max_flush_latency_ns: Maximum latency of flush operations in the
710 #                        defined interval, in nanoseconds.
711 #
712 # @avg_rd_latency_ns: Average latency of read operations in the
713 #                     defined interval, in nanoseconds.
714 #
715 # @avg_wr_latency_ns: Average latency of write operations in the
716 #                     defined interval, in nanoseconds.
717 #
718 # @avg_flush_latency_ns: Average latency of flush operations in the
719 #                        defined interval, in nanoseconds.
720 #
721 # @avg_rd_queue_depth: Average number of pending read operations
722 #                      in the defined interval.
723 #
724 # @avg_wr_queue_depth: Average number of pending write operations
725 #                      in the defined interval.
726 #
727 # Since: 2.5
728 ##
729 { 'struct': 'BlockDeviceTimedStats',
730   'data': { 'interval_length': 'int', 'min_rd_latency_ns': 'int',
731             'max_rd_latency_ns': 'int', 'avg_rd_latency_ns': 'int',
732             'min_wr_latency_ns': 'int', 'max_wr_latency_ns': 'int',
733             'avg_wr_latency_ns': 'int', 'min_flush_latency_ns': 'int',
734             'max_flush_latency_ns': 'int', 'avg_flush_latency_ns': 'int',
735             'avg_rd_queue_depth': 'number', 'avg_wr_queue_depth': 'number' } }
736
737 ##
738 # @BlockDeviceStats:
739 #
740 # Statistics of a virtual block device or a block backing device.
741 #
742 # @rd_bytes:      The number of bytes read by the device.
743 #
744 # @wr_bytes:      The number of bytes written by the device.
745 #
746 # @unmap_bytes: The number of bytes unmapped by the device (Since 4.2)
747 #
748 # @rd_operations: The number of read operations performed by the device.
749 #
750 # @wr_operations: The number of write operations performed by the device.
751 #
752 # @flush_operations: The number of cache flush operations performed by the
753 #                    device (since 0.15)
754 #
755 # @unmap_operations: The number of unmap operations performed by the device
756 #                    (Since 4.2)
757 #
758 # @rd_total_time_ns: Total time spent on reads in nanoseconds (since 0.15).
759 #
760 # @wr_total_time_ns: Total time spent on writes in nanoseconds (since 0.15).
761 #
762 # @flush_total_time_ns: Total time spent on cache flushes in nanoseconds
763 #                       (since 0.15).
764 #
765 # @unmap_total_time_ns: Total time spent on unmap operations in nanoseconds
766 #                       (Since 4.2)
767 #
768 # @wr_highest_offset: The offset after the greatest byte written to the
769 #                     device.  The intended use of this information is for
770 #                     growable sparse files (like qcow2) that are used on top
771 #                     of a physical device.
772 #
773 # @rd_merged: Number of read requests that have been merged into another
774 #             request (Since 2.3).
775 #
776 # @wr_merged: Number of write requests that have been merged into another
777 #             request (Since 2.3).
778 #
779 # @unmap_merged: Number of unmap requests that have been merged into another
780 #                request (Since 4.2)
781 #
782 # @idle_time_ns: Time since the last I/O operation, in
783 #                nanoseconds. If the field is absent it means that
784 #                there haven't been any operations yet (Since 2.5).
785 #
786 # @failed_rd_operations: The number of failed read operations
787 #                        performed by the device (Since 2.5)
788 #
789 # @failed_wr_operations: The number of failed write operations
790 #                        performed by the device (Since 2.5)
791 #
792 # @failed_flush_operations: The number of failed flush operations
793 #                           performed by the device (Since 2.5)
794 #
795 # @failed_unmap_operations: The number of failed unmap operations performed
796 #                           by the device (Since 4.2)
797 #
798 # @invalid_rd_operations: The number of invalid read operations
799 #                          performed by the device (Since 2.5)
800 #
801 # @invalid_wr_operations: The number of invalid write operations
802 #                         performed by the device (Since 2.5)
803 #
804 # @invalid_flush_operations: The number of invalid flush operations
805 #                            performed by the device (Since 2.5)
806 #
807 # @invalid_unmap_operations: The number of invalid unmap operations performed
808 #                            by the device (Since 4.2)
809 #
810 # @account_invalid: Whether invalid operations are included in the
811 #                   last access statistics (Since 2.5)
812 #
813 # @account_failed: Whether failed operations are included in the
814 #                  latency and last access statistics (Since 2.5)
815 #
816 # @timed_stats: Statistics specific to the set of previously defined
817 #               intervals of time (Since 2.5)
818 #
819 # @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
820 #
821 # @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
822 #
823 # @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
824 #
825 # Since: 0.14
826 ##
827 { 'struct': 'BlockDeviceStats',
828   'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'unmap_bytes' : 'int',
829            'rd_operations': 'int', 'wr_operations': 'int',
830            'flush_operations': 'int', 'unmap_operations': 'int',
831            'rd_total_time_ns': 'int', 'wr_total_time_ns': 'int',
832            'flush_total_time_ns': 'int', 'unmap_total_time_ns': 'int',
833            'wr_highest_offset': 'int',
834            'rd_merged': 'int', 'wr_merged': 'int', 'unmap_merged': 'int',
835            '*idle_time_ns': 'int',
836            'failed_rd_operations': 'int', 'failed_wr_operations': 'int',
837            'failed_flush_operations': 'int', 'failed_unmap_operations': 'int',
838            'invalid_rd_operations': 'int', 'invalid_wr_operations': 'int',
839            'invalid_flush_operations': 'int', 'invalid_unmap_operations': 'int',
840            'account_invalid': 'bool', 'account_failed': 'bool',
841            'timed_stats': ['BlockDeviceTimedStats'],
842            '*rd_latency_histogram': 'BlockLatencyHistogramInfo',
843            '*wr_latency_histogram': 'BlockLatencyHistogramInfo',
844            '*flush_latency_histogram': 'BlockLatencyHistogramInfo' } }
845
846 ##
847 # @BlockStatsSpecificFile:
848 #
849 # File driver statistics
850 #
851 # @discard-nb-ok: The number of successful discard operations performed by
852 #                 the driver.
853 #
854 # @discard-nb-failed: The number of failed discard operations performed by
855 #                     the driver.
856 #
857 # @discard-bytes-ok: The number of bytes discarded by the driver.
858 #
859 # Since: 4.2
860 ##
861 { 'struct': 'BlockStatsSpecificFile',
862   'data': {
863       'discard-nb-ok': 'uint64',
864       'discard-nb-failed': 'uint64',
865       'discard-bytes-ok': 'uint64' } }
866
867 ##
868 # @BlockStatsSpecificNvme:
869 #
870 # NVMe driver statistics
871 #
872 # @completion-errors: The number of completion errors.
873 #
874 # @aligned-accesses: The number of aligned accesses performed by
875 #                    the driver.
876 #
877 # @unaligned-accesses: The number of unaligned accesses performed by
878 #                      the driver.
879 #
880 # Since: 5.2
881 ##
882 { 'struct': 'BlockStatsSpecificNvme',
883   'data': {
884       'completion-errors': 'uint64',
885       'aligned-accesses': 'uint64',
886       'unaligned-accesses': 'uint64' } }
887
888 ##
889 # @BlockStatsSpecific:
890 #
891 # Block driver specific statistics
892 #
893 # Since: 4.2
894 ##
895 { 'union': 'BlockStatsSpecific',
896   'base': { 'driver': 'BlockdevDriver' },
897   'discriminator': 'driver',
898   'data': {
899       'file': 'BlockStatsSpecificFile',
900       'host_device': 'BlockStatsSpecificFile',
901       'nvme': 'BlockStatsSpecificNvme' } }
902
903 ##
904 # @BlockStats:
905 #
906 # Statistics of a virtual block device or a block backing device.
907 #
908 # @device: If the stats are for a virtual block device, the name
909 #          corresponding to the virtual block device.
910 #
911 # @node-name: The node name of the device. (Since 2.3)
912 #
913 # @qdev: The qdev ID, or if no ID is assigned, the QOM path of the block
914 #        device. (since 3.0)
915 #
916 # @stats:  A @BlockDeviceStats for the device.
917 #
918 # @driver-specific: Optional driver-specific stats. (Since 4.2)
919 #
920 # @parent: This describes the file block device if it has one.
921 #          Contains recursively the statistics of the underlying
922 #          protocol (e.g. the host file for a qcow2 image). If there is
923 #          no underlying protocol, this field is omitted
924 #
925 # @backing: This describes the backing block device if it has one.
926 #           (Since 2.0)
927 #
928 # Since: 0.14
929 ##
930 { 'struct': 'BlockStats',
931   'data': {'*device': 'str', '*qdev': 'str', '*node-name': 'str',
932            'stats': 'BlockDeviceStats',
933            '*driver-specific': 'BlockStatsSpecific',
934            '*parent': 'BlockStats',
935            '*backing': 'BlockStats'} }
936
937 ##
938 # @query-blockstats:
939 #
940 # Query the @BlockStats for all virtual block devices.
941 #
942 # @query-nodes: If true, the command will query all the block nodes
943 #               that have a node name, in a list which will include "parent"
944 #               information, but not "backing".
945 #               If false or omitted, the behavior is as before - query all the
946 #               device backends, recursively including their "parent" and
947 #               "backing". Filter nodes that were created implicitly are
948 #               skipped over in this mode. (Since 2.3)
949 #
950 # Returns: A list of @BlockStats for each virtual block devices.
951 #
952 # Since: 0.14
953 #
954 # Example:
955 #
956 # -> { "execute": "query-blockstats" }
957 # <- {
958 #       "return":[
959 #          {
960 #             "device":"ide0-hd0",
961 #             "parent":{
962 #                "stats":{
963 #                   "wr_highest_offset":3686448128,
964 #                   "wr_bytes":9786368,
965 #                   "wr_operations":751,
966 #                   "rd_bytes":122567168,
967 #                   "rd_operations":36772
968 #                   "wr_total_times_ns":313253456
969 #                   "rd_total_times_ns":3465673657
970 #                   "flush_total_times_ns":49653
971 #                   "flush_operations":61,
972 #                   "rd_merged":0,
973 #                   "wr_merged":0,
974 #                   "idle_time_ns":2953431879,
975 #                   "account_invalid":true,
976 #                   "account_failed":false
977 #                }
978 #             },
979 #             "stats":{
980 #                "wr_highest_offset":2821110784,
981 #                "wr_bytes":9786368,
982 #                "wr_operations":692,
983 #                "rd_bytes":122739200,
984 #                "rd_operations":36604
985 #                "flush_operations":51,
986 #                "wr_total_times_ns":313253456
987 #                "rd_total_times_ns":3465673657
988 #                "flush_total_times_ns":49653,
989 #                "rd_merged":0,
990 #                "wr_merged":0,
991 #                "idle_time_ns":2953431879,
992 #                "account_invalid":true,
993 #                "account_failed":false
994 #             },
995 #             "qdev": "/machine/unattached/device[23]"
996 #          },
997 #          {
998 #             "device":"ide1-cd0",
999 #             "stats":{
1000 #                "wr_highest_offset":0,
1001 #                "wr_bytes":0,
1002 #                "wr_operations":0,
1003 #                "rd_bytes":0,
1004 #                "rd_operations":0
1005 #                "flush_operations":0,
1006 #                "wr_total_times_ns":0
1007 #                "rd_total_times_ns":0
1008 #                "flush_total_times_ns":0,
1009 #                "rd_merged":0,
1010 #                "wr_merged":0,
1011 #                "account_invalid":false,
1012 #                "account_failed":false
1013 #             },
1014 #             "qdev": "/machine/unattached/device[24]"
1015 #          },
1016 #          {
1017 #             "device":"floppy0",
1018 #             "stats":{
1019 #                "wr_highest_offset":0,
1020 #                "wr_bytes":0,
1021 #                "wr_operations":0,
1022 #                "rd_bytes":0,
1023 #                "rd_operations":0
1024 #                "flush_operations":0,
1025 #                "wr_total_times_ns":0
1026 #                "rd_total_times_ns":0
1027 #                "flush_total_times_ns":0,
1028 #                "rd_merged":0,
1029 #                "wr_merged":0,
1030 #                "account_invalid":false,
1031 #                "account_failed":false
1032 #             },
1033 #             "qdev": "/machine/unattached/device[16]"
1034 #          },
1035 #          {
1036 #             "device":"sd0",
1037 #             "stats":{
1038 #                "wr_highest_offset":0,
1039 #                "wr_bytes":0,
1040 #                "wr_operations":0,
1041 #                "rd_bytes":0,
1042 #                "rd_operations":0
1043 #                "flush_operations":0,
1044 #                "wr_total_times_ns":0
1045 #                "rd_total_times_ns":0
1046 #                "flush_total_times_ns":0,
1047 #                "rd_merged":0,
1048 #                "wr_merged":0,
1049 #                "account_invalid":false,
1050 #                "account_failed":false
1051 #             }
1052 #          }
1053 #       ]
1054 #    }
1055 #
1056 ##
1057 { 'command': 'query-blockstats',
1058   'data': { '*query-nodes': 'bool' },
1059   'returns': ['BlockStats'] }
1060
1061 ##
1062 # @BlockdevOnError:
1063 #
1064 # An enumeration of possible behaviors for errors on I/O operations.
1065 # The exact meaning depends on whether the I/O was initiated by a guest
1066 # or by a block job
1067 #
1068 # @report: for guest operations, report the error to the guest;
1069 #          for jobs, cancel the job
1070 #
1071 # @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
1072 #          or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
1073 #          the failing request later and may still complete successfully. The
1074 #          stream block job continues to stream and will complete with an
1075 #          error.
1076 #
1077 # @enospc: same as @stop on ENOSPC, same as @report otherwise.
1078 #
1079 # @stop: for guest operations, stop the virtual machine;
1080 #        for jobs, pause the job
1081 #
1082 # @auto: inherit the error handling policy of the backend (since: 2.7)
1083 #
1084 # Since: 1.3
1085 ##
1086 { 'enum': 'BlockdevOnError',
1087   'data': ['report', 'ignore', 'enospc', 'stop', 'auto'] }
1088
1089 ##
1090 # @MirrorSyncMode:
1091 #
1092 # An enumeration of possible behaviors for the initial synchronization
1093 # phase of storage mirroring.
1094 #
1095 # @top: copies data in the topmost image to the destination
1096 #
1097 # @full: copies data from all images to the destination
1098 #
1099 # @none: only copy data written from now on
1100 #
1101 # @incremental: only copy data described by the dirty bitmap. (since: 2.4)
1102 #
1103 # @bitmap: only copy data described by the dirty bitmap. (since: 4.2)
1104 #          Behavior on completion is determined by the BitmapSyncMode.
1105 #
1106 # Since: 1.3
1107 ##
1108 { 'enum': 'MirrorSyncMode',
1109   'data': ['top', 'full', 'none', 'incremental', 'bitmap'] }
1110
1111 ##
1112 # @BitmapSyncMode:
1113 #
1114 # An enumeration of possible behaviors for the synchronization of a bitmap
1115 # when used for data copy operations.
1116 #
1117 # @on-success: The bitmap is only synced when the operation is successful.
1118 #              This is the behavior always used for 'INCREMENTAL' backups.
1119 #
1120 # @never: The bitmap is never synchronized with the operation, and is
1121 #         treated solely as a read-only manifest of blocks to copy.
1122 #
1123 # @always: The bitmap is always synchronized with the operation,
1124 #          regardless of whether or not the operation was successful.
1125 #
1126 # Since: 4.2
1127 ##
1128 { 'enum': 'BitmapSyncMode',
1129   'data': ['on-success', 'never', 'always'] }
1130
1131 ##
1132 # @MirrorCopyMode:
1133 #
1134 # An enumeration whose values tell the mirror block job when to
1135 # trigger writes to the target.
1136 #
1137 # @background: copy data in background only.
1138 #
1139 # @write-blocking: when data is written to the source, write it
1140 #                  (synchronously) to the target as well.  In
1141 #                  addition, data is copied in background just like in
1142 #                  @background mode.
1143 #
1144 # Since: 3.0
1145 ##
1146 { 'enum': 'MirrorCopyMode',
1147   'data': ['background', 'write-blocking'] }
1148
1149 ##
1150 # @BlockJobInfo:
1151 #
1152 # Information about a long-running block device operation.
1153 #
1154 # @type: the job type ('stream' for image streaming)
1155 #
1156 # @device: The job identifier. Originally the device name but other
1157 #          values are allowed since QEMU 2.7
1158 #
1159 # @len: Estimated @offset value at the completion of the job. This value can
1160 #       arbitrarily change while the job is running, in both directions.
1161 #
1162 # @offset: Progress made until now. The unit is arbitrary and the value can
1163 #          only meaningfully be used for the ratio of @offset to @len. The
1164 #          value is monotonically increasing.
1165 #
1166 # @busy: false if the job is known to be in a quiescent state, with
1167 #        no pending I/O.  Since 1.3.
1168 #
1169 # @paused: whether the job is paused or, if @busy is true, will
1170 #          pause itself as soon as possible.  Since 1.3.
1171 #
1172 # @speed: the rate limit, bytes per second
1173 #
1174 # @io-status: the status of the job (since 1.3)
1175 #
1176 # @ready: true if the job may be completed (since 2.2)
1177 #
1178 # @status: Current job state/status (since 2.12)
1179 #
1180 # @auto-finalize: Job will finalize itself when PENDING, moving to
1181 #                 the CONCLUDED state. (since 2.12)
1182 #
1183 # @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the NULL
1184 #                state and disappearing from the query list. (since 2.12)
1185 #
1186 # @error: Error information if the job did not complete successfully.
1187 #         Not set if the job completed successfully. (since 2.12.1)
1188 #
1189 # Since: 1.1
1190 ##
1191 { 'struct': 'BlockJobInfo',
1192   'data': {'type': 'str', 'device': 'str', 'len': 'int',
1193            'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int',
1194            'io-status': 'BlockDeviceIoStatus', 'ready': 'bool',
1195            'status': 'JobStatus',
1196            'auto-finalize': 'bool', 'auto-dismiss': 'bool',
1197            '*error': 'str' } }
1198
1199 ##
1200 # @query-block-jobs:
1201 #
1202 # Return information about long-running block device operations.
1203 #
1204 # Returns: a list of @BlockJobInfo for each active block job
1205 #
1206 # Since: 1.1
1207 ##
1208 { 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] }
1209
1210 ##
1211 # @block_resize:
1212 #
1213 # Resize a block image while a guest is running.
1214 #
1215 # Either @device or @node-name must be set but not both.
1216 #
1217 # @device: the name of the device to get the image resized
1218 #
1219 # @node-name: graph node name to get the image resized (Since 2.0)
1220 #
1221 # @size:  new image size in bytes
1222 #
1223 # Returns: - nothing on success
1224 #          - If @device is not a valid block device, DeviceNotFound
1225 #
1226 # Since: 0.14
1227 #
1228 # Example:
1229 #
1230 # -> { "execute": "block_resize",
1231 #      "arguments": { "device": "scratch", "size": 1073741824 } }
1232 # <- { "return": {} }
1233 #
1234 ##
1235 { 'command': 'block_resize',
1236   'data': { '*device': 'str',
1237             '*node-name': 'str',
1238             'size': 'int' },
1239   'coroutine': true }
1240
1241 ##
1242 # @NewImageMode:
1243 #
1244 # An enumeration that tells QEMU how to set the backing file path in
1245 # a new image file.
1246 #
1247 # @existing: QEMU should look for an existing image file.
1248 #
1249 # @absolute-paths: QEMU should create a new image with absolute paths
1250 #                  for the backing file. If there is no backing file available, the new
1251 #                  image will not be backed either.
1252 #
1253 # Since: 1.1
1254 ##
1255 { 'enum': 'NewImageMode',
1256   'data': [ 'existing', 'absolute-paths' ] }
1257
1258 ##
1259 # @BlockdevSnapshotSync:
1260 #
1261 # Either @device or @node-name must be set but not both.
1262 #
1263 # @device: the name of the device to take a snapshot of.
1264 #
1265 # @node-name: graph node name to generate the snapshot from (Since 2.0)
1266 #
1267 # @snapshot-file: the target of the new overlay image. If the file
1268 #                 exists, or if it is a device, the overlay will be created in the
1269 #                 existing file/device. Otherwise, a new file will be created.
1270 #
1271 # @snapshot-node-name: the graph node name of the new image (Since 2.0)
1272 #
1273 # @format: the format of the overlay image, default is 'qcow2'.
1274 #
1275 # @mode: whether and how QEMU should create a new image, default is
1276 #        'absolute-paths'.
1277 ##
1278 { 'struct': 'BlockdevSnapshotSync',
1279   'data': { '*device': 'str', '*node-name': 'str',
1280             'snapshot-file': 'str', '*snapshot-node-name': 'str',
1281             '*format': 'str', '*mode': 'NewImageMode' } }
1282
1283 ##
1284 # @BlockdevSnapshot:
1285 #
1286 # @node: device or node name that will have a snapshot taken.
1287 #
1288 # @overlay: reference to the existing block device that will become
1289 #           the overlay of @node, as part of taking the snapshot.
1290 #           It must not have a current backing file (this can be
1291 #           achieved by passing "backing": null to blockdev-add).
1292 #
1293 # Since: 2.5
1294 ##
1295 { 'struct': 'BlockdevSnapshot',
1296   'data': { 'node': 'str', 'overlay': 'str' } }
1297
1298 ##
1299 # @BackupPerf:
1300 #
1301 # Optional parameters for backup. These parameters don't affect
1302 # functionality, but may significantly affect performance.
1303 #
1304 # @use-copy-range: Use copy offloading. Default false.
1305 #
1306 # @max-workers: Maximum number of parallel requests for the sustained background
1307 #               copying process. Doesn't influence copy-before-write operations.
1308 #               Default 64.
1309 #
1310 # @max-chunk: Maximum request length for the sustained background copying
1311 #             process. Doesn't influence copy-before-write operations.
1312 #             0 means unlimited. If max-chunk is non-zero then it should not be
1313 #             less than job cluster size which is calculated as maximum of
1314 #             target image cluster size and 64k. Default 0.
1315 #
1316 # Since: 6.0
1317 ##
1318 { 'struct': 'BackupPerf',
1319   'data': { '*use-copy-range': 'bool',
1320             '*max-workers': 'int', '*max-chunk': 'int64' } }
1321
1322 ##
1323 # @BackupCommon:
1324 #
1325 # @job-id: identifier for the newly-created block job. If
1326 #          omitted, the device name will be used. (Since 2.7)
1327 #
1328 # @device: the device name or node-name of a root node which should be copied.
1329 #
1330 # @sync: what parts of the disk image should be copied to the destination
1331 #        (all the disk, only the sectors allocated in the topmost image, from a
1332 #        dirty bitmap, or only new I/O).
1333 #
1334 # @speed: the maximum speed, in bytes per second. The default is 0,
1335 #         for unlimited.
1336 #
1337 # @bitmap: The name of a dirty bitmap to use.
1338 #          Must be present if sync is "bitmap" or "incremental".
1339 #          Can be present if sync is "full" or "top".
1340 #          Must not be present otherwise.
1341 #          (Since 2.4 (drive-backup), 3.1 (blockdev-backup))
1342 #
1343 # @bitmap-mode: Specifies the type of data the bitmap should contain after
1344 #               the operation concludes.
1345 #               Must be present if a bitmap was provided,
1346 #               Must NOT be present otherwise. (Since 4.2)
1347 #
1348 # @compress: true to compress data, if the target format supports it.
1349 #            (default: false) (since 2.8)
1350 #
1351 # @on-source-error: the action to take on an error on the source,
1352 #                   default 'report'.  'stop' and 'enospc' can only be used
1353 #                   if the block device supports io-status (see BlockInfo).
1354 #
1355 # @on-target-error: the action to take on an error on the target,
1356 #                   default 'report' (no limitations, since this applies to
1357 #                   a different block device than @device).
1358 #
1359 # @auto-finalize: When false, this job will wait in a PENDING state after it has
1360 #                 finished its work, waiting for @block-job-finalize before
1361 #                 making any block graph changes.
1362 #                 When true, this job will automatically
1363 #                 perform its abort or commit actions.
1364 #                 Defaults to true. (Since 2.12)
1365 #
1366 # @auto-dismiss: When false, this job will wait in a CONCLUDED state after it
1367 #                has completely ceased all work, and awaits @block-job-dismiss.
1368 #                When true, this job will automatically disappear from the query
1369 #                list without user intervention.
1370 #                Defaults to true. (Since 2.12)
1371 #
1372 # @filter-node-name: the node name that should be assigned to the
1373 #                    filter driver that the backup job inserts into the graph
1374 #                    above node specified by @drive. If this option is not given,
1375 #                    a node name is autogenerated. (Since: 4.2)
1376 #
1377 # @x-perf: Performance options. (Since 6.0)
1378 #
1379 # Note: @on-source-error and @on-target-error only affect background
1380 #       I/O.  If an error occurs during a guest write request, the device's
1381 #       rerror/werror actions will be used.
1382 #
1383 # Since: 4.2
1384 ##
1385 { 'struct': 'BackupCommon',
1386   'data': { '*job-id': 'str', 'device': 'str',
1387             'sync': 'MirrorSyncMode', '*speed': 'int',
1388             '*bitmap': 'str', '*bitmap-mode': 'BitmapSyncMode',
1389             '*compress': 'bool',
1390             '*on-source-error': 'BlockdevOnError',
1391             '*on-target-error': 'BlockdevOnError',
1392             '*auto-finalize': 'bool', '*auto-dismiss': 'bool',
1393             '*filter-node-name': 'str', '*x-perf': 'BackupPerf'  } }
1394
1395 ##
1396 # @DriveBackup:
1397 #
1398 # @target: the target of the new image. If the file exists, or if it
1399 #          is a device, the existing file/device will be used as the new
1400 #          destination.  If it does not exist, a new file will be created.
1401 #
1402 # @format: the format of the new destination, default is to
1403 #          probe if @mode is 'existing', else the format of the source
1404 #
1405 # @mode: whether and how QEMU should create a new image, default is
1406 #        'absolute-paths'.
1407 #
1408 # Since: 1.6
1409 ##
1410 { 'struct': 'DriveBackup',
1411   'base': 'BackupCommon',
1412   'data': { 'target': 'str',
1413             '*format': 'str',
1414             '*mode': 'NewImageMode' } }
1415
1416 ##
1417 # @BlockdevBackup:
1418 #
1419 # @target: the device name or node-name of the backup target node.
1420 #
1421 # Since: 2.3
1422 ##
1423 { 'struct': 'BlockdevBackup',
1424   'base': 'BackupCommon',
1425   'data': { 'target': 'str' } }
1426
1427 ##
1428 # @blockdev-snapshot-sync:
1429 #
1430 # Takes a synchronous snapshot of a block device.
1431 #
1432 # For the arguments, see the documentation of BlockdevSnapshotSync.
1433 #
1434 # Returns: - nothing on success
1435 #          - If @device is not a valid block device, DeviceNotFound
1436 #
1437 # Since: 0.14
1438 #
1439 # Example:
1440 #
1441 # -> { "execute": "blockdev-snapshot-sync",
1442 #      "arguments": { "device": "ide-hd0",
1443 #                     "snapshot-file":
1444 #                     "/some/place/my-image",
1445 #                     "format": "qcow2" } }
1446 # <- { "return": {} }
1447 #
1448 ##
1449 { 'command': 'blockdev-snapshot-sync',
1450   'data': 'BlockdevSnapshotSync' }
1451
1452
1453 ##
1454 # @blockdev-snapshot:
1455 #
1456 # Takes a snapshot of a block device.
1457 #
1458 # Take a snapshot, by installing 'node' as the backing image of
1459 # 'overlay'. Additionally, if 'node' is associated with a block
1460 # device, the block device changes to using 'overlay' as its new active
1461 # image.
1462 #
1463 # For the arguments, see the documentation of BlockdevSnapshot.
1464 #
1465 # Features:
1466 # @allow-write-only-overlay: If present, the check whether this operation is safe
1467 #                            was relaxed so that it can be used to change
1468 #                            backing file of a destination of a blockdev-mirror.
1469 #                            (since 5.0)
1470 #
1471 # Since: 2.5
1472 #
1473 # Example:
1474 #
1475 # -> { "execute": "blockdev-add",
1476 #      "arguments": { "driver": "qcow2",
1477 #                     "node-name": "node1534",
1478 #                     "file": { "driver": "file",
1479 #                               "filename": "hd1.qcow2" },
1480 #                     "backing": null } }
1481 #
1482 # <- { "return": {} }
1483 #
1484 # -> { "execute": "blockdev-snapshot",
1485 #      "arguments": { "node": "ide-hd0",
1486 #                     "overlay": "node1534" } }
1487 # <- { "return": {} }
1488 #
1489 ##
1490 { 'command': 'blockdev-snapshot',
1491   'data': 'BlockdevSnapshot',
1492   'features': [ 'allow-write-only-overlay' ] }
1493
1494 ##
1495 # @change-backing-file:
1496 #
1497 # Change the backing file in the image file metadata.  This does not
1498 # cause QEMU to reopen the image file to reparse the backing filename
1499 # (it may, however, perform a reopen to change permissions from
1500 # r/o -> r/w -> r/o, if needed). The new backing file string is written
1501 # into the image file metadata, and the QEMU internal strings are
1502 # updated.
1503 #
1504 # @image-node-name: The name of the block driver state node of the
1505 #                   image to modify. The "device" argument is used
1506 #                   to verify "image-node-name" is in the chain
1507 #                   described by "device".
1508 #
1509 # @device: The device name or node-name of the root node that owns
1510 #          image-node-name.
1511 #
1512 # @backing-file: The string to write as the backing file.  This
1513 #                string is not validated, so care should be taken
1514 #                when specifying the string or the image chain may
1515 #                not be able to be reopened again.
1516 #
1517 # Returns: - Nothing on success
1518 #          - If "device" does not exist or cannot be determined, DeviceNotFound
1519 #
1520 # Since: 2.1
1521 ##
1522 { 'command': 'change-backing-file',
1523   'data': { 'device': 'str', 'image-node-name': 'str',
1524             'backing-file': 'str' } }
1525
1526 ##
1527 # @block-commit:
1528 #
1529 # Live commit of data from overlay image nodes into backing nodes - i.e.,
1530 # writes data between 'top' and 'base' into 'base'.
1531 #
1532 # If top == base, that is an error.
1533 # If top has no overlays on top of it, or if it is in use by a writer,
1534 # the job will not be completed by itself.  The user needs to complete
1535 # the job with the block-job-complete command after getting the ready
1536 # event. (Since 2.0)
1537 #
1538 # If the base image is smaller than top, then the base image will be
1539 # resized to be the same size as top.  If top is smaller than the base
1540 # image, the base will not be truncated.  If you want the base image
1541 # size to match the size of the smaller top, you can safely truncate
1542 # it yourself once the commit operation successfully completes.
1543 #
1544 # @job-id: identifier for the newly-created block job. If
1545 #          omitted, the device name will be used. (Since 2.7)
1546 #
1547 # @device: the device name or node-name of a root node
1548 #
1549 # @base-node: The node name of the backing image to write data into.
1550 #             If not specified, this is the deepest backing image.
1551 #             (since: 3.1)
1552 #
1553 # @base: Same as @base-node, except that it is a file name rather than a node
1554 #        name. This must be the exact filename string that was used to open the
1555 #        node; other strings, even if addressing the same file, are not
1556 #        accepted
1557 #
1558 # @top-node: The node name of the backing image within the image chain
1559 #            which contains the topmost data to be committed down. If
1560 #            not specified, this is the active layer. (since: 3.1)
1561 #
1562 # @top: Same as @top-node, except that it is a file name rather than a node
1563 #       name. This must be the exact filename string that was used to open the
1564 #       node; other strings, even if addressing the same file, are not
1565 #       accepted
1566 #
1567 # @backing-file: The backing file string to write into the overlay
1568 #                image of 'top'.  If 'top' does not have an overlay
1569 #                image, or if 'top' is in use by a writer, specifying
1570 #                a backing file string is an error.
1571 #
1572 #                This filename is not validated.  If a pathname string
1573 #                is such that it cannot be resolved by QEMU, that
1574 #                means that subsequent QMP or HMP commands must use
1575 #                node-names for the image in question, as filename
1576 #                lookup methods will fail.
1577 #
1578 #                If not specified, QEMU will automatically determine
1579 #                the backing file string to use, or error out if
1580 #                there is no obvious choice. Care should be taken
1581 #                when specifying the string, to specify a valid
1582 #                filename or protocol.
1583 #                (Since 2.1)
1584 #
1585 # @speed: the maximum speed, in bytes per second
1586 #
1587 # @on-error: the action to take on an error. 'ignore' means that the request
1588 #            should be retried. (default: report; Since: 5.0)
1589 #
1590 # @filter-node-name: the node name that should be assigned to the
1591 #                    filter driver that the commit job inserts into the graph
1592 #                    above @top. If this option is not given, a node name is
1593 #                    autogenerated. (Since: 2.9)
1594 #
1595 # @auto-finalize: When false, this job will wait in a PENDING state after it has
1596 #                 finished its work, waiting for @block-job-finalize before
1597 #                 making any block graph changes.
1598 #                 When true, this job will automatically
1599 #                 perform its abort or commit actions.
1600 #                 Defaults to true. (Since 3.1)
1601 #
1602 # @auto-dismiss: When false, this job will wait in a CONCLUDED state after it
1603 #                has completely ceased all work, and awaits @block-job-dismiss.
1604 #                When true, this job will automatically disappear from the query
1605 #                list without user intervention.
1606 #                Defaults to true. (Since 3.1)
1607 #
1608 # Features:
1609 # @deprecated: Members @base and @top are deprecated.  Use @base-node
1610 #              and @top-node instead.
1611 #
1612 # Returns: - Nothing on success
1613 #          - If @device does not exist, DeviceNotFound
1614 #          - Any other error returns a GenericError.
1615 #
1616 # Since: 1.3
1617 #
1618 # Example:
1619 #
1620 # -> { "execute": "block-commit",
1621 #      "arguments": { "device": "virtio0",
1622 #                     "top": "/tmp/snap1.qcow2" } }
1623 # <- { "return": {} }
1624 #
1625 ##
1626 { 'command': 'block-commit',
1627   'data': { '*job-id': 'str', 'device': 'str', '*base-node': 'str',
1628             '*base': { 'type': 'str', 'features': [ 'deprecated' ] },
1629             '*top-node': 'str',
1630             '*top': { 'type': 'str', 'features': [ 'deprecated' ] },
1631             '*backing-file': 'str', '*speed': 'int',
1632             '*on-error': 'BlockdevOnError',
1633             '*filter-node-name': 'str',
1634             '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } }
1635
1636 ##
1637 # @drive-backup:
1638 #
1639 # Start a point-in-time copy of a block device to a new destination.  The
1640 # status of ongoing drive-backup operations can be checked with
1641 # query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1642 # The operation can be stopped before it has completed using the
1643 # block-job-cancel command.
1644 #
1645 # Returns: - nothing on success
1646 #          - If @device is not a valid block device, GenericError
1647 #
1648 # Since: 1.6
1649 #
1650 # Example:
1651 #
1652 # -> { "execute": "drive-backup",
1653 #      "arguments": { "device": "drive0",
1654 #                     "sync": "full",
1655 #                     "target": "backup.img" } }
1656 # <- { "return": {} }
1657 #
1658 ##
1659 { 'command': 'drive-backup', 'boxed': true,
1660   'data': 'DriveBackup' }
1661
1662 ##
1663 # @blockdev-backup:
1664 #
1665 # Start a point-in-time copy of a block device to a new destination.  The
1666 # status of ongoing blockdev-backup operations can be checked with
1667 # query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1668 # The operation can be stopped before it has completed using the
1669 # block-job-cancel command.
1670 #
1671 # Returns: - nothing on success
1672 #          - If @device is not a valid block device, DeviceNotFound
1673 #
1674 # Since: 2.3
1675 #
1676 # Example:
1677 # -> { "execute": "blockdev-backup",
1678 #      "arguments": { "device": "src-id",
1679 #                     "sync": "full",
1680 #                     "target": "tgt-id" } }
1681 # <- { "return": {} }
1682 #
1683 ##
1684 { 'command': 'blockdev-backup', 'boxed': true,
1685   'data': 'BlockdevBackup' }
1686
1687
1688 ##
1689 # @query-named-block-nodes:
1690 #
1691 # Get the named block driver list
1692 #
1693 # @flat: Omit the nested data about backing image ("backing-image" key) if true.
1694 #        Default is false (Since 5.0)
1695 #
1696 # Returns: the list of BlockDeviceInfo
1697 #
1698 # Since: 2.0
1699 #
1700 # Example:
1701 #
1702 # -> { "execute": "query-named-block-nodes" }
1703 # <- { "return": [ { "ro":false,
1704 #                    "drv":"qcow2",
1705 #                    "encrypted":false,
1706 #                    "file":"disks/test.qcow2",
1707 #                    "node-name": "my-node",
1708 #                    "backing_file_depth":1,
1709 #                    "bps":1000000,
1710 #                    "bps_rd":0,
1711 #                    "bps_wr":0,
1712 #                    "iops":1000000,
1713 #                    "iops_rd":0,
1714 #                    "iops_wr":0,
1715 #                    "bps_max": 8000000,
1716 #                    "bps_rd_max": 0,
1717 #                    "bps_wr_max": 0,
1718 #                    "iops_max": 0,
1719 #                    "iops_rd_max": 0,
1720 #                    "iops_wr_max": 0,
1721 #                    "iops_size": 0,
1722 #                    "write_threshold": 0,
1723 #                    "image":{
1724 #                       "filename":"disks/test.qcow2",
1725 #                       "format":"qcow2",
1726 #                       "virtual-size":2048000,
1727 #                       "backing_file":"base.qcow2",
1728 #                       "full-backing-filename":"disks/base.qcow2",
1729 #                       "backing-filename-format":"qcow2",
1730 #                       "snapshots":[
1731 #                          {
1732 #                             "id": "1",
1733 #                             "name": "snapshot1",
1734 #                             "vm-state-size": 0,
1735 #                             "date-sec": 10000200,
1736 #                             "date-nsec": 12,
1737 #                             "vm-clock-sec": 206,
1738 #                             "vm-clock-nsec": 30
1739 #                          }
1740 #                       ],
1741 #                       "backing-image":{
1742 #                           "filename":"disks/base.qcow2",
1743 #                           "format":"qcow2",
1744 #                           "virtual-size":2048000
1745 #                       }
1746 #                    } } ] }
1747 #
1748 ##
1749 { 'command': 'query-named-block-nodes',
1750   'returns': [ 'BlockDeviceInfo' ],
1751   'data': { '*flat': 'bool' } }
1752
1753 ##
1754 # @XDbgBlockGraphNodeType:
1755 #
1756 # @block-backend: corresponds to BlockBackend
1757 #
1758 # @block-job: corresponds to BlockJob
1759 #
1760 # @block-driver: corresponds to BlockDriverState
1761 #
1762 # Since: 4.0
1763 ##
1764 { 'enum': 'XDbgBlockGraphNodeType',
1765   'data': [ 'block-backend', 'block-job', 'block-driver' ] }
1766
1767 ##
1768 # @XDbgBlockGraphNode:
1769 #
1770 # @id: Block graph node identifier. This @id is generated only for
1771 #      x-debug-query-block-graph and does not relate to any other identifiers in
1772 #      Qemu.
1773 #
1774 # @type: Type of graph node. Can be one of block-backend, block-job or
1775 #        block-driver-state.
1776 #
1777 # @name: Human readable name of the node. Corresponds to node-name for
1778 #        block-driver-state nodes; is not guaranteed to be unique in the whole
1779 #        graph (with block-jobs and block-backends).
1780 #
1781 # Since: 4.0
1782 ##
1783 { 'struct': 'XDbgBlockGraphNode',
1784   'data': { 'id': 'uint64', 'type': 'XDbgBlockGraphNodeType', 'name': 'str' } }
1785
1786 ##
1787 # @BlockPermission:
1788 #
1789 # Enum of base block permissions.
1790 #
1791 # @consistent-read: A user that has the "permission" of consistent reads is
1792 #                   guaranteed that their view of the contents of the block
1793 #                   device is complete and self-consistent, representing the
1794 #                   contents of a disk at a specific point.
1795 #                   For most block devices (including their backing files) this
1796 #                   is true, but the property cannot be maintained in a few
1797 #                   situations like for intermediate nodes of a commit block
1798 #                   job.
1799 #
1800 # @write: This permission is required to change the visible disk contents.
1801 #
1802 # @write-unchanged: This permission (which is weaker than BLK_PERM_WRITE) is
1803 #                   both enough and required for writes to the block node when
1804 #                   the caller promises that the visible disk content doesn't
1805 #                   change.
1806 #                   As the BLK_PERM_WRITE permission is strictly stronger,
1807 #                   either is sufficient to perform an unchanging write.
1808 #
1809 # @resize: This permission is required to change the size of a block node.
1810 #
1811 # @graph-mod: This permission is required to change the node that this
1812 #             BdrvChild points to.
1813 #
1814 # Since: 4.0
1815 ##
1816 { 'enum': 'BlockPermission',
1817   'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize',
1818             'graph-mod' ] }
1819 ##
1820 # @XDbgBlockGraphEdge:
1821 #
1822 # Block Graph edge description for x-debug-query-block-graph.
1823 #
1824 # @parent: parent id
1825 #
1826 # @child: child id
1827 #
1828 # @name: name of the relation (examples are 'file' and 'backing')
1829 #
1830 # @perm: granted permissions for the parent operating on the child
1831 #
1832 # @shared-perm: permissions that can still be granted to other users of the
1833 #               child while it is still attached to this parent
1834 #
1835 # Since: 4.0
1836 ##
1837 { 'struct': 'XDbgBlockGraphEdge',
1838   'data': { 'parent': 'uint64', 'child': 'uint64',
1839             'name': 'str', 'perm': [ 'BlockPermission' ],
1840             'shared-perm': [ 'BlockPermission' ] } }
1841
1842 ##
1843 # @XDbgBlockGraph:
1844 #
1845 # Block Graph - list of nodes and list of edges.
1846 #
1847 # Since: 4.0
1848 ##
1849 { 'struct': 'XDbgBlockGraph',
1850   'data': { 'nodes': ['XDbgBlockGraphNode'], 'edges': ['XDbgBlockGraphEdge'] } }
1851
1852 ##
1853 # @x-debug-query-block-graph:
1854 #
1855 # Get the block graph.
1856 #
1857 # Since: 4.0
1858 ##
1859 { 'command': 'x-debug-query-block-graph', 'returns': 'XDbgBlockGraph' }
1860
1861 ##
1862 # @drive-mirror:
1863 #
1864 # Start mirroring a block device's writes to a new destination. target
1865 # specifies the target of the new image. If the file exists, or if it
1866 # is a device, it will be used as the new destination for writes. If
1867 # it does not exist, a new file will be created. format specifies the
1868 # format of the mirror image, default is to probe if mode='existing',
1869 # else the format of the source.
1870 #
1871 # Returns: - nothing on success
1872 #          - If @device is not a valid block device, GenericError
1873 #
1874 # Since: 1.3
1875 #
1876 # Example:
1877 #
1878 # -> { "execute": "drive-mirror",
1879 #      "arguments": { "device": "ide-hd0",
1880 #                     "target": "/some/place/my-image",
1881 #                     "sync": "full",
1882 #                     "format": "qcow2" } }
1883 # <- { "return": {} }
1884 #
1885 ##
1886 { 'command': 'drive-mirror', 'boxed': true,
1887   'data': 'DriveMirror' }
1888
1889 ##
1890 # @DriveMirror:
1891 #
1892 # A set of parameters describing drive mirror setup.
1893 #
1894 # @job-id: identifier for the newly-created block job. If
1895 #          omitted, the device name will be used. (Since 2.7)
1896 #
1897 # @device:  the device name or node-name of a root node whose writes should be
1898 #           mirrored.
1899 #
1900 # @target: the target of the new image. If the file exists, or if it
1901 #          is a device, the existing file/device will be used as the new
1902 #          destination.  If it does not exist, a new file will be created.
1903 #
1904 # @format: the format of the new destination, default is to
1905 #          probe if @mode is 'existing', else the format of the source
1906 #
1907 # @node-name: the new block driver state node name in the graph
1908 #             (Since 2.1)
1909 #
1910 # @replaces: with sync=full graph node name to be replaced by the new
1911 #            image when a whole image copy is done. This can be used to repair
1912 #            broken Quorum files.  By default, @device is replaced, although
1913 #            implicitly created filters on it are kept. (Since 2.1)
1914 #
1915 # @mode: whether and how QEMU should create a new image, default is
1916 #        'absolute-paths'.
1917 #
1918 # @speed:  the maximum speed, in bytes per second
1919 #
1920 # @sync: what parts of the disk image should be copied to the destination
1921 #        (all the disk, only the sectors allocated in the topmost image, or
1922 #        only new I/O).
1923 #
1924 # @granularity: granularity of the dirty bitmap, default is 64K
1925 #               if the image format doesn't have clusters, 4K if the clusters
1926 #               are smaller than that, else the cluster size.  Must be a
1927 #               power of 2 between 512 and 64M (since 1.4).
1928 #
1929 # @buf-size: maximum amount of data in flight from source to
1930 #            target (since 1.4).
1931 #
1932 # @on-source-error: the action to take on an error on the source,
1933 #                   default 'report'.  'stop' and 'enospc' can only be used
1934 #                   if the block device supports io-status (see BlockInfo).
1935 #
1936 # @on-target-error: the action to take on an error on the target,
1937 #                   default 'report' (no limitations, since this applies to
1938 #                   a different block device than @device).
1939 # @unmap: Whether to try to unmap target sectors where source has
1940 #         only zero. If true, and target unallocated sectors will read as zero,
1941 #         target image sectors will be unmapped; otherwise, zeroes will be
1942 #         written. Both will result in identical contents.
1943 #         Default is true. (Since 2.4)
1944 #
1945 # @copy-mode: when to copy data to the destination; defaults to 'background'
1946 #             (Since: 3.0)
1947 #
1948 # @auto-finalize: When false, this job will wait in a PENDING state after it has
1949 #                 finished its work, waiting for @block-job-finalize before
1950 #                 making any block graph changes.
1951 #                 When true, this job will automatically
1952 #                 perform its abort or commit actions.
1953 #                 Defaults to true. (Since 3.1)
1954 #
1955 # @auto-dismiss: When false, this job will wait in a CONCLUDED state after it
1956 #                has completely ceased all work, and awaits @block-job-dismiss.
1957 #                When true, this job will automatically disappear from the query
1958 #                list without user intervention.
1959 #                Defaults to true. (Since 3.1)
1960 # Since: 1.3
1961 ##
1962 { 'struct': 'DriveMirror',
1963   'data': { '*job-id': 'str', 'device': 'str', 'target': 'str',
1964             '*format': 'str', '*node-name': 'str', '*replaces': 'str',
1965             'sync': 'MirrorSyncMode', '*mode': 'NewImageMode',
1966             '*speed': 'int', '*granularity': 'uint32',
1967             '*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
1968             '*on-target-error': 'BlockdevOnError',
1969             '*unmap': 'bool', '*copy-mode': 'MirrorCopyMode',
1970             '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } }
1971
1972 ##
1973 # @BlockDirtyBitmap:
1974 #
1975 # @node: name of device/node which the bitmap is tracking
1976 #
1977 # @name: name of the dirty bitmap
1978 #
1979 # Since: 2.4
1980 ##
1981 { 'struct': 'BlockDirtyBitmap',
1982   'data': { 'node': 'str', 'name': 'str' } }
1983
1984 ##
1985 # @BlockDirtyBitmapAdd:
1986 #
1987 # @node: name of device/node which the bitmap is tracking
1988 #
1989 # @name: name of the dirty bitmap (must be less than 1024 bytes)
1990 #
1991 # @granularity: the bitmap granularity, default is 64k for
1992 #               block-dirty-bitmap-add
1993 #
1994 # @persistent: the bitmap is persistent, i.e. it will be saved to the
1995 #              corresponding block device image file on its close. For now only
1996 #              Qcow2 disks support persistent bitmaps. Default is false for
1997 #              block-dirty-bitmap-add. (Since: 2.10)
1998 #
1999 # @disabled: the bitmap is created in the disabled state, which means that
2000 #            it will not track drive changes. The bitmap may be enabled with
2001 #            block-dirty-bitmap-enable. Default is false. (Since: 4.0)
2002 #
2003 # Since: 2.4
2004 ##
2005 { 'struct': 'BlockDirtyBitmapAdd',
2006   'data': { 'node': 'str', 'name': 'str', '*granularity': 'uint32',
2007             '*persistent': 'bool', '*disabled': 'bool' } }
2008
2009 ##
2010 # @BlockDirtyBitmapMergeSource:
2011 #
2012 # @local: name of the bitmap, attached to the same node as target bitmap.
2013 #
2014 # @external: bitmap with specified node
2015 #
2016 # Since: 4.1
2017 ##
2018 { 'alternate': 'BlockDirtyBitmapMergeSource',
2019   'data': { 'local': 'str',
2020             'external': 'BlockDirtyBitmap' } }
2021
2022 ##
2023 # @BlockDirtyBitmapMerge:
2024 #
2025 # @node: name of device/node which the @target bitmap is tracking
2026 #
2027 # @target: name of the destination dirty bitmap
2028 #
2029 # @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or fully
2030 #           specified BlockDirtyBitmap elements. The latter are supported
2031 #           since 4.1.
2032 #
2033 # Since: 4.0
2034 ##
2035 { 'struct': 'BlockDirtyBitmapMerge',
2036   'data': { 'node': 'str', 'target': 'str',
2037             'bitmaps': ['BlockDirtyBitmapMergeSource'] } }
2038
2039 ##
2040 # @block-dirty-bitmap-add:
2041 #
2042 # Create a dirty bitmap with a name on the node, and start tracking the writes.
2043 #
2044 # Returns: - nothing on success
2045 #          - If @node is not a valid block device or node, DeviceNotFound
2046 #          - If @name is already taken, GenericError with an explanation
2047 #
2048 # Since: 2.4
2049 #
2050 # Example:
2051 #
2052 # -> { "execute": "block-dirty-bitmap-add",
2053 #      "arguments": { "node": "drive0", "name": "bitmap0" } }
2054 # <- { "return": {} }
2055 #
2056 ##
2057 { 'command': 'block-dirty-bitmap-add',
2058   'data': 'BlockDirtyBitmapAdd' }
2059
2060 ##
2061 # @block-dirty-bitmap-remove:
2062 #
2063 # Stop write tracking and remove the dirty bitmap that was created
2064 # with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
2065 # storage too.
2066 #
2067 # Returns: - nothing on success
2068 #          - If @node is not a valid block device or node, DeviceNotFound
2069 #          - If @name is not found, GenericError with an explanation
2070 #          - if @name is frozen by an operation, GenericError
2071 #
2072 # Since: 2.4
2073 #
2074 # Example:
2075 #
2076 # -> { "execute": "block-dirty-bitmap-remove",
2077 #      "arguments": { "node": "drive0", "name": "bitmap0" } }
2078 # <- { "return": {} }
2079 #
2080 ##
2081 { 'command': 'block-dirty-bitmap-remove',
2082   'data': 'BlockDirtyBitmap' }
2083
2084 ##
2085 # @block-dirty-bitmap-clear:
2086 #
2087 # Clear (reset) a dirty bitmap on the device, so that an incremental
2088 # backup from this point in time forward will only backup clusters
2089 # modified after this clear operation.
2090 #
2091 # Returns: - nothing on success
2092 #          - If @node is not a valid block device, DeviceNotFound
2093 #          - If @name is not found, GenericError with an explanation
2094 #
2095 # Since: 2.4
2096 #
2097 # Example:
2098 #
2099 # -> { "execute": "block-dirty-bitmap-clear",
2100 #      "arguments": { "node": "drive0", "name": "bitmap0" } }
2101 # <- { "return": {} }
2102 #
2103 ##
2104 { 'command': 'block-dirty-bitmap-clear',
2105   'data': 'BlockDirtyBitmap' }
2106
2107 ##
2108 # @block-dirty-bitmap-enable:
2109 #
2110 # Enables a dirty bitmap so that it will begin tracking disk changes.
2111 #
2112 # Returns: - nothing on success
2113 #          - If @node is not a valid block device, DeviceNotFound
2114 #          - If @name is not found, GenericError with an explanation
2115 #
2116 # Since: 4.0
2117 #
2118 # Example:
2119 #
2120 # -> { "execute": "block-dirty-bitmap-enable",
2121 #      "arguments": { "node": "drive0", "name": "bitmap0" } }
2122 # <- { "return": {} }
2123 #
2124 ##
2125 { 'command': 'block-dirty-bitmap-enable',
2126   'data': 'BlockDirtyBitmap' }
2127
2128 ##
2129 # @block-dirty-bitmap-disable:
2130 #
2131 # Disables a dirty bitmap so that it will stop tracking disk changes.
2132 #
2133 # Returns: - nothing on success
2134 #          - If @node is not a valid block device, DeviceNotFound
2135 #          - If @name is not found, GenericError with an explanation
2136 #
2137 # Since: 4.0
2138 #
2139 # Example:
2140 #
2141 # -> { "execute": "block-dirty-bitmap-disable",
2142 #      "arguments": { "node": "drive0", "name": "bitmap0" } }
2143 # <- { "return": {} }
2144 #
2145 ##
2146 { 'command': 'block-dirty-bitmap-disable',
2147   'data': 'BlockDirtyBitmap' }
2148
2149 ##
2150 # @block-dirty-bitmap-merge:
2151 #
2152 # Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
2153 # Dirty bitmaps in @bitmaps will be unchanged, except if it also appears
2154 # as the @target bitmap. Any bits already set in @target will still be
2155 # set after the merge, i.e., this operation does not clear the target.
2156 # On error, @target is unchanged.
2157 #
2158 # The resulting bitmap will count as dirty any clusters that were dirty in any
2159 # of the source bitmaps. This can be used to achieve backup checkpoints, or in
2160 # simpler usages, to copy bitmaps.
2161 #
2162 # Returns: - nothing on success
2163 #          - If @node is not a valid block device, DeviceNotFound
2164 #          - If any bitmap in @bitmaps or @target is not found, GenericError
2165 #          - If any of the bitmaps have different sizes or granularities,
2166 #            GenericError
2167 #
2168 # Since: 4.0
2169 #
2170 # Example:
2171 #
2172 # -> { "execute": "block-dirty-bitmap-merge",
2173 #      "arguments": { "node": "drive0", "target": "bitmap0",
2174 #                     "bitmaps": ["bitmap1"] } }
2175 # <- { "return": {} }
2176 #
2177 ##
2178 { 'command': 'block-dirty-bitmap-merge',
2179   'data': 'BlockDirtyBitmapMerge' }
2180
2181 ##
2182 # @BlockDirtyBitmapSha256:
2183 #
2184 # SHA256 hash of dirty bitmap data
2185 #
2186 # @sha256: ASCII representation of SHA256 bitmap hash
2187 #
2188 # Since: 2.10
2189 ##
2190 { 'struct': 'BlockDirtyBitmapSha256',
2191   'data': {'sha256': 'str'} }
2192
2193 ##
2194 # @x-debug-block-dirty-bitmap-sha256:
2195 #
2196 # Get bitmap SHA256.
2197 #
2198 # Returns: - BlockDirtyBitmapSha256 on success
2199 #          - If @node is not a valid block device, DeviceNotFound
2200 #          - If @name is not found or if hashing has failed, GenericError with an
2201 #            explanation
2202 #
2203 # Since: 2.10
2204 ##
2205 { 'command': 'x-debug-block-dirty-bitmap-sha256',
2206   'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256' }
2207
2208 ##
2209 # @blockdev-mirror:
2210 #
2211 # Start mirroring a block device's writes to a new destination.
2212 #
2213 # @job-id: identifier for the newly-created block job. If
2214 #          omitted, the device name will be used. (Since 2.7)
2215 #
2216 # @device: The device name or node-name of a root node whose writes should be
2217 #          mirrored.
2218 #
2219 # @target: the id or node-name of the block device to mirror to. This mustn't be
2220 #          attached to guest.
2221 #
2222 # @replaces: with sync=full graph node name to be replaced by the new
2223 #            image when a whole image copy is done. This can be used to repair
2224 #            broken Quorum files.  By default, @device is replaced, although
2225 #            implicitly created filters on it are kept.
2226 #
2227 # @speed:  the maximum speed, in bytes per second
2228 #
2229 # @sync: what parts of the disk image should be copied to the destination
2230 #        (all the disk, only the sectors allocated in the topmost image, or
2231 #        only new I/O).
2232 #
2233 # @granularity: granularity of the dirty bitmap, default is 64K
2234 #               if the image format doesn't have clusters, 4K if the clusters
2235 #               are smaller than that, else the cluster size.  Must be a
2236 #               power of 2 between 512 and 64M
2237 #
2238 # @buf-size: maximum amount of data in flight from source to
2239 #            target
2240 #
2241 # @on-source-error: the action to take on an error on the source,
2242 #                   default 'report'.  'stop' and 'enospc' can only be used
2243 #                   if the block device supports io-status (see BlockInfo).
2244 #
2245 # @on-target-error: the action to take on an error on the target,
2246 #                   default 'report' (no limitations, since this applies to
2247 #                   a different block device than @device).
2248 #
2249 # @filter-node-name: the node name that should be assigned to the
2250 #                    filter driver that the mirror job inserts into the graph
2251 #                    above @device. If this option is not given, a node name is
2252 #                    autogenerated. (Since: 2.9)
2253 #
2254 # @copy-mode: when to copy data to the destination; defaults to 'background'
2255 #             (Since: 3.0)
2256 #
2257 # @auto-finalize: When false, this job will wait in a PENDING state after it has
2258 #                 finished its work, waiting for @block-job-finalize before
2259 #                 making any block graph changes.
2260 #                 When true, this job will automatically
2261 #                 perform its abort or commit actions.
2262 #                 Defaults to true. (Since 3.1)
2263 #
2264 # @auto-dismiss: When false, this job will wait in a CONCLUDED state after it
2265 #                has completely ceased all work, and awaits @block-job-dismiss.
2266 #                When true, this job will automatically disappear from the query
2267 #                list without user intervention.
2268 #                Defaults to true. (Since 3.1)
2269 # Returns: nothing on success.
2270 #
2271 # Since: 2.6
2272 #
2273 # Example:
2274 #
2275 # -> { "execute": "blockdev-mirror",
2276 #      "arguments": { "device": "ide-hd0",
2277 #                     "target": "target0",
2278 #                     "sync": "full" } }
2279 # <- { "return": {} }
2280 #
2281 ##
2282 { 'command': 'blockdev-mirror',
2283   'data': { '*job-id': 'str', 'device': 'str', 'target': 'str',
2284             '*replaces': 'str',
2285             'sync': 'MirrorSyncMode',
2286             '*speed': 'int', '*granularity': 'uint32',
2287             '*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
2288             '*on-target-error': 'BlockdevOnError',
2289             '*filter-node-name': 'str',
2290             '*copy-mode': 'MirrorCopyMode',
2291             '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } }
2292
2293 ##
2294 # @BlockIOThrottle:
2295 #
2296 # A set of parameters describing block throttling.
2297 #
2298 # @device: Block device name
2299 #
2300 # @id: The name or QOM path of the guest device (since: 2.8)
2301 #
2302 # @bps: total throughput limit in bytes per second
2303 #
2304 # @bps_rd: read throughput limit in bytes per second
2305 #
2306 # @bps_wr: write throughput limit in bytes per second
2307 #
2308 # @iops: total I/O operations per second
2309 #
2310 # @iops_rd: read I/O operations per second
2311 #
2312 # @iops_wr: write I/O operations per second
2313 #
2314 # @bps_max: total throughput limit during bursts,
2315 #           in bytes (Since 1.7)
2316 #
2317 # @bps_rd_max: read throughput limit during bursts,
2318 #              in bytes (Since 1.7)
2319 #
2320 # @bps_wr_max: write throughput limit during bursts,
2321 #              in bytes (Since 1.7)
2322 #
2323 # @iops_max: total I/O operations per second during bursts,
2324 #            in bytes (Since 1.7)
2325 #
2326 # @iops_rd_max: read I/O operations per second during bursts,
2327 #               in bytes (Since 1.7)
2328 #
2329 # @iops_wr_max: write I/O operations per second during bursts,
2330 #               in bytes (Since 1.7)
2331 #
2332 # @bps_max_length: maximum length of the @bps_max burst
2333 #                  period, in seconds. It must only
2334 #                  be set if @bps_max is set as well.
2335 #                  Defaults to 1. (Since 2.6)
2336 #
2337 # @bps_rd_max_length: maximum length of the @bps_rd_max
2338 #                     burst period, in seconds. It must only
2339 #                     be set if @bps_rd_max is set as well.
2340 #                     Defaults to 1. (Since 2.6)
2341 #
2342 # @bps_wr_max_length: maximum length of the @bps_wr_max
2343 #                     burst period, in seconds. It must only
2344 #                     be set if @bps_wr_max is set as well.
2345 #                     Defaults to 1. (Since 2.6)
2346 #
2347 # @iops_max_length: maximum length of the @iops burst
2348 #                   period, in seconds. It must only
2349 #                   be set if @iops_max is set as well.
2350 #                   Defaults to 1. (Since 2.6)
2351 #
2352 # @iops_rd_max_length: maximum length of the @iops_rd_max
2353 #                      burst period, in seconds. It must only
2354 #                      be set if @iops_rd_max is set as well.
2355 #                      Defaults to 1. (Since 2.6)
2356 #
2357 # @iops_wr_max_length: maximum length of the @iops_wr_max
2358 #                      burst period, in seconds. It must only
2359 #                      be set if @iops_wr_max is set as well.
2360 #                      Defaults to 1. (Since 2.6)
2361 #
2362 # @iops_size: an I/O size in bytes (Since 1.7)
2363 #
2364 # @group: throttle group name (Since 2.4)
2365 #
2366 # Features:
2367 # @deprecated: Member @device is deprecated.  Use @id instead.
2368 #
2369 # Since: 1.1
2370 ##
2371 { 'struct': 'BlockIOThrottle',
2372   'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
2373             '*id': 'str', 'bps': 'int', 'bps_rd': 'int',
2374             'bps_wr': 'int', 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
2375             '*bps_max': 'int', '*bps_rd_max': 'int',
2376             '*bps_wr_max': 'int', '*iops_max': 'int',
2377             '*iops_rd_max': 'int', '*iops_wr_max': 'int',
2378             '*bps_max_length': 'int', '*bps_rd_max_length': 'int',
2379             '*bps_wr_max_length': 'int', '*iops_max_length': 'int',
2380             '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int',
2381             '*iops_size': 'int', '*group': 'str' } }
2382
2383 ##
2384 # @ThrottleLimits:
2385 #
2386 # Limit parameters for throttling.
2387 # Since some limit combinations are illegal, limits should always be set in one
2388 # transaction. All fields are optional. When setting limits, if a field is
2389 # missing the current value is not changed.
2390 #
2391 # @iops-total: limit total I/O operations per second
2392 # @iops-total-max: I/O operations burst
2393 # @iops-total-max-length: length of the iops-total-max burst period, in seconds
2394 #                         It must only be set if @iops-total-max is set as well.
2395 # @iops-read: limit read operations per second
2396 # @iops-read-max: I/O operations read burst
2397 # @iops-read-max-length: length of the iops-read-max burst period, in seconds
2398 #                        It must only be set if @iops-read-max is set as well.
2399 # @iops-write: limit write operations per second
2400 # @iops-write-max: I/O operations write burst
2401 # @iops-write-max-length: length of the iops-write-max burst period, in seconds
2402 #                         It must only be set if @iops-write-max is set as well.
2403 # @bps-total: limit total bytes per second
2404 # @bps-total-max: total bytes burst
2405 # @bps-total-max-length: length of the bps-total-max burst period, in seconds.
2406 #                        It must only be set if @bps-total-max is set as well.
2407 # @bps-read: limit read bytes per second
2408 # @bps-read-max: total bytes read burst
2409 # @bps-read-max-length: length of the bps-read-max burst period, in seconds
2410 #                       It must only be set if @bps-read-max is set as well.
2411 # @bps-write: limit write bytes per second
2412 # @bps-write-max: total bytes write burst
2413 # @bps-write-max-length: length of the bps-write-max burst period, in seconds
2414 #                        It must only be set if @bps-write-max is set as well.
2415 # @iops-size: when limiting by iops max size of an I/O in bytes
2416 #
2417 # Since: 2.11
2418 ##
2419 { 'struct': 'ThrottleLimits',
2420   'data': { '*iops-total' : 'int', '*iops-total-max' : 'int',
2421             '*iops-total-max-length' : 'int', '*iops-read' : 'int',
2422             '*iops-read-max' : 'int', '*iops-read-max-length' : 'int',
2423             '*iops-write' : 'int', '*iops-write-max' : 'int',
2424             '*iops-write-max-length' : 'int', '*bps-total' : 'int',
2425             '*bps-total-max' : 'int', '*bps-total-max-length' : 'int',
2426             '*bps-read' : 'int', '*bps-read-max' : 'int',
2427             '*bps-read-max-length' : 'int', '*bps-write' : 'int',
2428             '*bps-write-max' : 'int', '*bps-write-max-length' : 'int',
2429             '*iops-size' : 'int' } }
2430
2431 ##
2432 # @ThrottleGroupProperties:
2433 #
2434 # Properties for throttle-group objects.
2435 #
2436 # The options starting with x- are aliases for the same key without x- in
2437 # the @limits object. As indicated by the x- prefix, this is not a stable
2438 # interface and may be removed or changed incompatibly in the future. Use
2439 # @limits for a supported stable interface.
2440 #
2441 # @limits: limits to apply for this throttle group
2442 #
2443 # Since: 2.11
2444 ##
2445 { 'struct': 'ThrottleGroupProperties',
2446   'data': { '*limits': 'ThrottleLimits',
2447             '*x-iops-total' : 'int', '*x-iops-total-max' : 'int',
2448             '*x-iops-total-max-length' : 'int', '*x-iops-read' : 'int',
2449             '*x-iops-read-max' : 'int', '*x-iops-read-max-length' : 'int',
2450             '*x-iops-write' : 'int', '*x-iops-write-max' : 'int',
2451             '*x-iops-write-max-length' : 'int', '*x-bps-total' : 'int',
2452             '*x-bps-total-max' : 'int', '*x-bps-total-max-length' : 'int',
2453             '*x-bps-read' : 'int', '*x-bps-read-max' : 'int',
2454             '*x-bps-read-max-length' : 'int', '*x-bps-write' : 'int',
2455             '*x-bps-write-max' : 'int', '*x-bps-write-max-length' : 'int',
2456             '*x-iops-size' : 'int' } }
2457
2458 ##
2459 # @block-stream:
2460 #
2461 # Copy data from a backing file into a block device.
2462 #
2463 # The block streaming operation is performed in the background until the entire
2464 # backing file has been copied.  This command returns immediately once streaming
2465 # has started.  The status of ongoing block streaming operations can be checked
2466 # with query-block-jobs.  The operation can be stopped before it has completed
2467 # using the block-job-cancel command.
2468 #
2469 # The node that receives the data is called the top image, can be located in
2470 # any part of the chain (but always above the base image; see below) and can be
2471 # specified using its device or node name. Earlier qemu versions only allowed
2472 # 'device' to name the top level node; presence of the 'base-node' parameter
2473 # during introspection can be used as a witness of the enhanced semantics
2474 # of 'device'.
2475 #
2476 # If a base file is specified then sectors are not copied from that base file and
2477 # its backing chain.  This can be used to stream a subset of the backing file
2478 # chain instead of flattening the entire image.
2479 # When streaming completes the image file will have the base file as its backing
2480 # file, unless that node was changed while the job was running.  In that case,
2481 # base's parent's backing (or filtered, whichever exists) child (i.e., base at
2482 # the beginning of the job) will be the new backing file.
2483 #
2484 # On successful completion the image file is updated to drop the backing file
2485 # and the BLOCK_JOB_COMPLETED event is emitted.
2486 #
2487 # In case @device is a filter node, block-stream modifies the first non-filter
2488 # overlay node below it to point to the new backing node instead of modifying
2489 # @device itself.
2490 #
2491 # @job-id: identifier for the newly-created block job. If
2492 #          omitted, the device name will be used. (Since 2.7)
2493 #
2494 # @device: the device or node name of the top image
2495 #
2496 # @base: the common backing file name.
2497 #        It cannot be set if @base-node or @bottom is also set.
2498 #
2499 # @base-node: the node name of the backing file.
2500 #             It cannot be set if @base or @bottom is also set. (Since 2.8)
2501 #
2502 # @bottom: the last node in the chain that should be streamed into
2503 #          top. It cannot be set if @base or @base-node is also set.
2504 #          It cannot be filter node. (Since 6.0)
2505 #
2506 # @backing-file: The backing file string to write into the top
2507 #                image. This filename is not validated.
2508 #
2509 #                If a pathname string is such that it cannot be
2510 #                resolved by QEMU, that means that subsequent QMP or
2511 #                HMP commands must use node-names for the image in
2512 #                question, as filename lookup methods will fail.
2513 #
2514 #                If not specified, QEMU will automatically determine
2515 #                the backing file string to use, or error out if there
2516 #                is no obvious choice.  Care should be taken when
2517 #                specifying the string, to specify a valid filename or
2518 #                protocol.
2519 #                (Since 2.1)
2520 #
2521 # @speed: the maximum speed, in bytes per second
2522 #
2523 # @on-error: the action to take on an error (default report).
2524 #            'stop' and 'enospc' can only be used if the block device
2525 #            supports io-status (see BlockInfo).  Since 1.3.
2526 #
2527 # @filter-node-name: the node name that should be assigned to the
2528 #                    filter driver that the stream job inserts into the graph
2529 #                    above @device. If this option is not given, a node name is
2530 #                    autogenerated. (Since: 6.0)
2531 #
2532 # @auto-finalize: When false, this job will wait in a PENDING state after it has
2533 #                 finished its work, waiting for @block-job-finalize before
2534 #                 making any block graph changes.
2535 #                 When true, this job will automatically
2536 #                 perform its abort or commit actions.
2537 #                 Defaults to true. (Since 3.1)
2538 #
2539 # @auto-dismiss: When false, this job will wait in a CONCLUDED state after it
2540 #                has completely ceased all work, and awaits @block-job-dismiss.
2541 #                When true, this job will automatically disappear from the query
2542 #                list without user intervention.
2543 #                Defaults to true. (Since 3.1)
2544 #
2545 # Returns: - Nothing on success.
2546 #          - If @device does not exist, DeviceNotFound.
2547 #
2548 # Since: 1.1
2549 #
2550 # Example:
2551 #
2552 # -> { "execute": "block-stream",
2553 #      "arguments": { "device": "virtio0",
2554 #                     "base": "/tmp/master.qcow2" } }
2555 # <- { "return": {} }
2556 #
2557 ##
2558 { 'command': 'block-stream',
2559   'data': { '*job-id': 'str', 'device': 'str', '*base': 'str',
2560             '*base-node': 'str', '*backing-file': 'str', '*bottom': 'str',
2561             '*speed': 'int', '*on-error': 'BlockdevOnError',
2562             '*filter-node-name': 'str',
2563             '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } }
2564
2565 ##
2566 # @block-job-set-speed:
2567 #
2568 # Set maximum speed for a background block operation.
2569 #
2570 # This command can only be issued when there is an active block job.
2571 #
2572 # Throttling can be disabled by setting the speed to 0.
2573 #
2574 # @device: The job identifier. This used to be a device name (hence
2575 #          the name of the parameter), but since QEMU 2.7 it can have
2576 #          other values.
2577 #
2578 # @speed: the maximum speed, in bytes per second, or 0 for unlimited.
2579 #         Defaults to 0.
2580 #
2581 # Returns: - Nothing on success
2582 #          - If no background operation is active on this device, DeviceNotActive
2583 #
2584 # Since: 1.1
2585 ##
2586 { 'command': 'block-job-set-speed',
2587   'data': { 'device': 'str', 'speed': 'int' } }
2588
2589 ##
2590 # @block-job-cancel:
2591 #
2592 # Stop an active background block operation.
2593 #
2594 # This command returns immediately after marking the active background block
2595 # operation for cancellation.  It is an error to call this command if no
2596 # operation is in progress.
2597 #
2598 # The operation will cancel as soon as possible and then emit the
2599 # BLOCK_JOB_CANCELLED event.  Before that happens the job is still visible when
2600 # enumerated using query-block-jobs.
2601 #
2602 # Note that if you issue 'block-job-cancel' after 'drive-mirror' has indicated
2603 # (via the event BLOCK_JOB_READY) that the source and destination are
2604 # synchronized, then the event triggered by this command changes to
2605 # BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
2606 # destination now has a point-in-time copy tied to the time of the cancellation.
2607 #
2608 # For streaming, the image file retains its backing file unless the streaming
2609 # operation happens to complete just as it is being cancelled.  A new streaming
2610 # operation can be started at a later time to finish copying all data from the
2611 # backing file.
2612 #
2613 # @device: The job identifier. This used to be a device name (hence
2614 #          the name of the parameter), but since QEMU 2.7 it can have
2615 #          other values.
2616 #
2617 # @force: If true, and the job has already emitted the event BLOCK_JOB_READY,
2618 #         abandon the job immediately (even if it is paused) instead of waiting
2619 #         for the destination to complete its final synchronization (since 1.3)
2620 #
2621 # Returns: - Nothing on success
2622 #          - If no background operation is active on this device, DeviceNotActive
2623 #
2624 # Since: 1.1
2625 ##
2626 { 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } }
2627
2628 ##
2629 # @block-job-pause:
2630 #
2631 # Pause an active background block operation.
2632 #
2633 # This command returns immediately after marking the active background block
2634 # operation for pausing.  It is an error to call this command if no
2635 # operation is in progress or if the job is already paused.
2636 #
2637 # The operation will pause as soon as possible.  No event is emitted when
2638 # the operation is actually paused.  Cancelling a paused job automatically
2639 # resumes it.
2640 #
2641 # @device: The job identifier. This used to be a device name (hence
2642 #          the name of the parameter), but since QEMU 2.7 it can have
2643 #          other values.
2644 #
2645 # Returns: - Nothing on success
2646 #          - If no background operation is active on this device, DeviceNotActive
2647 #
2648 # Since: 1.3
2649 ##
2650 { 'command': 'block-job-pause', 'data': { 'device': 'str' } }
2651
2652 ##
2653 # @block-job-resume:
2654 #
2655 # Resume an active background block operation.
2656 #
2657 # This command returns immediately after resuming a paused background block
2658 # operation.  It is an error to call this command if no operation is in
2659 # progress or if the job is not paused.
2660 #
2661 # This command also clears the error status of the job.
2662 #
2663 # @device: The job identifier. This used to be a device name (hence
2664 #          the name of the parameter), but since QEMU 2.7 it can have
2665 #          other values.
2666 #
2667 # Returns: - Nothing on success
2668 #          - If no background operation is active on this device, DeviceNotActive
2669 #
2670 # Since: 1.3
2671 ##
2672 { 'command': 'block-job-resume', 'data': { 'device': 'str' } }
2673
2674 ##
2675 # @block-job-complete:
2676 #
2677 # Manually trigger completion of an active background block operation.  This
2678 # is supported for drive mirroring, where it also switches the device to
2679 # write to the target path only.  The ability to complete is signaled with
2680 # a BLOCK_JOB_READY event.
2681 #
2682 # This command completes an active background block operation synchronously.
2683 # The ordering of this command's return with the BLOCK_JOB_COMPLETED event
2684 # is not defined.  Note that if an I/O error occurs during the processing of
2685 # this command: 1) the command itself will fail; 2) the error will be processed
2686 # according to the rerror/werror arguments that were specified when starting
2687 # the operation.
2688 #
2689 # A cancelled or paused job cannot be completed.
2690 #
2691 # @device: The job identifier. This used to be a device name (hence
2692 #          the name of the parameter), but since QEMU 2.7 it can have
2693 #          other values.
2694 #
2695 # Returns: - Nothing on success
2696 #          - If no background operation is active on this device, DeviceNotActive
2697 #
2698 # Since: 1.3
2699 ##
2700 { 'command': 'block-job-complete', 'data': { 'device': 'str' } }
2701
2702 ##
2703 # @block-job-dismiss:
2704 #
2705 # For jobs that have already concluded, remove them from the block-job-query
2706 # list. This command only needs to be run for jobs which were started with
2707 # QEMU 2.12+ job lifetime management semantics.
2708 #
2709 # This command will refuse to operate on any job that has not yet reached
2710 # its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
2711 # BLOCK_JOB_READY event, block-job-cancel or block-job-complete will still need
2712 # to be used as appropriate.
2713 #
2714 # @id: The job identifier.
2715 #
2716 # Returns: Nothing on success
2717 #
2718 # Since: 2.12
2719 ##
2720 { 'command': 'block-job-dismiss', 'data': { 'id': 'str' } }
2721
2722 ##
2723 # @block-job-finalize:
2724 #
2725 # Once a job that has manual=true reaches the pending state, it can be
2726 # instructed to finalize any graph changes and do any necessary cleanup
2727 # via this command.
2728 # For jobs in a transaction, instructing one job to finalize will force
2729 # ALL jobs in the transaction to finalize, so it is only necessary to instruct
2730 # a single member job to finalize.
2731 #
2732 # @id: The job identifier.
2733 #
2734 # Returns: Nothing on success
2735 #
2736 # Since: 2.12
2737 ##
2738 { 'command': 'block-job-finalize', 'data': { 'id': 'str' } }
2739
2740 ##
2741 # @BlockdevDiscardOptions:
2742 #
2743 # Determines how to handle discard requests.
2744 #
2745 # @ignore: Ignore the request
2746 # @unmap: Forward as an unmap request
2747 #
2748 # Since: 2.9
2749 ##
2750 { 'enum': 'BlockdevDiscardOptions',
2751   'data': [ 'ignore', 'unmap' ] }
2752
2753 ##
2754 # @BlockdevDetectZeroesOptions:
2755 #
2756 # Describes the operation mode for the automatic conversion of plain
2757 # zero writes by the OS to driver specific optimized zero write commands.
2758 #
2759 # @off: Disabled (default)
2760 # @on: Enabled
2761 # @unmap: Enabled and even try to unmap blocks if possible. This requires
2762 #         also that @BlockdevDiscardOptions is set to unmap for this device.
2763 #
2764 # Since: 2.1
2765 ##
2766 { 'enum': 'BlockdevDetectZeroesOptions',
2767   'data': [ 'off', 'on', 'unmap' ] }
2768
2769 ##
2770 # @BlockdevAioOptions:
2771 #
2772 # Selects the AIO backend to handle I/O requests
2773 #
2774 # @threads: Use qemu's thread pool
2775 # @native: Use native AIO backend (only Linux and Windows)
2776 # @io_uring: Use linux io_uring (since 5.0)
2777 #
2778 # Since: 2.9
2779 ##
2780 { 'enum': 'BlockdevAioOptions',
2781   'data': [ 'threads', 'native',
2782             { 'name': 'io_uring', 'if': 'defined(CONFIG_LINUX_IO_URING)' } ] }
2783
2784 ##
2785 # @BlockdevCacheOptions:
2786 #
2787 # Includes cache-related options for block devices
2788 #
2789 # @direct: enables use of O_DIRECT (bypass the host page cache;
2790 #          default: false)
2791 # @no-flush: ignore any flush requests for the device (default:
2792 #            false)
2793 #
2794 # Since: 2.9
2795 ##
2796 { 'struct': 'BlockdevCacheOptions',
2797   'data': { '*direct': 'bool',
2798             '*no-flush': 'bool' } }
2799
2800 ##
2801 # @BlockdevDriver:
2802 #
2803 # Drivers that are supported in block device operations.
2804 #
2805 # @throttle: Since 2.11
2806 # @nvme: Since 2.12
2807 # @copy-on-read: Since 3.0
2808 # @blklogwrites: Since 3.0
2809 # @blkreplay: Since 4.2
2810 # @compress: Since 5.0
2811 #
2812 # Since: 2.9
2813 ##
2814 { 'enum': 'BlockdevDriver',
2815   'data': [ 'blkdebug', 'blklogwrites', 'blkreplay', 'blkverify', 'bochs',
2816             'cloop', 'compress', 'copy-on-read', 'dmg', 'file', 'ftp', 'ftps',
2817             'gluster', 'host_cdrom', 'host_device', 'http', 'https', 'iscsi',
2818             'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme', 'parallels',
2819             'preallocate', 'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'rbd',
2820             { 'name': 'replication', 'if': 'defined(CONFIG_REPLICATION)' },
2821             'sheepdog',
2822             'ssh', 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat' ] }
2823
2824 ##
2825 # @BlockdevOptionsFile:
2826 #
2827 # Driver specific block device options for the file backend.
2828 #
2829 # @filename: path to the image file
2830 # @pr-manager: the id for the object that will handle persistent reservations
2831 #              for this device (default: none, forward the commands via SG_IO;
2832 #              since 2.11)
2833 # @aio: AIO backend (default: threads) (since: 2.8)
2834 # @locking: whether to enable file locking. If set to 'auto', only enable
2835 #           when Open File Descriptor (OFD) locking API is available
2836 #           (default: auto, since 2.10)
2837 # @drop-cache: invalidate page cache during live migration.  This prevents
2838 #              stale data on the migration destination with cache.direct=off.
2839 #              Currently only supported on Linux hosts.
2840 #              (default: on, since: 4.0)
2841 # @x-check-cache-dropped: whether to check that page cache was dropped on live
2842 #                         migration.  May cause noticeable delays if the image
2843 #                         file is large, do not use in production.
2844 #                         (default: off) (since: 3.0)
2845 #
2846 # Features:
2847 # @dynamic-auto-read-only: If present, enabled auto-read-only means that the
2848 #                          driver will open the image read-only at first,
2849 #                          dynamically reopen the image file read-write when
2850 #                          the first writer is attached to the node and reopen
2851 #                          read-only when the last writer is detached. This
2852 #                          allows giving QEMU write permissions only on demand
2853 #                          when an operation actually needs write access.
2854 #
2855 # Since: 2.9
2856 ##
2857 { 'struct': 'BlockdevOptionsFile',
2858   'data': { 'filename': 'str',
2859             '*pr-manager': 'str',
2860             '*locking': 'OnOffAuto',
2861             '*aio': 'BlockdevAioOptions',
2862             '*drop-cache': {'type': 'bool',
2863                             'if': 'defined(CONFIG_LINUX)'},
2864             '*x-check-cache-dropped': 'bool' },
2865   'features': [ { 'name': 'dynamic-auto-read-only',
2866                   'if': 'defined(CONFIG_POSIX)' } ] }
2867
2868 ##
2869 # @BlockdevOptionsNull:
2870 #
2871 # Driver specific block device options for the null backend.
2872 #
2873 # @size: size of the device in bytes.
2874 # @latency-ns: emulated latency (in nanoseconds) in processing
2875 #              requests. Default to zero which completes requests immediately.
2876 #              (Since 2.4)
2877 # @read-zeroes: if true, reads from the device produce zeroes; if false, the
2878 #               buffer is left unchanged. (default: false; since: 4.1)
2879 #
2880 # Since: 2.9
2881 ##
2882 { 'struct': 'BlockdevOptionsNull',
2883   'data': { '*size': 'int', '*latency-ns': 'uint64', '*read-zeroes': 'bool' } }
2884
2885 ##
2886 # @BlockdevOptionsNVMe:
2887 #
2888 # Driver specific block device options for the NVMe backend.
2889 #
2890 # @device: PCI controller address of the NVMe device in
2891 #          format hhhh:bb:ss.f (host:bus:slot.function)
2892 # @namespace: namespace number of the device, starting from 1.
2893 #
2894 # Note that the PCI @device must have been unbound from any host
2895 # kernel driver before instructing QEMU to add the blockdev.
2896 #
2897 # Since: 2.12
2898 ##
2899 { 'struct': 'BlockdevOptionsNVMe',
2900   'data': { 'device': 'str', 'namespace': 'int' } }
2901
2902 ##
2903 # @BlockdevOptionsVVFAT:
2904 #
2905 # Driver specific block device options for the vvfat protocol.
2906 #
2907 # @dir: directory to be exported as FAT image
2908 # @fat-type: FAT type: 12, 16 or 32
2909 # @floppy: whether to export a floppy image (true) or
2910 #          partitioned hard disk (false; default)
2911 # @label: set the volume label, limited to 11 bytes. FAT16 and
2912 #         FAT32 traditionally have some restrictions on labels, which are
2913 #         ignored by most operating systems. Defaults to "QEMU VVFAT".
2914 #         (since 2.4)
2915 # @rw: whether to allow write operations (default: false)
2916 #
2917 # Since: 2.9
2918 ##
2919 { 'struct': 'BlockdevOptionsVVFAT',
2920   'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool',
2921             '*label': 'str', '*rw': 'bool' } }
2922
2923 ##
2924 # @BlockdevOptionsGenericFormat:
2925 #
2926 # Driver specific block device options for image format that have no option
2927 # besides their data source.
2928 #
2929 # @file: reference to or definition of the data source block device
2930 #
2931 # Since: 2.9
2932 ##
2933 { 'struct': 'BlockdevOptionsGenericFormat',
2934   'data': { 'file': 'BlockdevRef' } }
2935
2936 ##
2937 # @BlockdevOptionsLUKS:
2938 #
2939 # Driver specific block device options for LUKS.
2940 #
2941 # @key-secret: the ID of a QCryptoSecret object providing
2942 #              the decryption key (since 2.6). Mandatory except when
2943 #              doing a metadata-only probe of the image.
2944 #
2945 # Since: 2.9
2946 ##
2947 { 'struct': 'BlockdevOptionsLUKS',
2948   'base': 'BlockdevOptionsGenericFormat',
2949   'data': { '*key-secret': 'str' } }
2950
2951
2952 ##
2953 # @BlockdevOptionsGenericCOWFormat:
2954 #
2955 # Driver specific block device options for image format that have no option
2956 # besides their data source and an optional backing file.
2957 #
2958 # @backing: reference to or definition of the backing file block
2959 #           device, null disables the backing file entirely.
2960 #           Defaults to the backing file stored the image file.
2961 #
2962 # Since: 2.9
2963 ##
2964 { 'struct': 'BlockdevOptionsGenericCOWFormat',
2965   'base': 'BlockdevOptionsGenericFormat',
2966   'data': { '*backing': 'BlockdevRefOrNull' } }
2967
2968 ##
2969 # @Qcow2OverlapCheckMode:
2970 #
2971 # General overlap check modes.
2972 #
2973 # @none: Do not perform any checks
2974 #
2975 # @constant: Perform only checks which can be done in constant time and
2976 #            without reading anything from disk
2977 #
2978 # @cached: Perform only checks which can be done without reading anything
2979 #          from disk
2980 #
2981 # @all: Perform all available overlap checks
2982 #
2983 # Since: 2.9
2984 ##
2985 { 'enum': 'Qcow2OverlapCheckMode',
2986   'data': [ 'none', 'constant', 'cached', 'all' ] }
2987
2988 ##
2989 # @Qcow2OverlapCheckFlags:
2990 #
2991 # Structure of flags for each metadata structure. Setting a field to 'true'
2992 # makes qemu guard that structure against unintended overwriting. The default
2993 # value is chosen according to the template given.
2994 #
2995 # @template: Specifies a template mode which can be adjusted using the other
2996 #            flags, defaults to 'cached'
2997 #
2998 # @bitmap-directory: since 3.0
2999 #
3000 # Since: 2.9
3001 ##
3002 { 'struct': 'Qcow2OverlapCheckFlags',
3003   'data': { '*template':         'Qcow2OverlapCheckMode',
3004             '*main-header':      'bool',
3005             '*active-l1':        'bool',
3006             '*active-l2':        'bool',
3007             '*refcount-table':   'bool',
3008             '*refcount-block':   'bool',
3009             '*snapshot-table':   'bool',
3010             '*inactive-l1':      'bool',
3011             '*inactive-l2':      'bool',
3012             '*bitmap-directory': 'bool' } }
3013
3014 ##
3015 # @Qcow2OverlapChecks:
3016 #
3017 # Specifies which metadata structures should be guarded against unintended
3018 # overwriting.
3019 #
3020 # @flags: set of flags for separate specification of each metadata structure
3021 #         type
3022 #
3023 # @mode: named mode which chooses a specific set of flags
3024 #
3025 # Since: 2.9
3026 ##
3027 { 'alternate': 'Qcow2OverlapChecks',
3028   'data': { 'flags': 'Qcow2OverlapCheckFlags',
3029             'mode':  'Qcow2OverlapCheckMode' } }
3030
3031 ##
3032 # @BlockdevQcowEncryptionFormat:
3033 #
3034 # @aes: AES-CBC with plain64 initialization vectors
3035 #
3036 # Since: 2.10
3037 ##
3038 { 'enum': 'BlockdevQcowEncryptionFormat',
3039   'data': [ 'aes' ] }
3040
3041 ##
3042 # @BlockdevQcowEncryption:
3043 #
3044 # Since: 2.10
3045 ##
3046 { 'union': 'BlockdevQcowEncryption',
3047   'base': { 'format': 'BlockdevQcowEncryptionFormat' },
3048   'discriminator': 'format',
3049   'data': { 'aes': 'QCryptoBlockOptionsQCow' } }
3050
3051 ##
3052 # @BlockdevOptionsQcow:
3053 #
3054 # Driver specific block device options for qcow.
3055 #
3056 # @encrypt: Image decryption options. Mandatory for
3057 #           encrypted images, except when doing a metadata-only
3058 #           probe of the image.
3059 #
3060 # Since: 2.10
3061 ##
3062 { 'struct': 'BlockdevOptionsQcow',
3063   'base': 'BlockdevOptionsGenericCOWFormat',
3064   'data': { '*encrypt': 'BlockdevQcowEncryption' } }
3065
3066
3067
3068 ##
3069 # @BlockdevQcow2EncryptionFormat:
3070 # @aes: AES-CBC with plain64 initialization vectors
3071 #
3072 # Since: 2.10
3073 ##
3074 { 'enum': 'BlockdevQcow2EncryptionFormat',
3075   'data': [ 'aes', 'luks' ] }
3076
3077 ##
3078 # @BlockdevQcow2Encryption:
3079 #
3080 # Since: 2.10
3081 ##
3082 { 'union': 'BlockdevQcow2Encryption',
3083   'base': { 'format': 'BlockdevQcow2EncryptionFormat' },
3084   'discriminator': 'format',
3085   'data': { 'aes': 'QCryptoBlockOptionsQCow',
3086             'luks': 'QCryptoBlockOptionsLUKS'} }
3087
3088 ##
3089 # @BlockdevOptionsPreallocate:
3090 #
3091 # Filter driver intended to be inserted between format and protocol node
3092 # and do preallocation in protocol node on write.
3093 #
3094 # @prealloc-align: on preallocation, align file length to this number,
3095 #                  default 1048576 (1M)
3096 #
3097 # @prealloc-size: how much to preallocate, default 134217728 (128M)
3098 #
3099 # Since: 6.0
3100 ##
3101 { 'struct': 'BlockdevOptionsPreallocate',
3102   'base': 'BlockdevOptionsGenericFormat',
3103   'data': { '*prealloc-align': 'int', '*prealloc-size': 'int' } }
3104
3105 ##
3106 # @BlockdevOptionsQcow2:
3107 #
3108 # Driver specific block device options for qcow2.
3109 #
3110 # @lazy-refcounts: whether to enable the lazy refcounts
3111 #                  feature (default is taken from the image file)
3112 #
3113 # @pass-discard-request: whether discard requests to the qcow2
3114 #                        device should be forwarded to the data source
3115 #
3116 # @pass-discard-snapshot: whether discard requests for the data source
3117 #                         should be issued when a snapshot operation (e.g.
3118 #                         deleting a snapshot) frees clusters in the qcow2 file
3119 #
3120 # @pass-discard-other: whether discard requests for the data source
3121 #                      should be issued on other occasions where a cluster
3122 #                      gets freed
3123 #
3124 # @overlap-check: which overlap checks to perform for writes
3125 #                 to the image, defaults to 'cached' (since 2.2)
3126 #
3127 # @cache-size: the maximum total size of the L2 table and
3128 #              refcount block caches in bytes (since 2.2)
3129 #
3130 # @l2-cache-size: the maximum size of the L2 table cache in
3131 #                 bytes (since 2.2)
3132 #
3133 # @l2-cache-entry-size: the size of each entry in the L2 cache in
3134 #                       bytes. It must be a power of two between 512
3135 #                       and the cluster size. The default value is
3136 #                       the cluster size (since 2.12)
3137 #
3138 # @refcount-cache-size: the maximum size of the refcount block cache
3139 #                       in bytes (since 2.2)
3140 #
3141 # @cache-clean-interval: clean unused entries in the L2 and refcount
3142 #                        caches. The interval is in seconds. The default value
3143 #                        is 600 on supporting platforms, and 0 on other
3144 #                        platforms. 0 disables this feature. (since 2.5)
3145 #
3146 # @encrypt: Image decryption options. Mandatory for
3147 #           encrypted images, except when doing a metadata-only
3148 #           probe of the image. (since 2.10)
3149 #
3150 # @data-file: reference to or definition of the external data file.
3151 #             This may only be specified for images that require an
3152 #             external data file. If it is not specified for such
3153 #             an image, the data file name is loaded from the image
3154 #             file. (since 4.0)
3155 #
3156 # Since: 2.9
3157 ##
3158 { 'struct': 'BlockdevOptionsQcow2',
3159   'base': 'BlockdevOptionsGenericCOWFormat',
3160   'data': { '*lazy-refcounts': 'bool',
3161             '*pass-discard-request': 'bool',
3162             '*pass-discard-snapshot': 'bool',
3163             '*pass-discard-other': 'bool',
3164             '*overlap-check': 'Qcow2OverlapChecks',
3165             '*cache-size': 'int',
3166             '*l2-cache-size': 'int',
3167             '*l2-cache-entry-size': 'int',
3168             '*refcount-cache-size': 'int',
3169             '*cache-clean-interval': 'int',
3170             '*encrypt': 'BlockdevQcow2Encryption',
3171             '*data-file': 'BlockdevRef' } }
3172
3173 ##
3174 # @SshHostKeyCheckMode:
3175 #
3176 # @none: Don't check the host key at all
3177 # @hash: Compare the host key with a given hash
3178 # @known_hosts: Check the host key against the known_hosts file
3179 #
3180 # Since: 2.12
3181 ##
3182 { 'enum': 'SshHostKeyCheckMode',
3183   'data': [ 'none', 'hash', 'known_hosts' ] }
3184
3185 ##
3186 # @SshHostKeyCheckHashType:
3187 #
3188 # @md5: The given hash is an md5 hash
3189 # @sha1: The given hash is an sha1 hash
3190 #
3191 # Since: 2.12
3192 ##
3193 { 'enum': 'SshHostKeyCheckHashType',
3194   'data': [ 'md5', 'sha1' ] }
3195
3196 ##
3197 # @SshHostKeyHash:
3198 #
3199 # @type: The hash algorithm used for the hash
3200 # @hash: The expected hash value
3201 #
3202 # Since: 2.12
3203 ##
3204 { 'struct': 'SshHostKeyHash',
3205   'data': { 'type': 'SshHostKeyCheckHashType',
3206             'hash': 'str' }}
3207
3208 ##
3209 # @SshHostKeyCheck:
3210 #
3211 # Since: 2.12
3212 ##
3213 { 'union': 'SshHostKeyCheck',
3214   'base': { 'mode': 'SshHostKeyCheckMode' },
3215   'discriminator': 'mode',
3216   'data': { 'hash': 'SshHostKeyHash' } }
3217
3218 ##
3219 # @BlockdevOptionsSsh:
3220 #
3221 # @server:              host address
3222 #
3223 # @path:                path to the image on the host
3224 #
3225 # @user:                user as which to connect, defaults to current
3226 #                       local user name
3227 #
3228 # @host-key-check:      Defines how and what to check the host key against
3229 #                       (default: known_hosts)
3230 #
3231 # Since: 2.9
3232 ##
3233 { 'struct': 'BlockdevOptionsSsh',
3234   'data': { 'server': 'InetSocketAddress',
3235             'path': 'str',
3236             '*user': 'str',
3237             '*host-key-check': 'SshHostKeyCheck' } }
3238
3239
3240 ##
3241 # @BlkdebugEvent:
3242 #
3243 # Trigger events supported by blkdebug.
3244 #
3245 # @l1_shrink_write_table: write zeros to the l1 table to shrink image.
3246 #                         (since 2.11)
3247 #
3248 # @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11)
3249 #
3250 # @cor_write: a write due to copy-on-read (since 2.11)
3251 #
3252 # @cluster_alloc_space: an allocation of file space for a cluster (since 4.1)
3253 #
3254 # @none: triggers once at creation of the blkdebug node (since 4.1)
3255 #
3256 # Since: 2.9
3257 ##
3258 { 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG',
3259   'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table',
3260             'l1_grow_activate_table', 'l2_load', 'l2_update',
3261             'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write',
3262             'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio',
3263             'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read',
3264             'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update',
3265             'refblock_load', 'refblock_update', 'refblock_update_part',
3266             'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write',
3267             'refblock_alloc_write_blocks', 'refblock_alloc_write_table',
3268             'refblock_alloc_switch_table', 'cluster_alloc',
3269             'cluster_alloc_bytes', 'cluster_free', 'flush_to_os',
3270             'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head',
3271             'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev',
3272             'pwritev_zero', 'pwritev_done', 'empty_image_prepare',
3273             'l1_shrink_write_table', 'l1_shrink_free_l2_clusters',
3274             'cor_write', 'cluster_alloc_space', 'none'] }
3275
3276 ##
3277 # @BlkdebugIOType:
3278 #
3279 # Kinds of I/O that blkdebug can inject errors in.
3280 #
3281 # @read: .bdrv_co_preadv()
3282 #
3283 # @write: .bdrv_co_pwritev()
3284 #
3285 # @write-zeroes: .bdrv_co_pwrite_zeroes()
3286 #
3287 # @discard: .bdrv_co_pdiscard()
3288 #
3289 # @flush: .bdrv_co_flush_to_disk()
3290 #
3291 # @block-status: .bdrv_co_block_status()
3292 #
3293 # Since: 4.1
3294 ##
3295 { 'enum': 'BlkdebugIOType', 'prefix': 'BLKDEBUG_IO_TYPE',
3296   'data': [ 'read', 'write', 'write-zeroes', 'discard', 'flush',
3297             'block-status' ] }
3298
3299 ##
3300 # @BlkdebugInjectErrorOptions:
3301 #
3302 # Describes a single error injection for blkdebug.
3303 #
3304 # @event: trigger event
3305 #
3306 # @state: the state identifier blkdebug needs to be in to
3307 #         actually trigger the event; defaults to "any"
3308 #
3309 # @iotype: the type of I/O operations on which this error should
3310 #          be injected; defaults to "all read, write,
3311 #          write-zeroes, discard, and flush operations"
3312 #          (since: 4.1)
3313 #
3314 # @errno: error identifier (errno) to be returned; defaults to
3315 #         EIO
3316 #
3317 # @sector: specifies the sector index which has to be affected
3318 #          in order to actually trigger the event; defaults to "any
3319 #          sector"
3320 #
3321 # @once: disables further events after this one has been
3322 #        triggered; defaults to false
3323 #
3324 # @immediately: fail immediately; defaults to false
3325 #
3326 # Since: 2.9
3327 ##
3328 { 'struct': 'BlkdebugInjectErrorOptions',
3329   'data': { 'event': 'BlkdebugEvent',
3330             '*state': 'int',
3331             '*iotype': 'BlkdebugIOType',
3332             '*errno': 'int',
3333             '*sector': 'int',
3334             '*once': 'bool',
3335             '*immediately': 'bool' } }
3336
3337 ##
3338 # @BlkdebugSetStateOptions:
3339 #
3340 # Describes a single state-change event for blkdebug.
3341 #
3342 # @event: trigger event
3343 #
3344 # @state: the current state identifier blkdebug needs to be in;
3345 #         defaults to "any"
3346 #
3347 # @new_state: the state identifier blkdebug is supposed to assume if
3348 #             this event is triggered
3349 #
3350 # Since: 2.9
3351 ##
3352 { 'struct': 'BlkdebugSetStateOptions',
3353   'data': { 'event': 'BlkdebugEvent',
3354             '*state': 'int',
3355             'new_state': 'int' } }
3356
3357 ##
3358 # @BlockdevOptionsBlkdebug:
3359 #
3360 # Driver specific block device options for blkdebug.
3361 #
3362 # @image: underlying raw block device (or image file)
3363 #
3364 # @config: filename of the configuration file
3365 #
3366 # @align: required alignment for requests in bytes, must be
3367 #         positive power of 2, or 0 for default
3368 #
3369 # @max-transfer: maximum size for I/O transfers in bytes, must be
3370 #                positive multiple of @align and of the underlying
3371 #                file's request alignment (but need not be a power of
3372 #                2), or 0 for default (since 2.10)
3373 #
3374 # @opt-write-zero: preferred alignment for write zero requests in bytes,
3375 #                  must be positive multiple of @align and of the
3376 #                  underlying file's request alignment (but need not be a
3377 #                  power of 2), or 0 for default (since 2.10)
3378 #
3379 # @max-write-zero: maximum size for write zero requests in bytes, must be
3380 #                  positive multiple of @align, of @opt-write-zero, and of
3381 #                  the underlying file's request alignment (but need not
3382 #                  be a power of 2), or 0 for default (since 2.10)
3383 #
3384 # @opt-discard: preferred alignment for discard requests in bytes, must
3385 #               be positive multiple of @align and of the underlying
3386 #               file's request alignment (but need not be a power of
3387 #               2), or 0 for default (since 2.10)
3388 #
3389 # @max-discard: maximum size for discard requests in bytes, must be
3390 #               positive multiple of @align, of @opt-discard, and of
3391 #               the underlying file's request alignment (but need not
3392 #               be a power of 2), or 0 for default (since 2.10)
3393 #
3394 # @inject-error: array of error injection descriptions
3395 #
3396 # @set-state: array of state-change descriptions
3397 #
3398 # @take-child-perms: Permissions to take on @image in addition to what
3399 #                    is necessary anyway (which depends on how the
3400 #                    blkdebug node is used).  Defaults to none.
3401 #                    (since 5.0)
3402 #
3403 # @unshare-child-perms: Permissions not to share on @image in addition
3404 #                       to what cannot be shared anyway (which depends
3405 #                       on how the blkdebug node is used).  Defaults
3406 #                       to none.  (since 5.0)
3407 #
3408 # Since: 2.9
3409 ##
3410 { 'struct': 'BlockdevOptionsBlkdebug',
3411   'data': { 'image': 'BlockdevRef',
3412             '*config': 'str',
3413             '*align': 'int', '*max-transfer': 'int32',
3414             '*opt-write-zero': 'int32', '*max-write-zero': 'int32',
3415             '*opt-discard': 'int32', '*max-discard': 'int32',
3416             '*inject-error': ['BlkdebugInjectErrorOptions'],
3417             '*set-state': ['BlkdebugSetStateOptions'],
3418             '*take-child-perms': ['BlockPermission'],
3419             '*unshare-child-perms': ['BlockPermission'] } }
3420
3421 ##
3422 # @BlockdevOptionsBlklogwrites:
3423 #
3424 # Driver specific block device options for blklogwrites.
3425 #
3426 # @file: block device
3427 #
3428 # @log: block device used to log writes to @file
3429 #
3430 # @log-sector-size: sector size used in logging writes to @file, determines
3431 #                   granularity of offsets and sizes of writes (default: 512)
3432 #
3433 # @log-append: append to an existing log (default: false)
3434 #
3435 # @log-super-update-interval: interval of write requests after which the log
3436 #                             super block is updated to disk (default: 4096)
3437 #
3438 # Since: 3.0
3439 ##
3440 { 'struct': 'BlockdevOptionsBlklogwrites',
3441   'data': { 'file': 'BlockdevRef',
3442             'log': 'BlockdevRef',
3443             '*log-sector-size': 'uint32',
3444             '*log-append': 'bool',
3445             '*log-super-update-interval': 'uint64' } }
3446
3447 ##
3448 # @BlockdevOptionsBlkverify:
3449 #
3450 # Driver specific block device options for blkverify.
3451 #
3452 # @test: block device to be tested
3453 #
3454 # @raw: raw image used for verification
3455 #
3456 # Since: 2.9
3457 ##
3458 { 'struct': 'BlockdevOptionsBlkverify',
3459   'data': { 'test': 'BlockdevRef',
3460             'raw': 'BlockdevRef' } }
3461
3462 ##
3463 # @BlockdevOptionsBlkreplay:
3464 #
3465 # Driver specific block device options for blkreplay.
3466 #
3467 # @image: disk image which should be controlled with blkreplay
3468 #
3469 # Since: 4.2
3470 ##
3471 { 'struct': 'BlockdevOptionsBlkreplay',
3472   'data': { 'image': 'BlockdevRef' } }
3473
3474 ##
3475 # @QuorumReadPattern:
3476 #
3477 # An enumeration of quorum read patterns.
3478 #
3479 # @quorum: read all the children and do a quorum vote on reads
3480 #
3481 # @fifo: read only from the first child that has not failed
3482 #
3483 # Since: 2.9
3484 ##
3485 { 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] }
3486
3487 ##
3488 # @BlockdevOptionsQuorum:
3489 #
3490 # Driver specific block device options for Quorum
3491 #
3492 # @blkverify: true if the driver must print content mismatch
3493 #                  set to false by default
3494 #
3495 # @children: the children block devices to use
3496 #
3497 # @vote-threshold: the vote limit under which a read will fail
3498 #
3499 # @rewrite-corrupted: rewrite corrupted data when quorum is reached
3500 #                     (Since 2.1)
3501 #
3502 # @read-pattern: choose read pattern and set to quorum by default
3503 #                (Since 2.2)
3504 #
3505 # Since: 2.9
3506 ##
3507 { 'struct': 'BlockdevOptionsQuorum',
3508   'data': { '*blkverify': 'bool',
3509             'children': [ 'BlockdevRef' ],
3510             'vote-threshold': 'int',
3511             '*rewrite-corrupted': 'bool',
3512             '*read-pattern': 'QuorumReadPattern' } }
3513
3514 ##
3515 # @BlockdevOptionsGluster:
3516 #
3517 # Driver specific block device options for Gluster
3518 #
3519 # @volume: name of gluster volume where VM image resides
3520 #
3521 # @path: absolute path to image file in gluster volume
3522 #
3523 # @server: gluster servers description
3524 #
3525 # @debug: libgfapi log level (default '4' which is Error)
3526 #         (Since 2.8)
3527 #
3528 # @logfile: libgfapi log file (default /dev/stderr) (Since 2.8)
3529 #
3530 # Since: 2.9
3531 ##
3532 { 'struct': 'BlockdevOptionsGluster',
3533   'data': { 'volume': 'str',
3534             'path': 'str',
3535             'server': ['SocketAddress'],
3536             '*debug': 'int',
3537             '*logfile': 'str' } }
3538
3539 ##
3540 # @IscsiTransport:
3541 #
3542 # An enumeration of libiscsi transport types
3543 #
3544 # Since: 2.9
3545 ##
3546 { 'enum': 'IscsiTransport',
3547   'data': [ 'tcp', 'iser' ] }
3548
3549 ##
3550 # @IscsiHeaderDigest:
3551 #
3552 # An enumeration of header digests supported by libiscsi
3553 #
3554 # Since: 2.9
3555 ##
3556 { 'enum': 'IscsiHeaderDigest',
3557   'prefix': 'QAPI_ISCSI_HEADER_DIGEST',
3558   'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] }
3559
3560 ##
3561 # @BlockdevOptionsIscsi:
3562 #
3563 # @transport: The iscsi transport type
3564 #
3565 # @portal: The address of the iscsi portal
3566 #
3567 # @target: The target iqn name
3568 #
3569 # @lun: LUN to connect to. Defaults to 0.
3570 #
3571 # @user: User name to log in with. If omitted, no CHAP
3572 #        authentication is performed.
3573 #
3574 # @password-secret: The ID of a QCryptoSecret object providing
3575 #                   the password for the login. This option is required if
3576 #                   @user is specified.
3577 #
3578 # @initiator-name: The iqn name we want to identify to the target
3579 #                  as. If this option is not specified, an initiator name is
3580 #                  generated automatically.
3581 #
3582 # @header-digest: The desired header digest. Defaults to
3583 #                 none-crc32c.
3584 #
3585 # @timeout: Timeout in seconds after which a request will
3586 #           timeout. 0 means no timeout and is the default.
3587 #
3588 # Driver specific block device options for iscsi
3589 #
3590 # Since: 2.9
3591 ##
3592 { 'struct': 'BlockdevOptionsIscsi',
3593   'data': { 'transport': 'IscsiTransport',
3594             'portal': 'str',
3595             'target': 'str',
3596             '*lun': 'int',
3597             '*user': 'str',
3598             '*password-secret': 'str',
3599             '*initiator-name': 'str',
3600             '*header-digest': 'IscsiHeaderDigest',
3601             '*timeout': 'int' } }
3602
3603
3604 ##
3605 # @RbdAuthMode:
3606 #
3607 # Since: 3.0
3608 ##
3609 { 'enum': 'RbdAuthMode',
3610   'data': [ 'cephx', 'none' ] }
3611
3612 ##
3613 # @BlockdevOptionsRbd:
3614 #
3615 # @pool: Ceph pool name.
3616 #
3617 # @namespace: Rados namespace name in the Ceph pool. (Since 5.0)
3618 #
3619 # @image: Image name in the Ceph pool.
3620 #
3621 # @conf: path to Ceph configuration file.  Values
3622 #        in the configuration file will be overridden by
3623 #        options specified via QAPI.
3624 #
3625 # @snapshot: Ceph snapshot name.
3626 #
3627 # @user: Ceph id name.
3628 #
3629 # @auth-client-required: Acceptable authentication modes.
3630 #                        This maps to Ceph configuration option
3631 #                        "auth_client_required".  (Since 3.0)
3632 #
3633 # @key-secret: ID of a QCryptoSecret object providing a key
3634 #              for cephx authentication.
3635 #              This maps to Ceph configuration option
3636 #              "key".  (Since 3.0)
3637 #
3638 # @server: Monitor host address and port.  This maps
3639 #          to the "mon_host" Ceph option.
3640 #
3641 # Since: 2.9
3642 ##
3643 { 'struct': 'BlockdevOptionsRbd',
3644   'data': { 'pool': 'str',
3645             '*namespace': 'str',
3646             'image': 'str',
3647             '*conf': 'str',
3648             '*snapshot': 'str',
3649             '*user': 'str',
3650             '*auth-client-required': ['RbdAuthMode'],
3651             '*key-secret': 'str',
3652             '*server': ['InetSocketAddressBase'] } }
3653
3654 ##
3655 # @BlockdevOptionsSheepdog:
3656 #
3657 # Driver specific block device options for sheepdog
3658 #
3659 # @vdi: Virtual disk image name
3660 # @server: The Sheepdog server to connect to
3661 # @snap-id: Snapshot ID
3662 # @tag: Snapshot tag name
3663 #
3664 # Only one of @snap-id and @tag may be present.
3665 #
3666 # Since: 2.9
3667 ##
3668 { 'struct': 'BlockdevOptionsSheepdog',
3669   'data': { 'server': 'SocketAddress',
3670             'vdi': 'str',
3671             '*snap-id': 'uint32',
3672             '*tag': 'str' } }
3673
3674 ##
3675 # @ReplicationMode:
3676 #
3677 # An enumeration of replication modes.
3678 #
3679 # @primary: Primary mode, the vm's state will be sent to secondary QEMU.
3680 #
3681 # @secondary: Secondary mode, receive the vm's state from primary QEMU.
3682 #
3683 # Since: 2.9
3684 ##
3685 { 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ],
3686   'if': 'defined(CONFIG_REPLICATION)' }
3687
3688 ##
3689 # @BlockdevOptionsReplication:
3690 #
3691 # Driver specific block device options for replication
3692 #
3693 # @mode: the replication mode
3694 #
3695 # @top-id: In secondary mode, node name or device ID of the root
3696 #          node who owns the replication node chain. Must not be given in
3697 #          primary mode.
3698 #
3699 # Since: 2.9
3700 ##
3701 { 'struct': 'BlockdevOptionsReplication',
3702   'base': 'BlockdevOptionsGenericFormat',
3703   'data': { 'mode': 'ReplicationMode',
3704             '*top-id': 'str' },
3705   'if': 'defined(CONFIG_REPLICATION)' }
3706
3707 ##
3708 # @NFSTransport:
3709 #
3710 # An enumeration of NFS transport types
3711 #
3712 # @inet: TCP transport
3713 #
3714 # Since: 2.9
3715 ##
3716 { 'enum': 'NFSTransport',
3717   'data': [ 'inet' ] }
3718
3719 ##
3720 # @NFSServer:
3721 #
3722 # Captures the address of the socket
3723 #
3724 # @type: transport type used for NFS (only TCP supported)
3725 #
3726 # @host: host address for NFS server
3727 #
3728 # Since: 2.9
3729 ##
3730 { 'struct': 'NFSServer',
3731   'data': { 'type': 'NFSTransport',
3732             'host': 'str' } }
3733
3734 ##
3735 # @BlockdevOptionsNfs:
3736 #
3737 # Driver specific block device option for NFS
3738 #
3739 # @server: host address
3740 #
3741 # @path: path of the image on the host
3742 #
3743 # @user: UID value to use when talking to the
3744 #        server (defaults to 65534 on Windows and getuid()
3745 #        on unix)
3746 #
3747 # @group: GID value to use when talking to the
3748 #         server (defaults to 65534 on Windows and getgid()
3749 #         in unix)
3750 #
3751 # @tcp-syn-count: number of SYNs during the session
3752 #                 establishment (defaults to libnfs default)
3753 #
3754 # @readahead-size: set the readahead size in bytes (defaults
3755 #                  to libnfs default)
3756 #
3757 # @page-cache-size: set the pagecache size in bytes (defaults
3758 #                   to libnfs default)
3759 #
3760 # @debug: set the NFS debug level (max 2) (defaults
3761 #         to libnfs default)
3762 #
3763 # Since: 2.9
3764 ##
3765 { 'struct': 'BlockdevOptionsNfs',
3766   'data': { 'server': 'NFSServer',
3767             'path': 'str',
3768             '*user': 'int',
3769             '*group': 'int',
3770             '*tcp-syn-count': 'int',
3771             '*readahead-size': 'int',
3772             '*page-cache-size': 'int',
3773             '*debug': 'int' } }
3774
3775 ##
3776 # @BlockdevOptionsCurlBase:
3777 #
3778 # Driver specific block device options shared by all protocols supported by the
3779 # curl backend.
3780 #
3781 # @url: URL of the image file
3782 #
3783 # @readahead: Size of the read-ahead cache; must be a multiple of
3784 #             512 (defaults to 256 kB)
3785 #
3786 # @timeout: Timeout for connections, in seconds (defaults to 5)
3787 #
3788 # @username: Username for authentication (defaults to none)
3789 #
3790 # @password-secret: ID of a QCryptoSecret object providing a password
3791 #                   for authentication (defaults to no password)
3792 #
3793 # @proxy-username: Username for proxy authentication (defaults to none)
3794 #
3795 # @proxy-password-secret: ID of a QCryptoSecret object providing a password
3796 #                         for proxy authentication (defaults to no password)
3797 #
3798 # Since: 2.9
3799 ##
3800 { 'struct': 'BlockdevOptionsCurlBase',
3801   'data': { 'url': 'str',
3802             '*readahead': 'int',
3803             '*timeout': 'int',
3804             '*username': 'str',
3805             '*password-secret': 'str',
3806             '*proxy-username': 'str',
3807             '*proxy-password-secret': 'str' } }
3808
3809 ##
3810 # @BlockdevOptionsCurlHttp:
3811 #
3812 # Driver specific block device options for HTTP connections over the curl
3813 # backend.  URLs must start with "http://".
3814 #
3815 # @cookie: List of cookies to set; format is
3816 #          "name1=content1; name2=content2;" as explained by
3817 #          CURLOPT_COOKIE(3). Defaults to no cookies.
3818 #
3819 # @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a
3820 #                 secure way. See @cookie for the format. (since 2.10)
3821 #
3822 # Since: 2.9
3823 ##
3824 { 'struct': 'BlockdevOptionsCurlHttp',
3825   'base': 'BlockdevOptionsCurlBase',
3826   'data': { '*cookie': 'str',
3827             '*cookie-secret': 'str'} }
3828
3829 ##
3830 # @BlockdevOptionsCurlHttps:
3831 #
3832 # Driver specific block device options for HTTPS connections over the curl
3833 # backend.  URLs must start with "https://".
3834 #
3835 # @cookie: List of cookies to set; format is
3836 #          "name1=content1; name2=content2;" as explained by
3837 #          CURLOPT_COOKIE(3). Defaults to no cookies.
3838 #
3839 # @sslverify: Whether to verify the SSL certificate's validity (defaults to
3840 #             true)
3841 #
3842 # @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a
3843 #                 secure way. See @cookie for the format. (since 2.10)
3844 #
3845 # Since: 2.9
3846 ##
3847 { 'struct': 'BlockdevOptionsCurlHttps',
3848   'base': 'BlockdevOptionsCurlBase',
3849   'data': { '*cookie': 'str',
3850             '*sslverify': 'bool',
3851             '*cookie-secret': 'str'} }
3852
3853 ##
3854 # @BlockdevOptionsCurlFtp:
3855 #
3856 # Driver specific block device options for FTP connections over the curl
3857 # backend.  URLs must start with "ftp://".
3858 #
3859 # Since: 2.9
3860 ##
3861 { 'struct': 'BlockdevOptionsCurlFtp',
3862   'base': 'BlockdevOptionsCurlBase',
3863   'data': { } }
3864
3865 ##
3866 # @BlockdevOptionsCurlFtps:
3867 #
3868 # Driver specific block device options for FTPS connections over the curl
3869 # backend.  URLs must start with "ftps://".
3870 #
3871 # @sslverify: Whether to verify the SSL certificate's validity (defaults to
3872 #             true)
3873 #
3874 # Since: 2.9
3875 ##
3876 { 'struct': 'BlockdevOptionsCurlFtps',
3877   'base': 'BlockdevOptionsCurlBase',
3878   'data': { '*sslverify': 'bool' } }
3879
3880 ##
3881 # @BlockdevOptionsNbd:
3882 #
3883 # Driver specific block device options for NBD.
3884 #
3885 # @server: NBD server address
3886 #
3887 # @export: export name
3888 #
3889 # @tls-creds: TLS credentials ID
3890 #
3891 # @x-dirty-bitmap: A metadata context name such as "qemu:dirty-bitmap:NAME"
3892 #                  or "qemu:allocation-depth" to query in place of the
3893 #                  traditional "base:allocation" block status (see
3894 #                  NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and
3895 #                  yes, naming this option x-context would have made
3896 #                  more sense) (since 3.0)
3897 #
3898 # @reconnect-delay: On an unexpected disconnect, the nbd client tries to
3899 #                   connect again until succeeding or encountering a serious
3900 #                   error.  During the first @reconnect-delay seconds, all
3901 #                   requests are paused and will be rerun on a successful
3902 #                   reconnect. After that time, any delayed requests and all
3903 #                   future requests before a successful reconnect will
3904 #                   immediately fail. Default 0 (Since 4.2)
3905 #
3906 # Since: 2.9
3907 ##
3908 { 'struct': 'BlockdevOptionsNbd',
3909   'data': { 'server': 'SocketAddress',
3910             '*export': 'str',
3911             '*tls-creds': 'str',
3912             '*x-dirty-bitmap': 'str',
3913             '*reconnect-delay': 'uint32' } }
3914
3915 ##
3916 # @BlockdevOptionsRaw:
3917 #
3918 # Driver specific block device options for the raw driver.
3919 #
3920 # @offset: position where the block device starts
3921 # @size: the assumed size of the device
3922 #
3923 # Since: 2.9
3924 ##
3925 { 'struct': 'BlockdevOptionsRaw',
3926   'base': 'BlockdevOptionsGenericFormat',
3927   'data': { '*offset': 'int', '*size': 'int' } }
3928
3929 ##
3930 # @BlockdevOptionsThrottle:
3931 #
3932 # Driver specific block device options for the throttle driver
3933 #
3934 # @throttle-group: the name of the throttle-group object to use. It
3935 #                  must already exist.
3936 # @file: reference to or definition of the data source block device
3937 # Since: 2.11
3938 ##
3939 { 'struct': 'BlockdevOptionsThrottle',
3940   'data': { 'throttle-group': 'str',
3941             'file' : 'BlockdevRef'
3942              } }
3943
3944 ##
3945 # @BlockdevOptionsCor:
3946 #
3947 # Driver specific block device options for the copy-on-read driver.
3948 #
3949 # @bottom: The name of a non-filter node (allocation-bearing layer) that
3950 #          limits the COR operations in the backing chain (inclusive), so
3951 #          that no data below this node will be copied by this filter.
3952 #          If option is absent, the limit is not applied, so that data
3953 #          from all backing layers may be copied.
3954 #
3955 # Since: 6.0
3956 ##
3957 { 'struct': 'BlockdevOptionsCor',
3958   'base': 'BlockdevOptionsGenericFormat',
3959   'data': { '*bottom': 'str' } }
3960
3961 ##
3962 # @BlockdevOptions:
3963 #
3964 # Options for creating a block device.  Many options are available for all
3965 # block devices, independent of the block driver:
3966 #
3967 # @driver: block driver name
3968 # @node-name: the node name of the new node (Since 2.0).
3969 #             This option is required on the top level of blockdev-add.
3970 #             Valid node names start with an alphabetic character and may
3971 #             contain only alphanumeric characters, '-', '.' and '_'. Their
3972 #             maximum length is 31 characters.
3973 # @discard: discard-related options (default: ignore)
3974 # @cache: cache-related options
3975 # @read-only: whether the block device should be read-only (default: false).
3976 #             Note that some block drivers support only read-only access,
3977 #             either generally or in certain configurations. In this case,
3978 #             the default value does not work and the option must be
3979 #             specified explicitly.
3980 # @auto-read-only: if true and @read-only is false, QEMU may automatically
3981 #                  decide not to open the image read-write as requested, but
3982 #                  fall back to read-only instead (and switch between the modes
3983 #                  later), e.g. depending on whether the image file is writable
3984 #                  or whether a writing user is attached to the node
3985 #                  (default: false, since 3.1)
3986 # @detect-zeroes: detect and optimize zero writes (Since 2.1)
3987 #                 (default: off)
3988 # @force-share: force share all permission on added nodes.
3989 #               Requires read-only=true. (Since 2.10)
3990 #
3991 # Remaining options are determined by the block driver.
3992 #
3993 # Since: 2.9
3994 ##
3995 { 'union': 'BlockdevOptions',
3996   'base': { 'driver': 'BlockdevDriver',
3997             '*node-name': 'str',
3998             '*discard': 'BlockdevDiscardOptions',
3999             '*cache': 'BlockdevCacheOptions',
4000             '*read-only': 'bool',
4001             '*auto-read-only': 'bool',
4002             '*force-share': 'bool',
4003             '*detect-zeroes': 'BlockdevDetectZeroesOptions' },
4004   'discriminator': 'driver',
4005   'data': {
4006       'blkdebug':   'BlockdevOptionsBlkdebug',
4007       'blklogwrites':'BlockdevOptionsBlklogwrites',
4008       'blkverify':  'BlockdevOptionsBlkverify',
4009       'blkreplay':  'BlockdevOptionsBlkreplay',
4010       'bochs':      'BlockdevOptionsGenericFormat',
4011       'cloop':      'BlockdevOptionsGenericFormat',
4012       'compress':   'BlockdevOptionsGenericFormat',
4013       'copy-on-read':'BlockdevOptionsCor',
4014       'dmg':        'BlockdevOptionsGenericFormat',
4015       'file':       'BlockdevOptionsFile',
4016       'ftp':        'BlockdevOptionsCurlFtp',
4017       'ftps':       'BlockdevOptionsCurlFtps',
4018       'gluster':    'BlockdevOptionsGluster',
4019       'host_cdrom': 'BlockdevOptionsFile',
4020       'host_device':'BlockdevOptionsFile',
4021       'http':       'BlockdevOptionsCurlHttp',
4022       'https':      'BlockdevOptionsCurlHttps',
4023       'iscsi':      'BlockdevOptionsIscsi',
4024       'luks':       'BlockdevOptionsLUKS',
4025       'nbd':        'BlockdevOptionsNbd',
4026       'nfs':        'BlockdevOptionsNfs',
4027       'null-aio':   'BlockdevOptionsNull',
4028       'null-co':    'BlockdevOptionsNull',
4029       'nvme':       'BlockdevOptionsNVMe',
4030       'parallels':  'BlockdevOptionsGenericFormat',
4031       'preallocate':'BlockdevOptionsPreallocate',
4032       'qcow2':      'BlockdevOptionsQcow2',
4033       'qcow':       'BlockdevOptionsQcow',
4034       'qed':        'BlockdevOptionsGenericCOWFormat',
4035       'quorum':     'BlockdevOptionsQuorum',
4036       'raw':        'BlockdevOptionsRaw',
4037       'rbd':        'BlockdevOptionsRbd',
4038       'replication': { 'type': 'BlockdevOptionsReplication',
4039                        'if': 'defined(CONFIG_REPLICATION)' },
4040       'sheepdog':   'BlockdevOptionsSheepdog',
4041       'ssh':        'BlockdevOptionsSsh',
4042       'throttle':   'BlockdevOptionsThrottle',
4043       'vdi':        'BlockdevOptionsGenericFormat',
4044       'vhdx':       'BlockdevOptionsGenericFormat',
4045       'vmdk':       'BlockdevOptionsGenericCOWFormat',
4046       'vpc':        'BlockdevOptionsGenericFormat',
4047       'vvfat':      'BlockdevOptionsVVFAT'
4048   } }
4049
4050 ##
4051 # @BlockdevRef:
4052 #
4053 # Reference to a block device.
4054 #
4055 # @definition: defines a new block device inline
4056 # @reference: references the ID of an existing block device
4057 #
4058 # Since: 2.9
4059 ##
4060 { 'alternate': 'BlockdevRef',
4061   'data': { 'definition': 'BlockdevOptions',
4062             'reference': 'str' } }
4063
4064 ##
4065 # @BlockdevRefOrNull:
4066 #
4067 # Reference to a block device.
4068 #
4069 # @definition: defines a new block device inline
4070 # @reference: references the ID of an existing block device.
4071 #             An empty string means that no block device should
4072 #             be referenced.  Deprecated; use null instead.
4073 # @null: No block device should be referenced (since 2.10)
4074 #
4075 # Since: 2.9
4076 ##
4077 { 'alternate': 'BlockdevRefOrNull',
4078   'data': { 'definition': 'BlockdevOptions',
4079             'reference': 'str',
4080             'null': 'null' } }
4081
4082 ##
4083 # @blockdev-add:
4084 #
4085 # Creates a new block device.
4086 #
4087 # Since: 2.9
4088 #
4089 # Example:
4090 #
4091 # 1.
4092 # -> { "execute": "blockdev-add",
4093 #      "arguments": {
4094 #           "driver": "qcow2",
4095 #           "node-name": "test1",
4096 #           "file": {
4097 #               "driver": "file",
4098 #               "filename": "test.qcow2"
4099 #            }
4100 #       }
4101 #     }
4102 # <- { "return": {} }
4103 #
4104 # 2.
4105 # -> { "execute": "blockdev-add",
4106 #      "arguments": {
4107 #           "driver": "qcow2",
4108 #           "node-name": "node0",
4109 #           "discard": "unmap",
4110 #           "cache": {
4111 #              "direct": true
4112 #            },
4113 #            "file": {
4114 #              "driver": "file",
4115 #              "filename": "/tmp/test.qcow2"
4116 #            },
4117 #            "backing": {
4118 #               "driver": "raw",
4119 #               "file": {
4120 #                  "driver": "file",
4121 #                  "filename": "/dev/fdset/4"
4122 #                }
4123 #            }
4124 #        }
4125 #      }
4126 #
4127 # <- { "return": {} }
4128 #
4129 ##
4130 { 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true }
4131
4132 ##
4133 # @x-blockdev-reopen:
4134 #
4135 # Reopens a block device using the given set of options. Any option
4136 # not specified will be reset to its default value regardless of its
4137 # previous status. If an option cannot be changed or a particular
4138 # driver does not support reopening then the command will return an
4139 # error.
4140 #
4141 # The top-level @node-name option (from BlockdevOptions) must be
4142 # specified and is used to select the block device to be reopened.
4143 # Other @node-name options must be either omitted or set to the
4144 # current name of the appropriate node. This command won't change any
4145 # node name and any attempt to do it will result in an error.
4146 #
4147 # In the case of options that refer to child nodes, the behavior of
4148 # this command depends on the value:
4149 #
4150 #  1) A set of options (BlockdevOptions): the child is reopened with
4151 #     the specified set of options.
4152 #
4153 #  2) A reference to the current child: the child is reopened using
4154 #     its existing set of options.
4155 #
4156 #  3) A reference to a different node: the current child is replaced
4157 #     with the specified one.
4158 #
4159 #  4) NULL: the current child (if any) is detached.
4160 #
4161 # Options (1) and (2) are supported in all cases, but at the moment
4162 # only @backing allows replacing or detaching an existing child.
4163 #
4164 # Unlike with blockdev-add, the @backing option must always be present
4165 # unless the node being reopened does not have a backing file and its
4166 # image does not have a default backing file name as part of its
4167 # metadata.
4168 #
4169 # Since: 4.0
4170 ##
4171 { 'command': 'x-blockdev-reopen',
4172   'data': 'BlockdevOptions', 'boxed': true }
4173
4174 ##
4175 # @blockdev-del:
4176 #
4177 # Deletes a block device that has been added using blockdev-add.
4178 # The command will fail if the node is attached to a device or is
4179 # otherwise being used.
4180 #
4181 # @node-name: Name of the graph node to delete.
4182 #
4183 # Since: 2.9
4184 #
4185 # Example:
4186 #
4187 # -> { "execute": "blockdev-add",
4188 #      "arguments": {
4189 #           "driver": "qcow2",
4190 #           "node-name": "node0",
4191 #           "file": {
4192 #               "driver": "file",
4193 #               "filename": "test.qcow2"
4194 #           }
4195 #      }
4196 #    }
4197 # <- { "return": {} }
4198 #
4199 # -> { "execute": "blockdev-del",
4200 #      "arguments": { "node-name": "node0" }
4201 #    }
4202 # <- { "return": {} }
4203 #
4204 ##
4205 { 'command': 'blockdev-del', 'data': { 'node-name': 'str' } }
4206
4207 ##
4208 # @BlockdevCreateOptionsFile:
4209 #
4210 # Driver specific image creation options for file.
4211 #
4212 # @filename: Filename for the new image file
4213 # @size: Size of the virtual disk in bytes
4214 # @preallocation: Preallocation mode for the new image (default: off;
4215 #                 allowed values: off,
4216 #                 falloc (if defined CONFIG_POSIX_FALLOCATE),
4217 #                 full (if defined CONFIG_POSIX))
4218 # @nocow: Turn off copy-on-write (valid only on btrfs; default: off)
4219 # @extent-size-hint: Extent size hint to add to the image file; 0 for not
4220 #                    adding an extent size hint (default: 1 MB, since 5.1)
4221 #
4222 # Since: 2.12
4223 ##
4224 { 'struct': 'BlockdevCreateOptionsFile',
4225   'data': { 'filename':             'str',
4226             'size':                 'size',
4227             '*preallocation':       'PreallocMode',
4228             '*nocow':               'bool',
4229             '*extent-size-hint':    'size'} }
4230
4231 ##
4232 # @BlockdevCreateOptionsGluster:
4233 #
4234 # Driver specific image creation options for gluster.
4235 #
4236 # @location: Where to store the new image file
4237 # @size: Size of the virtual disk in bytes
4238 # @preallocation: Preallocation mode for the new image (default: off;
4239 #                 allowed values: off,
4240 #                 falloc (if defined CONFIG_GLUSTERFS_FALLOCATE),
4241 #                 full (if defined CONFIG_GLUSTERFS_ZEROFILL))
4242 #
4243 # Since: 2.12
4244 ##
4245 { 'struct': 'BlockdevCreateOptionsGluster',
4246   'data': { 'location':         'BlockdevOptionsGluster',
4247             'size':             'size',
4248             '*preallocation':   'PreallocMode' } }
4249
4250 ##
4251 # @BlockdevCreateOptionsLUKS:
4252 #
4253 # Driver specific image creation options for LUKS.
4254 #
4255 # @file: Node to create the image format on
4256 # @size: Size of the virtual disk in bytes
4257 # @preallocation: Preallocation mode for the new image
4258 #                 (since: 4.2)
4259 #                 (default: off; allowed values: off, metadata, falloc, full)
4260 #
4261 # Since: 2.12
4262 ##
4263 { 'struct': 'BlockdevCreateOptionsLUKS',
4264   'base': 'QCryptoBlockCreateOptionsLUKS',
4265   'data': { 'file':             'BlockdevRef',
4266             'size':             'size',
4267             '*preallocation':   'PreallocMode' } }
4268
4269 ##
4270 # @BlockdevCreateOptionsNfs:
4271 #
4272 # Driver specific image creation options for NFS.
4273 #
4274 # @location: Where to store the new image file
4275 # @size: Size of the virtual disk in bytes
4276 #
4277 # Since: 2.12
4278 ##
4279 { 'struct': 'BlockdevCreateOptionsNfs',
4280   'data': { 'location':         'BlockdevOptionsNfs',
4281             'size':             'size' } }
4282
4283 ##
4284 # @BlockdevCreateOptionsParallels:
4285 #
4286 # Driver specific image creation options for parallels.
4287 #
4288 # @file: Node to create the image format on
4289 # @size: Size of the virtual disk in bytes
4290 # @cluster-size: Cluster size in bytes (default: 1 MB)
4291 #
4292 # Since: 2.12
4293 ##
4294 { 'struct': 'BlockdevCreateOptionsParallels',
4295   'data': { 'file':             'BlockdevRef',
4296             'size':             'size',
4297             '*cluster-size':    'size' } }
4298
4299 ##
4300 # @BlockdevCreateOptionsQcow:
4301 #
4302 # Driver specific image creation options for qcow.
4303 #
4304 # @file: Node to create the image format on
4305 # @size: Size of the virtual disk in bytes
4306 # @backing-file: File name of the backing file if a backing file
4307 #                should be used
4308 # @encrypt: Encryption options if the image should be encrypted
4309 #
4310 # Since: 2.12
4311 ##
4312 { 'struct': 'BlockdevCreateOptionsQcow',
4313   'data': { 'file':             'BlockdevRef',
4314             'size':             'size',
4315             '*backing-file':    'str',
4316             '*encrypt':         'QCryptoBlockCreateOptions' } }
4317
4318 ##
4319 # @BlockdevQcow2Version:
4320 #
4321 # @v2:  The original QCOW2 format as introduced in qemu 0.10 (version 2)
4322 # @v3:  The extended QCOW2 format as introduced in qemu 1.1 (version 3)
4323 #
4324 # Since: 2.12
4325 ##
4326 { 'enum': 'BlockdevQcow2Version',
4327   'data': [ 'v2', 'v3' ] }
4328
4329
4330 ##
4331 # @Qcow2CompressionType:
4332 #
4333 # Compression type used in qcow2 image file
4334 #
4335 # @zlib: zlib compression, see <http://zlib.net/>
4336 # @zstd: zstd compression, see <http://github.com/facebook/zstd>
4337 #
4338 # Since: 5.1
4339 ##
4340 { 'enum': 'Qcow2CompressionType',
4341   'data': [ 'zlib', { 'name': 'zstd', 'if': 'defined(CONFIG_ZSTD)' } ] }
4342
4343 ##
4344 # @BlockdevCreateOptionsQcow2:
4345 #
4346 # Driver specific image creation options for qcow2.