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