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 'preallocate', '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# @BlockdevOptionsPreallocate: 3103# 3104# Filter driver intended to be inserted between format and protocol node 3105# and do preallocation in protocol node on write. 3106# 3107# @prealloc-align: on preallocation, align file length to this number, 3108# default 1048576 (1M) 3109# 3110# @prealloc-size: how much to preallocate, default 134217728 (128M) 3111# 3112# Since: 6.0 3113## 3114{ 'struct': 'BlockdevOptionsPreallocate', 3115 'base': 'BlockdevOptionsGenericFormat', 3116 'data': { '*prealloc-align': 'int', '*prealloc-size': 'int' } } 3117 3118## 3119# @BlockdevOptionsQcow2: 3120# 3121# Driver specific block device options for qcow2. 3122# 3123# @lazy-refcounts: whether to enable the lazy refcounts 3124# feature (default is taken from the image file) 3125# 3126# @pass-discard-request: whether discard requests to the qcow2 3127# device should be forwarded to the data source 3128# 3129# @pass-discard-snapshot: whether discard requests for the data source 3130# should be issued when a snapshot operation (e.g. 3131# deleting a snapshot) frees clusters in the qcow2 file 3132# 3133# @pass-discard-other: whether discard requests for the data source 3134# should be issued on other occasions where a cluster 3135# gets freed 3136# 3137# @overlap-check: which overlap checks to perform for writes 3138# to the image, defaults to 'cached' (since 2.2) 3139# 3140# @cache-size: the maximum total size of the L2 table and 3141# refcount block caches in bytes (since 2.2) 3142# 3143# @l2-cache-size: the maximum size of the L2 table cache in 3144# bytes (since 2.2) 3145# 3146# @l2-cache-entry-size: the size of each entry in the L2 cache in 3147# bytes. It must be a power of two between 512 3148# and the cluster size. The default value is 3149# the cluster size (since 2.12) 3150# 3151# @refcount-cache-size: the maximum size of the refcount block cache 3152# in bytes (since 2.2) 3153# 3154# @cache-clean-interval: clean unused entries in the L2 and refcount 3155# caches. The interval is in seconds. The default value 3156# is 600 on supporting platforms, and 0 on other 3157# platforms. 0 disables this feature. (since 2.5) 3158# 3159# @encrypt: Image decryption options. Mandatory for 3160# encrypted images, except when doing a metadata-only 3161# probe of the image. (since 2.10) 3162# 3163# @data-file: reference to or definition of the external data file. 3164# This may only be specified for images that require an 3165# external data file. If it is not specified for such 3166# an image, the data file name is loaded from the image 3167# file. (since 4.0) 3168# 3169# Since: 2.9 3170## 3171{ 'struct': 'BlockdevOptionsQcow2', 3172 'base': 'BlockdevOptionsGenericCOWFormat', 3173 'data': { '*lazy-refcounts': 'bool', 3174 '*pass-discard-request': 'bool', 3175 '*pass-discard-snapshot': 'bool', 3176 '*pass-discard-other': 'bool', 3177 '*overlap-check': 'Qcow2OverlapChecks', 3178 '*cache-size': 'int', 3179 '*l2-cache-size': 'int', 3180 '*l2-cache-entry-size': 'int', 3181 '*refcount-cache-size': 'int', 3182 '*cache-clean-interval': 'int', 3183 '*encrypt': 'BlockdevQcow2Encryption', 3184 '*data-file': 'BlockdevRef' } } 3185 3186## 3187# @SshHostKeyCheckMode: 3188# 3189# @none: Don't check the host key at all 3190# @hash: Compare the host key with a given hash 3191# @known_hosts: Check the host key against the known_hosts file 3192# 3193# Since: 2.12 3194## 3195{ 'enum': 'SshHostKeyCheckMode', 3196 'data': [ 'none', 'hash', 'known_hosts' ] } 3197 3198## 3199# @SshHostKeyCheckHashType: 3200# 3201# @md5: The given hash is an md5 hash 3202# @sha1: The given hash is an sha1 hash 3203# 3204# Since: 2.12 3205## 3206{ 'enum': 'SshHostKeyCheckHashType', 3207 'data': [ 'md5', 'sha1' ] } 3208 3209## 3210# @SshHostKeyHash: 3211# 3212# @type: The hash algorithm used for the hash 3213# @hash: The expected hash value 3214# 3215# Since: 2.12 3216## 3217{ 'struct': 'SshHostKeyHash', 3218 'data': { 'type': 'SshHostKeyCheckHashType', 3219 'hash': 'str' }} 3220 3221## 3222# @SshHostKeyCheck: 3223# 3224# Since: 2.12 3225## 3226{ 'union': 'SshHostKeyCheck', 3227 'base': { 'mode': 'SshHostKeyCheckMode' }, 3228 'discriminator': 'mode', 3229 'data': { 'hash': 'SshHostKeyHash' } } 3230 3231## 3232# @BlockdevOptionsSsh: 3233# 3234# @server: host address 3235# 3236# @path: path to the image on the host 3237# 3238# @user: user as which to connect, defaults to current 3239# local user name 3240# 3241# @host-key-check: Defines how and what to check the host key against 3242# (default: known_hosts) 3243# 3244# Since: 2.9 3245## 3246{ 'struct': 'BlockdevOptionsSsh', 3247 'data': { 'server': 'InetSocketAddress', 3248 'path': 'str', 3249 '*user': 'str', 3250 '*host-key-check': 'SshHostKeyCheck' } } 3251 3252 3253## 3254# @BlkdebugEvent: 3255# 3256# Trigger events supported by blkdebug. 3257# 3258# @l1_shrink_write_table: write zeros to the l1 table to shrink image. 3259# (since 2.11) 3260# 3261# @l1_shrink_free_l2_clusters: discard the l2 tables. (since 2.11) 3262# 3263# @cor_write: a write due to copy-on-read (since 2.11) 3264# 3265# @cluster_alloc_space: an allocation of file space for a cluster (since 4.1) 3266# 3267# @none: triggers once at creation of the blkdebug node (since 4.1) 3268# 3269# Since: 2.9 3270## 3271{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG', 3272 'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table', 3273 'l1_grow_activate_table', 'l2_load', 'l2_update', 3274 'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write', 3275 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio', 3276 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read', 3277 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update', 3278 'refblock_load', 'refblock_update', 'refblock_update_part', 3279 'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write', 3280 'refblock_alloc_write_blocks', 'refblock_alloc_write_table', 3281 'refblock_alloc_switch_table', 'cluster_alloc', 3282 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os', 3283 'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head', 3284 'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev', 3285 'pwritev_zero', 'pwritev_done', 'empty_image_prepare', 3286 'l1_shrink_write_table', 'l1_shrink_free_l2_clusters', 3287 'cor_write', 'cluster_alloc_space', 'none'] } 3288 3289## 3290# @BlkdebugIOType: 3291# 3292# Kinds of I/O that blkdebug can inject errors in. 3293# 3294# @read: .bdrv_co_preadv() 3295# 3296# @write: .bdrv_co_pwritev() 3297# 3298# @write-zeroes: .bdrv_co_pwrite_zeroes() 3299# 3300# @discard: .bdrv_co_pdiscard() 3301# 3302# @flush: .bdrv_co_flush_to_disk() 3303# 3304# @block-status: .bdrv_co_block_status() 3305# 3306# Since: 4.1 3307## 3308{ 'enum': 'BlkdebugIOType', 'prefix': 'BLKDEBUG_IO_TYPE', 3309 'data': [ 'read', 'write', 'write-zeroes', 'discard', 'flush', 3310 'block-status' ] } 3311 3312## 3313# @BlkdebugInjectErrorOptions: 3314# 3315# Describes a single error injection for blkdebug. 3316# 3317# @event: trigger event 3318# 3319# @state: the state identifier blkdebug needs to be in to 3320# actually trigger the event; defaults to "any" 3321# 3322# @iotype: the type of I/O operations on which this error should 3323# be injected; defaults to "all read, write, 3324# write-zeroes, discard, and flush operations" 3325# (since: 4.1) 3326# 3327# @errno: error identifier (errno) to be returned; defaults to 3328# EIO 3329# 3330# @sector: specifies the sector index which has to be affected 3331# in order to actually trigger the event; defaults to "any 3332# sector" 3333# 3334# @once: disables further events after this one has been 3335# triggered; defaults to false 3336# 3337# @immediately: fail immediately; defaults to false 3338# 3339# Since: 2.9 3340## 3341{ 'struct': 'BlkdebugInjectErrorOptions', 3342 'data': { 'event': 'BlkdebugEvent', 3343 '*state': 'int', 3344 '*iotype': 'BlkdebugIOType', 3345 '*errno': 'int', 3346 '*sector': 'int', 3347 '*once': 'bool', 3348 '*immediately': 'bool' } } 3349 3350## 3351# @BlkdebugSetStateOptions: 3352# 3353# Describes a single state-change event for blkdebug. 3354# 3355# @event: trigger event 3356# 3357# @state: the current state identifier blkdebug needs to be in; 3358# defaults to "any" 3359# 3360# @new_state: the state identifier blkdebug is supposed to assume if 3361# this event is triggered 3362# 3363# Since: 2.9 3364## 3365{ 'struct': 'BlkdebugSetStateOptions', 3366 'data': { 'event': 'BlkdebugEvent', 3367 '*state': 'int', 3368 'new_state': 'int' } } 3369 3370## 3371# @BlockdevOptionsBlkdebug: 3372# 3373# Driver specific block device options for blkdebug. 3374# 3375# @image: underlying raw block device (or image file) 3376# 3377# @config: filename of the configuration file 3378# 3379# @align: required alignment for requests in bytes, must be 3380# positive power of 2, or 0 for default 3381# 3382# @max-transfer: maximum size for I/O transfers in bytes, must be 3383# positive multiple of @align and of the underlying 3384# file's request alignment (but need not be a power of 3385# 2), or 0 for default (since 2.10) 3386# 3387# @opt-write-zero: preferred alignment for write zero requests in bytes, 3388# must be positive multiple of @align and of the 3389# underlying file's request alignment (but need not be a 3390# power of 2), or 0 for default (since 2.10) 3391# 3392# @max-write-zero: maximum size for write zero requests in bytes, must be 3393# positive multiple of @align, of @opt-write-zero, and of 3394# the underlying file's request alignment (but need not 3395# be a power of 2), or 0 for default (since 2.10) 3396# 3397# @opt-discard: preferred alignment for discard requests in bytes, must 3398# be positive multiple of @align and of the underlying 3399# file's request alignment (but need not be a power of 3400# 2), or 0 for default (since 2.10) 3401# 3402# @max-discard: maximum size for discard requests in bytes, must be 3403# positive multiple of @align, of @opt-discard, and of 3404# the underlying file's request alignment (but need not 3405# be a power of 2), or 0 for default (since 2.10) 3406# 3407# @inject-error: array of error injection descriptions 3408# 3409# @set-state: array of state-change descriptions 3410# 3411# @take-child-perms: Permissions to take on @image in addition to what 3412# is necessary anyway (which depends on how the 3413# blkdebug node is used). Defaults to none. 3414# (since 5.0) 3415# 3416# @unshare-child-perms: Permissions not to share on @image in addition 3417# to what cannot be shared anyway (which depends 3418# on how the blkdebug node is used). Defaults 3419# to none. (since 5.0) 3420# 3421# Since: 2.9 3422## 3423{ 'struct': 'BlockdevOptionsBlkdebug', 3424 'data': { 'image': 'BlockdevRef', 3425 '*config': 'str', 3426 '*align': 'int', '*max-transfer': 'int32', 3427 '*opt-write-zero': 'int32', '*max-write-zero': 'int32', 3428 '*opt-discard': 'int32', '*max-discard': 'int32', 3429 '*inject-error': ['BlkdebugInjectErrorOptions'], 3430 '*set-state': ['BlkdebugSetStateOptions'], 3431 '*take-child-perms': ['BlockPermission'], 3432 '*unshare-child-perms': ['BlockPermission'] } } 3433 3434## 3435# @BlockdevOptionsBlklogwrites: 3436# 3437# Driver specific block device options for blklogwrites. 3438# 3439# @file: block device 3440# 3441# @log: block device used to log writes to @file 3442# 3443# @log-sector-size: sector size used in logging writes to @file, determines 3444# granularity of offsets and sizes of writes (default: 512) 3445# 3446# @log-append: append to an existing log (default: false) 3447# 3448# @log-super-update-interval: interval of write requests after which the log 3449# super block is updated to disk (default: 4096) 3450# 3451# Since: 3.0 3452## 3453{ 'struct': 'BlockdevOptionsBlklogwrites', 3454 'data': { 'file': 'BlockdevRef', 3455 'log': 'BlockdevRef', 3456 '*log-sector-size': 'uint32', 3457 '*log-append': 'bool', 3458 '*log-super-update-interval': 'uint64' } } 3459 3460## 3461# @BlockdevOptionsBlkverify: 3462# 3463# Driver specific block device options for blkverify. 3464# 3465# @test: block device to be tested 3466# 3467# @raw: raw image used for verification 3468# 3469# Since: 2.9 3470## 3471{ 'struct': 'BlockdevOptionsBlkverify', 3472 'data': { 'test': 'BlockdevRef', 3473 'raw': 'BlockdevRef' } } 3474 3475## 3476# @BlockdevOptionsBlkreplay: 3477# 3478# Driver specific block device options for blkreplay. 3479# 3480# @image: disk image which should be controlled with blkreplay 3481# 3482# Since: 4.2 3483## 3484{ 'struct': 'BlockdevOptionsBlkreplay', 3485 'data': { 'image': 'BlockdevRef' } } 3486 3487## 3488# @QuorumReadPattern: 3489# 3490# An enumeration of quorum read patterns. 3491# 3492# @quorum: read all the children and do a quorum vote on reads 3493# 3494# @fifo: read only from the first child that has not failed 3495# 3496# Since: 2.9 3497## 3498{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] } 3499 3500## 3501# @BlockdevOptionsQuorum: 3502# 3503# Driver specific block device options for Quorum 3504# 3505# @blkverify: true if the driver must print content mismatch 3506# set to false by default 3507# 3508# @children: the children block devices to use 3509# 3510# @vote-threshold: the vote limit under which a read will fail 3511# 3512# @rewrite-corrupted: rewrite corrupted data when quorum is reached 3513# (Since 2.1) 3514# 3515# @read-pattern: choose read pattern and set to quorum by default 3516# (Since 2.2) 3517# 3518# Since: 2.9 3519## 3520{ 'struct': 'BlockdevOptionsQuorum', 3521 'data': { '*blkverify': 'bool', 3522 'children': [ 'BlockdevRef' ], 3523 'vote-threshold': 'int', 3524 '*rewrite-corrupted': 'bool', 3525 '*read-pattern': 'QuorumReadPattern' } } 3526 3527## 3528# @BlockdevOptionsGluster: 3529# 3530# Driver specific block device options for Gluster 3531# 3532# @volume: name of gluster volume where VM image resides 3533# 3534# @path: absolute path to image file in gluster volume 3535# 3536# @server: gluster servers description 3537# 3538# @debug: libgfapi log level (default '4' which is Error) 3539# (Since 2.8) 3540# 3541# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8) 3542# 3543# Since: 2.9 3544## 3545{ 'struct': 'BlockdevOptionsGluster', 3546 'data': { 'volume': 'str', 3547 'path': 'str', 3548 'server': ['SocketAddress'], 3549 '*debug': 'int', 3550 '*logfile': 'str' } } 3551 3552## 3553# @IscsiTransport: 3554# 3555# An enumeration of libiscsi transport types 3556# 3557# Since: 2.9 3558## 3559{ 'enum': 'IscsiTransport', 3560 'data': [ 'tcp', 'iser' ] } 3561 3562## 3563# @IscsiHeaderDigest: 3564# 3565# An enumeration of header digests supported by libiscsi 3566# 3567# Since: 2.9 3568## 3569{ 'enum': 'IscsiHeaderDigest', 3570 'prefix': 'QAPI_ISCSI_HEADER_DIGEST', 3571 'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] } 3572 3573## 3574# @BlockdevOptionsIscsi: 3575# 3576# @transport: The iscsi transport type 3577# 3578# @portal: The address of the iscsi portal 3579# 3580# @target: The target iqn name 3581# 3582# @lun: LUN to connect to. Defaults to 0. 3583# 3584# @user: User name to log in with. If omitted, no CHAP 3585# authentication is performed. 3586# 3587# @password-secret: The ID of a QCryptoSecret object providing 3588# the password for the login. This option is required if 3589# @user is specified. 3590# 3591# @initiator-name: The iqn name we want to identify to the target 3592# as. If this option is not specified, an initiator name is 3593# generated automatically. 3594# 3595# @header-digest: The desired header digest. Defaults to 3596# none-crc32c. 3597# 3598# @timeout: Timeout in seconds after which a request will 3599# timeout. 0 means no timeout and is the default. 3600# 3601# Driver specific block device options for iscsi 3602# 3603# Since: 2.9 3604## 3605{ 'struct': 'BlockdevOptionsIscsi', 3606 'data': { 'transport': 'IscsiTransport', 3607 'portal': 'str', 3608 'target': 'str', 3609 '*lun': 'int', 3610 '*user': 'str', 3611 '*password-secret': 'str', 3612 '*initiator-name': 'str', 3613 '*header-digest': 'IscsiHeaderDigest', 3614 '*timeout': 'int' } } 3615 3616 3617## 3618# @RbdAuthMode: 3619# 3620# Since: 3.0 3621## 3622{ 'enum': 'RbdAuthMode', 3623 'data': [ 'cephx', 'none' ] } 3624 3625## 3626# @BlockdevOptionsRbd: 3627# 3628# @pool: Ceph pool name. 3629# 3630# @namespace: Rados namespace name in the Ceph pool. (Since 5.0) 3631# 3632# @image: Image name in the Ceph pool. 3633# 3634# @conf: path to Ceph configuration file. Values 3635# in the configuration file will be overridden by 3636# options specified via QAPI. 3637# 3638# @snapshot: Ceph snapshot name. 3639# 3640# @user: Ceph id name. 3641# 3642# @auth-client-required: Acceptable authentication modes. 3643# This maps to Ceph configuration option 3644# "auth_client_required". (Since 3.0) 3645# 3646# @key-secret: ID of a QCryptoSecret object providing a key 3647# for cephx authentication. 3648# This maps to Ceph configuration option 3649# "key". (Since 3.0) 3650# 3651# @server: Monitor host address and port. This maps 3652# to the "mon_host" Ceph option. 3653# 3654# Since: 2.9 3655## 3656{ 'struct': 'BlockdevOptionsRbd', 3657 'data': { 'pool': 'str', 3658 '*namespace': 'str', 3659 'image': 'str', 3660 '*conf': 'str', 3661 '*snapshot': 'str', 3662 '*user': 'str', 3663 '*auth-client-required': ['RbdAuthMode'], 3664 '*key-secret': 'str', 3665 '*server': ['InetSocketAddressBase'] } } 3666 3667## 3668# @BlockdevOptionsSheepdog: 3669# 3670# Driver specific block device options for sheepdog 3671# 3672# @vdi: Virtual disk image name 3673# @server: The Sheepdog server to connect to 3674# @snap-id: Snapshot ID 3675# @tag: Snapshot tag name 3676# 3677# Only one of @snap-id and @tag may be present. 3678# 3679# Since: 2.9 3680## 3681{ 'struct': 'BlockdevOptionsSheepdog', 3682 'data': { 'server': 'SocketAddress', 3683 'vdi': 'str', 3684 '*snap-id': 'uint32', 3685 '*tag': 'str' } } 3686 3687## 3688# @ReplicationMode: 3689# 3690# An enumeration of replication modes. 3691# 3692# @primary: Primary mode, the vm's state will be sent to secondary QEMU. 3693# 3694# @secondary: Secondary mode, receive the vm's state from primary QEMU. 3695# 3696# Since: 2.9 3697## 3698{ 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ], 3699 'if': 'defined(CONFIG_REPLICATION)' } 3700 3701## 3702# @BlockdevOptionsReplication: 3703# 3704# Driver specific block device options for replication 3705# 3706# @mode: the replication mode 3707# 3708# @top-id: In secondary mode, node name or device ID of the root 3709# node who owns the replication node chain. Must not be given in 3710# primary mode. 3711# 3712# Since: 2.9 3713## 3714{ 'struct': 'BlockdevOptionsReplication', 3715 'base': 'BlockdevOptionsGenericFormat', 3716 'data': { 'mode': 'ReplicationMode', 3717 '*top-id': 'str' }, 3718 'if': 'defined(CONFIG_REPLICATION)' } 3719 3720## 3721# @NFSTransport: 3722# 3723# An enumeration of NFS transport types 3724# 3725# @inet: TCP transport 3726# 3727# Since: 2.9 3728## 3729{ 'enum': 'NFSTransport', 3730 'data': [ 'inet' ] } 3731 3732## 3733# @NFSServer: 3734# 3735# Captures the address of the socket 3736# 3737# @type: transport type used for NFS (only TCP supported) 3738# 3739# @host: host address for NFS server 3740# 3741# Since: 2.9 3742## 3743{ 'struct': 'NFSServer', 3744 'data': { 'type': 'NFSTransport', 3745 'host': 'str' } } 3746 3747## 3748# @BlockdevOptionsNfs: 3749# 3750# Driver specific block device option for NFS 3751# 3752# @server: host address 3753# 3754# @path: path of the image on the host 3755# 3756# @user: UID value to use when talking to the 3757# server (defaults to 65534 on Windows and getuid() 3758# on unix) 3759# 3760# @group: GID value to use when talking to the 3761# server (defaults to 65534 on Windows and getgid() 3762# in unix) 3763# 3764# @tcp-syn-count: number of SYNs during the session 3765# establishment (defaults to libnfs default) 3766# 3767# @readahead-size: set the readahead size in bytes (defaults 3768# to libnfs default) 3769# 3770# @page-cache-size: set the pagecache size in bytes (defaults 3771# to libnfs default) 3772# 3773# @debug: set the NFS debug level (max 2) (defaults 3774# to libnfs default) 3775# 3776# Since: 2.9 3777## 3778{ 'struct': 'BlockdevOptionsNfs', 3779 'data': { 'server': 'NFSServer', 3780 'path': 'str', 3781 '*user': 'int', 3782 '*group': 'int', 3783 '*tcp-syn-count': 'int', 3784 '*readahead-size': 'int', 3785 '*page-cache-size': 'int', 3786 '*debug': 'int' } } 3787 3788## 3789# @BlockdevOptionsCurlBase: 3790# 3791# Driver specific block device options shared by all protocols supported by the 3792# curl backend. 3793# 3794# @url: URL of the image file 3795# 3796# @readahead: Size of the read-ahead cache; must be a multiple of 3797# 512 (defaults to 256 kB) 3798# 3799# @timeout: Timeout for connections, in seconds (defaults to 5) 3800# 3801# @username: Username for authentication (defaults to none) 3802# 3803# @password-secret: ID of a QCryptoSecret object providing a password 3804# for authentication (defaults to no password) 3805# 3806# @proxy-username: Username for proxy authentication (defaults to none) 3807# 3808# @proxy-password-secret: ID of a QCryptoSecret object providing a password 3809# for proxy authentication (defaults to no password) 3810# 3811# Since: 2.9 3812## 3813{ 'struct': 'BlockdevOptionsCurlBase', 3814 'data': { 'url': 'str', 3815 '*readahead': 'int', 3816 '*timeout': 'int', 3817 '*username': 'str', 3818 '*password-secret': 'str', 3819 '*proxy-username': 'str', 3820 '*proxy-password-secret': 'str' } } 3821 3822## 3823# @BlockdevOptionsCurlHttp: 3824# 3825# Driver specific block device options for HTTP connections over the curl 3826# backend. URLs must start with "http://". 3827# 3828# @cookie: List of cookies to set; format is 3829# "name1=content1; name2=content2;" as explained by 3830# CURLOPT_COOKIE(3). Defaults to no cookies. 3831# 3832# @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a 3833# secure way. See @cookie for the format. (since 2.10) 3834# 3835# Since: 2.9 3836## 3837{ 'struct': 'BlockdevOptionsCurlHttp', 3838 'base': 'BlockdevOptionsCurlBase', 3839 'data': { '*cookie': 'str', 3840 '*cookie-secret': 'str'} } 3841 3842## 3843# @BlockdevOptionsCurlHttps: 3844# 3845# Driver specific block device options for HTTPS connections over the curl 3846# backend. URLs must start with "https://". 3847# 3848# @cookie: List of cookies to set; format is 3849# "name1=content1; name2=content2;" as explained by 3850# CURLOPT_COOKIE(3). Defaults to no cookies. 3851# 3852# @sslverify: Whether to verify the SSL certificate's validity (defaults to 3853# true) 3854# 3855# @cookie-secret: ID of a QCryptoSecret object providing the cookie data in a 3856# secure way. See @cookie for the format. (since 2.10) 3857# 3858# Since: 2.9 3859## 3860{ 'struct': 'BlockdevOptionsCurlHttps', 3861 'base': 'BlockdevOptionsCurlBase', 3862 'data': { '*cookie': 'str', 3863 '*sslverify': 'bool', 3864 '*cookie-secret': 'str'} } 3865 3866## 3867# @BlockdevOptionsCurlFtp: 3868# 3869# Driver specific block device options for FTP connections over the curl 3870# backend. URLs must start with "ftp://". 3871# 3872# Since: 2.9 3873## 3874{ 'struct': 'BlockdevOptionsCurlFtp', 3875 'base': 'BlockdevOptionsCurlBase', 3876 'data': { } } 3877 3878## 3879# @BlockdevOptionsCurlFtps: 3880# 3881# Driver specific block device options for FTPS connections over the curl 3882# backend. URLs must start with "ftps://". 3883# 3884# @sslverify: Whether to verify the SSL certificate's validity (defaults to 3885# true) 3886# 3887# Since: 2.9 3888## 3889{ 'struct': 'BlockdevOptionsCurlFtps', 3890 'base': 'BlockdevOptionsCurlBase', 3891 'data': { '*sslverify': 'bool' } } 3892 3893## 3894# @BlockdevOptionsNbd: 3895# 3896# Driver specific block device options for NBD. 3897# 3898# @server: NBD server address 3899# 3900# @export: export name 3901# 3902# @tls-creds: TLS credentials ID 3903# 3904# @x-dirty-bitmap: A metadata context name such as "qemu:dirty-bitmap:NAME" 3905# or "qemu:allocation-depth" to query in place of the 3906# traditional "base:allocation" block status (see 3907# NBD_OPT_LIST_META_CONTEXT in the NBD protocol; and 3908# yes, naming this option x-context would have made 3909# more sense) (since 3.0) 3910# 3911# @reconnect-delay: On an unexpected disconnect, the nbd client tries to 3912# connect again until succeeding or encountering a serious 3913# error. During the first @reconnect-delay seconds, all 3914# requests are paused and will be rerun on a successful 3915# reconnect. After that time, any delayed requests and all 3916# future requests before a successful reconnect will 3917# immediately fail. Default 0 (Since 4.2) 3918# 3919# Since: 2.9 3920## 3921{ 'struct': 'BlockdevOptionsNbd', 3922 'data': { 'server': 'SocketAddress', 3923 '*export': 'str', 3924 '*tls-creds': 'str', 3925 '*x-dirty-bitmap': 'str', 3926 '*reconnect-delay': 'uint32' } } 3927 3928## 3929# @BlockdevOptionsRaw: 3930# 3931# Driver specific block device options for the raw driver. 3932# 3933# @offset: position where the block device starts 3934# @size: the assumed size of the device 3935# 3936# Since: 2.9 3937## 3938{ 'struct': 'BlockdevOptionsRaw', 3939 'base': 'BlockdevOptionsGenericFormat', 3940 'data': { '*offset': 'int', '*size': 'int' } } 3941 3942## 3943# @BlockdevOptionsThrottle: 3944# 3945# Driver specific block device options for the throttle driver 3946# 3947# @throttle-group: the name of the throttle-group object to use. It 3948# must already exist. 3949# @file: reference to or definition of the data source block device 3950# Since: 2.11 3951## 3952{ 'struct': 'BlockdevOptionsThrottle', 3953 'data': { 'throttle-group': 'str', 3954 'file' : 'BlockdevRef' 3955 } } 3956## 3957# @BlockdevOptions: 3958# 3959# Options for creating a block device. Many options are available for all 3960# block devices, independent of the block driver: 3961# 3962# @driver: block driver name 3963# @node-name: the node name of the new node (Since 2.0). 3964# This option is required on the top level of blockdev-add. 3965# Valid node names start with an alphabetic character and may 3966# contain only alphanumeric characters, '-', '.' and '_'. Their 3967# maximum length is 31 characters. 3968# @discard: discard-related options (default: ignore) 3969# @cache: cache-related options 3970# @read-only: whether the block device should be read-only (default: false). 3971# Note that some block drivers support only read-only access, 3972# either generally or in certain configurations. In this case, 3973# the default value does not work and the option must be 3974# specified explicitly. 3975# @auto-read-only: if true and @read-only is false, QEMU may automatically 3976# decide not to open the image read-write as requested, but 3977# fall back to read-only instead (and switch between the modes 3978# later), e.g. depending on whether the image file is writable 3979# or whether a writing user is attached to the node 3980# (default: false, since 3.1) 3981# @detect-zeroes: detect and optimize zero writes (Since 2.1) 3982# (default: off) 3983# @force-share: force share all permission on added nodes. 3984# Requires read-only=true. (Since 2.10) 3985# 3986# Remaining options are determined by the block driver. 3987# 3988# Since: 2.9 3989## 3990{ 'union': 'BlockdevOptions', 3991 'base': { 'driver': 'BlockdevDriver', 3992 '*node-name': 'str', 3993 '*discard': 'BlockdevDiscardOptions', 3994 '*cache': 'BlockdevCacheOptions', 3995 '*read-only': 'bool', 3996 '*auto-read-only': 'bool', 3997 '*force-share': 'bool', 3998 '*detect-zeroes': 'BlockdevDetectZeroesOptions' }, 3999 'discriminator': 'driver', 4000 'data': { 4001 'blkdebug': 'BlockdevOptionsBlkdebug', 4002 'blklogwrites':'BlockdevOptionsBlklogwrites', 4003 'blkverify': 'BlockdevOptionsBlkverify', 4004 'blkreplay': 'BlockdevOptionsBlkreplay', 4005 'bochs': 'BlockdevOptionsGenericFormat', 4006 'cloop': 'BlockdevOptionsGenericFormat', 4007 'compress': 'BlockdevOptionsGenericFormat', 4008 'copy-on-read':'BlockdevOptionsGenericFormat', 4009 'dmg': 'BlockdevOptionsGenericFormat', 4010 'file': 'BlockdevOptionsFile', 4011 'ftp': 'BlockdevOptionsCurlFtp', 4012 'ftps': 'BlockdevOptionsCurlFtps', 4013 'gluster': 'BlockdevOptionsGluster', 4014 'host_cdrom': 'BlockdevOptionsFile', 4015 'host_device':'BlockdevOptionsFile', 4016 'http': 'BlockdevOptionsCurlHttp', 4017 'https': 'BlockdevOptionsCurlHttps', 4018 'iscsi': 'BlockdevOptionsIscsi', 4019 'luks': 'BlockdevOptionsLUKS', 4020 'nbd': 'BlockdevOptionsNbd', 4021 'nfs': 'BlockdevOptionsNfs', 4022 'null-aio': 'BlockdevOptionsNull', 4023 'null-co': 'BlockdevOptionsNull', 4024 'nvme': 'BlockdevOptionsNVMe', 4025 'parallels': 'BlockdevOptionsGenericFormat', 4026 'preallocate':'BlockdevOptionsPreallocate', 4027 'qcow2': 'BlockdevOptionsQcow2', 4028 'qcow': 'BlockdevOptionsQcow', 4029 'qed': 'BlockdevOptionsGenericCOWFormat', 4030 'quorum': 'BlockdevOptionsQuorum', 4031 'raw': 'BlockdevOptionsRaw', 4032 'rbd': 'BlockdevOptionsRbd', 4033 'replication': { 'type': 'BlockdevOptionsReplication', 4034 'if': 'defined(CONFIG_REPLICATION)' }, 4035 'sheepdog': 'BlockdevOptionsSheepdog', 4036 'ssh': 'BlockdevOptionsSsh', 4037 'throttle': 'BlockdevOptionsThrottle', 4038 'vdi': 'BlockdevOptionsGenericFormat', 4039 'vhdx': 'BlockdevOptionsGenericFormat', 4040 'vmdk': 'BlockdevOptionsGenericCOWFormat', 4041 'vpc': 'BlockdevOptionsGenericFormat', 4042 'vvfat': 'BlockdevOptionsVVFAT' 4043 } } 4044 4045## 4046# @BlockdevRef: 4047# 4048# Reference to a block device. 4049# 4050# @definition: defines a new block device inline 4051# @reference: references the ID of an existing block device 4052# 4053# Since: 2.9 4054## 4055{ 'alternate': 'BlockdevRef', 4056 'data': { 'definition': 'BlockdevOptions', 4057 'reference': 'str' } } 4058 4059## 4060# @BlockdevRefOrNull: 4061# 4062# Reference to a block device. 4063# 4064# @definition: defines a new block device inline 4065# @reference: references the ID of an existing block device. 4066# An empty string means that no block device should 4067# be referenced. Deprecated; use null instead. 4068# @null: No block device should be referenced (since 2.10) 4069# 4070# Since: 2.9 4071## 4072{ 'alternate': 'BlockdevRefOrNull', 4073 'data': { 'definition': 'BlockdevOptions', 4074 'reference': 'str', 4075 'null': 'null' } } 4076 4077## 4078# @blockdev-add: 4079# 4080# Creates a new block device. 4081# 4082# Since: 2.9 4083# 4084# Example: 4085# 4086# 1. 4087# -> { "execute": "blockdev-add", 4088# "arguments": { 4089# "driver": "qcow2", 4090# "node-name": "test1", 4091# "file": { 4092# "driver": "file", 4093# "filename": "test.qcow2" 4094# } 4095# } 4096# } 4097# <- { "return": {} } 4098# 4099# 2. 4100# -> { "execute": "blockdev-add", 4101# "arguments": { 4102# "driver": "qcow2", 4103# "node-name": "node0", 4104# "discard": "unmap", 4105# "cache": { 4106# "direct": true 4107# }, 4108# "file": { 4109# "driver": "file", 4110# "filename": "/tmp/test.qcow2" 4111# }, 4112# "backing": { 4113# "driver": "raw", 4114# "file": { 4115# "driver": "file", 4116# "filename": "/dev/fdset/4" 4117# } 4118# } 4119# } 4120# } 4121# 4122# <- { "return": {} } 4123# 4124## 4125{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true } 4126 4127## 4128# @x-blockdev-reopen: 4129# 4130# Reopens a block device using the given set of options. Any option 4131# not specified will be reset to its default value regardless of its 4132# previous status. If an option cannot be changed or a particular 4133# driver does not support reopening then the command will return an 4134# error. 4135# 4136# The top-level @node-name option (from BlockdevOptions) must be 4137# specified and is used to select the block device to be reopened. 4138# Other @node-name options must be either omitted or set to the 4139# current name of the appropriate node. This command won't change any 4140# node name and any attempt to do it will result in an error. 4141# 4142# In the case of options that refer to child nodes, the behavior of 4143# this command depends on the value: 4144# 4145# 1) A set of options (BlockdevOptions): the child is reopened with 4146# the specified set of options. 4147# 4148# 2) A reference to the current child: the child is reopened using 4149# its existing set of options. 4150# 4151# 3) A reference to a different node: the current child is replaced 4152# with the specified one. 4153# 4154# 4) NULL: the current child (if any) is detached. 4155# 4156# Options (1) and (2) are supported in all cases, but at the moment 4157# only @backing allows replacing or detaching an existing child. 4158# 4159# Unlike with blockdev-add, the @backing option must always be present 4160# unless the node being reopened does not have a backing file and its 4161# image does not have a default backing file name as part of its 4162# metadata. 4163# 4164# Since: 4.0 4165## 4166{ 'command': 'x-blockdev-reopen', 4167 'data': 'BlockdevOptions', 'boxed': true } 4168 4169## 4170# @blockdev-del: 4171# 4172# Deletes a block device that has been added using blockdev-add. 4173# The command will fail if the node is attached to a device or is 4174# otherwise being used. 4175# 4176# @node-name: Name of the graph node to delete. 4177# 4178# Since: 2.9 4179# 4180# Example: 4181# 4182# -> { "execute": "blockdev-add", 4183# "arguments": { 4184# "driver": "qcow2", 4185# "node-name": "node0", 4186# "file": { 4187# "driver": "file", 4188# "filename": "test.qcow2" 4189# } 4190# } 4191# } 4192# <- { "return": {} } 4193# 4194# -> { "execute": "blockdev-del", 4195# "arguments": { "node-name": "node0" } 4196# } 4197# <- { "return": {} } 4198# 4199## 4200{ 'command': 'blockdev-del', 'data': { 'node-name': 'str' } } 4201 4202## 4203# @BlockdevCreateOptionsFile: 4204# 4205# Driver specific image creation options for file. 4206# 4207# @filename: Filename for the new image file 4208# @size: Size of the virtual disk in bytes 4209# @preallocation: Preallocation mode for the new image (default: off; 4210# allowed values: off, 4211# falloc (if defined CONFIG_POSIX_FALLOCATE), 4212# full (if defined CONFIG_POSIX)) 4213# @nocow: Turn off copy-on-write (valid only on btrfs; default: off) 4214# @extent-size-hint: Extent size hint to add to the image file; 0 for not 4215# adding an extent size hint (default: 1 MB, since 5.1) 4216# 4217# Since: 2.12 4218## 4219{ 'struct': 'BlockdevCreateOptionsFile', 4220 'data': { 'filename': 'str', 4221 'size': 'size', 4222 '*preallocation': 'PreallocMode', 4223 '*nocow': 'bool', 4224 '*extent-size-hint': 'size'} } 4225 4226## 4227# @BlockdevCreateOptionsGluster: 4228# 4229# Driver specific image creation options for gluster. 4230# 4231# @location: Where to store the new image file 4232# @size: Size of the virtual disk in bytes 4233# @preallocation: Preallocation mode for the new image (default: off; 4234# allowed values: off, 4235# falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), 4236# full (if defined CONFIG_GLUSTERFS_ZEROFILL)) 4237# 4238# Since: 2.12 4239## 4240{ 'struct': 'BlockdevCreateOptionsGluster', 4241 'data': { 'location': 'BlockdevOptionsGluster', 4242 'size': 'size', 4243 '*preallocation': 'PreallocMode' } } 4244 4245## 4246# @BlockdevCreateOptionsLUKS: 4247# 4248# Driver specific image creation options for LUKS. 4249# 4250# @file: Node to create the image format on 4251# @size: Size of the virtual disk in bytes 4252# @preallocation: Preallocation mode for the new image 4253# (since: 4.2) 4254# (default: off; allowed values: off, metadata, falloc, full) 4255# 4256# Since: 2.12 4257## 4258{ 'struct': 'BlockdevCreateOptionsLUKS', 4259 'base': 'QCryptoBlockCreateOptionsLUKS', 4260 'data': { 'file': 'BlockdevRef', 4261 'size': 'size', 4262 '*preallocation': 'PreallocMode' } } 4263 4264## 4265# @BlockdevCreateOptionsNfs: 4266# 4267# Driver specific image creation options for NFS. 4268# 4269# @location: Where to store the new image file 4270# @size: Size of the virtual disk in bytes 4271# 4272# Since: 2.12 4273## 4274{ 'struct': 'BlockdevCreateOptionsNfs', 4275 'data': { 'location': 'BlockdevOptionsNfs', 4276 'size': 'size' } } 4277 4278## 4279# @BlockdevCreateOptionsParallels: 4280# 4281# Driver specific image creation options for parallels. 4282# 4283# @file: Node to create the image format on 4284# @size: Size of the virtual disk in bytes 4285# @cluster-size: Cluster size in bytes (default: 1 MB) 4286# 4287# Since: 2.12 4288## 4289{ 'struct': 'BlockdevCreateOptionsParallels', 4290 'data': { 'file': 'BlockdevRef', 4291 'size': 'size', 4292 '*cluster-size': 'size' } } 4293 4294## 4295# @BlockdevCreateOptionsQcow: 4296# 4297# Driver specific image creation options for qcow. 4298# 4299# @file: Node to create the image format on 4300# @size: Size of the virtual disk in bytes 4301# @backing-file: File name of the backing file if a backing file 4302# should be used 4303# @encrypt: Encryption options if the image should be encrypted 4304# 4305# Since: 2.12 4306## 4307{ 'struct': 'BlockdevCreateOptionsQcow', 4308 'data': { 'file': 'BlockdevRef', 4309 'size': 'size', 4310 '*backing-file': 'str', 4311 '*encrypt': 'QCryptoBlockCreateOptions' } } 4312 4313## 4314# @BlockdevQcow2Version: 4315# 4316# @v2: The original QCOW2 format as introduced in qemu 0.10 (version 2) 4317# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) 4318# 4319# Since: 2.12 4320## 4321{ 'enum': 'BlockdevQcow2Version', 4322 'data': [ 'v2', 'v3' ] } 4323 4324 4325## 4326# @Qcow2CompressionType: 4327# 4328# Compression type used in qcow2 image file 4329# 4330# @zlib: zlib compression, see <http://zlib.net/> 4331# @zstd: zstd compression, see <http://github.com/facebook/zstd> 4332# 4333# Since: 5.1 4334## 4335{ 'enum': 'Qcow2CompressionType', 4336 'data': [ 'zlib', { 'name': 'zstd', 'if': 'defined(CONFIG_ZSTD)' } ] } 4337 4338## 4339# @BlockdevCreateOptionsQcow2: 4340# 4341# Driver specific image creation options for qcow2. 4342# 4343# @file: Node to create the image format on 4344# @data-file: Node to use as an external data file in which all guest 4345# data is stored so that only metadata remains in the qcow2 4346# file (since: 4.0) 4347# @data-file-raw: True if the external data file must stay valid as a 4348# standalone (read-only) raw image without looking at qcow2 4349# metadata (default: false; since: 4.0) 4350# @extended-l2: True to make the image have extended L2 entries 4351# (default: false; since 5.2) 4352# @size: Size of the virtual disk in bytes 4353# @version: Compatibility level (default: v3) 4354# @backing-file: File name of the backing file if a backing file 4355# should be used 4356# @backing-fmt: Name of the block driver to use for the backing file 4357# @encrypt: Encryption options if the image should be encrypted 4358# @cluster-size: qcow2 cluster size in bytes (default: 65536) 4359# @preallocation: Preallocation mode for the new image (default: off; 4360# allowed values: off, falloc, full, metadata) 4361# @lazy-refcounts: True if refcounts may be updated lazily (default: off) 4362# @refcount-bits: Width of reference counts in bits (default: 16) 4363# @compression-type: The image cluster compression method 4364# (default: zlib, since 5.1) 4365# 4366# Since: 2.12 4367## 4368{ 'struct': 'BlockdevCreateOptionsQcow2', 4369 'data': { 'file': 'BlockdevRef', 4370 '*data-file': 'BlockdevRef', 4371 '*data-file-raw': 'bool', 4372 '*extended-l2': 'bool', 4373 'size': 'size', 4374 '*version': 'BlockdevQcow2Version', 4375 '*backing-file': 'str', 4376 '*backing-fmt': 'BlockdevDriver', 4377 '*encrypt': 'QCryptoBlockCreateOptions', 4378 '*cluster-size': 'size', 4379 '*preallocation': 'PreallocMode', 4380 '*lazy-refcounts': 'bool', 4381 '*refcount-bits': 'int', 4382 '*compression-type':'Qcow2CompressionType' } } 4383 4384## 4385# @BlockdevCreateOptionsQed: 4386# 4387# Driver specific image creation options for qed. 4388# 4389# @file: Node to create the image format on 4390# @size: Size of the virtual disk in bytes 4391# @backing-file: File name of the backing file if a backing file 4392# should be used 4393# @backing-fmt: Name of the block driver to use for the backing file 4394# @cluster-size: Cluster size in bytes (default: 65536) 4395# @table-size: L1/L2 table size (in clusters) 4396# 4397# Since: 2.12 4398## 4399{ 'struct': 'BlockdevCreateOptionsQed', 4400 'data': { 'file': 'BlockdevRef', 4401 'size': 'size', 4402 '*backing-file': 'str', 4403 '*backing-fmt': 'BlockdevDriver', 4404 '*cluster-size': 'size', 4405 '*table-size': 'int' } } 4406 4407## 4408# @BlockdevCreateOptionsRbd: 4409# 4410# Driver specific image creation options for rbd/Ceph. 4411# 4412# @location: Where to store the new image file. This location cannot 4413# point to a snapshot. 4414# @size: Size of the virtual disk in bytes 4415# @cluster-size: RBD object size 4416# 4417# Since: 2.12 4418## 4419{ 'struct': 'BlockdevCreateOptionsRbd', 4420 'data': { 'location': 'BlockdevOptionsRbd', 4421 'size': 'size', 4422 '*cluster-size' : 'size' } } 4423 4424## 4425# @BlockdevVmdkSubformat: 4426# 4427# Subformat options for VMDK images 4428# 4429# @monolithicSparse: Single file image with sparse cluster allocation 4430# 4431# @monolithicFlat: Single flat data image and a descriptor file 4432# 4433# @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA) sparse extent 4434# files, in addition to a descriptor file 4435# 4436# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat extent 4437# files, in addition to a descriptor file 4438# 4439# @streamOptimized: Single file image sparse cluster allocation, optimized 4440# for streaming over network. 4441# 4442# Since: 4.0 4443## 4444{ 'enum': 'BlockdevVmdkSubformat', 4445 'data': [ 'monolithicSparse', 'monolithicFlat', 'twoGbMaxExtentSparse', 4446 'twoGbMaxExtentFlat', 'streamOptimized'] } 4447 4448## 4449# @BlockdevVmdkAdapterType: 4450# 4451# Adapter type info for VMDK images 4452# 4453# Since: 4.0 4454## 4455{ 'enum': 'BlockdevVmdkAdapterType', 4456 'data': [ 'ide', 'buslogic', 'lsilogic', 'legacyESX'] } 4457 4458## 4459# @BlockdevCreateOptionsVmdk: 4460# 4461# Driver specific image creation options for VMDK. 4462# 4463# @file: Where to store the new image file. This refers to the image 4464# file for monolithcSparse and streamOptimized format, or the 4465# descriptor file for other formats. 4466# @size: Size of the virtual disk in bytes 4467# @extents: Where to store the data extents. Required for monolithcFlat, 4468# twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For 4469# monolithicFlat, only one entry is required; for 4470# twoGbMaxExtent* formats, the number of entries required is 4471# calculated as extent_number = virtual_size / 2GB. Providing 4472# more extents than will be used is an error. 4473# @subformat: The subformat of the VMDK image. Default: "monolithicSparse". 4474# @backing-file: The path of backing file. Default: no backing file is used. 4475# @adapter-type: The adapter type used to fill in the descriptor. Default: ide. 4476# @hwversion: Hardware version. The meaningful options are "4" or "6". 4477# Default: "4". 4478# @zeroed-grain: Whether to enable zeroed-grain feature for sparse subformats. 4479# Default: false. 4480# 4481# Since: 4.0 4482## 4483{ 'struct': 'BlockdevCreateOptionsVmdk', 4484 'data': { 'file': 'BlockdevRef', 4485 'size': 'size', 4486 '*extents': ['BlockdevRef'], 4487 '*subformat': 'BlockdevVmdkSubformat', 4488 '*backing-file': 'str', 4489 '*adapter-type': 'BlockdevVmdkAdapterType', 4490 '*hwversion': 'str', 4491 '*zeroed-grain': 'bool' } } 4492 4493 4494## 4495# @SheepdogRedundancyType: 4496# 4497# @full: Create a fully replicated vdi with x copies 4498# @erasure-coded: Create an erasure coded vdi with x data strips and 4499# y parity strips 4500# 4501# Since: 2.12 4502## 4503{ 'enum': 'SheepdogRedundancyType', 4504 'data': [ 'full', 'erasure-coded' ] } 4505 4506## 4507# @SheepdogRedundancyFull: 4508# 4509# @copies: Number of copies to use (between 1 and 31) 4510# 4511# Since: 2.12 4512## 4513{ 'struct': 'SheepdogRedundancyFull', 4514 'data': { 'copies': 'int' }} 4515 4516## 4517# @SheepdogRedundancyErasureCoded: 4518# 4519# @data-strips: Number of data strips to use (one of {2,4,8,16}) 4520# @parity-strips: Number of parity strips to use (between 1 and 15) 4521# 4522# Since: 2.12 4523## 4524{ 'struct': 'SheepdogRedundancyErasureCoded', 4525 'data': { 'data-strips': 'int', 4526 'parity-strips': 'int' }} 4527 4528## 4529# @SheepdogRedundancy: 4530# 4531# Since: 2.12 4532## 4533{ 'union': 'SheepdogRedundancy', 4534 'base': { 'type': 'SheepdogRedundancyType' }, 4535 'discriminator': 'type', 4536 'data': { 'full': 'SheepdogRedundancyFull', 4537 'erasure-coded': 'SheepdogRedundancyErasureCoded' } } 4538 4539## 4540# @BlockdevCreateOptionsSheepdog: 4541# 4542# Driver specific image creation options for Sheepdog. 4543# 4544# @location: Where to store the new image file 4545# @size: Size of the virtual disk in bytes 4546# @backing-file: File name of a base image 4547# @preallocation: Preallocation mode for the new image (default: off; 4548# allowed values: off, full) 4549# @redundancy: Redundancy of the image 4550# @object-size: Object size of the image 4551# 4552# Since: 2.12 4553## 4554{ 'struct': 'BlockdevCreateOptionsSheepdog', 4555 'data': { 'location': 'BlockdevOptionsSheepdog', 4556 'size': 'size', 4557 '*backing-file': 'str', 4558 '*preallocation': 'PreallocMode', 4559 '*redundancy': 'SheepdogRedundancy', 4560 '*object-size': 'size' } } 4561 4562## 4563# @BlockdevCreateOptionsSsh: 4564# 4565# Driver specific image creation options for SSH. 4566# 4567# @location: Where to store the new image file 4568# @size: Size of the virtual disk in bytes 4569# 4570# Since: 2.12 4571## 4572{ 'struct': 'BlockdevCreateOptionsSsh', 4573 'data': { 'location': 'BlockdevOptionsSsh', 4574 'size': 'size' } } 4575 4576## 4577# @BlockdevCreateOptionsVdi: 4578# 4579# Driver specific image creation options for VDI. 4580# 4581# @file: Node to create the image format on 4582# @size: Size of the virtual disk in bytes 4583# @preallocation: Preallocation mode for the new image (default: off; 4584# allowed values: off, metadata) 4585# 4586# Since: 2.12 4587## 4588{ 'struct': 'BlockdevCreateOptionsVdi', 4589 'data': { 'file': 'BlockdevRef', 4590 'size': 'size', 4591 '*preallocation': 'PreallocMode' } } 4592 4593## 4594# @BlockdevVhdxSubformat: 4595# 4596# @dynamic: Growing image file 4597# @fixed: Preallocated fixed-size image file 4598# 4599# Since: 2.12 4600## 4601{ 'enum': 'BlockdevVhdxSubformat', 4602 'data': [ 'dynamic', 'fixed' ] } 4603 4604## 4605# @BlockdevCreateOptionsVhdx: 4606# 4607# Driver specific image creation options for vhdx. 4608# 4609# @file: Node to create the image format on 4610# @size: Size of the virtual disk in bytes 4611# @log-size: Log size in bytes, must be a multiple of 1 MB 4612# (default: 1 MB) 4613# @block-size: Block size in bytes, must be a multiple of 1 MB and not 4614# larger than 256 MB (default: automatically choose a block 4615# size depending on the image size) 4616# @subformat: vhdx subformat (default: dynamic) 4617# @block-state-zero: Force use of payload blocks of type 'ZERO'. Non-standard, 4618# but default. Do not set to 'off' when using 'qemu-img 4619# convert' with subformat=dynamic. 4620# 4621# Since: 2.12 4622## 4623{ 'struct': 'BlockdevCreateOptionsVhdx', 4624 'data': { 'file': 'BlockdevRef', 4625 'size': 'size', 4626 '*log-size': 'size', 4627 '*block-size': 'size', 4628 '*subformat': 'BlockdevVhdxSubformat', 4629 '*block-state-zero': 'bool' } } 4630 4631## 4632# @BlockdevVpcSubformat: 4633# 4634# @dynamic: Growing image file 4635# @fixed: Preallocated fixed-size image file 4636# 4637# Since: 2.12 4638## 4639{ 'enum': 'BlockdevVpcSubformat', 4640 'data': [ 'dynamic', 'fixed' ] } 4641 4642## 4643# @BlockdevCreateOptionsVpc: 4644# 4645# Driver specific image creation options for vpc (VHD). 4646# 4647# @file: Node to create the image format on 4648# @size: Size of the virtual disk in bytes 4649# @subformat: vhdx subformat (default: dynamic) 4650# @force-size: Force use of the exact byte size instead of rounding to the 4651# next size that can be represented in CHS geometry 4652# (default: false) 4653# 4654# Since: 2.12 4655## 4656{ 'struct': 'BlockdevCreateOptionsVpc', 4657 'data': { 'file': 'BlockdevRef', 4658 'size': 'size', 4659 '*subformat': 'BlockdevVpcSubformat', 4660 '*force-size': 'bool' } } 4661 4662## 4663# @BlockdevCreateOptions: 4664# 4665# Options for creating an image format on a given node. 4666# 4667# @driver: block driver to create the image format 4668# 4669# Since: 2.12 4670## 4671{ 'union': 'BlockdevCreateOptions', 4672 'base': { 4673 'driver': 'BlockdevDriver' }, 4674 'discriminator': 'driver', 4675 'data': { 4676 'file': 'BlockdevCreateOptionsFile', 4677 'gluster': 'BlockdevCreateOptionsGluster', 4678 'luks': 'BlockdevCreateOptionsLUKS', 4679 'nfs': 'BlockdevCreateOptionsNfs', 4680 'parallels': 'BlockdevCreateOptionsParallels', 4681 'qcow': 'BlockdevCreateOptionsQcow', 4682 'qcow2': 'BlockdevCreateOptionsQcow2', 4683 'qed': 'BlockdevCreateOptionsQed', 4684 'rbd': 'BlockdevCreateOptionsRbd', 4685 'sheepdog': 'BlockdevCreateOptionsSheepdog', 4686 'ssh': 'BlockdevCreateOptionsSsh', 4687 'vdi': 'BlockdevCreateOptionsVdi', 4688 'vhdx': 'BlockdevCreateOptionsVhdx', 4689 'vmdk': 'BlockdevCreateOptionsVmdk', 4690 'vpc': 'BlockdevCreateOptionsVpc' 4691 } } 4692 4693## 4694# @blockdev-create: 4695# 4696# Starts a job to create an image format on a given node. The job is 4697# automatically finalized, but a manual job-dismiss is required. 4698# 4699# @job-id: Identifier for the newly created job. 4700# 4701# @options: Options for the image creation. 4702# 4703# Since: 3.0 4704## 4705{ 'command': 'blockdev-create', 4706 'data': { 'job-id': 'str', 4707 'options': 'BlockdevCreateOptions' } } 4708 4709## 4710# @BlockdevAmendOptionsLUKS: 4711# 4712# Driver specific image amend options for LUKS. 4713# 4714# Since: 5.1 4715## 4716{ 'struct': 'BlockdevAmendOptionsLUKS', 4717 'base': 'QCryptoBlockAmendOptionsLUKS', 4718 'data': { } 4719} 4720 4721## 4722# @BlockdevAmendOptionsQcow2: 4723# 4724# Driver specific image amend options for qcow2. 4725# For now, only encryption options can be amended 4726# 4727# @encrypt Encryption options to be amended 4728# 4729# Since: 5.1 4730## 4731{ 'struct': 'BlockdevAmendOptionsQcow2', 4732 'data': { '*encrypt': 'QCryptoBlockAmendOptions' } } 4733 4734## 4735# @BlockdevAmendOptions: 4736# 4737# Options for amending an image format 4738# 4739# @driver: Block driver of the node to amend. 4740# 4741# Since: 5.1 4742## 4743{ 'union': 'BlockdevAmendOptions', 4744 'base': { 4745 'driver': 'BlockdevDriver' }, 4746 'discriminator': 'driver', 4747 'data': { 4748 'luks': 'BlockdevAmendOptionsLUKS', 4749 'qcow2': 'BlockdevAmendOptionsQcow2' } } 4750 4751## 4752# @x-blockdev-amend: 4753# 4754# Starts a job to amend format specific options of an existing open block device 4755# The job is automatically finalized, but a manual job-dismiss is required. 4756# 4757# @job-id: Identifier for the newly created job. 4758# 4759# @node-name: Name of the block node to work on 4760# 4761# @options: Options (driver specific) 4762# 4763# @force: Allow unsafe operations, format specific 4764# For luks that allows erase of the last active keyslot 4765# (permanent loss of data), 4766# and replacement of an active keyslot 4767# (possible loss of data if IO error happens) 4768# 4769# Since: 5.1 4770## 4771{ 'command': 'x-blockdev-amend', 4772 'data': { 'job-id': 'str', 4773 'node-name': 'str', 4774 'options': 'BlockdevAmendOptions', 4775 '*force': 'bool' } } 4776 4777## 4778# @BlockErrorAction: 4779# 4780# An enumeration of action that has been taken when a DISK I/O occurs 4781# 4782# @ignore: error has been ignored 4783# 4784# @report: error has been reported to the device 4785# 4786# @stop: error caused VM to be stopped 4787# 4788# Since: 2.1 4789## 4790{ 'enum': 'BlockErrorAction', 4791 'data': [ 'ignore', 'report', 'stop' ] } 4792 4793 4794## 4795# @BLOCK_IMAGE_CORRUPTED: 4796# 4797# Emitted when a disk image is being marked corrupt. The image can be 4798# identified by its device or node name. The 'device' field is always 4799# present for compatibility reasons, but it can be empty ("") if the 4800# image does not have a device name associated. 4801# 4802# @device: device name. This is always present for compatibility 4803# reasons, but it can be empty ("") if the image does not 4804# have a device name associated. 4805# 4806# @node-name: node name (Since: 2.4) 4807# 4808# @msg: informative message for human consumption, such as the kind of 4809# corruption being detected. It should not be parsed by machine as it is 4810# not guaranteed to be stable 4811# 4812# @offset: if the corruption resulted from an image access, this is 4813# the host's access offset into the image 4814# 4815# @size: if the corruption resulted from an image access, this is 4816# the access size 4817# 4818# @fatal: if set, the image is marked corrupt and therefore unusable after this 4819# event and must be repaired (Since 2.2; before, every 4820# BLOCK_IMAGE_CORRUPTED event was fatal) 4821# 4822# Note: If action is "stop", a STOP event will eventually follow the 4823# BLOCK_IO_ERROR event. 4824# 4825# Example: 4826# 4827# <- { "event": "BLOCK_IMAGE_CORRUPTED", 4828# "data": { "device": "ide0-hd0", "node-name": "node0", 4829# "msg": "Prevented active L1 table overwrite", "offset": 196608, 4830# "size": 65536 }, 4831# "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } 4832# 4833# Since: 1.7 4834## 4835{ 'event': 'BLOCK_IMAGE_CORRUPTED', 4836 'data': { 'device' : 'str', 4837 '*node-name' : 'str', 4838 'msg' : 'str', 4839 '*offset' : 'int', 4840 '*size' : 'int', 4841 'fatal' : 'bool' } } 4842 4843## 4844# @BLOCK_IO_ERROR: 4845# 4846# Emitted when a disk I/O error occurs 4847# 4848# @device: device name. This is always present for compatibility 4849# reasons, but it can be empty ("") if the image does not 4850# have a device name associated. 4851# 4852# @node-name: node name. Note that errors may be reported for the root node 4853# that is directly attached to a guest device rather than for the 4854# node where the error occurred. The node name is not present if 4855# the drive is empty. (Since: 2.8) 4856# 4857# @operation: I/O operation 4858# 4859# @action: action that has been taken 4860# 4861# @nospace: true if I/O error was caused due to a no-space 4862# condition. This key is only present if query-block's 4863# io-status is present, please see query-block documentation 4864# for more information (since: 2.2) 4865# 4866# @reason: human readable string describing the error cause. 4867# (This field is a debugging aid for humans, it should not 4868# be parsed by applications) (since: 2.2) 4869# 4870# Note: If action is "stop", a STOP event will eventually follow the 4871# BLOCK_IO_ERROR event 4872# 4873# Since: 0.13 4874# 4875# Example: 4876# 4877# <- { "event": "BLOCK_IO_ERROR", 4878# "data": { "device": "ide0-hd1", 4879# "node-name": "#block212", 4880# "operation": "write", 4881# "action": "stop" }, 4882# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 4883# 4884## 4885{ 'event': 'BLOCK_IO_ERROR', 4886 'data': { 'device': 'str', '*node-name': 'str', 4887 'operation': 'IoOperationType', 4888 'action': 'BlockErrorAction', '*nospace': 'bool', 4889 'reason': 'str' } } 4890 4891## 4892# @BLOCK_JOB_COMPLETED: 4893# 4894# Emitted when a block job has completed 4895# 4896# @type: job type 4897# 4898# @device: The job identifier. Originally the device name but other 4899# values are allowed since QEMU 2.7 4900# 4901# @len: maximum progress value 4902# 4903# @offset: current progress value. On success this is equal to len. 4904# On failure this is less than len 4905# 4906# @speed: rate limit, bytes per second 4907# 4908# @error: error message. Only present on failure. This field 4909# contains a human-readable error message. There are no semantics 4910# other than that streaming has failed and clients should not try to 4911# interpret the error string 4912# 4913# Since: 1.1 4914# 4915# Example: 4916# 4917# <- { "event": "BLOCK_JOB_COMPLETED", 4918# "data": { "type": "stream", "device": "virtio-disk0", 4919# "len": 10737418240, "offset": 10737418240, 4920# "speed": 0 }, 4921# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 4922# 4923## 4924{ 'event': 'BLOCK_JOB_COMPLETED', 4925 'data': { 'type' : 'JobType', 4926 'device': 'str', 4927 'len' : 'int', 4928 'offset': 'int', 4929 'speed' : 'int', 4930 '*error': 'str' } } 4931 4932## 4933# @BLOCK_JOB_CANCELLED: 4934# 4935# Emitted when a block job has been cancelled 4936# 4937# @type: job type 4938# 4939# @device: The job identifier. Originally the device name but other 4940# values are allowed since QEMU 2.7 4941# 4942# @len: maximum progress value 4943# 4944# @offset: current progress value. On success this is equal to len. 4945# On failure this is less than len 4946# 4947# @speed: rate limit, bytes per second 4948# 4949# Since: 1.1 4950# 4951# Example: 4952# 4953# <- { "event": "BLOCK_JOB_CANCELLED", 4954# "data": { "type": "stream", "device": "virtio-disk0", 4955# "len": 10737418240, "offset": 134217728, 4956# "speed": 0 }, 4957# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 4958# 4959## 4960{ 'event': 'BLOCK_JOB_CANCELLED', 4961 'data': { 'type' : 'JobType', 4962 'device': 'str', 4963 'len' : 'int', 4964 'offset': 'int', 4965 'speed' : 'int' } } 4966 4967## 4968# @BLOCK_JOB_ERROR: 4969# 4970# Emitted when a block job encounters an error 4971# 4972# @device: The job identifier. Originally the device name but other 4973# values are allowed since QEMU 2.7 4974# 4975# @operation: I/O operation 4976# 4977# @action: action that has been taken 4978# 4979# Since: 1.3 4980# 4981# Example: 4982# 4983# <- { "event": "BLOCK_JOB_ERROR", 4984# "data": { "device": "ide0-hd1", 4985# "operation": "write", 4986# "action": "stop" }, 4987# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 4988# 4989## 4990{ 'event': 'BLOCK_JOB_ERROR', 4991 'data': { 'device' : 'str', 4992 'operation': 'IoOperationType', 4993 'action' : 'BlockErrorAction' } } 4994 4995## 4996# @BLOCK_JOB_READY: 4997# 4998# Emitted when a block job is ready to complete 4999# 5000# @type: job type 5001# 5002# @device: The job identifier. Originally the device name but other 5003# values are allowed since QEMU 2.7 5004# 5005# @len: maximum progress value 5006# 5007# @offset: current progress value. On success this is equal to len. 5008# On failure this is less than len 5009# 5010# @speed: rate limit, bytes per second 5011# 5012# Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR 5013# event 5014# 5015# Since: 1.3 5016# 5017# Example: 5018# 5019# <- { "event": "BLOCK_JOB_READY", 5020# "data": { "device": "drive0", "type": "mirror", "speed": 0, 5021# "len": 2097152, "offset": 2097152 } 5022# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5023# 5024## 5025{ 'event': 'BLOCK_JOB_READY', 5026 'data': { 'type' : 'JobType', 5027 'device': 'str', 5028 'len' : 'int', 5029 'offset': 'int', 5030 'speed' : 'int' } } 5031 5032## 5033# @BLOCK_JOB_PENDING: 5034# 5035# Emitted when a block job is awaiting explicit authorization to finalize graph 5036# changes via @block-job-finalize. If this job is part of a transaction, it will 5037# not emit this event until the transaction has converged first. 5038# 5039# @type: job type 5040# 5041# @id: The job identifier. 5042# 5043# Since: 2.12 5044# 5045# Example: 5046# 5047# <- { "event": "BLOCK_JOB_WAITING", 5048# "data": { "device": "drive0", "type": "mirror" }, 5049# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 5050# 5051## 5052{ 'event': 'BLOCK_JOB_PENDING', 5053 'data': { 'type' : 'JobType', 5054 'id' : 'str' } } 5055 5056## 5057# @PreallocMode: 5058# 5059# Preallocation mode of QEMU image file 5060# 5061# @off: no preallocation 5062# @metadata: preallocate only for metadata 5063# @falloc: like @full preallocation but allocate disk space by 5064# posix_fallocate() rather than writing data. 5065# @full: preallocate all data by writing it to the device to ensure 5066# disk space is really available. This data may or may not be 5067# zero, depending on the image format and storage. 5068# @full preallocation also sets up metadata correctly. 5069# 5070# Since: 2.2 5071## 5072{ 'enum': 'PreallocMode', 5073 'data': [ 'off', 'metadata', 'falloc', 'full' ] } 5074 5075## 5076# @BLOCK_WRITE_THRESHOLD: 5077# 5078# Emitted when writes on block device reaches or exceeds the 5079# configured write threshold. For thin-provisioned devices, this 5080# means the device should be extended to avoid pausing for 5081# disk exhaustion. 5082# The event is one shot. Once triggered, it needs to be 5083# re-registered with another block-set-write-threshold command. 5084# 5085# @node-name: graph node name on which the threshold was exceeded. 5086# 5087# @amount-exceeded: amount of data which exceeded the threshold, in bytes. 5088# 5089# @write-threshold: last configured threshold, in bytes. 5090# 5091# Since: 2.3 5092## 5093{ 'event': 'BLOCK_WRITE_THRESHOLD', 5094 'data': { 'node-name': 'str', 5095 'amount-exceeded': 'uint64', 5096 'write-threshold': 'uint64' } } 5097 5098## 5099# @block-set-write-threshold: 5100# 5101# Change the write threshold for a block drive. An event will be 5102# delivered if a write to this block drive crosses the configured 5103# threshold. The threshold is an offset, thus must be 5104# non-negative. Default is no write threshold. Setting the threshold 5105# to zero disables it. 5106# 5107# This is useful to transparently resize thin-provisioned drives without 5108# the guest OS noticing. 5109# 5110# @node-name: graph node name on which the threshold must be set. 5111# 5112# @write-threshold: configured threshold for the block device, bytes. 5113# Use 0 to disable the threshold. 5114# 5115# Since: 2.3 5116# 5117# Example: 5118# 5119# -> { "execute": "block-set-write-threshold", 5120# "arguments": { "node-name": "mydev", 5121# "write-threshold": 17179869184 } } 5122# <- { "return": {} } 5123# 5124## 5125{ 'command': 'block-set-write-threshold', 5126 'data': { 'node-name': 'str', 'write-threshold': 'uint64' } } 5127 5128## 5129# @x-blockdev-change: 5130# 5131# Dynamically reconfigure the block driver state graph. It can be used 5132# to add, remove, insert or replace a graph node. Currently only the 5133# Quorum driver implements this feature to add or remove its child. This 5134# is useful to fix a broken quorum child. 5135# 5136# If @node is specified, it will be inserted under @parent. @child 5137# may not be specified in this case. If both @parent and @child are 5138# specified but @node is not, @child will be detached from @parent. 5139# 5140# @parent: the id or name of the parent node. 5141# 5142# @child: the name of a child under the given parent node. 5143# 5144# @node: the name of the node that will be added. 5145# 5146# Note: this command is experimental, and its API is not stable. It 5147# does not support all kinds of operations, all kinds of children, nor 5148# all block drivers. 5149# 5150# FIXME Removing children from a quorum node means introducing gaps in the 5151# child indices. This cannot be represented in the 'children' list of 5152# BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename(). 5153# 5154# Warning: The data in a new quorum child MUST be consistent with that of 5155# the rest of the array. 5156# 5157# Since: 2.7 5158# 5159# Example: 5160# 5161# 1. Add a new node to a quorum 5162# -> { "execute": "blockdev-add", 5163# "arguments": { 5164# "driver": "raw", 5165# "node-name": "new_node", 5166# "file": { "driver": "file", 5167# "filename": "test.raw" } } } 5168# <- { "return": {} } 5169# -> { "execute": "x-blockdev-change", 5170# "arguments": { "parent": "disk1", 5171# "node": "new_node" } } 5172# <- { "return": {} } 5173# 5174# 2. Delete a quorum's node 5175# -> { "execute": "x-blockdev-change", 5176# "arguments": { "parent": "disk1", 5177# "child": "children.1" } } 5178# <- { "return": {} } 5179# 5180## 5181{ 'command': 'x-blockdev-change', 5182 'data' : { 'parent': 'str', 5183 '*child': 'str', 5184 '*node': 'str' } } 5185 5186## 5187# @x-blockdev-set-iothread: 5188# 5189# Move @node and its children into the @iothread. If @iothread is null then 5190# move @node and its children into the main loop. 5191# 5192# The node must not be attached to a BlockBackend. 5193# 5194# @node-name: the name of the block driver node 5195# 5196# @iothread: the name of the IOThread object or null for the main loop 5197# 5198# @force: true if the node and its children should be moved when a BlockBackend 5199# is already attached 5200# 5201# Note: this command is experimental and intended for test cases that need 5202# control over IOThreads only. 5203# 5204# Since: 2.12 5205# 5206# Example: 5207# 5208# 1. Move a node into an IOThread 5209# -> { "execute": "x-blockdev-set-iothread", 5210# "arguments": { "node-name": "disk1", 5211# "iothread": "iothread0" } } 5212# <- { "return": {} } 5213# 5214# 2. Move a node into the main loop 5215# -> { "execute": "x-blockdev-set-iothread", 5216# "arguments": { "node-name": "disk1", 5217# "iothread": null } } 5218# <- { "return": {} } 5219# 5220## 5221{ 'command': 'x-blockdev-set-iothread', 5222 'data' : { 'node-name': 'str', 5223 'iothread': 'StrOrNull', 5224 '*force': 'bool' } } 5225 5226## 5227# @QuorumOpType: 5228# 5229# An enumeration of the quorum operation types 5230# 5231# @read: read operation 5232# 5233# @write: write operation 5234# 5235# @flush: flush operation 5236# 5237# Since: 2.6 5238## 5239{ 'enum': 'QuorumOpType', 5240 'data': [ 'read', 'write', 'flush' ] } 5241 5242## 5243# @QUORUM_FAILURE: 5244# 5245# Emitted by the Quorum block driver if it fails to establish a quorum 5246# 5247# @reference: device name if defined else node name 5248# 5249# @sector-num: number of the first sector of the failed read operation 5250# 5251# @sectors-count: failed read operation sector count 5252# 5253# Note: This event is rate-limited. 5254# 5255# Since: 2.0 5256# 5257# Example: 5258# 5259# <- { "event": "QUORUM_FAILURE", 5260# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 }, 5261# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } 5262# 5263## 5264{ 'event': 'QUORUM_FAILURE', 5265 'data': { 'reference': 'str', 'sector-num': 'int', 'sectors-count': 'int' } } 5266 5267## 5268# @QUORUM_REPORT_BAD: 5269# 5270# Emitted to report a corruption of a Quorum file 5271# 5272# @type: quorum operation type (Since 2.6) 5273# 5274# @error: error message. Only present on failure. This field 5275# contains a human-readable error message. There are no semantics other 5276# than that the block layer reported an error and clients should not 5277# try to interpret the error string. 5278# 5279# @node-name: the graph node name of the block driver state 5280# 5281# @sector-num: number of the first sector of the failed read operation 5282# 5283# @sectors-count: failed read operation sector count 5284# 5285# Note: This event is rate-limited. 5286# 5287# Since: 2.0 5288# 5289# Example: 5290# 5291# 1. Read operation 5292# 5293# { "event": "QUORUM_REPORT_BAD", 5294# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5, 5295# "type": "read" }, 5296# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } 5297# 5298# 2. Flush operation 5299# 5300# { "event": "QUORUM_REPORT_BAD", 5301# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120, 5302# "type": "flush", "error": "Broken pipe" }, 5303# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } } 5304# 5305## 5306{ 'event': 'QUORUM_REPORT_BAD', 5307 'data': { 'type': 'QuorumOpType', '*error': 'str', 'node-name': 'str', 5308 'sector-num': 'int', 'sectors-count': 'int' } } 5309 5310## 5311# @BlockdevSnapshotInternal: 5312# 5313# @device: the device name or node-name of a root node to generate the snapshot 5314# from 5315# 5316# @name: the name of the internal snapshot to be created 5317# 5318# Notes: In transaction, if @name is empty, or any snapshot matching @name 5319# exists, the operation will fail. Only some image formats support it, 5320# for example, qcow2, rbd, and sheepdog. 5321# 5322# Since: 1.7 5323## 5324{ 'struct': 'BlockdevSnapshotInternal', 5325 'data': { 'device': 'str', 'name': 'str' } } 5326 5327## 5328# @blockdev-snapshot-internal-sync: 5329# 5330# Synchronously take an internal snapshot of a block device, when the 5331# format of the image used supports it. If the name is an empty 5332# string, or a snapshot with name already exists, the operation will 5333# fail. 5334# 5335# For the arguments, see the documentation of BlockdevSnapshotInternal. 5336# 5337# Returns: - nothing on success 5338# - If @device is not a valid block device, GenericError 5339# - If any snapshot matching @name exists, or @name is empty, 5340# GenericError 5341# - If the format of the image used does not support it, 5342# BlockFormatFeatureNotSupported 5343# 5344# Since: 1.7 5345# 5346# Example: 5347# 5348# -> { "execute": "blockdev-snapshot-internal-sync", 5349# "arguments": { "device": "ide-hd0", 5350# "name": "snapshot0" } 5351# } 5352# <- { "return": {} } 5353# 5354## 5355{ 'command': 'blockdev-snapshot-internal-sync', 5356 'data': 'BlockdevSnapshotInternal' } 5357 5358## 5359# @blockdev-snapshot-delete-internal-sync: 5360# 5361# Synchronously delete an internal snapshot of a block device, when the format 5362# of the image used support it. The snapshot is identified by name or id or 5363# both. One of the name or id is required. Return SnapshotInfo for the 5364# successfully deleted snapshot. 5365# 5366# @device: the device name or node-name of a root node to delete the snapshot 5367# from 5368# 5369# @id: optional the snapshot's ID to be deleted 5370# 5371# @name: optional the snapshot's name to be deleted 5372# 5373# Returns: - SnapshotInfo on success 5374# - If @device is not a valid block device, GenericError 5375# - If snapshot not found, GenericError 5376# - If the format of the image used does not support it, 5377# BlockFormatFeatureNotSupported 5378# - If @id and @name are both not specified, GenericError 5379# 5380# Since: 1.7 5381# 5382# Example: 5383# 5384# -> { "execute": "blockdev-snapshot-delete-internal-sync", 5385# "arguments": { "device": "ide-hd0", 5386# "name": "snapshot0" } 5387# } 5388# <- { "return": { 5389# "id": "1", 5390# "name": "snapshot0", 5391# "vm-state-size": 0, 5392# "date-sec": 1000012, 5393# "date-nsec": 10, 5394# "vm-clock-sec": 100, 5395# "vm-clock-nsec": 20, 5396# "icount": 220414 5397# } 5398# } 5399# 5400## 5401{ 'command': 'blockdev-snapshot-delete-internal-sync', 5402 'data': { 'device': 'str', '*id': 'str', '*name': 'str'}, 5403 'returns': 'SnapshotInfo' } 5404