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# - If "device" does not exist or cannot be determined, DeviceNotFound 1591# 1592# Since: 2.1 1593## 1594{ 'command': 'change-backing-file', 1595 'data': { 'device': 'str', 'image-node-name': 'str', 1596 'backing-file': 'str' } } 1597 1598## 1599# @block-commit: 1600# 1601# Live commit of data from overlay image nodes into backing nodes - i.e., 1602# writes data between 'top' and 'base' into 'base'. 1603# 1604# @job-id: identifier for the newly-created block job. If 1605# omitted, the device name will be used. (Since 2.7) 1606# 1607# @device: the device name or node-name of a root node 1608# 1609# @base-node: The node name of the backing image to write data into. 1610# If not specified, this is the deepest backing image. 1611# (since: 3.1) 1612# 1613# @base: Same as @base-node, except that it is a file name rather than a node 1614# name. This must be the exact filename string that was used to open the 1615# node; other strings, even if addressing the same file, are not 1616# accepted (deprecated, use @base-node instead) 1617# 1618# @top-node: The node name of the backing image within the image chain 1619# which contains the topmost data to be committed down. If 1620# not specified, this is the active layer. (since: 3.1) 1621# 1622# @top: Same as @top-node, except that it is a file name rather than a node 1623# name. This must be the exact filename string that was used to open the 1624# node; other strings, even if addressing the same file, are not 1625# accepted (deprecated, use @base-node instead) 1626# 1627# @backing-file: The backing file string to write into the overlay 1628# image of 'top'. If 'top' is the active layer, 1629# specifying a backing file string is an error. This 1630# filename is not validated. 1631# 1632# If a pathname string is such that it cannot be 1633# resolved by QEMU, that means that subsequent QMP or 1634# HMP commands must use node-names for the image in 1635# question, as filename lookup methods will fail. 1636# 1637# If not specified, QEMU will automatically determine 1638# the backing file string to use, or error out if 1639# there is no obvious choice. Care should be taken 1640# when specifying the string, to specify a valid 1641# filename or protocol. 1642# (Since 2.1) 1643# 1644# If top == base, that is an error. 1645# If top == active, the job will not be completed by itself, 1646# user needs to complete the job with the block-job-complete 1647# command after getting the ready event. (Since 2.0) 1648# 1649# If the base image is smaller than top, then the base image 1650# will be resized to be the same size as top. If top is 1651# smaller than the base image, the base will not be 1652# truncated. If you want the base image size to match the 1653# size of the smaller top, you can safely truncate it 1654# yourself once the commit operation successfully completes. 1655# 1656# @speed: the maximum speed, in bytes per second 1657# 1658# @filter-node-name: the node name that should be assigned to the 1659# filter driver that the commit job inserts into the graph 1660# above @top. If this option is not given, a node name is 1661# autogenerated. (Since: 2.9) 1662# 1663# @auto-finalize: When false, this job will wait in a PENDING state after it has 1664# finished its work, waiting for @block-job-finalize before 1665# making any block graph changes. 1666# When true, this job will automatically 1667# perform its abort or commit actions. 1668# Defaults to true. (Since 3.1) 1669# 1670# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it 1671# has completely ceased all work, and awaits @block-job-dismiss. 1672# When true, this job will automatically disappear from the query 1673# list without user intervention. 1674# Defaults to true. (Since 3.1) 1675# 1676# Returns: - Nothing on success 1677# - If @device does not exist, DeviceNotFound 1678# - Any other error returns a GenericError. 1679# 1680# Since: 1.3 1681# 1682# Example: 1683# 1684# -> { "execute": "block-commit", 1685# "arguments": { "device": "virtio0", 1686# "top": "/tmp/snap1.qcow2" } } 1687# <- { "return": {} } 1688# 1689## 1690{ 'command': 'block-commit', 1691 'data': { '*job-id': 'str', 'device': 'str', '*base-node': 'str', 1692 '*base': 'str', '*top-node': 'str', '*top': 'str', 1693 '*backing-file': 'str', '*speed': 'int', 1694 '*filter-node-name': 'str', 1695 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } } 1696 1697## 1698# @drive-backup: 1699# 1700# Start a point-in-time copy of a block device to a new destination. The 1701# status of ongoing drive-backup operations can be checked with 1702# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1703# The operation can be stopped before it has completed using the 1704# block-job-cancel command. 1705# 1706# Returns: - nothing on success 1707# - If @device is not a valid block device, GenericError 1708# 1709# Since: 1.6 1710# 1711# Example: 1712# 1713# -> { "execute": "drive-backup", 1714# "arguments": { "device": "drive0", 1715# "sync": "full", 1716# "target": "backup.img" } } 1717# <- { "return": {} } 1718# 1719## 1720{ 'command': 'drive-backup', 'boxed': true, 1721 'data': 'DriveBackup' } 1722 1723## 1724# @blockdev-backup: 1725# 1726# Start a point-in-time copy of a block device to a new destination. The 1727# status of ongoing blockdev-backup operations can be checked with 1728# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1729# The operation can be stopped before it has completed using the 1730# block-job-cancel command. 1731# 1732# Returns: - nothing on success 1733# - If @device is not a valid block device, DeviceNotFound 1734# 1735# Since: 2.3 1736# 1737# Example: 1738# -> { "execute": "blockdev-backup", 1739# "arguments": { "device": "src-id", 1740# "sync": "full", 1741# "target": "tgt-id" } } 1742# <- { "return": {} } 1743# 1744## 1745{ 'command': 'blockdev-backup', 'boxed': true, 1746 'data': 'BlockdevBackup' } 1747 1748 1749## 1750# @query-named-block-nodes: 1751# 1752# Get the named block driver list 1753# 1754# Returns: the list of BlockDeviceInfo 1755# 1756# Since: 2.0 1757# 1758# Example: 1759# 1760# -> { "execute": "query-named-block-nodes" } 1761# <- { "return": [ { "ro":false, 1762# "drv":"qcow2", 1763# "encrypted":false, 1764# "file":"disks/test.qcow2", 1765# "node-name": "my-node", 1766# "backing_file_depth":1, 1767# "bps":1000000, 1768# "bps_rd":0, 1769# "bps_wr":0, 1770# "iops":1000000, 1771# "iops_rd":0, 1772# "iops_wr":0, 1773# "bps_max": 8000000, 1774# "bps_rd_max": 0, 1775# "bps_wr_max": 0, 1776# "iops_max": 0, 1777# "iops_rd_max": 0, 1778# "iops_wr_max": 0, 1779# "iops_size": 0, 1780# "write_threshold": 0, 1781# "image":{ 1782# "filename":"disks/test.qcow2", 1783# "format":"qcow2", 1784# "virtual-size":2048000, 1785# "backing_file":"base.qcow2", 1786# "full-backing-filename":"disks/base.qcow2", 1787# "backing-filename-format":"qcow2", 1788# "snapshots":[ 1789# { 1790# "id": "1", 1791# "name": "snapshot1", 1792# "vm-state-size": 0, 1793# "date-sec": 10000200, 1794# "date-nsec": 12, 1795# "vm-clock-sec": 206, 1796# "vm-clock-nsec": 30 1797# } 1798# ], 1799# "backing-image":{ 1800# "filename":"disks/base.qcow2", 1801# "format":"qcow2", 1802# "virtual-size":2048000 1803# } 1804# } } ] } 1805# 1806## 1807{ 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ] } 1808 1809## 1810# @XDbgBlockGraphNodeType: 1811# 1812# @block-backend: corresponds to BlockBackend 1813# 1814# @block-job: corresonds to BlockJob 1815# 1816# @block-driver: corresponds to BlockDriverState 1817# 1818# Since: 4.0 1819## 1820{ 'enum': 'XDbgBlockGraphNodeType', 1821 'data': [ 'block-backend', 'block-job', 'block-driver' ] } 1822 1823## 1824# @XDbgBlockGraphNode: 1825# 1826# @id: Block graph node identifier. This @id is generated only for 1827# x-debug-query-block-graph and does not relate to any other identifiers in 1828# Qemu. 1829# 1830# @type: Type of graph node. Can be one of block-backend, block-job or 1831# block-driver-state. 1832# 1833# @name: Human readable name of the node. Corresponds to node-name for 1834# block-driver-state nodes; is not guaranteed to be unique in the whole 1835# graph (with block-jobs and block-backends). 1836# 1837# Since: 4.0 1838## 1839{ 'struct': 'XDbgBlockGraphNode', 1840 'data': { 'id': 'uint64', 'type': 'XDbgBlockGraphNodeType', 'name': 'str' } } 1841 1842## 1843# @BlockPermission: 1844# 1845# Enum of base block permissions. 1846# 1847# @consistent-read: A user that has the "permission" of consistent reads is 1848# guaranteed that their view of the contents of the block 1849# device is complete and self-consistent, representing the 1850# contents of a disk at a specific point. 1851# For most block devices (including their backing files) this 1852# is true, but the property cannot be maintained in a few 1853# situations like for intermediate nodes of a commit block 1854# job. 1855# 1856# @write: This permission is required to change the visible disk contents. 1857# 1858# @write-unchanged: This permission (which is weaker than BLK_PERM_WRITE) is 1859# both enough and required for writes to the block node when 1860# the caller promises that the visible disk content doesn't 1861# change. 1862# As the BLK_PERM_WRITE permission is strictly stronger, 1863# either is sufficient to perform an unchanging write. 1864# 1865# @resize: This permission is required to change the size of a block node. 1866# 1867# @graph-mod: This permission is required to change the node that this 1868# BdrvChild points to. 1869# 1870# Since: 4.0 1871## 1872 { 'enum': 'BlockPermission', 1873 'data': [ 'consistent-read', 'write', 'write-unchanged', 'resize', 1874 'graph-mod' ] } 1875## 1876# @XDbgBlockGraphEdge: 1877# 1878# Block Graph edge description for x-debug-query-block-graph. 1879# 1880# @parent: parent id 1881# 1882# @child: child id 1883# 1884# @name: name of the relation (examples are 'file' and 'backing') 1885# 1886# @perm: granted permissions for the parent operating on the child 1887# 1888# @shared-perm: permissions that can still be granted to other users of the 1889# child while it is still attached to this parent 1890# 1891# Since: 4.0 1892## 1893{ 'struct': 'XDbgBlockGraphEdge', 1894 'data': { 'parent': 'uint64', 'child': 'uint64', 1895 'name': 'str', 'perm': [ 'BlockPermission' ], 1896 'shared-perm': [ 'BlockPermission' ] } } 1897 1898## 1899# @XDbgBlockGraph: 1900# 1901# Block Graph - list of nodes and list of edges. 1902# 1903# Since: 4.0 1904## 1905{ 'struct': 'XDbgBlockGraph', 1906 'data': { 'nodes': ['XDbgBlockGraphNode'], 'edges': ['XDbgBlockGraphEdge'] } } 1907 1908## 1909# @x-debug-query-block-graph: 1910# 1911# Get the block graph. 1912# 1913# Since: 4.0 1914## 1915{ 'command': 'x-debug-query-block-graph', 'returns': 'XDbgBlockGraph' } 1916 1917## 1918# @drive-mirror: 1919# 1920# Start mirroring a block device's writes to a new destination. target 1921# specifies the target of the new image. If the file exists, or if it 1922# is a device, it will be used as the new destination for writes. If 1923# it does not exist, a new file will be created. format specifies the 1924# format of the mirror image, default is to probe if mode='existing', 1925# else the format of the source. 1926# 1927# Returns: - nothing on success 1928# - If @device is not a valid block device, GenericError 1929# 1930# Since: 1.3 1931# 1932# Example: 1933# 1934# -> { "execute": "drive-mirror", 1935# "arguments": { "device": "ide-hd0", 1936# "target": "/some/place/my-image", 1937# "sync": "full", 1938# "format": "qcow2" } } 1939# <- { "return": {} } 1940# 1941## 1942{ 'command': 'drive-mirror', 'boxed': true, 1943 'data': 'DriveMirror' } 1944 1945## 1946# @DriveMirror: 1947# 1948# A set of parameters describing drive mirror setup. 1949# 1950# @job-id: identifier for the newly-created block job. If 1951# omitted, the device name will be used. (Since 2.7) 1952# 1953# @device: the device name or node-name of a root node whose writes should be 1954# mirrored. 1955# 1956# @target: the target of the new image. If the file exists, or if it 1957# is a device, the existing file/device will be used as the new 1958# destination. If it does not exist, a new file will be created. 1959# 1960# @format: the format of the new destination, default is to 1961# probe if @mode is 'existing', else the format of the source 1962# 1963# @node-name: the new block driver state node name in the graph 1964# (Since 2.1) 1965# 1966# @replaces: with sync=full graph node name to be replaced by the new 1967# image when a whole image copy is done. This can be used to repair 1968# broken Quorum files. (Since 2.1) 1969# 1970# @mode: whether and how QEMU should create a new image, default is 1971# 'absolute-paths'. 1972# 1973# @speed: the maximum speed, in bytes per second 1974# 1975# @sync: what parts of the disk image should be copied to the destination 1976# (all the disk, only the sectors allocated in the topmost image, or 1977# only new I/O). 1978# 1979# @granularity: granularity of the dirty bitmap, default is 64K 1980# if the image format doesn't have clusters, 4K if the clusters 1981# are smaller than that, else the cluster size. Must be a 1982# power of 2 between 512 and 64M (since 1.4). 1983# 1984# @buf-size: maximum amount of data in flight from source to 1985# target (since 1.4). 1986# 1987# @on-source-error: the action to take on an error on the source, 1988# default 'report'. 'stop' and 'enospc' can only be used 1989# if the block device supports io-status (see BlockInfo). 1990# 1991# @on-target-error: the action to take on an error on the target, 1992# default 'report' (no limitations, since this applies to 1993# a different block device than @device). 1994# @unmap: Whether to try to unmap target sectors where source has 1995# only zero. If true, and target unallocated sectors will read as zero, 1996# target image sectors will be unmapped; otherwise, zeroes will be 1997# written. Both will result in identical contents. 1998# Default is true. (Since 2.4) 1999# 2000# @copy-mode: when to copy data to the destination; defaults to 'background' 2001# (Since: 3.0) 2002# 2003# @auto-finalize: When false, this job will wait in a PENDING state after it has 2004# finished its work, waiting for @block-job-finalize before 2005# making any block graph changes. 2006# When true, this job will automatically 2007# perform its abort or commit actions. 2008# Defaults to true. (Since 3.1) 2009# 2010# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it 2011# has completely ceased all work, and awaits @block-job-dismiss. 2012# When true, this job will automatically disappear from the query 2013# list without user intervention. 2014# Defaults to true. (Since 3.1) 2015# Since: 1.3 2016## 2017{ 'struct': 'DriveMirror', 2018 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 2019 '*format': 'str', '*node-name': 'str', '*replaces': 'str', 2020 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode', 2021 '*speed': 'int', '*granularity': 'uint32', 2022 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError', 2023 '*on-target-error': 'BlockdevOnError', 2024 '*unmap': 'bool', '*copy-mode': 'MirrorCopyMode', 2025 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } } 2026 2027## 2028# @BlockDirtyBitmap: 2029# 2030# @node: name of device/node which the bitmap is tracking 2031# 2032# @name: name of the dirty bitmap 2033# 2034# Since: 2.4 2035## 2036{ 'struct': 'BlockDirtyBitmap', 2037 'data': { 'node': 'str', 'name': 'str' } } 2038 2039## 2040# @BlockDirtyBitmapAdd: 2041# 2042# @node: name of device/node which the bitmap is tracking 2043# 2044# @name: name of the dirty bitmap (must be less than 1024 bytes) 2045# 2046# @granularity: the bitmap granularity, default is 64k for 2047# block-dirty-bitmap-add 2048# 2049# @persistent: the bitmap is persistent, i.e. it will be saved to the 2050# corresponding block device image file on its close. For now only 2051# Qcow2 disks support persistent bitmaps. Default is false for 2052# block-dirty-bitmap-add. (Since: 2.10) 2053# 2054# @disabled: the bitmap is created in the disabled state, which means that 2055# it will not track drive changes. The bitmap may be enabled with 2056# block-dirty-bitmap-enable. Default is false. (Since: 4.0) 2057# 2058# Since: 2.4 2059## 2060{ 'struct': 'BlockDirtyBitmapAdd', 2061 'data': { 'node': 'str', 'name': 'str', '*granularity': 'uint32', 2062 '*persistent': 'bool', '*disabled': 'bool' } } 2063 2064## 2065# @BlockDirtyBitmapMergeSource: 2066# 2067# @local: name of the bitmap, attached to the same node as target bitmap. 2068# 2069# @external: bitmap with specified node 2070# 2071# Since: 4.1 2072## 2073{ 'alternate': 'BlockDirtyBitmapMergeSource', 2074 'data': { 'local': 'str', 2075 'external': 'BlockDirtyBitmap' } } 2076 2077## 2078# @BlockDirtyBitmapMerge: 2079# 2080# @node: name of device/node which the @target bitmap is tracking 2081# 2082# @target: name of the destination dirty bitmap 2083# 2084# @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or fully 2085# specifed BlockDirtyBitmap elements. The latter are supported 2086# since 4.1. 2087# 2088# Since: 4.0 2089## 2090{ 'struct': 'BlockDirtyBitmapMerge', 2091 'data': { 'node': 'str', 'target': 'str', 2092 'bitmaps': ['BlockDirtyBitmapMergeSource'] } } 2093 2094## 2095# @block-dirty-bitmap-add: 2096# 2097# Create a dirty bitmap with a name on the node, and start tracking the writes. 2098# 2099# Returns: - nothing on success 2100# - If @node is not a valid block device or node, DeviceNotFound 2101# - If @name is already taken, GenericError with an explanation 2102# 2103# Since: 2.4 2104# 2105# Example: 2106# 2107# -> { "execute": "block-dirty-bitmap-add", 2108# "arguments": { "node": "drive0", "name": "bitmap0" } } 2109# <- { "return": {} } 2110# 2111## 2112{ 'command': 'block-dirty-bitmap-add', 2113 'data': 'BlockDirtyBitmapAdd' } 2114 2115## 2116# @block-dirty-bitmap-remove: 2117# 2118# Stop write tracking and remove the dirty bitmap that was created 2119# with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its 2120# storage too. 2121# 2122# Returns: - nothing on success 2123# - If @node is not a valid block device or node, DeviceNotFound 2124# - If @name is not found, GenericError with an explanation 2125# - if @name is frozen by an operation, GenericError 2126# 2127# Since: 2.4 2128# 2129# Example: 2130# 2131# -> { "execute": "block-dirty-bitmap-remove", 2132# "arguments": { "node": "drive0", "name": "bitmap0" } } 2133# <- { "return": {} } 2134# 2135## 2136{ 'command': 'block-dirty-bitmap-remove', 2137 'data': 'BlockDirtyBitmap' } 2138 2139## 2140# @block-dirty-bitmap-clear: 2141# 2142# Clear (reset) a dirty bitmap on the device, so that an incremental 2143# backup from this point in time forward will only backup clusters 2144# modified after this clear operation. 2145# 2146# Returns: - nothing on success 2147# - If @node is not a valid block device, DeviceNotFound 2148# - If @name is not found, GenericError with an explanation 2149# 2150# Since: 2.4 2151# 2152# Example: 2153# 2154# -> { "execute": "block-dirty-bitmap-clear", 2155# "arguments": { "node": "drive0", "name": "bitmap0" } } 2156# <- { "return": {} } 2157# 2158## 2159{ 'command': 'block-dirty-bitmap-clear', 2160 'data': 'BlockDirtyBitmap' } 2161 2162## 2163# @block-dirty-bitmap-enable: 2164# 2165# Enables a dirty bitmap so that it will begin tracking disk changes. 2166# 2167# Returns: - nothing on success 2168# - If @node is not a valid block device, DeviceNotFound 2169# - If @name is not found, GenericError with an explanation 2170# 2171# Since: 4.0 2172# 2173# Example: 2174# 2175# -> { "execute": "block-dirty-bitmap-enable", 2176# "arguments": { "node": "drive0", "name": "bitmap0" } } 2177# <- { "return": {} } 2178# 2179## 2180 { 'command': 'block-dirty-bitmap-enable', 2181 'data': 'BlockDirtyBitmap' } 2182 2183## 2184# @block-dirty-bitmap-disable: 2185# 2186# Disables a dirty bitmap so that it will stop tracking disk changes. 2187# 2188# Returns: - nothing on success 2189# - If @node is not a valid block device, DeviceNotFound 2190# - If @name is not found, GenericError with an explanation 2191# 2192# Since: 4.0 2193# 2194# Example: 2195# 2196# -> { "execute": "block-dirty-bitmap-disable", 2197# "arguments": { "node": "drive0", "name": "bitmap0" } } 2198# <- { "return": {} } 2199# 2200## 2201 { 'command': 'block-dirty-bitmap-disable', 2202 'data': 'BlockDirtyBitmap' } 2203 2204## 2205# @block-dirty-bitmap-merge: 2206# 2207# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap. 2208# Dirty bitmaps in @bitmaps will be unchanged, except if it also appears 2209# as the @target bitmap. Any bits already set in @target will still be 2210# set after the merge, i.e., this operation does not clear the target. 2211# On error, @target is unchanged. 2212# 2213# The resulting bitmap will count as dirty any clusters that were dirty in any 2214# of the source bitmaps. This can be used to achieve backup checkpoints, or in 2215# simpler usages, to copy bitmaps. 2216# 2217# Returns: - nothing on success 2218# - If @node is not a valid block device, DeviceNotFound 2219# - If any bitmap in @bitmaps or @target is not found, GenericError 2220# - If any of the bitmaps have different sizes or granularities, 2221# GenericError 2222# 2223# Since: 4.0 2224# 2225# Example: 2226# 2227# -> { "execute": "block-dirty-bitmap-merge", 2228# "arguments": { "node": "drive0", "target": "bitmap0", 2229# "bitmaps": ["bitmap1"] } } 2230# <- { "return": {} } 2231# 2232## 2233 { 'command': 'block-dirty-bitmap-merge', 2234 'data': 'BlockDirtyBitmapMerge' } 2235 2236## 2237# @BlockDirtyBitmapSha256: 2238# 2239# SHA256 hash of dirty bitmap data 2240# 2241# @sha256: ASCII representation of SHA256 bitmap hash 2242# 2243# Since: 2.10 2244## 2245 { 'struct': 'BlockDirtyBitmapSha256', 2246 'data': {'sha256': 'str'} } 2247 2248## 2249# @x-debug-block-dirty-bitmap-sha256: 2250# 2251# Get bitmap SHA256. 2252# 2253# Returns: - BlockDirtyBitmapSha256 on success 2254# - If @node is not a valid block device, DeviceNotFound 2255# - If @name is not found or if hashing has failed, GenericError with an 2256# explanation 2257# 2258# Since: 2.10 2259## 2260 { 'command': 'x-debug-block-dirty-bitmap-sha256', 2261 'data': 'BlockDirtyBitmap', 'returns': 'BlockDirtyBitmapSha256' } 2262 2263## 2264# @blockdev-mirror: 2265# 2266# Start mirroring a block device's writes to a new destination. 2267# 2268# @job-id: identifier for the newly-created block job. If 2269# omitted, the device name will be used. (Since 2.7) 2270# 2271# @device: The device name or node-name of a root node whose writes should be 2272# mirrored. 2273# 2274# @target: the id or node-name of the block device to mirror to. This mustn't be 2275# attached to guest. 2276# 2277# @replaces: with sync=full graph node name to be replaced by the new 2278# image when a whole image copy is done. This can be used to repair 2279# broken Quorum files. 2280# 2281# @speed: the maximum speed, in bytes per second 2282# 2283# @sync: what parts of the disk image should be copied to the destination 2284# (all the disk, only the sectors allocated in the topmost image, or 2285# only new I/O). 2286# 2287# @granularity: granularity of the dirty bitmap, default is 64K 2288# if the image format doesn't have clusters, 4K if the clusters 2289# are smaller than that, else the cluster size. Must be a 2290# power of 2 between 512 and 64M 2291# 2292# @buf-size: maximum amount of data in flight from source to 2293# target 2294# 2295# @on-source-error: the action to take on an error on the source, 2296# default 'report'. 'stop' and 'enospc' can only be used 2297# if the block device supports io-status (see BlockInfo). 2298# 2299# @on-target-error: the action to take on an error on the target, 2300# default 'report' (no limitations, since this applies to 2301# a different block device than @device). 2302# 2303# @filter-node-name: the node name that should be assigned to the 2304# filter driver that the mirror job inserts into the graph 2305# above @device. If this option is not given, a node name is 2306# autogenerated. (Since: 2.9) 2307# 2308# @copy-mode: when to copy data to the destination; defaults to 'background' 2309# (Since: 3.0) 2310# 2311# @auto-finalize: When false, this job will wait in a PENDING state after it has 2312# finished its work, waiting for @block-job-finalize before 2313# making any block graph changes. 2314# When true, this job will automatically 2315# perform its abort or commit actions. 2316# Defaults to true. (Since 3.1) 2317# 2318# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it 2319# has completely ceased all work, and awaits @block-job-dismiss. 2320# When true, this job will automatically disappear from the query 2321# list without user intervention. 2322# Defaults to true. (Since 3.1) 2323# Returns: nothing on success. 2324# 2325# Since: 2.6 2326# 2327# Example: 2328# 2329# -> { "execute": "blockdev-mirror", 2330# "arguments": { "device": "ide-hd0", 2331# "target": "target0", 2332# "sync": "full" } } 2333# <- { "return": {} } 2334# 2335## 2336{ 'command': 'blockdev-mirror', 2337 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 2338 '*replaces': 'str', 2339 'sync': 'MirrorSyncMode', 2340 '*speed': 'int', '*granularity': 'uint32', 2341 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError', 2342 '*on-target-error': 'BlockdevOnError', 2343 '*filter-node-name': 'str', 2344 '*copy-mode': 'MirrorCopyMode', 2345 '*auto-finalize': 'bool', '*auto-dismiss': 'bool' } } 2346 2347## 2348# @block_set_io_throttle: 2349# 2350# Change I/O throttle limits for a block drive. 2351# 2352# Since QEMU 2.4, each device with I/O limits is member of a throttle 2353# group. 2354# 2355# If two or more devices are members of the same group, the limits 2356# will apply to the combined I/O of the whole group in a round-robin 2357# fashion. Therefore, setting new I/O limits to a device will affect 2358# the whole group. 2359# 2360# The name of the group can be specified using the 'group' parameter. 2361# If the parameter is unset, it is assumed to be the current group of 2362# that device. If it's not in any group yet, the name of the device 2363# will be used as the name for its group. 2364# 2365# The 'group' parameter can also be used to move a device to a 2366# different group. In this case the limits specified in the parameters 2367# will be applied to the new group only. 2368# 2369# I/O limits can be disabled by setting all of them to 0. In this case 2370# the device will be removed from its group and the rest of its 2371# members will not be affected. The 'group' parameter is ignored. 2372# 2373# Returns: - Nothing on success 2374# - If @device is not a valid block device, DeviceNotFound 2375# 2376# Since: 1.1 2377# 2378# Example: 2379# 2380# -> { "execute": "block_set_io_throttle", 2381# "arguments": { "id": "virtio-blk-pci0/virtio-backend", 2382# "bps": 0, 2383# "bps_rd": 0, 2384# "bps_wr": 0, 2385# "iops": 512, 2386# "iops_rd": 0, 2387# "iops_wr": 0, 2388# "bps_max": 0, 2389# "bps_rd_max": 0, 2390# "bps_wr_max": 0, 2391# "iops_max": 0, 2392# "iops_rd_max": 0, 2393# "iops_wr_max": 0, 2394# "bps_max_length": 0, 2395# "iops_size": 0 } } 2396# <- { "return": {} } 2397# 2398# -> { "execute": "block_set_io_throttle", 2399# "arguments": { "id": "ide0-1-0", 2400# "bps": 1000000, 2401# "bps_rd": 0, 2402# "bps_wr": 0, 2403# "iops": 0, 2404# "iops_rd": 0, 2405# "iops_wr": 0, 2406# "bps_max": 8000000, 2407# "bps_rd_max": 0, 2408# "bps_wr_max": 0, 2409# "iops_max": 0, 2410# "iops_rd_max": 0, 2411# "iops_wr_max": 0, 2412# "bps_max_length": 60, 2413# "iops_size": 0 } } 2414# <- { "return": {} } 2415## 2416{ 'command': 'block_set_io_throttle', 'boxed': true, 2417 'data': 'BlockIOThrottle' } 2418 2419## 2420# @BlockIOThrottle: 2421# 2422# A set of parameters describing block throttling. 2423# 2424# @device: Block device name (deprecated, use @id instead) 2425# 2426# @id: The name or QOM path of the guest device (since: 2.8) 2427# 2428# @bps: total throughput limit in bytes per second 2429# 2430# @bps_rd: read throughput limit in bytes per second 2431# 2432# @bps_wr: write throughput limit in bytes per second 2433# 2434# @iops: total I/O operations per second 2435# 2436# @iops_rd: read I/O operations per second 2437# 2438# @iops_wr: write I/O operations per second 2439# 2440# @bps_max: total throughput limit during bursts, 2441# in bytes (Since 1.7) 2442# 2443# @bps_rd_max: read throughput limit during bursts, 2444# in bytes (Since 1.7) 2445# 2446# @bps_wr_max: write throughput limit during bursts, 2447# in bytes (Since 1.7) 2448# 2449# @iops_max: total I/O operations per second during bursts, 2450# in bytes (Since 1.7) 2451# 2452# @iops_rd_max: read I/O operations per second during bursts, 2453# in bytes (Since 1.7) 2454# 2455# @iops_wr_max: write I/O operations per second during bursts, 2456# in bytes (Since 1.7) 2457# 2458# @bps_max_length: maximum length of the @bps_max burst 2459# period, in seconds. It must only 2460# be set if @bps_max is set as well. 2461# Defaults to 1. (Since 2.6) 2462# 2463# @bps_rd_max_length: maximum length of the @bps_rd_max 2464# burst period, in seconds. It must only 2465# be set if @bps_rd_max is set as well. 2466# Defaults to 1. (Since 2.6) 2467# 2468# @bps_wr_max_length: maximum length of the @bps_wr_max 2469# burst period, in seconds. It must only 2470# be set if @bps_wr_max is set as well. 2471# Defaults to 1. (Since 2.6) 2472# 2473# @iops_max_length: maximum length of the @iops burst 2474# period, in seconds. It must only 2475# be set if @iops_max is set as well. 2476# Defaults to 1. (Since 2.6) 2477# 2478# @iops_rd_max_length: maximum length of the @iops_rd_max 2479# burst period, in seconds. It must only 2480# be set if @iops_rd_max is set as well. 2481# Defaults to 1. (Since 2.6) 2482# 2483# @iops_wr_max_length: maximum length of the @iops_wr_max 2484# burst period, in seconds. It must only 2485# be set if @iops_wr_max is set as well. 2486# Defaults to 1. (Since 2.6) 2487# 2488# @iops_size: an I/O size in bytes (Since 1.7) 2489# 2490# @group: throttle group name (Since 2.4) 2491# 2492# Since: 1.1 2493## 2494{ 'struct': 'BlockIOThrottle', 2495 'data': { '*device': 'str', '*id': 'str', 'bps': 'int', 'bps_rd': 'int', 2496 'bps_wr': 'int', 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int', 2497 '*bps_max': 'int', '*bps_rd_max': 'int', 2498 '*bps_wr_max': 'int', '*iops_max': 'int', 2499 '*iops_rd_max': 'int', '*iops_wr_max': 'int', 2500 '*bps_max_length': 'int', '*bps_rd_max_length': 'int', 2501 '*bps_wr_max_length': 'int', '*iops_max_length': 'int', 2502 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int', 2503 '*iops_size': 'int', '*group': 'str' } } 2504 2505## 2506# @ThrottleLimits: 2507# 2508# Limit parameters for throttling. 2509# Since some limit combinations are illegal, limits should always be set in one 2510# transaction. All fields are optional. When setting limits, if a field is 2511# missing the current value is not changed. 2512# 2513# @iops-total: limit total I/O operations per second 2514# @iops-total-max: I/O operations burst 2515# @iops-total-max-length: length of the iops-total-max burst period, in seconds 2516# It must only be set if @iops-total-max is set as well. 2517# @iops-read: limit read operations per second 2518# @iops-read-max: I/O operations read burst 2519# @iops-read-max-length: length of the iops-read-max burst period, in seconds 2520# It must only be set if @iops-read-max is set as well. 2521# @iops-write: limit write operations per second 2522# @iops-write-max: I/O operations write burst 2523# @iops-write-max-length: length of the iops-write-max burst period, in seconds 2524# It must only be set if @iops-write-max is set as well. 2525# @bps-total: limit total bytes per second 2526# @bps-total-max: total bytes burst 2527# @bps-total-max-length: length of the bps-total-max burst period, in seconds. 2528# It must only be set if @bps-total-max is set as well. 2529# @bps-read: limit read bytes per second 2530# @bps-read-max: total bytes read burst 2531# @bps-read-max-length: length of the bps-read-max burst period, in seconds 2532# It must only be set if @bps-read-max is set as well. 2533# @bps-write: limit write bytes per second 2534# @bps-write-max: total bytes write burst 2535# @bps-write-max-length: length of the bps-write-max burst period, in seconds 2536# It must only be set if @bps-write-max is set as well. 2537# @iops-size: when limiting by iops max size of an I/O in bytes 2538# 2539# Since: 2.11 2540## 2541{ 'struct': 'ThrottleLimits', 2542 'data': { '*iops-total' : 'int', '*iops-total-max' : 'int', 2543 '*iops-total-max-length' : 'int', '*iops-read' : 'int', 2544 '*iops-read-max' : 'int', '*iops-read-max-length' : 'int', 2545 '*iops-write' : 'int', '*iops-write-max' : 'int', 2546 '*iops-write-max-length' : 'int', '*bps-total' : 'int', 2547 '*bps-total-max' : 'int', '*bps-total-max-length' : 'int', 2548 '*bps-read' : 'int', '*bps-read-max' : 'int', 2549 '*bps-read-max-length' : 'int', '*bps-write' : 'int', 2550 '*bps-write-max' : 'int', '*bps-write-max-length' : 'int', 2551 '*iops-size' : 'int' } } 2552 2553## 2554# @block-stream: 2555# 2556# Copy data from a backing file into a block device. 2557# 2558# The block streaming operation is performed in the background until the entire 2559# backing file has been copied. This command returns immediately once streaming 2560# has started. The status of ongoing block streaming operations can be checked 2561# with query-block-jobs. The operation can be stopped before it has completed 2562# using the block-job-cancel command. 2563# 2564# The node that receives the data is called the top image, can be located in 2565# any part of the chain (but always above the base image; see below) and can be 2566# specified using its device or node name. Earlier qemu versions only allowed 2567# 'device' to name the top level node; presence of the 'base-node' parameter 2568# during introspection can be used as a witness of the enhanced semantics 2569# of 'device'. 2570# 2571# If a base file is specified then sectors are not copied from that base file and 2572# its backing chain. When streaming completes the image file will have the base 2573# file as its backing file. This can be used to stream a subset of the backing 2574# file chain instead of flattening the entire image. 2575# 2576# On successful completion the image file is updated to drop the backing file 2577# and the BLOCK_JOB_COMPLETED event is emitted. 2578# 2579# @job-id: identifier for the newly-created block job. If 2580# omitted, the device name will be used. (Since 2.7) 2581# 2582# @device: the device or node name of the top image 2583# 2584# @base: the common backing file name. 2585# It cannot be set if @base-node is also set. 2586# 2587# @base-node: the node name of the backing file. 2588# It cannot be set if @base is also set. (Since 2.8) 2589# 2590# @backing-file: The backing file string to write into the top 2591# image. This filename is not validated. 2592# 2593# If a pathname string is such that it cannot be 2594# resolved by QEMU, that means that subsequent QMP or 2595# HMP commands must use node-names for the image in 2596# question, as filename lookup methods will fail. 2597# 2598# If not specified, QEMU will automatically determine 2599# the backing file string to use, or error out if there 2600# is no obvious choice. Care should be taken when 2601# specifying the string, to specify a valid filename or 2602# protocol. 2603# (Since 2.1) 2604# 2605# @speed: the maximum speed, in bytes per second 2606# 2607# @on-error: the action to take on an error (default report). 2608# 'stop' and 'enospc' can only be used if the block device 2609# supports io-status (see BlockInfo). Since 1.3. 2610# 2611# @auto-finalize: When false, this job will wait in a PENDING state after it has 2612# finished its work, waiting for @block-job-finalize before 2613# making any block graph changes. 2614# When true, this job will automatically 2615# perform its abort or commit actions. 2616# Defaults to true. (Since 3.1) 2617# 2618# @auto-dismiss: When false, this job will wait in a CONCLUDED state after it 2619# has completely ceased all work, and awaits @block-job-dismiss. 2620# When true, this job will automatically disappear from the query 2621# list without user intervention. 2622# Defaults to true. (Since 3.1) 2623# 2624# Returns: - Nothing on success. 2625# - 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# @io_uring: Use linux io_uring (since 5.0) 2855# 2856# Since: 2.9 2857## 2858{ 'enum': 'BlockdevAioOptions', 2859 'data': [ 'threads', 'native', 2860 { 'name': 'io_uring', 'if': 'defined(CONFIG_LINUX_IO_URING)' } ] } 2861 2862## 2863# @BlockdevCacheOptions: 2864# 2865# Includes cache-related options for block devices 2866# 2867# @direct: enables use of O_DIRECT (bypass the host page cache; 2868# default: false) 2869# @no-flush: ignore any flush requests for the device (default: 2870# false) 2871# 2872# Since: 2.9 2873## 2874{ 'struct': 'BlockdevCacheOptions', 2875 'data': { '*direct': 'bool', 2876 '*no-flush': 'bool' } } 2877 2878## 2879# @BlockdevDriver: 2880# 2881# Drivers that are supported in block device operations. 2882# 2883# @vxhs: Since 2.10 2884# @throttle: Since 2.11 2885# @nvme: Since 2.12 2886# @copy-on-read: Since 3.0 2887# @blklogwrites: Since 3.0 2888# @blkreplay: Since 4.2 2889# @compress: Since 5.0 2890# 2891# Since: 2.9 2892## 2893{ 'enum': 'BlockdevDriver', 2894 'data': [ 'blkdebug', 'blklogwrites', 'blkreplay', 'blkverify', 'bochs', 2895 'cloop', 'compress', 'copy-on-read', 'dmg', 'file', 'ftp', 'ftps', 2896 'gluster', 'host_cdrom', 'host_device', 'http', 'https', 'iscsi', 2897 'luks', 'nbd', 'nfs', 'null-aio', 'null-co', 'nvme', 'parallels', 2898 'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'rbd', 2899 { 'name': 'replication', 'if': 'defined(CONFIG_REPLICATION)' }, 2900 'sheepdog', 2901 'ssh', 'throttle', 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat', 'vxhs' ] } 2902 2903## 2904# @BlockdevOptionsFile: 2905# 2906# Driver specific block device options for the file backend. 2907# 2908# @filename: path to the image file 2909# @pr-manager: the id for the object that will handle persistent reservations 2910# for this device (default: none, forward the commands via SG_IO; 2911# since 2.11) 2912# @aio: AIO backend (default: threads) (since: 2.8) 2913# @locking: whether to enable file locking. If set to 'auto', only enable 2914# when Open File Descriptor (OFD) locking API is available 2915# (default: auto, since 2.10) 2916# @drop-cache: invalidate page cache during live migration. This prevents 2917# stale data on the migration destination with cache.direct=off. 2918# Currently only supported on Linux hosts. 2919# (default: on, since: 4.0) 2920# @x-check-cache-dropped: whether to check that page cache was dropped on live 2921# migration. May cause noticeable delays if the image 2922# file is large, do not use in production. 2923# (default: off) (since: 3.0) 2924# 2925# Features: 2926# @dynamic-auto-read-only: If present, enabled auto-read-only means that the 2927# driver will open the image read-only at first, 2928# dynamically reopen the image file read-write when 2929# the first writer is attached to the node and reopen 2930# read-only when the last writer is detached. This 2931# allows giving QEMU write permissions only on demand 2932# when an operation actually needs write access. 2933# 2934# Since: 2.9 2935## 2936{ 'struct': 'BlockdevOptionsFile', 2937 'data': { 'filename': 'str', 2938 '*pr-manager': 'str', 2939 '*locking': 'OnOffAuto', 2940 '*aio': 'BlockdevAioOptions', 2941 '*drop-cache': {'type': 'bool', 2942 'if': 'defined(CONFIG_LINUX)'}, 2943 '*x-check-cache-dropped': 'bool' }, 2944 'features': [ { 'name': 'dynamic-auto-read-only', 2945 'if': 'defined(CONFIG_POSIX)' } ] } 2946 2947## 2948# @BlockdevOptionsNull: 2949# 2950# Driver specific block device options for the null backend. 2951# 2952# @size: size of the device in bytes. 2953# @latency-ns: emulated latency (in nanoseconds) in processing 2954# requests. Default to zero which completes requests immediately. 2955# (Since 2.4) 2956# @read-zeroes: if true, reads from the device produce zeroes; if false, the 2957# buffer is left unchanged. (default: false; since: 4.1) 2958# 2959# Since: 2.9 2960## 2961{ 'struct': 'BlockdevOptionsNull', 2962 'data': { '*size': 'int', '*latency-ns': 'uint64', '*read-zeroes': 'bool' } } 2963 2964## 2965# @BlockdevOptionsNVMe: 2966# 2967# Driver specific block device options for the NVMe backend. 2968# 2969# @device: PCI controller address of the NVMe device in 2970# format hhhh:bb:ss.f (host:bus:slot.function) 2971# @namespace: namespace number of the device, starting from 1. 2972# 2973# Note that the PCI @device must have been unbound from any host 2974# kernel driver before instructing QEMU to add the blockdev. 2975# 2976# Since: 2.12 2977## 2978{ 'struct': 'BlockdevOptionsNVMe', 2979 'data': { 'device': 'str', 'namespace': 'int' } } 2980 2981## 2982# @BlockdevOptionsVVFAT: 2983# 2984# Driver specific block device options for the vvfat protocol. 2985# 2986# @dir: directory to be exported as FAT image 2987# @fat-type: FAT type: 12, 16 or 32 2988# @floppy: whether to export a floppy image (true) or 2989# partitioned hard disk (false; default) 2990# @label: set the volume label, limited to 11 bytes. FAT16 and 2991# FAT32 traditionally have some restrictions on labels, which are 2992# ignored by most operating systems. Defaults to "QEMU VVFAT". 2993# (since 2.4) 2994# @rw: whether to allow write operations (default: false) 2995# 2996# Since: 2.9 2997## 2998{ 'struct': 'BlockdevOptionsVVFAT', 2999 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool', 3000 '*label': 'str', '*rw': 'bool' } } 3001 3002## 3003# @BlockdevOptionsGenericFormat: 3004# 3005# Driver specific block device options for image format that have no option 3006# besides their data source. 3007# 3008# @file: reference to or definition of the data source block device 3009# 3010# Since: 2.9 3011## 3012{ 'struct': 'BlockdevOptionsGenericFormat', 3013 'data': { 'file': 'BlockdevRef' } } 3014 3015## 3016# @BlockdevOptionsLUKS: 3017# 3018# Driver specific block device options for LUKS. 3019# 3020# @key-secret: the ID of a QCryptoSecret object providing 3021# the decryption key (since 2.6). Mandatory except when 3022# doing a metadata-only probe of the image. 3023# 3024# Since: 2.9 3025## 3026{ 'struct': 'BlockdevOptionsLUKS', 3027 'base': 'BlockdevOptionsGenericFormat', 3028 'data': { '*key-secret': 'str' } } 3029 3030 3031## 3032# @BlockdevOptionsGenericCOWFormat: 3033# 3034# Driver specific block device options for image format that have no option 3035# besides their data source and an optional backing file. 3036# 3037# @backing: reference to or definition of the backing file block 3038# device, null disables the backing file entirely. 3039# Defaults to the backing file stored the image file. 3040# 3041# Since: 2.9 3042## 3043{ 'struct': 'BlockdevOptionsGenericCOWFormat', 3044 'base': 'BlockdevOptionsGenericFormat', 3045 'data': { '*backing': 'BlockdevRefOrNull' } } 3046 3047## 3048# @Qcow2OverlapCheckMode: 3049# 3050# General overlap check modes. 3051# 3052# @none: Do not perform any checks 3053# 3054# @constant: Perform only checks which can be done in constant time and 3055# without reading anything from disk 3056# 3057# @cached: Perform only checks which can be done without reading anything 3058# from disk 3059# 3060# @all: Perform all available overlap checks 3061# 3062# Since: 2.9 3063## 3064{ 'enum': 'Qcow2OverlapCheckMode', 3065 'data': [ 'none', 'constant', 'cached', 'all' ] } 3066 3067## 3068# @Qcow2OverlapCheckFlags: 3069# 3070# Structure of flags for each metadata structure. Setting a field to 'true' 3071# makes qemu guard that structure against unintended overwriting. The default 3072# value is chosen according to the template given. 3073# 3074# @template: Specifies a template mode which can be adjusted using the other 3075# flags, defaults to 'cached' 3076# 3077# @bitmap-directory: since 3.0 3078# 3079# Since: 2.9 3080## 3081{ 'struct': 'Qcow2OverlapCheckFlags', 3082 'data': { '*template': 'Qcow2OverlapCheckMode', 3083 '*main-header': 'bool', 3084 '*active-l1': 'bool', 3085 '*active-l2': 'bool', 3086 '*refcount-table': 'bool', 3087 '*refcount-block': 'bool', 3088 '*snapshot-table': 'bool', 3089 '*inactive-l1': 'bool', 3090 '*inactive-l2': 'bool', 3091 '*bitmap-directory': 'bool' } } 3092 3093## 3094# @Qcow2OverlapChecks: 3095# 3096# Specifies which metadata structures should be guarded against unintended 3097# overwriting. 3098# 3099# @flags: set of flags for separate specification of each metadata structure 3100# type 3101# 3102# @mode: named mode which chooses a specific set of flags 3103# 3104# Since: 2.9 3105## 3106{ 'alternate': 'Qcow2OverlapChecks', 3107 'data': { 'flags': 'Qcow2OverlapCheckFlags', 3108 'mode': 'Qcow2OverlapCheckMode' } } 3109 3110## 3111# @BlockdevQcowEncryptionFormat: 3112# 3113# @aes: AES-CBC with plain64 initialization vectors 3114# 3115# Since: 2.10 3116## 3117{ 'enum': 'BlockdevQcowEncryptionFormat', 3118 'data': [ 'aes' ] } 3119 3120## 3121# @BlockdevQcowEncryption: 3122# 3123# Since: 2.10 3124## 3125{ 'union': 'BlockdevQcowEncryption', 3126 'base': { 'format': 'BlockdevQcowEncryptionFormat' }, 3127 'discriminator': 'format', 3128 'data': { 'aes': 'QCryptoBlockOptionsQCow' } } 3129 3130## 3131# @BlockdevOptionsQcow: 3132# 3133# Driver specific block device options for qcow. 3134# 3135# @encrypt: Image decryption options. Mandatory for 3136# encrypted images, except when doing a metadata-only 3137# probe of the image. 3138# 3139# Since: 2.10 3140## 3141{ 'struct': 'BlockdevOptionsQcow', 3142 'base': 'BlockdevOptionsGenericCOWFormat', 3143 'data': { '*encrypt': 'BlockdevQcowEncryption' } } 3144 3145 3146 3147## 3148# @BlockdevQcow2EncryptionFormat: 3149# @aes: AES-CBC with plain64 initialization vectors 3150# 3151# Since: 2.10 3152## 3153{ 'enum': 'BlockdevQcow2EncryptionFormat', 3154 'data': [ 'aes', 'luks' ] } 3155 3156## 3157# @BlockdevQcow2Encryption: 3158# 3159# Since: 2.10 3160## 3161{ 'union': 'BlockdevQcow2Encryption', 3162 'base': { 'format': 'BlockdevQcow2EncryptionFormat' }, 3163 'discriminator': 'format', 3164 'data': { 'aes': 'QCryptoBlockOptionsQCow', 3165 'luks': 'QCryptoBlockOptionsLUKS'} } 3166 3167## 3168# @BlockdevOptionsQcow2: 3169# 3170# Driver specific block device options for qcow2. 3171# 3172# @lazy-refcounts: whether to enable the lazy refcounts 3173# feature (default is taken from the image file) 3174# 3175# @pass-discard-request: whether discard requests to the qcow2 3176# device should be forwarded to the data source 3177# 3178# @pass-discard-snapshot: whether discard requests for the data source 3179# should be issued when a snapshot operation (e.g. 3180# deleting a snapshot) frees clusters in the qcow2 file 3181# 3182# @pass-discard-other: whether discard requests for the data source 3183# should be issued on other occasions where a cluster 3184# gets freed 3185# 3186# @overlap-check: which overlap checks to perform for writes 3187# to the image, defaults to 'cached' (since 2.2) 3188# 3189# @cache-size: the maximum total size of the L2 table and 3190# refcount block caches in bytes (since 2.2) 3191# 3192# @l2-cache-size: the maximum size of the L2 table cache in 3193# bytes (since 2.2) 3194# 3195# @l2-cache-entry-size: the size of each entry in the L2 cache in 3196# bytes. It must be a power of two between 512 3197# and the cluster size. The default value is 3198# the cluster size (since 2.12) 3199# 3200# @refcount-cache-size: the maximum size of the refcount block cache 3201# in bytes (since 2.2) 3202# 3203# @cache-clean-interval: clean unused entries in the L2 and refcount 3204# caches. The interval is in seconds. The default value 3205# is 600 on supporting platforms, and 0 on other 3206# platforms. 0 disables this feature. (since 2.5) 3207# 3208# @encrypt: Image decryption options. Mandatory for 3209# encrypted images, except when doing a metadata-only 3210# probe of the image. (since 2.10) 3211# 3212# @data-file: reference to or definition of the external data file. 3213# This may only be specified for images that require an 3214# external data file. If it is not specified for such 3215# an image, the data file name is loaded from the image 3216# file. (since 4.0) 3217# 3218# Since: 2.9 3219## 3220{ 'struct': 'BlockdevOptionsQcow2', 3221 'base': 'BlockdevOptionsGenericCOWFormat', 3222 'data': { '*lazy-refcounts': 'bool', 3223 '*pass-discard-request': 'bool', 3224 '*pass-discard-snapshot': 'bool', 3225 '*pass-discard-other': 'bool', 3226 '*overlap-check': 'Qcow2OverlapChecks', 3227 '*cache-size': 'int', 3228 '*l2-cache-size': 'int', 3229 '*l2-cache-entry-size': 'int', 3230 '*refcount-cache-size': 'int', 3231 '*cache-clean-interval': 'int', 3232 '*encrypt': 'BlockdevQcow2Encryption', 3233 '*data-file': 'BlockdevRef' } } 3234 3235## 3236# @SshHostKeyCheckMode: 3237# 3238# @none: Don't check the host key at all 3239# @hash: Compare the host key with a given hash 3240# @known_hosts: Check the host key against the known_hosts file 3241# 3242# Since: 2.12 3243## 3244{ 'enum': 'SshHostKeyCheckMode', 3245 'data': [ 'none', 'hash', 'known_hosts' ] } 3246 3247## 3248# @SshHostKeyCheckHashType: 3249# 3250# @md5: The given hash is an md5 hash 3251# @sha1: The given hash is an sha1 hash 3252# 3253# Since: 2.12 3254## 3255{ 'enum': 'SshHostKeyCheckHashType', 3256 'data': [ 'md5', 'sha1' ] } 3257 3258## 3259# @SshHostKeyHash: 3260# 3261# @type: The hash algorithm used for the hash 3262# @hash: The expected hash value 3263# 3264# Since: 2.12 3265## 3266{ 'struct': 'SshHostKeyHash', 3267 'data': { 'type': 'SshHostKeyCheckHashType', 3268 'hash': 'str' }} 3269 3270## 3271# @SshHostKeyCheck: 3272# 3273# Since: 2.12 3274## 3275{ 'union': 'SshHostKeyCheck', 3276 'base': { 'mode': 'SshHostKeyCheckMode' }, 3277 'discriminator': 'mode', 3278 'data': { 'hash': 'SshHostKeyHash' } } 3279 3280## 3281# @BlockdevOptionsSsh: 3282# 3283# @server: host address 3284# 3285# @path: path to the image on the host 3286# 3287# @user: user as which to connect, defaults to current 3288# local user name 3289# 3290# @host-key-check: Defines how and what to check the host key against 3291# (default: known_hosts) 3292# 3293# Since: 2.9 3294## 3295{ 'struct': 'BlockdevOptionsSsh', 3296 'data': { 'server': 'InetSocketAddress', 3297 'path': 'str', 3298 '*user': 'str', 3299 '*host-key-check': 'SshHostKeyCheck' } } 3300 3301 3302## 3303# @BlkdebugEvent: 3304# 3305# Trigger events supported by blkdebug. 3306# 3307# @l1_shrink_write_table: write zeros to the l1 table to shrink image. 3308# (since 2.11) 3309# 3310# @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11) 3311# 3312# @cor_write: a write due to copy-on-read (since 2.11) 3313# 3314# @cluster_alloc_space: an allocation of file space for a cluster (since 4.1) 3315# 3316# @none: triggers once at creation of the blkdebug node (since 4.1) 3317# 3318# Since: 2.9 3319## 3320{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG', 3321 'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table', 3322 'l1_grow_activate_table', 'l2_load', 'l2_update', 3323 'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write', 3324 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio', 3325 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read', 3326 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update', 3327 'refblock_load', 'refblock_update', 'refblock_update_part', 3328 'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write', 3329 'refblock_alloc_write_blocks', 'refblock_alloc_write_table', 3330 'refblock_alloc_switch_table', 'cluster_alloc', 3331 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os', 3332 'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head', 3333 'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev', 3334 'pwritev_zero', 'pwritev_done', 'empty_image_prepare', 3335 'l1_shrink_write_table', 'l1_shrink_free_l2_clusters', 3336 'cor_write', 'cluster_alloc_space', 'none'] } 3337 3338## 3339# @BlkdebugIOType: 3340# 3341# Kinds of I/O that blkdebug can inject errors in. 3342# 3343# @read: .bdrv_co_preadv() 3344# 3345# @write: .bdrv_co_pwritev() 3346# 3347# @write-zeroes: .bdrv_co_pwrite_zeroes() 3348# 3349# @discard: .bdrv_co_pdiscard() 3350# 3351# @flush: .bdrv_co_flush_to_disk() 3352# 3353# @block-status: .bdrv_co_block_status() 3354# 3355# Since: 4.1 3356## 3357{ 'enum': 'BlkdebugIOType', 'prefix': 'BLKDEBUG_IO_TYPE', 3358 'data': [ 'read', 'write', 'write-zeroes', 'discard', 'flush', 3359 'block-status' ] } 3360 3361## 3362# @BlkdebugInjectErrorOptions: 3363# 3364# Describes a single error injection for blkdebug. 3365# 3366# @event: trigger event 3367# 3368# @state: the state identifier blkdebug needs to be in to 3369# actually trigger the event; defaults to "any" 3370# 3371# @iotype: the type of I/O operations on which this error should 3372# be injected; defaults to "all read, write, 3373# write-zeroes, discard, and flush operations" 3374# (since: 4.1) 3375# 3376# @errno: error identifier (errno) to be returned; defaults to 3377# EIO 3378# 3379# @sector: specifies the sector index which has to be affected 3380# in order to actually trigger the event; defaults to "any 3381# sector" 3382# 3383# @once: disables further events after this one has been 3384# triggered; defaults to false 3385# 3386# @immediately: fail immediately; defaults to false 3387# 3388# Since: 2.9 3389## 3390{ 'struct': 'BlkdebugInjectErrorOptions', 3391 'data': { 'event': 'BlkdebugEvent', 3392 '*state': 'int', 3393 '*iotype': 'BlkdebugIOType', 3394 '*errno': 'int', 3395 '*sector': 'int', 3396 '*once': 'bool', 3397 '*immediately': 'bool' } } 3398 3399## 3400# @BlkdebugSetStateOptions: 3401# 3402# Describes a single state-change event for blkdebug. 3403# 3404# @event: trigger event 3405# 3406# @state: the current state identifier blkdebug needs to be in; 3407# defaults to "any" 3408# 3409# @new_state: the state identifier blkdebug is supposed to assume if 3410# this event is triggered 3411# 3412# Since: 2.9 3413## 3414{ 'struct': 'BlkdebugSetStateOptions', 3415 'data': { 'event': 'BlkdebugEvent', 3416 '*state': 'int', 3417 'new_state': 'int' } } 3418 3419## 3420# @BlockdevOptionsBlkdebug: 3421# 3422# Driver specific block device options for blkdebug. 3423# 3424# @image: underlying raw block device (or image file) 3425# 3426# @config: filename of the configuration file 3427# 3428# @align: required alignment for requests in bytes, must be 3429# positive power of 2, or 0 for default 3430# 3431# @max-transfer: maximum size for I/O transfers in bytes, must be 3432# positive multiple of @align and of the underlying 3433# file's request alignment (but need not be a power of 3434# 2), or 0 for default (since 2.10) 3435# 3436# @opt-write-zero: preferred alignment for write zero requests in bytes, 3437# must be positive multiple of @align and of the 3438# underlying file's request alignment (but need not be a 3439# power of 2), or 0 for default (since 2.10) 3440# 3441# @max-write-zero: maximum size for write zero requests in bytes, must be 3442# positive multiple of @align, of @opt-write-zero, and of 3443# the underlying file's request alignment (but need not 3444# be a power of 2), or 0 for default (since 2.10) 3445# 3446# @opt-discard: preferred alignment for discard requests in bytes, must 3447# be positive multiple of @align and of the underlying 3448# file's request alignment (but need not be a power of 3449# 2), or 0 for default (since 2.10) 3450# 3451# @max-discard: maximum size for discard requests in bytes, must be 3452# positive multiple of @align, of @opt-discard, and of 3453# the underlying file's request alignment (but need not 3454# be a power of 2), or 0 for default (since 2.10) 3455# 3456# @inject-error: array of error injection descriptions 3457# 3458# @set-state: array of state-change descriptions 3459# 3460# @take-child-perms: Permissions to take on @image in addition to what 3461# is necessary anyway (which depends on how the 3462# blkdebug node is used). Defaults to none. 3463# (since 5.0) 3464# 3465# @unshare-child-perms: Permissions not to share on @image in addition 3466# to what cannot be shared anyway (which depends 3467# on how the blkdebug node is used). Defaults 3468# to none. (since 5.0) 3469# 3470# Since: 2.9 3471## 3472{ 'struct': 'BlockdevOptionsBlkdebug', 3473 'data': { 'image': 'BlockdevRef', 3474 '*config': 'str', 3475 '*align': 'int', '*max-transfer': 'int32', 3476 '*opt-write-zero': 'int32', '*max-write-zero': 'int32', 3477 '*opt-discard': 'int32', '*max-discard': 'int32', 3478 '*inject-error': ['BlkdebugInjectErrorOptions'], 3479 '*set-state': ['BlkdebugSetStateOptions'], 3480 '*take-child-perms': ['BlockPermission'], 3481 '*unshare-child-perms': ['BlockPermission'] } } 3482 3483## 3484# @BlockdevOptionsBlklogwrites: 3485# 3486# Driver specific block device options for blklogwrites. 3487# 3488# @file: block device 3489# 3490# @log: block device used to log writes to @file 3491# 3492# @log-sector-size: sector size used in logging writes to @file, determines 3493# granularity of offsets and sizes of writes (default: 512) 3494# 3495# @log-append: append to an existing log (default: false) 3496# 3497# @log-super-update-interval: interval of write requests after which the log 3498# super block is updated to disk (default: 4096) 3499# 3500# Since: 3.0 3501## 3502{ 'struct': 'BlockdevOptionsBlklogwrites', 3503 'data': { 'file': 'BlockdevRef', 3504 'log': 'BlockdevRef', 3505 '*log-sector-size': 'uint32', 3506 '*log-append': 'bool', 3507 '*log-super-update-interval': 'uint64' } } 3508 3509## 3510# @BlockdevOptionsBlkverify: 3511# 3512# Driver specific block device options for blkverify. 3513# 3514# @test: block device to be tested 3515# 3516# @raw: raw image used for verification 3517# 3518# Since: 2.9 3519## 3520{ 'struct': 'BlockdevOptionsBlkverify', 3521 'data': { 'test': 'BlockdevRef', 3522 'raw': 'BlockdevRef' } } 3523 3524## 3525# @BlockdevOptionsBlkreplay: 3526# 3527# Driver specific block device options for blkreplay. 3528# 3529# @image: disk image which should be controlled with blkreplay 3530# 3531# Since: 4.2 3532## 3533{ 'struct': 'BlockdevOptionsBlkreplay', 3534 'data': { 'image': 'BlockdevRef' } } 3535 3536## 3537# @QuorumReadPattern: 3538# 3539# An enumeration of quorum read patterns. 3540# 3541# @quorum: read all the children and do a quorum vote on reads 3542# 3543# @fifo: read only from the first child that has not failed 3544# 3545# Since: 2.9 3546## 3547{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] } 3548 3549## 3550# @BlockdevOptionsQuorum: 3551# 3552# Driver specific block device options for Quorum 3553# 3554# @blkverify: true if the driver must print content mismatch 3555# set to false by default 3556# 3557# @children: the children block devices to use 3558# 3559# @vote-threshold: the vote limit under which a read will fail 3560# 3561# @rewrite-corrupted: rewrite corrupted data when quorum is reached 3562# (Since 2.1) 3563# 3564# @read-pattern: choose read pattern and set to quorum by default 3565# (Since 2.2) 3566# 3567# Since: 2.9 3568## 3569{ 'struct': 'BlockdevOptionsQuorum', 3570 'data': { '*blkverify': 'bool', 3571 'children': [ 'BlockdevRef' ], 3572 'vote-threshold': 'int', 3573 '*rewrite-corrupted': 'bool', 3574 '*read-pattern': 'QuorumReadPattern' } } 3575 3576## 3577# @BlockdevOptionsGluster: 3578# 3579# Driver specific block device options for Gluster 3580# 3581# @volume: name of gluster volume where VM image resides 3582# 3583# @path: absolute path to image file in gluster volume 3584# 3585# @server: gluster servers description 3586# 3587# @debug: libgfapi log level (default '4' which is Error) 3588# (Since 2.8) 3589# 3590# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8) 3591# 3592# Since: 2.9 3593## 3594{ 'struct': 'BlockdevOptionsGluster', 3595 'data': { 'volume': 'str', 3596 'path': 'str', 3597 'server': ['SocketAddress'], 3598 '*debug': 'int', 3599 '*logfile': 'str' } } 3600 3601## 3602# @IscsiTransport: 3603# 3604# An enumeration of libiscsi transport types 3605# 3606# Since: 2.9 3607## 3608{ 'enum': 'IscsiTransport', 3609 'data': [ 'tcp', 'iser' ] } 3610 3611## 3612# @IscsiHeaderDigest: 3613# 3614# An enumeration of header digests supported by libiscsi 3615# 3616# Since: 2.9 3617## 3618{ 'enum': 'IscsiHeaderDigest', 3619 'prefix': 'QAPI_ISCSI_HEADER_DIGEST', 3620 'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] } 3621 3622## 3623# @BlockdevOptionsIscsi: 3624# 3625# @transport: The iscsi transport type 3626# 3627# @portal: The address of the iscsi portal 3628# 3629# @target: The target iqn name 3630# 3631# @lun: LUN to connect to. Defaults to 0. 3632# 3633# @user: User name to log in with. If omitted, no CHAP 3634# authentication is performed. 3635# 3636# @password-secret: The ID of a QCryptoSecret object providing 3637# the password for the login. This option is required if 3638# @user is specified. 3639# 3640# @initiator-name: The iqn name we want to identify to the target 3641# as. If this option is not specified, an initiator name is 3642# generated automatically. 3643# 3644# @header-digest: The desired header digest. Defaults to 3645# none-crc32c. 3646# 3647# @timeout: Timeout in seconds after which a request will 3648# timeout. 0 means no timeout and is the default. 3649# 3650# Driver specific block device options for iscsi 3651# 3652# Since: 2.9 3653## 3654{ 'struct': 'BlockdevOptionsIscsi', 3655 'data': { 'transport': 'IscsiTransport', 3656 'portal': 'str', 3657 'target': 'str', 3658 '*lun': 'int', 3659 '*user': 'str', 3660 '*password-secret': 'str', 3661 '*initiator-name': 'str', 3662 '*header-digest': 'IscsiHeaderDigest', 3663 '*timeout': 'int' } } 3664 3665 3666## 3667# @RbdAuthMode: 3668# 3669# Since: 3.0 3670## 3671{ 'enum': 'RbdAuthMode', 3672 'data': [ 'cephx', 'none' ] } 3673 3674## 3675# @BlockdevOptionsRbd: 3676# 3677# @pool: Ceph pool name. 3678# 3679# @image: Image name in the Ceph pool. 3680# 3681# @conf: path to Ceph configuration file. Values 3682# in the configuration file will be overridden by 3683# options specified via QAPI. 3684# 3685# @snapshot: Ceph snapshot name. 3686# 3687# @user: Ceph id name. 3688# 3689# @auth-client-required: Acceptable authentication modes. 3690# This maps to Ceph configuration option 3691# "auth_client_required". (Since 3.0) 3692# 3693# @key-secret: ID of a QCryptoSecret object providing a key 3694# for cephx authentication. 3695# This maps to Ceph configuration option 3696# "key". (Since 3.0) 3697# 3698# @server: Monitor host address and port. This maps 3699# to the "mon_host" Ceph option. 3700# 3701# Since: 2.9 3702## 3703{ 'struct': 'BlockdevOptionsRbd', 3704 'data': { 'pool': 'str', 3705 'image': 'str', 3706 '*conf': 'str', 3707 '*snapshot': 'str', 3708 '*user': 'str', 3709 '*auth-client-required': ['RbdAuthMode'], 3710 '*key-secret': 'str', 3711 '*server': ['InetSocketAddressBase'] } } 3712 3713## 3714# @BlockdevOptionsSheepdog: 3715# 3716# Driver specific block device options for sheepdog 3717# 3718# @vdi: Virtual disk image name 3719# @server: The Sheepdog server to connect to 3720# @snap-id: Snapshot ID 3721# @tag: Snapshot tag name 3722# 3723# Only one of @snap-id and @tag may be present. 3724# 3725# Since: 2.9 3726## 3727{ 'struct': 'BlockdevOptionsSheepdog', 3728 'data': { 'server': 'SocketAddress', 3729 'vdi': 'str', 3730 '*snap-id': 'uint32', 3731 '*tag': 'str' } } 3732 3733## 3734# @ReplicationMode: 3735# 3736# An enumeration of replication modes. 3737# 3738# @primary: Primary mode, the vm's state will be sent to secondary QEMU. 3739# 3740# @secondary: Secondary mode, receive the vm's state from primary QEMU. 3741# 3742# Since: 2.9 3743## 3744{ 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ], 3745 'if': 'defined(CONFIG_REPLICATION)' } 3746 3747## 3748# @BlockdevOptionsReplication: 3749# 3750# Driver specific block device options for replication 3751# 3752# @mode: the replication mode 3753# 3754# @top-id: In secondary mode, node name or device ID of the root 3755# node who owns the replication node chain. Must not be given in 3756# primary mode. 3757# 3758# Since: 2.9 3759## 3760{ 'struct': 'BlockdevOptionsReplication', 3761 'base': 'BlockdevOptionsGenericFormat', 3762 'data': { 'mode': 'ReplicationMode', 3763 '*top-id': 'str' }, 3764 'if': 'defined(CONFIG_REPLICATION)' } 3765 3766## 3767# @NFSTransport: 3768# 3769# An enumeration of NFS transport types 3770# 3771# @inet: TCP transport 3772# 3773# Since: 2.9 3774## 3775{ 'enum': 'NFSTransport', 3776 'data': [ 'inet' ] } 3777 3778## 3779# @NFSServer: 3780# 3781# Captures the address of the socket 3782# 3783# @type: transport type used for NFS (only TCP supported) 3784# 3785# @host: host address for NFS server 3786# 3787# Since: 2.9 3788## 3789{ 'struct': 'NFSServer', 3790 'data': { 'type': 'NFSTransport', 3791 'host': 'str' } } 3792 3793## 3794# @BlockdevOptionsNfs: 3795# 3796# Driver specific block device option for NFS 3797# 3798# @server: host address 3799# 3800# @path: path of the image on the host 3801# 3802# @user: UID value to use when talking to the 3803# server (defaults to 65534 on Windows and getuid() 3804# on unix) 3805# 3806# @group: GID value to use when talking to the 3807# server (defaults to 65534 on Windows and getgid() 3808# in unix) 3809# 3810# @tcp-syn-count: number of SYNs during the session 3811# establishment (defaults to libnfs default) 3812# 3813# @readahead-size: set the readahead size in bytes (defaults 3814# to libnfs default) 3815# 3816# @page-cache-size: set the pagecache size in bytes (defaults 3817# to libnfs default) 3818# 3819# @debug: set the NFS debug level (max 2) (defaults 3820# to libnfs default) 3821# 3822# Since: 2.9 3823## 3824{ 'struct': 'BlockdevOptionsNfs', 3825 'data': { 'server': 'NFSServer', 3826 'path': 'str', 3827 '*user': 'int', 3828 '*group': 'int', 3829 '*tcp-syn-count': 'int', 3830 '*readahead-size': 'int', 3831 '*page-cache-size': 'int', 3832 '*debug': 'int' } } 3833 3834## 3835# @BlockdevOptionsCurlBase: 3836# 3837# Driver specific block device options shared by all protocols supported by the 3838# curl backend. 3839# 3840# @url: URL of the image file 3841# 3842# @readahead: Size of the read-ahead cache; must be a multiple of 3843# 512 (defaults to 256 kB) 3844# 3845# @timeout: Timeout for connections, in seconds (defaults to 5) 3846# 3847# @username: Username for authentication (defaults to none) 3848# 3849# @password-secret: ID of a QCryptoSecret object providing a password 3850# for authentication (defaults to no password) 3851# 3852# @proxy-username: Username for proxy authentication (defaults to none) 3853# 3854# @proxy-password-secret: ID of a QCryptoSecret object providing a password 3855# for proxy authentication (defaults to no password) 3856# 3857# Since: 2.9 3858## 3859{ 'struct': 'BlockdevOptionsCurlBase', 3860 'data': { 'url': 'str', 3861 '*readahead': 'int', 3862 '*timeout': 'int', 3863 '*username': 'str', 3864 '*password-secret': 'str', 3865 '*proxy-username': 'str', 3866 '*proxy-password-secret': 'str' } } 3867 3868## 3869# @BlockdevOptionsCurlHttp: 3870# 3871# Driver specific block device options for HTTP connections over the curl 3872# backend. URLs must start with "http://". 3873# 3874# @cookie: List of cookies to set; format is 3875# "name1=content1; name2=content2;" as explained by 3876# CURLOPT_COOKIE(3). Defaults to no cookies. 3877# 3878# @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a 3879# secure way. See @cookie for the format. (since 2.10) 3880# 3881# Since: 2.9 3882## 3883{ 'struct': 'BlockdevOptionsCurlHttp', 3884 'base': 'BlockdevOptionsCurlBase', 3885 'data': { '*cookie': 'str', 3886 '*cookie-secret': 'str'} } 3887 3888## 3889# @BlockdevOptionsCurlHttps: 3890# 3891# Driver specific block device options for HTTPS connections over the curl 3892# backend. URLs must start with "https://". 3893# 3894# @cookie: List of cookies to set; format is 3895# "name1=content1; name2=content2;" as explained by 3896# CURLOPT_COOKIE(3). Defaults to no cookies. 3897# 3898# @sslverify: Whether to verify the SSL certificate's validity (defaults to 3899# true) 3900# 3901# @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a 3902# secure way. See @cookie for the format. (since 2.10) 3903# 3904# Since: 2.9 3905## 3906{ 'struct': 'BlockdevOptionsCurlHttps', 3907 'base': 'BlockdevOptionsCurlBase', 3908 'data': { '*cookie': 'str', 3909 '*sslverify': 'bool', 3910 '*cookie-secret': 'str'} } 3911 3912## 3913# @BlockdevOptionsCurlFtp: 3914# 3915# Driver specific block device options for FTP connections over the curl 3916# backend. URLs must start with "ftp://". 3917# 3918# Since: 2.9 3919## 3920{ 'struct': 'BlockdevOptionsCurlFtp', 3921 'base': 'BlockdevOptionsCurlBase', 3922 'data': { } } 3923 3924## 3925# @BlockdevOptionsCurlFtps: 3926# 3927# Driver specific block device options for FTPS connections over the curl 3928# backend. URLs must start with "ftps://". 3929# 3930# @sslverify: Whether to verify the SSL certificate's validity (defaults to 3931# true) 3932# 3933# Since: 2.9 3934## 3935{ 'struct': 'BlockdevOptionsCurlFtps', 3936 'base': 'BlockdevOptionsCurlBase', 3937 'data': { '*sslverify': 'bool' } } 3938 3939## 3940# @BlockdevOptionsNbd: 3941# 3942# Driver specific block device options for NBD. 3943# 3944# @server: NBD server address 3945# 3946# @export: export name 3947# 3948# @tls-creds: TLS credentials ID 3949# 3950# @x-dirty-bitmap: A "qemu:dirty-bitmap:NAME" string to query in place of 3951# traditional "base:allocation" block status (see 3952# NBD_OPT_LIST_META_CONTEXT in the NBD protocol) (since 3.0) 3953# 3954# @reconnect-delay: On an unexpected disconnect, the nbd client tries to 3955# connect again until succeeding or encountering a serious 3956# error. During the first @reconnect-delay seconds, all 3957# requests are paused and will be rerun on a successful 3958# reconnect. After that time, any delayed requests and all 3959# future requests before a successful reconnect will 3960# immediately fail. Default 0 (Since 4.2) 3961# 3962# Since: 2.9 3963## 3964{ 'struct': 'BlockdevOptionsNbd', 3965 'data': { 'server': 'SocketAddress', 3966 '*export': 'str', 3967 '*tls-creds': 'str', 3968 '*x-dirty-bitmap': 'str', 3969 '*reconnect-delay': 'uint32' } } 3970 3971## 3972# @BlockdevOptionsRaw: 3973# 3974# Driver specific block device options for the raw driver. 3975# 3976# @offset: position where the block device starts 3977# @size: the assumed size of the device 3978# 3979# Since: 2.9 3980## 3981{ 'struct': 'BlockdevOptionsRaw', 3982 'base': 'BlockdevOptionsGenericFormat', 3983 'data': { '*offset': 'int', '*size': 'int' } } 3984 3985## 3986# @BlockdevOptionsVxHS: 3987# 3988# Driver specific block device options for VxHS 3989# 3990# @vdisk-id: UUID of VxHS volume 3991# @server: vxhs server IP, port 3992# @tls-creds: TLS credentials ID 3993# 3994# Since: 2.10 3995## 3996{ 'struct': 'BlockdevOptionsVxHS', 3997 'data': { 'vdisk-id': 'str', 3998 'server': 'InetSocketAddressBase', 3999 '*tls-creds': 'str' } } 4000 4001## 4002# @BlockdevOptionsThrottle: 4003# 4004# Driver specific block device options for the throttle driver 4005# 4006# @throttle-group: the name of the throttle-group object to use. It 4007# must already exist. 4008# @file: reference to or definition of the data source block device 4009# Since: 2.11 4010## 4011{ 'struct': 'BlockdevOptionsThrottle', 4012 'data': { 'throttle-group': 'str', 4013 'file' : 'BlockdevRef' 4014 } } 4015## 4016# @BlockdevOptions: 4017# 4018# Options for creating a block device. Many options are available for all 4019# block devices, independent of the block driver: 4020# 4021# @driver: block driver name 4022# @node-name: the node name of the new node (Since 2.0). 4023# This option is required on the top level of blockdev-add. 4024# Valid node names start with an alphabetic character and may 4025# contain only alphanumeric characters, '-', '.' and '_'. Their 4026# maximum length is 31 characters. 4027# @discard: discard-related options (default: ignore) 4028# @cache: cache-related options 4029# @read-only: whether the block device should be read-only (default: false). 4030# Note that some block drivers support only read-only access, 4031# either generally or in certain configurations. In this case, 4032# the default value does not work and the option must be 4033# specified explicitly. 4034# @auto-read-only: if true and @read-only is false, QEMU may automatically 4035# decide not to open the image read-write as requested, but 4036# fall back to read-only instead (and switch between the modes 4037# later), e.g. depending on whether the image file is writable 4038# or whether a writing user is attached to the node 4039# (default: false, since 3.1) 4040# @detect-zeroes: detect and optimize zero writes (Since 2.1) 4041# (default: off) 4042# @force-share: force share all permission on added nodes. 4043# Requires read-only=true. (Since 2.10) 4044# 4045# Remaining options are determined by the block driver. 4046# 4047# Since: 2.9 4048## 4049{ 'union': 'BlockdevOptions', 4050 'base': { 'driver': 'BlockdevDriver', 4051 '*node-name': 'str', 4052 '*discard': 'BlockdevDiscardOptions', 4053 '*cache': 'BlockdevCacheOptions', 4054 '*read-only': 'bool', 4055 '*auto-read-only': 'bool', 4056 '*force-share': 'bool', 4057 '*detect-zeroes': 'BlockdevDetectZeroesOptions' }, 4058 'discriminator': 'driver', 4059 'data': { 4060 'blkdebug': 'BlockdevOptionsBlkdebug', 4061 'blklogwrites':'BlockdevOptionsBlklogwrites', 4062 'blkverify': 'BlockdevOptionsBlkverify', 4063 'blkreplay': 'BlockdevOptionsBlkreplay', 4064 'bochs': 'BlockdevOptionsGenericFormat', 4065 'cloop': 'BlockdevOptionsGenericFormat', 4066 'compress': 'BlockdevOptionsGenericFormat', 4067 'copy-on-read':'BlockdevOptionsGenericFormat', 4068 'dmg': 'BlockdevOptionsGenericFormat', 4069 'file': 'BlockdevOptionsFile', 4070 'ftp': 'BlockdevOptionsCurlFtp', 4071 'ftps': 'BlockdevOptionsCurlFtps', 4072 'gluster': 'BlockdevOptionsGluster', 4073 'host_cdrom': 'BlockdevOptionsFile', 4074 'host_device':'BlockdevOptionsFile', 4075 'http': 'BlockdevOptionsCurlHttp', 4076 'https': 'BlockdevOptionsCurlHttps', 4077 'iscsi': 'BlockdevOptionsIscsi', 4078 'luks': 'BlockdevOptionsLUKS', 4079 'nbd': 'BlockdevOptionsNbd', 4080 'nfs': 'BlockdevOptionsNfs', 4081 'null-aio': 'BlockdevOptionsNull', 4082 'null-co': 'BlockdevOptionsNull', 4083 'nvme': 'BlockdevOptionsNVMe', 4084 'parallels': 'BlockdevOptionsGenericFormat', 4085 'qcow2': 'BlockdevOptionsQcow2', 4086 'qcow': 'BlockdevOptionsQcow', 4087 'qed': 'BlockdevOptionsGenericCOWFormat', 4088 'quorum': 'BlockdevOptionsQuorum', 4089 'raw': 'BlockdevOptionsRaw', 4090 'rbd': 'BlockdevOptionsRbd', 4091 'replication': { 'type': 'BlockdevOptionsReplication', 4092 'if': 'defined(CONFIG_REPLICATION)' }, 4093 'sheepdog': 'BlockdevOptionsSheepdog', 4094 'ssh': 'BlockdevOptionsSsh', 4095 'throttle': 'BlockdevOptionsThrottle', 4096 'vdi': 'BlockdevOptionsGenericFormat', 4097 'vhdx': 'BlockdevOptionsGenericFormat', 4098 'vmdk': 'BlockdevOptionsGenericCOWFormat', 4099 'vpc': 'BlockdevOptionsGenericFormat', 4100 'vvfat': 'BlockdevOptionsVVFAT', 4101 'vxhs': 'BlockdevOptionsVxHS' 4102 } } 4103 4104## 4105# @BlockdevRef: 4106# 4107# Reference to a block device. 4108# 4109# @definition: defines a new block device inline 4110# @reference: references the ID of an existing block device 4111# 4112# Since: 2.9 4113## 4114{ 'alternate': 'BlockdevRef', 4115 'data': { 'definition': 'BlockdevOptions', 4116 'reference': 'str' } } 4117 4118## 4119# @BlockdevRefOrNull: 4120# 4121# Reference to a block device. 4122# 4123# @definition: defines a new block device inline 4124# @reference: references the ID of an existing block device. 4125# An empty string means that no block device should 4126# be referenced. Deprecated; use null instead. 4127# @null: No block device should be referenced (since 2.10) 4128# 4129# Since: 2.9 4130## 4131{ 'alternate': 'BlockdevRefOrNull', 4132 'data': { 'definition': 'BlockdevOptions', 4133 'reference': 'str', 4134 'null': 'null' } } 4135 4136## 4137# @blockdev-add: 4138# 4139# Creates a new block device. If the @id option is given at the top level, a 4140# BlockBackend will be created; otherwise, @node-name is mandatory at the top 4141# level and no BlockBackend will be created. 4142# 4143# Since: 2.9 4144# 4145# Example: 4146# 4147# 1. 4148# -> { "execute": "blockdev-add", 4149# "arguments": { 4150# "driver": "qcow2", 4151# "node-name": "test1", 4152# "file": { 4153# "driver": "file", 4154# "filename": "test.qcow2" 4155# } 4156# } 4157# } 4158# <- { "return": {} } 4159# 4160# 2. 4161# -> { "execute": "blockdev-add", 4162# "arguments": { 4163# "driver": "qcow2", 4164# "node-name": "node0", 4165# "discard": "unmap", 4166# "cache": { 4167# "direct": true 4168# }, 4169# "file": { 4170# "driver": "file", 4171# "filename": "/tmp/test.qcow2" 4172# }, 4173# "backing": { 4174# "driver": "raw", 4175# "file": { 4176# "driver": "file", 4177# "filename": "/dev/fdset/4" 4178# } 4179# } 4180# } 4181# } 4182# 4183# <- { "return": {} } 4184# 4185## 4186{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true } 4187 4188## 4189# @x-blockdev-reopen: 4190# 4191# Reopens a block device using the given set of options. Any option 4192# not specified will be reset to its default value regardless of its 4193# previous status. If an option cannot be changed or a particular 4194# driver does not support reopening then the command will return an 4195# error. 4196# 4197# The top-level @node-name option (from BlockdevOptions) must be 4198# specified and is used to select the block device to be reopened. 4199# Other @node-name options must be either omitted or set to the 4200# current name of the appropriate node. This command won't change any 4201# node name and any attempt to do it will result in an error. 4202# 4203# In the case of options that refer to child nodes, the behavior of 4204# this command depends on the value: 4205# 4206# 1) A set of options (BlockdevOptions): the child is reopened with 4207# the specified set of options. 4208# 4209# 2) A reference to the current child: the child is reopened using 4210# its existing set of options. 4211# 4212# 3) A reference to a different node: the current child is replaced 4213# with the specified one. 4214# 4215# 4) NULL: the current child (if any) is detached. 4216# 4217# Options (1) and (2) are supported in all cases, but at the moment 4218# only @backing allows replacing or detaching an existing child. 4219# 4220# Unlike with blockdev-add, the @backing option must always be present 4221# unless the node being reopened does not have a backing file and its 4222# image does not have a default backing file name as part of its 4223# metadata. 4224# 4225# Since: 4.0 4226## 4227{ 'command': 'x-blockdev-reopen', 4228 'data': 'BlockdevOptions', 'boxed': true } 4229 4230## 4231# @blockdev-del: 4232# 4233# Deletes a block device that has been added using blockdev-add. 4234# The command will fail if the node is attached to a device or is 4235# otherwise being used. 4236# 4237# @node-name: Name of the graph node to delete. 4238# 4239# Since: 2.9 4240# 4241# Example: 4242# 4243# -> { "execute": "blockdev-add", 4244# "arguments": { 4245# "driver": "qcow2", 4246# "node-name": "node0", 4247# "file": { 4248# "driver": "file", 4249# "filename": "test.qcow2" 4250# } 4251# } 4252# } 4253# <- { "return": {} } 4254# 4255# -> { "execute": "blockdev-del", 4256# "arguments": { "node-name": "node0" } 4257# } 4258# <- { "return": {} } 4259# 4260## 4261{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' } } 4262 4263## 4264# @BlockdevCreateOptionsFile: 4265# 4266# Driver specific image creation options for file. 4267# 4268# @filename: Filename for the new image file 4269# @size: Size of the virtual disk in bytes 4270# @preallocation: Preallocation mode for the new image (default: off; 4271# allowed values: off, 4272# falloc (if defined CONFIG_POSIX_FALLOCATE), 4273# full (if defined CONFIG_POSIX)) 4274# @nocow: Turn off copy-on-write (valid only on btrfs; default: off) 4275# 4276# Since: 2.12 4277## 4278{ 'struct': 'BlockdevCreateOptionsFile', 4279 'data': { 'filename': 'str', 4280 'size': 'size', 4281 '*preallocation': 'PreallocMode', 4282 '*nocow': 'bool' } } 4283 4284## 4285# @BlockdevCreateOptionsGluster: 4286# 4287# Driver specific image creation options for gluster. 4288# 4289# @location: Where to store the new image file 4290# @size: Size of the virtual disk in bytes 4291# @preallocation: Preallocation mode for the new image (default: off; 4292# allowed values: off, 4293# falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), 4294# full (if defined CONFIG_GLUSTERFS_ZEROFILL)) 4295# 4296# Since: 2.12 4297## 4298{ 'struct': 'BlockdevCreateOptionsGluster', 4299 'data': { 'location': 'BlockdevOptionsGluster', 4300 'size': 'size', 4301 '*preallocation': 'PreallocMode' } } 4302 4303## 4304# @BlockdevCreateOptionsLUKS: 4305# 4306# Driver specific image creation options for LUKS. 4307# 4308# @file: Node to create the image format on 4309# @size: Size of the virtual disk in bytes 4310# @preallocation: Preallocation mode for the new image 4311# (since: 4.2) 4312# (default: off; allowed values: off, metadata, falloc, full) 4313# 4314# Since: 2.12 4315## 4316{ 'struct': 'BlockdevCreateOptionsLUKS', 4317 'base': 'QCryptoBlockCreateOptionsLUKS', 4318 'data': { 'file': 'BlockdevRef', 4319 'size': 'size', 4320 '*preallocation': 'PreallocMode' } } 4321 4322## 4323# @BlockdevCreateOptionsNfs: 4324# 4325# Driver specific image creation options for NFS. 4326# 4327# @location: Where to store the new image file 4328# @size: Size of the virtual disk in bytes 4329# 4330# Since: 2.12 4331## 4332{ 'struct': 'BlockdevCreateOptionsNfs', 4333 'data': { 'location': 'BlockdevOptionsNfs', 4334 'size': 'size' } } 4335 4336## 4337# @BlockdevCreateOptionsParallels: 4338# 4339# Driver specific image creation options for parallels. 4340# 4341# @file: Node to create the image format on 4342# @size: Size of the virtual disk in bytes 4343# @cluster-size: Cluster size in bytes (default: 1 MB) 4344# 4345# Since: 2.12 4346## 4347{ 'struct': 'BlockdevCreateOptionsParallels', 4348 'data': { 'file': 'BlockdevRef', 4349 'size': 'size', 4350 '*cluster-size': 'size' } } 4351 4352## 4353# @BlockdevCreateOptionsQcow: 4354# 4355# Driver specific image creation options for qcow. 4356# 4357# @file: Node to create the image format on 4358# @size: Size of the virtual disk in bytes 4359# @backing-file: File name of the backing file if a backing file 4360# should be used 4361# @encrypt: Encryption options if the image should be encrypted 4362# 4363# Since: 2.12 4364## 4365{ 'struct': 'BlockdevCreateOptionsQcow', 4366 'data': { 'file': 'BlockdevRef', 4367 'size': 'size', 4368 '*backing-file': 'str', 4369 '*encrypt': 'QCryptoBlockCreateOptions' } } 4370 4371## 4372# @BlockdevQcow2Version: 4373# 4374# @v2: The original QCOW2 format as introduced in qemu 0.10 (version 2) 4375# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) 4376# 4377# Since: 2.12 4378## 4379{ 'enum': 'BlockdevQcow2Version', 4380 'data': [ 'v2', 'v3' ] } 4381 4382 4383## 4384# @BlockdevCreateOptionsQcow2: 4385# 4386# Driver specific image creation options for qcow2. 4387# 4388# @file: Node to create the image format on 4389# @data-file: Node to use as an external data file in which all guest 4390# data is stored so that only metadata remains in the qcow2 4391# file (since: 4.0) 4392# @data-file-raw: True if the external data file must stay valid as a 4393# standalone (read-only) raw image without looking at qcow2 4394# metadata (default: false; since: 4.0) 4395# @size: Size of the virtual disk in bytes 4396# @version: Compatibility level (default: v3) 4397# @backing-file: File name of the backing file if a backing file 4398# should be used 4399# @backing-fmt: Name of the block driver to use for the backing file 4400# @encrypt: Encryption options if the image should be encrypted 4401# @cluster-size: qcow2 cluster size in bytes (default: 65536) 4402# @preallocation: Preallocation mode for the new image (default: off; 4403# allowed values: off, falloc, full, metadata) 4404# @lazy-refcounts: True if refcounts may be updated lazily (default: off) 4405# @refcount-bits: Width of reference counts in bits (default: 16) 4406# 4407# Since: 2.12 4408## 4409{ 'struct': 'BlockdevCreateOptionsQcow2', 4410 'data': { 'file': 'BlockdevRef', 4411 '*data-file': 'BlockdevRef', 4412 '*data-file-raw': 'bool', 4413 'size': 'size', 4414 '*version': 'BlockdevQcow2Version', 4415 '*backing-file': 'str', 4416 '*backing-fmt': 'BlockdevDriver', 4417 '*encrypt': 'QCryptoBlockCreateOptions', 4418 '*cluster-size': 'size', 4419 '*preallocation': 'PreallocMode', 4420 '*lazy-refcounts': 'bool', 4421 '*refcount-bits': 'int' } } 4422 4423## 4424# @BlockdevCreateOptionsQed: 4425# 4426# Driver specific image creation options for qed. 4427# 4428# @file: Node to create the image format on 4429# @size: Size of the virtual disk in bytes 4430# @backing-file: File name of the backing file if a backing file 4431# should be used 4432# @backing-fmt: Name of the block driver to use for the backing file 4433# @cluster-size: Cluster size in bytes (default: 65536) 4434# @table-size: L1/L2 table size (in clusters) 4435# 4436# Since: 2.12 4437## 4438{ 'struct': 'BlockdevCreateOptionsQed', 4439 'data': { 'file': 'BlockdevRef', 4440 'size': 'size', 4441 '*backing-file': 'str', 4442 '*backing-fmt': 'BlockdevDriver', 4443 '*cluster-size': 'size', 4444 '*table-size': 'int' } } 4445 4446## 4447# @BlockdevCreateOptionsRbd: 4448# 4449# Driver specific image creation options for rbd/Ceph. 4450# 4451# @location: Where to store the new image file. This location cannot 4452# point to a snapshot. 4453# @size: Size of the virtual disk in bytes 4454# @cluster-size: RBD object size 4455# 4456# Since: 2.12 4457## 4458{ 'struct': 'BlockdevCreateOptionsRbd', 4459 'data': { 'location': 'BlockdevOptionsRbd', 4460 'size': 'size', 4461 '*cluster-size' : 'size' } } 4462 4463## 4464# @BlockdevVmdkSubformat: 4465# 4466# Subformat options for VMDK images 4467# 4468# @monolithicSparse: Single file image with sparse cluster allocation 4469# 4470# @monolithicFlat: Single flat data image and a descriptor file 4471# 4472# @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA) sparse extent 4473# files, in addition to a descriptor file 4474# 4475# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat extent 4476# files, in addition to a descriptor file 4477# 4478# @streamOptimized: Single file image sparse cluster allocation, optimized 4479# for streaming over network. 4480# 4481# Since: 4.0 4482## 4483{ 'enum': 'BlockdevVmdkSubformat', 4484 'data': [ 'monolithicSparse', 'monolithicFlat', 'twoGbMaxExtentSparse', 4485 'twoGbMaxExtentFlat', 'streamOptimized'] } 4486 4487## 4488# @BlockdevVmdkAdapterType: 4489# 4490# Adapter type info for VMDK images 4491# 4492# Since: 4.0 4493## 4494{ 'enum': 'BlockdevVmdkAdapterType', 4495 'data': [ 'ide', 'buslogic', 'lsilogic', 'legacyESX'] } 4496 4497## 4498# @BlockdevCreateOptionsVmdk: 4499# 4500# Driver specific image creation options for VMDK. 4501# 4502# @file: Where to store the new image file. This refers to the image 4503# file for monolithcSparse and streamOptimized format, or the 4504# descriptor file for other formats. 4505# @size: Size of the virtual disk in bytes 4506# @extents: Where to store the data extents. Required for monolithcFlat, 4507# twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For 4508# monolithicFlat, only one entry is required; for 4509# twoGbMaxExtent* formats, the number of entries required is 4510# calculated as extent_number = virtual_size / 2GB. Providing 4511# more extents than will be used is an error. 4512# @subformat: The subformat of the VMDK image. Default: "monolithicSparse". 4513# @backing-file: The path of backing file. Default: no backing file is used. 4514# @adapter-type: The adapter type used to fill in the descriptor. Default: ide. 4515# @hwversion: Hardware version. The meaningful options are "4" or "6". 4516# Default: "4". 4517# @zeroed-grain: Whether to enable zeroed-grain feature for sparse subformats. 4518# Default: false. 4519# 4520# Since: 4.0 4521## 4522{ 'struct': 'BlockdevCreateOptionsVmdk', 4523 'data': { 'file': 'BlockdevRef', 4524 'size': 'size', 4525 '*extents': ['BlockdevRef'], 4526 '*subformat': 'BlockdevVmdkSubformat', 4527 '*backing-file': 'str', 4528 '*adapter-type': 'BlockdevVmdkAdapterType', 4529 '*hwversion': 'str', 4530 '*zeroed-grain': 'bool' } } 4531 4532 4533## 4534# @SheepdogRedundancyType: 4535# 4536# @full: Create a fully replicated vdi with x copies 4537# @erasure-coded: Create an erasure coded vdi with x data strips and 4538# y parity strips 4539# 4540# Since: 2.12 4541## 4542{ 'enum': 'SheepdogRedundancyType', 4543 'data': [ 'full', 'erasure-coded' ] } 4544 4545## 4546# @SheepdogRedundancyFull: 4547# 4548# @copies: Number of copies to use (between 1 and 31) 4549# 4550# Since: 2.12 4551## 4552{ 'struct': 'SheepdogRedundancyFull', 4553 'data': { 'copies': 'int' }} 4554 4555## 4556# @SheepdogRedundancyErasureCoded: 4557# 4558# @data-strips: Number of data strips to use (one of {2,4,8,16}) 4559# @parity-strips: Number of parity strips to use (between 1 and 15) 4560# 4561# Since: 2.12 4562## 4563{ 'struct': 'SheepdogRedundancyErasureCoded', 4564 'data': { 'data-strips': 'int', 4565 'parity-strips': 'int' }} 4566 4567## 4568# @SheepdogRedundancy: 4569# 4570# Since: 2.12 4571## 4572{ 'union': 'SheepdogRedundancy', 4573 'base': { 'type': 'SheepdogRedundancyType' }, 4574 'discriminator': 'type', 4575 'data': { 'full': 'SheepdogRedundancyFull', 4576 'erasure-coded': 'SheepdogRedundancyErasureCoded' } } 4577 4578## 4579# @BlockdevCreateOptionsSheepdog: 4580# 4581# Driver specific image creation options for Sheepdog. 4582# 4583# @location: Where to store the new image file 4584# @size: Size of the virtual disk in bytes 4585# @backing-file: File name of a base image 4586# @preallocation: Preallocation mode for the new image (default: off; 4587# allowed values: off, full) 4588# @redundancy: Redundancy of the image 4589# @object-size: Object size of the image 4590# 4591# Since: 2.12 4592## 4593{ 'struct': 'BlockdevCreateOptionsSheepdog', 4594 'data': { 'location': 'BlockdevOptionsSheepdog', 4595 'size': 'size', 4596 '*backing-file': 'str', 4597 '*preallocation': 'PreallocMode', 4598 '*redundancy': 'SheepdogRedundancy', 4599 '*object-size': 'size' } } 4600 4601## 4602# @BlockdevCreateOptionsSsh: 4603# 4604# Driver specific image creation options for SSH. 4605# 4606# @location: Where to store the new image file 4607# @size: Size of the virtual disk in bytes 4608# 4609# Since: 2.12 4610## 4611{ 'struct': 'BlockdevCreateOptionsSsh', 4612 'data': { 'location': 'BlockdevOptionsSsh', 4613 'size': 'size' } } 4614 4615## 4616# @BlockdevCreateOptionsVdi: 4617# 4618# Driver specific image creation options for VDI. 4619# 4620# @file: Node to create the image format on 4621# @size: Size of the virtual disk in bytes 4622# @preallocation: Preallocation mode for the new image (default: off; 4623# allowed values: off, metadata) 4624# 4625# Since: 2.12 4626## 4627{ 'struct': 'BlockdevCreateOptionsVdi', 4628 'data': { 'file': 'BlockdevRef', 4629 'size': 'size', 4630 '*preallocation': 'PreallocMode' } } 4631 4632## 4633# @BlockdevVhdxSubformat: 4634# 4635# @dynamic: Growing image file 4636# @fixed: Preallocated fixed-size image file 4637# 4638# Since: 2.12 4639## 4640{ 'enum': 'BlockdevVhdxSubformat', 4641 'data': [ 'dynamic', 'fixed' ] } 4642 4643## 4644# @BlockdevCreateOptionsVhdx: 4645# 4646# Driver specific image creation options for vhdx. 4647# 4648# @file: Node to create the image format on 4649# @size: Size of the virtual disk in bytes 4650# @log-size: Log size in bytes, must be a multiple of 1 MB 4651# (default: 1 MB) 4652# @block-size: Block size in bytes, must be a multiple of 1 MB and not 4653# larger than 256 MB (default: automatically choose a block 4654# size depending on the image size) 4655# @subformat: vhdx subformat (default: dynamic) 4656# @block-state-zero: Force use of payload blocks of type 'ZERO'. Non-standard, 4657# but default. Do not set to 'off' when using 'qemu-img 4658# convert' with subformat=dynamic. 4659# 4660# Since: 2.12 4661## 4662{ 'struct': 'BlockdevCreateOptionsVhdx', 4663 'data': { 'file': 'BlockdevRef', 4664 'size': 'size', 4665 '*log-size': 'size', 4666 '*block-size': 'size', 4667 '*subformat': 'BlockdevVhdxSubformat', 4668 '*block-state-zero': 'bool' } } 4669 4670## 4671# @BlockdevVpcSubformat: 4672# 4673# @dynamic: Growing image file 4674# @fixed: Preallocated fixed-size image file 4675# 4676# Since: 2.12 4677## 4678{ 'enum': 'BlockdevVpcSubformat', 4679 'data': [ 'dynamic', 'fixed' ] } 4680 4681## 4682# @BlockdevCreateOptionsVpc: 4683# 4684# Driver specific image creation options for vpc (VHD). 4685# 4686# @file: Node to create the image format on 4687# @size: Size of the virtual disk in bytes 4688# @subformat: vhdx subformat (default: dynamic) 4689# @force-size: Force use of the exact byte size instead of rounding to the 4690# next size that can be represented in CHS geometry 4691# (default: false) 4692# 4693# Since: 2.12 4694## 4695{ 'struct': 'BlockdevCreateOptionsVpc', 4696 'data': { 'file': 'BlockdevRef', 4697 'size': 'size', 4698 '*subformat': 'BlockdevVpcSubformat', 4699 '*force-size': 'bool' } } 4700 4701## 4702# @BlockdevCreateOptions: 4703# 4704# Options for creating an image format on a given node. 4705# 4706# @driver: block driver to create the image format 4707# 4708# Since: 2.12 4709## 4710{ 'union': 'BlockdevCreateOptions', 4711 'base': { 4712 'driver': 'BlockdevDriver' }, 4713 'discriminator': 'driver', 4714 'data': { 4715 'file': 'BlockdevCreateOptionsFile', 4716 'gluster': 'BlockdevCreateOptionsGluster', 4717 'luks': 'BlockdevCreateOptionsLUKS', 4718 'nfs': 'BlockdevCreateOptionsNfs', 4719 'parallels': 'BlockdevCreateOptionsParallels', 4720 'qcow': 'BlockdevCreateOptionsQcow', 4721 'qcow2': 'BlockdevCreateOptionsQcow2', 4722 'qed': 'BlockdevCreateOptionsQed', 4723 'rbd': 'BlockdevCreateOptionsRbd', 4724 'sheepdog': 'BlockdevCreateOptionsSheepdog', 4725 'ssh': 'BlockdevCreateOptionsSsh', 4726 'vdi': 'BlockdevCreateOptionsVdi', 4727 'vhdx': 'BlockdevCreateOptionsVhdx', 4728 'vmdk': 'BlockdevCreateOptionsVmdk', 4729 'vpc': 'BlockdevCreateOptionsVpc' 4730 } } 4731 4732## 4733# @blockdev-create: 4734# 4735# Starts a job to create an image format on a given node. The job is 4736# automatically finalized, but a manual job-dismiss is required. 4737# 4738# @job-id: Identifier for the newly created job. 4739# 4740# @options: Options for the image creation. 4741# 4742# Since: 3.0 4743## 4744{ 'command': 'blockdev-create', 4745 'data': { 'job-id': 'str', 4746 'options': 'BlockdevCreateOptions' } } 4747 4748## 4749# @blockdev-open-tray: 4750# 4751# Opens a block device's tray. If there is a block driver state tree inserted as 4752# a medium, it will become inaccessible to the guest (but it will remain 4753# associated to the block device, so closing the tray will make it accessible 4754# again). 4755# 4756# If the tray was already open before, this will be a no-op. 4757# 4758# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in 4759# which no such event will be generated, these include: 4760# 4761# - if the guest has locked the tray, @force is false and the guest does not 4762# respond to the eject request 4763# - if the BlockBackend denoted by @device does not have a guest device attached 4764# to it 4765# - if the guest device does not have an actual tray 4766# 4767# @device: Block device name (deprecated, use @id instead) 4768# 4769# @id: The name or QOM path of the guest device (since: 2.8) 4770# 4771# @force: if false (the default), an eject request will be sent to 4772# the guest if it has locked the tray (and the tray will not be opened 4773# immediately); if true, the tray will be opened regardless of whether 4774# it is locked 4775# 4776# Since: 2.5 4777# 4778# Example: 4779# 4780# -> { "execute": "blockdev-open-tray", 4781# "arguments": { "id": "ide0-1-0" } } 4782# 4783# <- { "timestamp": { "seconds": 1418751016, 4784# "microseconds": 716996 }, 4785# "event": "DEVICE_TRAY_MOVED", 4786# "data": { "device": "ide1-cd0", 4787# "id": "ide0-1-0", 4788# "tray-open": true } } 4789# 4790# <- { "return": {} } 4791# 4792## 4793{ 'command': 'blockdev-open-tray', 4794 'data': { '*device': 'str', 4795 '*id': 'str', 4796 '*force': 'bool' } } 4797 4798## 4799# @blockdev-close-tray: 4800# 4801# Closes a block device's tray. If there is a block driver state tree associated 4802# with the block device (which is currently ejected), that tree will be loaded 4803# as the medium. 4804# 4805# If the tray was already closed before, this will be a no-op. 4806# 4807# @device: Block device name (deprecated, use @id instead) 4808# 4809# @id: The name or QOM path of the guest device (since: 2.8) 4810# 4811# Since: 2.5 4812# 4813# Example: 4814# 4815# -> { "execute": "blockdev-close-tray", 4816# "arguments": { "id": "ide0-1-0" } } 4817# 4818# <- { "timestamp": { "seconds": 1418751345, 4819# "microseconds": 272147 }, 4820# "event": "DEVICE_TRAY_MOVED", 4821# "data": { "device": "ide1-cd0", 4822# "id": "ide0-1-0", 4823# "tray-open": false } } 4824# 4825# <- { "return": {} } 4826# 4827## 4828{ 'command': 'blockdev-close-tray', 4829 'data': { '*device': 'str', 4830 '*id': 'str' } } 4831 4832## 4833# @blockdev-remove-medium: 4834# 4835# Removes a medium (a block driver state tree) from a block device. That block 4836# device's tray must currently be open (unless there is no attached guest 4837# device). 4838# 4839# If the tray is open and there is no medium inserted, this will be a no-op. 4840# 4841# @id: The name or QOM path of the guest device 4842# 4843# Since: 2.12 4844# 4845# Example: 4846# 4847# -> { "execute": "blockdev-remove-medium", 4848# "arguments": { "id": "ide0-1-0" } } 4849# 4850# <- { "error": { "class": "GenericError", 4851# "desc": "Tray of device 'ide0-1-0' is not open" } } 4852# 4853# -> { "execute": "blockdev-open-tray", 4854# "arguments": { "id": "ide0-1-0" } } 4855# 4856# <- { "timestamp": { "seconds": 1418751627, 4857# "microseconds": 549958 }, 4858# "event": "DEVICE_TRAY_MOVED", 4859# "data": { "device": "ide1-cd0", 4860# "id": "ide0-1-0", 4861# "tray-open": true } } 4862# 4863# <- { "return": {} } 4864# 4865# -> { "execute": "blockdev-remove-medium", 4866# "arguments": { "id": "ide0-1-0" } } 4867# 4868# <- { "return": {} } 4869# 4870## 4871{ 'command': 'blockdev-remove-medium', 4872 'data': { 'id': 'str' } } 4873 4874## 4875# @blockdev-insert-medium: 4876# 4877# Inserts a medium (a block driver state tree) into a block device. That block 4878# device's tray must currently be open (unless there is no attached guest 4879# device) and there must be no medium inserted already. 4880# 4881# @id: The name or QOM path of the guest device 4882# 4883# @node-name: name of a node in the block driver state graph 4884# 4885# Since: 2.12 4886# 4887# Example: 4888# 4889# -> { "execute": "blockdev-add", 4890# "arguments": { 4891# "node-name": "node0", 4892# "driver": "raw", 4893# "file": { "driver": "file", 4894# "filename": "fedora.iso" } } } 4895# <- { "return": {} } 4896# 4897# -> { "execute": "blockdev-insert-medium", 4898# "arguments": { "id": "ide0-1-0", 4899# "node-name": "node0" } } 4900# 4901# <- { "return": {} } 4902# 4903## 4904{ 'command': 'blockdev-insert-medium', 4905 'data': { 'id': 'str', 4906 'node-name': 'str'} } 4907 4908 4909## 4910# @BlockdevChangeReadOnlyMode: 4911# 4912# Specifies the new read-only mode of a block device subject to the 4913# @blockdev-change-medium command. 4914# 4915# @retain: Retains the current read-only mode 4916# 4917# @read-only: Makes the device read-only 4918# 4919# @read-write: Makes the device writable 4920# 4921# Since: 2.3 4922# 4923## 4924{ 'enum': 'BlockdevChangeReadOnlyMode', 4925 'data': ['retain', 'read-only', 'read-write'] } 4926 4927 4928## 4929# @blockdev-change-medium: 4930# 4931# Changes the medium inserted into a block device by ejecting the current medium 4932# and loading a new image file which is inserted as the new medium (this command 4933# combines blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium 4934# and blockdev-close-tray). 4935# 4936# @device: Block device name (deprecated, use @id instead) 4937# 4938# @id: The name or QOM path of the guest device 4939# (since: 2.8) 4940# 4941# @filename: filename of the new image to be loaded 4942# 4943# @format: format to open the new image with (defaults to 4944# the probed format) 4945# 4946# @read-only-mode: change the read-only mode of the device; defaults 4947# to 'retain' 4948# 4949# Since: 2.5 4950# 4951# Examples: 4952# 4953# 1. Change a removable medium 4954# 4955# -> { "execute": "blockdev-change-medium", 4956# "arguments": { "id": "ide0-1-0", 4957# "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", 4958# "format": "raw" } } 4959# <- { "return": {} } 4960# 4961# 2. Load a read-only medium into a writable drive 4962# 4963# -> { "execute": "blockdev-change-medium", 4964# "arguments": { "id": "floppyA", 4965# "filename": "/srv/images/ro.img", 4966# "format": "raw", 4967# "read-only-mode": "retain" } } 4968# 4969# <- { "error": 4970# { "class": "GenericError", 4971# "desc": "Could not open '/srv/images/ro.img': Permission denied" } } 4972# 4973# -> { "execute": "blockdev-change-medium", 4974# "arguments": { "id": "floppyA", 4975# "filename": "/srv/images/ro.img", 4976# "format": "raw", 4977# "read-only-mode": "read-only" } } 4978# 4979# <- { "return": {} } 4980# 4981## 4982{ 'command': 'blockdev-change-medium', 4983 'data': { '*device': 'str', 4984 '*id': 'str', 4985 'filename': 'str', 4986 '*format': 'str', 4987 '*read-only-mode': 'BlockdevChangeReadOnlyMode' } } 4988 4989 4990## 4991# @BlockErrorAction: 4992# 4993# An enumeration of action that has been taken when a DISK I/O occurs 4994# 4995# @ignore: error has been ignored 4996# 4997# @report: error has been reported to the device 4998# 4999# @stop: error caused VM to be stopped 5000# 5001# Since: 2.1 5002## 5003{ 'enum': 'BlockErrorAction', 5004 'data': [ 'ignore', 'report', 'stop' ] } 5005 5006 5007## 5008# @BLOCK_IMAGE_CORRUPTED: 5009# 5010# Emitted when a disk image is being marked corrupt. The image can be 5011# identified by its device or node name. The 'device' field is always 5012# present for compatibility reasons, but it can be empty ("") if the 5013# image does not have a device name associated. 5014# 5015# @device: device name. This is always present for compatibility 5016# reasons, but it can be empty ("") if the image does not 5017# have a device name associated. 5018# 5019# @node-name: node name (Since: 2.4) 5020# 5021# @msg: informative message for human consumption, such as the kind of 5022# corruption being detected. It should not be parsed by machine as it is 5023# not guaranteed to be stable 5024# 5025# @offset: if the corruption resulted from an image access, this is 5026# the host's access offset into the image 5027# 5028# @size: if the corruption resulted from an image access, this is 5029# the access size 5030# 5031# @fatal: if set, the image is marked corrupt and therefore unusable after this 5032# event and must be repaired (Since 2.2; before, every 5033# BLOCK_IMAGE_CORRUPTED event was fatal) 5034# 5035# Note: If action is "stop", a STOP event will eventually follow the 5036# BLOCK_IO_ERROR event. 5037# 5038# Example: 5039# 5040# <- { "event": "BLOCK_IMAGE_CORRUPTED", 5041# "data": { "device": "ide0-hd0", "node-name": "node0", 5042# "msg": "Prevented active L1 table overwrite", "offset": 196608, 5043# "size": 65536 }, 5044# "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } 5045# 5046# Since: 1.7 5047## 5048{ 'event': 'BLOCK_IMAGE_CORRUPTED', 5049 'data': { 'device' : 'str', 5050 '*node-name' : 'str', 5051 'msg' : 'str', 5052 '*offset' : 'int', 5053 '*size' : 'int', 5054 'fatal' : 'bool' } } 5055 5056## 5057# @BLOCK_IO_ERROR: 5058# 5059# Emitted when a disk I/O error occurs 5060# 5061# @device: device name. This is always present for compatibility 5062# reasons, but it can be empty ("") if the image does not 5063# have a device name associated. 5064# 5065# @node-name: node name. Note that errors may be reported for the root node 5066# that is directly attached to a guest device rather than for the 5067# node where the error occurred. The node name is not present if 5068# the drive is empty. (Since: 2.8) 5069# 5070# @operation: I/O operation 5071# 5072# @action: action that has been taken 5073# 5074# @nospace: true if I/O error was caused due to a no-space 5075# condition. This key is only present if query-block's 5076# io-status is present, please see query-block documentation 5077# for more information (since: 2.2) 5078# 5079# @reason: human readable string describing the error cause. 5080# (This field is a debugging aid for humans, it should not 5081# be parsed by applications) (since: 2.2) 5082# 5083# Note: If action is "stop", a STOP event will eventually follow the 5084# BLOCK_IO_ERROR event 5085# 5086# Since: 0.13.0 5087# 5088# Example: 5089# 5090# <- { "event": "BLOCK_IO_ERROR", 5091# "data": { "device": "ide0-hd1", 5092# "node-name": "#block212", 5093# "operation": "write", 5094# "action": "stop" }, 5095# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5096# 5097## 5098{ 'event': 'BLOCK_IO_ERROR', 5099 'data': { 'device': 'str', '*node-name': 'str', 5100 'operation': 'IoOperationType', 5101 'action': 'BlockErrorAction', '*nospace': 'bool', 5102 'reason': 'str' } } 5103 5104## 5105# @BLOCK_JOB_COMPLETED: 5106# 5107# Emitted when a block job has completed 5108# 5109# @type: job type 5110# 5111# @device: The job identifier. Originally the device name but other 5112# values are allowed since QEMU 2.7 5113# 5114# @len: maximum progress value 5115# 5116# @offset: current progress value. On success this is equal to len. 5117# On failure this is less than len 5118# 5119# @speed: rate limit, bytes per second 5120# 5121# @error: error message. Only present on failure. This field 5122# contains a human-readable error message. There are no semantics 5123# other than that streaming has failed and clients should not try to 5124# interpret the error string 5125# 5126# Since: 1.1 5127# 5128# Example: 5129# 5130# <- { "event": "BLOCK_JOB_COMPLETED", 5131# "data": { "type": "stream", "device": "virtio-disk0", 5132# "len": 10737418240, "offset": 10737418240, 5133# "speed": 0 }, 5134# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 5135# 5136## 5137{ 'event': 'BLOCK_JOB_COMPLETED', 5138 'data': { 'type' : 'JobType', 5139 'device': 'str', 5140 'len' : 'int', 5141 'offset': 'int', 5142 'speed' : 'int', 5143 '*error': 'str' } } 5144 5145## 5146# @BLOCK_JOB_CANCELLED: 5147# 5148# Emitted when a block job has been cancelled 5149# 5150# @type: job type 5151# 5152# @device: The job identifier. Originally the device name but other 5153# values are allowed since QEMU 2.7 5154# 5155# @len: maximum progress value 5156# 5157# @offset: current progress value. On success this is equal to len. 5158# On failure this is less than len 5159# 5160# @speed: rate limit, bytes per second 5161# 5162# Since: 1.1 5163# 5164# Example: 5165# 5166# <- { "event": "BLOCK_JOB_CANCELLED", 5167# "data": { "type": "stream", "device": "virtio-disk0", 5168# "len": 10737418240, "offset": 134217728, 5169# "speed": 0 }, 5170# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 5171# 5172## 5173{ 'event': 'BLOCK_JOB_CANCELLED', 5174 'data': { 'type' : 'JobType', 5175 'device': 'str', 5176 'len' : 'int', 5177 'offset': 'int', 5178 'speed' : 'int' } } 5179 5180## 5181# @BLOCK_JOB_ERROR: 5182# 5183# Emitted when a block job encounters an error 5184# 5185# @device: The job identifier. Originally the device name but other 5186# values are allowed since QEMU 2.7 5187# 5188# @operation: I/O operation 5189# 5190# @action: action that has been taken 5191# 5192# Since: 1.3 5193# 5194# Example: 5195# 5196# <- { "event": "BLOCK_JOB_ERROR", 5197# "data": { "device": "ide0-hd1", 5198# "operation": "write", 5199# "action": "stop" }, 5200# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5201# 5202## 5203{ 'event': 'BLOCK_JOB_ERROR', 5204 'data': { 'device' : 'str', 5205 'operation': 'IoOperationType', 5206 'action' : 'BlockErrorAction' } } 5207 5208## 5209# @BLOCK_JOB_READY: 5210# 5211# Emitted when a block job is ready to complete 5212# 5213# @type: job type 5214# 5215# @device: The job identifier. Originally the device name but other 5216# values are allowed since QEMU 2.7 5217# 5218# @len: maximum progress value 5219# 5220# @offset: current progress value. On success this is equal to len. 5221# On failure this is less than len 5222# 5223# @speed: rate limit, bytes per second 5224# 5225# Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR 5226# event 5227# 5228# Since: 1.3 5229# 5230# Example: 5231# 5232# <- { "event": "BLOCK_JOB_READY", 5233# "data": { "device": "drive0", "type": "mirror", "speed": 0, 5234# "len": 2097152, "offset": 2097152 } 5235# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5236# 5237## 5238{ 'event': 'BLOCK_JOB_READY', 5239 'data': { 'type' : 'JobType', 5240 'device': 'str', 5241 'len' : 'int', 5242 'offset': 'int', 5243 'speed' : 'int' } } 5244 5245## 5246# @BLOCK_JOB_PENDING: 5247# 5248# Emitted when a block job is awaiting explicit authorization to finalize graph 5249# changes via @block-job-finalize. If this job is part of a transaction, it will 5250# not emit this event until the transaction has converged first. 5251# 5252# @type: job type 5253# 5254# @id: The job identifier. 5255# 5256# Since: 2.12 5257# 5258# Example: 5259# 5260# <- { "event": "BLOCK_JOB_WAITING", 5261# "data": { "device": "drive0", "type": "mirror" }, 5262# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5263# 5264## 5265{ 'event': 'BLOCK_JOB_PENDING', 5266 'data': { 'type' : 'JobType', 5267 'id' : 'str' } } 5268 5269## 5270# @PreallocMode: 5271# 5272# Preallocation mode of QEMU image file 5273# 5274# @off: no preallocation 5275# @metadata: preallocate only for metadata 5276# @falloc: like @full preallocation but allocate disk space by 5277# posix_fallocate() rather than writing data. 5278# @full: preallocate all data by writing it to the device to ensure 5279# disk space is really available. This data may or may not be 5280# zero, depending on the image format and storage. 5281# @full preallocation also sets up metadata correctly. 5282# 5283# Since: 2.2 5284## 5285{ 'enum': 'PreallocMode', 5286 'data': [ 'off', 'metadata', 'falloc', 'full' ] } 5287 5288## 5289# @BLOCK_WRITE_THRESHOLD: 5290# 5291# Emitted when writes on block device reaches or exceeds the 5292# configured write threshold. For thin-provisioned devices, this 5293# means the device should be extended to avoid pausing for 5294# disk exhaustion. 5295# The event is one shot. Once triggered, it needs to be 5296# re-registered with another block-set-write-threshold command. 5297# 5298# @node-name: graph node name on which the threshold was exceeded. 5299# 5300# @amount-exceeded: amount of data which exceeded the threshold, in bytes. 5301# 5302# @write-threshold: last configured threshold, in bytes. 5303# 5304# Since: 2.3 5305## 5306{ 'event': 'BLOCK_WRITE_THRESHOLD', 5307 'data': { 'node-name': 'str', 5308 'amount-exceeded': 'uint64', 5309 'write-threshold': 'uint64' } } 5310 5311## 5312# @block-set-write-threshold: 5313# 5314# Change the write threshold for a block drive. An event will be 5315# delivered if a write to this block drive crosses the configured 5316# threshold. The threshold is an offset, thus must be 5317# non-negative. Default is no write threshold. Setting the threshold 5318# to zero disables it. 5319# 5320# This is useful to transparently resize thin-provisioned drives without 5321# the guest OS noticing. 5322# 5323# @node-name: graph node name on which the threshold must be set. 5324# 5325# @write-threshold: configured threshold for the block device, bytes. 5326# Use 0 to disable the threshold. 5327# 5328# Since: 2.3 5329# 5330# Example: 5331# 5332# -> { "execute": "block-set-write-threshold", 5333# "arguments": { "node-name": "mydev", 5334# "write-threshold": 17179869184 } } 5335# <- { "return": {} } 5336# 5337## 5338{ 'command': 'block-set-write-threshold', 5339 'data': { 'node-name': 'str', 'write-threshold': 'uint64' } } 5340 5341## 5342# @x-blockdev-change: 5343# 5344# Dynamically reconfigure the block driver state graph. It can be used 5345# to add, remove, insert or replace a graph node. Currently only the 5346# Quorum driver implements this feature to add or remove its child. This 5347# is useful to fix a broken quorum child. 5348# 5349# If @node is specified, it will be inserted under @parent. @child 5350# may not be specified in this case. If both @parent and @child are 5351# specified but @node is not, @child will be detached from @parent. 5352# 5353# @parent: the id or name of the parent node. 5354# 5355# @child: the name of a child under the given parent node. 5356# 5357# @node: the name of the node that will be added. 5358# 5359# Note: this command is experimental, and its API is not stable. It 5360# does not support all kinds of operations, all kinds of children, nor 5361# all block drivers. 5362# 5363# FIXME Removing children from a quorum node means introducing gaps in the 5364# child indices. This cannot be represented in the 'children' list of 5365# BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename(). 5366# 5367# Warning: The data in a new quorum child MUST be consistent with that of 5368# the rest of the array. 5369# 5370# Since: 2.7 5371# 5372# Example: 5373# 5374# 1. Add a new node to a quorum 5375# -> { "execute": "blockdev-add", 5376# "arguments": { 5377# "driver": "raw", 5378# "node-name": "new_node", 5379# "file": { "driver": "file", 5380# "filename": "test.raw" } } } 5381# <- { "return": {} } 5382# -> { "execute": "x-blockdev-change", 5383# "arguments": { "parent": "disk1", 5384# "node": "new_node" } } 5385# <- { "return": {} } 5386# 5387# 2. Delete a quorum's node 5388# -> { "execute": "x-blockdev-change", 5389# "arguments": { "parent": "disk1", 5390# "child": "children.1" } } 5391# <- { "return": {} } 5392# 5393## 5394{ 'command': 'x-blockdev-change', 5395 'data' : { 'parent': 'str', 5396 '*child': 'str', 5397 '*node': 'str' } } 5398 5399## 5400# @x-blockdev-set-iothread: 5401# 5402# Move @node and its children into the @iothread. If @iothread is null then 5403# move @node and its children into the main loop. 5404# 5405# The node must not be attached to a BlockBackend. 5406# 5407# @node-name: the name of the block driver node 5408# 5409# @iothread: the name of the IOThread object or null for the main loop 5410# 5411# @force: true if the node and its children should be moved when a BlockBackend 5412# is already attached 5413# 5414# Note: this command is experimental and intended for test cases that need 5415# control over IOThreads only. 5416# 5417# Since: 2.12 5418# 5419# Example: 5420# 5421# 1. Move a node into an IOThread 5422# -> { "execute": "x-blockdev-set-iothread", 5423# "arguments": { "node-name": "disk1", 5424# "iothread": "iothread0" } } 5425# <- { "return": {} } 5426# 5427# 2. Move a node into the main loop 5428# -> { "execute": "x-blockdev-set-iothread", 5429# "arguments": { "node-name": "disk1", 5430# "iothread": null } } 5431# <- { "return": {} } 5432# 5433## 5434{ 'command': 'x-blockdev-set-iothread', 5435 'data' : { 'node-name': 'str', 5436 'iothread': 'StrOrNull', 5437 '*force': 'bool' } } 5438