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