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