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