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