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