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