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# @depth: number of layers (0 = top image, 1 = top image's backing 413# file, ..., n - 1 = bottom image (where n is the number of images 414# in the chain)) before reaching one for which the range is 415# allocated 416# 417# @present: true if this layer provides the data, false if adding a 418# backing layer could impact this region (since 6.1) 419# 420# @offset: if present, the image file stores the data for this range 421# in raw format at the given (host) offset 422# 423# @filename: filename that is referred to by @offset 424# 425# Since: 2.6 426## 427{ 'struct': 'MapEntry', 428 'data': {'start': 'int', 'length': 'int', 'data': 'bool', 429 'zero': 'bool', 'depth': 'int', 'present': 'bool', 430 '*offset': 'int', '*filename': 'str' } } 431 432## 433# @BlockdevCacheInfo: 434# 435# Cache mode information for a block device 436# 437# @writeback: true if writeback mode is enabled 438# 439# @direct: true if the host page cache is bypassed (O_DIRECT) 440# 441# @no-flush: true if flush requests are ignored for the device 442# 443# Since: 2.3 444## 445{ 'struct': 'BlockdevCacheInfo', 446 'data': { 'writeback': 'bool', 447 'direct': 'bool', 448 'no-flush': 'bool' } } 449 450## 451# @BlockDeviceInfo: 452# 453# Information about the backing device for a block device. 454# 455# @file: the filename of the backing device 456# 457# @node-name: the name of the block driver node (Since 2.0) 458# 459# @ro: true if the backing device was open read-only 460# 461# @drv: the name of the block format used to open the backing device. 462# As of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 463# 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 464# 'host_device', 'http', 'https', 'luks', 'nbd', 'parallels', 465# 'qcow', 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 466# 'archipelago' added, 'cow' dropped 2.3: 'host_floppy' deprecated 467# 2.5: 'host_floppy' dropped 2.6: 'luks' added 2.8: 'replication' 468# added, 'tftp' dropped 2.9: 'archipelago' dropped 469# 470# @backing_file: the name of the backing file (for copy-on-write) 471# 472# @backing_file_depth: number of files in the backing file chain 473# (since: 1.2) 474# 475# @encrypted: true if the backing device is encrypted 476# 477# @detect_zeroes: detect and optimize zero writes (Since 2.1) 478# 479# @bps: total throughput limit in bytes per second is specified 480# 481# @bps_rd: read throughput limit in bytes per second is specified 482# 483# @bps_wr: write throughput limit in bytes per second is specified 484# 485# @iops: total I/O operations per second is specified 486# 487# @iops_rd: read I/O operations per second is specified 488# 489# @iops_wr: write I/O operations per second is specified 490# 491# @image: the info of image used (since: 1.6) 492# 493# @bps_max: total throughput limit during bursts, in bytes (Since 1.7) 494# 495# @bps_rd_max: read throughput limit during bursts, in bytes (Since 496# 1.7) 497# 498# @bps_wr_max: write throughput limit during bursts, in bytes (Since 499# 1.7) 500# 501# @iops_max: total I/O operations per second during bursts, in bytes 502# (Since 1.7) 503# 504# @iops_rd_max: read I/O operations per second during bursts, in bytes 505# (Since 1.7) 506# 507# @iops_wr_max: write I/O operations per second during bursts, in 508# bytes (Since 1.7) 509# 510# @bps_max_length: maximum length of the @bps_max burst period, in 511# seconds. (Since 2.6) 512# 513# @bps_rd_max_length: maximum length of the @bps_rd_max burst period, 514# in seconds. (Since 2.6) 515# 516# @bps_wr_max_length: maximum length of the @bps_wr_max burst period, 517# in seconds. (Since 2.6) 518# 519# @iops_max_length: maximum length of the @iops burst period, in 520# seconds. (Since 2.6) 521# 522# @iops_rd_max_length: maximum length of the @iops_rd_max burst 523# period, in seconds. (Since 2.6) 524# 525# @iops_wr_max_length: maximum length of the @iops_wr_max burst 526# period, in seconds. (Since 2.6) 527# 528# @iops_size: an I/O size in bytes (Since 1.7) 529# 530# @group: throttle group name (Since 2.4) 531# 532# @cache: the cache mode used for the block device (since: 2.3) 533# 534# @write_threshold: configured write threshold for the device. 0 if 535# disabled. (Since 2.3) 536# 537# @dirty-bitmaps: dirty bitmaps information (only present if node has 538# one or more dirty bitmaps) (Since 4.2) 539# 540# Since: 0.14 541## 542{ 'struct': 'BlockDeviceInfo', 543 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str', 544 '*backing_file': 'str', 'backing_file_depth': 'int', 545 'encrypted': 'bool', 546 'detect_zeroes': 'BlockdevDetectZeroesOptions', 547 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int', 548 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int', 549 'image': 'ImageInfo', 550 '*bps_max': 'int', '*bps_rd_max': 'int', 551 '*bps_wr_max': 'int', '*iops_max': 'int', 552 '*iops_rd_max': 'int', '*iops_wr_max': 'int', 553 '*bps_max_length': 'int', '*bps_rd_max_length': 'int', 554 '*bps_wr_max_length': 'int', '*iops_max_length': 'int', 555 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int', 556 '*iops_size': 'int', '*group': 'str', 'cache': 'BlockdevCacheInfo', 557 'write_threshold': 'int', '*dirty-bitmaps': ['BlockDirtyInfo'] } } 558 559## 560# @BlockDeviceIoStatus: 561# 562# An enumeration of block device I/O status. 563# 564# @ok: The last I/O operation has succeeded 565# 566# @failed: The last I/O operation has failed 567# 568# @nospace: The last I/O operation has failed due to a no-space 569# condition 570# 571# Since: 1.0 572## 573{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] } 574 575## 576# @BlockDirtyInfo: 577# 578# Block dirty bitmap information. 579# 580# @name: the name of the dirty bitmap (Since 2.4) 581# 582# @count: number of dirty bytes according to the dirty bitmap 583# 584# @granularity: granularity of the dirty bitmap in bytes (since 1.4) 585# 586# @recording: true if the bitmap is recording new writes from the 587# guest. (since 4.0) 588# 589# @busy: true if the bitmap is in-use by some operation (NBD or jobs) 590# and cannot be modified via QMP or used by another operation. 591# (since 4.0) 592# 593# @persistent: true if the bitmap was stored on disk, is scheduled to 594# be stored on disk, or both. (since 4.0) 595# 596# @inconsistent: true if this is a persistent bitmap that was 597# improperly stored. Implies @persistent to be true; @recording 598# and @busy to be false. This bitmap cannot be used. To remove 599# it, use @block-dirty-bitmap-remove. (Since 4.0) 600# 601# Since: 1.3 602## 603{ 'struct': 'BlockDirtyInfo', 604 'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32', 605 'recording': 'bool', 'busy': 'bool', 606 'persistent': 'bool', '*inconsistent': 'bool' } } 607 608## 609# @Qcow2BitmapInfoFlags: 610# 611# An enumeration of flags that a bitmap can report to the user. 612# 613# @in-use: This flag is set by any process actively modifying the 614# qcow2 file, and cleared when the updated bitmap is flushed to 615# the qcow2 image. The presence of this flag in an offline image 616# means that the bitmap was not saved correctly after its last 617# usage, and may contain inconsistent data. 618# 619# @auto: The bitmap must reflect all changes of the virtual disk by 620# any application that would write to this qcow2 file. 621# 622# Since: 4.0 623## 624{ 'enum': 'Qcow2BitmapInfoFlags', 625 'data': ['in-use', 'auto'] } 626 627## 628# @Qcow2BitmapInfo: 629# 630# Qcow2 bitmap information. 631# 632# @name: the name of the bitmap 633# 634# @granularity: granularity of the bitmap in bytes 635# 636# @flags: flags of the bitmap 637# 638# Since: 4.0 639## 640{ 'struct': 'Qcow2BitmapInfo', 641 'data': {'name': 'str', 'granularity': 'uint32', 642 'flags': ['Qcow2BitmapInfoFlags'] } } 643 644## 645# @BlockLatencyHistogramInfo: 646# 647# Block latency histogram. 648# 649# @boundaries: list of interval boundary values in nanoseconds, all 650# greater than zero and in ascending order. For example, the list 651# [10, 50, 100] produces the following histogram intervals: [0, 652# 10), [10, 50), [50, 100), [100, +inf). 653# 654# @bins: list of io request counts corresponding to histogram 655# intervals, one more element than @boundaries has. For the 656# example above, @bins may be something like [3, 1, 5, 2], and 657# corresponding histogram looks like: 658# 659# :: 660# 661# 5| * 662# 4| * 663# 3| * * 664# 2| * * * 665# 1| * * * * 666# +------------------ 667# 10 50 100 668# 669# Since: 4.0 670## 671{ 'struct': 'BlockLatencyHistogramInfo', 672 'data': {'boundaries': ['uint64'], 'bins': ['uint64'] } } 673 674## 675# @BlockInfo: 676# 677# Block device information. This structure describes a virtual device 678# and the backing device associated with it. 679# 680# @device: The device name associated with the virtual device. 681# 682# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the 683# block device. (since 2.10) 684# 685# @type: This field is returned only for compatibility reasons, it 686# should not be used (always returns 'unknown') 687# 688# @removable: True if the device supports removable media. 689# 690# @locked: True if the guest has locked this device from having its 691# media removed 692# 693# @tray_open: True if the device's tray is open (only present if it 694# has a tray) 695# 696# @io-status: @BlockDeviceIoStatus. Only present if the device 697# supports it and the VM is configured to stop on errors 698# (supported device models: virtio-blk, IDE, SCSI except 699# scsi-generic) 700# 701# @inserted: @BlockDeviceInfo describing the device if media is 702# present 703# 704# Since: 0.14 705## 706{ 'struct': 'BlockInfo', 707 'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool', 708 'locked': 'bool', '*inserted': 'BlockDeviceInfo', 709 '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus' } } 710 711## 712# @BlockMeasureInfo: 713# 714# Image file size calculation information. This structure describes 715# the size requirements for creating a new image file. 716# 717# The size requirements depend on the new image file format. File 718# size always equals virtual disk size for the 'raw' format, even for 719# sparse POSIX files. Compact formats such as 'qcow2' represent 720# unallocated and zero regions efficiently so file size may be smaller 721# than virtual disk size. 722# 723# The values are upper bounds that are guaranteed to fit the new image 724# file. Subsequent modification, such as internal snapshot or further 725# bitmap creation, may require additional space and is not covered 726# here. 727# 728# @required: Size required for a new image file, in bytes, when 729# copying just allocated guest-visible contents. 730# 731# @fully-allocated: Image file size, in bytes, once data has been 732# written to all sectors, when copying just guest-visible 733# contents. 734# 735# @bitmaps: Additional size required if all the top-level bitmap 736# metadata in the source image were to be copied to the 737# destination, present only when source and destination both 738# support persistent bitmaps. (since 5.1) 739# 740# Since: 2.10 741## 742{ 'struct': 'BlockMeasureInfo', 743 'data': {'required': 'int', 'fully-allocated': 'int', '*bitmaps': 'int'} } 744 745## 746# @query-block: 747# 748# Get a list of BlockInfo for all virtual block devices. 749# 750# Returns: a list of @BlockInfo describing each virtual block device. 751# Filter nodes that were created implicitly are skipped over. 752# 753# Since: 0.14 754# 755# Example: 756# 757# -> { "execute": "query-block" } 758# <- { 759# "return":[ 760# { 761# "io-status": "ok", 762# "device":"ide0-hd0", 763# "locked":false, 764# "removable":false, 765# "inserted":{ 766# "ro":false, 767# "drv":"qcow2", 768# "encrypted":false, 769# "file":"disks/test.qcow2", 770# "backing_file_depth":1, 771# "bps":1000000, 772# "bps_rd":0, 773# "bps_wr":0, 774# "iops":1000000, 775# "iops_rd":0, 776# "iops_wr":0, 777# "bps_max": 8000000, 778# "bps_rd_max": 0, 779# "bps_wr_max": 0, 780# "iops_max": 0, 781# "iops_rd_max": 0, 782# "iops_wr_max": 0, 783# "iops_size": 0, 784# "detect_zeroes": "on", 785# "write_threshold": 0, 786# "image":{ 787# "filename":"disks/test.qcow2", 788# "format":"qcow2", 789# "virtual-size":2048000, 790# "backing_file":"base.qcow2", 791# "full-backing-filename":"disks/base.qcow2", 792# "backing-filename-format":"qcow2", 793# "snapshots":[ 794# { 795# "id": "1", 796# "name": "snapshot1", 797# "vm-state-size": 0, 798# "date-sec": 10000200, 799# "date-nsec": 12, 800# "vm-clock-sec": 206, 801# "vm-clock-nsec": 30 802# } 803# ], 804# "backing-image":{ 805# "filename":"disks/base.qcow2", 806# "format":"qcow2", 807# "virtual-size":2048000 808# } 809# } 810# }, 811# "qdev": "ide_disk", 812# "type":"unknown" 813# }, 814# { 815# "io-status": "ok", 816# "device":"ide1-cd0", 817# "locked":false, 818# "removable":true, 819# "qdev": "/machine/unattached/device[23]", 820# "tray_open": false, 821# "type":"unknown" 822# }, 823# { 824# "device":"floppy0", 825# "locked":false, 826# "removable":true, 827# "qdev": "/machine/unattached/device[20]", 828# "type":"unknown" 829# }, 830# { 831# "device":"sd0", 832# "locked":false, 833# "removable":true, 834# "type":"unknown" 835# } 836# ] 837# } 838## 839{ 'command': 'query-block', 'returns': ['BlockInfo'], 840 'allow-preconfig': true } 841 842## 843# @BlockDeviceTimedStats: 844# 845# Statistics of a block device during a given interval of time. 846# 847# @interval_length: Interval used for calculating the statistics, in 848# seconds. 849# 850# @min_rd_latency_ns: Minimum latency of read operations in the 851# defined interval, in nanoseconds. 852# 853# @min_wr_latency_ns: Minimum latency of write operations in the 854# defined interval, in nanoseconds. 855# 856# @min_zone_append_latency_ns: Minimum latency of zone append operations 857# in the defined interval, in nanoseconds 858# (since 8.1) 859# 860# @min_flush_latency_ns: Minimum latency of flush operations in the 861# defined interval, in nanoseconds. 862# 863# @max_rd_latency_ns: Maximum latency of read operations in the 864# defined interval, in nanoseconds. 865# 866# @max_wr_latency_ns: Maximum latency of write operations in the 867# defined interval, in nanoseconds. 868# 869# @max_zone_append_latency_ns: Maximum latency of zone append operations 870# in the defined interval, in nanoseconds 871# (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 operations 883# in the defined interval, in nanoseconds 884# (since 8.1) 885# 886# @avg_flush_latency_ns: Average latency of flush operations in the 887# defined interval, in nanoseconds. 888# 889# @avg_rd_queue_depth: Average number of pending read operations in 890# the defined interval. 891# 892# @avg_wr_queue_depth: Average number of pending write operations in 893# the defined interval. 894# 895# @avg_zone_append_queue_depth: Average number of pending zone append 896# operations in the defined interval 897# (since 8.1). 898# 899# Since: 2.5 900## 901{ 'struct': 'BlockDeviceTimedStats', 902 'data': { 'interval_length': 'int', 'min_rd_latency_ns': 'int', 903 'max_rd_latency_ns': 'int', 'avg_rd_latency_ns': 'int', 904 'min_wr_latency_ns': 'int', 'max_wr_latency_ns': 'int', 905 'avg_wr_latency_ns': 'int', 'min_zone_append_latency_ns': 'int', 906 'max_zone_append_latency_ns': 'int', 907 'avg_zone_append_latency_ns': 'int', 908 'min_flush_latency_ns': 'int', 'max_flush_latency_ns': 'int', 909 'avg_flush_latency_ns': 'int', 'avg_rd_queue_depth': 'number', 910 'avg_wr_queue_depth': 'number', 911 'avg_zone_append_queue_depth': 'number' } } 912 913## 914# @BlockDeviceStats: 915# 916# Statistics of a virtual block device or a block backing device. 917# 918# @rd_bytes: The number of bytes read by the device. 919# 920# @wr_bytes: The number of bytes written by the device. 921# 922# @zone_append_bytes: The number of bytes appended by the zoned devices 923# (since 8.1) 924# 925# @unmap_bytes: The number of bytes unmapped by the device (Since 4.2) 926# 927# @rd_operations: The number of read operations performed by the 928# device. 929# 930# @wr_operations: The number of write operations performed by the 931# device. 932# 933# @zone_append_operations: The number of zone append operations performed 934# by the zoned devices (since 8.1) 935# 936# @flush_operations: The number of cache flush operations performed by 937# the device (since 0.15) 938# 939# @unmap_operations: The number of unmap operations performed by the 940# device (Since 4.2) 941# 942# @rd_total_time_ns: Total time spent on reads in nanoseconds (since 943# 0.15). 944# 945# @wr_total_time_ns: Total time spent on writes in nanoseconds (since 946# 0.15). 947# 948# @zone_append_total_time_ns: Total time spent on zone append writes 949# in nanoseconds (since 8.1) 950# 951# @flush_total_time_ns: Total time spent on cache flushes in 952# nanoseconds (since 0.15). 953# 954# @unmap_total_time_ns: Total time spent on unmap operations in 955# nanoseconds (Since 4.2) 956# 957# @wr_highest_offset: The offset after the greatest byte written to 958# the device. The intended use of this information is for 959# growable sparse files (like qcow2) that are used on top of a 960# physical device. 961# 962# @rd_merged: Number of read requests that have been merged into 963# another request (Since 2.3). 964# 965# @wr_merged: Number of write requests that have been merged into 966# another request (Since 2.3). 967# 968# @zone_append_merged: Number of zone append requests that have been merged 969# into another request (since 8.1) 970# 971# @unmap_merged: Number of unmap requests that have been merged into 972# another request (Since 4.2) 973# 974# @idle_time_ns: Time since the last I/O operation, in nanoseconds. 975# If the field is absent it means that there haven't been any 976# operations yet (Since 2.5). 977# 978# @failed_rd_operations: The number of failed read operations 979# performed by the device (Since 2.5) 980# 981# @failed_wr_operations: The number of failed write operations 982# performed by the device (Since 2.5) 983# 984# @failed_zone_append_operations: The number of failed zone append write 985# operations performed by the zoned devices 986# (since 8.1) 987# 988# @failed_flush_operations: The number of failed flush operations 989# performed by the device (Since 2.5) 990# 991# @failed_unmap_operations: The number of failed unmap operations 992# performed by the device (Since 4.2) 993# 994# @invalid_rd_operations: The number of invalid read operations 995# performed by the device (Since 2.5) 996# 997# @invalid_wr_operations: The number of invalid write operations 998# performed by the device (Since 2.5) 999# 1000# @invalid_zone_append_operations: The number of invalid zone append operations 1001# performed by the zoned device (since 8.1) 1002# 1003# @invalid_flush_operations: The number of invalid flush operations 1004# performed by the device (Since 2.5) 1005# 1006# @invalid_unmap_operations: The number of invalid unmap operations 1007# performed by the device (Since 4.2) 1008# 1009# @account_invalid: Whether invalid operations are included in the 1010# last access statistics (Since 2.5) 1011# 1012# @account_failed: Whether failed operations are included in the 1013# latency and last access statistics (Since 2.5) 1014# 1015# @timed_stats: Statistics specific to the set of previously defined 1016# intervals of time (Since 2.5) 1017# 1018# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) 1019# 1020# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) 1021# 1022# @zone_append_latency_histogram: @BlockLatencyHistogramInfo. (since 8.1) 1023# 1024# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) 1025# 1026# Since: 0.14 1027## 1028{ 'struct': 'BlockDeviceStats', 1029 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'zone_append_bytes': 'int', 1030 'unmap_bytes' : 'int', 'rd_operations': 'int', 1031 'wr_operations': 'int', 'zone_append_operations': 'int', 1032 'flush_operations': 'int', 'unmap_operations': 'int', 1033 'rd_total_time_ns': 'int', 'wr_total_time_ns': 'int', 1034 'zone_append_total_time_ns': 'int', 'flush_total_time_ns': 'int', 1035 'unmap_total_time_ns': 'int', 'wr_highest_offset': 'int', 1036 'rd_merged': 'int', 'wr_merged': 'int', 'zone_append_merged': 'int', 1037 'unmap_merged': 'int', '*idle_time_ns': 'int', 1038 'failed_rd_operations': 'int', 'failed_wr_operations': 'int', 1039 'failed_zone_append_operations': 'int', 1040 'failed_flush_operations': 'int', 1041 'failed_unmap_operations': 'int', 'invalid_rd_operations': 'int', 1042 'invalid_wr_operations': 'int', 1043 'invalid_zone_append_operations': 'int', 1044 'invalid_flush_operations': 'int', 'invalid_unmap_operations': 'int', 1045 'account_invalid': 'bool', 'account_failed': 'bool', 1046 'timed_stats': ['BlockDeviceTimedStats'], 1047 '*rd_latency_histogram': 'BlockLatencyHistogramInfo', 1048 '*wr_latency_histogram': 'BlockLatencyHistogramInfo', 1049 '*zone_append_latency_histogram': 'BlockLatencyHistogramInfo', 1050 '*flush_latency_histogram': 'BlockLatencyHistogramInfo' } } 1051 1052## 1053# @BlockStatsSpecificFile: 1054# 1055# File driver statistics 1056# 1057# @discard-nb-ok: The number of successful discard operations 1058# performed by the driver. 1059# 1060# @discard-nb-failed: The number of failed discard operations 1061# performed by the driver. 1062# 1063# @discard-bytes-ok: The number of bytes discarded by the driver. 1064# 1065# Since: 4.2 1066## 1067{ 'struct': 'BlockStatsSpecificFile', 1068 'data': { 1069 'discard-nb-ok': 'uint64', 1070 'discard-nb-failed': 'uint64', 1071 'discard-bytes-ok': 'uint64' } } 1072 1073## 1074# @BlockStatsSpecificNvme: 1075# 1076# NVMe driver statistics 1077# 1078# @completion-errors: The number of completion errors. 1079# 1080# @aligned-accesses: The number of aligned accesses performed by the 1081# driver. 1082# 1083# @unaligned-accesses: The number of unaligned accesses performed by 1084# the driver. 1085# 1086# Since: 5.2 1087## 1088{ 'struct': 'BlockStatsSpecificNvme', 1089 'data': { 1090 'completion-errors': 'uint64', 1091 'aligned-accesses': 'uint64', 1092 'unaligned-accesses': 'uint64' } } 1093 1094## 1095# @BlockStatsSpecific: 1096# 1097# Block driver specific statistics 1098# 1099# Since: 4.2 1100## 1101{ 'union': 'BlockStatsSpecific', 1102 'base': { 'driver': 'BlockdevDriver' }, 1103 'discriminator': 'driver', 1104 'data': { 1105 'file': 'BlockStatsSpecificFile', 1106 'host_device': { 'type': 'BlockStatsSpecificFile', 1107 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 1108 'nvme': 'BlockStatsSpecificNvme' } } 1109 1110## 1111# @BlockStats: 1112# 1113# Statistics of a virtual block device or a block backing device. 1114# 1115# @device: If the stats are for a virtual block device, the name 1116# corresponding to the virtual block device. 1117# 1118# @node-name: The node name of the device. (Since 2.3) 1119# 1120# @qdev: The qdev ID, or if no ID is assigned, the QOM path of the 1121# block device. (since 3.0) 1122# 1123# @stats: A @BlockDeviceStats for the device. 1124# 1125# @driver-specific: Optional driver-specific stats. (Since 4.2) 1126# 1127# @parent: This describes the file block device if it has one. 1128# Contains recursively the statistics of the underlying protocol 1129# (e.g. the host file for a qcow2 image). If there is no 1130# underlying protocol, this field is omitted 1131# 1132# @backing: This describes the backing block device if it has one. 1133# (Since 2.0) 1134# 1135# Since: 0.14 1136## 1137{ 'struct': 'BlockStats', 1138 'data': {'*device': 'str', '*qdev': 'str', '*node-name': 'str', 1139 'stats': 'BlockDeviceStats', 1140 '*driver-specific': 'BlockStatsSpecific', 1141 '*parent': 'BlockStats', 1142 '*backing': 'BlockStats'} } 1143 1144## 1145# @query-blockstats: 1146# 1147# Query the @BlockStats for all virtual block devices. 1148# 1149# @query-nodes: If true, the command will query all the block nodes 1150# that have a node name, in a list which will include "parent" 1151# information, but not "backing". If false or omitted, the 1152# behavior is as before - query all the device backends, 1153# recursively including their "parent" and "backing". Filter nodes 1154# that were created implicitly are skipped over in this mode. 1155# (Since 2.3) 1156# 1157# Returns: A list of @BlockStats for each virtual block devices. 1158# 1159# Since: 0.14 1160# 1161# Example: 1162# 1163# -> { "execute": "query-blockstats" } 1164# <- { 1165# "return":[ 1166# { 1167# "device":"ide0-hd0", 1168# "parent":{ 1169# "stats":{ 1170# "wr_highest_offset":3686448128, 1171# "wr_bytes":9786368, 1172# "wr_operations":751, 1173# "rd_bytes":122567168, 1174# "rd_operations":36772 1175# "wr_total_times_ns":313253456 1176# "rd_total_times_ns":3465673657 1177# "flush_total_times_ns":49653 1178# "flush_operations":61, 1179# "rd_merged":0, 1180# "wr_merged":0, 1181# "idle_time_ns":2953431879, 1182# "account_invalid":true, 1183# "account_failed":false 1184# } 1185# }, 1186# "stats":{ 1187# "wr_highest_offset":2821110784, 1188# "wr_bytes":9786368, 1189# "wr_operations":692, 1190# "rd_bytes":122739200, 1191# "rd_operations":36604 1192# "flush_operations":51, 1193# "wr_total_times_ns":313253456 1194# "rd_total_times_ns":3465673657 1195# "flush_total_times_ns":49653, 1196# "rd_merged":0, 1197# "wr_merged":0, 1198# "idle_time_ns":2953431879, 1199# "account_invalid":true, 1200# "account_failed":false 1201# }, 1202# "qdev": "/machine/unattached/device[23]" 1203# }, 1204# { 1205# "device":"ide1-cd0", 1206# "stats":{ 1207# "wr_highest_offset":0, 1208# "wr_bytes":0, 1209# "wr_operations":0, 1210# "rd_bytes":0, 1211# "rd_operations":0 1212# "flush_operations":0, 1213# "wr_total_times_ns":0 1214# "rd_total_times_ns":0 1215# "flush_total_times_ns":0, 1216# "rd_merged":0, 1217# "wr_merged":0, 1218# "account_invalid":false, 1219# "account_failed":false 1220# }, 1221# "qdev": "/machine/unattached/device[24]" 1222# }, 1223# { 1224# "device":"floppy0", 1225# "stats":{ 1226# "wr_highest_offset":0, 1227# "wr_bytes":0, 1228# "wr_operations":0, 1229# "rd_bytes":0, 1230# "rd_operations":0 1231# "flush_operations":0, 1232# "wr_total_times_ns":0 1233# "rd_total_times_ns":0 1234# "flush_total_times_ns":0, 1235# "rd_merged":0, 1236# "wr_merged":0, 1237# "account_invalid":false, 1238# "account_failed":false 1239# }, 1240# "qdev": "/machine/unattached/device[16]" 1241# }, 1242# { 1243# "device":"sd0", 1244# "stats":{ 1245# "wr_highest_offset":0, 1246# "wr_bytes":0, 1247# "wr_operations":0, 1248# "rd_bytes":0, 1249# "rd_operations":0 1250# "flush_operations":0, 1251# "wr_total_times_ns":0 1252# "rd_total_times_ns":0 1253# "flush_total_times_ns":0, 1254# "rd_merged":0, 1255# "wr_merged":0, 1256# "account_invalid":false, 1257# "account_failed":false 1258# } 1259# } 1260# ] 1261# } 1262## 1263{ 'command': 'query-blockstats', 1264 'data': { '*query-nodes': 'bool' }, 1265 'returns': ['BlockStats'], 1266 'allow-preconfig': true } 1267 1268## 1269# @BlockdevOnError: 1270# 1271# An enumeration of possible behaviors for errors on I/O operations. 1272# The exact meaning depends on whether the I/O was initiated by a 1273# guest or by a block job 1274# 1275# @report: for guest operations, report the error to the guest; for 1276# jobs, cancel the job 1277# 1278# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR 1279# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs 1280# retry the failing request later and may still complete 1281# successfully. The stream block job continues to stream and will 1282# complete with an error. 1283# 1284# @enospc: same as @stop on ENOSPC, same as @report otherwise. 1285# 1286# @stop: for guest operations, stop the virtual machine; for jobs, 1287# pause the job 1288# 1289# @auto: inherit the error handling policy of the backend (since: 2.7) 1290# 1291# Since: 1.3 1292## 1293{ 'enum': 'BlockdevOnError', 1294 'data': ['report', 'ignore', 'enospc', 'stop', 'auto'] } 1295 1296## 1297# @MirrorSyncMode: 1298# 1299# An enumeration of possible behaviors for the initial synchronization 1300# phase of storage mirroring. 1301# 1302# @top: copies data in the topmost image to the destination 1303# 1304# @full: copies data from all images to the destination 1305# 1306# @none: only copy data written from now on 1307# 1308# @incremental: only copy data described by the dirty bitmap. 1309# (since: 2.4) 1310# 1311# @bitmap: only copy data described by the dirty bitmap. (since: 4.2) 1312# Behavior on completion is determined by the BitmapSyncMode. 1313# 1314# Since: 1.3 1315## 1316{ 'enum': 'MirrorSyncMode', 1317 'data': ['top', 'full', 'none', 'incremental', 'bitmap'] } 1318 1319## 1320# @BitmapSyncMode: 1321# 1322# An enumeration of possible behaviors for the synchronization of a 1323# bitmap when used for data copy operations. 1324# 1325# @on-success: The bitmap is only synced when the operation is 1326# successful. This is the behavior always used for 'INCREMENTAL' 1327# backups. 1328# 1329# @never: The bitmap is never synchronized with the operation, and is 1330# treated solely as a read-only manifest of blocks to copy. 1331# 1332# @always: The bitmap is always synchronized with the operation, 1333# regardless of whether or not the operation was successful. 1334# 1335# Since: 4.2 1336## 1337{ 'enum': 'BitmapSyncMode', 1338 'data': ['on-success', 'never', 'always'] } 1339 1340## 1341# @MirrorCopyMode: 1342# 1343# An enumeration whose values tell the mirror block job when to 1344# trigger writes to the target. 1345# 1346# @background: copy data in background only. 1347# 1348# @write-blocking: when data is written to the source, write it 1349# (synchronously) to the target as well. In addition, data is 1350# copied in background just like in @background mode. 1351# 1352# Since: 3.0 1353## 1354{ 'enum': 'MirrorCopyMode', 1355 'data': ['background', 'write-blocking'] } 1356 1357## 1358# @BlockJobInfo: 1359# 1360# Information about a long-running block device operation. 1361# 1362# @type: the job type ('stream' for image streaming) 1363# 1364# @device: The job identifier. Originally the device name but other 1365# values are allowed since QEMU 2.7 1366# 1367# @len: Estimated @offset value at the completion of the job. This 1368# value can arbitrarily change while the job is running, in both 1369# directions. 1370# 1371# @offset: Progress made until now. The unit is arbitrary and the 1372# value can only meaningfully be used for the ratio of @offset to 1373# @len. The value is monotonically increasing. 1374# 1375# @busy: false if the job is known to be in a quiescent state, with no 1376# pending I/O. (Since 1.3) 1377# 1378# @paused: whether the job is paused or, if @busy is true, will pause 1379# itself as soon as possible. (Since 1.3) 1380# 1381# @speed: the rate limit, bytes per second 1382# 1383# @io-status: the status of the job (since 1.3) 1384# 1385# @ready: true if the job may be completed (since 2.2) 1386# 1387# @status: Current job state/status (since 2.12) 1388# 1389# @auto-finalize: Job will finalize itself when PENDING, moving to the 1390# CONCLUDED state. (since 2.12) 1391# 1392# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the 1393# NULL state and disappearing from the query list. (since 2.12) 1394# 1395# @error: Error information if the job did not complete successfully. 1396# Not set if the job completed successfully. (since 2.12.1) 1397# 1398# Since: 1.1 1399## 1400{ 'struct': 'BlockJobInfo', 1401 'data': {'type': 'str', 'device': 'str', 'len': 'int', 1402 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int', 1403 'io-status': 'BlockDeviceIoStatus', 'ready': 'bool', 1404 'status': 'JobStatus', 1405 'auto-finalize': 'bool', 'auto-dismiss': 'bool', 1406 '*error': 'str' } } 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# @BlockdevDiscardOptions: 3051# 3052# Determines how to handle discard requests. 3053# 3054# @ignore: Ignore the request 3055# 3056# @unmap: Forward as an unmap request 3057# 3058# Since: 2.9 3059## 3060{ 'enum': 'BlockdevDiscardOptions', 3061 'data': [ 'ignore', 'unmap' ] } 3062 3063## 3064# @BlockdevDetectZeroesOptions: 3065# 3066# Describes the operation mode for the automatic conversion of plain 3067# zero writes by the OS to driver specific optimized zero write 3068# commands. 3069# 3070# @off: Disabled (default) 3071# 3072# @on: Enabled 3073# 3074# @unmap: Enabled and even try to unmap blocks if possible. This 3075# requires also that @BlockdevDiscardOptions is set to unmap for 3076# this device. 3077# 3078# Since: 2.1 3079## 3080{ 'enum': 'BlockdevDetectZeroesOptions', 3081 'data': [ 'off', 'on', 'unmap' ] } 3082 3083## 3084# @BlockdevAioOptions: 3085# 3086# Selects the AIO backend to handle I/O requests 3087# 3088# @threads: Use qemu's thread pool 3089# 3090# @native: Use native AIO backend (only Linux and Windows) 3091# 3092# @io_uring: Use linux io_uring (since 5.0) 3093# 3094# Since: 2.9 3095## 3096{ 'enum': 'BlockdevAioOptions', 3097 'data': [ 'threads', 'native', 3098 { 'name': 'io_uring', 'if': 'CONFIG_LINUX_IO_URING' } ] } 3099 3100## 3101# @BlockdevCacheOptions: 3102# 3103# Includes cache-related options for block devices 3104# 3105# @direct: enables use of O_DIRECT (bypass the host page cache; 3106# default: false) 3107# 3108# @no-flush: ignore any flush requests for the device (default: false) 3109# 3110# Since: 2.9 3111## 3112{ 'struct': 'BlockdevCacheOptions', 3113 'data': { '*direct': 'bool', 3114 '*no-flush': 'bool' } } 3115 3116## 3117# @BlockdevDriver: 3118# 3119# Drivers that are supported in block device operations. 3120# 3121# @throttle: Since 2.11 3122# 3123# @nvme: Since 2.12 3124# 3125# @copy-on-read: Since 3.0 3126# 3127# @blklogwrites: Since 3.0 3128# 3129# @blkreplay: Since 4.2 3130# 3131# @compress: Since 5.0 3132# 3133# @copy-before-write: Since 6.2 3134# 3135# @snapshot-access: Since 7.0 3136# 3137# Since: 2.9 3138## 3139{ 'enum': 'BlockdevDriver', 3140 'data': [ 'blkdebug', 'blklogwrites', 'blkreplay', 'blkverify', 'bochs', 3141 'cloop', 'compress', 'copy-before-write', 'copy-on-read', 'dmg', 3142 'file', 'snapshot-access', 'ftp', 'ftps', 'gluster', 3143 {'name': 'host_cdrom', 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 3144 {'name': 'host_device', 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 3145 'http', 'https', 3146 { 'name': 'io_uring', 'if': 'CONFIG_BLKIO' }, 3147 'iscsi', 3148 'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme', 3149 { 'name': 'nvme-io_uring', 'if': 'CONFIG_BLKIO' }, 3150 'parallels', 'preallocate', 'qcow', 'qcow2', 'qed', 'quorum', 3151 'raw', 'rbd', 3152 { 'name': 'replication', 'if': 'CONFIG_REPLICATION' }, 3153 'ssh', 'throttle', 'vdi', 'vhdx', 3154 { 'name': 'virtio-blk-vfio-pci', 'if': 'CONFIG_BLKIO' }, 3155 { 'name': 'virtio-blk-vhost-user', 'if': 'CONFIG_BLKIO' }, 3156 { 'name': 'virtio-blk-vhost-vdpa', 'if': 'CONFIG_BLKIO' }, 3157 'vmdk', 'vpc', 'vvfat' ] } 3158 3159## 3160# @BlockdevOptionsFile: 3161# 3162# Driver specific block device options for the file backend. 3163# 3164# @filename: path to the image file 3165# 3166# @pr-manager: the id for the object that will handle persistent 3167# reservations for this device (default: none, forward the 3168# commands via SG_IO; since 2.11) 3169# 3170# @aio: AIO backend (default: threads) (since: 2.8) 3171# 3172# @aio-max-batch: maximum number of requests to batch together into a 3173# single submission in the AIO backend. The smallest value 3174# between this and the aio-max-batch value of the IOThread object 3175# is chosen. 0 means that the AIO backend will handle it 3176# automatically. (default: 0, since 6.2) 3177# 3178# @locking: whether to enable file locking. If set to 'auto', only 3179# enable when Open File Descriptor (OFD) locking API is available 3180# (default: auto, since 2.10) 3181# 3182# @drop-cache: invalidate page cache during live migration. This 3183# prevents stale data on the migration destination with 3184# cache.direct=off. Currently only supported on Linux hosts. 3185# (default: on, since: 4.0) 3186# 3187# @x-check-cache-dropped: whether to check that page cache was dropped 3188# on live migration. May cause noticeable delays if the image 3189# file is large, do not use in production. (default: off) 3190# (since: 3.0) 3191# 3192# Features: 3193# 3194# @dynamic-auto-read-only: If present, enabled auto-read-only means 3195# that the driver will open the image read-only at first, 3196# dynamically reopen the image file read-write when the first 3197# writer is attached to the node and reopen read-only when the 3198# last writer is detached. This allows giving QEMU write 3199# permissions only on demand when an operation actually needs 3200# write access. 3201# 3202# @unstable: Member x-check-cache-dropped is meant for debugging. 3203# 3204# Since: 2.9 3205## 3206{ 'struct': 'BlockdevOptionsFile', 3207 'data': { 'filename': 'str', 3208 '*pr-manager': 'str', 3209 '*locking': 'OnOffAuto', 3210 '*aio': 'BlockdevAioOptions', 3211 '*aio-max-batch': 'int', 3212 '*drop-cache': {'type': 'bool', 3213 'if': 'CONFIG_LINUX'}, 3214 '*x-check-cache-dropped': { 'type': 'bool', 3215 'features': [ 'unstable' ] } }, 3216 'features': [ { 'name': 'dynamic-auto-read-only', 3217 'if': 'CONFIG_POSIX' } ] } 3218 3219## 3220# @BlockdevOptionsNull: 3221# 3222# Driver specific block device options for the null backend. 3223# 3224# @size: size of the device in bytes. 3225# 3226# @latency-ns: emulated latency (in nanoseconds) in processing 3227# requests. Default to zero which completes requests immediately. 3228# (Since 2.4) 3229# 3230# @read-zeroes: if true, reads from the device produce zeroes; if 3231# false, the buffer is left unchanged. 3232# (default: false; since: 4.1) 3233# 3234# Since: 2.9 3235## 3236{ 'struct': 'BlockdevOptionsNull', 3237 'data': { '*size': 'int', '*latency-ns': 'uint64', '*read-zeroes': 'bool' } } 3238 3239## 3240# @BlockdevOptionsNVMe: 3241# 3242# Driver specific block device options for the NVMe backend. 3243# 3244# @device: PCI controller address of the NVMe device in format 3245# hhhh:bb:ss.f (host:bus:slot.function) 3246# 3247# @namespace: namespace number of the device, starting from 1. 3248# 3249# Note that the PCI @device must have been unbound from any host 3250# kernel driver before instructing QEMU to add the blockdev. 3251# 3252# Since: 2.12 3253## 3254{ 'struct': 'BlockdevOptionsNVMe', 3255 'data': { 'device': 'str', 'namespace': 'int' } } 3256 3257## 3258# @BlockdevOptionsVVFAT: 3259# 3260# Driver specific block device options for the vvfat protocol. 3261# 3262# @dir: directory to be exported as FAT image 3263# 3264# @fat-type: FAT type: 12, 16 or 32 3265# 3266# @floppy: whether to export a floppy image (true) or partitioned hard 3267# disk (false; default) 3268# 3269# @label: set the volume label, limited to 11 bytes. FAT16 and FAT32 3270# traditionally have some restrictions on labels, which are 3271# ignored by most operating systems. Defaults to "QEMU VVFAT". 3272# (since 2.4) 3273# 3274# @rw: whether to allow write operations (default: false) 3275# 3276# Since: 2.9 3277## 3278{ 'struct': 'BlockdevOptionsVVFAT', 3279 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool', 3280 '*label': 'str', '*rw': 'bool' } } 3281 3282## 3283# @BlockdevOptionsGenericFormat: 3284# 3285# Driver specific block device options for image format that have no 3286# option besides their data source. 3287# 3288# @file: reference to or definition of the data source block device 3289# 3290# Since: 2.9 3291## 3292{ 'struct': 'BlockdevOptionsGenericFormat', 3293 'data': { 'file': 'BlockdevRef' } } 3294 3295## 3296# @BlockdevOptionsLUKS: 3297# 3298# Driver specific block device options for LUKS. 3299# 3300# @key-secret: the ID of a QCryptoSecret object providing the 3301# decryption key (since 2.6). Mandatory except when doing a 3302# metadata-only probe of the image. 3303# 3304# Since: 2.9 3305## 3306{ 'struct': 'BlockdevOptionsLUKS', 3307 'base': 'BlockdevOptionsGenericFormat', 3308 'data': { '*key-secret': 'str' } } 3309 3310## 3311# @BlockdevOptionsGenericCOWFormat: 3312# 3313# Driver specific block device options for image format that have no 3314# option besides their data source and an optional backing file. 3315# 3316# @backing: reference to or definition of the backing file block 3317# device, null disables the backing file entirely. Defaults to 3318# the backing file stored the image file. 3319# 3320# Since: 2.9 3321## 3322{ 'struct': 'BlockdevOptionsGenericCOWFormat', 3323 'base': 'BlockdevOptionsGenericFormat', 3324 'data': { '*backing': 'BlockdevRefOrNull' } } 3325 3326## 3327# @Qcow2OverlapCheckMode: 3328# 3329# General overlap check modes. 3330# 3331# @none: Do not perform any checks 3332# 3333# @constant: Perform only checks which can be done in constant time 3334# and without reading anything from disk 3335# 3336# @cached: Perform only checks which can be done without reading 3337# anything from disk 3338# 3339# @all: Perform all available overlap checks 3340# 3341# Since: 2.9 3342## 3343{ 'enum': 'Qcow2OverlapCheckMode', 3344 'data': [ 'none', 'constant', 'cached', 'all' ] } 3345 3346## 3347# @Qcow2OverlapCheckFlags: 3348# 3349# Structure of flags for each metadata structure. Setting a field to 3350# 'true' makes qemu guard that structure against unintended 3351# overwriting. The default value is chosen according to the template 3352# given. 3353# 3354# @template: Specifies a template mode which can be adjusted using the 3355# other flags, defaults to 'cached' 3356# 3357# @bitmap-directory: since 3.0 3358# 3359# Since: 2.9 3360## 3361{ 'struct': 'Qcow2OverlapCheckFlags', 3362 'data': { '*template': 'Qcow2OverlapCheckMode', 3363 '*main-header': 'bool', 3364 '*active-l1': 'bool', 3365 '*active-l2': 'bool', 3366 '*refcount-table': 'bool', 3367 '*refcount-block': 'bool', 3368 '*snapshot-table': 'bool', 3369 '*inactive-l1': 'bool', 3370 '*inactive-l2': 'bool', 3371 '*bitmap-directory': 'bool' } } 3372 3373## 3374# @Qcow2OverlapChecks: 3375# 3376# Specifies which metadata structures should be guarded against 3377# unintended overwriting. 3378# 3379# @flags: set of flags for separate specification of each metadata 3380# structure type 3381# 3382# @mode: named mode which chooses a specific set of flags 3383# 3384# Since: 2.9 3385## 3386{ 'alternate': 'Qcow2OverlapChecks', 3387 'data': { 'flags': 'Qcow2OverlapCheckFlags', 3388 'mode': 'Qcow2OverlapCheckMode' } } 3389 3390## 3391# @BlockdevQcowEncryptionFormat: 3392# 3393# @aes: AES-CBC with plain64 initialization vectors 3394# 3395# Since: 2.10 3396## 3397{ 'enum': 'BlockdevQcowEncryptionFormat', 3398 'data': [ 'aes' ] } 3399 3400## 3401# @BlockdevQcowEncryption: 3402# 3403# Since: 2.10 3404## 3405{ 'union': 'BlockdevQcowEncryption', 3406 'base': { 'format': 'BlockdevQcowEncryptionFormat' }, 3407 'discriminator': 'format', 3408 'data': { 'aes': 'QCryptoBlockOptionsQCow' } } 3409 3410## 3411# @BlockdevOptionsQcow: 3412# 3413# Driver specific block device options for qcow. 3414# 3415# @encrypt: Image decryption options. Mandatory for encrypted images, 3416# except when doing a metadata-only probe of the image. 3417# 3418# Since: 2.10 3419## 3420{ 'struct': 'BlockdevOptionsQcow', 3421 'base': 'BlockdevOptionsGenericCOWFormat', 3422 'data': { '*encrypt': 'BlockdevQcowEncryption' } } 3423 3424## 3425# @BlockdevQcow2EncryptionFormat: 3426# 3427# @aes: AES-CBC with plain64 initialization vectors 3428# 3429# Since: 2.10 3430## 3431{ 'enum': 'BlockdevQcow2EncryptionFormat', 3432 'data': [ 'aes', 'luks' ] } 3433 3434## 3435# @BlockdevQcow2Encryption: 3436# 3437# Since: 2.10 3438## 3439{ 'union': 'BlockdevQcow2Encryption', 3440 'base': { 'format': 'BlockdevQcow2EncryptionFormat' }, 3441 'discriminator': 'format', 3442 'data': { 'aes': 'QCryptoBlockOptionsQCow', 3443 'luks': 'QCryptoBlockOptionsLUKS'} } 3444 3445## 3446# @BlockdevOptionsPreallocate: 3447# 3448# Filter driver intended to be inserted between format and protocol 3449# node and do preallocation in protocol node on write. 3450# 3451# @prealloc-align: on preallocation, align file length to this number, 3452# default 1048576 (1M) 3453# 3454# @prealloc-size: how much to preallocate, default 134217728 (128M) 3455# 3456# Since: 6.0 3457## 3458{ 'struct': 'BlockdevOptionsPreallocate', 3459 'base': 'BlockdevOptionsGenericFormat', 3460 'data': { '*prealloc-align': 'int', '*prealloc-size': 'int' } } 3461 3462## 3463# @BlockdevOptionsQcow2: 3464# 3465# Driver specific block device options for qcow2. 3466# 3467# @lazy-refcounts: whether to enable the lazy refcounts feature 3468# (default is taken from the image file) 3469# 3470# @pass-discard-request: whether discard requests to the qcow2 device 3471# should be forwarded to the data source 3472# 3473# @pass-discard-snapshot: whether discard requests for the data source 3474# should be issued when a snapshot operation (e.g. deleting a 3475# snapshot) frees clusters in the qcow2 file 3476# 3477# @pass-discard-other: whether discard requests for the data source 3478# should be issued on other occasions where a cluster gets freed 3479# 3480# @discard-no-unref: when enabled, discards from the guest will not cause 3481# cluster allocations to be relinquished. This prevents qcow2 fragmentation 3482# that would be caused by such discards. Besides potential 3483# performance degradation, such fragmentation can lead to increased 3484# allocation of clusters past the end of the image file, 3485# resulting in image files whose file length can grow much larger 3486# than their guest disk size would suggest. 3487# If image file length is of concern (e.g. when storing qcow2 3488# images directly on block devices), you should consider enabling 3489# this option. (since 8.1) 3490# 3491# @overlap-check: which overlap checks to perform for writes to the 3492# image, defaults to 'cached' (since 2.2) 3493# 3494# @cache-size: the maximum total size of the L2 table and refcount 3495# block caches in bytes (since 2.2) 3496# 3497# @l2-cache-size: the maximum size of the L2 table cache in bytes 3498# (since 2.2) 3499# 3500# @l2-cache-entry-size: the size of each entry in the L2 cache in 3501# bytes. It must be a power of two between 512 and the cluster 3502# size. The default value is the cluster size (since 2.12) 3503# 3504# @refcount-cache-size: the maximum size of the refcount block cache 3505# in bytes (since 2.2) 3506# 3507# @cache-clean-interval: clean unused entries in the L2 and refcount 3508# caches. The interval is in seconds. The default value is 600 3509# on supporting platforms, and 0 on other platforms. 0 disables 3510# this feature. (since 2.5) 3511# 3512# @encrypt: Image decryption options. Mandatory for encrypted images, 3513# except when doing a metadata-only probe of the image. (since 3514# 2.10) 3515# 3516# @data-file: reference to or definition of the external data file. 3517# This may only be specified for images that require an external 3518# data file. If it is not specified for such an image, the data 3519# file name is loaded from the image file. (since 4.0) 3520# 3521# Since: 2.9 3522## 3523{ 'struct': 'BlockdevOptionsQcow2', 3524 'base': 'BlockdevOptionsGenericCOWFormat', 3525 'data': { '*lazy-refcounts': 'bool', 3526 '*pass-discard-request': 'bool', 3527 '*pass-discard-snapshot': 'bool', 3528 '*pass-discard-other': 'bool', 3529 '*discard-no-unref': 'bool', 3530 '*overlap-check': 'Qcow2OverlapChecks', 3531 '*cache-size': 'int', 3532 '*l2-cache-size': 'int', 3533 '*l2-cache-entry-size': 'int', 3534 '*refcount-cache-size': 'int', 3535 '*cache-clean-interval': 'int', 3536 '*encrypt': 'BlockdevQcow2Encryption', 3537 '*data-file': 'BlockdevRef' } } 3538 3539## 3540# @SshHostKeyCheckMode: 3541# 3542# @none: Don't check the host key at all 3543# 3544# @hash: Compare the host key with a given hash 3545# 3546# @known_hosts: Check the host key against the known_hosts file 3547# 3548# Since: 2.12 3549## 3550{ 'enum': 'SshHostKeyCheckMode', 3551 'data': [ 'none', 'hash', 'known_hosts' ] } 3552 3553## 3554# @SshHostKeyCheckHashType: 3555# 3556# @md5: The given hash is an md5 hash 3557# 3558# @sha1: The given hash is an sha1 hash 3559# 3560# @sha256: The given hash is an sha256 hash 3561# 3562# Since: 2.12 3563## 3564{ 'enum': 'SshHostKeyCheckHashType', 3565 'data': [ 'md5', 'sha1', 'sha256' ] } 3566 3567## 3568# @SshHostKeyHash: 3569# 3570# @type: The hash algorithm used for the hash 3571# 3572# @hash: The expected hash value 3573# 3574# Since: 2.12 3575## 3576{ 'struct': 'SshHostKeyHash', 3577 'data': { 'type': 'SshHostKeyCheckHashType', 3578 'hash': 'str' }} 3579 3580## 3581# @SshHostKeyCheck: 3582# 3583# Since: 2.12 3584## 3585{ 'union': 'SshHostKeyCheck', 3586 'base': { 'mode': 'SshHostKeyCheckMode' }, 3587 'discriminator': 'mode', 3588 'data': { 'hash': 'SshHostKeyHash' } } 3589 3590## 3591# @BlockdevOptionsSsh: 3592# 3593# @server: host address 3594# 3595# @path: path to the image on the host 3596# 3597# @user: user as which to connect, defaults to current local user name 3598# 3599# @host-key-check: Defines how and what to check the host key against 3600# (default: known_hosts) 3601# 3602# Since: 2.9 3603## 3604{ 'struct': 'BlockdevOptionsSsh', 3605 'data': { 'server': 'InetSocketAddress', 3606 'path': 'str', 3607 '*user': 'str', 3608 '*host-key-check': 'SshHostKeyCheck' } } 3609 3610## 3611# @BlkdebugEvent: 3612# 3613# Trigger events supported by blkdebug. 3614# 3615# @l1_shrink_write_table: write zeros to the l1 table to shrink image. 3616# (since 2.11) 3617# 3618# @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11) 3619# 3620# @cor_write: a write due to copy-on-read (since 2.11) 3621# 3622# @cluster_alloc_space: an allocation of file space for a cluster 3623# (since 4.1) 3624# 3625# @none: triggers once at creation of the blkdebug node (since 4.1) 3626# 3627# Since: 2.9 3628## 3629{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG', 3630 'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table', 3631 'l1_grow_activate_table', 'l2_load', 'l2_update', 3632 'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write', 3633 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio', 3634 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read', 3635 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update', 3636 'refblock_load', 'refblock_update', 'refblock_update_part', 3637 'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write', 3638 'refblock_alloc_write_blocks', 'refblock_alloc_write_table', 3639 'refblock_alloc_switch_table', 'cluster_alloc', 3640 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os', 3641 'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head', 3642 'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev', 3643 'pwritev_zero', 'pwritev_done', 'empty_image_prepare', 3644 'l1_shrink_write_table', 'l1_shrink_free_l2_clusters', 3645 'cor_write', 'cluster_alloc_space', 'none'] } 3646 3647## 3648# @BlkdebugIOType: 3649# 3650# Kinds of I/O that blkdebug can inject errors in. 3651# 3652# @read: .bdrv_co_preadv() 3653# 3654# @write: .bdrv_co_pwritev() 3655# 3656# @write-zeroes: .bdrv_co_pwrite_zeroes() 3657# 3658# @discard: .bdrv_co_pdiscard() 3659# 3660# @flush: .bdrv_co_flush_to_disk() 3661# 3662# @block-status: .bdrv_co_block_status() 3663# 3664# Since: 4.1 3665## 3666{ 'enum': 'BlkdebugIOType', 'prefix': 'BLKDEBUG_IO_TYPE', 3667 'data': [ 'read', 'write', 'write-zeroes', 'discard', 'flush', 3668 'block-status' ] } 3669 3670## 3671# @BlkdebugInjectErrorOptions: 3672# 3673# Describes a single error injection for blkdebug. 3674# 3675# @event: trigger event 3676# 3677# @state: the state identifier blkdebug needs to be in to actually 3678# trigger the event; defaults to "any" 3679# 3680# @iotype: the type of I/O operations on which this error should be 3681# injected; defaults to "all read, write, write-zeroes, discard, 3682# and flush operations" (since: 4.1) 3683# 3684# @errno: error identifier (errno) to be returned; defaults to EIO 3685# 3686# @sector: specifies the sector index which has to be affected in 3687# order to actually trigger the event; defaults to "any sector" 3688# 3689# @once: disables further events after this one has been triggered; 3690# defaults to false 3691# 3692# @immediately: fail immediately; defaults to false 3693# 3694# Since: 2.9 3695## 3696{ 'struct': 'BlkdebugInjectErrorOptions', 3697 'data': { 'event': 'BlkdebugEvent', 3698 '*state': 'int', 3699 '*iotype': 'BlkdebugIOType', 3700 '*errno': 'int', 3701 '*sector': 'int', 3702 '*once': 'bool', 3703 '*immediately': 'bool' } } 3704 3705## 3706# @BlkdebugSetStateOptions: 3707# 3708# Describes a single state-change event for blkdebug. 3709# 3710# @event: trigger event 3711# 3712# @state: the current state identifier blkdebug needs to be in; 3713# defaults to "any" 3714# 3715# @new_state: the state identifier blkdebug is supposed to assume if 3716# this event is triggered 3717# 3718# Since: 2.9 3719## 3720{ 'struct': 'BlkdebugSetStateOptions', 3721 'data': { 'event': 'BlkdebugEvent', 3722 '*state': 'int', 3723 'new_state': 'int' } } 3724 3725## 3726# @BlockdevOptionsBlkdebug: 3727# 3728# Driver specific block device options for blkdebug. 3729# 3730# @image: underlying raw block device (or image file) 3731# 3732# @config: filename of the configuration file 3733# 3734# @align: required alignment for requests in bytes, must be positive 3735# power of 2, or 0 for default 3736# 3737# @max-transfer: maximum size for I/O transfers in bytes, must be 3738# positive multiple of @align and of the underlying file's request 3739# alignment (but need not be a power of 2), or 0 for default 3740# (since 2.10) 3741# 3742# @opt-write-zero: preferred alignment for write zero requests in 3743# bytes, must be positive multiple of @align and of the underlying 3744# file's request alignment (but need not be a power of 2), or 0 3745# for default (since 2.10) 3746# 3747# @max-write-zero: maximum size for write zero requests in bytes, must 3748# be positive multiple of @align, of @opt-write-zero, and of the 3749# underlying file's request alignment (but need not be a power of 3750# 2), or 0 for default (since 2.10) 3751# 3752# @opt-discard: preferred alignment for discard requests in bytes, 3753# must be positive multiple of @align and of the underlying file's 3754# request alignment (but need not be a power of 2), or 0 for 3755# default (since 2.10) 3756# 3757# @max-discard: maximum size for discard requests in bytes, must be 3758# positive multiple of @align, of @opt-discard, and of the 3759# underlying file's request alignment (but need not be a power of 3760# 2), or 0 for default (since 2.10) 3761# 3762# @inject-error: array of error injection descriptions 3763# 3764# @set-state: array of state-change descriptions 3765# 3766# @take-child-perms: Permissions to take on @image in addition to what 3767# is necessary anyway (which depends on how the blkdebug node is 3768# used). Defaults to none. (since 5.0) 3769# 3770# @unshare-child-perms: Permissions not to share on @image in addition 3771# to what cannot be shared anyway (which depends on how the 3772# blkdebug node is used). Defaults to none. (since 5.0) 3773# 3774# Since: 2.9 3775## 3776{ 'struct': 'BlockdevOptionsBlkdebug', 3777 'data': { 'image': 'BlockdevRef', 3778 '*config': 'str', 3779 '*align': 'int', '*max-transfer': 'int32', 3780 '*opt-write-zero': 'int32', '*max-write-zero': 'int32', 3781 '*opt-discard': 'int32', '*max-discard': 'int32', 3782 '*inject-error': ['BlkdebugInjectErrorOptions'], 3783 '*set-state': ['BlkdebugSetStateOptions'], 3784 '*take-child-perms': ['BlockPermission'], 3785 '*unshare-child-perms': ['BlockPermission'] } } 3786 3787## 3788# @BlockdevOptionsBlklogwrites: 3789# 3790# Driver specific block device options for blklogwrites. 3791# 3792# @file: block device 3793# 3794# @log: block device used to log writes to @file 3795# 3796# @log-sector-size: sector size used in logging writes to @file, 3797# determines granularity of offsets and sizes of writes 3798# (default: 512) 3799# 3800# @log-append: append to an existing log (default: false) 3801# 3802# @log-super-update-interval: interval of write requests after which 3803# the log super block is updated to disk (default: 4096) 3804# 3805# Since: 3.0 3806## 3807{ 'struct': 'BlockdevOptionsBlklogwrites', 3808 'data': { 'file': 'BlockdevRef', 3809 'log': 'BlockdevRef', 3810 '*log-sector-size': 'uint32', 3811 '*log-append': 'bool', 3812 '*log-super-update-interval': 'uint64' } } 3813 3814## 3815# @BlockdevOptionsBlkverify: 3816# 3817# Driver specific block device options for blkverify. 3818# 3819# @test: block device to be tested 3820# 3821# @raw: raw image used for verification 3822# 3823# Since: 2.9 3824## 3825{ 'struct': 'BlockdevOptionsBlkverify', 3826 'data': { 'test': 'BlockdevRef', 3827 'raw': 'BlockdevRef' } } 3828 3829## 3830# @BlockdevOptionsBlkreplay: 3831# 3832# Driver specific block device options for blkreplay. 3833# 3834# @image: disk image which should be controlled with blkreplay 3835# 3836# Since: 4.2 3837## 3838{ 'struct': 'BlockdevOptionsBlkreplay', 3839 'data': { 'image': 'BlockdevRef' } } 3840 3841## 3842# @QuorumReadPattern: 3843# 3844# An enumeration of quorum read patterns. 3845# 3846# @quorum: read all the children and do a quorum vote on reads 3847# 3848# @fifo: read only from the first child that has not failed 3849# 3850# Since: 2.9 3851## 3852{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] } 3853 3854## 3855# @BlockdevOptionsQuorum: 3856# 3857# Driver specific block device options for Quorum 3858# 3859# @blkverify: true if the driver must print content mismatch set to 3860# false by default 3861# 3862# @children: the children block devices to use 3863# 3864# @vote-threshold: the vote limit under which a read will fail 3865# 3866# @rewrite-corrupted: rewrite corrupted data when quorum is reached 3867# (Since 2.1) 3868# 3869# @read-pattern: choose read pattern and set to quorum by default 3870# (Since 2.2) 3871# 3872# Since: 2.9 3873## 3874{ 'struct': 'BlockdevOptionsQuorum', 3875 'data': { '*blkverify': 'bool', 3876 'children': [ 'BlockdevRef' ], 3877 'vote-threshold': 'int', 3878 '*rewrite-corrupted': 'bool', 3879 '*read-pattern': 'QuorumReadPattern' } } 3880 3881## 3882# @BlockdevOptionsGluster: 3883# 3884# Driver specific block device options for Gluster 3885# 3886# @volume: name of gluster volume where VM image resides 3887# 3888# @path: absolute path to image file in gluster volume 3889# 3890# @server: gluster servers description 3891# 3892# @debug: libgfapi log level (default '4' which is Error) (Since 2.8) 3893# 3894# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8) 3895# 3896# Since: 2.9 3897## 3898{ 'struct': 'BlockdevOptionsGluster', 3899 'data': { 'volume': 'str', 3900 'path': 'str', 3901 'server': ['SocketAddress'], 3902 '*debug': 'int', 3903 '*logfile': 'str' } } 3904 3905## 3906# @BlockdevOptionsIoUring: 3907# 3908# Driver specific block device options for the io_uring backend. 3909# 3910# @filename: path to the image file 3911# 3912# Since: 7.2 3913## 3914{ 'struct': 'BlockdevOptionsIoUring', 3915 'data': { 'filename': 'str' }, 3916 'if': 'CONFIG_BLKIO' } 3917 3918## 3919# @BlockdevOptionsNvmeIoUring: 3920# 3921# Driver specific block device options for the nvme-io_uring backend. 3922# 3923# @path: path to the NVMe namespace's character device (e.g. 3924# /dev/ng0n1). 3925# 3926# Since: 7.2 3927## 3928{ 'struct': 'BlockdevOptionsNvmeIoUring', 3929 'data': { 'path': 'str' }, 3930 'if': 'CONFIG_BLKIO' } 3931 3932## 3933# @BlockdevOptionsVirtioBlkVfioPci: 3934# 3935# Driver specific block device options for the virtio-blk-vfio-pci 3936# backend. 3937# 3938# @path: path to the PCI device's sysfs directory (e.g. 3939# /sys/bus/pci/devices/0000:00:01.0). 3940# 3941# Since: 7.2 3942## 3943{ 'struct': 'BlockdevOptionsVirtioBlkVfioPci', 3944 'data': { 'path': 'str' }, 3945 'if': 'CONFIG_BLKIO' } 3946 3947## 3948# @BlockdevOptionsVirtioBlkVhostUser: 3949# 3950# Driver specific block device options for the virtio-blk-vhost-user 3951# backend. 3952# 3953# @path: path to the vhost-user UNIX domain socket. 3954# 3955# Since: 7.2 3956## 3957{ 'struct': 'BlockdevOptionsVirtioBlkVhostUser', 3958 'data': { 'path': 'str' }, 3959 'if': 'CONFIG_BLKIO' } 3960 3961## 3962# @BlockdevOptionsVirtioBlkVhostVdpa: 3963# 3964# Driver specific block device options for the virtio-blk-vhost-vdpa 3965# backend. 3966# 3967# @path: path to the vhost-vdpa character device. 3968# 3969# Features: 3970# @fdset: Member @path supports the special "/dev/fdset/N" path 3971# (since 8.1) 3972# 3973# Since: 7.2 3974## 3975{ 'struct': 'BlockdevOptionsVirtioBlkVhostVdpa', 3976 'data': { 'path': 'str' }, 3977 'features': [ { 'name' :'fdset', 3978 'if': 'CONFIG_BLKIO_VHOST_VDPA_FD' } ], 3979 'if': 'CONFIG_BLKIO' } 3980 3981## 3982# @IscsiTransport: 3983# 3984# An enumeration of libiscsi transport types 3985# 3986# Since: 2.9 3987## 3988{ 'enum': 'IscsiTransport', 3989 'data': [ 'tcp', 'iser' ] } 3990 3991## 3992# @IscsiHeaderDigest: 3993# 3994# An enumeration of header digests supported by libiscsi 3995# 3996# Since: 2.9 3997## 3998{ 'enum': 'IscsiHeaderDigest', 3999 'prefix': 'QAPI_ISCSI_HEADER_DIGEST', 4000 'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] } 4001 4002## 4003# @BlockdevOptionsIscsi: 4004# 4005# @transport: The iscsi transport type 4006# 4007# @portal: The address of the iscsi portal 4008# 4009# @target: The target iqn name 4010# 4011# @lun: LUN to connect to. Defaults to 0. 4012# 4013# @user: User name to log in with. If omitted, no CHAP authentication 4014# is performed. 4015# 4016# @password-secret: The ID of a QCryptoSecret object providing the 4017# password for the login. This option is required if @user is 4018# specified. 4019# 4020# @initiator-name: The iqn name we want to identify to the target as. 4021# If this option is not specified, an initiator name is generated 4022# automatically. 4023# 4024# @header-digest: The desired header digest. Defaults to none-crc32c. 4025# 4026# @timeout: Timeout in seconds after which a request will timeout. 0 4027# means no timeout and is the default. 4028# 4029# Driver specific block device options for iscsi 4030# 4031# Since: 2.9 4032## 4033{ 'struct': 'BlockdevOptionsIscsi', 4034 'data': { 'transport': 'IscsiTransport', 4035 'portal': 'str', 4036 'target': 'str', 4037 '*lun': 'int', 4038 '*user': 'str', 4039 '*password-secret': 'str', 4040 '*initiator-name': 'str', 4041 '*header-digest': 'IscsiHeaderDigest', 4042 '*timeout': 'int' } } 4043 4044## 4045# @RbdAuthMode: 4046# 4047# Since: 3.0 4048## 4049{ 'enum': 'RbdAuthMode', 4050 'data': [ 'cephx', 'none' ] } 4051 4052## 4053# @RbdImageEncryptionFormat: 4054# 4055# @luks-any: Used for opening either luks or luks2 (Since 8.0) 4056# 4057# Since: 6.1 4058## 4059{ 'enum': 'RbdImageEncryptionFormat', 4060 'data': [ 'luks', 'luks2', 'luks-any' ] } 4061 4062## 4063# @RbdEncryptionOptionsLUKSBase: 4064# 4065# @key-secret: ID of a QCryptoSecret object providing a passphrase for 4066# unlocking the encryption 4067# 4068# Since: 6.1 4069## 4070{ 'struct': 'RbdEncryptionOptionsLUKSBase', 4071 'data': { 'key-secret': 'str' } } 4072 4073## 4074# @RbdEncryptionCreateOptionsLUKSBase: 4075# 4076# @cipher-alg: The encryption algorithm 4077# 4078# Since: 6.1 4079## 4080{ 'struct': 'RbdEncryptionCreateOptionsLUKSBase', 4081 'base': 'RbdEncryptionOptionsLUKSBase', 4082 'data': { '*cipher-alg': 'QCryptoCipherAlgorithm' } } 4083 4084## 4085# @RbdEncryptionOptionsLUKS: 4086# 4087# Since: 6.1 4088## 4089{ 'struct': 'RbdEncryptionOptionsLUKS', 4090 'base': 'RbdEncryptionOptionsLUKSBase', 4091 'data': { } } 4092 4093## 4094# @RbdEncryptionOptionsLUKS2: 4095# 4096# Since: 6.1 4097## 4098{ 'struct': 'RbdEncryptionOptionsLUKS2', 4099 'base': 'RbdEncryptionOptionsLUKSBase', 4100 'data': { } } 4101 4102## 4103# @RbdEncryptionOptionsLUKSAny: 4104# 4105# Since: 8.0 4106## 4107{ 'struct': 'RbdEncryptionOptionsLUKSAny', 4108 'base': 'RbdEncryptionOptionsLUKSBase', 4109 'data': { } } 4110 4111## 4112# @RbdEncryptionCreateOptionsLUKS: 4113# 4114# Since: 6.1 4115## 4116{ 'struct': 'RbdEncryptionCreateOptionsLUKS', 4117 'base': 'RbdEncryptionCreateOptionsLUKSBase', 4118 'data': { } } 4119 4120## 4121# @RbdEncryptionCreateOptionsLUKS2: 4122# 4123# Since: 6.1 4124## 4125{ 'struct': 'RbdEncryptionCreateOptionsLUKS2', 4126 'base': 'RbdEncryptionCreateOptionsLUKSBase', 4127 'data': { } } 4128 4129## 4130# @RbdEncryptionOptions: 4131# 4132# @format: Encryption format. 4133# 4134# @parent: Parent image encryption options (for cloned images). Can 4135# be left unspecified if this cloned image is encrypted using the 4136# same format and secret as its parent image (i.e. not explicitly 4137# formatted) or if its parent image is not encrypted. (Since 8.0) 4138# 4139# Since: 6.1 4140## 4141{ 'union': 'RbdEncryptionOptions', 4142 'base': { 'format': 'RbdImageEncryptionFormat', 4143 '*parent': 'RbdEncryptionOptions' }, 4144 'discriminator': 'format', 4145 'data': { 'luks': 'RbdEncryptionOptionsLUKS', 4146 'luks2': 'RbdEncryptionOptionsLUKS2', 4147 'luks-any': 'RbdEncryptionOptionsLUKSAny'} } 4148 4149## 4150# @RbdEncryptionCreateOptions: 4151# 4152# Since: 6.1 4153## 4154{ 'union': 'RbdEncryptionCreateOptions', 4155 'base': { 'format': 'RbdImageEncryptionFormat' }, 4156 'discriminator': 'format', 4157 'data': { 'luks': 'RbdEncryptionCreateOptionsLUKS', 4158 'luks2': 'RbdEncryptionCreateOptionsLUKS2' } } 4159 4160## 4161# @BlockdevOptionsRbd: 4162# 4163# @pool: Ceph pool name. 4164# 4165# @namespace: Rados namespace name in the Ceph pool. (Since 5.0) 4166# 4167# @image: Image name in the Ceph pool. 4168# 4169# @conf: path to Ceph configuration file. Values in the configuration 4170# file will be overridden by options specified via QAPI. 4171# 4172# @snapshot: Ceph snapshot name. 4173# 4174# @encrypt: Image encryption options. (Since 6.1) 4175# 4176# @user: Ceph id name. 4177# 4178# @auth-client-required: Acceptable authentication modes. This maps 4179# to Ceph configuration option "auth_client_required". (Since 4180# 3.0) 4181# 4182# @key-secret: ID of a QCryptoSecret object providing a key for cephx 4183# authentication. This maps to Ceph configuration option "key". 4184# (Since 3.0) 4185# 4186# @server: Monitor host address and port. This maps to the "mon_host" 4187# Ceph option. 4188# 4189# Since: 2.9 4190## 4191{ 'struct': 'BlockdevOptionsRbd', 4192 'data': { 'pool': 'str', 4193 '*namespace': 'str', 4194 'image': 'str', 4195 '*conf': 'str', 4196 '*snapshot': 'str', 4197 '*encrypt': 'RbdEncryptionOptions', 4198 '*user': 'str', 4199 '*auth-client-required': ['RbdAuthMode'], 4200 '*key-secret': 'str', 4201 '*server': ['InetSocketAddressBase'] } } 4202 4203## 4204# @ReplicationMode: 4205# 4206# An enumeration of replication modes. 4207# 4208# @primary: Primary mode, the vm's state will be sent to secondary 4209# QEMU. 4210# 4211# @secondary: Secondary mode, receive the vm's state from primary 4212# QEMU. 4213# 4214# Since: 2.9 4215## 4216{ 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ], 4217 'if': 'CONFIG_REPLICATION' } 4218 4219## 4220# @BlockdevOptionsReplication: 4221# 4222# Driver specific block device options for replication 4223# 4224# @mode: the replication mode 4225# 4226# @top-id: In secondary mode, node name or device ID of the root node 4227# who owns the replication node chain. Must not be given in 4228# primary mode. 4229# 4230# Since: 2.9 4231## 4232{ 'struct': 'BlockdevOptionsReplication', 4233 'base': 'BlockdevOptionsGenericFormat', 4234 'data': { 'mode': 'ReplicationMode', 4235 '*top-id': 'str' }, 4236 'if': 'CONFIG_REPLICATION' } 4237 4238## 4239# @NFSTransport: 4240# 4241# An enumeration of NFS transport types 4242# 4243# @inet: TCP transport 4244# 4245# Since: 2.9 4246## 4247{ 'enum': 'NFSTransport', 4248 'data': [ 'inet' ] } 4249 4250## 4251# @NFSServer: 4252# 4253# Captures the address of the socket 4254# 4255# @type: transport type used for NFS (only TCP supported) 4256# 4257# @host: host address for NFS server 4258# 4259# Since: 2.9 4260## 4261{ 'struct': 'NFSServer', 4262 'data': { 'type': 'NFSTransport', 4263 'host': 'str' } } 4264 4265## 4266# @BlockdevOptionsNfs: 4267# 4268# Driver specific block device option for NFS 4269# 4270# @server: host address 4271# 4272# @path: path of the image on the host 4273# 4274# @user: UID value to use when talking to the server (defaults to 4275# 65534 on Windows and getuid() on unix) 4276# 4277# @group: GID value to use when talking to the server (defaults to 4278# 65534 on Windows and getgid() in unix) 4279# 4280# @tcp-syn-count: number of SYNs during the session establishment 4281# (defaults to libnfs default) 4282# 4283# @readahead-size: set the readahead size in bytes (defaults to libnfs 4284# default) 4285# 4286# @page-cache-size: set the pagecache size in bytes (defaults to 4287# libnfs default) 4288# 4289# @debug: set the NFS debug level (max 2) (defaults to libnfs default) 4290# 4291# Since: 2.9 4292## 4293{ 'struct': 'BlockdevOptionsNfs', 4294 'data': { 'server': 'NFSServer', 4295 'path': 'str', 4296 '*user': 'int', 4297 '*group': 'int', 4298 '*tcp-syn-count': 'int', 4299 '*readahead-size': 'int', 4300 '*page-cache-size': 'int', 4301 '*debug': 'int' } } 4302 4303## 4304# @BlockdevOptionsCurlBase: 4305# 4306# Driver specific block device options shared by all protocols 4307# supported by the curl backend. 4308# 4309# @url: URL of the image file 4310# 4311# @readahead: Size of the read-ahead cache; must be a multiple of 512 4312# (defaults to 256 kB) 4313# 4314# @timeout: Timeout for connections, in seconds (defaults to 5) 4315# 4316# @username: Username for authentication (defaults to none) 4317# 4318# @password-secret: ID of a QCryptoSecret object providing a password 4319# for authentication (defaults to no password) 4320# 4321# @proxy-username: Username for proxy authentication (defaults to 4322# none) 4323# 4324# @proxy-password-secret: ID of a QCryptoSecret object providing a 4325# password for proxy authentication (defaults to no password) 4326# 4327# Since: 2.9 4328## 4329{ 'struct': 'BlockdevOptionsCurlBase', 4330 'data': { 'url': 'str', 4331 '*readahead': 'int', 4332 '*timeout': 'int', 4333 '*username': 'str', 4334 '*password-secret': 'str', 4335 '*proxy-username': 'str', 4336 '*proxy-password-secret': 'str' } } 4337 4338## 4339# @BlockdevOptionsCurlHttp: 4340# 4341# Driver specific block device options for HTTP connections over the 4342# curl backend. URLs must start with "http://". 4343# 4344# @cookie: List of cookies to set; format is "name1=content1; 4345# name2=content2;" as explained by CURLOPT_COOKIE(3). Defaults to 4346# no cookies. 4347# 4348# @cookie-secret: ID of a QCryptoSecret object providing the cookie 4349# data in a secure way. See @cookie for the format. (since 2.10) 4350# 4351# Since: 2.9 4352## 4353{ 'struct': 'BlockdevOptionsCurlHttp', 4354 'base': 'BlockdevOptionsCurlBase', 4355 'data': { '*cookie': 'str', 4356 '*cookie-secret': 'str'} } 4357 4358## 4359# @BlockdevOptionsCurlHttps: 4360# 4361# Driver specific block device options for HTTPS connections over the 4362# curl backend. URLs must start with "https://". 4363# 4364# @cookie: List of cookies to set; format is "name1=content1; 4365# name2=content2;" as explained by CURLOPT_COOKIE(3). Defaults to 4366# no cookies. 4367# 4368# @sslverify: Whether to verify the SSL certificate's validity 4369# (defaults to true) 4370# 4371# @cookie-secret: ID of a QCryptoSecret object providing the cookie 4372# data in a secure way. See @cookie for the format. (since 2.10) 4373# 4374# Since: 2.9 4375## 4376{ 'struct': 'BlockdevOptionsCurlHttps', 4377 'base': 'BlockdevOptionsCurlBase', 4378 'data': { '*cookie': 'str', 4379 '*sslverify': 'bool', 4380 '*cookie-secret': 'str'} } 4381 4382## 4383# @BlockdevOptionsCurlFtp: 4384# 4385# Driver specific block device options for FTP connections over the 4386# curl backend. URLs must start with "ftp://". 4387# 4388# Since: 2.9 4389## 4390{ 'struct': 'BlockdevOptionsCurlFtp', 4391 'base': 'BlockdevOptionsCurlBase', 4392 'data': { } } 4393 4394## 4395# @BlockdevOptionsCurlFtps: 4396# 4397# Driver specific block device options for FTPS connections over the 4398# curl backend. URLs must start with "ftps://". 4399# 4400# @sslverify: Whether to verify the SSL certificate's validity 4401# (defaults to true) 4402# 4403# Since: 2.9 4404## 4405{ 'struct': 'BlockdevOptionsCurlFtps', 4406 'base': 'BlockdevOptionsCurlBase', 4407 'data': { '*sslverify': 'bool' } } 4408 4409## 4410# @BlockdevOptionsNbd: 4411# 4412# Driver specific block device options for NBD. 4413# 4414# @server: NBD server address 4415# 4416# @export: export name 4417# 4418# @tls-creds: TLS credentials ID 4419# 4420# @tls-hostname: TLS hostname override for certificate validation 4421# (Since 7.0) 4422# 4423# @x-dirty-bitmap: A metadata context name such as 4424# "qemu:dirty-bitmap:NAME" or "qemu:allocation-depth" to query in 4425# place of the traditional "base:allocation" block status (see 4426# NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and yes, naming 4427# this option x-context would have made more sense) (since 3.0) 4428# 4429# @reconnect-delay: On an unexpected disconnect, the nbd client tries 4430# to connect again until succeeding or encountering a serious 4431# error. During the first @reconnect-delay seconds, all requests 4432# are paused and will be rerun on a successful reconnect. After 4433# that time, any delayed requests and all future requests before a 4434# successful reconnect will immediately fail. Default 0 (Since 4435# 4.2) 4436# 4437# @open-timeout: In seconds. If zero, the nbd driver tries the 4438# connection only once, and fails to open if the connection fails. 4439# If non-zero, the nbd driver will repeat connection attempts 4440# until successful or until @open-timeout seconds have elapsed. 4441# Default 0 (Since 7.0) 4442# 4443# Features: 4444# 4445# @unstable: Member @x-dirty-bitmap is experimental. 4446# 4447# Since: 2.9 4448## 4449{ 'struct': 'BlockdevOptionsNbd', 4450 'data': { 'server': 'SocketAddress', 4451 '*export': 'str', 4452 '*tls-creds': 'str', 4453 '*tls-hostname': 'str', 4454 '*x-dirty-bitmap': { 'type': 'str', 'features': [ 'unstable' ] }, 4455 '*reconnect-delay': 'uint32', 4456 '*open-timeout': 'uint32' } } 4457 4458## 4459# @BlockdevOptionsRaw: 4460# 4461# Driver specific block device options for the raw driver. 4462# 4463# @offset: position where the block device starts 4464# 4465# @size: the assumed size of the device 4466# 4467# Since: 2.9 4468## 4469{ 'struct': 'BlockdevOptionsRaw', 4470 'base': 'BlockdevOptionsGenericFormat', 4471 'data': { '*offset': 'int', '*size': 'int' } } 4472 4473## 4474# @BlockdevOptionsThrottle: 4475# 4476# Driver specific block device options for the throttle driver 4477# 4478# @throttle-group: the name of the throttle-group object to use. It 4479# must already exist. 4480# 4481# @file: reference to or definition of the data source block device 4482# 4483# Since: 2.11 4484## 4485{ 'struct': 'BlockdevOptionsThrottle', 4486 'data': { 'throttle-group': 'str', 4487 'file' : 'BlockdevRef' 4488 } } 4489 4490## 4491# @BlockdevOptionsCor: 4492# 4493# Driver specific block device options for the copy-on-read driver. 4494# 4495# @bottom: The name of a non-filter node (allocation-bearing layer) 4496# that limits the COR operations in the backing chain (inclusive), 4497# so that no data below this node will be copied by this filter. 4498# If option is absent, the limit is not applied, so that data from 4499# all backing layers may be copied. 4500# 4501# Since: 6.0 4502## 4503{ 'struct': 'BlockdevOptionsCor', 4504 'base': 'BlockdevOptionsGenericFormat', 4505 'data': { '*bottom': 'str' } } 4506 4507## 4508# @OnCbwError: 4509# 4510# An enumeration of possible behaviors for copy-before-write operation 4511# failures. 4512# 4513# @break-guest-write: report the error to the guest. This way, the 4514# guest will not be able to overwrite areas that cannot be backed 4515# up, so the backup process remains valid. 4516# 4517# @break-snapshot: continue guest write. Doing so will make the 4518# provided snapshot state invalid and any backup or export process 4519# based on it will finally fail. 4520# 4521# Since: 7.1 4522## 4523{ 'enum': 'OnCbwError', 4524 'data': [ 'break-guest-write', 'break-snapshot' ] } 4525 4526## 4527# @BlockdevOptionsCbw: 4528# 4529# Driver specific block device options for the copy-before-write 4530# driver, which does so called copy-before-write operations: when data 4531# is written to the filter, the filter first reads corresponding 4532# blocks from its file child and copies them to @target child. After 4533# successfully copying, the write request is propagated to file child. 4534# If copying fails, the original write request is failed too and no 4535# data is written to file child. 4536# 4537# @target: The target for copy-before-write operations. 4538# 4539# @bitmap: If specified, copy-before-write filter will do 4540# copy-before-write operations only for dirty regions of the 4541# bitmap. Bitmap size must be equal to length of file and target 4542# child of the filter. Note also, that bitmap is used only to 4543# initialize internal bitmap of the process, so further 4544# modifications (or removing) of specified bitmap doesn't 4545# influence the filter. (Since 7.0) 4546# 4547# @on-cbw-error: Behavior on failure of copy-before-write operation. 4548# Default is @break-guest-write. (Since 7.1) 4549# 4550# @cbw-timeout: Zero means no limit. Non-zero sets the timeout in 4551# seconds for copy-before-write operation. When a timeout occurs, 4552# the respective copy-before-write operation will fail, and the 4553# @on-cbw-error parameter will decide how this failure is handled. 4554# Default 0. (Since 7.1) 4555# 4556# Since: 6.2 4557## 4558{ 'struct': 'BlockdevOptionsCbw', 4559 'base': 'BlockdevOptionsGenericFormat', 4560 'data': { 'target': 'BlockdevRef', '*bitmap': 'BlockDirtyBitmap', 4561 '*on-cbw-error': 'OnCbwError', '*cbw-timeout': 'uint32' } } 4562 4563## 4564# @BlockdevOptions: 4565# 4566# Options for creating a block device. Many options are available for 4567# all block devices, independent of the block driver: 4568# 4569# @driver: block driver name 4570# 4571# @node-name: the node name of the new node (Since 2.0). This option 4572# is required on the top level of blockdev-add. Valid node names 4573# start with an alphabetic character and may contain only 4574# alphanumeric characters, '-', '.' and '_'. Their maximum length 4575# is 31 characters. 4576# 4577# @discard: discard-related options (default: ignore) 4578# 4579# @cache: cache-related options 4580# 4581# @read-only: whether the block device should be read-only (default: 4582# false). Note that some block drivers support only read-only 4583# access, either generally or in certain configurations. In this 4584# case, the default value does not work and the option must be 4585# specified explicitly. 4586# 4587# @auto-read-only: if true and @read-only is false, QEMU may 4588# automatically decide not to open the image read-write as 4589# requested, but fall back to read-only instead (and switch 4590# between the modes later), e.g. depending on whether the image 4591# file is writable or whether a writing user is attached to the 4592# node (default: false, since 3.1) 4593# 4594# @detect-zeroes: detect and optimize zero writes (Since 2.1) 4595# (default: off) 4596# 4597# @force-share: force share all permission on added nodes. Requires 4598# read-only=true. (Since 2.10) 4599# 4600# Remaining options are determined by the block driver. 4601# 4602# Since: 2.9 4603## 4604{ 'union': 'BlockdevOptions', 4605 'base': { 'driver': 'BlockdevDriver', 4606 '*node-name': 'str', 4607 '*discard': 'BlockdevDiscardOptions', 4608 '*cache': 'BlockdevCacheOptions', 4609 '*read-only': 'bool', 4610 '*auto-read-only': 'bool', 4611 '*force-share': 'bool', 4612 '*detect-zeroes': 'BlockdevDetectZeroesOptions' }, 4613 'discriminator': 'driver', 4614 'data': { 4615 'blkdebug': 'BlockdevOptionsBlkdebug', 4616 'blklogwrites':'BlockdevOptionsBlklogwrites', 4617 'blkverify': 'BlockdevOptionsBlkverify', 4618 'blkreplay': 'BlockdevOptionsBlkreplay', 4619 'bochs': 'BlockdevOptionsGenericFormat', 4620 'cloop': 'BlockdevOptionsGenericFormat', 4621 'compress': 'BlockdevOptionsGenericFormat', 4622 'copy-before-write':'BlockdevOptionsCbw', 4623 'copy-on-read':'BlockdevOptionsCor', 4624 'dmg': 'BlockdevOptionsGenericFormat', 4625 'file': 'BlockdevOptionsFile', 4626 'ftp': 'BlockdevOptionsCurlFtp', 4627 'ftps': 'BlockdevOptionsCurlFtps', 4628 'gluster': 'BlockdevOptionsGluster', 4629 'host_cdrom': { 'type': 'BlockdevOptionsFile', 4630 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 4631 'host_device': { 'type': 'BlockdevOptionsFile', 4632 'if': 'HAVE_HOST_BLOCK_DEVICE' }, 4633 'http': 'BlockdevOptionsCurlHttp', 4634 'https': 'BlockdevOptionsCurlHttps', 4635 'io_uring': { 'type': 'BlockdevOptionsIoUring', 4636 'if': 'CONFIG_BLKIO' }, 4637 'iscsi': 'BlockdevOptionsIscsi', 4638 'luks': 'BlockdevOptionsLUKS', 4639 'nbd': 'BlockdevOptionsNbd', 4640 'nfs': 'BlockdevOptionsNfs', 4641 'null-aio': 'BlockdevOptionsNull', 4642 'null-co': 'BlockdevOptionsNull', 4643 'nvme': 'BlockdevOptionsNVMe', 4644 'nvme-io_uring': { 'type': 'BlockdevOptionsNvmeIoUring', 4645 'if': 'CONFIG_BLKIO' }, 4646 'parallels': 'BlockdevOptionsGenericFormat', 4647 'preallocate':'BlockdevOptionsPreallocate', 4648 'qcow2': 'BlockdevOptionsQcow2', 4649 'qcow': 'BlockdevOptionsQcow', 4650 'qed': 'BlockdevOptionsGenericCOWFormat', 4651 'quorum': 'BlockdevOptionsQuorum', 4652 'raw': 'BlockdevOptionsRaw', 4653 'rbd': 'BlockdevOptionsRbd', 4654 'replication': { 'type': 'BlockdevOptionsReplication', 4655 'if': 'CONFIG_REPLICATION' }, 4656 'snapshot-access': 'BlockdevOptionsGenericFormat', 4657 'ssh': 'BlockdevOptionsSsh', 4658 'throttle': 'BlockdevOptionsThrottle', 4659 'vdi': 'BlockdevOptionsGenericFormat', 4660 'vhdx': 'BlockdevOptionsGenericFormat', 4661 'virtio-blk-vfio-pci': 4662 { 'type': 'BlockdevOptionsVirtioBlkVfioPci', 4663 'if': 'CONFIG_BLKIO' }, 4664 'virtio-blk-vhost-user': 4665 { 'type': 'BlockdevOptionsVirtioBlkVhostUser', 4666 'if': 'CONFIG_BLKIO' }, 4667 'virtio-blk-vhost-vdpa': 4668 { 'type': 'BlockdevOptionsVirtioBlkVhostVdpa', 4669 'if': 'CONFIG_BLKIO' }, 4670 'vmdk': 'BlockdevOptionsGenericCOWFormat', 4671 'vpc': 'BlockdevOptionsGenericFormat', 4672 'vvfat': 'BlockdevOptionsVVFAT' 4673 } } 4674 4675## 4676# @BlockdevRef: 4677# 4678# Reference to a block device. 4679# 4680# @definition: defines a new block device inline 4681# 4682# @reference: references the ID of an existing block device 4683# 4684# Since: 2.9 4685## 4686{ 'alternate': 'BlockdevRef', 4687 'data': { 'definition': 'BlockdevOptions', 4688 'reference': 'str' } } 4689 4690## 4691# @BlockdevRefOrNull: 4692# 4693# Reference to a block device. 4694# 4695# @definition: defines a new block device inline 4696# 4697# @reference: references the ID of an existing block device. An empty 4698# string means that no block device should be referenced. 4699# Deprecated; use null instead. 4700# 4701# @null: No block device should be referenced (since 2.10) 4702# 4703# Since: 2.9 4704## 4705{ 'alternate': 'BlockdevRefOrNull', 4706 'data': { 'definition': 'BlockdevOptions', 4707 'reference': 'str', 4708 'null': 'null' } } 4709 4710## 4711# @blockdev-add: 4712# 4713# Creates a new block device. 4714# 4715# Since: 2.9 4716# 4717# Examples: 4718# 4719# -> { "execute": "blockdev-add", 4720# "arguments": { 4721# "driver": "qcow2", 4722# "node-name": "test1", 4723# "file": { 4724# "driver": "file", 4725# "filename": "test.qcow2" 4726# } 4727# } 4728# } 4729# <- { "return": {} } 4730# 4731# -> { "execute": "blockdev-add", 4732# "arguments": { 4733# "driver": "qcow2", 4734# "node-name": "node0", 4735# "discard": "unmap", 4736# "cache": { 4737# "direct": true 4738# }, 4739# "file": { 4740# "driver": "file", 4741# "filename": "/tmp/test.qcow2" 4742# }, 4743# "backing": { 4744# "driver": "raw", 4745# "file": { 4746# "driver": "file", 4747# "filename": "/dev/fdset/4" 4748# } 4749# } 4750# } 4751# } 4752# 4753# <- { "return": {} } 4754## 4755{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true, 4756 'allow-preconfig': true } 4757 4758## 4759# @blockdev-reopen: 4760# 4761# Reopens one or more block devices using the given set of options. 4762# Any option not specified will be reset to its default value 4763# regardless of its previous status. If an option cannot be changed 4764# or a particular driver does not support reopening then the command 4765# will return an error. All devices in the list are reopened in one 4766# transaction, so if one of them fails then the whole transaction is 4767# cancelled. 4768# 4769# The command receives a list of block devices to reopen. For each 4770# one of them, the top-level @node-name option (from BlockdevOptions) 4771# must be specified and is used to select the block device to be 4772# reopened. Other @node-name options must be either omitted or set to 4773# the current name of the appropriate node. This command won't change 4774# any node name and any attempt to do it will result in an error. 4775# 4776# In the case of options that refer to child nodes, the behavior of 4777# this command depends on the value: 4778# 4779# 1) A set of options (BlockdevOptions): the child is reopened with 4780# the specified set of options. 4781# 4782# 2) A reference to the current child: the child is reopened using 4783# its existing set of options. 4784# 4785# 3) A reference to a different node: the current child is replaced 4786# with the specified one. 4787# 4788# 4) NULL: the current child (if any) is detached. 4789# 4790# Options (1) and (2) are supported in all cases. Option (3) is 4791# supported for @file and @backing, and option (4) for @backing only. 4792# 4793# Unlike with blockdev-add, the @backing option must always be present 4794# unless the node being reopened does not have a backing file and its 4795# image does not have a default backing file name as part of its 4796# metadata. 4797# 4798# Since: 6.1 4799## 4800{ 'command': 'blockdev-reopen', 4801 'data': { 'options': ['BlockdevOptions'] }, 4802 'allow-preconfig': true } 4803 4804## 4805# @blockdev-del: 4806# 4807# Deletes a block device that has been added using blockdev-add. The 4808# command will fail if the node is attached to a device or is 4809# otherwise being used. 4810# 4811# @node-name: Name of the graph node to delete. 4812# 4813# Since: 2.9 4814# 4815# Example: 4816# 4817# -> { "execute": "blockdev-add", 4818# "arguments": { 4819# "driver": "qcow2", 4820# "node-name": "node0", 4821# "file": { 4822# "driver": "file", 4823# "filename": "test.qcow2" 4824# } 4825# } 4826# } 4827# <- { "return": {} } 4828# 4829# -> { "execute": "blockdev-del", 4830# "arguments": { "node-name": "node0" } 4831# } 4832# <- { "return": {} } 4833## 4834{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' }, 4835 'allow-preconfig': true } 4836 4837## 4838# @BlockdevCreateOptionsFile: 4839# 4840# Driver specific image creation options for file. 4841# 4842# @filename: Filename for the new image file 4843# 4844# @size: Size of the virtual disk in bytes 4845# 4846# @preallocation: Preallocation mode for the new image (default: off; 4847# allowed values: off, falloc (if CONFIG_POSIX_FALLOCATE), full 4848# (if CONFIG_POSIX)) 4849# 4850# @nocow: Turn off copy-on-write (valid only on btrfs; default: off) 4851# 4852# @extent-size-hint: Extent size hint to add to the image file; 0 for 4853# not adding an extent size hint (default: 1 MB, since 5.1) 4854# 4855# Since: 2.12 4856## 4857{ 'struct': 'BlockdevCreateOptionsFile', 4858 'data': { 'filename': 'str', 4859 'size': 'size', 4860 '*preallocation': 'PreallocMode', 4861 '*nocow': 'bool', 4862 '*extent-size-hint': 'size'} } 4863 4864## 4865# @BlockdevCreateOptionsGluster: 4866# 4867# Driver specific image creation options for gluster. 4868# 4869# @location: Where to store the new image file 4870# 4871# @size: Size of the virtual disk in bytes 4872# 4873# @preallocation: Preallocation mode for the new image (default: off; 4874# allowed values: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), 4875# full (if CONFIG_GLUSTERFS_ZEROFILL)) 4876# 4877# Since: 2.12 4878## 4879{ 'struct': 'BlockdevCreateOptionsGluster', 4880 'data': { 'location': 'BlockdevOptionsGluster', 4881 'size': 'size', 4882 '*preallocation': 'PreallocMode' } } 4883 4884## 4885# @BlockdevCreateOptionsLUKS: 4886# 4887# Driver specific image creation options for LUKS. 4888# 4889# @file: Node to create the image format on 4890# 4891# @size: Size of the virtual disk in bytes 4892# 4893# @preallocation: Preallocation mode for the new image (since: 4.2) 4894# (default: off; allowed values: off, metadata, falloc, full) 4895# 4896# Since: 2.12 4897## 4898{ 'struct': 'BlockdevCreateOptionsLUKS', 4899 'base': 'QCryptoBlockCreateOptionsLUKS', 4900 'data': { 'file': 'BlockdevRef', 4901 'size': 'size', 4902 '*preallocation': 'PreallocMode' } } 4903 4904## 4905# @BlockdevCreateOptionsNfs: 4906# 4907# Driver specific image creation options for NFS. 4908# 4909# @location: Where to store the new image file 4910# 4911# @size: Size of the virtual disk in bytes 4912# 4913# Since: 2.12 4914## 4915{ 'struct': 'BlockdevCreateOptionsNfs', 4916 'data': { 'location': 'BlockdevOptionsNfs', 4917 'size': 'size' } } 4918 4919## 4920# @BlockdevCreateOptionsParallels: 4921# 4922# Driver specific image creation options for parallels. 4923# 4924# @file: Node to create the image format on 4925# 4926# @size: Size of the virtual disk in bytes 4927# 4928# @cluster-size: Cluster size in bytes (default: 1 MB) 4929# 4930# Since: 2.12 4931## 4932{ 'struct': 'BlockdevCreateOptionsParallels', 4933 'data': { 'file': 'BlockdevRef', 4934 'size': 'size', 4935 '*cluster-size': 'size' } } 4936 4937## 4938# @BlockdevCreateOptionsQcow: 4939# 4940# Driver specific image creation options for qcow. 4941# 4942# @file: Node to create the image format on 4943# 4944# @size: Size of the virtual disk in bytes 4945# 4946# @backing-file: File name of the backing file if a backing file 4947# should be used 4948# 4949# @encrypt: Encryption options if the image should be encrypted 4950# 4951# Since: 2.12 4952## 4953{ 'struct': 'BlockdevCreateOptionsQcow', 4954 'data': { 'file': 'BlockdevRef', 4955 'size': 'size', 4956 '*backing-file': 'str', 4957 '*encrypt': 'QCryptoBlockCreateOptions' } } 4958 4959## 4960# @BlockdevQcow2Version: 4961# 4962# @v2: The original QCOW2 format as introduced in qemu 0.10 (version 4963# 2) 4964# 4965# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) 4966# 4967# Since: 2.12 4968## 4969{ 'enum': 'BlockdevQcow2Version', 4970 'data': [ 'v2', 'v3' ] } 4971 4972## 4973# @Qcow2CompressionType: 4974# 4975# Compression type used in qcow2 image file 4976# 4977# @zlib: zlib compression, see <http://zlib.net/> 4978# 4979# @zstd: zstd compression, see <http://github.com/facebook/zstd> 4980# 4981# Since: 5.1 4982## 4983{ 'enum': 'Qcow2CompressionType', 4984 'data': [ 'zlib', { 'name': 'zstd', 'if': 'CONFIG_ZSTD' } ] } 4985 4986## 4987# @BlockdevCreateOptionsQcow2: 4988# 4989# Driver specific image creation options for qcow2. 4990# 4991# @file: Node to create the image format on 4992# 4993# @data-file: Node to use as an external data file in which all guest 4994# data is stored so that only metadata remains in the qcow2 file 4995# (since: 4.0) 4996# 4997# @data-file-raw: True if the external data file must stay valid as a 4998# standalone (read-only) raw image without looking at qcow2 4999# metadata (default: false; since: 4.0) 5000# 5001# @extended-l2: True to make the image have extended L2 entries 5002# (default: false; since 5.2) 5003# 5004# @size: Size of the virtual disk in bytes 5005# 5006# @version: Compatibility level (default: v3) 5007# 5008# @backing-file: File name of the backing file if a backing file 5009# should be used 5010# 5011# @backing-fmt: Name of the block driver to use for the backing file 5012# 5013# @encrypt: Encryption options if the image should be encrypted 5014# 5015# @cluster-size: qcow2 cluster size in bytes (default: 65536) 5016# 5017# @preallocation: Preallocation mode for the new image (default: off; 5018# allowed values: off, falloc, full, metadata) 5019# 5020# @lazy-refcounts: True if refcounts may be updated lazily 5021# (default: off) 5022# 5023# @refcount-bits: Width of reference counts in bits (default: 16) 5024# 5025# @compression-type: The image cluster compression method 5026# (default: zlib, since 5.1) 5027# 5028# Since: 2.12 5029## 5030{ 'struct': 'BlockdevCreateOptionsQcow2', 5031 'data': { 'file': 'BlockdevRef', 5032 '*data-file': 'BlockdevRef', 5033 '*data-file-raw': 'bool', 5034 '*extended-l2': 'bool', 5035 'size': 'size', 5036 '*version': 'BlockdevQcow2Version', 5037 '*backing-file': 'str', 5038 '*backing-fmt': 'BlockdevDriver', 5039 '*encrypt': 'QCryptoBlockCreateOptions', 5040 '*cluster-size': 'size', 5041 '*preallocation': 'PreallocMode', 5042 '*lazy-refcounts': 'bool', 5043 '*refcount-bits': 'int', 5044 '*compression-type':'Qcow2CompressionType' } } 5045 5046## 5047# @BlockdevCreateOptionsQed: 5048# 5049# Driver specific image creation options for qed. 5050# 5051# @file: Node to create the image format on 5052# 5053# @size: Size of the virtual disk in bytes 5054# 5055# @backing-file: File name of the backing file if a backing file 5056# should be used 5057# 5058# @backing-fmt: Name of the block driver to use for the backing file 5059# 5060# @cluster-size: Cluster size in bytes (default: 65536) 5061# 5062# @table-size: L1/L2 table size (in clusters) 5063# 5064# Since: 2.12 5065## 5066{ 'struct': 'BlockdevCreateOptionsQed', 5067 'data': { 'file': 'BlockdevRef', 5068 'size': 'size', 5069 '*backing-file': 'str', 5070 '*backing-fmt': 'BlockdevDriver', 5071 '*cluster-size': 'size', 5072 '*table-size': 'int' } } 5073 5074## 5075# @BlockdevCreateOptionsRbd: 5076# 5077# Driver specific image creation options for rbd/Ceph. 5078# 5079# @location: Where to store the new image file. This location cannot 5080# point to a snapshot. 5081# 5082# @size: Size of the virtual disk in bytes 5083# 5084# @cluster-size: RBD object size 5085# 5086# @encrypt: Image encryption options. (Since 6.1) 5087# 5088# Since: 2.12 5089## 5090{ 'struct': 'BlockdevCreateOptionsRbd', 5091 'data': { 'location': 'BlockdevOptionsRbd', 5092 'size': 'size', 5093 '*cluster-size' : 'size', 5094 '*encrypt' : 'RbdEncryptionCreateOptions' } } 5095 5096## 5097# @BlockdevVmdkSubformat: 5098# 5099# Subformat options for VMDK images 5100# 5101# @monolithicSparse: Single file image with sparse cluster allocation 5102# 5103# @monolithicFlat: Single flat data image and a descriptor file 5104# 5105# @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA) 5106# sparse extent files, in addition to a descriptor file 5107# 5108# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat 5109# extent files, in addition to a descriptor file 5110# 5111# @streamOptimized: Single file image sparse cluster allocation, 5112# optimized for streaming over network. 5113# 5114# Since: 4.0 5115## 5116{ 'enum': 'BlockdevVmdkSubformat', 5117 'data': [ 'monolithicSparse', 'monolithicFlat', 'twoGbMaxExtentSparse', 5118 'twoGbMaxExtentFlat', 'streamOptimized'] } 5119 5120## 5121# @BlockdevVmdkAdapterType: 5122# 5123# Adapter type info for VMDK images 5124# 5125# Since: 4.0 5126## 5127{ 'enum': 'BlockdevVmdkAdapterType', 5128 'data': [ 'ide', 'buslogic', 'lsilogic', 'legacyESX'] } 5129 5130## 5131# @BlockdevCreateOptionsVmdk: 5132# 5133# Driver specific image creation options for VMDK. 5134# 5135# @file: Where to store the new image file. This refers to the image 5136# file for monolithcSparse and streamOptimized format, or the 5137# descriptor file for other formats. 5138# 5139# @size: Size of the virtual disk in bytes 5140# 5141# @extents: Where to store the data extents. Required for 5142# monolithcFlat, twoGbMaxExtentSparse and twoGbMaxExtentFlat 5143# formats. For monolithicFlat, only one entry is required; for 5144# twoGbMaxExtent* formats, the number of entries required is 5145# calculated as extent_number = virtual_size / 2GB. Providing more 5146# extents than will be used is an error. 5147# 5148# @subformat: The subformat of the VMDK image. Default: 5149# "monolithicSparse". 5150# 5151# @backing-file: The path of backing file. Default: no backing file 5152# is used. 5153# 5154# @adapter-type: The adapter type used to fill in the descriptor. 5155# Default: ide. 5156# 5157# @hwversion: Hardware version. The meaningful options are "4" or 5158# "6". Default: "4". 5159# 5160# @toolsversion: VMware guest tools version. Default: "2147483647" 5161# (Since 6.2) 5162# 5163# @zeroed-grain: Whether to enable zeroed-grain feature for sparse 5164# subformats. Default: false. 5165# 5166# Since: 4.0 5167## 5168{ 'struct': 'BlockdevCreateOptionsVmdk', 5169 'data': { 'file': 'BlockdevRef', 5170 'size': 'size', 5171 '*extents': ['BlockdevRef'], 5172 '*subformat': 'BlockdevVmdkSubformat', 5173 '*backing-file': 'str', 5174 '*adapter-type': 'BlockdevVmdkAdapterType', 5175 '*hwversion': 'str', 5176 '*toolsversion': 'str', 5177 '*zeroed-grain': 'bool' } } 5178 5179## 5180# @BlockdevCreateOptionsSsh: 5181# 5182# Driver specific image creation options for SSH. 5183# 5184# @location: Where to store the new image file 5185# 5186# @size: Size of the virtual disk in bytes 5187# 5188# Since: 2.12 5189## 5190{ 'struct': 'BlockdevCreateOptionsSsh', 5191 'data': { 'location': 'BlockdevOptionsSsh', 5192 'size': 'size' } } 5193 5194## 5195# @BlockdevCreateOptionsVdi: 5196# 5197# Driver specific image creation options for VDI. 5198# 5199# @file: Node to create the image format on 5200# 5201# @size: Size of the virtual disk in bytes 5202# 5203# @preallocation: Preallocation mode for the new image (default: off; 5204# allowed values: off, metadata) 5205# 5206# Since: 2.12 5207## 5208{ 'struct': 'BlockdevCreateOptionsVdi', 5209 'data': { 'file': 'BlockdevRef', 5210 'size': 'size', 5211 '*preallocation': 'PreallocMode' } } 5212 5213## 5214# @BlockdevVhdxSubformat: 5215# 5216# @dynamic: Growing image file 5217# 5218# @fixed: Preallocated fixed-size image file 5219# 5220# Since: 2.12 5221## 5222{ 'enum': 'BlockdevVhdxSubformat', 5223 'data': [ 'dynamic', 'fixed' ] } 5224 5225## 5226# @BlockdevCreateOptionsVhdx: 5227# 5228# Driver specific image creation options for vhdx. 5229# 5230# @file: Node to create the image format on 5231# 5232# @size: Size of the virtual disk in bytes 5233# 5234# @log-size: Log size in bytes, must be a multiple of 1 MB (default: 1 5235# MB) 5236# 5237# @block-size: Block size in bytes, must be a multiple of 1 MB and not 5238# larger than 256 MB (default: automatically choose a block size 5239# depending on the image size) 5240# 5241# @subformat: vhdx subformat (default: dynamic) 5242# 5243# @block-state-zero: Force use of payload blocks of type 5244# 'ZERO'. Non-standard, but default. Do not set to 'off' when 5245# using 'qemu-img convert' with subformat=dynamic. 5246# 5247# Since: 2.12 5248## 5249{ 'struct': 'BlockdevCreateOptionsVhdx', 5250 'data': { 'file': 'BlockdevRef', 5251 'size': 'size', 5252 '*log-size': 'size', 5253 '*block-size': 'size', 5254 '*subformat': 'BlockdevVhdxSubformat', 5255 '*block-state-zero': 'bool' } } 5256 5257## 5258# @BlockdevVpcSubformat: 5259# 5260# @dynamic: Growing image file 5261# 5262# @fixed: Preallocated fixed-size image file 5263# 5264# Since: 2.12 5265## 5266{ 'enum': 'BlockdevVpcSubformat', 5267 'data': [ 'dynamic', 'fixed' ] } 5268 5269## 5270# @BlockdevCreateOptionsVpc: 5271# 5272# Driver specific image creation options for vpc (VHD). 5273# 5274# @file: Node to create the image format on 5275# 5276# @size: Size of the virtual disk in bytes 5277# 5278# @subformat: vhdx subformat (default: dynamic) 5279# 5280# @force-size: Force use of the exact byte size instead of rounding to 5281# the next size that can be represented in CHS geometry 5282# (default: false) 5283# 5284# Since: 2.12 5285## 5286{ 'struct': 'BlockdevCreateOptionsVpc', 5287 'data': { 'file': 'BlockdevRef', 5288 'size': 'size', 5289 '*subformat': 'BlockdevVpcSubformat', 5290 '*force-size': 'bool' } } 5291 5292## 5293# @BlockdevCreateOptions: 5294# 5295# Options for creating an image format on a given node. 5296# 5297# @driver: block driver to create the image format 5298# 5299# Since: 2.12 5300## 5301{ 'union': 'BlockdevCreateOptions', 5302 'base': { 5303 'driver': 'BlockdevDriver' }, 5304 'discriminator': 'driver', 5305 'data': { 5306 'file': 'BlockdevCreateOptionsFile', 5307 'gluster': 'BlockdevCreateOptionsGluster', 5308 'luks': 'BlockdevCreateOptionsLUKS', 5309 'nfs': 'BlockdevCreateOptionsNfs', 5310 'parallels': 'BlockdevCreateOptionsParallels', 5311 'qcow': 'BlockdevCreateOptionsQcow', 5312 'qcow2': 'BlockdevCreateOptionsQcow2', 5313 'qed': 'BlockdevCreateOptionsQed', 5314 'rbd': 'BlockdevCreateOptionsRbd', 5315 'ssh': 'BlockdevCreateOptionsSsh', 5316 'vdi': 'BlockdevCreateOptionsVdi', 5317 'vhdx': 'BlockdevCreateOptionsVhdx', 5318 'vmdk': 'BlockdevCreateOptionsVmdk', 5319 'vpc': 'BlockdevCreateOptionsVpc' 5320 } } 5321 5322## 5323# @blockdev-create: 5324# 5325# Starts a job to create an image format on a given node. The job is 5326# automatically finalized, but a manual job-dismiss is required. 5327# 5328# @job-id: Identifier for the newly created job. 5329# 5330# @options: Options for the image creation. 5331# 5332# Since: 3.0 5333## 5334{ 'command': 'blockdev-create', 5335 'data': { 'job-id': 'str', 5336 'options': 'BlockdevCreateOptions' }, 5337 'allow-preconfig': true } 5338 5339## 5340# @BlockdevAmendOptionsLUKS: 5341# 5342# Driver specific image amend options for LUKS. 5343# 5344# Since: 5.1 5345## 5346{ 'struct': 'BlockdevAmendOptionsLUKS', 5347 'base': 'QCryptoBlockAmendOptionsLUKS', 5348 'data': { } 5349} 5350 5351## 5352# @BlockdevAmendOptionsQcow2: 5353# 5354# Driver specific image amend options for qcow2. For now, only 5355# encryption options can be amended 5356# 5357# @encrypt: Encryption options to be amended 5358# 5359# Since: 5.1 5360## 5361{ 'struct': 'BlockdevAmendOptionsQcow2', 5362 'data': { '*encrypt': 'QCryptoBlockAmendOptions' } } 5363 5364## 5365# @BlockdevAmendOptions: 5366# 5367# Options for amending an image format 5368# 5369# @driver: Block driver of the node to amend. 5370# 5371# Since: 5.1 5372## 5373{ 'union': 'BlockdevAmendOptions', 5374 'base': { 5375 'driver': 'BlockdevDriver' }, 5376 'discriminator': 'driver', 5377 'data': { 5378 'luks': 'BlockdevAmendOptionsLUKS', 5379 'qcow2': 'BlockdevAmendOptionsQcow2' } } 5380 5381## 5382# @x-blockdev-amend: 5383# 5384# Starts a job to amend format specific options of an existing open 5385# block device The job is automatically finalized, but a manual 5386# job-dismiss is required. 5387# 5388# @job-id: Identifier for the newly created job. 5389# 5390# @node-name: Name of the block node to work on 5391# 5392# @options: Options (driver specific) 5393# 5394# @force: Allow unsafe operations, format specific For luks that 5395# allows erase of the last active keyslot (permanent loss of 5396# data), and replacement of an active keyslot (possible loss of 5397# data if IO error happens) 5398# 5399# Features: 5400# 5401# @unstable: This command is experimental. 5402# 5403# Since: 5.1 5404## 5405{ 'command': 'x-blockdev-amend', 5406 'data': { 'job-id': 'str', 5407 'node-name': 'str', 5408 'options': 'BlockdevAmendOptions', 5409 '*force': 'bool' }, 5410 'features': [ 'unstable' ], 5411 'allow-preconfig': true } 5412 5413## 5414# @BlockErrorAction: 5415# 5416# An enumeration of action that has been taken when a DISK I/O occurs 5417# 5418# @ignore: error has been ignored 5419# 5420# @report: error has been reported to the device 5421# 5422# @stop: error caused VM to be stopped 5423# 5424# Since: 2.1 5425## 5426{ 'enum': 'BlockErrorAction', 5427 'data': [ 'ignore', 'report', 'stop' ] } 5428 5429## 5430# @BLOCK_IMAGE_CORRUPTED: 5431# 5432# Emitted when a disk image is being marked corrupt. The image can be 5433# identified by its device or node name. The 'device' field is always 5434# present for compatibility reasons, but it can be empty ("") if the 5435# image does not have a device name associated. 5436# 5437# @device: device name. This is always present for compatibility 5438# reasons, but it can be empty ("") if the image does not have a 5439# device name associated. 5440# 5441# @node-name: node name (Since: 2.4) 5442# 5443# @msg: informative message for human consumption, such as the kind of 5444# corruption being detected. It should not be parsed by machine 5445# as it is not guaranteed to be stable 5446# 5447# @offset: if the corruption resulted from an image access, this is 5448# the host's access offset into the image 5449# 5450# @size: if the corruption resulted from an image access, this is the 5451# access size 5452# 5453# @fatal: if set, the image is marked corrupt and therefore unusable 5454# after this event and must be repaired (Since 2.2; before, every 5455# BLOCK_IMAGE_CORRUPTED event was fatal) 5456# 5457# Note: If action is "stop", a STOP event will eventually follow the 5458# BLOCK_IO_ERROR event. 5459# 5460# Example: 5461# 5462# <- { "event": "BLOCK_IMAGE_CORRUPTED", 5463# "data": { "device": "", "node-name": "drive", "fatal": false, 5464# "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" }, 5465# "timestamp": { "seconds": 1648243240, "microseconds": 906060 } } 5466# 5467# Since: 1.7 5468## 5469{ 'event': 'BLOCK_IMAGE_CORRUPTED', 5470 'data': { 'device' : 'str', 5471 '*node-name' : 'str', 5472 'msg' : 'str', 5473 '*offset' : 'int', 5474 '*size' : 'int', 5475 'fatal' : 'bool' } } 5476 5477## 5478# @BLOCK_IO_ERROR: 5479# 5480# Emitted when a disk I/O error occurs 5481# 5482# @device: device name. This is always present for compatibility 5483# reasons, but it can be empty ("") if the image does not have a 5484# device name associated. 5485# 5486# @node-name: node name. Note that errors may be reported for the 5487# root node that is directly attached to a guest device rather 5488# than for the node where the error occurred. The node name is 5489# not present if the drive is empty. (Since: 2.8) 5490# 5491# @operation: I/O operation 5492# 5493# @action: action that has been taken 5494# 5495# @nospace: true if I/O error was caused due to a no-space condition. 5496# This key is only present if query-block's io-status is present, 5497# please see query-block documentation for more information 5498# (since: 2.2) 5499# 5500# @reason: human readable string describing the error cause. (This 5501# field is a debugging aid for humans, it should not be parsed by 5502# applications) (since: 2.2) 5503# 5504# Note: If action is "stop", a STOP event will eventually follow the 5505# BLOCK_IO_ERROR event 5506# 5507# Since: 0.13 5508# 5509# Example: 5510# 5511# <- { "event": "BLOCK_IO_ERROR", 5512# "data": { "device": "ide0-hd1", 5513# "node-name": "#block212", 5514# "operation": "write", 5515# "action": "stop", 5516# "reason": "No space left on device" }, 5517# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5518## 5519{ 'event': 'BLOCK_IO_ERROR', 5520 'data': { 'device': 'str', '*node-name': 'str', 5521 'operation': 'IoOperationType', 5522 'action': 'BlockErrorAction', '*nospace': 'bool', 5523 'reason': 'str' } } 5524 5525## 5526# @BLOCK_JOB_COMPLETED: 5527# 5528# Emitted when a block job has completed 5529# 5530# @type: job type 5531# 5532# @device: The job identifier. Originally the device name but other 5533# values are allowed since QEMU 2.7 5534# 5535# @len: maximum progress value 5536# 5537# @offset: current progress value. On success this is equal to len. 5538# On failure this is less than len 5539# 5540# @speed: rate limit, bytes per second 5541# 5542# @error: error message. Only present on failure. This field 5543# contains a human-readable error message. There are no semantics 5544# other than that streaming has failed and clients should not try 5545# to interpret the error string 5546# 5547# Since: 1.1 5548# 5549# Example: 5550# 5551# <- { "event": "BLOCK_JOB_COMPLETED", 5552# "data": { "type": "stream", "device": "virtio-disk0", 5553# "len": 10737418240, "offset": 10737418240, 5554# "speed": 0 }, 5555# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 5556## 5557{ 'event': 'BLOCK_JOB_COMPLETED', 5558 'data': { 'type' : 'JobType', 5559 'device': 'str', 5560 'len' : 'int', 5561 'offset': 'int', 5562 'speed' : 'int', 5563 '*error': 'str' } } 5564 5565## 5566# @BLOCK_JOB_CANCELLED: 5567# 5568# Emitted when a block job has been cancelled 5569# 5570# @type: job type 5571# 5572# @device: The job identifier. Originally the device name but other 5573# values are allowed since QEMU 2.7 5574# 5575# @len: maximum progress value 5576# 5577# @offset: current progress value. On success this is equal to len. 5578# On failure this is less than len 5579# 5580# @speed: rate limit, bytes per second 5581# 5582# Since: 1.1 5583# 5584# Example: 5585# 5586# <- { "event": "BLOCK_JOB_CANCELLED", 5587# "data": { "type": "stream", "device": "virtio-disk0", 5588# "len": 10737418240, "offset": 134217728, 5589# "speed": 0 }, 5590# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 5591## 5592{ 'event': 'BLOCK_JOB_CANCELLED', 5593 'data': { 'type' : 'JobType', 5594 'device': 'str', 5595 'len' : 'int', 5596 'offset': 'int', 5597 'speed' : 'int' } } 5598 5599## 5600# @BLOCK_JOB_ERROR: 5601# 5602# Emitted when a block job encounters an error 5603# 5604# @device: The job identifier. Originally the device name but other 5605# values are allowed since QEMU 2.7 5606# 5607# @operation: I/O operation 5608# 5609# @action: action that has been taken 5610# 5611# Since: 1.3 5612# 5613# Example: 5614# 5615# <- { "event": "BLOCK_JOB_ERROR", 5616# "data": { "device": "ide0-hd1", 5617# "operation": "write", 5618# "action": "stop" }, 5619# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5620## 5621{ 'event': 'BLOCK_JOB_ERROR', 5622 'data': { 'device' : 'str', 5623 'operation': 'IoOperationType', 5624 'action' : 'BlockErrorAction' } } 5625 5626## 5627# @BLOCK_JOB_READY: 5628# 5629# Emitted when a block job is ready to complete 5630# 5631# @type: job type 5632# 5633# @device: The job identifier. Originally the device name but other 5634# values are allowed since QEMU 2.7 5635# 5636# @len: maximum progress value 5637# 5638# @offset: current progress value. On success this is equal to len. 5639# On failure this is less than len 5640# 5641# @speed: rate limit, bytes per second 5642# 5643# Note: The "ready to complete" status is always reset by a 5644# @BLOCK_JOB_ERROR event 5645# 5646# Since: 1.3 5647# 5648# Example: 5649# 5650# <- { "event": "BLOCK_JOB_READY", 5651# "data": { "device": "drive0", "type": "mirror", "speed": 0, 5652# "len": 2097152, "offset": 2097152 }, 5653# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5654## 5655{ 'event': 'BLOCK_JOB_READY', 5656 'data': { 'type' : 'JobType', 5657 'device': 'str', 5658 'len' : 'int', 5659 'offset': 'int', 5660 'speed' : 'int' } } 5661 5662## 5663# @BLOCK_JOB_PENDING: 5664# 5665# Emitted when a block job is awaiting explicit authorization to 5666# finalize graph changes via @block-job-finalize. If this job is part 5667# of a transaction, it will not emit this event until the transaction 5668# has converged first. 5669# 5670# @type: job type 5671# 5672# @id: The job identifier. 5673# 5674# Since: 2.12 5675# 5676# Example: 5677# 5678# <- { "event": "BLOCK_JOB_PENDING", 5679# "data": { "type": "mirror", "id": "backup_1" }, 5680# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5681## 5682{ 'event': 'BLOCK_JOB_PENDING', 5683 'data': { 'type' : 'JobType', 5684 'id' : 'str' } } 5685 5686## 5687# @PreallocMode: 5688# 5689# Preallocation mode of QEMU image file 5690# 5691# @off: no preallocation 5692# 5693# @metadata: preallocate only for metadata 5694# 5695# @falloc: like @full preallocation but allocate disk space by 5696# posix_fallocate() rather than writing data. 5697# 5698# @full: preallocate all data by writing it to the device to ensure 5699# disk space is really available. This data may or may not be 5700# zero, depending on the image format and storage. @full 5701# preallocation also sets up metadata correctly. 5702# 5703# Since: 2.2 5704## 5705{ 'enum': 'PreallocMode', 5706 'data': [ 'off', 'metadata', 'falloc', 'full' ] } 5707 5708## 5709# @BLOCK_WRITE_THRESHOLD: 5710# 5711# Emitted when writes on block device reaches or exceeds the 5712# configured write threshold. For thin-provisioned devices, this 5713# means the device should be extended to avoid pausing for disk 5714# exhaustion. The event is one shot. Once triggered, it needs to be 5715# re-registered with another block-set-write-threshold command. 5716# 5717# @node-name: graph node name on which the threshold was exceeded. 5718# 5719# @amount-exceeded: amount of data which exceeded the threshold, in 5720# bytes. 5721# 5722# @write-threshold: last configured threshold, in bytes. 5723# 5724# Since: 2.3 5725## 5726{ 'event': 'BLOCK_WRITE_THRESHOLD', 5727 'data': { 'node-name': 'str', 5728 'amount-exceeded': 'uint64', 5729 'write-threshold': 'uint64' } } 5730 5731## 5732# @block-set-write-threshold: 5733# 5734# Change the write threshold for a block drive. An event will be 5735# delivered if a write to this block drive crosses the configured 5736# threshold. The threshold is an offset, thus must be non-negative. 5737# Default is no write threshold. Setting the threshold to zero 5738# disables it. 5739# 5740# This is useful to transparently resize thin-provisioned drives 5741# without the guest OS noticing. 5742# 5743# @node-name: graph node name on which the threshold must be set. 5744# 5745# @write-threshold: configured threshold for the block device, bytes. 5746# Use 0 to disable the threshold. 5747# 5748# Since: 2.3 5749# 5750# Example: 5751# 5752# -> { "execute": "block-set-write-threshold", 5753# "arguments": { "node-name": "mydev", 5754# "write-threshold": 17179869184 } } 5755# <- { "return": {} } 5756## 5757{ 'command': 'block-set-write-threshold', 5758 'data': { 'node-name': 'str', 'write-threshold': 'uint64' }, 5759 'allow-preconfig': true } 5760 5761## 5762# @x-blockdev-change: 5763# 5764# Dynamically reconfigure the block driver state graph. It can be 5765# used to add, remove, insert or replace a graph node. Currently only 5766# the Quorum driver implements this feature to add or remove its 5767# child. This is useful to fix a broken quorum child. 5768# 5769# If @node is specified, it will be inserted under @parent. @child 5770# may not be specified in this case. If both @parent and @child are 5771# specified but @node is not, @child will be detached from @parent. 5772# 5773# @parent: the id or name of the parent node. 5774# 5775# @child: the name of a child under the given parent node. 5776# 5777# @node: the name of the node that will be added. 5778# 5779# Features: 5780# 5781# @unstable: This command is experimental, and its API is not stable. 5782# It does not support all kinds of operations, all kinds of 5783# children, nor all block drivers. 5784# 5785# FIXME Removing children from a quorum node means introducing 5786# gaps in the child indices. This cannot be represented in the 5787# 'children' list of BlockdevOptionsQuorum, as returned by 5788# .bdrv_refresh_filename(). 5789# 5790# Warning: The data in a new quorum child MUST be consistent with 5791# that of the rest of the array. 5792# 5793# Since: 2.7 5794# 5795# Examples: 5796# 5797# 1. Add a new node to a quorum 5798# 5799# -> { "execute": "blockdev-add", 5800# "arguments": { 5801# "driver": "raw", 5802# "node-name": "new_node", 5803# "file": { "driver": "file", 5804# "filename": "test.raw" } } } 5805# <- { "return": {} } 5806# -> { "execute": "x-blockdev-change", 5807# "arguments": { "parent": "disk1", 5808# "node": "new_node" } } 5809# <- { "return": {} } 5810# 5811# 2. Delete a quorum's node 5812# 5813# -> { "execute": "x-blockdev-change", 5814# "arguments": { "parent": "disk1", 5815# "child": "children.1" } } 5816# <- { "return": {} } 5817## 5818{ 'command': 'x-blockdev-change', 5819 'data' : { 'parent': 'str', 5820 '*child': 'str', 5821 '*node': 'str' }, 5822 'features': [ 'unstable' ], 5823 'allow-preconfig': true } 5824 5825## 5826# @x-blockdev-set-iothread: 5827# 5828# Move @node and its children into the @iothread. If @iothread is 5829# null then move @node and its children into the main loop. 5830# 5831# The node must not be attached to a BlockBackend. 5832# 5833# @node-name: the name of the block driver node 5834# 5835# @iothread: the name of the IOThread object or null for the main loop 5836# 5837# @force: true if the node and its children should be moved when a 5838# BlockBackend is already attached 5839# 5840# Features: 5841# 5842# @unstable: This command is experimental and intended for test cases 5843# that need control over IOThreads only. 5844# 5845# Since: 2.12 5846# 5847# Examples: 5848# 5849# 1. Move a node into an IOThread 5850# 5851# -> { "execute": "x-blockdev-set-iothread", 5852# "arguments": { "node-name": "disk1", 5853# "iothread": "iothread0" } } 5854# <- { "return": {} } 5855# 5856# 2. Move a node into the main loop 5857# 5858# -> { "execute": "x-blockdev-set-iothread", 5859# "arguments": { "node-name": "disk1", 5860# "iothread": null } } 5861# <- { "return": {} } 5862## 5863{ 'command': 'x-blockdev-set-iothread', 5864 'data' : { 'node-name': 'str', 5865 'iothread': 'StrOrNull', 5866 '*force': 'bool' }, 5867 'features': [ 'unstable' ], 5868 'allow-preconfig': true } 5869 5870## 5871# @QuorumOpType: 5872# 5873# An enumeration of the quorum operation types 5874# 5875# @read: read operation 5876# 5877# @write: write operation 5878# 5879# @flush: flush operation 5880# 5881# Since: 2.6 5882## 5883{ 'enum': 'QuorumOpType', 5884 'data': [ 'read', 'write', 'flush' ] } 5885 5886## 5887# @QUORUM_FAILURE: 5888# 5889# Emitted by the Quorum block driver if it fails to establish a quorum 5890# 5891# @reference: device name if defined else node name 5892# 5893# @sector-num: number of the first sector of the failed read operation 5894# 5895# @sectors-count: failed read operation sector count 5896# 5897# Note: This event is rate-limited. 5898# 5899# Since: 2.0 5900# 5901# Example: 5902# 5903# <- { "event": "QUORUM_FAILURE", 5904# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, 5905# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } 5906## 5907{ 'event': 'QUORUM_FAILURE', 5908 'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } } 5909 5910## 5911# @QUORUM_REPORT_BAD: 5912# 5913# Emitted to report a corruption of a Quorum file 5914# 5915# @type: quorum operation type (Since 2.6) 5916# 5917# @error: error message. Only present on failure. This field 5918# contains a human-readable error message. There are no semantics 5919# other than that the block layer reported an error and clients 5920# should not try to interpret the error string. 5921# 5922# @node-name: the graph node name of the block driver state 5923# 5924# @sector-num: number of the first sector of the failed read operation 5925# 5926# @sectors-count: failed read operation sector count 5927# 5928# Note: This event is rate-limited. 5929# 5930# Since: 2.0 5931# 5932# Examples: 5933# 5934# 1. Read operation 5935# 5936# <- { "event": "QUORUM_REPORT_BAD", 5937# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, 5938# "type": "read" }, 5939# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } 5940# 5941# 2. Flush operation 5942# 5943# <- { "event": "QUORUM_REPORT_BAD", 5944# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, 5945# "type": "flush", "error": "Broken pipe" }, 5946# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } 5947## 5948{ 'event': 'QUORUM_REPORT_BAD', 5949 'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str', 5950 'sector-num': 'int', 'sectors-count': 'int' } } 5951 5952## 5953# @BlockdevSnapshotInternal: 5954# 5955# @device: the device name or node-name of a root node to generate the 5956# snapshot from 5957# 5958# @name: the name of the internal snapshot to be created 5959# 5960# Notes: In transaction, if @name is empty, or any snapshot matching 5961# @name exists, the operation will fail. Only some image formats 5962# support it, for example, qcow2, and rbd. 5963# 5964# Since: 1.7 5965## 5966{ 'struct': 'BlockdevSnapshotInternal', 5967 'data': { 'device': 'str', 'name': 'str' } } 5968 5969## 5970# @blockdev-snapshot-internal-sync: 5971# 5972# Synchronously take an internal snapshot of a block device, when the 5973# format of the image used supports it. If the name is an empty 5974# string, or a snapshot with name already exists, the operation will 5975# fail. 5976# 5977# For the arguments, see the documentation of 5978# BlockdevSnapshotInternal. 5979# 5980# Returns: 5981# - nothing on success 5982# - If @device is not a valid block device, GenericError 5983# - If any snapshot matching @name exists, or @name is empty, 5984# GenericError 5985# - If the format of the image used does not support it, 5986# GenericError 5987# 5988# Since: 1.7 5989# 5990# Example: 5991# 5992# -> { "execute": "blockdev-snapshot-internal-sync", 5993# "arguments": { "device": "ide-hd0", 5994# "name": "snapshot0" } 5995# } 5996# <- { "return": {} } 5997## 5998{ 'command': 'blockdev-snapshot-internal-sync', 5999 'data': 'BlockdevSnapshotInternal', 6000 'allow-preconfig': true } 6001 6002## 6003# @blockdev-snapshot-delete-internal-sync: 6004# 6005# Synchronously delete an internal snapshot of a block device, when 6006# the format of the image used support it. The snapshot is identified 6007# by name or id or both. One of the name or id is required. Return 6008# SnapshotInfo for the successfully deleted snapshot. 6009# 6010# @device: the device name or node-name of a root node to delete the 6011# snapshot from 6012# 6013# @id: optional the snapshot's ID to be deleted 6014# 6015# @name: optional the snapshot's name to be deleted 6016# 6017# Returns: 6018# - SnapshotInfo on success 6019# - If @device is not a valid block device, GenericError 6020# - If snapshot not found, GenericError 6021# - If the format of the image used does not support it, 6022# GenericError 6023# - If @id and @name are both not specified, GenericError 6024# 6025# Since: 1.7 6026# 6027# Example: 6028# 6029# -> { "execute": "blockdev-snapshot-delete-internal-sync", 6030# "arguments": { "device": "ide-hd0", 6031# "name": "snapshot0" } 6032# } 6033# <- { "return": { 6034# "id": "1", 6035# "name": "snapshot0", 6036# "vm-state-size": 0, 6037# "date-sec": 1000012, 6038# "date-nsec": 10, 6039# "vm-clock-sec": 100, 6040# "vm-clock-nsec": 20, 6041# "icount": 220414 6042# } 6043# } 6044## 6045{ 'command': 'blockdev-snapshot-delete-internal-sync', 6046 'data': { 'device': 'str', '*id': 'str', '*name': 'str'}, 6047 'returns': 'SnapshotInfo', 6048 'allow-preconfig': true } 6049 6050## 6051# @DummyBlockCoreForceArrays: 6052# 6053# Not used by QMP; hack to let us use BlockGraphInfoList internally 6054# 6055# Since: 8.0 6056## 6057{ 'struct': 'DummyBlockCoreForceArrays', 6058 'data': { 'unused-block-graph-info': ['BlockGraphInfo'] } } 6059