blob: aa40d44f1db6b1fa0a18b6b095cacb8d9d19c040 [file] [log] [blame]
Benoît Canet5db15092014-06-05 13:45:30 +02001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Marc-André Lureaud3a48372017-01-13 15:41:23 +01003
4##
Markus Armbrusterf5cf31c2017-08-24 21:14:08 +02005# == Block core (VM unrelated)
Marc-André Lureaud3a48372017-01-13 15:41:23 +01006##
Benoît Canet5db15092014-06-05 13:45:30 +02007
Benoît Canet5db15092014-06-05 13:45:30 +02008{ 'include': 'common.json' }
Markus Armbruster2031c132017-08-24 21:14:06 +02009{ 'include': 'crypto.json' }
Kevin Wolfbf425082018-05-16 16:03:10 +020010{ 'include': 'job.json' }
Markus Armbrustera2ff5a42017-08-24 21:13:56 +020011{ 'include': 'sockets.json' }
Benoît Canet1ad166b2014-06-05 13:45:31 +020012
13##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +040014# @SnapshotInfo:
Benoît Canet1ad166b2014-06-05 13:45:31 +020015#
16# @id: unique snapshot id
17#
18# @name: user chosen name
19#
20# @vm-state-size: size of the VM state
21#
22# @date-sec: UTC date of the snapshot in seconds
23#
24# @date-nsec: fractional part in nano seconds to be used with date-sec
25#
26# @vm-clock-sec: VM clock relative to boot in seconds
27#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020028# @vm-clock-nsec: fractional part in nano seconds to be used with
29# vm-clock-sec
Benoît Canet1ad166b2014-06-05 13:45:31 +020030#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020031# @icount: Current instruction count. Appears when execution
32# record/replay is enabled. Used for "time-traveling" to match
33# the moment in the recorded execution with the snapshots. This
34# counter may be obtained through @query-replay command (since
35# 5.2)
Pavel Dovgalyukb39847a2020-10-03 20:13:08 +030036#
Benoît Canet1ad166b2014-06-05 13:45:31 +020037# Since: 1.3
Benoît Canet1ad166b2014-06-05 13:45:31 +020038##
Eric Blake895a2a82015-05-04 09:05:27 -060039{ 'struct': 'SnapshotInfo',
Benoît Canet1ad166b2014-06-05 13:45:31 +020040 'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int',
41 'date-sec': 'int', 'date-nsec': 'int',
Pavel Dovgalyukb39847a2020-10-03 20:13:08 +030042 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int',
43 '*icount': 'int' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +020044
45##
Daniel P. Berrange0a12f6f2017-06-23 17:24:18 +010046# @ImageInfoSpecificQCow2EncryptionBase:
47#
48# @format: The encryption format
49#
50# Since: 2.10
51##
52{ 'struct': 'ImageInfoSpecificQCow2EncryptionBase',
53 'data': { 'format': 'BlockdevQcow2EncryptionFormat'}}
54
55##
56# @ImageInfoSpecificQCow2Encryption:
57#
58# Since: 2.10
59##
60{ 'union': 'ImageInfoSpecificQCow2Encryption',
61 'base': 'ImageInfoSpecificQCow2EncryptionBase',
62 'discriminator': 'format',
Anton Nefedov29cd0402018-06-18 11:40:06 +030063 'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
Daniel P. Berrange0a12f6f2017-06-23 17:24:18 +010064
65##
Benoît Canet1ad166b2014-06-05 13:45:31 +020066# @ImageInfoSpecificQCow2:
67#
68# @compat: compatibility level
69#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020070# @data-file: the filename of the external data file that is stored in
71# the image and used as a default for opening the image
72# (since: 4.0)
Kevin Wolf9b890bd2019-01-15 19:02:40 +010073#
Kevin Wolf6c3944d2019-02-22 14:29:38 +010074# @data-file-raw: True if the external data file must stay valid as a
Markus Armbrustera937b6a2023-04-28 12:54:29 +020075# standalone (read-only) raw image without looking at qcow2
76# metadata (since: 4.0)
Kevin Wolf6c3944d2019-02-22 14:29:38 +010077#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020078# @extended-l2: true if the image has extended L2 entries; only valid
79# for compat >= 1.1 (since 5.2)
Alberto Garcia7be20252020-07-10 18:13:13 +020080#
Markus Armbruster1d8bda12017-03-15 13:57:06 +010081# @lazy-refcounts: on or off; only valid for compat >= 1.1
Benoît Canet1ad166b2014-06-05 13:45:31 +020082#
Markus Armbruster1d8bda12017-03-15 13:57:06 +010083# @corrupt: true if the image has been marked corrupt; only valid for
Markus Armbrustera937b6a2023-04-28 12:54:29 +020084# compat >= 1.1 (since 2.2)
Max Reitz9009b192014-09-30 21:31:28 +020085#
Max Reitz0709c5a2015-02-10 15:28:44 -050086# @refcount-bits: width of a refcount entry in bits (since 2.3)
87#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020088# @encrypt: details about encryption parameters; only set if image is
89# encrypted (since 2.10)
Daniel P. Berrange0a12f6f2017-06-23 17:24:18 +010090#
Andrey Shinkevichb8968c82019-02-08 18:06:07 +030091# @bitmaps: A list of qcow2 bitmap details (since 4.0)
92#
Denis Plotnikov572ad972020-05-07 11:25:18 +030093# @compression-type: the image cluster compression method (since 5.1)
94#
Benoît Canet1ad166b2014-06-05 13:45:31 +020095# Since: 1.7
96##
Eric Blake895a2a82015-05-04 09:05:27 -060097{ 'struct': 'ImageInfoSpecificQCow2',
Benoît Canet1ad166b2014-06-05 13:45:31 +020098 'data': {
99 'compat': 'str',
Kevin Wolf9b890bd2019-01-15 19:02:40 +0100100 '*data-file': 'str',
Kevin Wolf6c3944d2019-02-22 14:29:38 +0100101 '*data-file-raw': 'bool',
Alberto Garcia7be20252020-07-10 18:13:13 +0200102 '*extended-l2': 'bool',
Max Reitz9009b192014-09-30 21:31:28 +0200103 '*lazy-refcounts': 'bool',
Max Reitz0709c5a2015-02-10 15:28:44 -0500104 '*corrupt': 'bool',
Daniel P. Berrange0a12f6f2017-06-23 17:24:18 +0100105 'refcount-bits': 'int',
Andrey Shinkevichb8968c82019-02-08 18:06:07 +0300106 '*encrypt': 'ImageInfoSpecificQCow2Encryption',
Denis Plotnikov572ad972020-05-07 11:25:18 +0300107 '*bitmaps': ['Qcow2BitmapInfo'],
108 'compression-type': 'Qcow2CompressionType'
Benoît Canet1ad166b2014-06-05 13:45:31 +0200109 } }
110
111##
112# @ImageInfoSpecificVmdk:
113#
114# @create-type: The create type of VMDK image
115#
116# @cid: Content id of image
117#
118# @parent-cid: Parent VMDK image's cid
119#
120# @extents: List of extent files
121#
122# Since: 1.7
123##
Eric Blake895a2a82015-05-04 09:05:27 -0600124{ 'struct': 'ImageInfoSpecificVmdk',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200125 'data': {
126 'create-type': 'str',
127 'cid': 'int',
128 'parent-cid': 'int',
Hanna Reitz456e7512022-06-20 18:26:55 +0200129 'extents': ['VmdkExtentInfo']
130 } }
131
132##
133# @VmdkExtentInfo:
134#
135# Information about a VMDK extent file
136#
137# @filename: Name of the extent file
138#
Markus Armbruster9e272072023-07-20 09:16:09 +0200139# @format: Extent type (e.g. FLAT or SPARSE)
Hanna Reitz456e7512022-06-20 18:26:55 +0200140#
141# @virtual-size: Number of bytes covered by this extent
142#
143# @cluster-size: Cluster size in bytes (for non-flat extents)
144#
145# @compressed: Whether this extent contains compressed data
146#
147# Since: 8.0
148##
149{ 'struct': 'VmdkExtentInfo',
150 'data': {
151 'filename': 'str',
152 'format': 'str',
153 'virtual-size': 'int',
154 '*cluster-size': 'int',
155 '*compressed': 'bool'
Benoît Canet1ad166b2014-06-05 13:45:31 +0200156 } }
157
158##
Or Ozeri42e4ac92021-06-27 14:46:35 +0300159# @ImageInfoSpecificRbd:
160#
161# @encryption-format: Image encryption format
162#
163# Since: 6.1
164##
165{ 'struct': 'ImageInfoSpecificRbd',
166 'data': {
167 '*encryption-format': 'RbdImageEncryptionFormat'
168 } }
169
170##
Hanna Reitz7f36a502022-06-20 18:26:54 +0200171# @ImageInfoSpecificFile:
172#
173# @extent-size-hint: Extent size hint (if available)
174#
175# Since: 8.0
176##
177{ 'struct': 'ImageInfoSpecificFile',
178 'data': {
179 '*extent-size-hint': 'size'
180 } }
181
182##
Markus Armbruster0db4f502021-09-17 16:31:20 +0200183# @ImageInfoSpecificKind:
184#
185# @luks: Since 2.7
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200186#
Markus Armbruster0db4f502021-09-17 16:31:20 +0200187# @rbd: Since 6.1
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200188#
Hanna Reitz7f36a502022-06-20 18:26:54 +0200189# @file: Since 8.0
Markus Armbruster0db4f502021-09-17 16:31:20 +0200190#
191# Since: 1.7
192##
193{ 'enum': 'ImageInfoSpecificKind',
Hanna Reitz7f36a502022-06-20 18:26:54 +0200194 'data': [ 'qcow2', 'vmdk', 'luks', 'rbd', 'file' ] }
Markus Armbruster0db4f502021-09-17 16:31:20 +0200195
196##
197# @ImageInfoSpecificQCow2Wrapper:
198#
Markus Armbruster2fecccb2024-02-05 08:47:06 +0100199# @data: image information specific to QCOW2
200#
Markus Armbruster0db4f502021-09-17 16:31:20 +0200201# Since: 1.7
202##
203{ 'struct': 'ImageInfoSpecificQCow2Wrapper',
204 'data': { 'data': 'ImageInfoSpecificQCow2' } }
205
206##
207# @ImageInfoSpecificVmdkWrapper:
208#
Markus Armbruster2fecccb2024-02-05 08:47:06 +0100209# @data: image information specific to VMDK
210#
Markus Armbruster0db4f502021-09-17 16:31:20 +0200211# Since: 6.1
212##
213{ 'struct': 'ImageInfoSpecificVmdkWrapper',
214 'data': { 'data': 'ImageInfoSpecificVmdk' } }
215
216##
217# @ImageInfoSpecificLUKSWrapper:
218#
Markus Armbruster2fecccb2024-02-05 08:47:06 +0100219# @data: image information specific to LUKS
220#
Markus Armbruster0db4f502021-09-17 16:31:20 +0200221# Since: 2.7
222##
223{ 'struct': 'ImageInfoSpecificLUKSWrapper',
224 'data': { 'data': 'QCryptoBlockInfoLUKS' } }
225# If we need to add block driver specific parameters for
226# LUKS in future, then we'll subclass QCryptoBlockInfoLUKS
227# to define a ImageInfoSpecificLUKS
228
229##
230# @ImageInfoSpecificRbdWrapper:
231#
Markus Armbruster2fecccb2024-02-05 08:47:06 +0100232# @data: image information specific to RBD
233#
Markus Armbruster0db4f502021-09-17 16:31:20 +0200234# Since: 6.1
235##
236{ 'struct': 'ImageInfoSpecificRbdWrapper',
237 'data': { 'data': 'ImageInfoSpecificRbd' } }
238
239##
Hanna Reitz7f36a502022-06-20 18:26:54 +0200240# @ImageInfoSpecificFileWrapper:
241#
Markus Armbruster2fecccb2024-02-05 08:47:06 +0100242# @data: image information specific to files
243#
Hanna Reitz7f36a502022-06-20 18:26:54 +0200244# Since: 8.0
245##
246{ 'struct': 'ImageInfoSpecificFileWrapper',
247 'data': { 'data': 'ImageInfoSpecificFile' } }
248
249##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200250# @ImageInfoSpecific:
251#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200252# A discriminated record of image format specific information
253# structures.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200254#
Markus Armbruster89a22732024-02-05 08:47:09 +0100255# @type: block driver name
256#
Benoît Canet1ad166b2014-06-05 13:45:31 +0200257# Since: 1.7
258##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200259{ 'union': 'ImageInfoSpecific',
Markus Armbruster0db4f502021-09-17 16:31:20 +0200260 'base': { 'type': 'ImageInfoSpecificKind' },
261 'discriminator': 'type',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200262 'data': {
Markus Armbruster0db4f502021-09-17 16:31:20 +0200263 'qcow2': 'ImageInfoSpecificQCow2Wrapper',
264 'vmdk': 'ImageInfoSpecificVmdkWrapper',
265 'luks': 'ImageInfoSpecificLUKSWrapper',
Hanna Reitz7f36a502022-06-20 18:26:54 +0200266 'rbd': 'ImageInfoSpecificRbdWrapper',
267 'file': 'ImageInfoSpecificFileWrapper'
Benoît Canet1ad166b2014-06-05 13:45:31 +0200268 } }
269
270##
Hanna Reitza2085f82022-06-20 18:26:56 +0200271# @BlockNodeInfo:
Benoît Canet1ad166b2014-06-05 13:45:31 +0200272#
273# Information about a QEMU image file
274#
275# @filename: name of the image file
276#
277# @format: format of the image file
278#
279# @virtual-size: maximum capacity in bytes of the image
280#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100281# @actual-size: actual size on disk in bytes of the image
Benoît Canet1ad166b2014-06-05 13:45:31 +0200282#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100283# @dirty-flag: true if image is not cleanly closed
Benoît Canet1ad166b2014-06-05 13:45:31 +0200284#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100285# @cluster-size: size of a cluster in bytes
Benoît Canet1ad166b2014-06-05 13:45:31 +0200286#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100287# @encrypted: true if the image is encrypted
Benoît Canet1ad166b2014-06-05 13:45:31 +0200288#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100289# @compressed: true if the image is compressed (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200290#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100291# @backing-filename: name of the backing file
Benoît Canet1ad166b2014-06-05 13:45:31 +0200292#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100293# @full-backing-filename: full path of the backing file
Benoît Canet1ad166b2014-06-05 13:45:31 +0200294#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100295# @backing-filename-format: the format of the backing file
Benoît Canet1ad166b2014-06-05 13:45:31 +0200296#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100297# @snapshots: list of VM snapshots
Benoît Canet1ad166b2014-06-05 13:45:31 +0200298#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100299# @format-specific: structure supplying additional format-specific
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200300# information (since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200301#
Hanna Reitza2085f82022-06-20 18:26:56 +0200302# Since: 8.0
Benoît Canet1ad166b2014-06-05 13:45:31 +0200303##
Hanna Reitza2085f82022-06-20 18:26:56 +0200304{ 'struct': 'BlockNodeInfo',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200305 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool',
306 '*actual-size': 'int', 'virtual-size': 'int',
307 '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool',
308 '*backing-filename': 'str', '*full-backing-filename': 'str',
309 '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'],
Kevin Wolf24bf10d2014-11-21 17:43:57 +0100310 '*format-specific': 'ImageInfoSpecific' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +0200311
312##
Hanna Reitza2085f82022-06-20 18:26:56 +0200313# @ImageInfo:
314#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200315# Information about a QEMU image file, and potentially its backing
316# image
Hanna Reitza2085f82022-06-20 18:26:56 +0200317#
318# @backing-image: info of the backing image
319#
320# Since: 1.3
321##
322{ 'struct': 'ImageInfo',
323 'base': 'BlockNodeInfo',
324 'data': {
325 '*backing-image': 'ImageInfo'
326 } }
327
328##
Hanna Reitz6cab3392022-06-20 18:26:59 +0200329# @BlockChildInfo:
330#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200331# Information about all nodes in the block graph starting at some
332# node, annotated with information about that node in relation to its
333# parent.
Hanna Reitz6cab3392022-06-20 18:26:59 +0200334#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200335# @name: Child name of the root node in the BlockGraphInfo struct, in
336# its role as the child of some undescribed parent node
Hanna Reitz6cab3392022-06-20 18:26:59 +0200337#
338# @info: Block graph information starting at this node
339#
340# Since: 8.0
341##
342{ 'struct': 'BlockChildInfo',
343 'data': {
344 'name': 'str',
345 'info': 'BlockGraphInfo'
346 } }
347
348##
349# @BlockGraphInfo:
350#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200351# Information about all nodes in a block (sub)graph in the form of
352# BlockNodeInfo data. The base BlockNodeInfo struct contains the
353# information for the (sub)graph's root node.
Hanna Reitz6cab3392022-06-20 18:26:59 +0200354#
355# @children: Array of links to this node's child nodes' information
356#
357# Since: 8.0
358##
359{ 'struct': 'BlockGraphInfo',
360 'base': 'BlockNodeInfo',
361 'data': { 'children': ['BlockChildInfo'] } }
362
363##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200364# @ImageCheck:
365#
366# Information about a QEMU image file check
367#
368# @filename: name of the image file checked
369#
370# @format: format of the image file checked
371#
372# @check-errors: number of unexpected errors occurred during check
373#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100374# @image-end-offset: offset (in bytes) where the image ends, this
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200375# field is present if the driver for the image format supports it
Benoît Canet1ad166b2014-06-05 13:45:31 +0200376#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100377# @corruptions: number of corruptions found during the check if any
Benoît Canet1ad166b2014-06-05 13:45:31 +0200378#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100379# @leaks: number of leaks found during the check if any
Benoît Canet1ad166b2014-06-05 13:45:31 +0200380#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200381# @corruptions-fixed: number of corruptions fixed during the check if
382# any
Benoît Canet1ad166b2014-06-05 13:45:31 +0200383#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100384# @leaks-fixed: number of leaks fixed during the check if any
Benoît Canet1ad166b2014-06-05 13:45:31 +0200385#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200386# @total-clusters: total number of clusters, this field is present if
387# the driver for the image format supports it
Benoît Canet1ad166b2014-06-05 13:45:31 +0200388#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200389# @allocated-clusters: total number of allocated clusters, this field
390# is present if the driver for the image format supports it
Benoît Canet1ad166b2014-06-05 13:45:31 +0200391#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100392# @fragmented-clusters: total number of fragmented clusters, this
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200393# field is present if the driver for the image format supports it
Benoît Canet1ad166b2014-06-05 13:45:31 +0200394#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100395# @compressed-clusters: total number of compressed clusters, this
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200396# field is present if the driver for the image format supports it
Benoît Canet1ad166b2014-06-05 13:45:31 +0200397#
398# Since: 1.4
Benoît Canet1ad166b2014-06-05 13:45:31 +0200399##
Eric Blake895a2a82015-05-04 09:05:27 -0600400{ 'struct': 'ImageCheck',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200401 'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int',
402 '*image-end-offset': 'int', '*corruptions': 'int', '*leaks': 'int',
403 '*corruptions-fixed': 'int', '*leaks-fixed': 'int',
404 '*total-clusters': 'int', '*allocated-clusters': 'int',
405 '*fragmented-clusters': 'int', '*compressed-clusters': 'int' } }
406
407##
Fam Zheng16b0d552016-01-26 11:59:02 +0800408# @MapEntry:
409#
410# Mapping information from a virtual block range to a host file range
411#
Max Reitzffb515f2020-11-04 17:55:12 +0100412# @start: virtual (guest) offset of the first byte described by this
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200413# entry
Fam Zheng16b0d552016-01-26 11:59:02 +0800414#
415# @length: the number of bytes of the mapped virtual range
416#
Max Reitzffb515f2020-11-04 17:55:12 +0100417# @data: reading the image will actually read data from a file (in
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200418# particular, if @offset is present this means that the sectors
419# are not simply preallocated, but contain actual data in raw
420# format)
Fam Zheng16b0d552016-01-26 11:59:02 +0800421#
Max Reitzffb515f2020-11-04 17:55:12 +0100422# @zero: whether the virtual blocks read as zeroes
Fam Zheng16b0d552016-01-26 11:59:02 +0800423#
Andrey Drobyshev via52b10c92023-09-08 00:02:26 +0300424# @compressed: true if the data is stored compressed (since 8.2)
425#
Max Reitzffb515f2020-11-04 17:55:12 +0100426# @depth: number of layers (0 = top image, 1 = top image's backing
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200427# file, ..., n - 1 = bottom image (where n is the number of images
428# in the chain)) before reaching one for which the range is
429# allocated
Fam Zheng16b0d552016-01-26 11:59:02 +0800430#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200431# @present: true if this layer provides the data, false if adding a
432# backing layer could impact this region (since 6.1)
Eric Blake8417e132021-07-01 14:06:55 -0500433#
Max Reitzffb515f2020-11-04 17:55:12 +0100434# @offset: if present, the image file stores the data for this range
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200435# in raw format at the given (host) offset
Fam Zheng16b0d552016-01-26 11:59:02 +0800436#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100437# @filename: filename that is referred to by @offset
Fam Zheng16b0d552016-01-26 11:59:02 +0800438#
439# Since: 2.6
Fam Zheng16b0d552016-01-26 11:59:02 +0800440##
441{ 'struct': 'MapEntry',
442 'data': {'start': 'int', 'length': 'int', 'data': 'bool',
Andrey Drobyshev via52b10c92023-09-08 00:02:26 +0300443 'zero': 'bool', 'compressed': 'bool', 'depth': 'int',
444 'present': 'bool', '*offset': 'int', '*filename': 'str' } }
Fam Zheng16b0d552016-01-26 11:59:02 +0800445
446##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +0400447# @BlockdevCacheInfo:
Kevin Wolf9e193c52014-05-22 13:28:45 +0200448#
449# Cache mode information for a block device
450#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200451# @writeback: true if writeback mode is enabled
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200452#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200453# @direct: true if the host page cache is bypassed (O_DIRECT)
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200454#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200455# @no-flush: true if flush requests are ignored for the device
Kevin Wolf9e193c52014-05-22 13:28:45 +0200456#
457# Since: 2.3
458##
Eric Blake895a2a82015-05-04 09:05:27 -0600459{ 'struct': 'BlockdevCacheInfo',
Kevin Wolf9e193c52014-05-22 13:28:45 +0200460 'data': { 'writeback': 'bool',
461 'direct': 'bool',
462 'no-flush': 'bool' } }
463
464##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200465# @BlockDeviceInfo:
466#
467# Information about the backing device for a block device.
468#
469# @file: the filename of the backing device
470#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100471# @node-name: the name of the block driver node (Since 2.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200472#
473# @ro: true if the backing device was open read-only
474#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200475# @drv: the name of the block format used to open the backing device.
476# As of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow',
477# 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom',
478# 'host_device', 'http', 'https', 'luks', 'nbd', 'parallels',
479# 'qcow', 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2:
480# 'archipelago' added, 'cow' dropped 2.3: 'host_floppy' deprecated
481# 2.5: 'host_floppy' dropped 2.6: 'luks' added 2.8: 'replication'
482# added, 'tftp' dropped 2.9: 'archipelago' dropped
Benoît Canet1ad166b2014-06-05 13:45:31 +0200483#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100484# @backing_file: the name of the backing file (for copy-on-write)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200485#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200486# @backing_file_depth: number of files in the backing file chain
487# (since: 1.2)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200488#
489# @encrypted: true if the backing device is encrypted
490#
Benoît Canet1ad166b2014-06-05 13:45:31 +0200491# @detect_zeroes: detect and optimize zero writes (Since 2.1)
492#
493# @bps: total throughput limit in bytes per second is specified
494#
495# @bps_rd: read throughput limit in bytes per second is specified
496#
497# @bps_wr: write throughput limit in bytes per second is specified
498#
499# @iops: total I/O operations per second is specified
500#
501# @iops_rd: read I/O operations per second is specified
502#
503# @iops_wr: write I/O operations per second is specified
504#
505# @image: the info of image used (since: 1.6)
506#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200507# @bps_max: total throughput limit during bursts, in bytes (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200508#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200509# @bps_rd_max: read throughput limit during bursts, in bytes (Since
510# 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200511#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200512# @bps_wr_max: write throughput limit during bursts, in bytes (Since
513# 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200514#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200515# @iops_max: total I/O operations per second during bursts, in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200516# (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200517#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200518# @iops_rd_max: read I/O operations per second during bursts, in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200519# (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200520#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200521# @iops_wr_max: write I/O operations per second during bursts, in
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200522# bytes (Since 1.7)
Alberto Garcia398befd2016-02-18 12:27:04 +0200523#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200524# @bps_max_length: maximum length of the @bps_max burst period, in
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200525# seconds. (Since 2.6)
Alberto Garcia398befd2016-02-18 12:27:04 +0200526#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200527# @bps_rd_max_length: maximum length of the @bps_rd_max burst period,
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200528# in seconds. (Since 2.6)
Alberto Garcia398befd2016-02-18 12:27:04 +0200529#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200530# @bps_wr_max_length: maximum length of the @bps_wr_max burst period,
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200531# in seconds. (Since 2.6)
Alberto Garcia398befd2016-02-18 12:27:04 +0200532#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200533# @iops_max_length: maximum length of the @iops burst period, in
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200534# seconds. (Since 2.6)
Alberto Garcia398befd2016-02-18 12:27:04 +0200535#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200536# @iops_rd_max_length: maximum length of the @iops_rd_max burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200537# period, in seconds. (Since 2.6)
Alberto Garcia398befd2016-02-18 12:27:04 +0200538#
Markus Armbrusterf2de3b92023-04-25 08:42:17 +0200539# @iops_wr_max_length: maximum length of the @iops_wr_max burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200540# period, in seconds. (Since 2.6)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200541#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100542# @iops_size: an I/O size in bytes (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200543#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100544# @group: throttle group name (Since 2.4)
Alberto Garciab8fe1692015-06-08 18:17:46 +0200545#
Kevin Wolf9e193c52014-05-22 13:28:45 +0200546# @cache: the cache mode used for the block device (since: 2.3)
547#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200548# @write_threshold: configured write threshold for the device. 0 if
549# disabled. (Since 2.3)
Francesco Romanie2462112015-01-12 14:11:13 +0100550#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200551# @dirty-bitmaps: dirty bitmaps information (only present if node has
552# one or more dirty bitmaps) (Since 4.2)
Vladimir Sementsov-Ogievskiy590a63d2019-07-29 16:35:56 -0400553#
Markus Armbruster9bc6e892020-11-18 07:41:58 +0100554# Since: 0.14
Benoît Canet1ad166b2014-06-05 13:45:31 +0200555##
Eric Blake895a2a82015-05-04 09:05:27 -0600556{ 'struct': 'BlockDeviceInfo',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200557 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str',
558 '*backing_file': 'str', 'backing_file_depth': 'int',
Markus Armbrusterdf4097a2020-03-17 12:54:51 +0100559 'encrypted': 'bool',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200560 'detect_zeroes': 'BlockdevDetectZeroesOptions',
561 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
562 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
563 'image': 'ImageInfo',
564 '*bps_max': 'int', '*bps_rd_max': 'int',
565 '*bps_wr_max': 'int', '*iops_max': 'int',
566 '*iops_rd_max': 'int', '*iops_wr_max': 'int',
Alberto Garcia398befd2016-02-18 12:27:04 +0200567 '*bps_max_length': 'int', '*bps_rd_max_length': 'int',
568 '*bps_wr_max_length': 'int', '*iops_max_length': 'int',
569 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int',
Alberto Garciab8fe1692015-06-08 18:17:46 +0200570 '*iops_size': 'int', '*group': 'str', 'cache': 'BlockdevCacheInfo',
Vladimir Sementsov-Ogievskiy590a63d2019-07-29 16:35:56 -0400571 'write_threshold': 'int', '*dirty-bitmaps': ['BlockDirtyInfo'] } }
Benoît Canet1ad166b2014-06-05 13:45:31 +0200572
573##
574# @BlockDeviceIoStatus:
575#
576# An enumeration of block device I/O status.
577#
578# @ok: The last I/O operation has succeeded
579#
580# @failed: The last I/O operation has failed
581#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200582# @nospace: The last I/O operation has failed due to a no-space
583# condition
Benoît Canet1ad166b2014-06-05 13:45:31 +0200584#
585# Since: 1.0
586##
587{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
588
589##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200590# @BlockDirtyInfo:
591#
592# Block dirty bitmap information.
593#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100594# @name: the name of the dirty bitmap (Since 2.4)
Fam Zheng0db6e542015-04-17 19:49:50 -0400595#
Benoît Canet1ad166b2014-06-05 13:45:31 +0200596# @count: number of dirty bytes according to the dirty bitmap
597#
598# @granularity: granularity of the dirty bitmap in bytes (since 1.4)
599#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200600# @recording: true if the bitmap is recording new writes from the
601# guest. (since 4.0)
John Snow4db6ceb2019-03-12 12:05:48 -0400602#
603# @busy: true if the bitmap is in-use by some operation (NBD or jobs)
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200604# and cannot be modified via QMP or used by another operation.
605# (since 4.0)
John Snowa1135342015-04-17 19:50:00 -0400606#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200607# @persistent: true if the bitmap was stored on disk, is scheduled to
608# be stored on disk, or both. (since 4.0)
John Snowb0f45552019-03-12 12:05:49 -0400609#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200610# @inconsistent: true if this is a persistent bitmap that was
611# improperly stored. Implies @persistent to be true; @recording
612# and @busy to be false. This bitmap cannot be used. To remove
613# it, use @block-dirty-bitmap-remove. (Since 4.0)
Eric Blakef67cf662019-02-19 17:49:43 -0500614#
Benoît Canet1ad166b2014-06-05 13:45:31 +0200615# Since: 1.3
616##
Eric Blake895a2a82015-05-04 09:05:27 -0600617{ 'struct': 'BlockDirtyInfo',
John Snowa1135342015-04-17 19:50:00 -0400618 'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32',
Markus Armbrusterdf4097a2020-03-17 12:54:51 +0100619 'recording': 'bool', 'busy': 'bool',
John Snowb0f45552019-03-12 12:05:49 -0400620 'persistent': 'bool', '*inconsistent': 'bool' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +0200621
622##
Andrey Shinkevichb8968c82019-02-08 18:06:07 +0300623# @Qcow2BitmapInfoFlags:
624#
625# An enumeration of flags that a bitmap can report to the user.
626#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200627# @in-use: This flag is set by any process actively modifying the
628# qcow2 file, and cleared when the updated bitmap is flushed to
629# the qcow2 image. The presence of this flag in an offline image
630# means that the bitmap was not saved correctly after its last
631# usage, and may contain inconsistent data.
Andrey Shinkevichb8968c82019-02-08 18:06:07 +0300632#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200633# @auto: The bitmap must reflect all changes of the virtual disk by
634# any application that would write to this qcow2 file.
Andrey Shinkevichb8968c82019-02-08 18:06:07 +0300635#
636# Since: 4.0
637##
638{ 'enum': 'Qcow2BitmapInfoFlags',
639 'data': ['in-use', 'auto'] }
640
641##
642# @Qcow2BitmapInfo:
643#
644# Qcow2 bitmap information.
645#
646# @name: the name of the bitmap
647#
648# @granularity: granularity of the bitmap in bytes
649#
650# @flags: flags of the bitmap
651#
652# Since: 4.0
653##
654{ 'struct': 'Qcow2BitmapInfo',
655 'data': {'name': 'str', 'granularity': 'uint32',
656 'flags': ['Qcow2BitmapInfoFlags'] } }
657
658##
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +0300659# @BlockLatencyHistogramInfo:
660#
661# Block latency histogram.
662#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200663# @boundaries: list of interval boundary values in nanoseconds, all
664# greater than zero and in ascending order. For example, the list
665# [10, 50, 100] produces the following histogram intervals: [0,
666# 10), [10, 50), [50, 100), [100, +inf).
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +0300667#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200668# @bins: list of io request counts corresponding to histogram
Markus Armbrusterdad3c952023-07-20 09:16:04 +0200669# intervals, one more element than @boundaries has. For the
670# example above, @bins may be something like [3, 1, 5, 2], and
Markus Armbrusterd9884872024-02-05 08:46:57 +0100671# corresponding histogram looks like::
Peter Maydella0fcff32020-09-25 17:23:05 +0100672#
673# 5| *
674# 4| *
675# 3| * *
676# 2| * * *
677# 1| * * * *
678# +------------------
679# 10 50 100
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +0300680#
Vladimir Sementsov-Ogievskiycb8aac32019-03-05 15:53:17 +0300681# Since: 4.0
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +0300682##
683{ 'struct': 'BlockLatencyHistogramInfo',
684 'data': {'boundaries': ['uint64'], 'bins': ['uint64'] } }
685
686##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200687# @BlockInfo:
688#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200689# Block device information. This structure describes a virtual device
690# and the backing device associated with it.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200691#
692# @device: The device name associated with the virtual device.
693#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200694# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the
695# block device. (since 2.10)
Kevin Wolf46eade72017-07-11 13:27:38 +0200696#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200697# @type: This field is returned only for compatibility reasons, it
698# should not be used (always returns 'unknown')
Benoît Canet1ad166b2014-06-05 13:45:31 +0200699#
700# @removable: True if the device supports removable media.
701#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200702# @locked: True if the guest has locked this device from having its
703# media removed
Benoît Canet1ad166b2014-06-05 13:45:31 +0200704#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200705# @tray_open: True if the device's tray is open (only present if it
706# has a tray)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200707#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200708# @io-status: @BlockDeviceIoStatus. Only present if the device
709# supports it and the VM is configured to stop on errors
710# (supported device models: virtio-blk, IDE, SCSI except
711# scsi-generic)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200712#
Markus Armbruster1d8bda12017-03-15 13:57:06 +0100713# @inserted: @BlockDeviceInfo describing the device if media is
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200714# present
Benoît Canet1ad166b2014-06-05 13:45:31 +0200715#
Andrea Bolognani23e46452022-05-03 09:37:35 +0200716# Since: 0.14
Benoît Canet1ad166b2014-06-05 13:45:31 +0200717##
Eric Blake895a2a82015-05-04 09:05:27 -0600718{ 'struct': 'BlockInfo',
Kevin Wolf46eade72017-07-11 13:27:38 +0200719 'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool',
Benoît Canet1ad166b2014-06-05 13:45:31 +0200720 'locked': 'bool', '*inserted': 'BlockDeviceInfo',
Daniel P. Berrangée67d8e22021-02-19 19:22:36 +0000721 '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +0200722
723##
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100724# @BlockMeasureInfo:
725#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200726# Image file size calculation information. This structure describes
727# the size requirements for creating a new image file.
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100728#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200729# The size requirements depend on the new image file format. File
730# size always equals virtual disk size for the 'raw' format, even for
731# sparse POSIX files. Compact formats such as 'qcow2' represent
732# unallocated and zero regions efficiently so file size may be smaller
733# than virtual disk size.
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100734#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200735# The values are upper bounds that are guaranteed to fit the new image
736# file. Subsequent modification, such as internal snapshot or further
737# bitmap creation, may require additional space and is not covered
738# here.
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100739#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200740# @required: Size required for a new image file, in bytes, when
741# copying just allocated guest-visible contents.
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100742#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200743# @fully-allocated: Image file size, in bytes, once data has been
744# written to all sectors, when copying just guest-visible
745# contents.
Eric Blake5d72c682020-05-21 14:21:34 -0500746#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200747# @bitmaps: Additional size required if all the top-level bitmap
748# metadata in the source image were to be copied to the
749# destination, present only when source and destination both
750# support persistent bitmaps. (since 5.1)
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100751#
752# Since: 2.10
753##
754{ 'struct': 'BlockMeasureInfo',
Eric Blake5d72c682020-05-21 14:21:34 -0500755 'data': {'required': 'int', 'fully-allocated': 'int', '*bitmaps': 'int'} }
Stefan Hajnoczi90880ff2017-07-05 13:57:30 +0100756
757##
Benoît Canet1ad166b2014-06-05 13:45:31 +0200758# @query-block:
759#
760# Get a list of BlockInfo for all virtual block devices.
761#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200762# Returns: a list of @BlockInfo describing each virtual block device.
763# Filter nodes that were created implicitly are skipped over.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200764#
Markus Armbruster9bc6e892020-11-18 07:41:58 +0100765# Since: 0.14
Marc-André Lureau978ccea2016-06-23 13:58:48 +0200766#
John Snow14b48aa2024-07-16 22:13:08 -0400767# .. qmp-example::
Marc-André Lureau978ccea2016-06-23 13:58:48 +0200768#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100769# -> { "execute": "query-block" }
770# <- {
771# "return":[
772# {
773# "io-status": "ok",
774# "device":"ide0-hd0",
775# "locked":false,
776# "removable":false,
777# "inserted":{
778# "ro":false,
779# "drv":"qcow2",
780# "encrypted":false,
781# "file":"disks/test.qcow2",
782# "backing_file_depth":1,
783# "bps":1000000,
784# "bps_rd":0,
785# "bps_wr":0,
786# "iops":1000000,
787# "iops_rd":0,
788# "iops_wr":0,
789# "bps_max": 8000000,
790# "bps_rd_max": 0,
791# "bps_wr_max": 0,
792# "iops_max": 0,
793# "iops_rd_max": 0,
794# "iops_wr_max": 0,
795# "iops_size": 0,
796# "detect_zeroes": "on",
797# "write_threshold": 0,
798# "image":{
799# "filename":"disks/test.qcow2",
Marc-André Lureau978ccea2016-06-23 13:58:48 +0200800# "format":"qcow2",
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100801# "virtual-size":2048000,
802# "backing_file":"base.qcow2",
803# "full-backing-filename":"disks/base.qcow2",
804# "backing-filename-format":"qcow2",
805# "snapshots":[
806# {
807# "id": "1",
808# "name": "snapshot1",
809# "vm-state-size": 0,
810# "date-sec": 10000200,
811# "date-nsec": 12,
812# "vm-clock-sec": 206,
813# "vm-clock-nsec": 30
814# }
815# ],
816# "backing-image":{
817# "filename":"disks/base.qcow2",
818# "format":"qcow2",
819# "virtual-size":2048000
820# }
821# }
822# },
823# "qdev": "ide_disk",
824# "type":"unknown"
825# },
826# {
827# "io-status": "ok",
828# "device":"ide1-cd0",
829# "locked":false,
830# "removable":true,
831# "qdev": "/machine/unattached/device[23]",
832# "tray_open": false,
833# "type":"unknown"
834# },
835# {
836# "device":"floppy0",
837# "locked":false,
838# "removable":true,
839# "qdev": "/machine/unattached/device[20]",
840# "type":"unknown"
841# },
842# {
843# "device":"sd0",
844# "locked":false,
845# "removable":true,
846# "type":"unknown"
847# }
848# ]
849# }
Benoît Canet1ad166b2014-06-05 13:45:31 +0200850##
Paolo Bonzinif55ba802020-11-03 04:37:20 -0500851{ 'command': 'query-block', 'returns': ['BlockInfo'],
852 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +0200853
Alberto Garcia979e9b02015-10-28 17:33:05 +0200854##
855# @BlockDeviceTimedStats:
856#
857# Statistics of a block device during a given interval of time.
858#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200859# @interval_length: Interval used for calculating the statistics, in
860# seconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200861#
862# @min_rd_latency_ns: Minimum latency of read operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200863# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200864#
865# @min_wr_latency_ns: Minimum latency of write operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200866# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200867#
Markus Armbruster9e272072023-07-20 09:16:09 +0200868# @min_zone_append_latency_ns: Minimum latency of zone append
869# operations in the defined interval, in nanoseconds (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800870#
Alberto Garcia979e9b02015-10-28 17:33:05 +0200871# @min_flush_latency_ns: Minimum latency of flush operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200872# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200873#
874# @max_rd_latency_ns: Maximum latency of read operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200875# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200876#
877# @max_wr_latency_ns: Maximum latency of write operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200878# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200879#
Markus Armbruster9e272072023-07-20 09:16:09 +0200880# @max_zone_append_latency_ns: Maximum latency of zone append
881# operations in the defined interval, in nanoseconds (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800882#
Alberto Garcia979e9b02015-10-28 17:33:05 +0200883# @max_flush_latency_ns: Maximum latency of flush operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200884# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200885#
886# @avg_rd_latency_ns: Average latency of read operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200887# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200888#
889# @avg_wr_latency_ns: Average latency of write operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200890# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200891#
Markus Armbruster9e272072023-07-20 09:16:09 +0200892# @avg_zone_append_latency_ns: Average latency of zone append
893# operations in the defined interval, in nanoseconds (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800894#
Alberto Garcia979e9b02015-10-28 17:33:05 +0200895# @avg_flush_latency_ns: Average latency of flush operations in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200896# defined interval, in nanoseconds.
Alberto Garcia979e9b02015-10-28 17:33:05 +0200897#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200898# @avg_rd_queue_depth: Average number of pending read operations in
899# the defined interval.
Alberto Garcia96e4ded2015-10-28 17:33:06 +0200900#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200901# @avg_wr_queue_depth: Average number of pending write operations in
902# the defined interval.
Alberto Garcia96e4ded2015-10-28 17:33:06 +0200903#
Sam Li52eb76f2023-05-08 13:19:14 +0800904# @avg_zone_append_queue_depth: Average number of pending zone append
Markus Armbruster9e272072023-07-20 09:16:09 +0200905# operations in the defined interval (since 8.1).
Sam Li52eb76f2023-05-08 13:19:14 +0800906#
Alberto Garcia979e9b02015-10-28 17:33:05 +0200907# Since: 2.5
908##
Alberto Garcia979e9b02015-10-28 17:33:05 +0200909{ 'struct': 'BlockDeviceTimedStats',
910 'data': { 'interval_length': 'int', 'min_rd_latency_ns': 'int',
911 'max_rd_latency_ns': 'int', 'avg_rd_latency_ns': 'int',
912 'min_wr_latency_ns': 'int', 'max_wr_latency_ns': 'int',
Sam Li52eb76f2023-05-08 13:19:14 +0800913 'avg_wr_latency_ns': 'int', 'min_zone_append_latency_ns': 'int',
914 'max_zone_append_latency_ns': 'int',
915 'avg_zone_append_latency_ns': 'int',
916 'min_flush_latency_ns': 'int', 'max_flush_latency_ns': 'int',
917 'avg_flush_latency_ns': 'int', 'avg_rd_queue_depth': 'number',
918 'avg_wr_queue_depth': 'number',
919 'avg_zone_append_queue_depth': 'number' } }
Alberto Garcia979e9b02015-10-28 17:33:05 +0200920
Benoît Canet1ad166b2014-06-05 13:45:31 +0200921##
922# @BlockDeviceStats:
923#
924# Statistics of a virtual block device or a block backing device.
925#
Andrea Bolognani23e46452022-05-03 09:37:35 +0200926# @rd_bytes: The number of bytes read by the device.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200927#
Andrea Bolognani23e46452022-05-03 09:37:35 +0200928# @wr_bytes: The number of bytes written by the device.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200929#
Markus Armbruster9e272072023-07-20 09:16:09 +0200930# @zone_append_bytes: The number of bytes appended by the zoned
931# devices (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800932#
Anton Nefedov159f85d2019-09-23 15:17:30 +0300933# @unmap_bytes: The number of bytes unmapped by the device (Since 4.2)
934#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200935# @rd_operations: The number of read operations performed by the
936# device.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200937#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200938# @wr_operations: The number of write operations performed by the
939# device.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200940#
Markus Armbruster9e272072023-07-20 09:16:09 +0200941# @zone_append_operations: The number of zone append operations
942# performed by the zoned devices (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800943#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200944# @flush_operations: The number of cache flush operations performed by
945# the device (since 0.15)
Benoît Canet1ad166b2014-06-05 13:45:31 +0200946#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200947# @unmap_operations: The number of unmap operations performed by the
948# device (Since 4.2)
Anton Nefedov159f85d2019-09-23 15:17:30 +0300949#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200950# @rd_total_time_ns: Total time spent on reads in nanoseconds (since
951# 0.15).
Anton Nefedov329d27e2019-09-23 15:17:29 +0300952#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200953# @wr_total_time_ns: Total time spent on writes in nanoseconds (since
954# 0.15).
Anton Nefedov329d27e2019-09-23 15:17:29 +0300955#
Sam Li52eb76f2023-05-08 13:19:14 +0800956# @zone_append_total_time_ns: Total time spent on zone append writes
Markus Armbruster9e272072023-07-20 09:16:09 +0200957# in nanoseconds (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800958#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200959# @flush_total_time_ns: Total time spent on cache flushes in
960# nanoseconds (since 0.15).
Benoît Canet1ad166b2014-06-05 13:45:31 +0200961#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200962# @unmap_total_time_ns: Total time spent on unmap operations in
963# nanoseconds (Since 4.2)
Anton Nefedov159f85d2019-09-23 15:17:30 +0300964#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200965# @wr_highest_offset: The offset after the greatest byte written to
966# the device. The intended use of this information is for
967# growable sparse files (like qcow2) that are used on top of a
968# physical device.
Benoît Canet1ad166b2014-06-05 13:45:31 +0200969#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200970# @rd_merged: Number of read requests that have been merged into
971# another request (Since 2.3).
Peter Lievenf4564d52015-02-02 14:52:18 +0100972#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200973# @wr_merged: Number of write requests that have been merged into
974# another request (Since 2.3).
Peter Lievenf4564d52015-02-02 14:52:18 +0100975#
Markus Armbruster9e272072023-07-20 09:16:09 +0200976# @zone_append_merged: Number of zone append requests that have been
977# merged into another request (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800978#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200979# @unmap_merged: Number of unmap requests that have been merged into
980# another request (Since 4.2)
Anton Nefedov159f85d2019-09-23 15:17:30 +0300981#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200982# @idle_time_ns: Time since the last I/O operation, in nanoseconds.
983# If the field is absent it means that there haven't been any
984# operations yet (Since 2.5).
Alberto Garciacb38fff2015-10-28 17:33:02 +0200985#
Alberto Garcia7ee12da2015-10-28 17:33:03 +0200986# @failed_rd_operations: The number of failed read operations
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200987# performed by the device (Since 2.5)
Alberto Garcia7ee12da2015-10-28 17:33:03 +0200988#
989# @failed_wr_operations: The number of failed write operations
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200990# performed by the device (Since 2.5)
Alberto Garcia7ee12da2015-10-28 17:33:03 +0200991#
Markus Armbruster9e272072023-07-20 09:16:09 +0200992# @failed_zone_append_operations: The number of failed zone append
993# write operations performed by the zoned devices (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +0800994#
Alberto Garcia7ee12da2015-10-28 17:33:03 +0200995# @failed_flush_operations: The number of failed flush operations
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200996# performed by the device (Since 2.5)
Alberto Garcia7ee12da2015-10-28 17:33:03 +0200997#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200998# @failed_unmap_operations: The number of failed unmap operations
999# performed by the device (Since 4.2)
Anton Nefedov159f85d2019-09-23 15:17:30 +03001000#
Alberto Garcia7ee12da2015-10-28 17:33:03 +02001001# @invalid_rd_operations: The number of invalid read operations
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001002# performed by the device (Since 2.5)
Alberto Garcia7ee12da2015-10-28 17:33:03 +02001003#
1004# @invalid_wr_operations: The number of invalid write operations
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001005# performed by the device (Since 2.5)
Alberto Garcia7ee12da2015-10-28 17:33:03 +02001006#
Markus Armbruster9e272072023-07-20 09:16:09 +02001007# @invalid_zone_append_operations: The number of invalid zone append
1008# operations performed by the zoned device (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +08001009#
Alberto Garcia7ee12da2015-10-28 17:33:03 +02001010# @invalid_flush_operations: The number of invalid flush operations
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001011# performed by the device (Since 2.5)
Alberto Garcia7ee12da2015-10-28 17:33:03 +02001012#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001013# @invalid_unmap_operations: The number of invalid unmap operations
1014# performed by the device (Since 4.2)
Anton Nefedov159f85d2019-09-23 15:17:30 +03001015#
Alberto Garcia362e9292015-10-28 17:33:04 +02001016# @account_invalid: Whether invalid operations are included in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001017# last access statistics (Since 2.5)
Alberto Garcia362e9292015-10-28 17:33:04 +02001018#
1019# @account_failed: Whether failed operations are included in the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001020# latency and last access statistics (Since 2.5)
Alberto Garcia362e9292015-10-28 17:33:04 +02001021#
Alberto Garcia979e9b02015-10-28 17:33:05 +02001022# @timed_stats: Statistics specific to the set of previously defined
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001023# intervals of time (Since 2.5)
Alberto Garcia979e9b02015-10-28 17:33:05 +02001024#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001025# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +03001026#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001027# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +03001028#
Markus Armbruster9e272072023-07-20 09:16:09 +02001029# @zone_append_latency_histogram: @BlockLatencyHistogramInfo.
1030# (since 8.1)
Sam Li52eb76f2023-05-08 13:19:14 +08001031#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001032# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +03001033#
Markus Armbruster9bc6e892020-11-18 07:41:58 +01001034# Since: 0.14
Benoît Canet1ad166b2014-06-05 13:45:31 +02001035##
Eric Blake895a2a82015-05-04 09:05:27 -06001036{ 'struct': 'BlockDeviceStats',
Sam Li52eb76f2023-05-08 13:19:14 +08001037 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'zone_append_bytes': 'int',
1038 'unmap_bytes' : 'int', 'rd_operations': 'int',
1039 'wr_operations': 'int', 'zone_append_operations': 'int',
Anton Nefedov159f85d2019-09-23 15:17:30 +03001040 'flush_operations': 'int', 'unmap_operations': 'int',
Anton Nefedov329d27e2019-09-23 15:17:29 +03001041 'rd_total_time_ns': 'int', 'wr_total_time_ns': 'int',
Sam Li52eb76f2023-05-08 13:19:14 +08001042 'zone_append_total_time_ns': 'int', 'flush_total_time_ns': 'int',
1043 'unmap_total_time_ns': 'int', 'wr_highest_offset': 'int',
1044 'rd_merged': 'int', 'wr_merged': 'int', 'zone_append_merged': 'int',
1045 'unmap_merged': 'int', '*idle_time_ns': 'int',
Alberto Garcia7ee12da2015-10-28 17:33:03 +02001046 'failed_rd_operations': 'int', 'failed_wr_operations': 'int',
Sam Li52eb76f2023-05-08 13:19:14 +08001047 'failed_zone_append_operations': 'int',
1048 'failed_flush_operations': 'int',
1049 'failed_unmap_operations': 'int', 'invalid_rd_operations': 'int',
1050 'invalid_wr_operations': 'int',
1051 'invalid_zone_append_operations': 'int',
Anton Nefedov159f85d2019-09-23 15:17:30 +03001052 'invalid_flush_operations': 'int', 'invalid_unmap_operations': 'int',
Alberto Garcia979e9b02015-10-28 17:33:05 +02001053 'account_invalid': 'bool', 'account_failed': 'bool',
Vladimir Sementsov-Ogievskiy7e5c7762018-03-09 19:52:12 +03001054 'timed_stats': ['BlockDeviceTimedStats'],
Vladimir Sementsov-Ogievskiycb8aac32019-03-05 15:53:17 +03001055 '*rd_latency_histogram': 'BlockLatencyHistogramInfo',
1056 '*wr_latency_histogram': 'BlockLatencyHistogramInfo',
Sam Li52eb76f2023-05-08 13:19:14 +08001057 '*zone_append_latency_histogram': 'BlockLatencyHistogramInfo',
Vladimir Sementsov-Ogievskiycb8aac32019-03-05 15:53:17 +03001058 '*flush_latency_histogram': 'BlockLatencyHistogramInfo' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001059
1060##
Anton Nefedovd9245592019-09-23 15:17:37 +03001061# @BlockStatsSpecificFile:
1062#
1063# File driver statistics
1064#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001065# @discard-nb-ok: The number of successful discard operations
1066# performed by the driver.
Anton Nefedovd9245592019-09-23 15:17:37 +03001067#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001068# @discard-nb-failed: The number of failed discard operations
1069# performed by the driver.
Anton Nefedovd9245592019-09-23 15:17:37 +03001070#
1071# @discard-bytes-ok: The number of bytes discarded by the driver.
1072#
1073# Since: 4.2
1074##
1075{ 'struct': 'BlockStatsSpecificFile',
1076 'data': {
1077 'discard-nb-ok': 'uint64',
1078 'discard-nb-failed': 'uint64',
1079 'discard-bytes-ok': 'uint64' } }
1080
1081##
Philippe Mathieu-Daudéf25e7ab2020-10-01 18:29:39 +02001082# @BlockStatsSpecificNvme:
1083#
1084# NVMe driver statistics
1085#
1086# @completion-errors: The number of completion errors.
1087#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001088# @aligned-accesses: The number of aligned accesses performed by the
1089# driver.
Philippe Mathieu-Daudéf25e7ab2020-10-01 18:29:39 +02001090#
1091# @unaligned-accesses: The number of unaligned accesses performed by
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001092# the driver.
Philippe Mathieu-Daudéf25e7ab2020-10-01 18:29:39 +02001093#
1094# Since: 5.2
1095##
1096{ 'struct': 'BlockStatsSpecificNvme',
1097 'data': {
1098 'completion-errors': 'uint64',
1099 'aligned-accesses': 'uint64',
1100 'unaligned-accesses': 'uint64' } }
1101
1102##
Anton Nefedovd9245592019-09-23 15:17:37 +03001103# @BlockStatsSpecific:
1104#
1105# Block driver specific statistics
1106#
Markus Armbruster89a22732024-02-05 08:47:09 +01001107# @driver: block driver name
1108#
Anton Nefedovd9245592019-09-23 15:17:37 +03001109# Since: 4.2
1110##
1111{ 'union': 'BlockStatsSpecific',
1112 'base': { 'driver': 'BlockdevDriver' },
1113 'discriminator': 'driver',
1114 'data': {
1115 'file': 'BlockStatsSpecificFile',
Joelle van Dyne14176c82021-03-15 11:03:38 -07001116 'host_device': { 'type': 'BlockStatsSpecificFile',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04001117 'if': 'HAVE_HOST_BLOCK_DEVICE' },
Philippe Mathieu-Daudéf25e7ab2020-10-01 18:29:39 +02001118 'nvme': 'BlockStatsSpecificNvme' } }
Anton Nefedovd9245592019-09-23 15:17:37 +03001119
1120##
Benoît Canet1ad166b2014-06-05 13:45:31 +02001121# @BlockStats:
1122#
1123# Statistics of a virtual block device or a block backing device.
1124#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001125# @device: If the stats are for a virtual block device, the name
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001126# corresponding to the virtual block device.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001127#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001128# @node-name: The node name of the device. (Since 2.3)
Fam Zheng4875a772014-10-31 11:32:56 +08001129#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001130# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the
1131# block device. (since 3.0)
Kevin Wolf5a9cb5a2018-07-27 16:07:07 +02001132#
Andrea Bolognani23e46452022-05-03 09:37:35 +02001133# @stats: A @BlockDeviceStats for the device.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001134#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001135# @driver-specific: Optional driver-specific stats. (Since 4.2)
Anton Nefedovd9245592019-09-23 15:17:37 +03001136#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001137# @parent: This describes the file block device if it has one.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001138# Contains recursively the statistics of the underlying protocol
Markus Armbruster9e272072023-07-20 09:16:09 +02001139# (e.g. the host file for a qcow2 image). If there is no
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001140# underlying protocol, this field is omitted
Benoît Canet1ad166b2014-06-05 13:45:31 +02001141#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001142# @backing: This describes the backing block device if it has one.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001143# (Since 2.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001144#
Markus Armbruster9bc6e892020-11-18 07:41:58 +01001145# Since: 0.14
Benoît Canet1ad166b2014-06-05 13:45:31 +02001146##
Eric Blake895a2a82015-05-04 09:05:27 -06001147{ 'struct': 'BlockStats',
Kevin Wolf5a9cb5a2018-07-27 16:07:07 +02001148 'data': {'*device': 'str', '*qdev': 'str', '*node-name': 'str',
Fam Zheng4875a772014-10-31 11:32:56 +08001149 'stats': 'BlockDeviceStats',
Anton Nefedovd9245592019-09-23 15:17:37 +03001150 '*driver-specific': 'BlockStatsSpecific',
Benoît Canet1ad166b2014-06-05 13:45:31 +02001151 '*parent': 'BlockStats',
1152 '*backing': 'BlockStats'} }
1153
1154##
1155# @query-blockstats:
1156#
1157# Query the @BlockStats for all virtual block devices.
1158#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001159# @query-nodes: If true, the command will query all the block nodes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001160# that have a node name, in a list which will include "parent"
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001161# information, but not "backing". If false or omitted, the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001162# behavior is as before - query all the device backends,
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001163# recursively including their "parent" and "backing". Filter
1164# nodes that were created implicitly are skipped over in this
1165# mode. (Since 2.3)
Fam Zhengf71eaa72014-10-31 11:32:57 +08001166#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001167# Returns: A list of @BlockStats for each virtual block devices.
1168#
Markus Armbruster9bc6e892020-11-18 07:41:58 +01001169# Since: 0.14
Marc-André Lureauf2eaea12016-06-23 14:00:14 +02001170#
John Snow14b48aa2024-07-16 22:13:08 -04001171# .. qmp-example::
Marc-André Lureauf2eaea12016-06-23 14:00:14 +02001172#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001173# -> { "execute": "query-blockstats" }
1174# <- {
1175# "return":[
1176# {
1177# "device":"ide0-hd0",
1178# "parent":{
1179# "stats":{
1180# "wr_highest_offset":3686448128,
1181# "wr_bytes":9786368,
1182# "wr_operations":751,
1183# "rd_bytes":122567168,
1184# "rd_operations":36772
1185# "wr_total_times_ns":313253456
1186# "rd_total_times_ns":3465673657
1187# "flush_total_times_ns":49653
1188# "flush_operations":61,
1189# "rd_merged":0,
1190# "wr_merged":0,
1191# "idle_time_ns":2953431879,
1192# "account_invalid":true,
1193# "account_failed":false
1194# }
1195# },
1196# "stats":{
1197# "wr_highest_offset":2821110784,
1198# "wr_bytes":9786368,
1199# "wr_operations":692,
1200# "rd_bytes":122739200,
1201# "rd_operations":36604
1202# "flush_operations":51,
1203# "wr_total_times_ns":313253456
1204# "rd_total_times_ns":3465673657
1205# "flush_total_times_ns":49653,
1206# "rd_merged":0,
1207# "wr_merged":0,
1208# "idle_time_ns":2953431879,
1209# "account_invalid":true,
1210# "account_failed":false
1211# },
1212# "qdev": "/machine/unattached/device[23]"
1213# },
1214# {
1215# "device":"ide1-cd0",
1216# "stats":{
1217# "wr_highest_offset":0,
1218# "wr_bytes":0,
1219# "wr_operations":0,
1220# "rd_bytes":0,
1221# "rd_operations":0
1222# "flush_operations":0,
1223# "wr_total_times_ns":0
1224# "rd_total_times_ns":0
1225# "flush_total_times_ns":0,
1226# "rd_merged":0,
1227# "wr_merged":0,
1228# "account_invalid":false,
1229# "account_failed":false
1230# },
1231# "qdev": "/machine/unattached/device[24]"
1232# },
1233# {
1234# "device":"floppy0",
1235# "stats":{
1236# "wr_highest_offset":0,
1237# "wr_bytes":0,
1238# "wr_operations":0,
1239# "rd_bytes":0,
1240# "rd_operations":0
1241# "flush_operations":0,
1242# "wr_total_times_ns":0
1243# "rd_total_times_ns":0
1244# "flush_total_times_ns":0,
1245# "rd_merged":0,
1246# "wr_merged":0,
1247# "account_invalid":false,
1248# "account_failed":false
1249# },
1250# "qdev": "/machine/unattached/device[16]"
1251# },
1252# {
1253# "device":"sd0",
1254# "stats":{
1255# "wr_highest_offset":0,
1256# "wr_bytes":0,
1257# "wr_operations":0,
1258# "rd_bytes":0,
1259# "rd_operations":0
1260# "flush_operations":0,
1261# "wr_total_times_ns":0
1262# "rd_total_times_ns":0
1263# "flush_total_times_ns":0,
1264# "rd_merged":0,
1265# "wr_merged":0,
1266# "account_invalid":false,
1267# "account_failed":false
1268# }
1269# }
1270# ]
1271# }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001272##
Fam Zhengf71eaa72014-10-31 11:32:57 +08001273{ 'command': 'query-blockstats',
1274 'data': { '*query-nodes': 'bool' },
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001275 'returns': ['BlockStats'],
1276 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001277
1278##
1279# @BlockdevOnError:
1280#
1281# An enumeration of possible behaviors for errors on I/O operations.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001282# The exact meaning depends on whether the I/O was initiated by a
1283# guest or by a block job
Benoît Canet1ad166b2014-06-05 13:45:31 +02001284#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001285# @report: for guest operations, report the error to the guest; for
1286# jobs, cancel the job
Benoît Canet1ad166b2014-06-05 13:45:31 +02001287#
1288# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001289# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001290# retry the failing request later and may still complete
1291# successfully. The stream block job continues to stream and will
1292# complete with an error.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001293#
1294# @enospc: same as @stop on ENOSPC, same as @report otherwise.
1295#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001296# @stop: for guest operations, stop the virtual machine; for jobs,
1297# pause the job
Benoît Canet1ad166b2014-06-05 13:45:31 +02001298#
Kevin Wolf8c398252016-06-29 17:41:35 +02001299# @auto: inherit the error handling policy of the backend (since: 2.7)
1300#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001301# Since: 1.3
1302##
1303{ 'enum': 'BlockdevOnError',
Kevin Wolf8c398252016-06-29 17:41:35 +02001304 'data': ['report', 'ignore', 'enospc', 'stop', 'auto'] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001305
1306##
1307# @MirrorSyncMode:
1308#
1309# An enumeration of possible behaviors for the initial synchronization
1310# phase of storage mirroring.
1311#
1312# @top: copies data in the topmost image to the destination
1313#
1314# @full: copies data from all images to the destination
1315#
1316# @none: only copy data written from now on
1317#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001318# @incremental: only copy data described by the dirty bitmap.
1319# (since: 2.4)
John Snowc8b56502019-07-29 16:35:52 -04001320#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001321# @bitmap: only copy data described by the dirty bitmap. (since: 4.2)
1322# Behavior on completion is determined by the BitmapSyncMode.
John Snowd58d8452015-04-17 19:49:58 -04001323#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001324# Since: 1.3
1325##
1326{ 'enum': 'MirrorSyncMode',
John Snowc8b56502019-07-29 16:35:52 -04001327 'data': ['top', 'full', 'none', 'incremental', 'bitmap'] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001328
1329##
John Snow00a463b2019-07-29 16:35:52 -04001330# @BitmapSyncMode:
1331#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001332# An enumeration of possible behaviors for the synchronization of a
1333# bitmap when used for data copy operations.
John Snow00a463b2019-07-29 16:35:52 -04001334#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001335# @on-success: The bitmap is only synced when the operation is
1336# successful. This is the behavior always used for 'INCREMENTAL'
1337# backups.
John Snow00a463b2019-07-29 16:35:52 -04001338#
John Snowcf0cd292019-07-29 16:35:53 -04001339# @never: The bitmap is never synchronized with the operation, and is
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001340# treated solely as a read-only manifest of blocks to copy.
John Snowcf0cd292019-07-29 16:35:53 -04001341#
John Snowc23909e2019-07-29 16:35:53 -04001342# @always: The bitmap is always synchronized with the operation,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001343# regardless of whether or not the operation was successful.
John Snowc23909e2019-07-29 16:35:53 -04001344#
John Snow00a463b2019-07-29 16:35:52 -04001345# Since: 4.2
1346##
1347{ 'enum': 'BitmapSyncMode',
John Snowc23909e2019-07-29 16:35:53 -04001348 'data': ['on-success', 'never', 'always'] }
John Snow00a463b2019-07-29 16:35:52 -04001349
1350##
Max Reitzd06107a2018-06-13 20:18:21 +02001351# @MirrorCopyMode:
1352#
1353# An enumeration whose values tell the mirror block job when to
1354# trigger writes to the target.
1355#
1356# @background: copy data in background only.
1357#
1358# @write-blocking: when data is written to the source, write it
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001359# (synchronously) to the target as well. In addition, data is
1360# copied in background just like in @background mode.
Max Reitzd06107a2018-06-13 20:18:21 +02001361#
1362# Since: 3.0
1363##
1364{ 'enum': 'MirrorCopyMode',
1365 'data': ['background', 'write-blocking'] }
1366
1367##
Fiona Ebner76cb2f22023-10-31 14:54:30 +01001368# @BlockJobInfoMirror:
1369#
1370# Information specific to mirror block jobs.
1371#
1372# @actively-synced: Whether the source is actively synced to the
1373# target, i.e. same data and new writes are done synchronously to
1374# both.
1375#
Markus Armbruster37507c12024-01-20 10:53:27 +01001376# Since: 8.2
Fiona Ebner76cb2f22023-10-31 14:54:30 +01001377##
1378{ 'struct': 'BlockJobInfoMirror',
1379 'data': { 'actively-synced': 'bool' } }
1380
1381##
Benoît Canet1ad166b2014-06-05 13:45:31 +02001382# @BlockJobInfo:
1383#
1384# Information about a long-running block device operation.
1385#
1386# @type: the job type ('stream' for image streaming)
1387#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001388# @device: The job identifier. Originally the device name but other
1389# values are allowed since QEMU 2.7
Benoît Canet1ad166b2014-06-05 13:45:31 +02001390#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001391# @len: Estimated @offset value at the completion of the job. This
1392# value can arbitrarily change while the job is running, in both
1393# directions.
Kevin Wolfa81e0a82018-05-16 13:04:34 +02001394#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001395# @offset: Progress made until now. The unit is arbitrary and the
1396# value can only meaningfully be used for the ratio of @offset to
1397# @len. The value is monotonically increasing.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001398#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001399# @busy: false if the job is known to be in a quiescent state, with no
1400# pending I/O. (Since 1.3)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001401#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001402# @paused: whether the job is paused or, if @busy is true, will pause
1403# itself as soon as possible. (Since 1.3)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001404#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001405# @speed: the rate limit, bytes per second
1406#
1407# @io-status: the status of the job (since 1.3)
1408#
Max Reitzef6dbf12014-10-24 15:57:34 +02001409# @ready: true if the job may be completed (since 2.2)
1410#
John Snow58b295b2018-03-10 03:27:29 -05001411# @status: Current job state/status (since 2.12)
1412#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001413# @auto-finalize: Job will finalize itself when PENDING, moving to the
1414# CONCLUDED state. (since 2.12)
John Snowb40dacd2018-03-10 03:27:44 -05001415#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001416# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the
1417# NULL state and disappearing from the query list. (since 2.12)
John Snowb40dacd2018-03-10 03:27:44 -05001418#
John Snowab9ba612018-05-08 19:36:59 -04001419# @error: Error information if the job did not complete successfully.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001420# Not set if the job completed successfully. (since 2.12.1)
John Snowab9ba612018-05-08 19:36:59 -04001421#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001422# Since: 1.1
1423##
Fiona Ebner701efc92023-10-31 14:54:28 +01001424{ 'union': 'BlockJobInfo',
1425 'base': {'type': 'JobType', 'device': 'str', 'len': 'int',
Benoît Canet1ad166b2014-06-05 13:45:31 +02001426 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int',
John Snow58b295b2018-03-10 03:27:29 -05001427 'io-status': 'BlockDeviceIoStatus', 'ready': 'bool',
Kevin Wolfa50c2ab2018-04-13 17:19:31 +02001428 'status': 'JobStatus',
John Snowab9ba612018-05-08 19:36:59 -04001429 'auto-finalize': 'bool', 'auto-dismiss': 'bool',
Fiona Ebner701efc92023-10-31 14:54:28 +01001430 '*error': 'str' },
1431 'discriminator': 'type',
Fiona Ebner76cb2f22023-10-31 14:54:30 +01001432 'data': { 'mirror': 'BlockJobInfoMirror' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001433
1434##
1435# @query-block-jobs:
1436#
1437# Return information about long-running block device operations.
1438#
1439# Returns: a list of @BlockJobInfo for each active block job
1440#
1441# Since: 1.1
1442##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001443{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'],
1444 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001445
1446##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001447# @block_resize:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001448#
1449# Resize a block image while a guest is running.
1450#
1451# Either @device or @node-name must be set but not both.
1452#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001453# @device: the name of the device to get the image resized
Benoît Canet1ad166b2014-06-05 13:45:31 +02001454#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001455# @node-name: graph node name to get the image resized (Since 2.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001456#
Andrea Bolognani23e46452022-05-03 09:37:35 +02001457# @size: new image size in bytes
Benoît Canet1ad166b2014-06-05 13:45:31 +02001458#
Markus Armbruster2746f062024-02-27 12:39:12 +01001459# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001460# - If @device is not a valid block device, DeviceNotFound
Benoît Canet1ad166b2014-06-05 13:45:31 +02001461#
Markus Armbruster9bc6e892020-11-18 07:41:58 +01001462# Since: 0.14
Marc-André Lureau0dc869c2016-06-23 14:01:52 +02001463#
John Snow14b48aa2024-07-16 22:13:08 -04001464# .. qmp-example::
Marc-André Lureau0dc869c2016-06-23 14:01:52 +02001465#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001466# -> { "execute": "block_resize",
1467# "arguments": { "device": "scratch", "size": 1073741824 } }
1468# <- { "return": {} }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001469##
Marc-André Lureaub0ddeba2018-12-08 15:16:04 +04001470{ 'command': 'block_resize',
1471 'data': { '*device': 'str',
1472 '*node-name': 'str',
Kevin Wolfeb94b812020-10-05 17:58:55 +02001473 'size': 'int' },
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001474 'coroutine': true,
1475 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001476
1477##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001478# @NewImageMode:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001479#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001480# An enumeration that tells QEMU how to set the backing file path in a
1481# new image file.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001482#
1483# @existing: QEMU should look for an existing image file.
1484#
1485# @absolute-paths: QEMU should create a new image with absolute paths
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001486# for the backing file. If there is no backing file available,
1487# the new image will not be backed either.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001488#
1489# Since: 1.1
1490##
1491{ 'enum': 'NewImageMode',
1492 'data': [ 'existing', 'absolute-paths' ] }
1493
1494##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001495# @BlockdevSnapshotSync:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001496#
1497# Either @device or @node-name must be set but not both.
1498#
Max Reitz681b86a2019-06-03 22:22:35 +02001499# @device: the name of the device to take a snapshot of.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001500#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001501# @node-name: graph node name to generate the snapshot from (Since
1502# 2.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001503#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001504# @snapshot-file: the target of the new overlay image. If the file
1505# exists, or if it is a device, the overlay will be created in the
1506# existing file/device. Otherwise, a new file will be created.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001507#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001508# @snapshot-node-name: the graph node name of the new image (Since
1509# 2.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001510#
Max Reitz681b86a2019-06-03 22:22:35 +02001511# @format: the format of the overlay image, default is 'qcow2'.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001512#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001513# @mode: whether and how QEMU should create a new image, default is
Markus Armbruster9e272072023-07-20 09:16:09 +02001514# 'absolute-paths'.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001515##
Alberto Garciaa911e6a2015-10-26 14:27:14 +02001516{ 'struct': 'BlockdevSnapshotSync',
Benoît Canet1ad166b2014-06-05 13:45:31 +02001517 'data': { '*device': 'str', '*node-name': 'str',
1518 'snapshot-file': 'str', '*snapshot-node-name': 'str',
1519 '*format': 'str', '*mode': 'NewImageMode' } }
1520
1521##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001522# @BlockdevSnapshot:
Alberto Garcia43de7e22015-10-26 14:27:16 +02001523#
Max Reitz681b86a2019-06-03 22:22:35 +02001524# @node: device or node name that will have a snapshot taken.
Alberto Garcia43de7e22015-10-26 14:27:16 +02001525#
1526# @overlay: reference to the existing block device that will become
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001527# the overlay of @node, as part of taking the snapshot. It must
1528# not have a current backing file (this can be achieved by passing
1529# "backing": null to blockdev-add).
Alberto Garcia43de7e22015-10-26 14:27:16 +02001530#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001531# Since: 2.5
Alberto Garcia43de7e22015-10-26 14:27:16 +02001532##
1533{ 'struct': 'BlockdevSnapshot',
1534 'data': { 'node': 'str', 'overlay': 'str' } }
1535
1536##
Vladimir Sementsov-Ogievskiy86c6a3b2021-01-17 00:46:43 +03001537# @BackupPerf:
1538#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001539# Optional parameters for backup. These parameters don't affect
Vladimir Sementsov-Ogievskiy86c6a3b2021-01-17 00:46:43 +03001540# functionality, but may significantly affect performance.
1541#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001542# @use-copy-range: Use copy offloading. Default false.
Vladimir Sementsov-Ogievskiy86c6a3b2021-01-17 00:46:43 +03001543#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001544# @max-workers: Maximum number of parallel requests for the sustained
1545# background copying process. Doesn't influence copy-before-write
1546# operations. Default 64.
Vladimir Sementsov-Ogievskiy2c59fd82021-01-17 00:46:52 +03001547#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001548# @max-chunk: Maximum request length for the sustained background
1549# copying process. Doesn't influence copy-before-write
1550# operations. 0 means unlimited. If max-chunk is non-zero then
1551# it should not be less than job cluster size which is calculated
1552# as maximum of target image cluster size and 64k. Default 0.
Vladimir Sementsov-Ogievskiy2c59fd82021-01-17 00:46:52 +03001553#
Vladimir Sementsov-Ogievskiy86c6a3b2021-01-17 00:46:43 +03001554# Since: 6.0
1555##
1556{ 'struct': 'BackupPerf',
Vladimir Sementsov-Ogievskiy2c59fd82021-01-17 00:46:52 +03001557 'data': { '*use-copy-range': 'bool',
1558 '*max-workers': 'int', '*max-chunk': 'int64' } }
Vladimir Sementsov-Ogievskiy86c6a3b2021-01-17 00:46:43 +03001559
1560##
John Snow3c950372019-07-29 16:35:52 -04001561# @BackupCommon:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001562#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001563# @job-id: identifier for the newly-created block job. If omitted,
1564# the device name will be used. (Since 2.7)
Alberto Garcia70559d42016-07-05 17:28:58 +03001565#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001566# @device: the device name or node-name of a root node which should be
1567# copied.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001568#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001569# @sync: what parts of the disk image should be copied to the
1570# destination (all the disk, only the sectors allocated in the
1571# topmost image, from a dirty bitmap, or only new I/O).
John Snow3c950372019-07-29 16:35:52 -04001572#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001573# @speed: the maximum speed, in bytes per second. The default is 0,
1574# for unlimited.
John Snow3c950372019-07-29 16:35:52 -04001575#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001576# @bitmap: The name of a dirty bitmap to use. Must be present if sync
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001577# is "bitmap" or "incremental". Can be present if sync is "full"
Markus Armbruster9e272072023-07-20 09:16:09 +02001578# or "top". Must not be present otherwise.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001579# (Since 2.4 (drive-backup), 3.1 (blockdev-backup))
John Snowc8b56502019-07-29 16:35:52 -04001580#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001581# @bitmap-mode: Specifies the type of data the bitmap should contain
1582# after the operation concludes. Must be present if a bitmap was
1583# provided, Must NOT be present otherwise. (Since 4.2)
John Snow3c950372019-07-29 16:35:52 -04001584#
1585# @compress: true to compress data, if the target format supports it.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001586# (default: false) (since 2.8)
John Snow3c950372019-07-29 16:35:52 -04001587#
1588# @on-source-error: the action to take on an error on the source,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001589# default 'report'. 'stop' and 'enospc' can only be used if the
1590# block device supports io-status (see BlockInfo).
John Snow3c950372019-07-29 16:35:52 -04001591#
1592# @on-target-error: the action to take on an error on the target,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001593# default 'report' (no limitations, since this applies to a
1594# different block device than @device).
John Snow3c950372019-07-29 16:35:52 -04001595#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001596# @auto-finalize: When false, this job will wait in a PENDING state
1597# after it has finished its work, waiting for @block-job-finalize
1598# before making any block graph changes. When true, this job will
1599# automatically perform its abort or commit actions. Defaults to
1600# true. (Since 2.12)
John Snow3c950372019-07-29 16:35:52 -04001601#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001602# @auto-dismiss: When false, this job will wait in a CONCLUDED state
1603# after it has completely ceased all work, and awaits
1604# @block-job-dismiss. When true, this job will automatically
1605# disappear from the query list without user intervention.
1606# Defaults to true. (Since 2.12)
John Snow3c950372019-07-29 16:35:52 -04001607#
Vladimir Sementsov-Ogievskiy00e30f02019-10-01 16:14:09 +03001608# @filter-node-name: the node name that should be assigned to the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001609# filter driver that the backup job inserts into the graph above
1610# node specified by @drive. If this option is not given, a node
1611# name is autogenerated. (Since: 4.2)
Vladimir Sementsov-Ogievskiy00e30f02019-10-01 16:14:09 +03001612#
Vladimir Sementsov-Ogievskiy0fd05c82024-03-13 18:28:21 +03001613# @discard-source: Discard blocks on source which have already been
1614# copied to the target. (Since 9.1)
1615#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001616# @x-perf: Performance options. (Since 6.0)
Vladimir Sementsov-Ogievskiy86c6a3b2021-01-17 00:46:43 +03001617#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02001618# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001619#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02001620# @unstable: Member @x-perf is experimental.
1621#
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001622# .. note:: @on-source-error and @on-target-error only affect
1623# background I/O. If an error occurs during a guest write request,
1624# the device's rerror/werror actions will be used.
John Snow3c950372019-07-29 16:35:52 -04001625#
1626# Since: 4.2
1627##
1628{ 'struct': 'BackupCommon',
1629 'data': { '*job-id': 'str', 'device': 'str',
1630 'sync': 'MirrorSyncMode', '*speed': 'int',
John Snowc8b56502019-07-29 16:35:52 -04001631 '*bitmap': 'str', '*bitmap-mode': 'BitmapSyncMode',
1632 '*compress': 'bool',
John Snow3c950372019-07-29 16:35:52 -04001633 '*on-source-error': 'BlockdevOnError',
1634 '*on-target-error': 'BlockdevOnError',
Vladimir Sementsov-Ogievskiy00e30f02019-10-01 16:14:09 +03001635 '*auto-finalize': 'bool', '*auto-dismiss': 'bool',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02001636 '*filter-node-name': 'str',
Vladimir Sementsov-Ogievskiy0fd05c82024-03-13 18:28:21 +03001637 '*discard-source': 'bool',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02001638 '*x-perf': { 'type': 'BackupPerf',
1639 'features': [ 'unstable' ] } } }
John Snow3c950372019-07-29 16:35:52 -04001640
1641##
1642# @DriveBackup:
1643#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001644# @target: the target of the new image. If the file exists, or if it
1645# is a device, the existing file/device will be used as the new
1646# destination. If it does not exist, a new file will be created.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001647#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001648# @format: the format of the new destination, default is to probe if
1649# @mode is 'existing', else the format of the source
Benoît Canet1ad166b2014-06-05 13:45:31 +02001650#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001651# @mode: whether and how QEMU should create a new image, default is
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001652# 'absolute-paths'.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001653#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001654# Since: 1.6
1655##
Eric Blake895a2a82015-05-04 09:05:27 -06001656{ 'struct': 'DriveBackup',
John Snow3c950372019-07-29 16:35:52 -04001657 'base': 'BackupCommon',
1658 'data': { 'target': 'str',
1659 '*format': 'str',
1660 '*mode': 'NewImageMode' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001661
1662##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001663# @BlockdevBackup:
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001664#
Kevin Wolf39d990a2016-08-02 19:22:04 +02001665# @target: the device name or node-name of the backup target node.
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001666#
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001667# Since: 2.3
1668##
Eric Blake895a2a82015-05-04 09:05:27 -06001669{ 'struct': 'BlockdevBackup',
John Snow3c950372019-07-29 16:35:52 -04001670 'base': 'BackupCommon',
1671 'data': { 'target': 'str' } }
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001672
1673##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001674# @blockdev-snapshot-sync:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001675#
Max Reitz681b86a2019-06-03 22:22:35 +02001676# Takes a synchronous snapshot of a block device.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001677#
Markus Armbruster2746f062024-02-27 12:39:12 +01001678# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001679# - If @device is not a valid block device, DeviceNotFound
Benoît Canet1ad166b2014-06-05 13:45:31 +02001680#
Markus Armbruster9bc6e892020-11-18 07:41:58 +01001681# Since: 0.14
Marc-André Lureaub4039d82016-06-23 14:04:28 +02001682#
John Snow14b48aa2024-07-16 22:13:08 -04001683# .. qmp-example::
Marc-André Lureaub4039d82016-06-23 14:04:28 +02001684#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001685# -> { "execute": "blockdev-snapshot-sync",
1686# "arguments": { "device": "ide-hd0",
1687# "snapshot-file":
1688# "/some/place/my-image",
1689# "format": "qcow2" } }
1690# <- { "return": {} }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001691##
1692{ 'command': 'blockdev-snapshot-sync',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001693 'data': 'BlockdevSnapshotSync',
1694 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001695
Alberto Garcia43de7e22015-10-26 14:27:16 +02001696##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001697# @blockdev-snapshot:
Alberto Garcia43de7e22015-10-26 14:27:16 +02001698#
Max Reitz681b86a2019-06-03 22:22:35 +02001699# Takes a snapshot of a block device.
Alberto Garcia43de7e22015-10-26 14:27:16 +02001700#
Max Reitz681b86a2019-06-03 22:22:35 +02001701# Take a snapshot, by installing 'node' as the backing image of
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001702# 'overlay'. Additionally, if 'node' is associated with a block
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001703# device, the block device changes to using 'overlay' as its new
1704# active image.
Marc-André Lureau3282eca2016-06-23 14:08:19 +02001705#
Peter Krempac6bdc312020-03-10 12:38:31 +01001706# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001707#
1708# @allow-write-only-overlay: If present, the check whether this
1709# operation is safe was relaxed so that it can be used to change
1710# backing file of a destination of a blockdev-mirror. (since 5.0)
Peter Krempac6bdc312020-03-10 12:38:31 +01001711#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001712# Since: 2.5
Marc-André Lureau3282eca2016-06-23 14:08:19 +02001713#
John Snow14b48aa2024-07-16 22:13:08 -04001714# .. qmp-example::
Marc-André Lureau3282eca2016-06-23 14:08:19 +02001715#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001716# -> { "execute": "blockdev-add",
1717# "arguments": { "driver": "qcow2",
1718# "node-name": "node1534",
1719# "file": { "driver": "file",
1720# "filename": "hd1.qcow2" },
1721# "backing": null } }
Marc-André Lureau3282eca2016-06-23 14:08:19 +02001722#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001723# <- { "return": {} }
Marc-André Lureau3282eca2016-06-23 14:08:19 +02001724#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001725# -> { "execute": "blockdev-snapshot",
1726# "arguments": { "node": "ide-hd0",
1727# "overlay": "node1534" } }
1728# <- { "return": {} }
Alberto Garcia43de7e22015-10-26 14:27:16 +02001729##
1730{ 'command': 'blockdev-snapshot',
Peter Krempac6bdc312020-03-10 12:38:31 +01001731 'data': 'BlockdevSnapshot',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001732 'features': [ 'allow-write-only-overlay' ],
1733 'allow-preconfig': true }
Alberto Garcia43de7e22015-10-26 14:27:16 +02001734
Benoît Canet1ad166b2014-06-05 13:45:31 +02001735##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001736# @change-backing-file:
Jeff Codyfa40e652014-07-01 09:52:16 +02001737#
1738# Change the backing file in the image file metadata. This does not
1739# cause QEMU to reopen the image file to reparse the backing filename
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001740# (it may, however, perform a reopen to change permissions from r/o ->
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001741# r/w -> r/o, if needed). The new backing file string is written into
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001742# the image file metadata, and the QEMU internal strings are updated.
Jeff Codyfa40e652014-07-01 09:52:16 +02001743#
1744# @image-node-name: The name of the block driver state node of the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001745# image to modify. The "device" argument is used to verify
1746# "image-node-name" is in the chain described by "device".
Jeff Codyfa40e652014-07-01 09:52:16 +02001747#
Peter Maydell26ec4e52020-02-13 17:56:26 +00001748# @device: The device name or node-name of the root node that owns
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001749# image-node-name.
Jeff Codyfa40e652014-07-01 09:52:16 +02001750#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001751# @backing-file: The string to write as the backing file. This string
1752# is not validated, so care should be taken when specifying the
1753# string or the image chain may not be able to be reopened again.
Jeff Codyfa40e652014-07-01 09:52:16 +02001754#
Markus Armbruster2746f062024-02-27 12:39:12 +01001755# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001756# - If "device" does not exist or cannot be determined,
1757# DeviceNotFound
Marc-André Lureau280c4b32016-06-23 14:09:20 +02001758#
Jeff Codyfa40e652014-07-01 09:52:16 +02001759# Since: 2.1
1760##
1761{ 'command': 'change-backing-file',
1762 'data': { 'device': 'str', 'image-node-name': 'str',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001763 'backing-file': 'str' },
1764 'allow-preconfig': true }
Jeff Codyfa40e652014-07-01 09:52:16 +02001765
1766##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001767# @block-commit:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001768#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001769# Live commit of data from overlay image nodes into backing nodes -
1770# i.e., writes data between 'top' and 'base' into 'base'.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001771#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001772# If top == base, that is an error. If top has no overlays on top of
1773# it, or if it is in use by a writer, the job will not be completed by
1774# itself. The user needs to complete the job with the
1775# block-job-complete command after getting the ready event. (Since
1776# 2.0)
Max Reitz05ea3852019-06-11 21:19:26 +02001777#
1778# If the base image is smaller than top, then the base image will be
1779# resized to be the same size as top. If top is smaller than the base
1780# image, the base will not be truncated. If you want the base image
1781# size to match the size of the smaller top, you can safely truncate
1782# it yourself once the commit operation successfully completes.
1783#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001784# @job-id: identifier for the newly-created block job. If omitted,
1785# the device name will be used. (Since 2.7)
Alberto Garciafd62c602016-07-05 17:29:00 +03001786#
Peter Maydell26ec4e52020-02-13 17:56:26 +00001787# @device: the device name or node-name of a root node
Benoît Canet1ad166b2014-06-05 13:45:31 +02001788#
Kevin Wolf3c605f42017-06-27 17:18:20 +02001789# @base-node: The node name of the backing image to write data into.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001790# If not specified, this is the deepest backing image.
1791# (since: 3.1)
Benoît Canet1ad166b2014-06-05 13:45:31 +02001792#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001793# @base: Same as @base-node, except that it is a file name rather than
1794# a node name. This must be the exact filename string that was
1795# used to open the node; other strings, even if addressing the
1796# same file, are not accepted
Kevin Wolf3c605f42017-06-27 17:18:20 +02001797#
1798# @top-node: The node name of the backing image within the image chain
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001799# which contains the topmost data to be committed down. If not
1800# specified, this is the active layer. (since: 3.1)
Kevin Wolf3c605f42017-06-27 17:18:20 +02001801#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001802# @top: Same as @top-node, except that it is a file name rather than a
1803# node name. This must be the exact filename string that was used
1804# to open the node; other strings, even if addressing the same
1805# file, are not accepted
Benoît Canet1ad166b2014-06-05 13:45:31 +02001806#
Peter Maydell26ec4e52020-02-13 17:56:26 +00001807# @backing-file: The backing file string to write into the overlay
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001808# image of 'top'. If 'top' does not have an overlay image, or if
1809# 'top' is in use by a writer, specifying a backing file string is
1810# an error.
Jeff Cody54e26902014-06-25 15:40:10 -04001811#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001812# This filename is not validated. If a pathname string is such
1813# that it cannot be resolved by QEMU, that means that subsequent
1814# QMP or HMP commands must use node-names for the image in
1815# question, as filename lookup methods will fail.
Jeff Cody54e26902014-06-25 15:40:10 -04001816#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001817# If not specified, QEMU will automatically determine the backing
1818# file string to use, or error out if there is no obvious choice.
1819# Care should be taken when specifying the string, to specify a
1820# valid filename or protocol. (Since 2.1)
Jeff Cody54e26902014-06-25 15:40:10 -04001821#
Markus Armbruster209e64d2024-03-22 15:09:08 +01001822# @backing-mask-protocol: If true, replace any protocol mentioned in
1823# the 'backing file format' with 'raw', rather than storing the
1824# protocol name as the backing format. Can be used even when no
1825# image header will be updated (default false; since 9.0).
Peter Krempa4b028cb2023-12-05 18:14:41 +01001826#
Peter Maydell26ec4e52020-02-13 17:56:26 +00001827# @speed: the maximum speed, in bytes per second
Benoît Canet1ad166b2014-06-05 13:45:31 +02001828#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001829# @on-error: the action to take on an error. 'ignore' means that the
1830# request should be retried. (default: report; Since: 5.0)
Kevin Wolf8faad1c2020-02-14 21:08:11 +01001831#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01001832# @filter-node-name: the node name that should be assigned to the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001833# filter driver that the commit job inserts into the graph above
1834# @top. If this option is not given, a node name is
1835# autogenerated. (Since: 2.9)
Kevin Wolf0db832f2017-02-20 18:10:05 +01001836#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001837# @auto-finalize: When false, this job will wait in a PENDING state
1838# after it has finished its work, waiting for @block-job-finalize
1839# before making any block graph changes. When true, this job will
1840# automatically perform its abort or commit actions. Defaults to
1841# true. (Since 3.1)
John Snow96fbf532018-09-06 09:02:21 -04001842#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001843# @auto-dismiss: When false, this job will wait in a CONCLUDED state
1844# after it has completely ceased all work, and awaits
1845# @block-job-dismiss. When true, this job will automatically
1846# disappear from the query list without user intervention.
1847# Defaults to true. (Since 3.1)
John Snow96fbf532018-09-06 09:02:21 -04001848#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001849# Features:
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001850#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001851# @deprecated: Members @base and @top are deprecated. Use @base-node
1852# and @top-node instead.
1853#
Markus Armbruster2746f062024-02-27 12:39:12 +01001854# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001855# - If @device does not exist, DeviceNotFound
1856# - Any other error returns a GenericError.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001857#
1858# Since: 1.3
1859#
John Snow14b48aa2024-07-16 22:13:08 -04001860# .. qmp-example::
Marc-André Lureauf44fb582016-06-23 14:10:29 +02001861#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001862# -> { "execute": "block-commit",
1863# "arguments": { "device": "virtio0",
1864# "top": "/tmp/snap1.qcow2" } }
1865# <- { "return": {} }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001866##
1867{ 'command': 'block-commit',
Kevin Wolf3c605f42017-06-27 17:18:20 +02001868 'data': { '*job-id': 'str', 'device': 'str', '*base-node': 'str',
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01001869 '*base': { 'type': 'str', 'features': [ 'deprecated' ] },
1870 '*top-node': 'str',
1871 '*top': { 'type': 'str', 'features': [ 'deprecated' ] },
Peter Krempa4b028cb2023-12-05 18:14:41 +01001872 '*backing-file': 'str', '*backing-mask-protocol': 'bool',
1873 '*speed': 'int',
Kevin Wolf8faad1c2020-02-14 21:08:11 +01001874 '*on-error': 'BlockdevOnError',
John Snow96fbf532018-09-06 09:02:21 -04001875 '*filter-node-name': 'str',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001876 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' },
1877 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001878
1879##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001880# @drive-backup:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001881#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001882# Start a point-in-time copy of a block device to a new destination.
1883# The status of ongoing drive-backup operations can be checked with
1884# query-block-jobs where the BlockJobInfo.type field has the value
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001885# 'backup'. The operation can be stopped before it has completed
1886# using the block-job-cancel command.
Benoît Canet1ad166b2014-06-05 13:45:31 +02001887#
Vladimir Sementsov-Ogievskiy10841592021-11-04 09:58:11 +01001888# Features:
Vladimir Sementsov-Ogievskiy10841592021-11-04 09:58:11 +01001889#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001890# @deprecated: This command is deprecated. Use @blockdev-backup
1891# instead.
1892#
Markus Armbruster2746f062024-02-27 12:39:12 +01001893# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001894# - If @device is not a valid block device, GenericError
Benoît Canet1ad166b2014-06-05 13:45:31 +02001895#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001896# Since: 1.6
Marc-André Lureaub0336412016-06-23 14:11:47 +02001897#
John Snow14b48aa2024-07-16 22:13:08 -04001898# .. qmp-example::
Marc-André Lureaub0336412016-06-23 14:11:47 +02001899#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001900# -> { "execute": "drive-backup",
1901# "arguments": { "device": "drive0",
1902# "sync": "full",
1903# "target": "backup.img" } }
1904# <- { "return": {} }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001905##
Pavel Butsykin81206a82016-07-22 11:17:50 +03001906{ 'command': 'drive-backup', 'boxed': true,
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001907 'data': 'DriveBackup', 'features': ['deprecated'],
1908 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001909
1910##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001911# @blockdev-backup:
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001912#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001913# Start a point-in-time copy of a block device to a new destination.
1914# The status of ongoing blockdev-backup operations can be checked with
1915# query-block-jobs where the BlockJobInfo.type field has the value
Markus Armbruster01bed0f2024-07-29 08:52:20 +02001916# 'backup'. The operation can be stopped before it has completed
1917# using the block-job-cancel command.
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001918#
Markus Armbruster2746f062024-02-27 12:39:12 +01001919# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001920# - If @device is not a valid block device, DeviceNotFound
Pavel Butsykindc7a4a92016-07-22 11:17:51 +03001921#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001922# Since: 2.3
Marc-André Lureau1cf75112016-06-23 14:13:07 +02001923#
John Snow14b48aa2024-07-16 22:13:08 -04001924# .. qmp-example::
Andrea Bolognani4ae65a52022-05-03 09:37:32 +02001925#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001926# -> { "execute": "blockdev-backup",
1927# "arguments": { "device": "src-id",
1928# "sync": "full",
1929# "target": "tgt-id" } }
1930# <- { "return": {} }
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001931##
Pavel Butsykindc7a4a92016-07-22 11:17:51 +03001932{ 'command': 'blockdev-backup', 'boxed': true,
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001933 'data': 'BlockdevBackup',
1934 'allow-preconfig': true }
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001935
Fam Zhengc29c1dd2014-12-18 18:37:05 +08001936##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001937# @query-named-block-nodes:
Benoît Canet1ad166b2014-06-05 13:45:31 +02001938#
1939# Get the named block driver list
1940#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02001941# @flat: Omit the nested data about backing image ("backing-image"
1942# key) if true. Default is false (Since 5.0)
Peter Krempafacda542020-01-20 09:50:49 +01001943#
Benoît Canet1ad166b2014-06-05 13:45:31 +02001944# Returns: the list of BlockDeviceInfo
1945#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04001946# Since: 2.0
Marc-André Lureaue1f34cb2016-06-23 14:13:48 +02001947#
John Snow14b48aa2024-07-16 22:13:08 -04001948# .. qmp-example::
Marc-André Lureaue1f34cb2016-06-23 14:13:48 +02001949#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001950# -> { "execute": "query-named-block-nodes" }
1951# <- { "return": [ { "ro":false,
1952# "drv":"qcow2",
1953# "encrypted":false,
1954# "file":"disks/test.qcow2",
1955# "node-name": "my-node",
1956# "backing_file_depth":1,
1957# "detect_zeroes":"off",
1958# "bps":1000000,
1959# "bps_rd":0,
1960# "bps_wr":0,
1961# "iops":1000000,
1962# "iops_rd":0,
1963# "iops_wr":0,
1964# "bps_max": 8000000,
1965# "bps_rd_max": 0,
1966# "bps_wr_max": 0,
1967# "iops_max": 0,
1968# "iops_rd_max": 0,
1969# "iops_wr_max": 0,
1970# "iops_size": 0,
1971# "write_threshold": 0,
1972# "image":{
1973# "filename":"disks/test.qcow2",
Marc-André Lureaue1f34cb2016-06-23 14:13:48 +02001974# "format":"qcow2",
Markus Armbrusterd23055b2024-02-16 15:58:34 +01001975# "virtual-size":2048000,
1976# "backing_file":"base.qcow2",
1977# "full-backing-filename":"disks/base.qcow2",
1978# "backing-filename-format":"qcow2",
1979# "snapshots":[
1980# {
1981# "id": "1",
1982# "name": "snapshot1",
1983# "vm-state-size": 0,
1984# "date-sec": 10000200,
1985# "date-nsec": 12,
1986# "vm-clock-sec": 206,
1987# "vm-clock-nsec": 30
1988# }
1989# ],
1990# "backing-image":{
1991# "filename":"disks/base.qcow2",
1992# "format":"qcow2",
1993# "virtual-size":2048000
1994# }
1995# } } ] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02001996##
Peter Krempafacda542020-01-20 09:50:49 +01001997{ 'command': 'query-named-block-nodes',
1998 'returns': [ 'BlockDeviceInfo' ],
Paolo Bonzinif55ba802020-11-03 04:37:20 -05001999 'data': { '*flat': 'bool' },
2000 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002001
2002##
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002003# @XDbgBlockGraphNodeType:
2004#
2005# @block-backend: corresponds to BlockBackend
2006#
zhaolichang2400e502020-09-17 15:50:28 +08002007# @block-job: corresponds to BlockJob
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002008#
2009# @block-driver: corresponds to BlockDriverState
2010#
2011# Since: 4.0
2012##
2013{ 'enum': 'XDbgBlockGraphNodeType',
2014 'data': [ 'block-backend', 'block-job', 'block-driver' ] }
2015
2016##
2017# @XDbgBlockGraphNode:
2018#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002019# @id: Block graph node identifier. This @id is generated only for
2020# x-debug-query-block-graph and does not relate to any other
2021# identifiers in Qemu.
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002022#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002023# @type: Type of graph node. Can be one of block-backend, block-job
2024# or block-driver-state.
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002025#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002026# @name: Human readable name of the node. Corresponds to node-name
2027# for block-driver-state nodes; is not guaranteed to be unique in
2028# the whole graph (with block-jobs and block-backends).
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002029#
2030# Since: 4.0
2031##
2032{ 'struct': 'XDbgBlockGraphNode',
2033 'data': { 'id': 'uint64', 'type': 'XDbgBlockGraphNodeType', 'name': 'str' } }
2034
2035##
2036# @BlockPermission:
2037#
2038# Enum of base block permissions.
2039#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002040# @consistent-read: A user that has the "permission" of consistent
2041# reads is guaranteed that their view of the contents of the block
2042# device is complete and self-consistent, representing the
2043# contents of a disk at a specific point. For most block devices
2044# (including their backing files) this is true, but the property
2045# cannot be maintained in a few situations like for intermediate
2046# nodes of a commit block job.
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002047#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002048# @write: This permission is required to change the visible disk
2049# contents.
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002050#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002051# @write-unchanged: This permission (which is weaker than
2052# BLK_PERM_WRITE) is both enough and required for writes to the
2053# block node when the caller promises that the visible disk
2054# content doesn't change. As the BLK_PERM_WRITE permission is
2055# strictly stronger, either is sufficient to perform an unchanging
2056# write.
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002057#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002058# @resize: This permission is required to change the size of a block
2059# node.
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002060#
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002061# Since: 4.0
2062##
Markus Armbrusterfbeed192020-07-30 11:16:56 +02002063{ 'enum': 'BlockPermission',
Vladimir Sementsov-Ogievskiy64631f32021-09-02 12:37:54 +03002064 'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize' ] }
2065
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002066##
2067# @XDbgBlockGraphEdge:
2068#
2069# Block Graph edge description for x-debug-query-block-graph.
2070#
2071# @parent: parent id
2072#
2073# @child: child id
2074#
2075# @name: name of the relation (examples are 'file' and 'backing')
2076#
2077# @perm: granted permissions for the parent operating on the child
2078#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002079# @shared-perm: permissions that can still be granted to other users
2080# of the child while it is still attached to this parent
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002081#
2082# Since: 4.0
2083##
2084{ 'struct': 'XDbgBlockGraphEdge',
2085 'data': { 'parent': 'uint64', 'child': 'uint64',
2086 'name': 'str', 'perm': [ 'BlockPermission' ],
2087 'shared-perm': [ 'BlockPermission' ] } }
2088
2089##
2090# @XDbgBlockGraph:
2091#
2092# Block Graph - list of nodes and list of edges.
2093#
2094# Since: 4.0
2095##
2096{ 'struct': 'XDbgBlockGraph',
2097 'data': { 'nodes': ['XDbgBlockGraphNode'], 'edges': ['XDbgBlockGraphEdge'] } }
2098
2099##
2100# @x-debug-query-block-graph:
2101#
2102# Get the block graph.
2103#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002104# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002105#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002106# @unstable: This command is meant for debugging.
2107#
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002108# Since: 4.0
2109##
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002110{ 'command': 'x-debug-query-block-graph', 'returns': 'XDbgBlockGraph',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002111 'features': [ 'unstable' ],
2112 'allow-preconfig': true }
Vladimir Sementsov-Ogievskiy5d3b4e92018-12-21 20:09:07 +03002113
2114##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002115# @drive-mirror:
Benoît Canet1ad166b2014-06-05 13:45:31 +02002116#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002117# Start mirroring a block device's writes to a new destination.
2118# target specifies the target of the new image. If the file exists,
2119# or if it is a device, it will be used as the new destination for
Markus Armbrusteraa03e162024-03-22 15:09:03 +01002120# writes. If it does not exist, a new file will be created. @format
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002121# specifies the format of the mirror image, default is to probe if
2122# mode='existing', else the format of the source.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002123#
Markus Armbruster2746f062024-02-27 12:39:12 +01002124# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002125# - If @device is not a valid block device, GenericError
Eric Blakefaecd402016-07-14 16:37:58 -06002126#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002127# Since: 1.3
Marc-André Lureau12a21b72016-06-23 14:17:31 +02002128#
John Snow14b48aa2024-07-16 22:13:08 -04002129# .. qmp-example::
Marc-André Lureau12a21b72016-06-23 14:17:31 +02002130#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002131# -> { "execute": "drive-mirror",
2132# "arguments": { "device": "ide-hd0",
2133# "target": "/some/place/my-image",
2134# "sync": "full",
2135# "format": "qcow2" } }
2136# <- { "return": {} }
Eric Blakefaecd402016-07-14 16:37:58 -06002137##
2138{ 'command': 'drive-mirror', 'boxed': true,
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002139 'data': 'DriveMirror',
2140 'allow-preconfig': true }
Eric Blakefaecd402016-07-14 16:37:58 -06002141
2142##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002143# @DriveMirror:
Eric Blakefaecd402016-07-14 16:37:58 -06002144#
2145# A set of parameters describing drive mirror setup.
2146#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002147# @job-id: identifier for the newly-created block job. If omitted,
2148# the device name will be used. (Since 2.7)
Alberto Garcia71aa9862016-07-05 17:28:57 +03002149#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002150# @device: the device name or node-name of a root node whose writes
2151# should be mirrored.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002152#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002153# @target: the target of the new image. If the file exists, or if it
2154# is a device, the existing file/device will be used as the new
2155# destination. If it does not exist, a new file will be created.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002156#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002157# @format: the format of the new destination, default is to probe if
2158# @mode is 'existing', else the format of the source
Benoît Canet1ad166b2014-06-05 13:45:31 +02002159#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002160# @node-name: the new block driver state node name in the graph (Since
2161# 2.1)
Benoît Canet4c828dc2014-06-16 12:00:55 +02002162#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002163# @replaces: with sync=full graph node name to be replaced by the new
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002164# image when a whole image copy is done. This can be used to
2165# repair broken Quorum files. By default, @device is replaced,
2166# although implicitly created filters on it are kept. (Since 2.1)
Benoît Canet09158f02014-06-27 18:25:25 +02002167#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002168# @mode: whether and how QEMU should create a new image, default is
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002169# 'absolute-paths'.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002170#
Andrea Bolognani23e46452022-05-03 09:37:35 +02002171# @speed: the maximum speed, in bytes per second
Benoît Canet1ad166b2014-06-05 13:45:31 +02002172#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002173# @sync: what parts of the disk image should be copied to the
2174# destination (all the disk, only the sectors allocated in the
2175# topmost image, or only new I/O).
Benoît Canet1ad166b2014-06-05 13:45:31 +02002176#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002177# @granularity: granularity of the dirty bitmap, default is 64K if the
2178# image format doesn't have clusters, 4K if the clusters are
2179# smaller than that, else the cluster size. Must be a power of 2
2180# between 512 and 64M (since 1.4).
Benoît Canet1ad166b2014-06-05 13:45:31 +02002181#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002182# @buf-size: maximum amount of data in flight from source to target
2183# (since 1.4).
Benoît Canet1ad166b2014-06-05 13:45:31 +02002184#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002185# @on-source-error: the action to take on an error on the source,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002186# default 'report'. 'stop' and 'enospc' can only be used if the
2187# block device supports io-status (see BlockInfo).
Benoît Canet1ad166b2014-06-05 13:45:31 +02002188#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002189# @on-target-error: the action to take on an error on the target,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002190# default 'report' (no limitations, since this applies to a
2191# different block device than @device).
Andrea Bolognani4ae65a52022-05-03 09:37:32 +02002192#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002193# @unmap: Whether to try to unmap target sectors where source has only
2194# zero. If true, and target unallocated sectors will read as
2195# zero, target image sectors will be unmapped; otherwise, zeroes
2196# will be written. Both will result in identical contents.
2197# Default is true. (Since 2.4)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002198#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002199# @copy-mode: when to copy data to the destination; defaults to
2200# 'background' (Since: 3.0)
Max Reitz481deba2018-06-13 20:18:22 +02002201#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002202# @auto-finalize: When false, this job will wait in a PENDING state
2203# after it has finished its work, waiting for @block-job-finalize
2204# before making any block graph changes. When true, this job will
2205# automatically perform its abort or commit actions. Defaults to
2206# true. (Since 3.1)
John Snowa6b58ad2018-09-06 09:02:22 -04002207#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002208# @auto-dismiss: When false, this job will wait in a CONCLUDED state
2209# after it has completely ceased all work, and awaits
2210# @block-job-dismiss. When true, this job will automatically
2211# disappear from the query list without user intervention.
2212# Defaults to true. (Since 3.1)
Andrea Bolognani4ae65a52022-05-03 09:37:32 +02002213#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002214# Since: 1.3
Benoît Canet1ad166b2014-06-05 13:45:31 +02002215##
Eric Blakefaecd402016-07-14 16:37:58 -06002216{ 'struct': 'DriveMirror',
Alberto Garcia71aa9862016-07-05 17:28:57 +03002217 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str',
2218 '*format': 'str', '*node-name': 'str', '*replaces': 'str',
Benoît Canet1ad166b2014-06-05 13:45:31 +02002219 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode',
2220 '*speed': 'int', '*granularity': 'uint32',
2221 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
Fam Zheng0fc9f8e2015-06-08 13:56:08 +08002222 '*on-target-error': 'BlockdevOnError',
John Snowa6b58ad2018-09-06 09:02:22 -04002223 '*unmap': 'bool', '*copy-mode': 'MirrorCopyMode',
2224 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002225
2226##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002227# @BlockDirtyBitmap:
John Snow341ebc22015-04-17 19:49:52 -04002228#
2229# @node: name of device/node which the bitmap is tracking
2230#
2231# @name: name of the dirty bitmap
2232#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002233# Since: 2.4
John Snow341ebc22015-04-17 19:49:52 -04002234##
Eric Blake895a2a82015-05-04 09:05:27 -06002235{ 'struct': 'BlockDirtyBitmap',
John Snow341ebc22015-04-17 19:49:52 -04002236 'data': { 'node': 'str', 'name': 'str' } }
2237
2238##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002239# @BlockDirtyBitmapAdd:
John Snow341ebc22015-04-17 19:49:52 -04002240#
2241# @node: name of device/node which the bitmap is tracking
2242#
Eric Blakecf7c49c2019-11-13 20:46:33 -06002243# @name: name of the dirty bitmap (must be less than 1024 bytes)
John Snow341ebc22015-04-17 19:49:52 -04002244#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002245# @granularity: the bitmap granularity, default is 64k for
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002246# block-dirty-bitmap-add
John Snow341ebc22015-04-17 19:49:52 -04002247#
Vladimir Sementsov-Ogievskiyfd5ae4c2017-06-28 15:05:23 +03002248# @persistent: the bitmap is persistent, i.e. it will be saved to the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002249# corresponding block device image file on its close. For now
2250# only Qcow2 disks support persistent bitmaps. Default is false
2251# for block-dirty-bitmap-add. (Since: 2.10)
Vladimir Sementsov-Ogievskiyfd5ae4c2017-06-28 15:05:23 +03002252#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002253# @disabled: the bitmap is created in the disabled state, which means
2254# that it will not track drive changes. The bitmap may be enabled
2255# with block-dirty-bitmap-enable. Default is false. (Since: 4.0)
Vladimir Sementsov-Ogievskiya6e2ca52018-06-11 14:53:32 -04002256#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002257# Since: 2.4
John Snow341ebc22015-04-17 19:49:52 -04002258##
Eric Blake895a2a82015-05-04 09:05:27 -06002259{ 'struct': 'BlockDirtyBitmapAdd',
Vladimir Sementsov-Ogievskiyfd5ae4c2017-06-28 15:05:23 +03002260 'data': { 'node': 'str', 'name': 'str', '*granularity': 'uint32',
John Snow3264ffc2019-10-02 19:24:11 -04002261 '*persistent': 'bool', '*disabled': 'bool' } }
John Snow341ebc22015-04-17 19:49:52 -04002262
2263##
Vladimir Sementsov-Ogievskiy1466ef62022-03-15 00:32:24 +03002264# @BlockDirtyBitmapOrStr:
Vladimir Sementsov-Ogievskiyeff08292019-05-28 19:33:31 -04002265#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002266# @local: name of the bitmap, attached to the same node as target
2267# bitmap.
Vladimir Sementsov-Ogievskiyeff08292019-05-28 19:33:31 -04002268#
2269# @external: bitmap with specified node
2270#
2271# Since: 4.1
2272##
Vladimir Sementsov-Ogievskiy1466ef62022-03-15 00:32:24 +03002273{ 'alternate': 'BlockDirtyBitmapOrStr',
Vladimir Sementsov-Ogievskiyeff08292019-05-28 19:33:31 -04002274 'data': { 'local': 'str',
2275 'external': 'BlockDirtyBitmap' } }
2276
2277##
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002278# @BlockDirtyBitmapMerge:
2279#
Vladimir Sementsov-Ogievskiyeff08292019-05-28 19:33:31 -04002280# @node: name of device/node which the @target bitmap is tracking
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002281#
John Snow360d4e42018-12-21 04:35:21 -05002282# @target: name of the destination dirty bitmap
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002283#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002284# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or
2285# fully specified BlockDirtyBitmap elements. The latter are
2286# supported since 4.1.
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002287#
John Snow0e2b7f02018-12-21 04:35:22 -05002288# Since: 4.0
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002289##
2290{ 'struct': 'BlockDirtyBitmapMerge',
Vladimir Sementsov-Ogievskiyeff08292019-05-28 19:33:31 -04002291 'data': { 'node': 'str', 'target': 'str',
Vladimir Sementsov-Ogievskiy1466ef62022-03-15 00:32:24 +03002292 'bitmaps': ['BlockDirtyBitmapOrStr'] } }
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002293
2294##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002295# @block-dirty-bitmap-add:
John Snow341ebc22015-04-17 19:49:52 -04002296#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002297# Create a dirty bitmap with a name on the node, and start tracking
2298# the writes.
John Snow341ebc22015-04-17 19:49:52 -04002299#
Markus Armbruster2746f062024-02-27 12:39:12 +01002300# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002301# - If @node is not a valid block device or node, DeviceNotFound
2302# - If @name is already taken, GenericError with an explanation
John Snow341ebc22015-04-17 19:49:52 -04002303#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002304# Since: 2.4
Marc-André Lureau2258a5d2016-06-23 14:19:37 +02002305#
John Snow14b48aa2024-07-16 22:13:08 -04002306# .. qmp-example::
Marc-André Lureau2258a5d2016-06-23 14:19:37 +02002307#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002308# -> { "execute": "block-dirty-bitmap-add",
2309# "arguments": { "node": "drive0", "name": "bitmap0" } }
2310# <- { "return": {} }
John Snow341ebc22015-04-17 19:49:52 -04002311##
2312{ 'command': 'block-dirty-bitmap-add',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002313 'data': 'BlockDirtyBitmapAdd',
2314 'allow-preconfig': true }
John Snow341ebc22015-04-17 19:49:52 -04002315
2316##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002317# @block-dirty-bitmap-remove:
John Snow341ebc22015-04-17 19:49:52 -04002318#
Marc-André Lureau4bbca422016-06-23 14:23:39 +02002319# Stop write tracking and remove the dirty bitmap that was created
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002320# with block-dirty-bitmap-add. If the bitmap is persistent, remove it
2321# from its storage too.
John Snow341ebc22015-04-17 19:49:52 -04002322#
Markus Armbruster2746f062024-02-27 12:39:12 +01002323# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002324# - If @node is not a valid block device or node, DeviceNotFound
2325# - If @name is not found, GenericError with an explanation
2326# - if @name is frozen by an operation, GenericError
John Snow341ebc22015-04-17 19:49:52 -04002327#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002328# Since: 2.4
Marc-André Lureau4bbca422016-06-23 14:23:39 +02002329#
John Snow14b48aa2024-07-16 22:13:08 -04002330# .. qmp-example::
Marc-André Lureau4bbca422016-06-23 14:23:39 +02002331#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002332# -> { "execute": "block-dirty-bitmap-remove",
2333# "arguments": { "node": "drive0", "name": "bitmap0" } }
2334# <- { "return": {} }
John Snow341ebc22015-04-17 19:49:52 -04002335##
2336{ 'command': 'block-dirty-bitmap-remove',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002337 'data': 'BlockDirtyBitmap',
2338 'allow-preconfig': true }
John Snow341ebc22015-04-17 19:49:52 -04002339
2340##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002341# @block-dirty-bitmap-clear:
John Snowe74e6b72015-04-17 19:49:59 -04002342#
Marc-André Lureau73dffdc2016-06-23 14:25:54 +02002343# Clear (reset) a dirty bitmap on the device, so that an incremental
2344# backup from this point in time forward will only backup clusters
2345# modified after this clear operation.
John Snowe74e6b72015-04-17 19:49:59 -04002346#
Markus Armbruster2746f062024-02-27 12:39:12 +01002347# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002348# - If @node is not a valid block device, DeviceNotFound
2349# - If @name is not found, GenericError with an explanation
John Snowe74e6b72015-04-17 19:49:59 -04002350#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002351# Since: 2.4
Marc-André Lureau73dffdc2016-06-23 14:25:54 +02002352#
John Snow14b48aa2024-07-16 22:13:08 -04002353# .. qmp-example::
Marc-André Lureau73dffdc2016-06-23 14:25:54 +02002354#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002355# -> { "execute": "block-dirty-bitmap-clear",
2356# "arguments": { "node": "drive0", "name": "bitmap0" } }
2357# <- { "return": {} }
John Snowe74e6b72015-04-17 19:49:59 -04002358##
2359{ 'command': 'block-dirty-bitmap-clear',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002360 'data': 'BlockDirtyBitmap',
2361 'allow-preconfig': true }
John Snowe74e6b72015-04-17 19:49:59 -04002362
2363##
John Snow0e2b7f02018-12-21 04:35:22 -05002364# @block-dirty-bitmap-enable:
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002365#
2366# Enables a dirty bitmap so that it will begin tracking disk changes.
2367#
Markus Armbruster2746f062024-02-27 12:39:12 +01002368# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002369# - If @node is not a valid block device, DeviceNotFound
2370# - If @name is not found, GenericError with an explanation
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002371#
John Snow0e2b7f02018-12-21 04:35:22 -05002372# Since: 4.0
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002373#
John Snow14b48aa2024-07-16 22:13:08 -04002374# .. qmp-example::
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002375#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002376# -> { "execute": "block-dirty-bitmap-enable",
2377# "arguments": { "node": "drive0", "name": "bitmap0" } }
2378# <- { "return": {} }
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002379##
Markus Armbrusterfbeed192020-07-30 11:16:56 +02002380{ 'command': 'block-dirty-bitmap-enable',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002381 'data': 'BlockDirtyBitmap',
2382 'allow-preconfig': true }
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002383
2384##
John Snow0e2b7f02018-12-21 04:35:22 -05002385# @block-dirty-bitmap-disable:
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002386#
2387# Disables a dirty bitmap so that it will stop tracking disk changes.
2388#
Markus Armbruster2746f062024-02-27 12:39:12 +01002389# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002390# - If @node is not a valid block device, DeviceNotFound
2391# - If @name is not found, GenericError with an explanation
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002392#
John Snow0e2b7f02018-12-21 04:35:22 -05002393# Since: 4.0
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002394#
John Snow14b48aa2024-07-16 22:13:08 -04002395# .. qmp-example::
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002396#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002397# -> { "execute": "block-dirty-bitmap-disable",
2398# "arguments": { "node": "drive0", "name": "bitmap0" } }
2399# <- { "return": {} }
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002400##
Markus Armbrusterfbeed192020-07-30 11:16:56 +02002401{ 'command': 'block-dirty-bitmap-disable',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002402 'data': 'BlockDirtyBitmap',
2403 'allow-preconfig': true }
Vladimir Sementsov-Ogievskiy5c5d2e52018-06-11 14:53:32 -04002404
2405##
John Snow0e2b7f02018-12-21 04:35:22 -05002406# @block-dirty-bitmap-merge:
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002407#
John Snow360d4e42018-12-21 04:35:21 -05002408# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002409# Dirty bitmaps in @bitmaps will be unchanged, except if it also
2410# appears as the @target bitmap. Any bits already set in @target will
2411# still be set after the merge, i.e., this operation does not clear
2412# the target. On error, @target is unchanged.
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002413#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002414# The resulting bitmap will count as dirty any clusters that were
2415# dirty in any of the source bitmaps. This can be used to achieve
2416# backup checkpoints, or in simpler usages, to copy bitmaps.
John Snow73ab5d62019-02-19 17:49:43 -05002417#
Markus Armbruster2746f062024-02-27 12:39:12 +01002418# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002419# - If @node is not a valid block device, DeviceNotFound
2420# - If any bitmap in @bitmaps or @target is not found,
2421# GenericError
2422# - If any of the bitmaps have different sizes or granularities,
2423# GenericError
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002424#
John Snow0e2b7f02018-12-21 04:35:22 -05002425# Since: 4.0
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002426#
John Snow14b48aa2024-07-16 22:13:08 -04002427# .. qmp-example::
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002428#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002429# -> { "execute": "block-dirty-bitmap-merge",
2430# "arguments": { "node": "drive0", "target": "bitmap0",
2431# "bitmaps": ["bitmap1"] } }
2432# <- { "return": {} }
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002433##
Markus Armbrusterfbeed192020-07-30 11:16:56 +02002434{ 'command': 'block-dirty-bitmap-merge',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002435 'data': 'BlockDirtyBitmapMerge',
2436 'allow-preconfig': true }
Vladimir Sementsov-Ogievskiyb598e532018-06-11 14:53:32 -04002437
2438##
Vladimir Sementsov-Ogievskiya3b52532017-06-28 15:05:25 +03002439# @BlockDirtyBitmapSha256:
2440#
2441# SHA256 hash of dirty bitmap data
2442#
2443# @sha256: ASCII representation of SHA256 bitmap hash
2444#
2445# Since: 2.10
2446##
Markus Armbrusterfbeed192020-07-30 11:16:56 +02002447{ 'struct': 'BlockDirtyBitmapSha256',
2448 'data': {'sha256': 'str'} }
Vladimir Sementsov-Ogievskiya3b52532017-06-28 15:05:25 +03002449
2450##
2451# @x-debug-block-dirty-bitmap-sha256:
2452#
John Snow73ab5d62019-02-19 17:49:43 -05002453# Get bitmap SHA256.
Vladimir Sementsov-Ogievskiya3b52532017-06-28 15:05:25 +03002454#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002455# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002456#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002457# @unstable: This command is meant for debugging.
2458#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002459# Returns:
Markus Armbrustere2c1dcb2024-02-27 12:39:14 +01002460# BlockDirtyBitmapSha256
Markus Armbruster2746f062024-02-27 12:39:12 +01002461#
2462# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002463# - If @node is not a valid block device, DeviceNotFound
2464# - If @name is not found or if hashing has failed, GenericError
2465# with an explanation
Vladimir Sementsov-Ogievskiya3b52532017-06-28 15:05:25 +03002466#
2467# Since: 2.10
2468##
Markus Armbrusterfbeed192020-07-30 11:16:56 +02002469{ 'command': 'x-debug-block-dirty-bitmap-sha256',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002470 'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002471 'features': [ 'unstable' ],
2472 'allow-preconfig': true }
Vladimir Sementsov-Ogievskiya3b52532017-06-28 15:05:25 +03002473
2474##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002475# @blockdev-mirror:
Fam Zhengdf925622015-12-24 12:45:05 +08002476#
2477# Start mirroring a block device's writes to a new destination.
2478#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002479# @job-id: identifier for the newly-created block job. If omitted,
2480# the device name will be used. (Since 2.7)
Alberto Garcia71aa9862016-07-05 17:28:57 +03002481#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002482# @device: The device name or node-name of a root node whose writes
2483# should be mirrored.
Fam Zhengdf925622015-12-24 12:45:05 +08002484#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002485# @target: the id or node-name of the block device to mirror to. This
2486# mustn't be attached to guest.
Fam Zhengdf925622015-12-24 12:45:05 +08002487#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002488# @replaces: with sync=full graph node name to be replaced by the new
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002489# image when a whole image copy is done. This can be used to
2490# repair broken Quorum files. By default, @device is replaced,
2491# although implicitly created filters on it are kept.
Fam Zhengdf925622015-12-24 12:45:05 +08002492#
Andrea Bolognani23e46452022-05-03 09:37:35 +02002493# @speed: the maximum speed, in bytes per second
Fam Zhengdf925622015-12-24 12:45:05 +08002494#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002495# @sync: what parts of the disk image should be copied to the
2496# destination (all the disk, only the sectors allocated in the
2497# topmost image, or only new I/O).
Fam Zhengdf925622015-12-24 12:45:05 +08002498#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002499# @granularity: granularity of the dirty bitmap, default is 64K if the
2500# image format doesn't have clusters, 4K if the clusters are
2501# smaller than that, else the cluster size. Must be a power of 2
2502# between 512 and 64M
Fam Zhengdf925622015-12-24 12:45:05 +08002503#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002504# @buf-size: maximum amount of data in flight from source to target
Fam Zhengdf925622015-12-24 12:45:05 +08002505#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002506# @on-source-error: the action to take on an error on the source,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002507# default 'report'. 'stop' and 'enospc' can only be used if the
2508# block device supports io-status (see BlockInfo).
Fam Zhengdf925622015-12-24 12:45:05 +08002509#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002510# @on-target-error: the action to take on an error on the target,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002511# default 'report' (no limitations, since this applies to a
2512# different block device than @device).
Fam Zhengdf925622015-12-24 12:45:05 +08002513#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002514# @filter-node-name: the node name that should be assigned to the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002515# filter driver that the mirror job inserts into the graph above
2516# @device. If this option is not given, a node name is
2517# autogenerated. (Since: 2.9)
Kevin Wolf6cdbceb2017-02-20 18:10:05 +01002518#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002519# @copy-mode: when to copy data to the destination; defaults to
2520# 'background' (Since: 3.0)
Max Reitz481deba2018-06-13 20:18:22 +02002521#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002522# @auto-finalize: When false, this job will wait in a PENDING state
2523# after it has finished its work, waiting for @block-job-finalize
2524# before making any block graph changes. When true, this job will
2525# automatically perform its abort or commit actions. Defaults to
2526# true. (Since 3.1)
John Snowa6b58ad2018-09-06 09:02:22 -04002527#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002528# @auto-dismiss: When false, this job will wait in a CONCLUDED state
2529# after it has completely ceased all work, and awaits
2530# @block-job-dismiss. When true, this job will automatically
2531# disappear from the query list without user intervention.
2532# Defaults to true. (Since 3.1)
Andrea Bolognani4ae65a52022-05-03 09:37:32 +02002533#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002534# Since: 2.6
Marc-André Lureauf6235a22016-06-23 15:32:39 +02002535#
John Snow14b48aa2024-07-16 22:13:08 -04002536# .. qmp-example::
Marc-André Lureauf6235a22016-06-23 15:32:39 +02002537#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002538# -> { "execute": "blockdev-mirror",
2539# "arguments": { "device": "ide-hd0",
2540# "target": "target0",
2541# "sync": "full" } }
2542# <- { "return": {} }
Fam Zhengdf925622015-12-24 12:45:05 +08002543##
2544{ 'command': 'blockdev-mirror',
Alberto Garcia71aa9862016-07-05 17:28:57 +03002545 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str',
Fam Zhengdf925622015-12-24 12:45:05 +08002546 '*replaces': 'str',
2547 'sync': 'MirrorSyncMode',
2548 '*speed': 'int', '*granularity': 'uint32',
2549 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
Kevin Wolf6cdbceb2017-02-20 18:10:05 +01002550 '*on-target-error': 'BlockdevOnError',
Max Reitz481deba2018-06-13 20:18:22 +02002551 '*filter-node-name': 'str',
John Snowa6b58ad2018-09-06 09:02:22 -04002552 '*copy-mode': 'MirrorCopyMode',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002553 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' },
2554 'allow-preconfig': true }
Fam Zhengdf925622015-12-24 12:45:05 +08002555
2556##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04002557# @BlockIOThrottle:
Eric Blake4dc93972016-07-13 21:50:21 -06002558#
2559# A set of parameters describing block throttling.
2560#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01002561# @device: Block device name
Kevin Wolf7a9877a2016-09-20 13:38:48 +02002562#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002563# @id: The name or QOM path of the guest device (since: 2.8)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002564#
2565# @bps: total throughput limit in bytes per second
2566#
2567# @bps_rd: read throughput limit in bytes per second
2568#
2569# @bps_wr: write throughput limit in bytes per second
2570#
2571# @iops: total I/O operations per second
2572#
Alberto Garciaf5a845f2016-02-18 12:27:08 +02002573# @iops_rd: read I/O operations per second
Benoît Canet1ad166b2014-06-05 13:45:31 +02002574#
2575# @iops_wr: write I/O operations per second
2576#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002577# @bps_max: total throughput limit during bursts, in bytes (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002578#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002579# @bps_rd_max: read throughput limit during bursts, in bytes (Since
2580# 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002581#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002582# @bps_wr_max: write throughput limit during bursts, in bytes (Since
2583# 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002584#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002585# @iops_max: total I/O operations per second during bursts, in bytes
2586# (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002587#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002588# @iops_rd_max: read I/O operations per second during bursts, in bytes
2589# (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002590#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002591# @iops_wr_max: write I/O operations per second during bursts, in
2592# bytes (Since 1.7)
Alberto Garciadce13202016-02-18 12:27:03 +02002593#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002594# @bps_max_length: maximum length of the @bps_max burst period, in
2595# seconds. It must only be set if @bps_max is set as well.
Markus Armbruster5305a4e2024-03-22 15:09:09 +01002596# Defaults to 1. (Since 2.6)
Alberto Garciadce13202016-02-18 12:27:03 +02002597#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002598# @bps_rd_max_length: maximum length of the @bps_rd_max burst period,
2599# in seconds. It must only be set if @bps_rd_max is set as well.
Markus Armbruster5305a4e2024-03-22 15:09:09 +01002600# Defaults to 1. (Since 2.6)
Alberto Garciadce13202016-02-18 12:27:03 +02002601#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002602# @bps_wr_max_length: maximum length of the @bps_wr_max burst period,
2603# in seconds. It must only be set if @bps_wr_max is set as well.
Markus Armbruster5305a4e2024-03-22 15:09:09 +01002604# Defaults to 1. (Since 2.6)
Alberto Garciadce13202016-02-18 12:27:03 +02002605#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002606# @iops_max_length: maximum length of the @iops burst period, in
2607# seconds. It must only be set if @iops_max is set as well.
Markus Armbruster5305a4e2024-03-22 15:09:09 +01002608# Defaults to 1. (Since 2.6)
Alberto Garciadce13202016-02-18 12:27:03 +02002609#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002610# @iops_rd_max_length: maximum length of the @iops_rd_max burst
2611# period, in seconds. It must only be set if @iops_rd_max is set
Markus Armbruster5305a4e2024-03-22 15:09:09 +01002612# as well. Defaults to 1. (Since 2.6)
Alberto Garciadce13202016-02-18 12:27:03 +02002613#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002614# @iops_wr_max_length: maximum length of the @iops_wr_max burst
2615# period, in seconds. It must only be set if @iops_wr_max is set
Markus Armbruster5305a4e2024-03-22 15:09:09 +01002616# as well. Defaults to 1. (Since 2.6)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002617#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002618# @iops_size: an I/O size in bytes (Since 1.7)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002619#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01002620# @group: throttle group name (Since 2.4)
Alberto Garcia76f4afb2015-06-08 18:17:44 +02002621#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01002622# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002623#
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01002624# @deprecated: Member @device is deprecated. Use @id instead.
2625#
Benoît Canet1ad166b2014-06-05 13:45:31 +02002626# Since: 1.1
2627##
Eric Blake4dc93972016-07-13 21:50:21 -06002628{ 'struct': 'BlockIOThrottle',
Markus Armbrusterdf4097a2020-03-17 12:54:51 +01002629 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
2630 '*id': 'str', 'bps': 'int', 'bps_rd': 'int',
Kevin Wolf7a9877a2016-09-20 13:38:48 +02002631 'bps_wr': 'int', 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
Benoît Canet1ad166b2014-06-05 13:45:31 +02002632 '*bps_max': 'int', '*bps_rd_max': 'int',
2633 '*bps_wr_max': 'int', '*iops_max': 'int',
2634 '*iops_rd_max': 'int', '*iops_wr_max': 'int',
Alberto Garciadce13202016-02-18 12:27:03 +02002635 '*bps_max_length': 'int', '*bps_rd_max_length': 'int',
2636 '*bps_wr_max_length': 'int', '*iops_max_length': 'int',
2637 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int',
Alberto Garcia76f4afb2015-06-08 18:17:44 +02002638 '*iops_size': 'int', '*group': 'str' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002639
2640##
Manos Pitsidianakis432d8892017-08-25 16:20:26 +03002641# @ThrottleLimits:
2642#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002643# Limit parameters for throttling. Since some limit combinations are
2644# illegal, limits should always be set in one transaction. All fields
2645# are optional. When setting limits, if a field is missing the
2646# current value is not changed.
Manos Pitsidianakis432d8892017-08-25 16:20:26 +03002647#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002648# @iops-total: limit total I/O operations per second
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002649#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002650# @iops-total-max: I/O operations burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002651#
2652# @iops-total-max-length: length of the iops-total-max burst period,
2653# in seconds It must only be set if @iops-total-max is set as
2654# well.
2655#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002656# @iops-read: limit read operations per second
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002657#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002658# @iops-read-max: I/O operations read burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002659#
2660# @iops-read-max-length: length of the iops-read-max burst period, in
2661# seconds It must only be set if @iops-read-max is set as well.
2662#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002663# @iops-write: limit write operations per second
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002664#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002665# @iops-write-max: I/O operations write burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002666#
2667# @iops-write-max-length: length of the iops-write-max burst period,
2668# in seconds It must only be set if @iops-write-max is set as
2669# well.
2670#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002671# @bps-total: limit total bytes per second
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002672#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002673# @bps-total-max: total bytes burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002674#
2675# @bps-total-max-length: length of the bps-total-max burst period, in
2676# seconds. It must only be set if @bps-total-max is set as well.
2677#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002678# @bps-read: limit read bytes per second
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002679#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002680# @bps-read-max: total bytes read burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002681#
2682# @bps-read-max-length: length of the bps-read-max burst period, in
2683# seconds It must only be set if @bps-read-max is set as well.
2684#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002685# @bps-write: limit write bytes per second
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002686#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002687# @bps-write-max: total bytes write burst
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002688#
2689# @bps-write-max-length: length of the bps-write-max burst period, in
2690# seconds It must only be set if @bps-write-max is set as well.
2691#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002692# @iops-size: when limiting by iops max size of an I/O in bytes
Manos Pitsidianakis432d8892017-08-25 16:20:26 +03002693#
2694# Since: 2.11
2695##
2696{ 'struct': 'ThrottleLimits',
2697 'data': { '*iops-total' : 'int', '*iops-total-max' : 'int',
2698 '*iops-total-max-length' : 'int', '*iops-read' : 'int',
2699 '*iops-read-max' : 'int', '*iops-read-max-length' : 'int',
2700 '*iops-write' : 'int', '*iops-write-max' : 'int',
2701 '*iops-write-max-length' : 'int', '*bps-total' : 'int',
2702 '*bps-total-max' : 'int', '*bps-total-max-length' : 'int',
2703 '*bps-read' : 'int', '*bps-read-max' : 'int',
2704 '*bps-read-max-length' : 'int', '*bps-write' : 'int',
2705 '*bps-write-max' : 'int', '*bps-write-max-length' : 'int',
2706 '*iops-size' : 'int' } }
2707
2708##
Kevin Wolf381bd742020-10-20 12:47:58 +02002709# @ThrottleGroupProperties:
2710#
2711# Properties for throttle-group objects.
2712#
Kevin Wolf381bd742020-10-20 12:47:58 +02002713# @limits: limits to apply for this throttle group
2714#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002715# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002716#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002717# @unstable: All members starting with x- are aliases for the same key
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002718# without x- in the @limits object. This is not a stable
2719# interface and may be removed or changed incompatibly in the
2720# future. Use @limits for a supported stable interface.
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002721#
Kevin Wolf381bd742020-10-20 12:47:58 +02002722# Since: 2.11
2723##
2724{ 'struct': 'ThrottleGroupProperties',
2725 'data': { '*limits': 'ThrottleLimits',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02002726 '*x-iops-total': { 'type': 'int',
2727 'features': [ 'unstable' ] },
2728 '*x-iops-total-max': { 'type': 'int',
2729 'features': [ 'unstable' ] },
2730 '*x-iops-total-max-length': { 'type': 'int',
2731 'features': [ 'unstable' ] },
2732 '*x-iops-read': { 'type': 'int',
2733 'features': [ 'unstable' ] },
2734 '*x-iops-read-max': { 'type': 'int',
2735 'features': [ 'unstable' ] },
2736 '*x-iops-read-max-length': { 'type': 'int',
2737 'features': [ 'unstable' ] },
2738 '*x-iops-write': { 'type': 'int',
2739 'features': [ 'unstable' ] },
2740 '*x-iops-write-max': { 'type': 'int',
2741 'features': [ 'unstable' ] },
2742 '*x-iops-write-max-length': { 'type': 'int',
2743 'features': [ 'unstable' ] },
2744 '*x-bps-total': { 'type': 'int',
2745 'features': [ 'unstable' ] },
2746 '*x-bps-total-max': { 'type': 'int',
2747 'features': [ 'unstable' ] },
2748 '*x-bps-total-max-length': { 'type': 'int',
2749 'features': [ 'unstable' ] },
2750 '*x-bps-read': { 'type': 'int',
2751 'features': [ 'unstable' ] },
2752 '*x-bps-read-max': { 'type': 'int',
2753 'features': [ 'unstable' ] },
2754 '*x-bps-read-max-length': { 'type': 'int',
2755 'features': [ 'unstable' ] },
2756 '*x-bps-write': { 'type': 'int',
2757 'features': [ 'unstable' ] },
2758 '*x-bps-write-max': { 'type': 'int',
2759 'features': [ 'unstable' ] },
2760 '*x-bps-write-max-length': { 'type': 'int',
2761 'features': [ 'unstable' ] },
2762 '*x-iops-size': { 'type': 'int',
2763 'features': [ 'unstable' ] } } }
Kevin Wolf381bd742020-10-20 12:47:58 +02002764
2765##
Benoît Canet1ad166b2014-06-05 13:45:31 +02002766# @block-stream:
2767#
2768# Copy data from a backing file into a block device.
2769#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002770# The block streaming operation is performed in the background until
2771# the entire backing file has been copied. This command returns
2772# immediately once streaming has started. The status of ongoing block
2773# streaming operations can be checked with query-block-jobs. The
2774# operation can be stopped before it has completed using the
2775# block-job-cancel command.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002776#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002777# The node that receives the data is called the top image, can be
2778# located in any part of the chain (but always above the base image;
2779# see below) and can be specified using its device or node name.
2780# Earlier qemu versions only allowed 'device' to name the top level
2781# node; presence of the 'base-node' parameter during introspection can
2782# be used as a witness of the enhanced semantics of 'device'.
Alberto Garcia554b6142016-10-28 10:08:11 +03002783#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002784# If a base file is specified then sectors are not copied from that
2785# base file and its backing chain. This can be used to stream a
2786# subset of the backing file chain instead of flattening the entire
2787# image. When streaming completes the image file will have the base
2788# file as its backing file, unless that node was changed while the job
2789# was running. In that case, base's parent's backing (or filtered,
2790# whichever exists) child (i.e., base at the beginning of the job)
2791# will be the new backing file.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002792#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002793# On successful completion the image file is updated to drop the
2794# backing file and the BLOCK_JOB_COMPLETED event is emitted.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002795#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002796# In case @device is a filter node, block-stream modifies the first
2797# non-filter overlay node below it to point to the new backing node
2798# instead of modifying @device itself.
Max Reitz67acfd22019-06-12 17:48:11 +02002799#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002800# @job-id: identifier for the newly-created block job. If omitted,
2801# the device name will be used. (Since 2.7)
Alberto Garcia23233222016-07-05 17:28:59 +03002802#
Alberto Garcia554b6142016-10-28 10:08:11 +03002803# @device: the device or node name of the top image
Benoît Canet1ad166b2014-06-05 13:45:31 +02002804#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002805# @base: the common backing file name. It cannot be set if @base-node
2806# or @bottom is also set.
Alberto Garcia312fe092016-10-28 10:08:19 +03002807#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002808# @base-node: the node name of the backing file. It cannot be set if
2809# @base or @bottom is also set. (Since 2.8)
Vladimir Sementsov-Ogievskiy7f4a3962020-12-16 09:17:00 +03002810#
2811# @bottom: the last node in the chain that should be streamed into
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002812# top. It cannot be set if @base or @base-node is also set. It
2813# cannot be filter node. (Since 6.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002814#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002815# @backing-file: The backing file string to write into the top image.
2816# This filename is not validated.
Jeff Cody13d8cc52014-06-25 15:40:11 -04002817#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002818# If a pathname string is such that it cannot be resolved by QEMU,
2819# that means that subsequent QMP or HMP commands must use
2820# node-names for the image in question, as filename lookup methods
2821# will fail.
Jeff Cody13d8cc52014-06-25 15:40:11 -04002822#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002823# If not specified, QEMU will automatically determine the backing
2824# file string to use, or error out if there is no obvious choice.
2825# Care should be taken when specifying the string, to specify a
2826# valid filename or protocol. (Since 2.1)
Jeff Cody13d8cc52014-06-25 15:40:11 -04002827#
Markus Armbruster209e64d2024-03-22 15:09:08 +01002828# @backing-mask-protocol: If true, replace any protocol mentioned in
2829# the 'backing file format' with 'raw', rather than storing the
2830# protocol name as the backing format. Can be used even when no
2831# image header will be updated (default false; since 9.0).
Peter Krempa72098a32023-12-05 18:14:42 +01002832#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002833# @speed: the maximum speed, in bytes per second
Benoît Canet1ad166b2014-06-05 13:45:31 +02002834#
Markus Armbruster01bed0f2024-07-29 08:52:20 +02002835# @on-error: the action to take on an error (default report). 'stop'
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002836# and 'enospc' can only be used if the block device supports
2837# io-status (see BlockInfo). (Since 1.3)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002838#
Andrey Shinkevich880747a2020-12-16 09:16:54 +03002839# @filter-node-name: the node name that should be assigned to the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002840# filter driver that the stream job inserts into the graph above
2841# @device. If this option is not given, a node name is
2842# autogenerated. (Since: 6.0)
Andrey Shinkevich880747a2020-12-16 09:16:54 +03002843#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002844# @auto-finalize: When false, this job will wait in a PENDING state
2845# after it has finished its work, waiting for @block-job-finalize
2846# before making any block graph changes. When true, this job will
2847# automatically perform its abort or commit actions. Defaults to
2848# true. (Since 3.1)
John Snow241ca1a2018-09-06 09:02:23 -04002849#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002850# @auto-dismiss: When false, this job will wait in a CONCLUDED state
2851# after it has completely ceased all work, and awaits
2852# @block-job-dismiss. When true, this job will automatically
2853# disappear from the query list without user intervention.
2854# Defaults to true. (Since 3.1)
John Snow241ca1a2018-09-06 09:02:23 -04002855#
Markus Armbruster2746f062024-02-27 12:39:12 +01002856# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002857# - If @device does not exist, DeviceNotFound.
Marc-André Lureau49b37c22016-06-23 14:52:13 +02002858#
Benoît Canet1ad166b2014-06-05 13:45:31 +02002859# Since: 1.1
Marc-André Lureau49b37c22016-06-23 14:52:13 +02002860#
John Snow14b48aa2024-07-16 22:13:08 -04002861# .. qmp-example::
Marc-André Lureau49b37c22016-06-23 14:52:13 +02002862#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01002863# -> { "execute": "block-stream",
2864# "arguments": { "device": "virtio0",
2865# "base": "/tmp/master.qcow2" } }
2866# <- { "return": {} }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002867##
2868{ 'command': 'block-stream',
Alberto Garcia23233222016-07-05 17:28:59 +03002869 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str',
Peter Krempa72098a32023-12-05 18:14:42 +01002870 '*base-node': 'str', '*backing-file': 'str',
2871 '*backing-mask-protocol': 'bool',
2872 '*bottom': 'str',
Vladimir Sementsov-Ogievskiy7f4a3962020-12-16 09:17:00 +03002873 '*speed': 'int', '*on-error': 'BlockdevOnError',
Andrey Shinkevich880747a2020-12-16 09:16:54 +03002874 '*filter-node-name': 'str',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002875 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' },
2876 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002877
2878##
2879# @block-job-set-speed:
2880#
2881# Set maximum speed for a background block operation.
2882#
2883# This command can only be issued when there is an active block job.
2884#
2885# Throttling can be disabled by setting the speed to 0.
2886#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002887# @device: The job identifier. This used to be a device name (hence
2888# the name of the parameter), but since QEMU 2.7 it can have other
2889# values.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002890#
Peter Maydell26ec4e52020-02-13 17:56:26 +00002891# @speed: the maximum speed, in bytes per second, or 0 for unlimited.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002892# Defaults to 0.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002893#
Markus Armbruster2746f062024-02-27 12:39:12 +01002894# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002895# - If no background operation is active on this device,
2896# DeviceNotActive
Benoît Canet1ad166b2014-06-05 13:45:31 +02002897#
2898# Since: 1.1
2899##
2900{ 'command': 'block-job-set-speed',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002901 'data': { 'device': 'str', 'speed': 'int' },
2902 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002903
2904##
2905# @block-job-cancel:
2906#
2907# Stop an active background block operation.
2908#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002909# This command returns immediately after marking the active background
2910# block operation for cancellation. It is an error to call this
2911# command if no operation is in progress.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002912#
2913# The operation will cancel as soon as possible and then emit the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002914# BLOCK_JOB_CANCELLED event. Before that happens the job is still
2915# visible when enumerated using query-block-jobs.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002916#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002917# Note that if you issue 'block-job-cancel' after 'drive-mirror' has
2918# indicated (via the event BLOCK_JOB_READY) that the source and
2919# destination are synchronized, then the event triggered by this
2920# command changes to BLOCK_JOB_COMPLETED, to indicate that the
2921# mirroring has ended and the destination now has a point-in-time copy
2922# tied to the time of the cancellation.
Kashyap Chamarthyc117bb12017-11-21 12:52:53 +01002923#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002924# For streaming, the image file retains its backing file unless the
2925# streaming operation happens to complete just as it is being
2926# cancelled. A new streaming operation can be started at a later time
2927# to finish copying all data from the backing file.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002928#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002929# @device: The job identifier. This used to be a device name (hence
2930# the name of the parameter), but since QEMU 2.7 it can have other
2931# values.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002932#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002933# @force: If true, and the job has already emitted the event
2934# BLOCK_JOB_READY, abandon the job immediately (even if it is
2935# paused) instead of waiting for the destination to complete its
2936# final synchronization (since 1.3)
Benoît Canet1ad166b2014-06-05 13:45:31 +02002937#
Markus Armbruster2746f062024-02-27 12:39:12 +01002938# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002939# - If no background operation is active on this device,
2940# DeviceNotActive
Benoît Canet1ad166b2014-06-05 13:45:31 +02002941#
2942# Since: 1.1
2943##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002944{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' },
2945 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002946
2947##
2948# @block-job-pause:
2949#
2950# Pause an active background block operation.
2951#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002952# This command returns immediately after marking the active background
2953# block operation for pausing. It is an error to call this command if
2954# no operation is in progress or if the job is already paused.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002955#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002956# The operation will pause as soon as possible. No event is emitted
2957# when the operation is actually paused. Cancelling a paused job
2958# automatically resumes it.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002959#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002960# @device: The job identifier. This used to be a device name (hence
2961# the name of the parameter), but since QEMU 2.7 it can have other
2962# values.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002963#
Markus Armbruster2746f062024-02-27 12:39:12 +01002964# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002965# - If no background operation is active on this device,
2966# DeviceNotActive
Benoît Canet1ad166b2014-06-05 13:45:31 +02002967#
2968# Since: 1.3
2969##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002970{ 'command': 'block-job-pause', 'data': { 'device': 'str' },
2971 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002972
2973##
2974# @block-job-resume:
2975#
2976# Resume an active background block operation.
2977#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002978# This command returns immediately after resuming a paused background
2979# block operation. It is an error to call this command if no
2980# operation is in progress or if the job is not paused.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002981#
2982# This command also clears the error status of the job.
2983#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002984# @device: The job identifier. This used to be a device name (hence
2985# the name of the parameter), but since QEMU 2.7 it can have other
2986# values.
Benoît Canet1ad166b2014-06-05 13:45:31 +02002987#
Markus Armbruster2746f062024-02-27 12:39:12 +01002988# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02002989# - If no background operation is active on this device,
2990# DeviceNotActive
Benoît Canet1ad166b2014-06-05 13:45:31 +02002991#
2992# Since: 1.3
2993##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05002994{ 'command': 'block-job-resume', 'data': { 'device': 'str' },
2995 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02002996
2997##
2998# @block-job-complete:
2999#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003000# Manually trigger completion of an active background block operation.
3001# This is supported for drive mirroring, where it also switches the
3002# device to write to the target path only. The ability to complete is
3003# signaled with a BLOCK_JOB_READY event.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003004#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003005# This command completes an active background block operation
3006# synchronously. The ordering of this command's return with the
3007# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
3008# occurs during the processing of this command: 1) the command itself
3009# will fail; 2) the error will be processed according to the
3010# rerror/werror arguments that were specified when starting the
3011# operation.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003012#
3013# A cancelled or paused job cannot be completed.
3014#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003015# @device: The job identifier. This used to be a device name (hence
3016# the name of the parameter), but since QEMU 2.7 it can have other
3017# values.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003018#
Markus Armbruster2746f062024-02-27 12:39:12 +01003019# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003020# - If no background operation is active on this device,
3021# DeviceNotActive
Benoît Canet1ad166b2014-06-05 13:45:31 +02003022#
3023# Since: 1.3
3024##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05003025{ 'command': 'block-job-complete', 'data': { 'device': 'str' },
3026 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003027
3028##
John Snow75f71052018-03-10 03:27:36 -05003029# @block-job-dismiss:
3030#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003031# For jobs that have already concluded, remove them from the
3032# block-job-query list. This command only needs to be run for jobs
3033# which were started with QEMU 2.12+ job lifetime management
3034# semantics.
John Snow75f71052018-03-10 03:27:36 -05003035#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003036# This command will refuse to operate on any job that has not yet
Markus Armbruster01bed0f2024-07-29 08:52:20 +02003037# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
3038# make use of the BLOCK_JOB_READY event, block-job-cancel or
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003039# block-job-complete will still need to be used as appropriate.
John Snow75f71052018-03-10 03:27:36 -05003040#
3041# @id: The job identifier.
3042#
John Snow75f71052018-03-10 03:27:36 -05003043# Since: 2.12
3044##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05003045{ 'command': 'block-job-dismiss', 'data': { 'id': 'str' },
3046 'allow-preconfig': true }
John Snow75f71052018-03-10 03:27:36 -05003047
3048##
John Snow11b61fb2018-03-10 03:27:43 -05003049# @block-job-finalize:
3050#
3051# Once a job that has manual=true reaches the pending state, it can be
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003052# instructed to finalize any graph changes and do any necessary
3053# cleanup via this command. For jobs in a transaction, instructing
3054# one job to finalize will force ALL jobs in the transaction to
3055# finalize, so it is only necessary to instruct a single member job to
3056# finalize.
John Snow11b61fb2018-03-10 03:27:43 -05003057#
3058# @id: The job identifier.
3059#
John Snow11b61fb2018-03-10 03:27:43 -05003060# Since: 2.12
3061##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05003062{ 'command': 'block-job-finalize', 'data': { 'id': 'str' },
3063 'allow-preconfig': true }
John Snow11b61fb2018-03-10 03:27:43 -05003064
3065##
Fiona Ebner2d400d12023-10-31 14:54:26 +01003066# @BlockJobChangeOptionsMirror:
3067#
3068# @copy-mode: Switch to this copy mode. Currently, only the switch
3069# from 'background' to 'write-blocking' is implemented.
3070#
3071# Since: 8.2
3072##
3073{ 'struct': 'BlockJobChangeOptionsMirror',
3074 'data': { 'copy-mode' : 'MirrorCopyMode' } }
3075
3076##
Fiona Ebner61a3a5a2023-10-31 14:54:22 +01003077# @BlockJobChangeOptions:
3078#
3079# Block job options that can be changed after job creation.
3080#
3081# @id: The job identifier
3082#
3083# @type: The job type
3084#
Markus Armbruster37507c12024-01-20 10:53:27 +01003085# Since: 8.2
Fiona Ebner61a3a5a2023-10-31 14:54:22 +01003086##
3087{ 'union': 'BlockJobChangeOptions',
3088 'base': { 'id': 'str', 'type': 'JobType' },
3089 'discriminator': 'type',
Fiona Ebner2d400d12023-10-31 14:54:26 +01003090 'data': { 'mirror': 'BlockJobChangeOptionsMirror' } }
Fiona Ebner61a3a5a2023-10-31 14:54:22 +01003091
3092##
3093# @block-job-change:
3094#
3095# Change the block job's options.
3096#
3097# Since: 8.2
3098##
3099{ 'command': 'block-job-change',
3100 'data': 'BlockJobChangeOptions', 'boxed': true }
3101
3102##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003103# @BlockdevDiscardOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003104#
3105# Determines how to handle discard requests.
3106#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003107# @ignore: Ignore the request
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003108#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003109# @unmap: Forward as an unmap request
Benoît Canet1ad166b2014-06-05 13:45:31 +02003110#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003111# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003112##
3113{ 'enum': 'BlockdevDiscardOptions',
3114 'data': [ 'ignore', 'unmap' ] }
3115
3116##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003117# @BlockdevDetectZeroesOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003118#
3119# Describes the operation mode for the automatic conversion of plain
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003120# zero writes by the OS to driver specific optimized zero write
3121# commands.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003122#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003123# @off: Disabled (default)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003124#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003125# @on: Enabled
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003126#
3127# @unmap: Enabled and even try to unmap blocks if possible. This
3128# requires also that @BlockdevDiscardOptions is set to unmap for
3129# this device.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003130#
3131# Since: 2.1
3132##
3133{ 'enum': 'BlockdevDetectZeroesOptions',
3134 'data': [ 'off', 'on', 'unmap' ] }
3135
3136##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003137# @BlockdevAioOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003138#
3139# Selects the AIO backend to handle I/O requests
3140#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003141# @threads: Use qemu's thread pool
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003142#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003143# @native: Use native AIO backend (only Linux and Windows)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003144#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003145# @io_uring: Use linux io_uring (since 5.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003146#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003147# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003148##
3149{ 'enum': 'BlockdevAioOptions',
Aarushi Mehtaf14beae2020-01-20 14:18:45 +00003150 'data': [ 'threads', 'native',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04003151 { 'name': 'io_uring', 'if': 'CONFIG_LINUX_IO_URING' } ] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003152
3153##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003154# @BlockdevCacheOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003155#
3156# Includes cache-related options for block devices
3157#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003158# @direct: enables use of O_DIRECT (bypass the host page cache;
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003159# default: false)
3160#
3161# @no-flush: ignore any flush requests for the device (default: false)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003162#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003163# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003164##
Eric Blake895a2a82015-05-04 09:05:27 -06003165{ 'struct': 'BlockdevCacheOptions',
Kevin Wolfaaa436f2016-03-14 13:16:51 +01003166 'data': { '*direct': 'bool',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003167 '*no-flush': 'bool' } }
3168
3169##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003170# @BlockdevDriver:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003171#
3172# Drivers that are supported in block device operations.
3173#
Manos Pitsidianakisd8e7d872017-08-25 16:20:27 +03003174# @throttle: Since 2.11
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003175#
Fam Zhengd87ee3d2018-01-16 14:09:01 +08003176# @nvme: Since 2.12
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003177#
Peter Maydell51f63ec2018-05-22 11:39:56 +01003178# @copy-on-read: Since 3.0
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003179#
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003180# @blklogwrites: Since 3.0
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003181#
Pavel Dovgalyuk35e32d92019-10-16 11:40:39 +03003182# @blkreplay: Since 4.2
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003183#
Andrey Shinkevichf41388e2019-12-02 15:15:04 +03003184# @compress: Since 5.0
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003185#
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03003186# @copy-before-write: Since 6.2
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003187#
Vladimir Sementsov-Ogievskiy1c14eaa2022-03-03 20:43:44 +01003188# @snapshot-access: Since 7.0
Ashish Mittalda92c3f2017-04-03 20:48:08 -07003189#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003190# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003191##
3192{ 'enum': 'BlockdevDriver',
Pavel Dovgalyuk35e32d92019-10-16 11:40:39 +03003193 'data': [ 'blkdebug', 'blklogwrites', 'blkreplay', 'blkverify', 'bochs',
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03003194 'cloop', 'compress', 'copy-before-write', 'copy-on-read', 'dmg',
Vladimir Sementsov-Ogievskiy1c14eaa2022-03-03 20:43:44 +01003195 'file', 'snapshot-access', 'ftp', 'ftps', 'gluster',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04003196 {'name': 'host_cdrom', 'if': 'HAVE_HOST_BLOCK_DEVICE' },
3197 {'name': 'host_device', 'if': 'HAVE_HOST_BLOCK_DEVICE' },
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04003198 'http', 'https',
3199 { 'name': 'io_uring', 'if': 'CONFIG_BLKIO' },
3200 'iscsi',
3201 'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme',
3202 { 'name': 'nvme-io_uring', 'if': 'CONFIG_BLKIO' },
3203 'parallels', 'preallocate', 'qcow', 'qcow2', 'qed', 'quorum',
3204 'raw', 'rbd',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04003205 { 'name': 'replication', 'if': 'CONFIG_REPLICATION' },
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04003206 'ssh', 'throttle', 'vdi', 'vhdx',
Alberto Faria03d9e4c2022-10-28 14:16:35 +01003207 { 'name': 'virtio-blk-vfio-pci', 'if': 'CONFIG_BLKIO' },
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04003208 { 'name': 'virtio-blk-vhost-user', 'if': 'CONFIG_BLKIO' },
3209 { 'name': 'virtio-blk-vhost-vdpa', 'if': 'CONFIG_BLKIO' },
3210 'vmdk', 'vpc', 'vvfat' ] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003211
3212##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003213# @BlockdevOptionsFile:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003214#
Kevin Wolf68555282016-09-08 13:08:20 +02003215# Driver specific block device options for the file backend.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003216#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003217# @filename: path to the image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003218#
3219# @pr-manager: the id for the object that will handle persistent
3220# reservations for this device (default: none, forward the
3221# commands via SG_IO; since 2.11)
3222#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003223# @aio: AIO backend (default: threads) (since: 2.8)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003224#
3225# @aio-max-batch: maximum number of requests to batch together into a
3226# single submission in the AIO backend. The smallest value
3227# between this and the aio-max-batch value of the IOThread object
3228# is chosen. 0 means that the AIO backend will handle it
3229# automatically. (default: 0, since 6.2)
3230#
3231# @locking: whether to enable file locking. If set to 'auto', only
3232# enable when Open File Descriptor (OFD) locking API is available
3233# (default: auto, since 2.10)
3234#
3235# @drop-cache: invalidate page cache during live migration. This
3236# prevents stale data on the migration destination with
3237# cache.direct=off. Currently only supported on Linux hosts.
3238# (default: on, since: 4.0)
3239#
3240# @x-check-cache-dropped: whether to check that page cache was dropped
3241# on live migration. May cause noticeable delays if the image
3242# file is large, do not use in production. (default: off)
3243# (since: 3.0)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003244#
Kevin Wolfc9d40702019-06-06 17:38:02 +02003245# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003246#
3247# @dynamic-auto-read-only: If present, enabled auto-read-only means
3248# that the driver will open the image read-only at first,
3249# dynamically reopen the image file read-write when the first
3250# writer is attached to the node and reopen read-only when the
3251# last writer is detached. This allows giving QEMU write
3252# permissions only on demand when an operation actually needs
3253# write access.
3254#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02003255# @unstable: Member x-check-cache-dropped is meant for debugging.
Kevin Wolfc9d40702019-06-06 17:38:02 +02003256#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003257# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003258##
Eric Blake895a2a82015-05-04 09:05:27 -06003259{ 'struct': 'BlockdevOptionsFile',
Kevin Wolf0a4279d2016-09-08 15:09:01 +02003260 'data': { 'filename': 'str',
Paolo Bonzini7c9e5272017-08-21 18:58:56 +02003261 '*pr-manager': 'str',
Fam Zheng16b48d52017-05-03 00:35:50 +08003262 '*locking': 'OnOffAuto',
Stefan Hajnoczi31be8a22018-04-27 17:23:12 +01003263 '*aio': 'BlockdevAioOptions',
Stefano Garzarella684960d2021-10-26 18:23:44 +02003264 '*aio-max-batch': 'int',
Peter Maydelldbb28bc2020-02-13 17:56:27 +00003265 '*drop-cache': {'type': 'bool',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04003266 'if': 'CONFIG_LINUX'},
Markus Armbruster9fb49da2021-10-28 12:25:13 +02003267 '*x-check-cache-dropped': { 'type': 'bool',
3268 'features': [ 'unstable' ] } },
Kevin Wolfc9d40702019-06-06 17:38:02 +02003269 'features': [ { 'name': 'dynamic-auto-read-only',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04003270 'if': 'CONFIG_POSIX' } ] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003271
3272##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003273# @BlockdevOptionsNull:
Fam Zhenge819ab22014-09-11 14:09:56 +08003274#
3275# Driver specific block device options for the null backend.
3276#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003277# @size: size of the device in bytes.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003278#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01003279# @latency-ns: emulated latency (in nanoseconds) in processing
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003280# requests. Default to zero which completes requests immediately.
3281# (Since 2.4)
3282#
3283# @read-zeroes: if true, reads from the device produce zeroes; if
3284# false, the buffer is left unchanged.
3285# (default: false; since: 4.1)
Fam Zhenge819ab22014-09-11 14:09:56 +08003286#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003287# Since: 2.9
Fam Zhenge819ab22014-09-11 14:09:56 +08003288##
Eric Blake895a2a82015-05-04 09:05:27 -06003289{ 'struct': 'BlockdevOptionsNull',
Kevin Wolf128b05f2019-06-17 13:54:48 +02003290 'data': { '*size': 'int', '*latency-ns': 'uint64', '*read-zeroes': 'bool' } }
Fam Zhenge819ab22014-09-11 14:09:56 +08003291
3292##
Fam Zhengd87ee3d2018-01-16 14:09:01 +08003293# @BlockdevOptionsNVMe:
3294#
3295# Driver specific block device options for the NVMe backend.
3296#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003297# @device: PCI controller address of the NVMe device in format
3298# hhhh:bb:ss.f (host:bus:slot.function)
3299#
Fam Zhengd87ee3d2018-01-16 14:09:01 +08003300# @namespace: namespace number of the device, starting from 1.
3301#
Daniel P. Berrangéecaf6472019-12-06 14:38:11 +00003302# Note that the PCI @device must have been unbound from any host
3303# kernel driver before instructing QEMU to add the blockdev.
3304#
Fam Zhengd87ee3d2018-01-16 14:09:01 +08003305# Since: 2.12
3306##
3307{ 'struct': 'BlockdevOptionsNVMe',
3308 'data': { 'device': 'str', 'namespace': 'int' } }
3309
3310##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003311# @BlockdevOptionsVVFAT:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003312#
3313# Driver specific block device options for the vvfat protocol.
3314#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003315# @dir: directory to be exported as FAT image
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003316#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003317# @fat-type: FAT type: 12, 16 or 32
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003318#
3319# @floppy: whether to export a floppy image (true) or partitioned hard
3320# disk (false; default)
3321#
3322# @label: set the volume label, limited to 11 bytes. FAT16 and FAT32
3323# traditionally have some restrictions on labels, which are
3324# ignored by most operating systems. Defaults to "QEMU VVFAT".
3325# (since 2.4)
3326#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003327# @rw: whether to allow write operations (default: false)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003328#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003329# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003330##
Eric Blake895a2a82015-05-04 09:05:27 -06003331{ 'struct': 'BlockdevOptionsVVFAT',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003332 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool',
Wolfgang Bumillerd5941dd2015-06-19 11:35:29 +02003333 '*label': 'str', '*rw': 'bool' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003334
3335##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003336# @BlockdevOptionsGenericFormat:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003337#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003338# Driver specific block device options for image format that have no
3339# option besides their data source.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003340#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003341# @file: reference to or definition of the data source block device
Benoît Canet1ad166b2014-06-05 13:45:31 +02003342#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003343# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003344##
Eric Blake895a2a82015-05-04 09:05:27 -06003345{ 'struct': 'BlockdevOptionsGenericFormat',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003346 'data': { 'file': 'BlockdevRef' } }
3347
3348##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003349# @BlockdevOptionsLUKS:
Daniel P. Berrange78368572016-03-21 14:11:47 +00003350#
3351# Driver specific block device options for LUKS.
3352#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003353# @key-secret: the ID of a QCryptoSecret object providing the
Markus Armbruster01bed0f2024-07-29 08:52:20 +02003354# decryption key (since 2.6). Mandatory except when doing a
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003355# metadata-only probe of the image.
Daniel P. Berrange78368572016-03-21 14:11:47 +00003356#
Markus Armbruster5305a4e2024-03-22 15:09:09 +01003357# @header: block device holding a detached LUKS header. (since 9.0)
Hyman Huang9ad5c4e2024-01-30 13:37:19 +08003358#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003359# Since: 2.9
Daniel P. Berrange78368572016-03-21 14:11:47 +00003360##
3361{ 'struct': 'BlockdevOptionsLUKS',
3362 'base': 'BlockdevOptionsGenericFormat',
Hyman Huang9ad5c4e2024-01-30 13:37:19 +08003363 'data': { '*key-secret': 'str',
3364 '*header': 'BlockdevRef'} }
Daniel P. Berrange78368572016-03-21 14:11:47 +00003365
Daniel P. Berrange78368572016-03-21 14:11:47 +00003366##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003367# @BlockdevOptionsGenericCOWFormat:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003368#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003369# Driver specific block device options for image format that have no
3370# option besides their data source and an optional backing file.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003371#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003372# @backing: reference to or definition of the backing file block
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003373# device, null disables the backing file entirely. Defaults to
3374# the backing file stored the image file.
Benoît Canet1ad166b2014-06-05 13:45:31 +02003375#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003376# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003377##
Eric Blake895a2a82015-05-04 09:05:27 -06003378{ 'struct': 'BlockdevOptionsGenericCOWFormat',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003379 'base': 'BlockdevOptionsGenericFormat',
Markus Armbrusterc42e8742017-07-18 08:54:00 +02003380 'data': { '*backing': 'BlockdevRefOrNull' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003381
3382##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003383# @Qcow2OverlapCheckMode:
Max Reitzf6585812014-08-20 19:59:36 +02003384#
3385# General overlap check modes.
3386#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003387# @none: Do not perform any checks
Max Reitzf6585812014-08-20 19:59:36 +02003388#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003389# @constant: Perform only checks which can be done in constant time
3390# and without reading anything from disk
Max Reitzf6585812014-08-20 19:59:36 +02003391#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003392# @cached: Perform only checks which can be done without reading
3393# anything from disk
Max Reitzf6585812014-08-20 19:59:36 +02003394#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003395# @all: Perform all available overlap checks
Max Reitzf6585812014-08-20 19:59:36 +02003396#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003397# Since: 2.9
Max Reitzf6585812014-08-20 19:59:36 +02003398##
3399{ 'enum': 'Qcow2OverlapCheckMode',
3400 'data': [ 'none', 'constant', 'cached', 'all' ] }
3401
3402##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003403# @Qcow2OverlapCheckFlags:
Max Reitzf6585812014-08-20 19:59:36 +02003404#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003405# Structure of flags for each metadata structure. Setting a field to
Vladimir Sementsov-Ogievskiy125f9732024-03-25 15:00:54 +03003406# 'true' makes QEMU guard that Qcow2 format structure against
3407# unintended overwriting. See Qcow2 format specification for detailed
3408# information on these structures. The default value is chosen
3409# according to the template given.
Max Reitzf6585812014-08-20 19:59:36 +02003410#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003411# @template: Specifies a template mode which can be adjusted using the
3412# other flags, defaults to 'cached'
Max Reitzf6585812014-08-20 19:59:36 +02003413#
Vladimir Sementsov-Ogievskiy125f9732024-03-25 15:00:54 +03003414# @main-header: Qcow2 format header
3415#
3416# @active-l1: Qcow2 active L1 table
3417#
3418# @active-l2: Qcow2 active L2 table
3419#
3420# @refcount-table: Qcow2 refcount table
3421#
3422# @refcount-block: Qcow2 refcount blocks
3423#
3424# @snapshot-table: Qcow2 snapshot table
3425#
3426# @inactive-l1: Qcow2 inactive L1 tables
3427#
3428# @inactive-l2: Qcow2 inactive L2 tables
3429#
3430# @bitmap-directory: Qcow2 bitmap directory (since 3.0)
Vladimir Sementsov-Ogievskiy0e4e4312018-07-05 18:15:15 +03003431#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003432# Since: 2.9
Max Reitzf6585812014-08-20 19:59:36 +02003433##
Eric Blake895a2a82015-05-04 09:05:27 -06003434{ 'struct': 'Qcow2OverlapCheckFlags',
Vladimir Sementsov-Ogievskiy0e4e4312018-07-05 18:15:15 +03003435 'data': { '*template': 'Qcow2OverlapCheckMode',
3436 '*main-header': 'bool',
3437 '*active-l1': 'bool',
3438 '*active-l2': 'bool',
3439 '*refcount-table': 'bool',
3440 '*refcount-block': 'bool',
3441 '*snapshot-table': 'bool',
3442 '*inactive-l1': 'bool',
3443 '*inactive-l2': 'bool',
3444 '*bitmap-directory': 'bool' } }
Max Reitzf6585812014-08-20 19:59:36 +02003445
3446##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003447# @Qcow2OverlapChecks:
Max Reitzf6585812014-08-20 19:59:36 +02003448#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003449# Specifies which metadata structures should be guarded against
3450# unintended overwriting.
Max Reitzf6585812014-08-20 19:59:36 +02003451#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003452# @flags: set of flags for separate specification of each metadata
3453# structure type
Max Reitzf6585812014-08-20 19:59:36 +02003454#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003455# @mode: named mode which chooses a specific set of flags
Max Reitzf6585812014-08-20 19:59:36 +02003456#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003457# Since: 2.9
Max Reitzf6585812014-08-20 19:59:36 +02003458##
Eric Blakeab916fa2015-05-04 09:05:13 -06003459{ 'alternate': 'Qcow2OverlapChecks',
Max Reitzf6585812014-08-20 19:59:36 +02003460 'data': { 'flags': 'Qcow2OverlapCheckFlags',
3461 'mode': 'Qcow2OverlapCheckMode' } }
3462
3463##
Daniel P. Berranged85f4222017-06-23 17:24:08 +01003464# @BlockdevQcowEncryptionFormat:
3465#
3466# @aes: AES-CBC with plain64 initialization vectors
3467#
3468# Since: 2.10
3469##
3470{ 'enum': 'BlockdevQcowEncryptionFormat',
3471 'data': [ 'aes' ] }
3472
3473##
3474# @BlockdevQcowEncryption:
3475#
Markus Armbruster89a22732024-02-05 08:47:09 +01003476# @format: encryption format
3477#
Daniel P. Berranged85f4222017-06-23 17:24:08 +01003478# Since: 2.10
3479##
3480{ 'union': 'BlockdevQcowEncryption',
3481 'base': { 'format': 'BlockdevQcowEncryptionFormat' },
3482 'discriminator': 'format',
3483 'data': { 'aes': 'QCryptoBlockOptionsQCow' } }
3484
3485##
3486# @BlockdevOptionsQcow:
3487#
3488# Driver specific block device options for qcow.
3489#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003490# @encrypt: Image decryption options. Mandatory for encrypted images,
3491# except when doing a metadata-only probe of the image.
Daniel P. Berranged85f4222017-06-23 17:24:08 +01003492#
3493# Since: 2.10
3494##
3495{ 'struct': 'BlockdevOptionsQcow',
3496 'base': 'BlockdevOptionsGenericCOWFormat',
3497 'data': { '*encrypt': 'BlockdevQcowEncryption' } }
3498
Daniel P. Berrangeb25b3872017-06-23 17:24:10 +01003499##
3500# @BlockdevQcow2EncryptionFormat:
John Snowa9e2eb02021-09-30 16:57:07 -04003501#
Eric Blake58823a02019-02-06 14:28:48 -06003502# @aes: AES-CBC with plain64 initialization vectors
Daniel P. Berrangeb25b3872017-06-23 17:24:10 +01003503#
3504# Since: 2.10
3505##
3506{ 'enum': 'BlockdevQcow2EncryptionFormat',
Daniel P. Berrange4652b8f2017-06-23 17:24:12 +01003507 'data': [ 'aes', 'luks' ] }
Daniel P. Berrangeb25b3872017-06-23 17:24:10 +01003508
3509##
3510# @BlockdevQcow2Encryption:
3511#
Markus Armbruster89a22732024-02-05 08:47:09 +01003512# @format: encryption format
3513#
Daniel P. Berrangeb25b3872017-06-23 17:24:10 +01003514# Since: 2.10
3515##
3516{ 'union': 'BlockdevQcow2Encryption',
3517 'base': { 'format': 'BlockdevQcow2EncryptionFormat' },
3518 'discriminator': 'format',
Daniel P. Berrange4652b8f2017-06-23 17:24:12 +01003519 'data': { 'aes': 'QCryptoBlockOptionsQCow',
3520 'luks': 'QCryptoBlockOptionsLUKS'} }
Daniel P. Berrangeb25b3872017-06-23 17:24:10 +01003521
Daniel P. Berranged85f4222017-06-23 17:24:08 +01003522##
Vladimir Sementsov-Ogievskiy33fa2222020-10-21 17:58:46 +03003523# @BlockdevOptionsPreallocate:
3524#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003525# Filter driver intended to be inserted between format and protocol
3526# node and do preallocation in protocol node on write.
Vladimir Sementsov-Ogievskiy33fa2222020-10-21 17:58:46 +03003527#
3528# @prealloc-align: on preallocation, align file length to this number,
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003529# default 1048576 (1M)
Vladimir Sementsov-Ogievskiy33fa2222020-10-21 17:58:46 +03003530#
3531# @prealloc-size: how much to preallocate, default 134217728 (128M)
3532#
3533# Since: 6.0
3534##
3535{ 'struct': 'BlockdevOptionsPreallocate',
3536 'base': 'BlockdevOptionsGenericFormat',
3537 'data': { '*prealloc-align': 'int', '*prealloc-size': 'int' } }
3538
3539##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003540# @BlockdevOptionsQcow2:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003541#
3542# Driver specific block device options for qcow2.
3543#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003544# @lazy-refcounts: whether to enable the lazy refcounts feature
3545# (default is taken from the image file)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003546#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003547# @pass-discard-request: whether discard requests to the qcow2 device
3548# should be forwarded to the data source
Benoît Canet1ad166b2014-06-05 13:45:31 +02003549#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01003550# @pass-discard-snapshot: whether discard requests for the data source
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003551# should be issued when a snapshot operation (e.g. deleting a
3552# snapshot) frees clusters in the qcow2 file
Benoît Canet1ad166b2014-06-05 13:45:31 +02003553#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003554# @pass-discard-other: whether discard requests for the data source
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003555# should be issued on other occasions where a cluster gets freed
Benoît Canet1ad166b2014-06-05 13:45:31 +02003556#
Jean-Louis Dupondb2b10902023-10-03 14:52:37 +02003557# @discard-no-unref: when enabled, data clusters will remain
3558# preallocated when they are no longer used, e.g. because they are
3559# discarded or converted to zero clusters. As usual, whether the
3560# old data is discarded or kept on the protocol level (i.e. in the
3561# image file) depends on the setting of the pass-discard-request
3562# option. Keeping the clusters preallocated prevents qcow2
3563# fragmentation that would otherwise be caused by freeing and
3564# re-allocating them later. Besides potential performance
3565# degradation, such fragmentation can lead to increased allocation
3566# of clusters past the end of the image file, resulting in image
Markus Armbruster209e64d2024-03-22 15:09:08 +01003567# files whose file length can grow much larger than their guest
3568# disk size would suggest. If image file length is of concern
3569# (e.g. when storing qcow2 images directly on block devices), you
3570# should consider enabling this option. (since 8.1)
Jean-Louis Dupond42a28902023-06-05 10:45:24 +02003571#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003572# @overlap-check: which overlap checks to perform for writes to the
3573# image, defaults to 'cached' (since 2.2)
Max Reitzf6585812014-08-20 19:59:36 +02003574#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003575# @cache-size: the maximum total size of the L2 table and refcount
3576# block caches in bytes (since 2.2)
Max Reitzf6585812014-08-20 19:59:36 +02003577#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003578# @l2-cache-size: the maximum size of the L2 table cache in bytes
3579# (since 2.2)
Max Reitzf6585812014-08-20 19:59:36 +02003580#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003581# @l2-cache-entry-size: the size of each entry in the L2 cache in
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003582# bytes. It must be a power of two between 512 and the cluster
3583# size. The default value is the cluster size (since 2.12)
Alberto Garcia1221fe62018-02-05 16:33:36 +02003584#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003585# @refcount-cache-size: the maximum size of the refcount block cache
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003586# in bytes (since 2.2)
Max Reitzf6585812014-08-20 19:59:36 +02003587#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003588# @cache-clean-interval: clean unused entries in the L2 and refcount
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003589# caches. The interval is in seconds. The default value is 600
3590# on supporting platforms, and 0 on other platforms. 0 disables
3591# this feature. (since 2.5)
Leonid Bloche957b502018-09-26 19:04:46 +03003592#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003593# @encrypt: Image decryption options. Mandatory for encrypted images,
3594# except when doing a metadata-only probe of the image. (since
3595# 2.10)
Alberto Garcia279621c2015-08-04 15:14:40 +03003596#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003597# @data-file: reference to or definition of the external data file.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003598# This may only be specified for images that require an external
3599# data file. If it is not specified for such an image, the data
3600# file name is loaded from the image file. (since 4.0)
Kevin Wolf0e8c08b2019-01-29 17:13:57 +01003601#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003602# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003603##
Eric Blake895a2a82015-05-04 09:05:27 -06003604{ 'struct': 'BlockdevOptionsQcow2',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003605 'base': 'BlockdevOptionsGenericCOWFormat',
3606 'data': { '*lazy-refcounts': 'bool',
3607 '*pass-discard-request': 'bool',
3608 '*pass-discard-snapshot': 'bool',
Max Reitzf6585812014-08-20 19:59:36 +02003609 '*pass-discard-other': 'bool',
Jean-Louis Dupond42a28902023-06-05 10:45:24 +02003610 '*discard-no-unref': 'bool',
Max Reitzf6585812014-08-20 19:59:36 +02003611 '*overlap-check': 'Qcow2OverlapChecks',
3612 '*cache-size': 'int',
3613 '*l2-cache-size': 'int',
Alberto Garcia1221fe62018-02-05 16:33:36 +02003614 '*l2-cache-entry-size': 'int',
Alberto Garcia279621c2015-08-04 15:14:40 +03003615 '*refcount-cache-size': 'int',
Daniel P. Berrangeb25b3872017-06-23 17:24:10 +01003616 '*cache-clean-interval': 'int',
Kevin Wolf0e8c08b2019-01-29 17:13:57 +01003617 '*encrypt': 'BlockdevQcow2Encryption',
3618 '*data-file': 'BlockdevRef' } }
Chrysostomos Nanakosb1de5f42014-07-30 20:59:09 +03003619
3620##
Kevin Wolfec2f5412018-02-05 14:59:05 +01003621# @SshHostKeyCheckMode:
3622#
Peter Maydellf5627502020-02-13 17:56:25 +00003623# @none: Don't check the host key at all
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003624#
Peter Maydellf5627502020-02-13 17:56:25 +00003625# @hash: Compare the host key with a given hash
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003626#
Peter Maydellf5627502020-02-13 17:56:25 +00003627# @known_hosts: Check the host key against the known_hosts file
Kevin Wolfec2f5412018-02-05 14:59:05 +01003628#
3629# Since: 2.12
3630##
3631{ 'enum': 'SshHostKeyCheckMode',
3632 'data': [ 'none', 'hash', 'known_hosts' ] }
3633
3634##
3635# @SshHostKeyCheckHashType:
3636#
Peter Maydellf5627502020-02-13 17:56:25 +00003637# @md5: The given hash is an md5 hash
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003638#
Peter Maydellf5627502020-02-13 17:56:25 +00003639# @sha1: The given hash is an sha1 hash
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003640#
Daniel P. Berrangébf783262021-06-22 12:51:56 +01003641# @sha256: The given hash is an sha256 hash
Kevin Wolfec2f5412018-02-05 14:59:05 +01003642#
3643# Since: 2.12
3644##
3645{ 'enum': 'SshHostKeyCheckHashType',
Daniel P. Berrangébf783262021-06-22 12:51:56 +01003646 'data': [ 'md5', 'sha1', 'sha256' ] }
Kevin Wolfec2f5412018-02-05 14:59:05 +01003647
3648##
3649# @SshHostKeyHash:
3650#
Peter Maydellf5627502020-02-13 17:56:25 +00003651# @type: The hash algorithm used for the hash
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003652#
Peter Maydellf5627502020-02-13 17:56:25 +00003653# @hash: The expected hash value
Kevin Wolfec2f5412018-02-05 14:59:05 +01003654#
3655# Since: 2.12
3656##
3657{ 'struct': 'SshHostKeyHash',
3658 'data': { 'type': 'SshHostKeyCheckHashType',
3659 'hash': 'str' }}
3660
3661##
Kevin Wolfec2f5412018-02-05 14:59:05 +01003662# @SshHostKeyCheck:
3663#
Markus Armbruster89a22732024-02-05 08:47:09 +01003664# @mode: How to check the host key
3665#
Kevin Wolfec2f5412018-02-05 14:59:05 +01003666# Since: 2.12
3667##
3668{ 'union': 'SshHostKeyCheck',
3669 'base': { 'mode': 'SshHostKeyCheckMode' },
3670 'discriminator': 'mode',
Anton Nefedov29cd0402018-06-18 11:40:06 +03003671 'data': { 'hash': 'SshHostKeyHash' } }
Kevin Wolfec2f5412018-02-05 14:59:05 +01003672
3673##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003674# @BlockdevOptionsSsh:
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303675#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02003676# @server: host address
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303677#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02003678# @path: path to the image on the host
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303679#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02003680# @user: user as which to connect, defaults to current local user name
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303681#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02003682# @host-key-check: Defines how and what to check the host key against
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003683# (default: known_hosts)
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303684#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003685# Since: 2.9
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303686##
3687{ 'struct': 'BlockdevOptionsSsh',
3688 'data': { 'server': 'InetSocketAddress',
3689 'path': 'str',
Kevin Wolfec2f5412018-02-05 14:59:05 +01003690 '*user': 'str',
3691 '*host-key-check': 'SshHostKeyCheck' } }
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05303692
Benoît Canet1ad166b2014-06-05 13:45:31 +02003693##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003694# @BlkdebugEvent:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003695#
3696# Trigger events supported by blkdebug.
Eric Blakea31939e2015-11-18 01:52:54 -07003697#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003698# @l1_shrink_write_table: write zeros to the l1 table to shrink image.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003699# (since 2.11)
Pavel Butsykin46b732c2017-09-18 15:42:29 +03003700#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003701# @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11)
Pavel Butsykin46b732c2017-09-18 15:42:29 +03003702#
Eric Blaked855ebc2017-10-05 14:02:46 -05003703# @cor_write: a write due to copy-on-read (since 2.11)
3704#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003705# @cluster_alloc_space: an allocation of file space for a cluster
3706# (since 4.1)
Anton Nefedovc8bb23c2019-05-16 17:27:49 +03003707#
Max Reitzf8cec152019-05-07 22:35:05 +02003708# @none: triggers once at creation of the blkdebug node (since 4.1)
3709#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003710# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003711##
Eric Blakea31939e2015-11-18 01:52:54 -07003712{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG',
Eric Blake5be5b772015-11-18 01:52:55 -07003713 'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table',
3714 'l1_grow_activate_table', 'l2_load', 'l2_update',
3715 'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003716 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio',
3717 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read',
3718 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update',
3719 'refblock_load', 'refblock_update', 'refblock_update_part',
Eric Blake5be5b772015-11-18 01:52:55 -07003720 'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write',
3721 'refblock_alloc_write_blocks', 'refblock_alloc_write_table',
3722 'refblock_alloc_switch_table', 'cluster_alloc',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003723 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os',
Eric Blake5be5b772015-11-18 01:52:55 -07003724 'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head',
3725 'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev',
Pavel Butsykin46b732c2017-09-18 15:42:29 +03003726 'pwritev_zero', 'pwritev_done', 'empty_image_prepare',
Eric Blaked855ebc2017-10-05 14:02:46 -05003727 'l1_shrink_write_table', 'l1_shrink_free_l2_clusters',
Max Reitzf8cec152019-05-07 22:35:05 +02003728 'cor_write', 'cluster_alloc_space', 'none'] }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003729
3730##
Max Reitz16789db2019-05-07 22:35:04 +02003731# @BlkdebugIOType:
3732#
3733# Kinds of I/O that blkdebug can inject errors in.
3734#
3735# @read: .bdrv_co_preadv()
3736#
3737# @write: .bdrv_co_pwritev()
3738#
3739# @write-zeroes: .bdrv_co_pwrite_zeroes()
3740#
3741# @discard: .bdrv_co_pdiscard()
3742#
3743# @flush: .bdrv_co_flush_to_disk()
3744#
Max Reitz1adb0b52019-05-07 22:35:06 +02003745# @block-status: .bdrv_co_block_status()
3746#
Max Reitz16789db2019-05-07 22:35:04 +02003747# Since: 4.1
3748##
3749{ 'enum': 'BlkdebugIOType', 'prefix': 'BLKDEBUG_IO_TYPE',
Max Reitz1adb0b52019-05-07 22:35:06 +02003750 'data': [ 'read', 'write', 'write-zeroes', 'discard', 'flush',
3751 'block-status' ] }
Max Reitz16789db2019-05-07 22:35:04 +02003752
3753##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003754# @BlkdebugInjectErrorOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003755#
3756# Describes a single error injection for blkdebug.
3757#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003758# @event: trigger event
Benoît Canet1ad166b2014-06-05 13:45:31 +02003759#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003760# @state: the state identifier blkdebug needs to be in to actually
3761# trigger the event; defaults to "any"
Benoît Canet1ad166b2014-06-05 13:45:31 +02003762#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003763# @iotype: the type of I/O operations on which this error should be
3764# injected; defaults to "all read, write, write-zeroes, discard,
3765# and flush operations" (since: 4.1)
Max Reitz16789db2019-05-07 22:35:04 +02003766#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003767# @errno: error identifier (errno) to be returned; defaults to EIO
Benoît Canet1ad166b2014-06-05 13:45:31 +02003768#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003769# @sector: specifies the sector index which has to be affected in
3770# order to actually trigger the event; defaults to "any sector"
Benoît Canet1ad166b2014-06-05 13:45:31 +02003771#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003772# @once: disables further events after this one has been triggered;
3773# defaults to false
Benoît Canet1ad166b2014-06-05 13:45:31 +02003774#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01003775# @immediately: fail immediately; defaults to false
Benoît Canet1ad166b2014-06-05 13:45:31 +02003776#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003777# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003778##
Eric Blake895a2a82015-05-04 09:05:27 -06003779{ 'struct': 'BlkdebugInjectErrorOptions',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003780 'data': { 'event': 'BlkdebugEvent',
3781 '*state': 'int',
Max Reitz16789db2019-05-07 22:35:04 +02003782 '*iotype': 'BlkdebugIOType',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003783 '*errno': 'int',
3784 '*sector': 'int',
3785 '*once': 'bool',
3786 '*immediately': 'bool' } }
3787
3788##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003789# @BlkdebugSetStateOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003790#
3791# Describes a single state-change event for blkdebug.
3792#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003793# @event: trigger event
Benoît Canet1ad166b2014-06-05 13:45:31 +02003794#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003795# @state: the current state identifier blkdebug needs to be in;
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003796# defaults to "any"
Benoît Canet1ad166b2014-06-05 13:45:31 +02003797#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003798# @new_state: the state identifier blkdebug is supposed to assume if
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003799# this event is triggered
Benoît Canet1ad166b2014-06-05 13:45:31 +02003800#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003801# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003802##
Eric Blake895a2a82015-05-04 09:05:27 -06003803{ 'struct': 'BlkdebugSetStateOptions',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003804 'data': { 'event': 'BlkdebugEvent',
3805 '*state': 'int',
3806 'new_state': 'int' } }
3807
3808##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003809# @BlockdevOptionsBlkdebug:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003810#
3811# Driver specific block device options for blkdebug.
3812#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003813# @image: underlying raw block device (or image file)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003814#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003815# @config: filename of the configuration file
Benoît Canet1ad166b2014-06-05 13:45:31 +02003816#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003817# @align: required alignment for requests in bytes, must be positive
3818# power of 2, or 0 for default
Eric Blake430b26a2017-04-29 14:14:18 -05003819#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003820# @max-transfer: maximum size for I/O transfers in bytes, must be
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003821# positive multiple of @align and of the underlying file's request
3822# alignment (but need not be a power of 2), or 0 for default
3823# (since 2.10)
Eric Blake430b26a2017-04-29 14:14:18 -05003824#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003825# @opt-write-zero: preferred alignment for write zero requests in
3826# bytes, must be positive multiple of @align and of the underlying
3827# file's request alignment (but need not be a power of 2), or 0
3828# for default (since 2.10)
Eric Blake430b26a2017-04-29 14:14:18 -05003829#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003830# @max-write-zero: maximum size for write zero requests in bytes, must
3831# be positive multiple of @align, of @opt-write-zero, and of the
3832# underlying file's request alignment (but need not be a power of
3833# 2), or 0 for default (since 2.10)
Eric Blake430b26a2017-04-29 14:14:18 -05003834#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003835# @opt-discard: preferred alignment for discard requests in bytes,
3836# must be positive multiple of @align and of the underlying file's
3837# request alignment (but need not be a power of 2), or 0 for
3838# default (since 2.10)
Eric Blake430b26a2017-04-29 14:14:18 -05003839#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003840# @max-discard: maximum size for discard requests in bytes, must be
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003841# positive multiple of @align, of @opt-discard, and of the
3842# underlying file's request alignment (but need not be a power of
3843# 2), or 0 for default (since 2.10)
Benoît Canet1ad166b2014-06-05 13:45:31 +02003844#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003845# @inject-error: array of error injection descriptions
Benoît Canet1ad166b2014-06-05 13:45:31 +02003846#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003847# @set-state: array of state-change descriptions
Benoît Canet1ad166b2014-06-05 13:45:31 +02003848#
Max Reitz69c64492019-11-08 13:34:53 +01003849# @take-child-perms: Permissions to take on @image in addition to what
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003850# is necessary anyway (which depends on how the blkdebug node is
3851# used). Defaults to none. (since 5.0)
Max Reitz69c64492019-11-08 13:34:53 +01003852#
3853# @unshare-child-perms: Permissions not to share on @image in addition
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003854# to what cannot be shared anyway (which depends on how the
3855# blkdebug node is used). Defaults to none. (since 5.0)
Max Reitz69c64492019-11-08 13:34:53 +01003856#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003857# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003858##
Eric Blake895a2a82015-05-04 09:05:27 -06003859{ 'struct': 'BlockdevOptionsBlkdebug',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003860 'data': { 'image': 'BlockdevRef',
3861 '*config': 'str',
Eric Blake430b26a2017-04-29 14:14:18 -05003862 '*align': 'int', '*max-transfer': 'int32',
3863 '*opt-write-zero': 'int32', '*max-write-zero': 'int32',
3864 '*opt-discard': 'int32', '*max-discard': 'int32',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003865 '*inject-error': ['BlkdebugInjectErrorOptions'],
Max Reitz69c64492019-11-08 13:34:53 +01003866 '*set-state': ['BlkdebugSetStateOptions'],
3867 '*take-child-perms': ['BlockPermission'],
3868 '*unshare-child-perms': ['BlockPermission'] } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003869
3870##
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003871# @BlockdevOptionsBlklogwrites:
3872#
3873# Driver specific block device options for blklogwrites.
3874#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003875# @file: block device
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003876#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003877# @log: block device used to log writes to @file
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003878#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003879# @log-sector-size: sector size used in logging writes to @file,
3880# determines granularity of offsets and sizes of writes
3881# (default: 512)
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003882#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003883# @log-append: append to an existing log (default: false)
Ari Sundholm7769eaa2018-07-06 17:01:36 +03003884#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003885# @log-super-update-interval: interval of write requests after which
3886# the log super block is updated to disk (default: 4096)
Ari Sundholm1dce6982018-07-04 17:59:36 +03003887#
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003888# Since: 3.0
3889##
3890{ 'struct': 'BlockdevOptionsBlklogwrites',
3891 'data': { 'file': 'BlockdevRef',
3892 'log': 'BlockdevRef',
Ari Sundholm0878b3c2018-07-04 17:59:35 +03003893 '*log-sector-size': 'uint32',
Ari Sundholm1dce6982018-07-04 17:59:36 +03003894 '*log-append': 'bool',
3895 '*log-super-update-interval': 'uint64' } }
Aapo Vienamobfcc2242018-07-03 17:48:48 +03003896
3897##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003898# @BlockdevOptionsBlkverify:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003899#
3900# Driver specific block device options for blkverify.
3901#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003902# @test: block device to be tested
Benoît Canet1ad166b2014-06-05 13:45:31 +02003903#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003904# @raw: raw image used for verification
Benoît Canet1ad166b2014-06-05 13:45:31 +02003905#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003906# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003907##
Eric Blake895a2a82015-05-04 09:05:27 -06003908{ 'struct': 'BlockdevOptionsBlkverify',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003909 'data': { 'test': 'BlockdevRef',
3910 'raw': 'BlockdevRef' } }
3911
3912##
Pavel Dovgalyuk35e32d92019-10-16 11:40:39 +03003913# @BlockdevOptionsBlkreplay:
3914#
3915# Driver specific block device options for blkreplay.
3916#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003917# @image: disk image which should be controlled with blkreplay
Pavel Dovgalyuk35e32d92019-10-16 11:40:39 +03003918#
3919# Since: 4.2
3920##
3921{ 'struct': 'BlockdevOptionsBlkreplay',
3922 'data': { 'image': 'BlockdevRef' } }
3923
3924##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003925# @QuorumReadPattern:
Liu Yuan62c60312014-08-18 17:41:04 +08003926#
3927# An enumeration of quorum read patterns.
3928#
3929# @quorum: read all the children and do a quorum vote on reads
3930#
3931# @fifo: read only from the first child that has not failed
3932#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003933# Since: 2.9
Liu Yuan62c60312014-08-18 17:41:04 +08003934##
3935{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] }
3936
3937##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003938# @BlockdevOptionsQuorum:
Benoît Canet1ad166b2014-06-05 13:45:31 +02003939#
3940# Driver specific block device options for Quorum
3941#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003942# @blkverify: true if the driver must print content mismatch set to
3943# false by default
Benoît Canet1ad166b2014-06-05 13:45:31 +02003944#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003945# @children: the children block devices to use
Benoît Canet1ad166b2014-06-05 13:45:31 +02003946#
3947# @vote-threshold: the vote limit under which a read will fail
3948#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01003949# @rewrite-corrupted: rewrite corrupted data when quorum is reached
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003950# (Since 2.1)
Benoît Canetcf29a572014-06-11 15:24:10 +02003951#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01003952# @read-pattern: choose read pattern and set to quorum by default
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003953# (Since 2.2)
Liu Yuan62c60312014-08-18 17:41:04 +08003954#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003955# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02003956##
Eric Blake895a2a82015-05-04 09:05:27 -06003957{ 'struct': 'BlockdevOptionsQuorum',
Benoît Canet1ad166b2014-06-05 13:45:31 +02003958 'data': { '*blkverify': 'bool',
3959 'children': [ 'BlockdevRef' ],
Liu Yuan62c60312014-08-18 17:41:04 +08003960 'vote-threshold': 'int',
3961 '*rewrite-corrupted': 'bool',
3962 '*read-pattern': 'QuorumReadPattern' } }
Benoît Canet1ad166b2014-06-05 13:45:31 +02003963
3964##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04003965# @BlockdevOptionsGluster:
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303966#
3967# Driver specific block device options for Gluster
3968#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003969# @volume: name of gluster volume where VM image resides
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303970#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003971# @path: absolute path to image file in gluster volume
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303972#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003973# @server: gluster servers description
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303974#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02003975# @debug: libgfapi log level (default '4' which is Error) (Since 2.8)
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303976#
Peter Maydell26ec4e52020-02-13 17:56:26 +00003977# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8)
Prasanna Kumar Kalevere9db8ff2016-07-22 20:26:48 +05303978#
Markus Armbruster79b7a772017-03-21 17:53:28 +01003979# Since: 2.9
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303980##
3981{ 'struct': 'BlockdevOptionsGluster',
3982 'data': { 'volume': 'str',
3983 'path': 'str',
Markus Armbruster62cf3962017-04-26 09:36:40 +02003984 'server': ['SocketAddress'],
Prasanna Kumar Kalever1a417e42016-11-02 22:20:36 +05303985 '*debug': 'int',
Prasanna Kumar Kalevere9db8ff2016-07-22 20:26:48 +05303986 '*logfile': 'str' } }
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05303987
3988##
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04003989# @BlockdevOptionsIoUring:
3990#
3991# Driver specific block device options for the io_uring backend.
3992#
3993# @filename: path to the image file
3994#
3995# Since: 7.2
3996##
3997{ 'struct': 'BlockdevOptionsIoUring',
3998 'data': { 'filename': 'str' },
3999 'if': 'CONFIG_BLKIO' }
4000
4001##
4002# @BlockdevOptionsNvmeIoUring:
4003#
4004# Driver specific block device options for the nvme-io_uring backend.
4005#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004006# @path: path to the NVMe namespace's character device (e.g.
4007# /dev/ng0n1).
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004008#
4009# Since: 7.2
4010##
4011{ 'struct': 'BlockdevOptionsNvmeIoUring',
Alberto Faria6c32fc02022-10-29 00:38:54 +01004012 'data': { 'path': 'str' },
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004013 'if': 'CONFIG_BLKIO' }
4014
4015##
Alberto Faria03d9e4c2022-10-28 14:16:35 +01004016# @BlockdevOptionsVirtioBlkVfioPci:
4017#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004018# Driver specific block device options for the virtio-blk-vfio-pci
4019# backend.
Alberto Faria03d9e4c2022-10-28 14:16:35 +01004020#
4021# @path: path to the PCI device's sysfs directory (e.g.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004022# /sys/bus/pci/devices/0000:00:01.0).
Alberto Faria03d9e4c2022-10-28 14:16:35 +01004023#
4024# Since: 7.2
4025##
4026{ 'struct': 'BlockdevOptionsVirtioBlkVfioPci',
4027 'data': { 'path': 'str' },
4028 'if': 'CONFIG_BLKIO' }
4029
4030##
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004031# @BlockdevOptionsVirtioBlkVhostUser:
4032#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004033# Driver specific block device options for the virtio-blk-vhost-user
4034# backend.
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004035#
4036# @path: path to the vhost-user UNIX domain socket.
4037#
4038# Since: 7.2
4039##
4040{ 'struct': 'BlockdevOptionsVirtioBlkVhostUser',
4041 'data': { 'path': 'str' },
4042 'if': 'CONFIG_BLKIO' }
4043
4044##
4045# @BlockdevOptionsVirtioBlkVhostVdpa:
4046#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004047# Driver specific block device options for the virtio-blk-vhost-vdpa
4048# backend.
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004049#
4050# @path: path to the vhost-vdpa character device.
4051#
Stefano Garzarella98b126f2023-05-30 09:19:41 +02004052# Features:
Markus Armbruster01bed0f2024-07-29 08:52:20 +02004053#
Stefano Garzarella98b126f2023-05-30 09:19:41 +02004054# @fdset: Member @path supports the special "/dev/fdset/N" path
4055# (since 8.1)
4056#
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004057# Since: 7.2
4058##
4059{ 'struct': 'BlockdevOptionsVirtioBlkVhostVdpa',
4060 'data': { 'path': 'str' },
Stefano Garzarella98b126f2023-05-30 09:19:41 +02004061 'features': [ { 'name' :'fdset',
4062 'if': 'CONFIG_BLKIO_VHOST_VDPA_FD' } ],
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004063 'if': 'CONFIG_BLKIO' }
4064
4065##
Kevin Wolf31eb1202016-12-08 14:23:11 +01004066# @IscsiTransport:
4067#
4068# An enumeration of libiscsi transport types
4069#
4070# Since: 2.9
4071##
4072{ 'enum': 'IscsiTransport',
4073 'data': [ 'tcp', 'iser' ] }
4074
4075##
4076# @IscsiHeaderDigest:
4077#
4078# An enumeration of header digests supported by libiscsi
4079#
4080# Since: 2.9
4081##
4082{ 'enum': 'IscsiHeaderDigest',
4083 'prefix': 'QAPI_ISCSI_HEADER_DIGEST',
4084 'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] }
4085
4086##
4087# @BlockdevOptionsIscsi:
4088#
Markus Armbrusterd6a5ca32024-01-29 12:50:07 +01004089# Driver specific block device options for iscsi
4090#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004091# @transport: The iscsi transport type
Kevin Wolf31eb1202016-12-08 14:23:11 +01004092#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004093# @portal: The address of the iscsi portal
Kevin Wolf31eb1202016-12-08 14:23:11 +01004094#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004095# @target: The target iqn name
Kevin Wolf31eb1202016-12-08 14:23:11 +01004096#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004097# @lun: LUN to connect to. Defaults to 0.
Kevin Wolf31eb1202016-12-08 14:23:11 +01004098#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004099# @user: User name to log in with. If omitted, no CHAP authentication
4100# is performed.
Kevin Wolf31eb1202016-12-08 14:23:11 +01004101#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004102# @password-secret: The ID of a QCryptoSecret object providing the
4103# password for the login. This option is required if @user is
4104# specified.
Kevin Wolf31eb1202016-12-08 14:23:11 +01004105#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004106# @initiator-name: The iqn name we want to identify to the target as.
4107# If this option is not specified, an initiator name is generated
4108# automatically.
Kevin Wolf31eb1202016-12-08 14:23:11 +01004109#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004110# @header-digest: The desired header digest. Defaults to none-crc32c.
Kevin Wolf31eb1202016-12-08 14:23:11 +01004111#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004112# @timeout: Timeout in seconds after which a request will timeout. 0
4113# means no timeout and is the default.
Kevin Wolf31eb1202016-12-08 14:23:11 +01004114#
Kevin Wolf31eb1202016-12-08 14:23:11 +01004115# Since: 2.9
4116##
4117{ 'struct': 'BlockdevOptionsIscsi',
4118 'data': { 'transport': 'IscsiTransport',
4119 'portal': 'str',
4120 'target': 'str',
4121 '*lun': 'int',
4122 '*user': 'str',
4123 '*password-secret': 'str',
4124 '*initiator-name': 'str',
4125 '*header-digest': 'IscsiHeaderDigest',
4126 '*timeout': 'int' } }
4127
Jeff Cody0a556792017-02-27 12:36:46 -05004128##
Markus Armbrustera3699de2018-06-14 21:14:42 +02004129# @RbdAuthMode:
4130#
4131# Since: 3.0
4132##
4133{ 'enum': 'RbdAuthMode',
4134 'data': [ 'cephx', 'none' ] }
4135
4136##
Or Ozeri42e4ac92021-06-27 14:46:35 +03004137# @RbdImageEncryptionFormat:
4138#
Or Ozerib8f218e2023-01-29 05:31:19 -06004139# @luks-any: Used for opening either luks or luks2 (Since 8.0)
4140#
Or Ozeri42e4ac92021-06-27 14:46:35 +03004141# Since: 6.1
4142##
4143{ 'enum': 'RbdImageEncryptionFormat',
Or Ozerib8f218e2023-01-29 05:31:19 -06004144 'data': [ 'luks', 'luks2', 'luks-any' ] }
Or Ozeri42e4ac92021-06-27 14:46:35 +03004145
4146##
4147# @RbdEncryptionOptionsLUKSBase:
4148#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004149# @key-secret: ID of a QCryptoSecret object providing a passphrase for
4150# unlocking the encryption
Or Ozeri42e4ac92021-06-27 14:46:35 +03004151#
4152# Since: 6.1
4153##
4154{ 'struct': 'RbdEncryptionOptionsLUKSBase',
4155 'data': { 'key-secret': 'str' } }
4156
4157##
4158# @RbdEncryptionCreateOptionsLUKSBase:
4159#
4160# @cipher-alg: The encryption algorithm
4161#
4162# Since: 6.1
4163##
4164{ 'struct': 'RbdEncryptionCreateOptionsLUKSBase',
4165 'base': 'RbdEncryptionOptionsLUKSBase',
4166 'data': { '*cipher-alg': 'QCryptoCipherAlgorithm' } }
4167
4168##
4169# @RbdEncryptionOptionsLUKS:
4170#
4171# Since: 6.1
4172##
4173{ 'struct': 'RbdEncryptionOptionsLUKS',
4174 'base': 'RbdEncryptionOptionsLUKSBase',
4175 'data': { } }
4176
4177##
4178# @RbdEncryptionOptionsLUKS2:
4179#
4180# Since: 6.1
4181##
4182{ 'struct': 'RbdEncryptionOptionsLUKS2',
4183 'base': 'RbdEncryptionOptionsLUKSBase',
4184 'data': { } }
4185
4186##
Or Ozerib8f218e2023-01-29 05:31:19 -06004187# @RbdEncryptionOptionsLUKSAny:
4188#
4189# Since: 8.0
4190##
4191{ 'struct': 'RbdEncryptionOptionsLUKSAny',
4192 'base': 'RbdEncryptionOptionsLUKSBase',
4193 'data': { } }
4194
4195##
Or Ozeri42e4ac92021-06-27 14:46:35 +03004196# @RbdEncryptionCreateOptionsLUKS:
4197#
4198# Since: 6.1
4199##
4200{ 'struct': 'RbdEncryptionCreateOptionsLUKS',
4201 'base': 'RbdEncryptionCreateOptionsLUKSBase',
4202 'data': { } }
4203
4204##
4205# @RbdEncryptionCreateOptionsLUKS2:
4206#
4207# Since: 6.1
4208##
4209{ 'struct': 'RbdEncryptionCreateOptionsLUKS2',
4210 'base': 'RbdEncryptionCreateOptionsLUKSBase',
4211 'data': { } }
4212
4213##
4214# @RbdEncryptionOptions:
4215#
Or Ozeri0f385a22023-01-29 05:31:20 -06004216# @format: Encryption format.
4217#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004218# @parent: Parent image encryption options (for cloned images). Can
4219# be left unspecified if this cloned image is encrypted using the
4220# same format and secret as its parent image (i.e. not explicitly
4221# formatted) or if its parent image is not encrypted. (Since 8.0)
Or Ozeri0f385a22023-01-29 05:31:20 -06004222#
Or Ozeri42e4ac92021-06-27 14:46:35 +03004223# Since: 6.1
4224##
4225{ 'union': 'RbdEncryptionOptions',
Or Ozeri0f385a22023-01-29 05:31:20 -06004226 'base': { 'format': 'RbdImageEncryptionFormat',
4227 '*parent': 'RbdEncryptionOptions' },
Or Ozeri42e4ac92021-06-27 14:46:35 +03004228 'discriminator': 'format',
4229 'data': { 'luks': 'RbdEncryptionOptionsLUKS',
Or Ozerib8f218e2023-01-29 05:31:19 -06004230 'luks2': 'RbdEncryptionOptionsLUKS2',
4231 'luks-any': 'RbdEncryptionOptionsLUKSAny'} }
Or Ozeri42e4ac92021-06-27 14:46:35 +03004232
4233##
4234# @RbdEncryptionCreateOptions:
4235#
Markus Armbruster89a22732024-02-05 08:47:09 +01004236# @format: Encryption format.
4237#
Or Ozeri42e4ac92021-06-27 14:46:35 +03004238# Since: 6.1
4239##
4240{ 'union': 'RbdEncryptionCreateOptions',
4241 'base': { 'format': 'RbdImageEncryptionFormat' },
4242 'discriminator': 'format',
4243 'data': { 'luks': 'RbdEncryptionCreateOptionsLUKS',
4244 'luks2': 'RbdEncryptionCreateOptionsLUKS2' } }
4245
4246##
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004247# @BlockdevOptionsRbd:
4248#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004249# @pool: Ceph pool name.
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004250#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004251# @namespace: Rados namespace name in the Ceph pool. (Since 5.0)
Florian Florensa19ae9ae2020-01-10 12:15:13 +01004252#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004253# @image: Image name in the Ceph pool.
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004254#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004255# @conf: path to Ceph configuration file. Values in the configuration
4256# file will be overridden by options specified via QAPI.
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004257#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004258# @snapshot: Ceph snapshot name.
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004259#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004260# @encrypt: Image encryption options. (Since 6.1)
Or Ozeri42e4ac92021-06-27 14:46:35 +03004261#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004262# @user: Ceph id name.
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004263#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004264# @auth-client-required: Acceptable authentication modes. This maps
4265# to Ceph configuration option "auth_client_required". (Since
4266# 3.0)
Markus Armbrustera3699de2018-06-14 21:14:42 +02004267#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004268# @key-secret: ID of a QCryptoSecret object providing a key for cephx
4269# authentication. This maps to Ceph configuration option "key".
4270# (Since 3.0)
Markus Armbrusterd083f952018-06-14 21:14:43 +02004271#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004272# @server: Monitor host address and port. This maps to the "mon_host"
4273# Ceph option.
Jeff Cody0a556792017-02-27 12:36:46 -05004274#
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004275# Since: 2.9
4276##
4277{ 'struct': 'BlockdevOptionsRbd',
4278 'data': { 'pool': 'str',
Florian Florensa19ae9ae2020-01-10 12:15:13 +01004279 '*namespace': 'str',
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004280 'image': 'str',
4281 '*conf': 'str',
4282 '*snapshot': 'str',
Or Ozeri42e4ac92021-06-27 14:46:35 +03004283 '*encrypt': 'RbdEncryptionOptions',
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004284 '*user': 'str',
Markus Armbrustera3699de2018-06-14 21:14:42 +02004285 '*auth-client-required': ['RbdAuthMode'],
Markus Armbrusterd083f952018-06-14 21:14:43 +02004286 '*key-secret': 'str',
Markus Armbruster577d8c92017-03-28 10:56:07 +02004287 '*server': ['InetSocketAddressBase'] } }
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004288
Kevin Wolf31eb1202016-12-08 14:23:11 +01004289##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004290# @ReplicationMode:
Changlong Xie190b9a82016-07-27 15:01:49 +08004291#
4292# An enumeration of replication modes.
4293#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004294# @primary: Primary mode, the vm's state will be sent to secondary
4295# QEMU.
Changlong Xie190b9a82016-07-27 15:01:49 +08004296#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004297# @secondary: Secondary mode, receive the vm's state from primary
4298# QEMU.
Changlong Xie190b9a82016-07-27 15:01:49 +08004299#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004300# Since: 2.9
Changlong Xie190b9a82016-07-27 15:01:49 +08004301##
Marc-André Lureau335d10c2018-12-13 16:37:24 +04004302{ 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ],
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04004303 'if': 'CONFIG_REPLICATION' }
Changlong Xie190b9a82016-07-27 15:01:49 +08004304
4305##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004306# @BlockdevOptionsReplication:
Wen Congyang82ac5542016-07-27 15:01:52 +08004307#
4308# Driver specific block device options for replication
4309#
4310# @mode: the replication mode
4311#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004312# @top-id: In secondary mode, node name or device ID of the root node
4313# who owns the replication node chain. Must not be given in
4314# primary mode.
Wen Congyang82ac5542016-07-27 15:01:52 +08004315#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004316# Since: 2.9
Wen Congyang82ac5542016-07-27 15:01:52 +08004317##
4318{ 'struct': 'BlockdevOptionsReplication',
4319 'base': 'BlockdevOptionsGenericFormat',
4320 'data': { 'mode': 'ReplicationMode',
Marc-André Lureau335d10c2018-12-13 16:37:24 +04004321 '*top-id': 'str' },
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04004322 'if': 'CONFIG_REPLICATION' }
Wen Congyang82ac5542016-07-27 15:01:52 +08004323
4324##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004325# @NFSTransport:
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304326#
4327# An enumeration of NFS transport types
4328#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004329# @inet: TCP transport
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304330#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004331# Since: 2.9
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304332##
4333{ 'enum': 'NFSTransport',
4334 'data': [ 'inet' ] }
4335
4336##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004337# @NFSServer:
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304338#
4339# Captures the address of the socket
4340#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004341# @type: transport type used for NFS (only TCP supported)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304342#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004343# @host: host address for NFS server
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304344#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004345# Since: 2.9
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304346##
4347{ 'struct': 'NFSServer',
4348 'data': { 'type': 'NFSTransport',
4349 'host': 'str' } }
4350
4351##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004352# @BlockdevOptionsNfs:
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304353#
4354# Driver specific block device option for NFS
4355#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004356# @server: host address
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304357#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004358# @path: path of the image on the host
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304359#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004360# @user: UID value to use when talking to the server (defaults to
4361# 65534 on Windows and getuid() on unix)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304362#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004363# @group: GID value to use when talking to the server (defaults to
4364# 65534 on Windows and getgid() in unix)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304365#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004366# @tcp-syn-count: number of SYNs during the session establishment
4367# (defaults to libnfs default)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304368#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004369# @readahead-size: set the readahead size in bytes (defaults to libnfs
4370# default)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304371#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004372# @page-cache-size: set the pagecache size in bytes (defaults to
4373# libnfs default)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304374#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004375# @debug: set the NFS debug level (max 2) (defaults to libnfs default)
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304376#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004377# Since: 2.9
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304378##
4379{ 'struct': 'BlockdevOptionsNfs',
4380 'data': { 'server': 'NFSServer',
4381 'path': 'str',
4382 '*user': 'int',
4383 '*group': 'int',
4384 '*tcp-syn-count': 'int',
4385 '*readahead-size': 'int',
4386 '*page-cache-size': 'int',
Prasanna Kumar Kalever7103d912016-11-02 22:20:37 +05304387 '*debug': 'int' } }
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304388
4389##
Max Reitz6b9d62d2017-03-31 14:04:30 +02004390# @BlockdevOptionsCurlBase:
Kevin Wolf68555282016-09-08 13:08:20 +02004391#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004392# Driver specific block device options shared by all protocols
4393# supported by the curl backend.
Kevin Wolf68555282016-09-08 13:08:20 +02004394#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004395# @url: URL of the image file
Max Reitz6b9d62d2017-03-31 14:04:30 +02004396#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004397# @readahead: Size of the read-ahead cache; must be a multiple of 512
4398# (defaults to 256 kB)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004399#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004400# @timeout: Timeout for connections, in seconds (defaults to 5)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004401#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004402# @username: Username for authentication (defaults to none)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004403#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004404# @password-secret: ID of a QCryptoSecret object providing a password
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004405# for authentication (defaults to no password)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004406#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004407# @proxy-username: Username for proxy authentication (defaults to
4408# none)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004409#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004410# @proxy-password-secret: ID of a QCryptoSecret object providing a
4411# password for proxy authentication (defaults to no password)
Kevin Wolf68555282016-09-08 13:08:20 +02004412#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004413# Since: 2.9
Kevin Wolf68555282016-09-08 13:08:20 +02004414##
Max Reitz6b9d62d2017-03-31 14:04:30 +02004415{ 'struct': 'BlockdevOptionsCurlBase',
4416 'data': { 'url': 'str',
4417 '*readahead': 'int',
4418 '*timeout': 'int',
4419 '*username': 'str',
4420 '*password-secret': 'str',
4421 '*proxy-username': 'str',
4422 '*proxy-password-secret': 'str' } }
4423
4424##
4425# @BlockdevOptionsCurlHttp:
4426#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004427# Driver specific block device options for HTTP connections over the
4428# curl backend. URLs must start with "http://".
Max Reitz6b9d62d2017-03-31 14:04:30 +02004429#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004430# @cookie: List of cookies to set; format is "name1=content1;
Markus Armbruster01bed0f2024-07-29 08:52:20 +02004431# name2=content2;" as explained by CURLOPT_COOKIE(3). Defaults to
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004432# no cookies.
Max Reitz6b9d62d2017-03-31 14:04:30 +02004433#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004434# @cookie-secret: ID of a QCryptoSecret object providing the cookie
4435# data in a secure way. See @cookie for the format. (since 2.10)
Peter Krempa327c8eb2017-05-04 16:00:06 +02004436#
Max Reitz6b9d62d2017-03-31 14:04:30 +02004437# Since: 2.9
4438##
4439{ 'struct': 'BlockdevOptionsCurlHttp',
4440 'base': 'BlockdevOptionsCurlBase',
Peter Krempa327c8eb2017-05-04 16:00:06 +02004441 'data': { '*cookie': 'str',
4442 '*cookie-secret': 'str'} }
Max Reitz6b9d62d2017-03-31 14:04:30 +02004443
4444##
4445# @BlockdevOptionsCurlHttps:
4446#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004447# Driver specific block device options for HTTPS connections over the
4448# curl backend. URLs must start with "https://".
Max Reitz6b9d62d2017-03-31 14:04:30 +02004449#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004450# @cookie: List of cookies to set; format is "name1=content1;
Markus Armbruster01bed0f2024-07-29 08:52:20 +02004451# name2=content2;" as explained by CURLOPT_COOKIE(3). Defaults to
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004452# no cookies.
Max Reitz6b9d62d2017-03-31 14:04:30 +02004453#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004454# @sslverify: Whether to verify the SSL certificate's validity
4455# (defaults to true)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004456#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004457# @cookie-secret: ID of a QCryptoSecret object providing the cookie
4458# data in a secure way. See @cookie for the format. (since 2.10)
Peter Krempa327c8eb2017-05-04 16:00:06 +02004459#
Max Reitz6b9d62d2017-03-31 14:04:30 +02004460# Since: 2.9
4461##
4462{ 'struct': 'BlockdevOptionsCurlHttps',
4463 'base': 'BlockdevOptionsCurlBase',
4464 'data': { '*cookie': 'str',
Peter Krempa327c8eb2017-05-04 16:00:06 +02004465 '*sslverify': 'bool',
4466 '*cookie-secret': 'str'} }
Max Reitz6b9d62d2017-03-31 14:04:30 +02004467
4468##
4469# @BlockdevOptionsCurlFtp:
4470#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004471# Driver specific block device options for FTP connections over the
4472# curl backend. URLs must start with "ftp://".
Max Reitz6b9d62d2017-03-31 14:04:30 +02004473#
4474# Since: 2.9
4475##
4476{ 'struct': 'BlockdevOptionsCurlFtp',
4477 'base': 'BlockdevOptionsCurlBase',
4478 'data': { } }
4479
4480##
4481# @BlockdevOptionsCurlFtps:
4482#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004483# Driver specific block device options for FTPS connections over the
4484# curl backend. URLs must start with "ftps://".
Max Reitz6b9d62d2017-03-31 14:04:30 +02004485#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004486# @sslverify: Whether to verify the SSL certificate's validity
4487# (defaults to true)
Max Reitz6b9d62d2017-03-31 14:04:30 +02004488#
4489# Since: 2.9
4490##
4491{ 'struct': 'BlockdevOptionsCurlFtps',
4492 'base': 'BlockdevOptionsCurlBase',
4493 'data': { '*sslverify': 'bool' } }
Kevin Wolf68555282016-09-08 13:08:20 +02004494
4495##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004496# @BlockdevOptionsNbd:
Max Reitz6b02b1f2016-10-25 15:11:36 +02004497#
4498# Driver specific block device options for NBD.
4499#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004500# @server: NBD server address
Max Reitz6b02b1f2016-10-25 15:11:36 +02004501#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004502# @export: export name
Max Reitz6b02b1f2016-10-25 15:11:36 +02004503#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004504# @tls-creds: TLS credentials ID
Max Reitz6b02b1f2016-10-25 15:11:36 +02004505#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004506# @tls-hostname: TLS hostname override for certificate validation
4507# (Since 7.0)
Daniel P. Berrangéa0cd6d22022-03-04 19:36:01 +00004508#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004509# @x-dirty-bitmap: A metadata context name such as
4510# "qemu:dirty-bitmap:NAME" or "qemu:allocation-depth" to query in
4511# place of the traditional "base:allocation" block status (see
4512# NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and yes, naming
4513# this option x-context would have made more sense) (since 3.0)
Eric Blake216ee362018-07-02 14:14:57 -05004514#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004515# @reconnect-delay: On an unexpected disconnect, the nbd client tries
4516# to connect again until succeeding or encountering a serious
4517# error. During the first @reconnect-delay seconds, all requests
4518# are paused and will be rerun on a successful reconnect. After
4519# that time, any delayed requests and all future requests before a
4520# successful reconnect will immediately fail. Default 0 (Since
4521# 4.2)
Vladimir Sementsov-Ogievskiyb172ae22019-06-18 14:43:23 +03004522#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004523# @open-timeout: In seconds. If zero, the nbd driver tries the
4524# connection only once, and fails to open if the connection fails.
4525# If non-zero, the nbd driver will repeat connection attempts
4526# until successful or until @open-timeout seconds have elapsed.
4527# Default 0 (Since 7.0)
Vladimir Sementsov-Ogievskiybe16b8b2021-09-06 22:06:48 +03004528#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02004529# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004530#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02004531# @unstable: Member @x-dirty-bitmap is experimental.
4532#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004533# Since: 2.9
Max Reitz6b02b1f2016-10-25 15:11:36 +02004534##
4535{ 'struct': 'BlockdevOptionsNbd',
Markus Armbruster62cf3962017-04-26 09:36:40 +02004536 'data': { 'server': 'SocketAddress',
Max Reitz6b02b1f2016-10-25 15:11:36 +02004537 '*export': 'str',
Eric Blake216ee362018-07-02 14:14:57 -05004538 '*tls-creds': 'str',
Daniel P. Berrangéa0cd6d22022-03-04 19:36:01 +00004539 '*tls-hostname': 'str',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02004540 '*x-dirty-bitmap': { 'type': 'str', 'features': [ 'unstable' ] },
Vladimir Sementsov-Ogievskiybe16b8b2021-09-06 22:06:48 +03004541 '*reconnect-delay': 'uint32',
4542 '*open-timeout': 'uint32' } }
Max Reitz6b02b1f2016-10-25 15:11:36 +02004543
4544##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004545# @BlockdevOptionsRaw:
Tomáš Golembiovský2fdc7042016-10-31 11:27:40 +01004546#
4547# Driver specific block device options for the raw driver.
4548#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004549# @offset: position where the block device starts
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004550#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004551# @size: the assumed size of the device
Tomáš Golembiovský2fdc7042016-10-31 11:27:40 +01004552#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004553# Since: 2.9
Tomáš Golembiovský2fdc7042016-10-31 11:27:40 +01004554##
4555{ 'struct': 'BlockdevOptionsRaw',
4556 'base': 'BlockdevOptionsGenericFormat',
4557 'data': { '*offset': 'int', '*size': 'int' } }
4558
4559##
Manos Pitsidianakisd8e7d872017-08-25 16:20:27 +03004560# @BlockdevOptionsThrottle:
4561#
4562# Driver specific block device options for the throttle driver
4563#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004564# @throttle-group: the name of the throttle-group object to use. It
4565# must already exist.
4566#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004567# @file: reference to or definition of the data source block device
Andrea Bolognani4ae65a52022-05-03 09:37:32 +02004568#
Manos Pitsidianakisd8e7d872017-08-25 16:20:27 +03004569# Since: 2.11
4570##
4571{ 'struct': 'BlockdevOptionsThrottle',
4572 'data': { 'throttle-group': 'str',
4573 'file' : 'BlockdevRef'
4574 } }
Andrey Shinkeviche4c8fdd2020-12-16 09:16:55 +03004575
4576##
4577# @BlockdevOptionsCor:
4578#
4579# Driver specific block device options for the copy-on-read driver.
4580#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004581# @bottom: The name of a non-filter node (allocation-bearing layer)
4582# that limits the COR operations in the backing chain (inclusive),
4583# so that no data below this node will be copied by this filter.
4584# If option is absent, the limit is not applied, so that data from
4585# all backing layers may be copied.
Andrey Shinkeviche4c8fdd2020-12-16 09:16:55 +03004586#
4587# Since: 6.0
4588##
4589{ 'struct': 'BlockdevOptionsCor',
4590 'base': 'BlockdevOptionsGenericFormat',
4591 'data': { '*bottom': 'str' } }
4592
Manos Pitsidianakisd8e7d872017-08-25 16:20:27 +03004593##
Vladimir Sementsov-Ogievskiyf1bb39a2022-04-07 16:27:21 +03004594# @OnCbwError:
4595#
4596# An enumeration of possible behaviors for copy-before-write operation
4597# failures.
4598#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004599# @break-guest-write: report the error to the guest. This way, the
4600# guest will not be able to overwrite areas that cannot be backed
4601# up, so the backup process remains valid.
Vladimir Sementsov-Ogievskiyf1bb39a2022-04-07 16:27:21 +03004602#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004603# @break-snapshot: continue guest write. Doing so will make the
4604# provided snapshot state invalid and any backup or export process
4605# based on it will finally fail.
Vladimir Sementsov-Ogievskiyf1bb39a2022-04-07 16:27:21 +03004606#
4607# Since: 7.1
4608##
4609{ 'enum': 'OnCbwError',
4610 'data': [ 'break-guest-write', 'break-snapshot' ] }
4611
4612##
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03004613# @BlockdevOptionsCbw:
4614#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004615# Driver specific block device options for the copy-before-write
4616# driver, which does so called copy-before-write operations: when data
4617# is written to the filter, the filter first reads corresponding
4618# blocks from its file child and copies them to @target child. After
4619# successfully copying, the write request is propagated to file child.
4620# If copying fails, the original write request is failed too and no
4621# data is written to file child.
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03004622#
4623# @target: The target for copy-before-write operations.
4624#
Vladimir Sementsov-Ogievskiy5f3a3cd2022-03-03 20:43:37 +01004625# @bitmap: If specified, copy-before-write filter will do
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004626# copy-before-write operations only for dirty regions of the
4627# bitmap. Bitmap size must be equal to length of file and target
4628# child of the filter. Note also, that bitmap is used only to
4629# initialize internal bitmap of the process, so further
4630# modifications (or removing) of specified bitmap doesn't
4631# influence the filter. (Since 7.0)
Vladimir Sementsov-Ogievskiy5f3a3cd2022-03-03 20:43:37 +01004632#
Vladimir Sementsov-Ogievskiyf1bb39a2022-04-07 16:27:21 +03004633# @on-cbw-error: Behavior on failure of copy-before-write operation.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004634# Default is @break-guest-write. (Since 7.1)
Vladimir Sementsov-Ogievskiyf1bb39a2022-04-07 16:27:21 +03004635#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004636# @cbw-timeout: Zero means no limit. Non-zero sets the timeout in
4637# seconds for copy-before-write operation. When a timeout occurs,
4638# the respective copy-before-write operation will fail, and the
4639# @on-cbw-error parameter will decide how this failure is handled.
Markus Armbruster5305a4e2024-03-22 15:09:09 +01004640# Default 0. (Since 7.1)
Vladimir Sementsov-Ogievskiy6db7fd12022-04-07 16:27:25 +03004641#
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03004642# Since: 6.2
4643##
4644{ 'struct': 'BlockdevOptionsCbw',
4645 'base': 'BlockdevOptionsGenericFormat',
Vladimir Sementsov-Ogievskiyf1bb39a2022-04-07 16:27:21 +03004646 'data': { 'target': 'BlockdevRef', '*bitmap': 'BlockDirtyBitmap',
Vladimir Sementsov-Ogievskiy6db7fd12022-04-07 16:27:25 +03004647 '*on-cbw-error': 'OnCbwError', '*cbw-timeout': 'uint32' } }
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03004648
4649##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004650# @BlockdevOptions:
Benoît Canet1ad166b2014-06-05 13:45:31 +02004651#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004652# Options for creating a block device. Many options are available for
4653# all block devices, independent of the block driver:
Eric Blake3666a972016-03-17 16:48:40 -06004654#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004655# @driver: block driver name
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004656#
Markus Armbruster01bed0f2024-07-29 08:52:20 +02004657# @node-name: the node name of the new node (Since 2.0). This option
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004658# is required on the top level of blockdev-add. Valid node names
4659# start with an alphabetic character and may contain only
Markus Armbruster01bed0f2024-07-29 08:52:20 +02004660# alphanumeric characters, '-', '.' and '_'. Their maximum length
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004661# is 31 characters.
4662#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004663# @discard: discard-related options (default: ignore)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004664#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004665# @cache: cache-related options
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004666#
4667# @read-only: whether the block device should be read-only (default:
Markus Armbruster01bed0f2024-07-29 08:52:20 +02004668# false). Note that some block drivers support only read-only
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004669# access, either generally or in certain configurations. In this
4670# case, the default value does not work and the option must be
4671# specified explicitly.
4672#
4673# @auto-read-only: if true and @read-only is false, QEMU may
4674# automatically decide not to open the image read-write as
4675# requested, but fall back to read-only instead (and switch
4676# between the modes later), e.g. depending on whether the image
4677# file is writable or whether a writing user is attached to the
4678# node (default: false, since 3.1)
4679#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01004680# @detect-zeroes: detect and optimize zero writes (Since 2.1)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004681# (default: off)
4682#
4683# @force-share: force share all permission on added nodes. Requires
4684# read-only=true. (Since 2.10)
Eric Blake3666a972016-03-17 16:48:40 -06004685#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004686# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02004687##
4688{ 'union': 'BlockdevOptions',
Eric Blake3666a972016-03-17 16:48:40 -06004689 'base': { 'driver': 'BlockdevDriver',
Eric Blake3666a972016-03-17 16:48:40 -06004690 '*node-name': 'str',
4691 '*discard': 'BlockdevDiscardOptions',
4692 '*cache': 'BlockdevCacheOptions',
Eric Blake3666a972016-03-17 16:48:40 -06004693 '*read-only': 'bool',
Kevin Wolfe35bdc12018-10-05 18:57:40 +02004694 '*auto-read-only': 'bool',
Fam Zheng5a9347c2017-05-03 00:35:37 +08004695 '*force-share': 'bool',
Eric Blake3666a972016-03-17 16:48:40 -06004696 '*detect-zeroes': 'BlockdevDetectZeroesOptions' },
Benoît Canet1ad166b2014-06-05 13:45:31 +02004697 'discriminator': 'driver',
4698 'data': {
Benoît Canet1ad166b2014-06-05 13:45:31 +02004699 'blkdebug': 'BlockdevOptionsBlkdebug',
Aapo Vienamobfcc2242018-07-03 17:48:48 +03004700 'blklogwrites':'BlockdevOptionsBlklogwrites',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004701 'blkverify': 'BlockdevOptionsBlkverify',
Pavel Dovgalyuk35e32d92019-10-16 11:40:39 +03004702 'blkreplay': 'BlockdevOptionsBlkreplay',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004703 'bochs': 'BlockdevOptionsGenericFormat',
4704 'cloop': 'BlockdevOptionsGenericFormat',
Andrey Shinkevichf41388e2019-12-02 15:15:04 +03004705 'compress': 'BlockdevOptionsGenericFormat',
Vladimir Sementsov-Ogievskiy783b2822021-08-24 11:38:44 +03004706 'copy-before-write':'BlockdevOptionsCbw',
Andrey Shinkeviche4c8fdd2020-12-16 09:16:55 +03004707 'copy-on-read':'BlockdevOptionsCor',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004708 'dmg': 'BlockdevOptionsGenericFormat',
Fam Zhengdb866be2014-09-11 14:09:58 +08004709 'file': 'BlockdevOptionsFile',
Max Reitz6b9d62d2017-03-31 14:04:30 +02004710 'ftp': 'BlockdevOptionsCurlFtp',
4711 'ftps': 'BlockdevOptionsCurlFtps',
Prasanna Kumar Kalever7edac2d2016-07-19 22:27:32 +05304712 'gluster': 'BlockdevOptionsGluster',
Joelle van Dyne14176c82021-03-15 11:03:38 -07004713 'host_cdrom': { 'type': 'BlockdevOptionsFile',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04004714 'if': 'HAVE_HOST_BLOCK_DEVICE' },
Joelle van Dyne14176c82021-03-15 11:03:38 -07004715 'host_device': { 'type': 'BlockdevOptionsFile',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04004716 'if': 'HAVE_HOST_BLOCK_DEVICE' },
Max Reitz6b9d62d2017-03-31 14:04:30 +02004717 'http': 'BlockdevOptionsCurlHttp',
4718 'https': 'BlockdevOptionsCurlHttps',
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004719 'io_uring': { 'type': 'BlockdevOptionsIoUring',
4720 'if': 'CONFIG_BLKIO' },
Kevin Wolf31eb1202016-12-08 14:23:11 +01004721 'iscsi': 'BlockdevOptionsIscsi',
Daniel P. Berrange78368572016-03-21 14:11:47 +00004722 'luks': 'BlockdevOptionsLUKS',
Max Reitz6b02b1f2016-10-25 15:11:36 +02004723 'nbd': 'BlockdevOptionsNbd',
Ashijeet Acharyaaa2623d2016-10-31 20:35:50 +05304724 'nfs': 'BlockdevOptionsNfs',
Fam Zhengdb866be2014-09-11 14:09:58 +08004725 'null-aio': 'BlockdevOptionsNull',
4726 'null-co': 'BlockdevOptionsNull',
Fam Zhengd87ee3d2018-01-16 14:09:01 +08004727 'nvme': 'BlockdevOptionsNVMe',
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004728 'nvme-io_uring': { 'type': 'BlockdevOptionsNvmeIoUring',
4729 'if': 'CONFIG_BLKIO' },
Benoît Canet1ad166b2014-06-05 13:45:31 +02004730 'parallels': 'BlockdevOptionsGenericFormat',
Vladimir Sementsov-Ogievskiy33fa2222020-10-21 17:58:46 +03004731 'preallocate':'BlockdevOptionsPreallocate',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004732 'qcow2': 'BlockdevOptionsQcow2',
Daniel P. Berranged85f4222017-06-23 17:24:08 +01004733 'qcow': 'BlockdevOptionsQcow',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004734 'qed': 'BlockdevOptionsGenericCOWFormat',
Fam Zhengdb866be2014-09-11 14:09:58 +08004735 'quorum': 'BlockdevOptionsQuorum',
Tomáš Golembiovský2fdc7042016-10-31 11:27:40 +01004736 'raw': 'BlockdevOptionsRaw',
Jeff Cody8a47e8e2017-02-27 01:16:41 -05004737 'rbd': 'BlockdevOptionsRbd',
Marc-André Lureau335d10c2018-12-13 16:37:24 +04004738 'replication': { 'type': 'BlockdevOptionsReplication',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04004739 'if': 'CONFIG_REPLICATION' },
Vladimir Sementsov-Ogievskiy1c14eaa2022-03-03 20:43:44 +01004740 'snapshot-access': 'BlockdevOptionsGenericFormat',
Ashijeet Acharyaad0e90a2016-10-25 18:34:01 +05304741 'ssh': 'BlockdevOptionsSsh',
Manos Pitsidianakisd8e7d872017-08-25 16:20:27 +03004742 'throttle': 'BlockdevOptionsThrottle',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004743 'vdi': 'BlockdevOptionsGenericFormat',
4744 'vhdx': 'BlockdevOptionsGenericFormat',
Alberto Faria03d9e4c2022-10-28 14:16:35 +01004745 'virtio-blk-vfio-pci':
4746 { 'type': 'BlockdevOptionsVirtioBlkVfioPci',
4747 'if': 'CONFIG_BLKIO' },
Stefan Hajnoczifd66dbd2022-10-13 14:58:57 -04004748 'virtio-blk-vhost-user':
4749 { 'type': 'BlockdevOptionsVirtioBlkVhostUser',
4750 'if': 'CONFIG_BLKIO' },
4751 'virtio-blk-vhost-vdpa':
4752 { 'type': 'BlockdevOptionsVirtioBlkVhostVdpa',
4753 'if': 'CONFIG_BLKIO' },
Benoît Canet1ad166b2014-06-05 13:45:31 +02004754 'vmdk': 'BlockdevOptionsGenericCOWFormat',
4755 'vpc': 'BlockdevOptionsGenericFormat',
Marc-André Lureaua0846452020-07-11 10:59:26 +04004756 'vvfat': 'BlockdevOptionsVVFAT'
Benoît Canet1ad166b2014-06-05 13:45:31 +02004757 } }
4758
4759##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04004760# @BlockdevRef:
Benoît Canet1ad166b2014-06-05 13:45:31 +02004761#
4762# Reference to a block device.
4763#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004764# @definition: defines a new block device inline
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004765#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004766# @reference: references the ID of an existing block device
Benoît Canet1ad166b2014-06-05 13:45:31 +02004767#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004768# Since: 2.9
Benoît Canet1ad166b2014-06-05 13:45:31 +02004769##
Eric Blakeab916fa2015-05-04 09:05:13 -06004770{ 'alternate': 'BlockdevRef',
Benoît Canet1ad166b2014-06-05 13:45:31 +02004771 'data': { 'definition': 'BlockdevOptions',
4772 'reference': 'str' } }
4773
4774##
Markus Armbrusterc42e8742017-07-18 08:54:00 +02004775# @BlockdevRefOrNull:
4776#
4777# Reference to a block device.
4778#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004779# @definition: defines a new block device inline
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004780#
4781# @reference: references the ID of an existing block device. An empty
4782# string means that no block device should be referenced.
4783# Deprecated; use null instead.
4784#
Peter Maydell26ec4e52020-02-13 17:56:26 +00004785# @null: No block device should be referenced (since 2.10)
Markus Armbrusterc42e8742017-07-18 08:54:00 +02004786#
4787# Since: 2.9
4788##
4789{ 'alternate': 'BlockdevRefOrNull',
4790 'data': { 'definition': 'BlockdevOptions',
4791 'reference': 'str',
4792 'null': 'null' } }
4793
4794##
Benoît Canet1ad166b2014-06-05 13:45:31 +02004795# @blockdev-add:
4796#
Kashyap Chamarthye947e9c2020-08-05 12:01:58 +02004797# Creates a new block device.
Benoît Canet1ad166b2014-06-05 13:45:31 +02004798#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004799# Since: 2.9
Marc-André Lureaub4749942016-06-23 14:54:05 +02004800#
John Snow14b48aa2024-07-16 22:13:08 -04004801# .. qmp-example::
Marc-André Lureaub4749942016-06-23 14:54:05 +02004802#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004803# -> { "execute": "blockdev-add",
4804# "arguments": {
4805# "driver": "qcow2",
4806# "node-name": "test1",
Jeff Codyb1660992017-01-24 20:14:11 -05004807# "file": {
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004808# "driver": "file",
4809# "filename": "test.qcow2"
4810# }
4811# }
4812# }
4813# <- { "return": {} }
4814#
John Snow14b48aa2024-07-16 22:13:08 -04004815# .. qmp-example::
4816#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004817# -> { "execute": "blockdev-add",
4818# "arguments": {
4819# "driver": "qcow2",
4820# "node-name": "node0",
4821# "discard": "unmap",
4822# "cache": {
4823# "direct": true
4824# },
4825# "file": {
Jeff Codyb1660992017-01-24 20:14:11 -05004826# "driver": "file",
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004827# "filename": "/tmp/test.qcow2"
4828# },
4829# "backing": {
4830# "driver": "raw",
4831# "file": {
4832# "driver": "file",
4833# "filename": "/dev/fdset/4"
4834# }
Marc-André Lureaub4749942016-06-23 14:54:05 +02004835# }
4836# }
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004837# }
Marc-André Lureaub4749942016-06-23 14:54:05 +02004838#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004839# <- { "return": {} }
Benoît Canet1ad166b2014-06-05 13:45:31 +02004840##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05004841{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true,
4842 'allow-preconfig': true }
Benoît Canet1ad166b2014-06-05 13:45:31 +02004843
Max Reitz7d8a9f72015-10-26 21:39:08 +01004844##
Alberto Garciae60edf62021-07-08 13:47:09 +02004845# @blockdev-reopen:
Alberto Garcia1479c732019-03-12 18:48:51 +02004846#
Alberto Garcia3908b7a2021-07-08 13:47:07 +02004847# Reopens one or more block devices using the given set of options.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004848# Any option not specified will be reset to its default value
4849# regardless of its previous status. If an option cannot be changed
4850# or a particular driver does not support reopening then the command
4851# will return an error. All devices in the list are reopened in one
4852# transaction, so if one of them fails then the whole transaction is
4853# cancelled.
Alberto Garcia1479c732019-03-12 18:48:51 +02004854#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004855# The command receives a list of block devices to reopen. For each
4856# one of them, the top-level @node-name option (from BlockdevOptions)
4857# must be specified and is used to select the block device to be
4858# reopened. Other @node-name options must be either omitted or set to
4859# the current name of the appropriate node. This command won't change
4860# any node name and any attempt to do it will result in an error.
Alberto Garcia1479c732019-03-12 18:48:51 +02004861#
4862# In the case of options that refer to child nodes, the behavior of
4863# this command depends on the value:
4864#
4865# 1) A set of options (BlockdevOptions): the child is reopened with
4866# the specified set of options.
4867#
4868# 2) A reference to the current child: the child is reopened using
4869# its existing set of options.
4870#
4871# 3) A reference to a different node: the current child is replaced
4872# with the specified one.
4873#
4874# 4) NULL: the current child (if any) is detached.
4875#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004876# Options (1) and (2) are supported in all cases. Option (3) is
Alberto Garcia3908b7a2021-07-08 13:47:07 +02004877# supported for @file and @backing, and option (4) for @backing only.
Alberto Garcia1479c732019-03-12 18:48:51 +02004878#
4879# Unlike with blockdev-add, the @backing option must always be present
4880# unless the node being reopened does not have a backing file and its
4881# image does not have a default backing file name as part of its
4882# metadata.
4883#
Alberto Garciae60edf62021-07-08 13:47:09 +02004884# Since: 6.1
Alberto Garcia1479c732019-03-12 18:48:51 +02004885##
Alberto Garciae60edf62021-07-08 13:47:09 +02004886{ 'command': 'blockdev-reopen',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05004887 'data': { 'options': ['BlockdevOptions'] },
4888 'allow-preconfig': true }
Alberto Garcia1479c732019-03-12 18:48:51 +02004889
4890##
Markus Armbruster79b7a772017-03-21 17:53:28 +01004891# @blockdev-del:
Alberto Garcia81b936a2015-11-02 16:51:55 +02004892#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004893# Deletes a block device that has been added using blockdev-add. The
4894# command will fail if the node is attached to a device or is
Kevin Wolf9ec88732016-09-21 14:56:11 +02004895# otherwise being used.
Alberto Garcia81b936a2015-11-02 16:51:55 +02004896#
Marc-André Lureau7a305382017-01-13 15:41:22 +01004897# @node-name: Name of the graph node to delete.
4898#
Markus Armbruster79b7a772017-03-21 17:53:28 +01004899# Since: 2.9
Marc-André Lureau915a2132016-06-23 14:55:00 +02004900#
John Snow14b48aa2024-07-16 22:13:08 -04004901# .. qmp-example::
Marc-André Lureau915a2132016-06-23 14:55:00 +02004902#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004903# -> { "execute": "blockdev-add",
4904# "arguments": {
4905# "driver": "qcow2",
4906# "node-name": "node0",
4907# "file": {
4908# "driver": "file",
4909# "filename": "test.qcow2"
4910# }
4911# }
4912# }
4913# <- { "return": {} }
Marc-André Lureau915a2132016-06-23 14:55:00 +02004914#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01004915# -> { "execute": "blockdev-del",
4916# "arguments": { "node-name": "node0" }
4917# }
4918# <- { "return": {} }
Alberto Garcia81b936a2015-11-02 16:51:55 +02004919##
Paolo Bonzinif55ba802020-11-03 04:37:20 -05004920{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' },
4921 'allow-preconfig': true }
Alberto Garcia81b936a2015-11-02 16:51:55 +02004922
4923##
Kevin Wolf927f11e2018-01-16 16:04:21 +01004924# @BlockdevCreateOptionsFile:
4925#
4926# Driver specific image creation options for file.
4927#
Peter Maydellf5627502020-02-13 17:56:25 +00004928# @filename: Filename for the new image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004929#
Peter Maydellf5627502020-02-13 17:56:25 +00004930# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004931#
Peter Maydellf5627502020-02-13 17:56:25 +00004932# @preallocation: Preallocation mode for the new image (default: off;
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004933# allowed values: off, falloc (if CONFIG_POSIX_FALLOCATE), full
4934# (if CONFIG_POSIX))
4935#
Peter Maydellf5627502020-02-13 17:56:25 +00004936# @nocow: Turn off copy-on-write (valid only on btrfs; default: off)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004937#
4938# @extent-size-hint: Extent size hint to add to the image file; 0 for
4939# not adding an extent size hint (default: 1 MB, since 5.1)
Kevin Wolf927f11e2018-01-16 16:04:21 +01004940#
4941# Since: 2.12
4942##
4943{ 'struct': 'BlockdevCreateOptionsFile',
Kevin Wolfffa244c2020-07-07 16:23:29 +02004944 'data': { 'filename': 'str',
4945 'size': 'size',
4946 '*preallocation': 'PreallocMode',
4947 '*nocow': 'bool',
4948 '*extent-size-hint': 'size'} }
Kevin Wolf927f11e2018-01-16 16:04:21 +01004949
4950##
Kevin Wolfab8bda72018-01-31 16:27:38 +01004951# @BlockdevCreateOptionsGluster:
4952#
4953# Driver specific image creation options for gluster.
4954#
Peter Maydellf5627502020-02-13 17:56:25 +00004955# @location: Where to store the new image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004956#
Peter Maydellf5627502020-02-13 17:56:25 +00004957# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004958#
Peter Maydellf5627502020-02-13 17:56:25 +00004959# @preallocation: Preallocation mode for the new image (default: off;
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004960# allowed values: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE),
4961# full (if CONFIG_GLUSTERFS_ZEROFILL))
Kevin Wolfab8bda72018-01-31 16:27:38 +01004962#
4963# Since: 2.12
4964##
4965{ 'struct': 'BlockdevCreateOptionsGluster',
4966 'data': { 'location': 'BlockdevOptionsGluster',
4967 'size': 'size',
4968 '*preallocation': 'PreallocMode' } }
4969
4970##
Kevin Wolf1bedcaf2018-03-02 14:31:04 +01004971# @BlockdevCreateOptionsLUKS:
4972#
4973# Driver specific image creation options for LUKS.
4974#
Hyman Huang433957b2024-01-30 13:37:20 +08004975# @file: Node to create the image format on, mandatory except when
Markus Armbruster5305a4e2024-03-22 15:09:09 +01004976# 'preallocation' is not requested
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004977#
Markus Armbruster5305a4e2024-03-22 15:09:09 +01004978# @header: Block device holding a detached LUKS header. (since 9.0)
Hyman Huangd0112eb2024-01-30 13:37:22 +08004979#
Peter Maydellf5627502020-02-13 17:56:25 +00004980# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02004981#
4982# @preallocation: Preallocation mode for the new image (since: 4.2)
4983# (default: off; allowed values: off, metadata, falloc, full)
Kevin Wolf1bedcaf2018-03-02 14:31:04 +01004984#
4985# Since: 2.12
4986##
4987{ 'struct': 'BlockdevCreateOptionsLUKS',
4988 'base': 'QCryptoBlockCreateOptionsLUKS',
Hyman Huang433957b2024-01-30 13:37:20 +08004989 'data': { '*file': 'BlockdevRef',
Hyman Huangd0112eb2024-01-30 13:37:22 +08004990 '*header': 'BlockdevRef',
Maxim Levitsky672de722019-07-16 19:19:01 +03004991 'size': 'size',
4992 '*preallocation': 'PreallocMode' } }
Kevin Wolf1bedcaf2018-03-02 14:31:04 +01004993
4994##
Kevin Wolfa1a42af2018-01-31 16:27:38 +01004995# @BlockdevCreateOptionsNfs:
4996#
4997# Driver specific image creation options for NFS.
4998#
Peter Maydellf5627502020-02-13 17:56:25 +00004999# @location: Where to store the new image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005000#
Peter Maydellf5627502020-02-13 17:56:25 +00005001# @size: Size of the virtual disk in bytes
Kevin Wolfa1a42af2018-01-31 16:27:38 +01005002#
5003# Since: 2.12
5004##
5005{ 'struct': 'BlockdevCreateOptionsNfs',
5006 'data': { 'location': 'BlockdevOptionsNfs',
5007 'size': 'size' } }
5008
5009##
Kevin Wolf1511b492018-03-06 12:13:58 +01005010# @BlockdevCreateOptionsParallels:
5011#
5012# Driver specific image creation options for parallels.
5013#
Peter Maydellf5627502020-02-13 17:56:25 +00005014# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005015#
Peter Maydellf5627502020-02-13 17:56:25 +00005016# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005017#
Peter Maydellf5627502020-02-13 17:56:25 +00005018# @cluster-size: Cluster size in bytes (default: 1 MB)
Kevin Wolf1511b492018-03-06 12:13:58 +01005019#
5020# Since: 2.12
5021##
5022{ 'struct': 'BlockdevCreateOptionsParallels',
5023 'data': { 'file': 'BlockdevRef',
5024 'size': 'size',
5025 '*cluster-size': 'size' } }
5026
5027##
Kevin Wolf42a3e1a2018-03-09 19:53:19 +01005028# @BlockdevCreateOptionsQcow:
5029#
5030# Driver specific image creation options for qcow.
5031#
Peter Maydellf5627502020-02-13 17:56:25 +00005032# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005033#
Peter Maydellf5627502020-02-13 17:56:25 +00005034# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005035#
Peter Maydellf5627502020-02-13 17:56:25 +00005036# @backing-file: File name of the backing file if a backing file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005037# should be used
5038#
Peter Maydellf5627502020-02-13 17:56:25 +00005039# @encrypt: Encryption options if the image should be encrypted
Kevin Wolf42a3e1a2018-03-09 19:53:19 +01005040#
5041# Since: 2.12
5042##
5043{ 'struct': 'BlockdevCreateOptionsQcow',
5044 'data': { 'file': 'BlockdevRef',
5045 'size': 'size',
5046 '*backing-file': 'str',
5047 '*encrypt': 'QCryptoBlockCreateOptions' } }
5048
5049##
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005050# @BlockdevQcow2Version:
5051#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005052# @v2: The original QCOW2 format as introduced in qemu 0.10 (version
5053# 2)
5054#
Andrea Bolognani23e46452022-05-03 09:37:35 +02005055# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3)
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005056#
5057# Since: 2.12
5058##
5059{ 'enum': 'BlockdevQcow2Version',
5060 'data': [ 'v2', 'v3' ] }
5061
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005062##
Denis Plotnikov572ad972020-05-07 11:25:18 +03005063# @Qcow2CompressionType:
5064#
5065# Compression type used in qcow2 image file
5066#
5067# @zlib: zlib compression, see <http://zlib.net/>
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005068#
Denis Plotnikovd298ac12020-05-07 11:25:20 +03005069# @zstd: zstd compression, see <http://github.com/facebook/zstd>
Denis Plotnikov572ad972020-05-07 11:25:18 +03005070#
5071# Since: 5.1
5072##
5073{ 'enum': 'Qcow2CompressionType',
Marc-André Lureau8a9f1e12021-08-04 12:31:05 +04005074 'data': [ 'zlib', { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] }
Denis Plotnikov572ad972020-05-07 11:25:18 +03005075
5076##
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005077# @BlockdevCreateOptionsQcow2:
5078#
5079# Driver specific image creation options for qcow2.
5080#
Peter Maydellf5627502020-02-13 17:56:25 +00005081# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005082#
Peter Maydellf5627502020-02-13 17:56:25 +00005083# @data-file: Node to use as an external data file in which all guest
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005084# data is stored so that only metadata remains in the qcow2 file
5085# (since: 4.0)
5086#
Peter Maydellf5627502020-02-13 17:56:25 +00005087# @data-file-raw: True if the external data file must stay valid as a
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005088# standalone (read-only) raw image without looking at qcow2
5089# metadata (default: false; since: 4.0)
5090#
Peter Maydell826bd062020-09-25 17:22:56 +01005091# @extended-l2: True to make the image have extended L2 entries
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005092# (default: false; since 5.2)
5093#
Peter Maydellf5627502020-02-13 17:56:25 +00005094# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005095#
Peter Maydellf5627502020-02-13 17:56:25 +00005096# @version: Compatibility level (default: v3)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005097#
Peter Maydellf5627502020-02-13 17:56:25 +00005098# @backing-file: File name of the backing file if a backing file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005099# should be used
5100#
Peter Maydellf5627502020-02-13 17:56:25 +00005101# @backing-fmt: Name of the block driver to use for the backing file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005102#
Peter Maydellf5627502020-02-13 17:56:25 +00005103# @encrypt: Encryption options if the image should be encrypted
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005104#
Peter Maydellf5627502020-02-13 17:56:25 +00005105# @cluster-size: qcow2 cluster size in bytes (default: 65536)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005106#
Peter Maydellf5627502020-02-13 17:56:25 +00005107# @preallocation: Preallocation mode for the new image (default: off;
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005108# allowed values: off, falloc, full, metadata)
5109#
5110# @lazy-refcounts: True if refcounts may be updated lazily
5111# (default: off)
5112#
Peter Maydellf5627502020-02-13 17:56:25 +00005113# @refcount-bits: Width of reference counts in bits (default: 16)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005114#
Denis Plotnikov572ad972020-05-07 11:25:18 +03005115# @compression-type: The image cluster compression method
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005116# (default: zlib, since 5.1)
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005117#
5118# Since: 2.12
5119##
5120{ 'struct': 'BlockdevCreateOptionsQcow2',
5121 'data': { 'file': 'BlockdevRef',
Kevin Wolfdcc98682019-01-14 16:57:27 +01005122 '*data-file': 'BlockdevRef',
Kevin Wolf6c3944d2019-02-22 14:29:38 +01005123 '*data-file-raw': 'bool',
Alberto Garcia7be20252020-07-10 18:13:13 +02005124 '*extended-l2': 'bool',
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005125 'size': 'size',
5126 '*version': 'BlockdevQcow2Version',
5127 '*backing-file': 'str',
5128 '*backing-fmt': 'BlockdevDriver',
5129 '*encrypt': 'QCryptoBlockCreateOptions',
5130 '*cluster-size': 'size',
5131 '*preallocation': 'PreallocMode',
5132 '*lazy-refcounts': 'bool',
Denis Plotnikov572ad972020-05-07 11:25:18 +03005133 '*refcount-bits': 'int',
5134 '*compression-type':'Qcow2CompressionType' } }
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005135
5136##
Kevin Wolf959355a2018-03-09 19:53:19 +01005137# @BlockdevCreateOptionsQed:
5138#
5139# Driver specific image creation options for qed.
5140#
Peter Maydellf5627502020-02-13 17:56:25 +00005141# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005142#
Peter Maydellf5627502020-02-13 17:56:25 +00005143# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005144#
Peter Maydellf5627502020-02-13 17:56:25 +00005145# @backing-file: File name of the backing file if a backing file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005146# should be used
5147#
Peter Maydellf5627502020-02-13 17:56:25 +00005148# @backing-fmt: Name of the block driver to use for the backing file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005149#
Peter Maydellf5627502020-02-13 17:56:25 +00005150# @cluster-size: Cluster size in bytes (default: 65536)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005151#
Peter Maydellf5627502020-02-13 17:56:25 +00005152# @table-size: L1/L2 table size (in clusters)
Kevin Wolf959355a2018-03-09 19:53:19 +01005153#
5154# Since: 2.12
5155##
5156{ 'struct': 'BlockdevCreateOptionsQed',
5157 'data': { 'file': 'BlockdevRef',
5158 'size': 'size',
5159 '*backing-file': 'str',
5160 '*backing-fmt': 'BlockdevDriver',
5161 '*cluster-size': 'size',
5162 '*table-size': 'int' } }
5163
5164##
Kevin Wolf1bebea32018-01-31 16:27:38 +01005165# @BlockdevCreateOptionsRbd:
5166#
5167# Driver specific image creation options for rbd/Ceph.
5168#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005169# @location: Where to store the new image file. This location cannot
5170# point to a snapshot.
5171#
Peter Maydellf5627502020-02-13 17:56:25 +00005172# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005173#
Peter Maydellf5627502020-02-13 17:56:25 +00005174# @cluster-size: RBD object size
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005175#
5176# @encrypt: Image encryption options. (Since 6.1)
Kevin Wolf1bebea32018-01-31 16:27:38 +01005177#
5178# Since: 2.12
5179##
5180{ 'struct': 'BlockdevCreateOptionsRbd',
5181 'data': { 'location': 'BlockdevOptionsRbd',
5182 'size': 'size',
Or Ozeri42e4ac92021-06-27 14:46:35 +03005183 '*cluster-size' : 'size',
5184 '*encrypt' : 'RbdEncryptionCreateOptions' } }
Kevin Wolf1bebea32018-01-31 16:27:38 +01005185
5186##
Fam Zheng30153722018-05-15 23:36:32 +08005187# @BlockdevVmdkSubformat:
5188#
5189# Subformat options for VMDK images
5190#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005191# @monolithicSparse: Single file image with sparse cluster allocation
Fam Zheng30153722018-05-15 23:36:32 +08005192#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005193# @monolithicFlat: Single flat data image and a descriptor file
Fam Zheng30153722018-05-15 23:36:32 +08005194#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005195# @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA)
5196# sparse extent files, in addition to a descriptor file
Fam Zheng30153722018-05-15 23:36:32 +08005197#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005198# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat
5199# extent files, in addition to a descriptor file
Fam Zheng30153722018-05-15 23:36:32 +08005200#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005201# @streamOptimized: Single file image sparse cluster allocation,
5202# optimized for streaming over network.
Fam Zheng30153722018-05-15 23:36:32 +08005203#
5204# Since: 4.0
5205##
5206{ 'enum': 'BlockdevVmdkSubformat',
5207 'data': [ 'monolithicSparse', 'monolithicFlat', 'twoGbMaxExtentSparse',
5208 'twoGbMaxExtentFlat', 'streamOptimized'] }
5209
5210##
5211# @BlockdevVmdkAdapterType:
5212#
5213# Adapter type info for VMDK images
5214#
5215# Since: 4.0
5216##
5217{ 'enum': 'BlockdevVmdkAdapterType',
5218 'data': [ 'ide', 'buslogic', 'lsilogic', 'legacyESX'] }
5219
5220##
5221# @BlockdevCreateOptionsVmdk:
5222#
5223# Driver specific image creation options for VMDK.
5224#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005225# @file: Where to store the new image file. This refers to the image
5226# file for monolithcSparse and streamOptimized format, or the
5227# descriptor file for other formats.
5228#
Peter Maydellf5627502020-02-13 17:56:25 +00005229# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005230#
5231# @extents: Where to store the data extents. Required for
5232# monolithcFlat, twoGbMaxExtentSparse and twoGbMaxExtentFlat
5233# formats. For monolithicFlat, only one entry is required; for
5234# twoGbMaxExtent* formats, the number of entries required is
Markus Armbruster01bed0f2024-07-29 08:52:20 +02005235# calculated as extent_number = virtual_size / 2GB. Providing
5236# more extents than will be used is an error.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005237#
5238# @subformat: The subformat of the VMDK image. Default:
5239# "monolithicSparse".
5240#
5241# @backing-file: The path of backing file. Default: no backing file
5242# is used.
5243#
5244# @adapter-type: The adapter type used to fill in the descriptor.
5245# Default: ide.
5246#
5247# @hwversion: Hardware version. The meaningful options are "4" or
Markus Armbruster01bed0f2024-07-29 08:52:20 +02005248# "6". Default: "4".
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005249#
5250# @toolsversion: VMware guest tools version. Default: "2147483647"
5251# (Since 6.2)
5252#
5253# @zeroed-grain: Whether to enable zeroed-grain feature for sparse
5254# subformats. Default: false.
Fam Zheng30153722018-05-15 23:36:32 +08005255#
5256# Since: 4.0
5257##
5258{ 'struct': 'BlockdevCreateOptionsVmdk',
5259 'data': { 'file': 'BlockdevRef',
5260 'size': 'size',
5261 '*extents': ['BlockdevRef'],
5262 '*subformat': 'BlockdevVmdkSubformat',
5263 '*backing-file': 'str',
5264 '*adapter-type': 'BlockdevVmdkAdapterType',
5265 '*hwversion': 'str',
Thomas Weißschuhf3d43df2021-09-13 15:04:19 +02005266 '*toolsversion': 'str',
Fam Zheng30153722018-05-15 23:36:32 +08005267 '*zeroed-grain': 'bool' } }
5268
Fam Zheng30153722018-05-15 23:36:32 +08005269##
Kevin Wolf4906da72018-02-05 16:24:32 +01005270# @BlockdevCreateOptionsSsh:
5271#
5272# Driver specific image creation options for SSH.
5273#
Peter Maydellf5627502020-02-13 17:56:25 +00005274# @location: Where to store the new image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005275#
Peter Maydellf5627502020-02-13 17:56:25 +00005276# @size: Size of the virtual disk in bytes
Kevin Wolf4906da72018-02-05 16:24:32 +01005277#
5278# Since: 2.12
5279##
5280{ 'struct': 'BlockdevCreateOptionsSsh',
5281 'data': { 'location': 'BlockdevOptionsSsh',
5282 'size': 'size' } }
5283
5284##
Max Reitz49858b52018-03-12 17:55:26 +01005285# @BlockdevCreateOptionsVdi:
5286#
5287# Driver specific image creation options for VDI.
5288#
Peter Maydellf5627502020-02-13 17:56:25 +00005289# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005290#
Peter Maydellf5627502020-02-13 17:56:25 +00005291# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005292#
Peter Maydellf5627502020-02-13 17:56:25 +00005293# @preallocation: Preallocation mode for the new image (default: off;
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005294# allowed values: off, metadata)
Max Reitz49858b52018-03-12 17:55:26 +01005295#
5296# Since: 2.12
5297##
5298{ 'struct': 'BlockdevCreateOptionsVdi',
5299 'data': { 'file': 'BlockdevRef',
5300 'size': 'size',
Kevin Wolf61fa6482018-03-20 15:08:00 +01005301 '*preallocation': 'PreallocMode' } }
Max Reitz49858b52018-03-12 17:55:26 +01005302
5303##
Kevin Wolf09b68da2018-03-09 19:53:19 +01005304# @BlockdevVhdxSubformat:
5305#
5306# @dynamic: Growing image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005307#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005308# @fixed: Preallocated fixed-size image file
Kevin Wolf09b68da2018-03-09 19:53:19 +01005309#
5310# Since: 2.12
5311##
5312{ 'enum': 'BlockdevVhdxSubformat',
5313 'data': [ 'dynamic', 'fixed' ] }
5314
5315##
5316# @BlockdevCreateOptionsVhdx:
5317#
5318# Driver specific image creation options for vhdx.
5319#
Peter Maydellf5627502020-02-13 17:56:25 +00005320# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005321#
Peter Maydellf5627502020-02-13 17:56:25 +00005322# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005323#
5324# @log-size: Log size in bytes, must be a multiple of 1 MB (default: 1
5325# MB)
5326#
Peter Maydellf5627502020-02-13 17:56:25 +00005327# @block-size: Block size in bytes, must be a multiple of 1 MB and not
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005328# larger than 256 MB (default: automatically choose a block size
5329# depending on the image size)
5330#
Peter Maydellf5627502020-02-13 17:56:25 +00005331# @subformat: vhdx subformat (default: dynamic)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005332#
Markus Armbruster9e272072023-07-20 09:16:09 +02005333# @block-state-zero: Force use of payload blocks of type 'ZERO'.
5334# Non-standard, but default. Do not set to 'off' when using
5335# 'qemu-img convert' with subformat=dynamic.
Kevin Wolf09b68da2018-03-09 19:53:19 +01005336#
5337# Since: 2.12
5338##
5339{ 'struct': 'BlockdevCreateOptionsVhdx',
5340 'data': { 'file': 'BlockdevRef',
5341 'size': 'size',
5342 '*log-size': 'size',
5343 '*block-size': 'size',
5344 '*subformat': 'BlockdevVhdxSubformat',
5345 '*block-state-zero': 'bool' } }
5346
5347##
Kevin Wolf182c8832018-03-09 19:53:19 +01005348# @BlockdevVpcSubformat:
5349#
5350# @dynamic: Growing image file
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005351#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005352# @fixed: Preallocated fixed-size image file
Kevin Wolf182c8832018-03-09 19:53:19 +01005353#
5354# Since: 2.12
5355##
5356{ 'enum': 'BlockdevVpcSubformat',
5357 'data': [ 'dynamic', 'fixed' ] }
5358
5359##
5360# @BlockdevCreateOptionsVpc:
5361#
5362# Driver specific image creation options for vpc (VHD).
5363#
Peter Maydellf5627502020-02-13 17:56:25 +00005364# @file: Node to create the image format on
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005365#
Peter Maydellf5627502020-02-13 17:56:25 +00005366# @size: Size of the virtual disk in bytes
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005367#
Peter Maydellf5627502020-02-13 17:56:25 +00005368# @subformat: vhdx subformat (default: dynamic)
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005369#
5370# @force-size: Force use of the exact byte size instead of rounding to
5371# the next size that can be represented in CHS geometry
5372# (default: false)
Kevin Wolf182c8832018-03-09 19:53:19 +01005373#
5374# Since: 2.12
5375##
5376{ 'struct': 'BlockdevCreateOptionsVpc',
5377 'data': { 'file': 'BlockdevRef',
5378 'size': 'size',
5379 '*subformat': 'BlockdevVpcSubformat',
5380 '*force-size': 'bool' } }
5381
5382##
Kevin Wolf53614682017-11-24 16:01:07 +01005383# @BlockdevCreateOptions:
5384#
5385# Options for creating an image format on a given node.
5386#
Peter Maydellf5627502020-02-13 17:56:25 +00005387# @driver: block driver to create the image format
Kevin Wolf53614682017-11-24 16:01:07 +01005388#
5389# Since: 2.12
5390##
5391{ 'union': 'BlockdevCreateOptions',
5392 'base': {
5393 'driver': 'BlockdevDriver' },
5394 'discriminator': 'driver',
5395 'data': {
Kevin Wolf927f11e2018-01-16 16:04:21 +01005396 'file': 'BlockdevCreateOptionsFile',
Kevin Wolfab8bda72018-01-31 16:27:38 +01005397 'gluster': 'BlockdevCreateOptionsGluster',
Kevin Wolf1bedcaf2018-03-02 14:31:04 +01005398 'luks': 'BlockdevCreateOptionsLUKS',
Kevin Wolfa1a42af2018-01-31 16:27:38 +01005399 'nfs': 'BlockdevCreateOptionsNfs',
Kevin Wolf1511b492018-03-06 12:13:58 +01005400 'parallels': 'BlockdevCreateOptionsParallels',
Kevin Wolf42a3e1a2018-03-09 19:53:19 +01005401 'qcow': 'BlockdevCreateOptionsQcow',
Kevin Wolfc2808ab2017-11-24 16:01:07 +01005402 'qcow2': 'BlockdevCreateOptionsQcow2',
Kevin Wolf959355a2018-03-09 19:53:19 +01005403 'qed': 'BlockdevCreateOptionsQed',
Kevin Wolf1bebea32018-01-31 16:27:38 +01005404 'rbd': 'BlockdevCreateOptionsRbd',
Kevin Wolf4906da72018-02-05 16:24:32 +01005405 'ssh': 'BlockdevCreateOptionsSsh',
Max Reitze3810572018-03-12 17:55:28 +01005406 'vdi': 'BlockdevCreateOptionsVdi',
Kevin Wolf09b68da2018-03-09 19:53:19 +01005407 'vhdx': 'BlockdevCreateOptionsVhdx',
Fam Zheng30153722018-05-15 23:36:32 +08005408 'vmdk': 'BlockdevCreateOptionsVmdk',
Anton Nefedov29cd0402018-06-18 11:40:06 +03005409 'vpc': 'BlockdevCreateOptionsVpc'
Kevin Wolf53614682017-11-24 16:01:07 +01005410 } }
5411
5412##
Kevin Wolf3fb588a2018-05-25 18:24:51 +02005413# @blockdev-create:
Kevin Wolfb0292b82018-01-09 16:50:57 +01005414#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005415# Starts a job to create an image format on a given node. The job is
Kevin Wolfe5ab4342018-01-18 14:33:04 +01005416# automatically finalized, but a manual job-dismiss is required.
Kevin Wolfb0292b82018-01-09 16:50:57 +01005417#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005418# @job-id: Identifier for the newly created job.
Kevin Wolfe5ab4342018-01-18 14:33:04 +01005419#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005420# @options: Options for the image creation.
Kevin Wolfe5ab4342018-01-18 14:33:04 +01005421#
5422# Since: 3.0
Kevin Wolfb0292b82018-01-09 16:50:57 +01005423##
Kevin Wolf3fb588a2018-05-25 18:24:51 +02005424{ 'command': 'blockdev-create',
Kevin Wolfe5ab4342018-01-18 14:33:04 +01005425 'data': { 'job-id': 'str',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05005426 'options': 'BlockdevCreateOptions' },
5427 'allow-preconfig': true }
Kevin Wolfb0292b82018-01-09 16:50:57 +01005428
5429##
Maxim Levitsky30da9dd2020-06-25 14:55:46 +02005430# @BlockdevAmendOptionsLUKS:
5431#
5432# Driver specific image amend options for LUKS.
5433#
5434# Since: 5.1
5435##
5436{ 'struct': 'BlockdevAmendOptionsLUKS',
5437 'base': 'QCryptoBlockAmendOptionsLUKS',
5438 'data': { }
5439}
5440
5441##
Maxim Levitsky8ea16132020-06-25 14:55:47 +02005442# @BlockdevAmendOptionsQcow2:
5443#
Markus Armbruster01bed0f2024-07-29 08:52:20 +02005444# Driver specific image amend options for qcow2. For now, only
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005445# encryption options can be amended
Maxim Levitsky8ea16132020-06-25 14:55:47 +02005446#
Markus Armbruster91577c42023-04-25 08:42:19 +02005447# @encrypt: Encryption options to be amended
Maxim Levitsky8ea16132020-06-25 14:55:47 +02005448#
5449# Since: 5.1
5450##
5451{ 'struct': 'BlockdevAmendOptionsQcow2',
5452 'data': { '*encrypt': 'QCryptoBlockAmendOptions' } }
5453
5454##
Maxim Levitskyced914d2020-06-25 14:55:45 +02005455# @BlockdevAmendOptions:
5456#
5457# Options for amending an image format
5458#
Andrea Bolognani23e46452022-05-03 09:37:35 +02005459# @driver: Block driver of the node to amend.
Maxim Levitskyced914d2020-06-25 14:55:45 +02005460#
5461# Since: 5.1
5462##
5463{ 'union': 'BlockdevAmendOptions',
5464 'base': {
5465 'driver': 'BlockdevDriver' },
5466 'discriminator': 'driver',
5467 'data': {
Maxim Levitsky8ea16132020-06-25 14:55:47 +02005468 'luks': 'BlockdevAmendOptionsLUKS',
5469 'qcow2': 'BlockdevAmendOptionsQcow2' } }
Maxim Levitskyced914d2020-06-25 14:55:45 +02005470
5471##
5472# @x-blockdev-amend:
5473#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005474# Starts a job to amend format specific options of an existing open
5475# block device The job is automatically finalized, but a manual
5476# job-dismiss is required.
Maxim Levitskyced914d2020-06-25 14:55:45 +02005477#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005478# @job-id: Identifier for the newly created job.
Maxim Levitskyced914d2020-06-25 14:55:45 +02005479#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005480# @node-name: Name of the block node to work on
Maxim Levitskyced914d2020-06-25 14:55:45 +02005481#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +02005482# @options: Options (driver specific)
Maxim Levitskyced914d2020-06-25 14:55:45 +02005483#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005484# @force: Allow unsafe operations, format specific For luks that
5485# allows erase of the last active keyslot (permanent loss of
5486# data), and replacement of an active keyslot (possible loss of
5487# data if IO error happens)
Maxim Levitskyced914d2020-06-25 14:55:45 +02005488#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005489# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005490#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005491# @unstable: This command is experimental.
5492#
Maxim Levitskyced914d2020-06-25 14:55:45 +02005493# Since: 5.1
5494##
5495{ 'command': 'x-blockdev-amend',
5496 'data': { 'job-id': 'str',
5497 'node-name': 'str',
5498 'options': 'BlockdevAmendOptions',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005499 '*force': 'bool' },
Paolo Bonzinif55ba802020-11-03 04:37:20 -05005500 'features': [ 'unstable' ],
5501 'allow-preconfig': true }
Maxim Levitskyced914d2020-06-25 14:55:45 +02005502
5503##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005504# @BlockErrorAction:
Wenchao Xiaa5895692014-06-18 08:43:30 +02005505#
5506# An enumeration of action that has been taken when a DISK I/O occurs
5507#
5508# @ignore: error has been ignored
5509#
5510# @report: error has been reported to the device
5511#
5512# @stop: error caused VM to be stopped
5513#
5514# Since: 2.1
5515##
5516{ 'enum': 'BlockErrorAction',
5517 'data': [ 'ignore', 'report', 'stop' ] }
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005518
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005519##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005520# @BLOCK_IMAGE_CORRUPTED:
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005521#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005522# Emitted when a disk image is being marked corrupt. The image can be
5523# identified by its device or node name. The 'device' field is always
Marc-André Lureau370d4eb2016-06-23 15:51:26 +02005524# present for compatibility reasons, but it can be empty ("") if the
5525# image does not have a device name associated.
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005526#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005527# @device: device name. This is always present for compatibility
5528# reasons, but it can be empty ("") if the image does not have a
5529# device name associated.
Alberto Garciadc881b42015-04-08 12:29:20 +03005530#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01005531# @node-name: node name (Since: 2.4)
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005532#
5533# @msg: informative message for human consumption, such as the kind of
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005534# corruption being detected. It should not be parsed by machine
5535# as it is not guaranteed to be stable
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005536#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01005537# @offset: if the corruption resulted from an image access, this is
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005538# the host's access offset into the image
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005539#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005540# @size: if the corruption resulted from an image access, this is the
5541# access size
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005542#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005543# @fatal: if set, the image is marked corrupt and therefore unusable
5544# after this event and must be repaired (Since 2.2; before, every
5545# BLOCK_IMAGE_CORRUPTED event was fatal)
Max Reitz9bf040b2014-09-05 16:07:15 +02005546#
Markus Armbruster01bed0f2024-07-29 08:52:20 +02005547# .. note:: If action is "stop", a STOP event will eventually follow
5548# the BLOCK_IO_ERROR event.
Marc-André Lureau07c9f582016-06-23 15:52:10 +02005549#
John Snow14b48aa2024-07-16 22:13:08 -04005550# .. qmp-example::
Marc-André Lureau370d4eb2016-06-23 15:51:26 +02005551#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005552# <- { "event": "BLOCK_IMAGE_CORRUPTED",
5553# "data": { "device": "", "node-name": "drive", "fatal": false,
5554# "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
5555# "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
Marc-André Lureau370d4eb2016-06-23 15:51:26 +02005556#
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005557# Since: 1.7
5558##
5559{ 'event': 'BLOCK_IMAGE_CORRUPTED',
Alberto Garciadc881b42015-04-08 12:29:20 +03005560 'data': { 'device' : 'str',
5561 '*node-name' : 'str',
5562 'msg' : 'str',
5563 '*offset' : 'int',
5564 '*size' : 'int',
5565 'fatal' : 'bool' } }
Wenchao Xiac120f0f2014-06-18 08:43:46 +02005566
5567##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005568# @BLOCK_IO_ERROR:
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005569#
5570# Emitted when a disk I/O error occurs
5571#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005572# @device: device name. This is always present for compatibility
5573# reasons, but it can be empty ("") if the image does not have a
5574# device name associated.
Kevin Wolf2bf7e102016-09-29 16:47:58 +02005575#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005576# @node-name: node name. Note that errors may be reported for the
5577# root node that is directly attached to a guest device rather
5578# than for the node where the error occurred. The node name is
5579# not present if the drive is empty. (Since: 2.8)
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005580#
5581# @operation: I/O operation
5582#
5583# @action: action that has been taken
5584#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005585# @nospace: true if I/O error was caused due to a no-space condition.
5586# This key is only present if query-block's io-status is present,
5587# please see query-block documentation for more information
5588# (since: 2.2)
Luiz Capitulinoc7c2ff02014-08-29 16:07:27 -04005589#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005590# @reason: human readable string describing the error cause. (This
5591# field is a debugging aid for humans, it should not be parsed by
5592# applications) (since: 2.2)
Luiz Capitulino624ff572014-09-11 10:25:48 -04005593#
Markus Armbruster01bed0f2024-07-29 08:52:20 +02005594# .. note:: If action is "stop", a STOP event will eventually follow
5595# the BLOCK_IO_ERROR event.
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005596#
Markus Armbruster9bc6e892020-11-18 07:41:58 +01005597# Since: 0.13
Marc-André Lureau07c9f582016-06-23 15:52:10 +02005598#
John Snow14b48aa2024-07-16 22:13:08 -04005599# .. qmp-example::
Marc-André Lureau07c9f582016-06-23 15:52:10 +02005600#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005601# <- { "event": "BLOCK_IO_ERROR",
5602# "data": { "device": "ide0-hd1",
5603# "node-name": "#block212",
5604# "operation": "write",
5605# "action": "stop",
5606# "reason": "No space left on device" },
5607# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005608##
5609{ 'event': 'BLOCK_IO_ERROR',
Kevin Wolfbfe1a142018-03-05 15:59:35 +01005610 'data': { 'device': 'str', '*node-name': 'str',
5611 'operation': 'IoOperationType',
Luiz Capitulino624ff572014-09-11 10:25:48 -04005612 'action': 'BlockErrorAction', '*nospace': 'bool',
5613 'reason': 'str' } }
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005614
5615##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005616# @BLOCK_JOB_COMPLETED:
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005617#
5618# Emitted when a block job has completed
5619#
5620# @type: job type
5621#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005622# @device: The job identifier. Originally the device name but other
5623# values are allowed since QEMU 2.7
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005624#
5625# @len: maximum progress value
5626#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005627# @offset: current progress value. On success this is equal to len.
5628# On failure this is less than len
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005629#
5630# @speed: rate limit, bytes per second
5631#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005632# @error: error message. Only present on failure. This field
5633# contains a human-readable error message. There are no semantics
5634# other than that streaming has failed and clients should not try
5635# to interpret the error string
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005636#
5637# Since: 1.1
Marc-André Lureaue21e65b2016-06-23 15:52:56 +02005638#
John Snow14b48aa2024-07-16 22:13:08 -04005639# .. qmp-example::
Marc-André Lureaue21e65b2016-06-23 15:52:56 +02005640#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005641# <- { "event": "BLOCK_JOB_COMPLETED",
5642# "data": { "type": "stream", "device": "virtio-disk0",
5643# "len": 10737418240, "offset": 10737418240,
5644# "speed": 0 },
5645# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005646##
5647{ 'event': 'BLOCK_JOB_COMPLETED',
Kevin Wolf8e4c8702018-04-12 18:01:07 +02005648 'data': { 'type' : 'JobType',
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005649 'device': 'str',
5650 'len' : 'int',
5651 'offset': 'int',
5652 'speed' : 'int',
5653 '*error': 'str' } }
5654
5655##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005656# @BLOCK_JOB_CANCELLED:
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005657#
5658# Emitted when a block job has been cancelled
5659#
5660# @type: job type
5661#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005662# @device: The job identifier. Originally the device name but other
5663# values are allowed since QEMU 2.7
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005664#
5665# @len: maximum progress value
5666#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005667# @offset: current progress value. On success this is equal to len.
5668# On failure this is less than len
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005669#
5670# @speed: rate limit, bytes per second
5671#
5672# Since: 1.1
Marc-André Lureaue161df32016-06-23 15:53:50 +02005673#
John Snow14b48aa2024-07-16 22:13:08 -04005674# .. qmp-example::
Marc-André Lureaue161df32016-06-23 15:53:50 +02005675#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005676# <- { "event": "BLOCK_JOB_CANCELLED",
5677# "data": { "type": "stream", "device": "virtio-disk0",
5678# "len": 10737418240, "offset": 134217728,
5679# "speed": 0 },
5680# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005681##
5682{ 'event': 'BLOCK_JOB_CANCELLED',
Kevin Wolf8e4c8702018-04-12 18:01:07 +02005683 'data': { 'type' : 'JobType',
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005684 'device': 'str',
5685 'len' : 'int',
5686 'offset': 'int',
5687 'speed' : 'int' } }
5688
5689##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005690# @BLOCK_JOB_ERROR:
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005691#
5692# Emitted when a block job encounters an error
5693#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005694# @device: The job identifier. Originally the device name but other
5695# values are allowed since QEMU 2.7
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005696#
5697# @operation: I/O operation
5698#
5699# @action: action that has been taken
5700#
5701# Since: 1.3
Marc-André Lureauaf0e0912016-06-23 15:54:20 +02005702#
John Snow14b48aa2024-07-16 22:13:08 -04005703# .. qmp-example::
Marc-André Lureauaf0e0912016-06-23 15:54:20 +02005704#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005705# <- { "event": "BLOCK_JOB_ERROR",
5706# "data": { "device": "ide0-hd1",
5707# "operation": "write",
5708# "action": "stop" },
5709# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
Wenchao Xia5a2d2cb2014-06-18 08:43:45 +02005710##
5711{ 'event': 'BLOCK_JOB_ERROR',
5712 'data': { 'device' : 'str',
5713 'operation': 'IoOperationType',
Markus Armbruster823c6862014-06-27 19:24:14 +02005714 'action' : 'BlockErrorAction' } }
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005715
5716##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005717# @BLOCK_JOB_READY:
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005718#
5719# Emitted when a block job is ready to complete
5720#
Markus Armbruster518848a2014-06-27 19:24:13 +02005721# @type: job type
5722#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005723# @device: The job identifier. Originally the device name but other
5724# values are allowed since QEMU 2.7
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005725#
Markus Armbruster518848a2014-06-27 19:24:13 +02005726# @len: maximum progress value
5727#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005728# @offset: current progress value. On success this is equal to len.
5729# On failure this is less than len
Markus Armbruster518848a2014-06-27 19:24:13 +02005730#
5731# @speed: rate limit, bytes per second
5732#
John Snowd461c272024-06-26 18:21:16 -04005733# .. note:: The "ready to complete" status is always reset by a
5734# @BLOCK_JOB_ERROR event.
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005735#
5736# Since: 1.3
Marc-André Lureau11a3dee2016-06-23 15:54:49 +02005737#
John Snow14b48aa2024-07-16 22:13:08 -04005738# .. qmp-example::
Marc-André Lureau11a3dee2016-06-23 15:54:49 +02005739#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005740# <- { "event": "BLOCK_JOB_READY",
5741# "data": { "device": "drive0", "type": "mirror", "speed": 0,
5742# "len": 2097152, "offset": 2097152 },
5743# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
Wenchao Xiabcada37b2014-06-18 08:43:47 +02005744##
5745{ 'event': 'BLOCK_JOB_READY',
Kevin Wolf8e4c8702018-04-12 18:01:07 +02005746 'data': { 'type' : 'JobType',
Markus Armbruster518848a2014-06-27 19:24:13 +02005747 'device': 'str',
5748 'len' : 'int',
5749 'offset': 'int',
5750 'speed' : 'int' } }
Hu Taoffeaac92014-09-10 17:05:47 +08005751
Marc-André Lureau49687ac2016-11-17 19:54:51 +04005752##
John Snow5f241592018-03-10 03:27:42 -05005753# @BLOCK_JOB_PENDING:
5754#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005755# Emitted when a block job is awaiting explicit authorization to
5756# finalize graph changes via @block-job-finalize. If this job is part
5757# of a transaction, it will not emit this event until the transaction
5758# has converged first.
John Snow5f241592018-03-10 03:27:42 -05005759#
5760# @type: job type
5761#
5762# @id: The job identifier.
5763#
5764# Since: 2.12
5765#
John Snow14b48aa2024-07-16 22:13:08 -04005766# .. qmp-example::
John Snow5f241592018-03-10 03:27:42 -05005767#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005768# <- { "event": "BLOCK_JOB_PENDING",
5769# "data": { "type": "mirror", "id": "backup_1" },
5770# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
John Snow5f241592018-03-10 03:27:42 -05005771##
5772{ 'event': 'BLOCK_JOB_PENDING',
Kevin Wolf8e4c8702018-04-12 18:01:07 +02005773 'data': { 'type' : 'JobType',
John Snow5f241592018-03-10 03:27:42 -05005774 'id' : 'str' } }
5775
5776##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005777# @PreallocMode:
Hu Taoffeaac92014-09-10 17:05:47 +08005778#
5779# Preallocation mode of QEMU image file
5780#
5781# @off: no preallocation
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005782#
Hu Taoffeaac92014-09-10 17:05:47 +08005783# @metadata: preallocate only for metadata
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005784#
Hu Taoffeaac92014-09-10 17:05:47 +08005785# @falloc: like @full preallocation but allocate disk space by
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005786# posix_fallocate() rather than writing data.
5787#
Max Reitzfa27c472019-07-11 15:29:35 +02005788# @full: preallocate all data by writing it to the device to ensure
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005789# disk space is really available. This data may or may not be
5790# zero, depending on the image format and storage. @full
5791# preallocation also sets up metadata correctly.
Hu Taoffeaac92014-09-10 17:05:47 +08005792#
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005793# Since: 2.2
Hu Taoffeaac92014-09-10 17:05:47 +08005794##
5795{ 'enum': 'PreallocMode',
5796 'data': [ 'off', 'metadata', 'falloc', 'full' ] }
Francesco Romanie2462112015-01-12 14:11:13 +01005797
5798##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005799# @BLOCK_WRITE_THRESHOLD:
Francesco Romanie2462112015-01-12 14:11:13 +01005800#
5801# Emitted when writes on block device reaches or exceeds the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005802# configured write threshold. For thin-provisioned devices, this
5803# means the device should be extended to avoid pausing for disk
5804# exhaustion. The event is one shot. Once triggered, it needs to be
Eric Blakef85d66f2017-05-12 14:30:15 -05005805# re-registered with another block-set-write-threshold command.
Francesco Romanie2462112015-01-12 14:11:13 +01005806#
5807# @node-name: graph node name on which the threshold was exceeded.
5808#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005809# @amount-exceeded: amount of data which exceeded the threshold, in
5810# bytes.
Francesco Romanie2462112015-01-12 14:11:13 +01005811#
5812# @write-threshold: last configured threshold, in bytes.
5813#
5814# Since: 2.3
5815##
5816{ 'event': 'BLOCK_WRITE_THRESHOLD',
5817 'data': { 'node-name': 'str',
5818 'amount-exceeded': 'uint64',
5819 'write-threshold': 'uint64' } }
5820
5821##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005822# @block-set-write-threshold:
Francesco Romanie2462112015-01-12 14:11:13 +01005823#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005824# Change the write threshold for a block drive. An event will be
Marc-André Lureaue8178622016-06-23 15:04:41 +02005825# delivered if a write to this block drive crosses the configured
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005826# threshold. The threshold is an offset, thus must be non-negative.
5827# Default is no write threshold. Setting the threshold to zero
5828# disables it.
Marc-André Lureaue8178622016-06-23 15:04:41 +02005829#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005830# This is useful to transparently resize thin-provisioned drives
5831# without the guest OS noticing.
Francesco Romanie2462112015-01-12 14:11:13 +01005832#
5833# @node-name: graph node name on which the threshold must be set.
5834#
5835# @write-threshold: configured threshold for the block device, bytes.
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005836# Use 0 to disable the threshold.
Francesco Romanie2462112015-01-12 14:11:13 +01005837#
Francesco Romanie2462112015-01-12 14:11:13 +01005838# Since: 2.3
Marc-André Lureaue8178622016-06-23 15:04:41 +02005839#
John Snow14b48aa2024-07-16 22:13:08 -04005840# .. qmp-example::
Marc-André Lureaue8178622016-06-23 15:04:41 +02005841#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005842# -> { "execute": "block-set-write-threshold",
5843# "arguments": { "node-name": "mydev",
5844# "write-threshold": 17179869184 } }
5845# <- { "return": {} }
Francesco Romanie2462112015-01-12 14:11:13 +01005846##
5847{ 'command': 'block-set-write-threshold',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05005848 'data': { 'node-name': 'str', 'write-threshold': 'uint64' },
5849 'allow-preconfig': true }
Wen Congyang7f821592016-05-10 15:36:39 +08005850
5851##
Marc-André Lureau5072f7b2016-11-17 19:54:55 +04005852# @x-blockdev-change:
Wen Congyang7f821592016-05-10 15:36:39 +08005853#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005854# Dynamically reconfigure the block driver state graph. It can be
5855# used to add, remove, insert or replace a graph node. Currently only
5856# the Quorum driver implements this feature to add or remove its
5857# child. This is useful to fix a broken quorum child.
Wen Congyang7f821592016-05-10 15:36:39 +08005858#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005859# If @node is specified, it will be inserted under @parent. @child
5860# may not be specified in this case. If both @parent and @child are
Wen Congyang7f821592016-05-10 15:36:39 +08005861# specified but @node is not, @child will be detached from @parent.
5862#
5863# @parent: the id or name of the parent node.
5864#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01005865# @child: the name of a child under the given parent node.
Wen Congyang7f821592016-05-10 15:36:39 +08005866#
Markus Armbruster1d8bda12017-03-15 13:57:06 +01005867# @node: the name of the node that will be added.
Wen Congyang7f821592016-05-10 15:36:39 +08005868#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005869# Features:
Wen Congyang7f821592016-05-10 15:36:39 +08005870#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005871# @unstable: This command is experimental, and its API is not stable.
5872# It does not support all kinds of operations, all kinds of
5873# children, nor all block drivers.
Kevin Wolf6b4738c2017-12-15 11:54:22 +01005874#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005875# FIXME Removing children from a quorum node means introducing
5876# gaps in the child indices. This cannot be represented in the
5877# 'children' list of BlockdevOptionsQuorum, as returned by
5878# .bdrv_refresh_filename().
5879#
5880# Warning: The data in a new quorum child MUST be consistent with
5881# that of the rest of the array.
Wen Congyang7f821592016-05-10 15:36:39 +08005882#
5883# Since: 2.7
Marc-André Lureaubd77ea22016-06-23 15:28:23 +02005884#
John Snowa9eab6e2024-07-16 22:13:09 -04005885# .. qmp-example::
5886# :title: Add a new node to a quorum
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005887#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005888# -> { "execute": "blockdev-add",
5889# "arguments": {
5890# "driver": "raw",
5891# "node-name": "new_node",
5892# "file": { "driver": "file",
5893# "filename": "test.raw" } } }
5894# <- { "return": {} }
5895# -> { "execute": "x-blockdev-change",
5896# "arguments": { "parent": "disk1",
5897# "node": "new_node" } }
5898# <- { "return": {} }
Marc-André Lureaubd77ea22016-06-23 15:28:23 +02005899#
John Snowa9eab6e2024-07-16 22:13:09 -04005900# .. qmp-example::
5901# :title: Delete a quorum's node
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005902#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005903# -> { "execute": "x-blockdev-change",
5904# "arguments": { "parent": "disk1",
5905# "child": "children.1" } }
5906# <- { "return": {} }
Wen Congyang7f821592016-05-10 15:36:39 +08005907##
5908{ 'command': 'x-blockdev-change',
5909 'data' : { 'parent': 'str',
5910 '*child': 'str',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005911 '*node': 'str' },
Paolo Bonzinif55ba802020-11-03 04:37:20 -05005912 'features': [ 'unstable' ],
5913 'allow-preconfig': true }
Stefan Hajnoczica00bbb2017-12-06 14:45:49 +00005914
5915##
5916# @x-blockdev-set-iothread:
5917#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005918# Move @node and its children into the @iothread. If @iothread is
5919# null then move @node and its children into the main loop.
Stefan Hajnoczica00bbb2017-12-06 14:45:49 +00005920#
5921# The node must not be attached to a BlockBackend.
5922#
5923# @node-name: the name of the block driver node
5924#
5925# @iothread: the name of the IOThread object or null for the main loop
5926#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005927# @force: true if the node and its children should be moved when a
5928# BlockBackend is already attached
Stefan Hajnoczi882e9b82017-12-07 20:13:17 +00005929#
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005930# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005931#
5932# @unstable: This command is experimental and intended for test cases
5933# that need control over IOThreads only.
Stefan Hajnoczica00bbb2017-12-06 14:45:49 +00005934#
5935# Since: 2.12
5936#
John Snowa9eab6e2024-07-16 22:13:09 -04005937# .. qmp-example::
5938# :title: Move a node into an IOThread
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005939#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005940# -> { "execute": "x-blockdev-set-iothread",
5941# "arguments": { "node-name": "disk1",
5942# "iothread": "iothread0" } }
5943# <- { "return": {} }
Stefan Hajnoczica00bbb2017-12-06 14:45:49 +00005944#
John Snowa9eab6e2024-07-16 22:13:09 -04005945# .. qmp-example::
5946# :title: Move a node into the main loop
Markus Armbrustera937b6a2023-04-28 12:54:29 +02005947#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005948# -> { "execute": "x-blockdev-set-iothread",
5949# "arguments": { "node-name": "disk1",
5950# "iothread": null } }
5951# <- { "return": {} }
Stefan Hajnoczica00bbb2017-12-06 14:45:49 +00005952##
5953{ 'command': 'x-blockdev-set-iothread',
5954 'data' : { 'node-name': 'str',
Stefan Hajnoczi882e9b82017-12-07 20:13:17 +00005955 'iothread': 'StrOrNull',
Markus Armbruster9fb49da2021-10-28 12:25:13 +02005956 '*force': 'bool' },
Paolo Bonzinif55ba802020-11-03 04:37:20 -05005957 'features': [ 'unstable' ],
5958 'allow-preconfig': true }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01005959
5960##
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01005961# @QuorumOpType:
5962#
5963# An enumeration of the quorum operation types
5964#
5965# @read: read operation
5966#
5967# @write: write operation
5968#
5969# @flush: flush operation
5970#
5971# Since: 2.6
5972##
5973{ 'enum': 'QuorumOpType',
5974 'data': [ 'read', 'write', 'flush' ] }
5975
5976##
5977# @QUORUM_FAILURE:
5978#
5979# Emitted by the Quorum block driver if it fails to establish a quorum
5980#
5981# @reference: device name if defined else node name
5982#
5983# @sector-num: number of the first sector of the failed read operation
5984#
5985# @sectors-count: failed read operation sector count
5986#
John Snowd461c272024-06-26 18:21:16 -04005987# .. note:: This event is rate-limited.
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01005988#
5989# Since: 2.0
5990#
John Snow14b48aa2024-07-16 22:13:08 -04005991# .. qmp-example::
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01005992#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01005993# <- { "event": "QUORUM_FAILURE",
5994# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
5995# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01005996##
5997{ 'event': 'QUORUM_FAILURE',
5998 'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } }
5999
6000##
6001# @QUORUM_REPORT_BAD:
6002#
6003# Emitted to report a corruption of a Quorum file
6004#
6005# @type: quorum operation type (Since 2.6)
6006#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006007# @error: error message. Only present on failure. This field
6008# contains a human-readable error message. There are no semantics
6009# other than that the block layer reported an error and clients
6010# should not try to interpret the error string.
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006011#
6012# @node-name: the graph node name of the block driver state
6013#
6014# @sector-num: number of the first sector of the failed read operation
6015#
6016# @sectors-count: failed read operation sector count
6017#
John Snowd461c272024-06-26 18:21:16 -04006018# .. note:: This event is rate-limited.
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006019#
6020# Since: 2.0
6021#
John Snowa9eab6e2024-07-16 22:13:09 -04006022# .. qmp-example::
6023# :title: Read operation
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006024#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01006025# <- { "event": "QUORUM_REPORT_BAD",
6026# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
6027# "type": "read" },
6028# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006029#
John Snowa9eab6e2024-07-16 22:13:09 -04006030# .. qmp-example::
6031# :title: Flush operation
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006032#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01006033# <- { "event": "QUORUM_REPORT_BAD",
6034# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
6035# "type": "flush", "error": "Broken pipe" },
6036# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006037##
6038{ 'event': 'QUORUM_REPORT_BAD',
6039 'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str',
6040 'sector-num': 'int', 'sectors-count': 'int' } }
6041
6042##
6043# @BlockdevSnapshotInternal:
6044#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006045# @device: the device name or node-name of a root node to generate the
6046# snapshot from
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006047#
6048# @name: the name of the internal snapshot to be created
6049#
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006050# Since: 1.7
6051##
6052{ 'struct': 'BlockdevSnapshotInternal',
6053 'data': { 'device': 'str', 'name': 'str' } }
6054
6055##
6056# @blockdev-snapshot-internal-sync:
6057#
6058# Synchronously take an internal snapshot of a block device, when the
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006059# format of the image used supports it. If the name is an empty
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006060# string, or a snapshot with name already exists, the operation will
6061# fail.
6062#
Markus Armbruster2746f062024-02-27 12:39:12 +01006063# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006064# - If @device is not a valid block device, GenericError
6065# - If any snapshot matching @name exists, or @name is empty,
6066# GenericError
6067# - If the format of the image used does not support it,
6068# GenericError
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006069#
Markus Armbrusterf0e0c462024-07-18 14:36:09 +02006070# .. note:: Only some image formats such as qcow2 and rbd support
6071# internal snapshots.
6072#
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006073# Since: 1.7
6074#
John Snow14b48aa2024-07-16 22:13:08 -04006075# .. qmp-example::
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006076#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01006077# -> { "execute": "blockdev-snapshot-internal-sync",
6078# "arguments": { "device": "ide-hd0",
6079# "name": "snapshot0" }
6080# }
6081# <- { "return": {} }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006082##
6083{ 'command': 'blockdev-snapshot-internal-sync',
Paolo Bonzinif55ba802020-11-03 04:37:20 -05006084 'data': 'BlockdevSnapshotInternal',
6085 'allow-preconfig': true }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006086
6087##
6088# @blockdev-snapshot-delete-internal-sync:
6089#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006090# Synchronously delete an internal snapshot of a block device, when
6091# the format of the image used support it. The snapshot is identified
6092# by name or id or both. One of the name or id is required. Return
6093# SnapshotInfo for the successfully deleted snapshot.
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006094#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006095# @device: the device name or node-name of a root node to delete the
6096# snapshot from
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006097#
6098# @id: optional the snapshot's ID to be deleted
6099#
6100# @name: optional the snapshot's name to be deleted
6101#
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006102# Returns:
Markus Armbrustere2c1dcb2024-02-27 12:39:14 +01006103# SnapshotInfo
Markus Armbruster2746f062024-02-27 12:39:12 +01006104#
6105# Errors:
Markus Armbrustera937b6a2023-04-28 12:54:29 +02006106# - If @device is not a valid block device, GenericError
6107# - If snapshot not found, GenericError
6108# - If the format of the image used does not support it,
6109# GenericError
6110# - If @id and @name are both not specified, GenericError
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006111#
6112# Since: 1.7
6113#
John Snow14b48aa2024-07-16 22:13:08 -04006114# .. qmp-example::
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006115#
Markus Armbrusterd23055b2024-02-16 15:58:34 +01006116# -> { "execute": "blockdev-snapshot-delete-internal-sync",
6117# "arguments": { "device": "ide-hd0",
6118# "name": "snapshot0" }
6119# }
6120# <- { "return": {
6121# "id": "1",
6122# "name": "snapshot0",
6123# "vm-state-size": 0,
6124# "date-sec": 1000012,
6125# "date-nsec": 10,
6126# "vm-clock-sec": 100,
6127# "vm-clock-nsec": 20,
6128# "icount": 220414
6129# }
6130# }
Kevin Wolfb3cf1ec2020-02-24 15:29:52 +01006131##
6132{ 'command': 'blockdev-snapshot-delete-internal-sync',
6133 'data': { 'device': 'str', '*id': 'str', '*name': 'str'},
Paolo Bonzinif55ba802020-11-03 04:37:20 -05006134 'returns': 'SnapshotInfo',
6135 'allow-preconfig': true }
Hanna Reitz456e7512022-06-20 18:26:55 +02006136
6137##
6138# @DummyBlockCoreForceArrays:
6139#
Hanna Reitzc04d0ab2022-06-20 18:27:03 +02006140# Not used by QMP; hack to let us use BlockGraphInfoList internally
Hanna Reitz456e7512022-06-20 18:26:55 +02006141#
6142# Since: 8.0
6143##
6144{ 'struct': 'DummyBlockCoreForceArrays',
Hanna Reitzc04d0ab2022-06-20 18:27:03 +02006145 'data': { 'unused-block-graph-info': ['BlockGraphInfo'] } }