1# -*- Mode: Python -*- 2# 3# QAPI block core definitions (vm unrelated) 4 5# QAPI common definitions 6{ 'include': 'common.json' } 7 8## 9# @SnapshotInfo 10# 11# @id: unique snapshot id 12# 13# @name: user chosen name 14# 15# @vm-state-size: size of the VM state 16# 17# @date-sec: UTC date of the snapshot in seconds 18# 19# @date-nsec: fractional part in nano seconds to be used with date-sec 20# 21# @vm-clock-sec: VM clock relative to boot in seconds 22# 23# @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec 24# 25# Since: 1.3 26# 27## 28 29{ 'struct': 'SnapshotInfo', 30 'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int', 31 'date-sec': 'int', 'date-nsec': 'int', 32 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int' } } 33 34## 35# @ImageInfoSpecificQCow2: 36# 37# @compat: compatibility level 38# 39# @lazy-refcounts: #optional on or off; only valid for compat >= 1.1 40# 41# @corrupt: #optional true if the image has been marked corrupt; only valid for 42# compat >= 1.1 (since 2.2) 43# 44# @refcount-bits: width of a refcount entry in bits (since 2.3) 45# 46# Since: 1.7 47## 48{ 'struct': 'ImageInfoSpecificQCow2', 49 'data': { 50 'compat': 'str', 51 '*lazy-refcounts': 'bool', 52 '*corrupt': 'bool', 53 'refcount-bits': 'int' 54 } } 55 56## 57# @ImageInfoSpecificVmdk: 58# 59# @create-type: The create type of VMDK image 60# 61# @cid: Content id of image 62# 63# @parent-cid: Parent VMDK image's cid 64# 65# @extents: List of extent files 66# 67# Since: 1.7 68## 69{ 'struct': 'ImageInfoSpecificVmdk', 70 'data': { 71 'create-type': 'str', 72 'cid': 'int', 73 'parent-cid': 'int', 74 'extents': ['ImageInfo'] 75 } } 76 77## 78# @ImageInfoSpecific: 79# 80# A discriminated record of image format specific information structures. 81# 82# Since: 1.7 83## 84 85{ 'union': 'ImageInfoSpecific', 86 'data': { 87 'qcow2': 'ImageInfoSpecificQCow2', 88 'vmdk': 'ImageInfoSpecificVmdk' 89 } } 90 91## 92# @ImageInfo: 93# 94# Information about a QEMU image file 95# 96# @filename: name of the image file 97# 98# @format: format of the image file 99# 100# @virtual-size: maximum capacity in bytes of the image 101# 102# @actual-size: #optional actual size on disk in bytes of the image 103# 104# @dirty-flag: #optional true if image is not cleanly closed 105# 106# @cluster-size: #optional size of a cluster in bytes 107# 108# @encrypted: #optional true if the image is encrypted 109# 110# @compressed: #optional true if the image is compressed (Since 1.7) 111# 112# @backing-filename: #optional name of the backing file 113# 114# @full-backing-filename: #optional full path of the backing file 115# 116# @backing-filename-format: #optional the format of the backing file 117# 118# @snapshots: #optional list of VM snapshots 119# 120# @backing-image: #optional info of the backing image (since 1.6) 121# 122# @format-specific: #optional structure supplying additional format-specific 123# information (since 1.7) 124# 125# Since: 1.3 126# 127## 128 129{ 'struct': 'ImageInfo', 130 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool', 131 '*actual-size': 'int', 'virtual-size': 'int', 132 '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool', 133 '*backing-filename': 'str', '*full-backing-filename': 'str', 134 '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'], 135 '*backing-image': 'ImageInfo', 136 '*format-specific': 'ImageInfoSpecific' } } 137 138## 139# @ImageCheck: 140# 141# Information about a QEMU image file check 142# 143# @filename: name of the image file checked 144# 145# @format: format of the image file checked 146# 147# @check-errors: number of unexpected errors occurred during check 148# 149# @image-end-offset: #optional offset (in bytes) where the image ends, this 150# field is present if the driver for the image format 151# supports it 152# 153# @corruptions: #optional number of corruptions found during the check if any 154# 155# @leaks: #optional number of leaks found during the check if any 156# 157# @corruptions-fixed: #optional number of corruptions fixed during the check 158# if any 159# 160# @leaks-fixed: #optional number of leaks fixed during the check if any 161# 162# @total-clusters: #optional total number of clusters, this field is present 163# if the driver for the image format supports it 164# 165# @allocated-clusters: #optional total number of allocated clusters, this 166# field is present if the driver for the image format 167# supports it 168# 169# @fragmented-clusters: #optional total number of fragmented clusters, this 170# field is present if the driver for the image format 171# supports it 172# 173# @compressed-clusters: #optional total number of compressed clusters, this 174# field is present if the driver for the image format 175# supports it 176# 177# Since: 1.4 178# 179## 180 181{ 'struct': 'ImageCheck', 182 'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int', 183 '*image-end-offset': 'int', '*corruptions': 'int', '*leaks': 'int', 184 '*corruptions-fixed': 'int', '*leaks-fixed': 'int', 185 '*total-clusters': 'int', '*allocated-clusters': 'int', 186 '*fragmented-clusters': 'int', '*compressed-clusters': 'int' } } 187 188## 189# @MapEntry: 190# 191# Mapping information from a virtual block range to a host file range 192# 193# @start: the start byte of the mapped virtual range 194# 195# @length: the number of bytes of the mapped virtual range 196# 197# @data: whether the mapped range has data 198# 199# @zero: whether the virtual blocks are zeroed 200# 201# @depth: the depth of the mapping 202# 203# @offset: #optional the offset in file that the virtual sectors are mapped to 204# 205# @filename: #optional filename that is referred to by @offset 206# 207# Since: 2.6 208# 209## 210{ 'struct': 'MapEntry', 211 'data': {'start': 'int', 'length': 'int', 'data': 'bool', 212 'zero': 'bool', 'depth': 'int', '*offset': 'int', 213 '*filename': 'str' } } 214 215## 216# @BlockdevCacheInfo 217# 218# Cache mode information for a block device 219# 220# @writeback: true if writeback mode is enabled 221# @direct: true if the host page cache is bypassed (O_DIRECT) 222# @no-flush: true if flush requests are ignored for the device 223# 224# Since: 2.3 225## 226{ 'struct': 'BlockdevCacheInfo', 227 'data': { 'writeback': 'bool', 228 'direct': 'bool', 229 'no-flush': 'bool' } } 230 231## 232# @BlockDeviceInfo: 233# 234# Information about the backing device for a block device. 235# 236# @file: the filename of the backing device 237# 238# @node-name: #optional the name of the block driver node (Since 2.0) 239# 240# @ro: true if the backing device was open read-only 241# 242# @drv: the name of the block format used to open the backing device. As of 243# 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg', 244# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 245# 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 246# 'qcow2', 'raw', 'tftp', 'vdi', 'vmdk', 'vpc', 'vvfat' 247# 2.2: 'archipelago' added, 'cow' dropped 248# 2.3: 'host_floppy' deprecated 249# 2.5: 'host_floppy' dropped 250# 2.6: 'luks' added 251# 252# @backing_file: #optional the name of the backing file (for copy-on-write) 253# 254# @backing_file_depth: number of files in the backing file chain (since: 1.2) 255# 256# @encrypted: true if the backing device is encrypted 257# 258# @encryption_key_missing: true if the backing device is encrypted but an 259# valid encryption key is missing 260# 261# @detect_zeroes: detect and optimize zero writes (Since 2.1) 262# 263# @bps: total throughput limit in bytes per second is specified 264# 265# @bps_rd: read throughput limit in bytes per second is specified 266# 267# @bps_wr: write throughput limit in bytes per second is specified 268# 269# @iops: total I/O operations per second is specified 270# 271# @iops_rd: read I/O operations per second is specified 272# 273# @iops_wr: write I/O operations per second is specified 274# 275# @image: the info of image used (since: 1.6) 276# 277# @bps_max: #optional total throughput limit during bursts, 278# in bytes (Since 1.7) 279# 280# @bps_rd_max: #optional read throughput limit during bursts, 281# in bytes (Since 1.7) 282# 283# @bps_wr_max: #optional write throughput limit during bursts, 284# in bytes (Since 1.7) 285# 286# @iops_max: #optional total I/O operations per second during bursts, 287# in bytes (Since 1.7) 288# 289# @iops_rd_max: #optional read I/O operations per second during bursts, 290# in bytes (Since 1.7) 291# 292# @iops_wr_max: #optional write I/O operations per second during bursts, 293# in bytes (Since 1.7) 294# 295# @bps_max_length: #optional maximum length of the @bps_max burst 296# period, in seconds. (Since 2.6) 297# 298# @bps_rd_max_length: #optional maximum length of the @bps_rd_max 299# burst period, in seconds. (Since 2.6) 300# 301# @bps_wr_max_length: #optional maximum length of the @bps_wr_max 302# burst period, in seconds. (Since 2.6) 303# 304# @iops_max_length: #optional maximum length of the @iops burst 305# period, in seconds. (Since 2.6) 306# 307# @iops_rd_max_length: #optional maximum length of the @iops_rd_max 308# burst period, in seconds. (Since 2.6) 309# 310# @iops_wr_max_length: #optional maximum length of the @iops_wr_max 311# burst period, in seconds. (Since 2.6) 312# 313# @iops_size: #optional an I/O size in bytes (Since 1.7) 314# 315# @group: #optional throttle group name (Since 2.4) 316# 317# @cache: the cache mode used for the block device (since: 2.3) 318# 319# @write_threshold: configured write threshold for the device. 320# 0 if disabled. (Since 2.3) 321# 322# Since: 0.14.0 323# 324## 325{ 'struct': 'BlockDeviceInfo', 326 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str', 327 '*backing_file': 'str', 'backing_file_depth': 'int', 328 'encrypted': 'bool', 'encryption_key_missing': 'bool', 329 'detect_zeroes': 'BlockdevDetectZeroesOptions', 330 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int', 331 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int', 332 'image': 'ImageInfo', 333 '*bps_max': 'int', '*bps_rd_max': 'int', 334 '*bps_wr_max': 'int', '*iops_max': 'int', 335 '*iops_rd_max': 'int', '*iops_wr_max': 'int', 336 '*bps_max_length': 'int', '*bps_rd_max_length': 'int', 337 '*bps_wr_max_length': 'int', '*iops_max_length': 'int', 338 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int', 339 '*iops_size': 'int', '*group': 'str', 'cache': 'BlockdevCacheInfo', 340 'write_threshold': 'int' } } 341 342## 343# @BlockDeviceIoStatus: 344# 345# An enumeration of block device I/O status. 346# 347# @ok: The last I/O operation has succeeded 348# 349# @failed: The last I/O operation has failed 350# 351# @nospace: The last I/O operation has failed due to a no-space condition 352# 353# Since: 1.0 354## 355{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] } 356 357## 358# @BlockDeviceMapEntry: 359# 360# Entry in the metadata map of the device (returned by "qemu-img map") 361# 362# @start: Offset in the image of the first byte described by this entry 363# (in bytes) 364# 365# @length: Length of the range described by this entry (in bytes) 366# 367# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.) 368# before reaching one for which the range is allocated. The value is 369# in the range 0 to the depth of the image chain - 1. 370# 371# @zero: the sectors in this range read as zeros 372# 373# @data: reading the image will actually read data from a file (in particular, 374# if @offset is present this means that the sectors are not simply 375# preallocated, but contain actual data in raw format) 376# 377# @offset: if present, the image file stores the data for this range in 378# raw format at the given offset. 379# 380# Since 1.7 381## 382{ 'struct': 'BlockDeviceMapEntry', 383 'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool', 384 'data': 'bool', '*offset': 'int' } } 385 386## 387# @DirtyBitmapStatus: 388# 389# An enumeration of possible states that a dirty bitmap can report to the user. 390# 391# @frozen: The bitmap is currently in-use by a backup operation or block job, 392# and is immutable. 393# 394# @disabled: The bitmap is currently in-use by an internal operation and is 395# read-only. It can still be deleted. 396# 397# @active: The bitmap is actively monitoring for new writes, and can be cleared, 398# deleted, or used for backup operations. 399# 400# Since: 2.4 401## 402{ 'enum': 'DirtyBitmapStatus', 403 'data': ['active', 'disabled', 'frozen'] } 404 405## 406# @BlockDirtyInfo: 407# 408# Block dirty bitmap information. 409# 410# @name: #optional the name of the dirty bitmap (Since 2.4) 411# 412# @count: number of dirty bytes according to the dirty bitmap 413# 414# @granularity: granularity of the dirty bitmap in bytes (since 1.4) 415# 416# @status: current status of the dirty bitmap (since 2.4) 417# 418# Since: 1.3 419## 420{ 'struct': 'BlockDirtyInfo', 421 'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32', 422 'status': 'DirtyBitmapStatus'} } 423 424## 425# @BlockInfo: 426# 427# Block device information. This structure describes a virtual device and 428# the backing device associated with it. 429# 430# @device: The device name associated with the virtual device. 431# 432# @type: This field is returned only for compatibility reasons, it should 433# not be used (always returns 'unknown') 434# 435# @removable: True if the device supports removable media. 436# 437# @locked: True if the guest has locked this device from having its media 438# removed 439# 440# @tray_open: #optional True if the device's tray is open 441# (only present if it has a tray) 442# 443# @dirty-bitmaps: #optional dirty bitmaps information (only present if the 444# driver has one or more dirty bitmaps) (Since 2.0) 445# 446# @io-status: #optional @BlockDeviceIoStatus. Only present if the device 447# supports it and the VM is configured to stop on errors 448# (supported device models: virtio-blk, ide, scsi-disk) 449# 450# @inserted: #optional @BlockDeviceInfo describing the device if media is 451# present 452# 453# Since: 0.14.0 454## 455{ 'struct': 'BlockInfo', 456 'data': {'device': 'str', 'type': 'str', 'removable': 'bool', 457 'locked': 'bool', '*inserted': 'BlockDeviceInfo', 458 '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus', 459 '*dirty-bitmaps': ['BlockDirtyInfo'] } } 460 461## 462# @query-block: 463# 464# Get a list of BlockInfo for all virtual block devices. 465# 466# Returns: a list of @BlockInfo describing each virtual block device 467# 468# Since: 0.14.0 469## 470{ 'command': 'query-block', 'returns': ['BlockInfo'] } 471 472 473## 474# @BlockDeviceTimedStats: 475# 476# Statistics of a block device during a given interval of time. 477# 478# @interval_length: Interval used for calculating the statistics, 479# in seconds. 480# 481# @min_rd_latency_ns: Minimum latency of read operations in the 482# defined interval, in nanoseconds. 483# 484# @min_wr_latency_ns: Minimum latency of write operations in the 485# defined interval, in nanoseconds. 486# 487# @min_flush_latency_ns: Minimum latency of flush operations in the 488# defined interval, in nanoseconds. 489# 490# @max_rd_latency_ns: Maximum latency of read operations in the 491# defined interval, in nanoseconds. 492# 493# @max_wr_latency_ns: Maximum latency of write operations in the 494# defined interval, in nanoseconds. 495# 496# @max_flush_latency_ns: Maximum latency of flush operations in the 497# defined interval, in nanoseconds. 498# 499# @avg_rd_latency_ns: Average latency of read operations in the 500# defined interval, in nanoseconds. 501# 502# @avg_wr_latency_ns: Average latency of write operations in the 503# defined interval, in nanoseconds. 504# 505# @avg_flush_latency_ns: Average latency of flush operations in the 506# defined interval, in nanoseconds. 507# 508# @avg_rd_queue_depth: Average number of pending read operations 509# in the defined interval. 510# 511# @avg_wr_queue_depth: Average number of pending write operations 512# in the defined interval. 513# 514# Since: 2.5 515## 516 517{ 'struct': 'BlockDeviceTimedStats', 518 'data': { 'interval_length': 'int', 'min_rd_latency_ns': 'int', 519 'max_rd_latency_ns': 'int', 'avg_rd_latency_ns': 'int', 520 'min_wr_latency_ns': 'int', 'max_wr_latency_ns': 'int', 521 'avg_wr_latency_ns': 'int', 'min_flush_latency_ns': 'int', 522 'max_flush_latency_ns': 'int', 'avg_flush_latency_ns': 'int', 523 'avg_rd_queue_depth': 'number', 'avg_wr_queue_depth': 'number' } } 524 525## 526# @BlockDeviceStats: 527# 528# Statistics of a virtual block device or a block backing device. 529# 530# @rd_bytes: The number of bytes read by the device. 531# 532# @wr_bytes: The number of bytes written by the device. 533# 534# @rd_operations: The number of read operations performed by the device. 535# 536# @wr_operations: The number of write operations performed by the device. 537# 538# @flush_operations: The number of cache flush operations performed by the 539# device (since 0.15.0) 540# 541# @flush_total_time_ns: Total time spend on cache flushes in nano-seconds 542# (since 0.15.0). 543# 544# @wr_total_time_ns: Total time spend on writes in nano-seconds (since 0.15.0). 545# 546# @rd_total_time_ns: Total_time_spend on reads in nano-seconds (since 0.15.0). 547# 548# @wr_highest_offset: The offset after the greatest byte written to the 549# device. The intended use of this information is for 550# growable sparse files (like qcow2) that are used on top 551# of a physical device. 552# 553# @rd_merged: Number of read requests that have been merged into another 554# request (Since 2.3). 555# 556# @wr_merged: Number of write requests that have been merged into another 557# request (Since 2.3). 558# 559# @idle_time_ns: #optional Time since the last I/O operation, in 560# nanoseconds. If the field is absent it means that 561# there haven't been any operations yet (Since 2.5). 562# 563# @failed_rd_operations: The number of failed read operations 564# performed by the device (Since 2.5) 565# 566# @failed_wr_operations: The number of failed write operations 567# performed by the device (Since 2.5) 568# 569# @failed_flush_operations: The number of failed flush operations 570# performed by the device (Since 2.5) 571# 572# @invalid_rd_operations: The number of invalid read operations 573# performed by the device (Since 2.5) 574# 575# @invalid_wr_operations: The number of invalid write operations 576# performed by the device (Since 2.5) 577# 578# @invalid_flush_operations: The number of invalid flush operations 579# performed by the device (Since 2.5) 580# 581# @account_invalid: Whether invalid operations are included in the 582# last access statistics (Since 2.5) 583# 584# @account_failed: Whether failed operations are included in the 585# latency and last access statistics (Since 2.5) 586# 587# @timed_stats: Statistics specific to the set of previously defined 588# intervals of time (Since 2.5) 589# 590# Since: 0.14.0 591## 592{ 'struct': 'BlockDeviceStats', 593 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'rd_operations': 'int', 594 'wr_operations': 'int', 'flush_operations': 'int', 595 'flush_total_time_ns': 'int', 'wr_total_time_ns': 'int', 596 'rd_total_time_ns': 'int', 'wr_highest_offset': 'int', 597 'rd_merged': 'int', 'wr_merged': 'int', '*idle_time_ns': 'int', 598 'failed_rd_operations': 'int', 'failed_wr_operations': 'int', 599 'failed_flush_operations': 'int', 'invalid_rd_operations': 'int', 600 'invalid_wr_operations': 'int', 'invalid_flush_operations': 'int', 601 'account_invalid': 'bool', 'account_failed': 'bool', 602 'timed_stats': ['BlockDeviceTimedStats'] } } 603 604## 605# @BlockStats: 606# 607# Statistics of a virtual block device or a block backing device. 608# 609# @device: #optional If the stats are for a virtual block device, the name 610# corresponding to the virtual block device. 611# 612# @node-name: #optional The node name of the device. (Since 2.3) 613# 614# @stats: A @BlockDeviceStats for the device. 615# 616# @parent: #optional This describes the file block device if it has one. 617# 618# @backing: #optional This describes the backing block device if it has one. 619# (Since 2.0) 620# 621# Since: 0.14.0 622## 623{ 'struct': 'BlockStats', 624 'data': {'*device': 'str', '*node-name': 'str', 625 'stats': 'BlockDeviceStats', 626 '*parent': 'BlockStats', 627 '*backing': 'BlockStats'} } 628 629## 630# @query-blockstats: 631# 632# Query the @BlockStats for all virtual block devices. 633# 634# @query-nodes: #optional If true, the command will query all the block nodes 635# that have a node name, in a list which will include "parent" 636# information, but not "backing". 637# If false or omitted, the behavior is as before - query all the 638# device backends, recursively including their "parent" and 639# "backing". (Since 2.3) 640# 641# Returns: A list of @BlockStats for each virtual block devices. 642# 643# Since: 0.14.0 644## 645{ 'command': 'query-blockstats', 646 'data': { '*query-nodes': 'bool' }, 647 'returns': ['BlockStats'] } 648 649## 650# @BlockdevOnError: 651# 652# An enumeration of possible behaviors for errors on I/O operations. 653# The exact meaning depends on whether the I/O was initiated by a guest 654# or by a block job 655# 656# @report: for guest operations, report the error to the guest; 657# for jobs, cancel the job 658# 659# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR 660# or BLOCK_JOB_ERROR) 661# 662# @enospc: same as @stop on ENOSPC, same as @report otherwise. 663# 664# @stop: for guest operations, stop the virtual machine; 665# for jobs, pause the job 666# 667# @auto: inherit the error handling policy of the backend (since: 2.7) 668# 669# Since: 1.3 670## 671{ 'enum': 'BlockdevOnError', 672 'data': ['report', 'ignore', 'enospc', 'stop', 'auto'] } 673 674## 675# @MirrorSyncMode: 676# 677# An enumeration of possible behaviors for the initial synchronization 678# phase of storage mirroring. 679# 680# @top: copies data in the topmost image to the destination 681# 682# @full: copies data from all images to the destination 683# 684# @none: only copy data written from now on 685# 686# @incremental: only copy data described by the dirty bitmap. Since: 2.4 687# 688# Since: 1.3 689## 690{ 'enum': 'MirrorSyncMode', 691 'data': ['top', 'full', 'none', 'incremental'] } 692 693## 694# @BlockJobType: 695# 696# Type of a block job. 697# 698# @commit: block commit job type, see "block-commit" 699# 700# @stream: block stream job type, see "block-stream" 701# 702# @mirror: drive mirror job type, see "drive-mirror" 703# 704# @backup: drive backup job type, see "drive-backup" 705# 706# Since: 1.7 707## 708{ 'enum': 'BlockJobType', 709 'data': ['commit', 'stream', 'mirror', 'backup'] } 710 711## 712# @BlockJobInfo: 713# 714# Information about a long-running block device operation. 715# 716# @type: the job type ('stream' for image streaming) 717# 718# @device: The job identifier. Originally the device name but other 719# values are allowed since QEMU 2.7 720# 721# @len: the maximum progress value 722# 723# @busy: false if the job is known to be in a quiescent state, with 724# no pending I/O. Since 1.3. 725# 726# @paused: whether the job is paused or, if @busy is true, will 727# pause itself as soon as possible. Since 1.3. 728# 729# @offset: the current progress value 730# 731# @speed: the rate limit, bytes per second 732# 733# @io-status: the status of the job (since 1.3) 734# 735# @ready: true if the job may be completed (since 2.2) 736# 737# Since: 1.1 738## 739{ 'struct': 'BlockJobInfo', 740 'data': {'type': 'str', 'device': 'str', 'len': 'int', 741 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int', 742 'io-status': 'BlockDeviceIoStatus', 'ready': 'bool'} } 743 744## 745# @query-block-jobs: 746# 747# Return information about long-running block device operations. 748# 749# Returns: a list of @BlockJobInfo for each active block job 750# 751# Since: 1.1 752## 753{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] } 754 755## 756# @block_passwd: 757# 758# This command sets the password of a block device that has not been open 759# with a password and requires one. 760# 761# The two cases where this can happen are a block device is created through 762# QEMU's initial command line or a block device is changed through the legacy 763# @change interface. 764# 765# In the event that the block device is created through the initial command 766# line, the VM will start in the stopped state regardless of whether '-S' is 767# used. The intention is for a management tool to query the block devices to 768# determine which ones are encrypted, set the passwords with this command, and 769# then start the guest with the @cont command. 770# 771# Either @device or @node-name must be set but not both. 772# 773# @device: #optional the name of the block backend device to set the password on 774# 775# @node-name: #optional graph node name to set the password on (Since 2.0) 776# 777# @password: the password to use for the device 778# 779# Returns: nothing on success 780# If @device is not a valid block device, DeviceNotFound 781# If @device is not encrypted, DeviceNotEncrypted 782# 783# Notes: Not all block formats support encryption and some that do are not 784# able to validate that a password is correct. Disk corruption may 785# occur if an invalid password is specified. 786# 787# Since: 0.14.0 788## 789{ 'command': 'block_passwd', 'data': {'*device': 'str', 790 '*node-name': 'str', 'password': 'str'} } 791 792## 793# @block_resize 794# 795# Resize a block image while a guest is running. 796# 797# Either @device or @node-name must be set but not both. 798# 799# @device: #optional the name of the device to get the image resized 800# 801# @node-name: #optional graph node name to get the image resized (Since 2.0) 802# 803# @size: new image size in bytes 804# 805# Returns: nothing on success 806# If @device is not a valid block device, DeviceNotFound 807# 808# Since: 0.14.0 809## 810{ 'command': 'block_resize', 'data': { '*device': 'str', 811 '*node-name': 'str', 812 'size': 'int' }} 813 814## 815# @NewImageMode 816# 817# An enumeration that tells QEMU how to set the backing file path in 818# a new image file. 819# 820# @existing: QEMU should look for an existing image file. 821# 822# @absolute-paths: QEMU should create a new image with absolute paths 823# for the backing file. If there is no backing file available, the new 824# image will not be backed either. 825# 826# Since: 1.1 827## 828{ 'enum': 'NewImageMode', 829 'data': [ 'existing', 'absolute-paths' ] } 830 831## 832# @BlockdevSnapshotSync 833# 834# Either @device or @node-name must be set but not both. 835# 836# @device: #optional the name of the device to generate the snapshot from. 837# 838# @node-name: #optional graph node name to generate the snapshot from (Since 2.0) 839# 840# @snapshot-file: the target of the new image. A new file will be created. 841# 842# @snapshot-node-name: #optional the graph node name of the new image (Since 2.0) 843# 844# @format: #optional the format of the snapshot image, default is 'qcow2'. 845# 846# @mode: #optional whether and how QEMU should create a new image, default is 847# 'absolute-paths'. 848## 849{ 'struct': 'BlockdevSnapshotSync', 850 'data': { '*device': 'str', '*node-name': 'str', 851 'snapshot-file': 'str', '*snapshot-node-name': 'str', 852 '*format': 'str', '*mode': 'NewImageMode' } } 853 854## 855# @BlockdevSnapshot 856# 857# @node: device or node name that will have a snapshot created. 858# 859# @overlay: reference to the existing block device that will become 860# the overlay of @node, as part of creating the snapshot. 861# It must not have a current backing file (this can be 862# achieved by passing "backing": "" to blockdev-add). 863# 864# Since 2.5 865## 866{ 'struct': 'BlockdevSnapshot', 867 'data': { 'node': 'str', 'overlay': 'str' } } 868 869## 870# @DriveBackup 871# 872# @job-id: #optional identifier for the newly-created block job. If 873# omitted, the device name will be used. (Since 2.7) 874# 875# @device: the name of the device which should be copied. 876# 877# @target: the target of the new image. If the file exists, or if it 878# is a device, the existing file/device will be used as the new 879# destination. If it does not exist, a new file will be created. 880# 881# @format: #optional the format of the new destination, default is to 882# probe if @mode is 'existing', else the format of the source 883# 884# @sync: what parts of the disk image should be copied to the destination 885# (all the disk, only the sectors allocated in the topmost image, from a 886# dirty bitmap, or only new I/O). 887# 888# @mode: #optional whether and how QEMU should create a new image, default is 889# 'absolute-paths'. 890# 891# @speed: #optional the maximum speed, in bytes per second 892# 893# @bitmap: #optional the name of dirty bitmap if sync is "incremental". 894# Must be present if sync is "incremental", must NOT be present 895# otherwise. (Since 2.4) 896# 897# @on-source-error: #optional the action to take on an error on the source, 898# default 'report'. 'stop' and 'enospc' can only be used 899# if the block device supports io-status (see BlockInfo). 900# 901# @on-target-error: #optional the action to take on an error on the target, 902# default 'report' (no limitations, since this applies to 903# a different block device than @device). 904# 905# Note that @on-source-error and @on-target-error only affect background I/O. 906# If an error occurs during a guest write request, the device's rerror/werror 907# actions will be used. 908# 909# Since: 1.6 910## 911{ 'struct': 'DriveBackup', 912 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 913 '*format': 'str', 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode', 914 '*speed': 'int', '*bitmap': 'str', 915 '*on-source-error': 'BlockdevOnError', 916 '*on-target-error': 'BlockdevOnError' } } 917 918## 919# @BlockdevBackup 920# 921# @job-id: #optional identifier for the newly-created block job. If 922# omitted, the device name will be used. (Since 2.7) 923# 924# @device: the name of the device which should be copied. 925# 926# @target: the name of the backup target device. 927# 928# @sync: what parts of the disk image should be copied to the destination 929# (all the disk, only the sectors allocated in the topmost image, or 930# only new I/O). 931# 932# @speed: #optional the maximum speed, in bytes per second. The default is 0, 933# for unlimited. 934# 935# @on-source-error: #optional the action to take on an error on the source, 936# default 'report'. 'stop' and 'enospc' can only be used 937# if the block device supports io-status (see BlockInfo). 938# 939# @on-target-error: #optional the action to take on an error on the target, 940# default 'report' (no limitations, since this applies to 941# a different block device than @device). 942# 943# Note that @on-source-error and @on-target-error only affect background I/O. 944# If an error occurs during a guest write request, the device's rerror/werror 945# actions will be used. 946# 947# Since: 2.3 948## 949{ 'struct': 'BlockdevBackup', 950 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 951 'sync': 'MirrorSyncMode', 952 '*speed': 'int', 953 '*on-source-error': 'BlockdevOnError', 954 '*on-target-error': 'BlockdevOnError' } } 955 956## 957# @blockdev-snapshot-sync 958# 959# Generates a synchronous snapshot of a block device. 960# 961# For the arguments, see the documentation of BlockdevSnapshotSync. 962# 963# Returns: nothing on success 964# If @device is not a valid block device, DeviceNotFound 965# 966# Since 0.14.0 967## 968{ 'command': 'blockdev-snapshot-sync', 969 'data': 'BlockdevSnapshotSync' } 970 971 972## 973# @blockdev-snapshot 974# 975# Generates a snapshot of a block device. 976# 977# For the arguments, see the documentation of BlockdevSnapshot. 978# 979# Since 2.5 980## 981{ 'command': 'blockdev-snapshot', 982 'data': 'BlockdevSnapshot' } 983 984## 985# @change-backing-file 986# 987# Change the backing file in the image file metadata. This does not 988# cause QEMU to reopen the image file to reparse the backing filename 989# (it may, however, perform a reopen to change permissions from 990# r/o -> r/w -> r/o, if needed). The new backing file string is written 991# into the image file metadata, and the QEMU internal strings are 992# updated. 993# 994# @image-node-name: The name of the block driver state node of the 995# image to modify. 996# 997# @device: The name of the device that owns image-node-name. 998# 999# @backing-file: The string to write as the backing file. This 1000# string is not validated, so care should be taken 1001# when specifying the string or the image chain may 1002# not be able to be reopened again. 1003# 1004# Since: 2.1 1005## 1006{ 'command': 'change-backing-file', 1007 'data': { 'device': 'str', 'image-node-name': 'str', 1008 'backing-file': 'str' } } 1009 1010## 1011# @block-commit 1012# 1013# Live commit of data from overlay image nodes into backing nodes - i.e., 1014# writes data between 'top' and 'base' into 'base'. 1015# 1016# @job-id: #optional identifier for the newly-created block job. If 1017# omitted, the device name will be used. (Since 2.7) 1018# 1019# @device: the name of the device 1020# 1021# @base: #optional The file name of the backing image to write data into. 1022# If not specified, this is the deepest backing image 1023# 1024# @top: #optional The file name of the backing image within the image chain, 1025# which contains the topmost data to be committed down. If 1026# not specified, this is the active layer. 1027# 1028# @backing-file: #optional The backing file string to write into the overlay 1029# image of 'top'. If 'top' is the active layer, 1030# specifying a backing file string is an error. This 1031# filename is not validated. 1032# 1033# If a pathname string is such that it cannot be 1034# resolved by QEMU, that means that subsequent QMP or 1035# HMP commands must use node-names for the image in 1036# question, as filename lookup methods will fail. 1037# 1038# If not specified, QEMU will automatically determine 1039# the backing file string to use, or error out if 1040# there is no obvious choice. Care should be taken 1041# when specifying the string, to specify a valid 1042# filename or protocol. 1043# (Since 2.1) 1044# 1045# If top == base, that is an error. 1046# If top == active, the job will not be completed by itself, 1047# user needs to complete the job with the block-job-complete 1048# command after getting the ready event. (Since 2.0) 1049# 1050# If the base image is smaller than top, then the base image 1051# will be resized to be the same size as top. If top is 1052# smaller than the base image, the base will not be 1053# truncated. If you want the base image size to match the 1054# size of the smaller top, you can safely truncate it 1055# yourself once the commit operation successfully completes. 1056# 1057# @speed: #optional the maximum speed, in bytes per second 1058# 1059# Returns: Nothing on success 1060# If commit or stream is already active on this device, DeviceInUse 1061# If @device does not exist, DeviceNotFound 1062# If image commit is not supported by this device, NotSupported 1063# If @base or @top is invalid, a generic error is returned 1064# If @speed is invalid, InvalidParameter 1065# 1066# Since: 1.3 1067# 1068## 1069{ 'command': 'block-commit', 1070 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', '*top': 'str', 1071 '*backing-file': 'str', '*speed': 'int' } } 1072 1073## 1074# @drive-backup 1075# 1076# Start a point-in-time copy of a block device to a new destination. The 1077# status of ongoing drive-backup operations can be checked with 1078# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1079# The operation can be stopped before it has completed using the 1080# block-job-cancel command. 1081# 1082# For the arguments, see the documentation of DriveBackup. 1083# 1084# Returns: nothing on success 1085# If @device is not a valid block device, DeviceNotFound 1086# 1087# Since 1.6 1088## 1089{ 'command': 'drive-backup', 'data': 'DriveBackup' } 1090 1091## 1092# @blockdev-backup 1093# 1094# Start a point-in-time copy of a block device to a new destination. The 1095# status of ongoing blockdev-backup operations can be checked with 1096# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1097# The operation can be stopped before it has completed using the 1098# block-job-cancel command. 1099# 1100# For the arguments, see the documentation of BlockdevBackup. 1101# 1102# Since 2.3 1103## 1104{ 'command': 'blockdev-backup', 'data': 'BlockdevBackup' } 1105 1106 1107## 1108# @query-named-block-nodes 1109# 1110# Get the named block driver list 1111# 1112# Returns: the list of BlockDeviceInfo 1113# 1114# Since 2.0 1115## 1116{ 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ] } 1117 1118## 1119# @drive-mirror 1120# 1121# Start mirroring a block device's writes to a new destination. 1122# 1123# See DriveMirror for parameter descriptions 1124# 1125# Returns: nothing on success 1126# If @device is not a valid block device, DeviceNotFound 1127# 1128# Since 1.3 1129## 1130{ 'command': 'drive-mirror', 'boxed': true, 1131 'data': 'DriveMirror' } 1132 1133## 1134# DriveMirror 1135# 1136# A set of parameters describing drive mirror setup. 1137# 1138# @job-id: #optional identifier for the newly-created block job. If 1139# omitted, the device name will be used. (Since 2.7) 1140# 1141# @device: the name of the device whose writes should be mirrored. 1142# 1143# @target: the target of the new image. If the file exists, or if it 1144# is a device, the existing file/device will be used as the new 1145# destination. If it does not exist, a new file will be created. 1146# 1147# @format: #optional the format of the new destination, default is to 1148# probe if @mode is 'existing', else the format of the source 1149# 1150# @node-name: #optional the new block driver state node name in the graph 1151# (Since 2.1) 1152# 1153# @replaces: #optional with sync=full graph node name to be replaced by the new 1154# image when a whole image copy is done. This can be used to repair 1155# broken Quorum files. (Since 2.1) 1156# 1157# @mode: #optional whether and how QEMU should create a new image, default is 1158# 'absolute-paths'. 1159# 1160# @speed: #optional the maximum speed, in bytes per second 1161# 1162# @sync: what parts of the disk image should be copied to the destination 1163# (all the disk, only the sectors allocated in the topmost image, or 1164# only new I/O). 1165# 1166# @granularity: #optional granularity of the dirty bitmap, default is 64K 1167# if the image format doesn't have clusters, 4K if the clusters 1168# are smaller than that, else the cluster size. Must be a 1169# power of 2 between 512 and 64M (since 1.4). 1170# 1171# @buf-size: #optional maximum amount of data in flight from source to 1172# target (since 1.4). 1173# 1174# @on-source-error: #optional the action to take on an error on the source, 1175# default 'report'. 'stop' and 'enospc' can only be used 1176# if the block device supports io-status (see BlockInfo). 1177# 1178# @on-target-error: #optional the action to take on an error on the target, 1179# default 'report' (no limitations, since this applies to 1180# a different block device than @device). 1181# @unmap: #optional Whether to try to unmap target sectors where source has 1182# only zero. If true, and target unallocated sectors will read as zero, 1183# target image sectors will be unmapped; otherwise, zeroes will be 1184# written. Both will result in identical contents. 1185# Default is true. (Since 2.4) 1186# 1187# Since 1.3 1188## 1189{ 'struct': 'DriveMirror', 1190 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 1191 '*format': 'str', '*node-name': 'str', '*replaces': 'str', 1192 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode', 1193 '*speed': 'int', '*granularity': 'uint32', 1194 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError', 1195 '*on-target-error': 'BlockdevOnError', 1196 '*unmap': 'bool' } } 1197 1198## 1199# @BlockDirtyBitmap 1200# 1201# @node: name of device/node which the bitmap is tracking 1202# 1203# @name: name of the dirty bitmap 1204# 1205# Since 2.4 1206## 1207{ 'struct': 'BlockDirtyBitmap', 1208 'data': { 'node': 'str', 'name': 'str' } } 1209 1210## 1211# @BlockDirtyBitmapAdd 1212# 1213# @node: name of device/node which the bitmap is tracking 1214# 1215# @name: name of the dirty bitmap 1216# 1217# @granularity: #optional the bitmap granularity, default is 64k for 1218# block-dirty-bitmap-add 1219# 1220# Since 2.4 1221## 1222{ 'struct': 'BlockDirtyBitmapAdd', 1223 'data': { 'node': 'str', 'name': 'str', '*granularity': 'uint32' } } 1224 1225## 1226# @block-dirty-bitmap-add 1227# 1228# Create a dirty bitmap with a name on the node 1229# 1230# Returns: nothing on success 1231# If @node is not a valid block device or node, DeviceNotFound 1232# If @name is already taken, GenericError with an explanation 1233# 1234# Since 2.4 1235## 1236{ 'command': 'block-dirty-bitmap-add', 1237 'data': 'BlockDirtyBitmapAdd' } 1238 1239## 1240# @block-dirty-bitmap-remove 1241# 1242# Remove a dirty bitmap on the node 1243# 1244# Returns: nothing on success 1245# If @node is not a valid block device or node, DeviceNotFound 1246# If @name is not found, GenericError with an explanation 1247# if @name is frozen by an operation, GenericError 1248# 1249# Since 2.4 1250## 1251{ 'command': 'block-dirty-bitmap-remove', 1252 'data': 'BlockDirtyBitmap' } 1253 1254## 1255# @block-dirty-bitmap-clear 1256# 1257# Clear (reset) a dirty bitmap on the device 1258# 1259# Returns: nothing on success 1260# If @node is not a valid block device, DeviceNotFound 1261# If @name is not found, GenericError with an explanation 1262# 1263# Since 2.4 1264## 1265{ 'command': 'block-dirty-bitmap-clear', 1266 'data': 'BlockDirtyBitmap' } 1267 1268## 1269# @blockdev-mirror 1270# 1271# Start mirroring a block device's writes to a new destination. 1272# 1273# @job-id: #optional identifier for the newly-created block job. If 1274# omitted, the device name will be used. (Since 2.7) 1275# 1276# @device: the name of the device whose writes should be mirrored. 1277# 1278# @target: the id or node-name of the block device to mirror to. This mustn't be 1279# attached to guest. 1280# 1281# @replaces: #optional with sync=full graph node name to be replaced by the new 1282# image when a whole image copy is done. This can be used to repair 1283# broken Quorum files. 1284# 1285# @speed: #optional the maximum speed, in bytes per second 1286# 1287# @sync: what parts of the disk image should be copied to the destination 1288# (all the disk, only the sectors allocated in the topmost image, or 1289# only new I/O). 1290# 1291# @granularity: #optional granularity of the dirty bitmap, default is 64K 1292# if the image format doesn't have clusters, 4K if the clusters 1293# are smaller than that, else the cluster size. Must be a 1294# power of 2 between 512 and 64M 1295# 1296# @buf-size: #optional maximum amount of data in flight from source to 1297# target 1298# 1299# @on-source-error: #optional the action to take on an error on the source, 1300# default 'report'. 'stop' and 'enospc' can only be used 1301# if the block device supports io-status (see BlockInfo). 1302# 1303# @on-target-error: #optional the action to take on an error on the target, 1304# default 'report' (no limitations, since this applies to 1305# a different block device than @device). 1306# 1307# Returns: nothing on success. 1308# 1309# Since 2.6 1310## 1311{ 'command': 'blockdev-mirror', 1312 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 1313 '*replaces': 'str', 1314 'sync': 'MirrorSyncMode', 1315 '*speed': 'int', '*granularity': 'uint32', 1316 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError', 1317 '*on-target-error': 'BlockdevOnError' } } 1318 1319## 1320# @block_set_io_throttle: 1321# 1322# Change I/O throttle limits for a block drive. 1323# 1324# Since QEMU 2.4, each device with I/O limits is member of a throttle 1325# group. 1326# 1327# If two or more devices are members of the same group, the limits 1328# will apply to the combined I/O of the whole group in a round-robin 1329# fashion. Therefore, setting new I/O limits to a device will affect 1330# the whole group. 1331# 1332# The name of the group can be specified using the 'group' parameter. 1333# If the parameter is unset, it is assumed to be the current group of 1334# that device. If it's not in any group yet, the name of the device 1335# will be used as the name for its group. 1336# 1337# The 'group' parameter can also be used to move a device to a 1338# different group. In this case the limits specified in the parameters 1339# will be applied to the new group only. 1340# 1341# I/O limits can be disabled by setting all of them to 0. In this case 1342# the device will be removed from its group and the rest of its 1343# members will not be affected. The 'group' parameter is ignored. 1344# 1345# See BlockIOThrottle for parameter descriptions. 1346# 1347# Returns: Nothing on success 1348# If @device is not a valid block device, DeviceNotFound 1349# 1350# Since: 1.1 1351## 1352{ 'command': 'block_set_io_throttle', 'boxed': true, 1353 'data': 'BlockIOThrottle' } 1354 1355## 1356# BlockIOThrottle 1357# 1358# A set of parameters describing block throttling. 1359# 1360# @device: The name of the device 1361# 1362# @bps: total throughput limit in bytes per second 1363# 1364# @bps_rd: read throughput limit in bytes per second 1365# 1366# @bps_wr: write throughput limit in bytes per second 1367# 1368# @iops: total I/O operations per second 1369# 1370# @iops_rd: read I/O operations per second 1371# 1372# @iops_wr: write I/O operations per second 1373# 1374# @bps_max: #optional total throughput limit during bursts, 1375# in bytes (Since 1.7) 1376# 1377# @bps_rd_max: #optional read throughput limit during bursts, 1378# in bytes (Since 1.7) 1379# 1380# @bps_wr_max: #optional write throughput limit during bursts, 1381# in bytes (Since 1.7) 1382# 1383# @iops_max: #optional total I/O operations per second during bursts, 1384# in bytes (Since 1.7) 1385# 1386# @iops_rd_max: #optional read I/O operations per second during bursts, 1387# in bytes (Since 1.7) 1388# 1389# @iops_wr_max: #optional write I/O operations per second during bursts, 1390# in bytes (Since 1.7) 1391# 1392# @bps_max_length: #optional maximum length of the @bps_max burst 1393# period, in seconds. It must only 1394# be set if @bps_max is set as well. 1395# Defaults to 1. (Since 2.6) 1396# 1397# @bps_rd_max_length: #optional maximum length of the @bps_rd_max 1398# burst period, in seconds. It must only 1399# be set if @bps_rd_max is set as well. 1400# Defaults to 1. (Since 2.6) 1401# 1402# @bps_wr_max_length: #optional maximum length of the @bps_wr_max 1403# burst period, in seconds. It must only 1404# be set if @bps_wr_max is set as well. 1405# Defaults to 1. (Since 2.6) 1406# 1407# @iops_max_length: #optional maximum length of the @iops burst 1408# period, in seconds. It must only 1409# be set if @iops_max is set as well. 1410# Defaults to 1. (Since 2.6) 1411# 1412# @iops_rd_max_length: #optional maximum length of the @iops_rd_max 1413# burst period, in seconds. It must only 1414# be set if @iops_rd_max is set as well. 1415# Defaults to 1. (Since 2.6) 1416# 1417# @iops_wr_max_length: #optional maximum length of the @iops_wr_max 1418# burst period, in seconds. It must only 1419# be set if @iops_wr_max is set as well. 1420# Defaults to 1. (Since 2.6) 1421# 1422# @iops_size: #optional an I/O size in bytes (Since 1.7) 1423# 1424# @group: #optional throttle group name (Since 2.4) 1425# 1426# Since: 1.1 1427## 1428{ 'struct': 'BlockIOThrottle', 1429 'data': { 'device': 'str', 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int', 1430 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int', 1431 '*bps_max': 'int', '*bps_rd_max': 'int', 1432 '*bps_wr_max': 'int', '*iops_max': 'int', 1433 '*iops_rd_max': 'int', '*iops_wr_max': 'int', 1434 '*bps_max_length': 'int', '*bps_rd_max_length': 'int', 1435 '*bps_wr_max_length': 'int', '*iops_max_length': 'int', 1436 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int', 1437 '*iops_size': 'int', '*group': 'str' } } 1438 1439## 1440# @block-stream: 1441# 1442# Copy data from a backing file into a block device. 1443# 1444# The block streaming operation is performed in the background until the entire 1445# backing file has been copied. This command returns immediately once streaming 1446# has started. The status of ongoing block streaming operations can be checked 1447# with query-block-jobs. The operation can be stopped before it has completed 1448# using the block-job-cancel command. 1449# 1450# If a base file is specified then sectors are not copied from that base file and 1451# its backing chain. When streaming completes the image file will have the base 1452# file as its backing file. This can be used to stream a subset of the backing 1453# file chain instead of flattening the entire image. 1454# 1455# On successful completion the image file is updated to drop the backing file 1456# and the BLOCK_JOB_COMPLETED event is emitted. 1457# 1458# @job-id: #optional identifier for the newly-created block job. If 1459# omitted, the device name will be used. (Since 2.7) 1460# 1461# @device: the device name 1462# 1463# @base: #optional the common backing file name 1464# 1465# @backing-file: #optional The backing file string to write into the active 1466# layer. This filename is not validated. 1467# 1468# If a pathname string is such that it cannot be 1469# resolved by QEMU, that means that subsequent QMP or 1470# HMP commands must use node-names for the image in 1471# question, as filename lookup methods will fail. 1472# 1473# If not specified, QEMU will automatically determine 1474# the backing file string to use, or error out if there 1475# is no obvious choice. Care should be taken when 1476# specifying the string, to specify a valid filename or 1477# protocol. 1478# (Since 2.1) 1479# 1480# @speed: #optional the maximum speed, in bytes per second 1481# 1482# @on-error: #optional the action to take on an error (default report). 1483# 'stop' and 'enospc' can only be used if the block device 1484# supports io-status (see BlockInfo). Since 1.3. 1485# 1486# Returns: Nothing on success 1487# If @device does not exist, DeviceNotFound 1488# 1489# Since: 1.1 1490## 1491{ 'command': 'block-stream', 1492 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', 1493 '*backing-file': 'str', '*speed': 'int', 1494 '*on-error': 'BlockdevOnError' } } 1495 1496## 1497# @block-job-set-speed: 1498# 1499# Set maximum speed for a background block operation. 1500# 1501# This command can only be issued when there is an active block job. 1502# 1503# Throttling can be disabled by setting the speed to 0. 1504# 1505# @device: The job identifier. This used to be a device name (hence 1506# the name of the parameter), but since QEMU 2.7 it can have 1507# other values. 1508# 1509# @speed: the maximum speed, in bytes per second, or 0 for unlimited. 1510# Defaults to 0. 1511# 1512# Returns: Nothing on success 1513# If no background operation is active on this device, DeviceNotActive 1514# 1515# Since: 1.1 1516## 1517{ 'command': 'block-job-set-speed', 1518 'data': { 'device': 'str', 'speed': 'int' } } 1519 1520## 1521# @block-job-cancel: 1522# 1523# Stop an active background block operation. 1524# 1525# This command returns immediately after marking the active background block 1526# operation for cancellation. It is an error to call this command if no 1527# operation is in progress. 1528# 1529# The operation will cancel as soon as possible and then emit the 1530# BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when 1531# enumerated using query-block-jobs. 1532# 1533# For streaming, the image file retains its backing file unless the streaming 1534# operation happens to complete just as it is being cancelled. A new streaming 1535# operation can be started at a later time to finish copying all data from the 1536# backing file. 1537# 1538# @device: The job identifier. This used to be a device name (hence 1539# the name of the parameter), but since QEMU 2.7 it can have 1540# other values. 1541# 1542# @force: #optional whether to allow cancellation of a paused job (default 1543# false). Since 1.3. 1544# 1545# Returns: Nothing on success 1546# If no background operation is active on this device, DeviceNotActive 1547# 1548# Since: 1.1 1549## 1550{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } } 1551 1552## 1553# @block-job-pause: 1554# 1555# Pause an active background block operation. 1556# 1557# This command returns immediately after marking the active background block 1558# operation for pausing. It is an error to call this command if no 1559# operation is in progress. Pausing an already paused job has no cumulative 1560# effect; a single block-job-resume command will resume the job. 1561# 1562# The operation will pause as soon as possible. No event is emitted when 1563# the operation is actually paused. Cancelling a paused job automatically 1564# resumes it. 1565# 1566# @device: The job identifier. This used to be a device name (hence 1567# the name of the parameter), but since QEMU 2.7 it can have 1568# other values. 1569# 1570# Returns: Nothing on success 1571# If no background operation is active on this device, DeviceNotActive 1572# 1573# Since: 1.3 1574## 1575{ 'command': 'block-job-pause', 'data': { 'device': 'str' } } 1576 1577## 1578# @block-job-resume: 1579# 1580# Resume an active background block operation. 1581# 1582# This command returns immediately after resuming a paused background block 1583# operation. It is an error to call this command if no operation is in 1584# progress. Resuming an already running job is not an error. 1585# 1586# This command also clears the error status of the job. 1587# 1588# @device: The job identifier. This used to be a device name (hence 1589# the name of the parameter), but since QEMU 2.7 it can have 1590# other values. 1591# 1592# Returns: Nothing on success 1593# If no background operation is active on this device, DeviceNotActive 1594# 1595# Since: 1.3 1596## 1597{ 'command': 'block-job-resume', 'data': { 'device': 'str' } } 1598 1599## 1600# @block-job-complete: 1601# 1602# Manually trigger completion of an active background block operation. This 1603# is supported for drive mirroring, where it also switches the device to 1604# write to the target path only. The ability to complete is signaled with 1605# a BLOCK_JOB_READY event. 1606# 1607# This command completes an active background block operation synchronously. 1608# The ordering of this command's return with the BLOCK_JOB_COMPLETED event 1609# is not defined. Note that if an I/O error occurs during the processing of 1610# this command: 1) the command itself will fail; 2) the error will be processed 1611# according to the rerror/werror arguments that were specified when starting 1612# the operation. 1613# 1614# A cancelled or paused job cannot be completed. 1615# 1616# @device: The job identifier. This used to be a device name (hence 1617# the name of the parameter), but since QEMU 2.7 it can have 1618# other values. 1619# 1620# Returns: Nothing on success 1621# If no background operation is active on this device, DeviceNotActive 1622# 1623# Since: 1.3 1624## 1625{ 'command': 'block-job-complete', 'data': { 'device': 'str' } } 1626 1627## 1628# @BlockdevDiscardOptions 1629# 1630# Determines how to handle discard requests. 1631# 1632# @ignore: Ignore the request 1633# @unmap: Forward as an unmap request 1634# 1635# Since: 1.7 1636## 1637{ 'enum': 'BlockdevDiscardOptions', 1638 'data': [ 'ignore', 'unmap' ] } 1639 1640## 1641# @BlockdevDetectZeroesOptions 1642# 1643# Describes the operation mode for the automatic conversion of plain 1644# zero writes by the OS to driver specific optimized zero write commands. 1645# 1646# @off: Disabled (default) 1647# @on: Enabled 1648# @unmap: Enabled and even try to unmap blocks if possible. This requires 1649# also that @BlockdevDiscardOptions is set to unmap for this device. 1650# 1651# Since: 2.1 1652## 1653{ 'enum': 'BlockdevDetectZeroesOptions', 1654 'data': [ 'off', 'on', 'unmap' ] } 1655 1656## 1657# @BlockdevAioOptions 1658# 1659# Selects the AIO backend to handle I/O requests 1660# 1661# @threads: Use qemu's thread pool 1662# @native: Use native AIO backend (only Linux and Windows) 1663# 1664# Since: 1.7 1665## 1666{ 'enum': 'BlockdevAioOptions', 1667 'data': [ 'threads', 'native' ] } 1668 1669## 1670# @BlockdevCacheOptions 1671# 1672# Includes cache-related options for block devices 1673# 1674# @direct: #optional enables use of O_DIRECT (bypass the host page cache; 1675# default: false) 1676# @no-flush: #optional ignore any flush requests for the device (default: 1677# false) 1678# 1679# Since: 1.7 1680## 1681{ 'struct': 'BlockdevCacheOptions', 1682 'data': { '*direct': 'bool', 1683 '*no-flush': 'bool' } } 1684 1685## 1686# @BlockdevDriver 1687# 1688# Drivers that are supported in block device operations. 1689# 1690# @host_device, @host_cdrom: Since 2.1 1691# 1692# Since: 2.0 1693# @gluster: Since 2.7 1694## 1695{ 'enum': 'BlockdevDriver', 1696 'data': [ 'archipelago', 'blkdebug', 'blkverify', 'bochs', 'cloop', 1697 'dmg', 'file', 'ftp', 'ftps', 'gluster', 'host_cdrom', 1698 'host_device', 'http', 'https', 'luks', 'null-aio', 'null-co', 1699 'parallels', 'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'tftp', 1700 'vdi', 'vhdx', 'vmdk', 'vpc', 'vvfat' ] } 1701 1702## 1703# @BlockdevOptionsFile 1704# 1705# Driver specific block device options for the file backend and similar 1706# protocols. 1707# 1708# @filename: path to the image file 1709# 1710# Since: 1.7 1711## 1712{ 'struct': 'BlockdevOptionsFile', 1713 'data': { 'filename': 'str' } } 1714 1715## 1716# @BlockdevOptionsNull 1717# 1718# Driver specific block device options for the null backend. 1719# 1720# @size: #optional size of the device in bytes. 1721# @latency-ns: #optional emulated latency (in nanoseconds) in processing 1722# requests. Default to zero which completes requests immediately. 1723# (Since 2.4) 1724# 1725# Since: 2.2 1726## 1727{ 'struct': 'BlockdevOptionsNull', 1728 'data': { '*size': 'int', '*latency-ns': 'uint64' } } 1729 1730## 1731# @BlockdevOptionsVVFAT 1732# 1733# Driver specific block device options for the vvfat protocol. 1734# 1735# @dir: directory to be exported as FAT image 1736# @fat-type: #optional FAT type: 12, 16 or 32 1737# @floppy: #optional whether to export a floppy image (true) or 1738# partitioned hard disk (false; default) 1739# @label: #optional set the volume label, limited to 11 bytes. FAT16 and 1740# FAT32 traditionally have some restrictions on labels, which are 1741# ignored by most operating systems. Defaults to "QEMU VVFAT". 1742# (since 2.4) 1743# @rw: #optional whether to allow write operations (default: false) 1744# 1745# Since: 1.7 1746## 1747{ 'struct': 'BlockdevOptionsVVFAT', 1748 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool', 1749 '*label': 'str', '*rw': 'bool' } } 1750 1751## 1752# @BlockdevOptionsGenericFormat 1753# 1754# Driver specific block device options for image format that have no option 1755# besides their data source. 1756# 1757# @file: reference to or definition of the data source block device 1758# 1759# Since: 1.7 1760## 1761{ 'struct': 'BlockdevOptionsGenericFormat', 1762 'data': { 'file': 'BlockdevRef' } } 1763 1764## 1765# @BlockdevOptionsLUKS 1766# 1767# Driver specific block device options for LUKS. 1768# 1769# @key-secret: #optional the ID of a QCryptoSecret object providing 1770# the decryption key (since 2.6). Mandatory except when 1771# doing a metadata-only probe of the image. 1772# 1773# Since: 2.6 1774## 1775{ 'struct': 'BlockdevOptionsLUKS', 1776 'base': 'BlockdevOptionsGenericFormat', 1777 'data': { '*key-secret': 'str' } } 1778 1779 1780## 1781# @BlockdevOptionsGenericCOWFormat 1782# 1783# Driver specific block device options for image format that have no option 1784# besides their data source and an optional backing file. 1785# 1786# @backing: #optional reference to or definition of the backing file block 1787# device (if missing, taken from the image file content). It is 1788# allowed to pass an empty string here in order to disable the 1789# default backing file. 1790# 1791# Since: 1.7 1792## 1793{ 'struct': 'BlockdevOptionsGenericCOWFormat', 1794 'base': 'BlockdevOptionsGenericFormat', 1795 'data': { '*backing': 'BlockdevRef' } } 1796 1797## 1798# @Qcow2OverlapCheckMode 1799# 1800# General overlap check modes. 1801# 1802# @none: Do not perform any checks 1803# 1804# @constant: Perform only checks which can be done in constant time and 1805# without reading anything from disk 1806# 1807# @cached: Perform only checks which can be done without reading anything 1808# from disk 1809# 1810# @all: Perform all available overlap checks 1811# 1812# Since: 2.2 1813## 1814{ 'enum': 'Qcow2OverlapCheckMode', 1815 'data': [ 'none', 'constant', 'cached', 'all' ] } 1816 1817## 1818# @Qcow2OverlapCheckFlags 1819# 1820# Structure of flags for each metadata structure. Setting a field to 'true' 1821# makes qemu guard that structure against unintended overwriting. The default 1822# value is chosen according to the template given. 1823# 1824# @template: Specifies a template mode which can be adjusted using the other 1825# flags, defaults to 'cached' 1826# 1827# Since: 2.2 1828## 1829{ 'struct': 'Qcow2OverlapCheckFlags', 1830 'data': { '*template': 'Qcow2OverlapCheckMode', 1831 '*main-header': 'bool', 1832 '*active-l1': 'bool', 1833 '*active-l2': 'bool', 1834 '*refcount-table': 'bool', 1835 '*refcount-block': 'bool', 1836 '*snapshot-table': 'bool', 1837 '*inactive-l1': 'bool', 1838 '*inactive-l2': 'bool' } } 1839 1840## 1841# @Qcow2OverlapChecks 1842# 1843# Specifies which metadata structures should be guarded against unintended 1844# overwriting. 1845# 1846# @flags: set of flags for separate specification of each metadata structure 1847# type 1848# 1849# @mode: named mode which chooses a specific set of flags 1850# 1851# Since: 2.2 1852## 1853{ 'alternate': 'Qcow2OverlapChecks', 1854 'data': { 'flags': 'Qcow2OverlapCheckFlags', 1855 'mode': 'Qcow2OverlapCheckMode' } } 1856 1857## 1858# @BlockdevOptionsQcow2 1859# 1860# Driver specific block device options for qcow2. 1861# 1862# @lazy-refcounts: #optional whether to enable the lazy refcounts 1863# feature (default is taken from the image file) 1864# 1865# @pass-discard-request: #optional whether discard requests to the qcow2 1866# device should be forwarded to the data source 1867# 1868# @pass-discard-snapshot: #optional whether discard requests for the data source 1869# should be issued when a snapshot operation (e.g. 1870# deleting a snapshot) frees clusters in the qcow2 file 1871# 1872# @pass-discard-other: #optional whether discard requests for the data source 1873# should be issued on other occasions where a cluster 1874# gets freed 1875# 1876# @overlap-check: #optional which overlap checks to perform for writes 1877# to the image, defaults to 'cached' (since 2.2) 1878# 1879# @cache-size: #optional the maximum total size of the L2 table and 1880# refcount block caches in bytes (since 2.2) 1881# 1882# @l2-cache-size: #optional the maximum size of the L2 table cache in 1883# bytes (since 2.2) 1884# 1885# @refcount-cache-size: #optional the maximum size of the refcount block cache 1886# in bytes (since 2.2) 1887# 1888# @cache-clean-interval: #optional clean unused entries in the L2 and refcount 1889# caches. The interval is in seconds. The default value 1890# is 0 and it disables this feature (since 2.5) 1891# 1892# Since: 1.7 1893## 1894{ 'struct': 'BlockdevOptionsQcow2', 1895 'base': 'BlockdevOptionsGenericCOWFormat', 1896 'data': { '*lazy-refcounts': 'bool', 1897 '*pass-discard-request': 'bool', 1898 '*pass-discard-snapshot': 'bool', 1899 '*pass-discard-other': 'bool', 1900 '*overlap-check': 'Qcow2OverlapChecks', 1901 '*cache-size': 'int', 1902 '*l2-cache-size': 'int', 1903 '*refcount-cache-size': 'int', 1904 '*cache-clean-interval': 'int' } } 1905 1906 1907## 1908# @BlockdevOptionsArchipelago 1909# 1910# Driver specific block device options for Archipelago. 1911# 1912# @volume: Name of the Archipelago volume image 1913# 1914# @mport: #optional The port number on which mapperd is 1915# listening. This is optional 1916# and if not specified, QEMU will make Archipelago 1917# use the default port (1001). 1918# 1919# @vport: #optional The port number on which vlmcd is 1920# listening. This is optional 1921# and if not specified, QEMU will make Archipelago 1922# use the default port (501). 1923# 1924# @segment: #optional The name of the shared memory segment 1925# Archipelago stack is using. This is optional 1926# and if not specified, QEMU will make Archipelago 1927# use the default value, 'archipelago'. 1928# Since: 2.2 1929## 1930{ 'struct': 'BlockdevOptionsArchipelago', 1931 'data': { 'volume': 'str', 1932 '*mport': 'int', 1933 '*vport': 'int', 1934 '*segment': 'str' } } 1935 1936 1937## 1938# @BlkdebugEvent 1939# 1940# Trigger events supported by blkdebug. 1941# 1942# Since: 2.0 1943## 1944{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG', 1945 'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table', 1946 'l1_grow_activate_table', 'l2_load', 'l2_update', 1947 'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write', 1948 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio', 1949 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read', 1950 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update', 1951 'refblock_load', 'refblock_update', 'refblock_update_part', 1952 'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write', 1953 'refblock_alloc_write_blocks', 'refblock_alloc_write_table', 1954 'refblock_alloc_switch_table', 'cluster_alloc', 1955 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os', 1956 'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head', 1957 'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev', 1958 'pwritev_zero', 'pwritev_done', 'empty_image_prepare' ] } 1959 1960## 1961# @BlkdebugInjectErrorOptions 1962# 1963# Describes a single error injection for blkdebug. 1964# 1965# @event: trigger event 1966# 1967# @state: #optional the state identifier blkdebug needs to be in to 1968# actually trigger the event; defaults to "any" 1969# 1970# @errno: #optional error identifier (errno) to be returned; defaults to 1971# EIO 1972# 1973# @sector: #optional specifies the sector index which has to be affected 1974# in order to actually trigger the event; defaults to "any 1975# sector" 1976# 1977# @once: #optional disables further events after this one has been 1978# triggered; defaults to false 1979# 1980# @immediately: #optional fail immediately; defaults to false 1981# 1982# Since: 2.0 1983## 1984{ 'struct': 'BlkdebugInjectErrorOptions', 1985 'data': { 'event': 'BlkdebugEvent', 1986 '*state': 'int', 1987 '*errno': 'int', 1988 '*sector': 'int', 1989 '*once': 'bool', 1990 '*immediately': 'bool' } } 1991 1992## 1993# @BlkdebugSetStateOptions 1994# 1995# Describes a single state-change event for blkdebug. 1996# 1997# @event: trigger event 1998# 1999# @state: #optional the current state identifier blkdebug needs to be in; 2000# defaults to "any" 2001# 2002# @new_state: the state identifier blkdebug is supposed to assume if 2003# this event is triggered 2004# 2005# Since: 2.0 2006## 2007{ 'struct': 'BlkdebugSetStateOptions', 2008 'data': { 'event': 'BlkdebugEvent', 2009 '*state': 'int', 2010 'new_state': 'int' } } 2011 2012## 2013# @BlockdevOptionsBlkdebug 2014# 2015# Driver specific block device options for blkdebug. 2016# 2017# @image: underlying raw block device (or image file) 2018# 2019# @config: #optional filename of the configuration file 2020# 2021# @align: #optional required alignment for requests in bytes, 2022# must be power of 2, or 0 for default 2023# 2024# @inject-error: #optional array of error injection descriptions 2025# 2026# @set-state: #optional array of state-change descriptions 2027# 2028# Since: 2.0 2029## 2030{ 'struct': 'BlockdevOptionsBlkdebug', 2031 'data': { 'image': 'BlockdevRef', 2032 '*config': 'str', 2033 '*align': 'int', 2034 '*inject-error': ['BlkdebugInjectErrorOptions'], 2035 '*set-state': ['BlkdebugSetStateOptions'] } } 2036 2037## 2038# @BlockdevOptionsBlkverify 2039# 2040# Driver specific block device options for blkverify. 2041# 2042# @test: block device to be tested 2043# 2044# @raw: raw image used for verification 2045# 2046# Since: 2.0 2047## 2048{ 'struct': 'BlockdevOptionsBlkverify', 2049 'data': { 'test': 'BlockdevRef', 2050 'raw': 'BlockdevRef' } } 2051 2052## 2053# @QuorumReadPattern 2054# 2055# An enumeration of quorum read patterns. 2056# 2057# @quorum: read all the children and do a quorum vote on reads 2058# 2059# @fifo: read only from the first child that has not failed 2060# 2061# Since: 2.2 2062## 2063{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] } 2064 2065## 2066# @BlockdevOptionsQuorum 2067# 2068# Driver specific block device options for Quorum 2069# 2070# @blkverify: #optional true if the driver must print content mismatch 2071# set to false by default 2072# 2073# @children: the children block devices to use 2074# 2075# @vote-threshold: the vote limit under which a read will fail 2076# 2077# @rewrite-corrupted: #optional rewrite corrupted data when quorum is reached 2078# (Since 2.1) 2079# 2080# @read-pattern: #optional choose read pattern and set to quorum by default 2081# (Since 2.2) 2082# 2083# Since: 2.0 2084## 2085{ 'struct': 'BlockdevOptionsQuorum', 2086 'data': { '*blkverify': 'bool', 2087 'children': [ 'BlockdevRef' ], 2088 'vote-threshold': 'int', 2089 '*rewrite-corrupted': 'bool', 2090 '*read-pattern': 'QuorumReadPattern' } } 2091 2092## 2093# @GlusterTransport 2094# 2095# An enumeration of Gluster transport types 2096# 2097# @tcp: TCP - Transmission Control Protocol 2098# 2099# @unix: UNIX - Unix domain socket 2100# 2101# Since: 2.7 2102## 2103{ 'enum': 'GlusterTransport', 2104 'data': [ 'unix', 'tcp' ] } 2105 2106 2107## 2108# @GlusterServer 2109# 2110# Captures the address of a socket 2111# 2112# Details for connecting to a gluster server 2113# 2114# @type: Transport type used for gluster connection 2115# 2116# @unix: socket file 2117# 2118# @tcp: host address and port number 2119# 2120# Since: 2.7 2121## 2122{ 'union': 'GlusterServer', 2123 'base': { 'type': 'GlusterTransport' }, 2124 'discriminator': 'type', 2125 'data': { 'unix': 'UnixSocketAddress', 2126 'tcp': 'InetSocketAddress' } } 2127 2128## 2129# @BlockdevOptionsGluster 2130# 2131# Driver specific block device options for Gluster 2132# 2133# @volume: name of gluster volume where VM image resides 2134# 2135# @path: absolute path to image file in gluster volume 2136# 2137# @server: gluster server description 2138# 2139# @debug-level: #optional libgfapi log level (default '4' which is Error) 2140# 2141# Since: 2.7 2142## 2143{ 'struct': 'BlockdevOptionsGluster', 2144 'data': { 'volume': 'str', 2145 'path': 'str', 2146 'server': ['GlusterServer'], 2147 '*debug_level': 'int' } } 2148 2149## 2150# @BlockdevOptions 2151# 2152# Options for creating a block device. Many options are available for all 2153# block devices, independent of the block driver: 2154# 2155# @driver: block driver name 2156# @id: #optional id by which the new block device can be referred to. 2157# This option is only allowed on the top level of blockdev-add. 2158# A BlockBackend will be created by blockdev-add if and only if 2159# this option is given. 2160# @node-name: #optional the name of a block driver state node (Since 2.0). 2161# This option is required on the top level of blockdev-add if 2162# the @id option is not given there. 2163# @discard: #optional discard-related options (default: ignore) 2164# @cache: #optional cache-related options 2165# @aio: #optional AIO backend (default: threads) 2166# @read-only: #optional whether the block device should be read-only 2167# (default: false) 2168# @detect-zeroes: #optional detect and optimize zero writes (Since 2.1) 2169# (default: off) 2170# 2171# Remaining options are determined by the block driver. 2172# 2173# Since: 1.7 2174## 2175{ 'union': 'BlockdevOptions', 2176 'base': { 'driver': 'BlockdevDriver', 2177# TODO 'id' is a BB-level option, remove it 2178 '*id': 'str', 2179 '*node-name': 'str', 2180 '*discard': 'BlockdevDiscardOptions', 2181 '*cache': 'BlockdevCacheOptions', 2182 '*aio': 'BlockdevAioOptions', 2183 '*read-only': 'bool', 2184 '*detect-zeroes': 'BlockdevDetectZeroesOptions' }, 2185 'discriminator': 'driver', 2186 'data': { 2187 'archipelago':'BlockdevOptionsArchipelago', 2188 'blkdebug': 'BlockdevOptionsBlkdebug', 2189 'blkverify': 'BlockdevOptionsBlkverify', 2190 'bochs': 'BlockdevOptionsGenericFormat', 2191 'cloop': 'BlockdevOptionsGenericFormat', 2192 'dmg': 'BlockdevOptionsGenericFormat', 2193 'file': 'BlockdevOptionsFile', 2194 'ftp': 'BlockdevOptionsFile', 2195 'ftps': 'BlockdevOptionsFile', 2196 'gluster': 'BlockdevOptionsGluster', 2197 'host_cdrom': 'BlockdevOptionsFile', 2198 'host_device':'BlockdevOptionsFile', 2199 'http': 'BlockdevOptionsFile', 2200 'https': 'BlockdevOptionsFile', 2201# TODO iscsi: Wait for structured options 2202 'luks': 'BlockdevOptionsLUKS', 2203# TODO nbd: Should take InetSocketAddress for 'host'? 2204# TODO nfs: Wait for structured options 2205 'null-aio': 'BlockdevOptionsNull', 2206 'null-co': 'BlockdevOptionsNull', 2207 'parallels': 'BlockdevOptionsGenericFormat', 2208 'qcow2': 'BlockdevOptionsQcow2', 2209 'qcow': 'BlockdevOptionsGenericCOWFormat', 2210 'qed': 'BlockdevOptionsGenericCOWFormat', 2211 'quorum': 'BlockdevOptionsQuorum', 2212 'raw': 'BlockdevOptionsGenericFormat', 2213# TODO rbd: Wait for structured options 2214# TODO sheepdog: Wait for structured options 2215# TODO ssh: Should take InetSocketAddress for 'host'? 2216 'tftp': 'BlockdevOptionsFile', 2217 'vdi': 'BlockdevOptionsGenericFormat', 2218 'vhdx': 'BlockdevOptionsGenericFormat', 2219 'vmdk': 'BlockdevOptionsGenericCOWFormat', 2220 'vpc': 'BlockdevOptionsGenericFormat', 2221 'vvfat': 'BlockdevOptionsVVFAT' 2222 } } 2223 2224## 2225# @BlockdevRef 2226# 2227# Reference to a block device. 2228# 2229# @definition: defines a new block device inline 2230# @reference: references the ID of an existing block device. An 2231# empty string means that no block device should be 2232# referenced. 2233# 2234# Since: 1.7 2235## 2236{ 'alternate': 'BlockdevRef', 2237 'data': { 'definition': 'BlockdevOptions', 2238 'reference': 'str' } } 2239 2240## 2241# @blockdev-add: 2242# 2243# Creates a new block device. If the @id option is given at the top level, a 2244# BlockBackend will be created; otherwise, @node-name is mandatory at the top 2245# level and no BlockBackend will be created. 2246# 2247# This command is still a work in progress. It doesn't support all 2248# block drivers among other things. Stay away from it unless you want 2249# to help with its development. 2250# 2251# @options: block device options for the new device 2252# 2253# Since: 1.7 2254## 2255{ 'command': 'blockdev-add', 'data': { 'options': 'BlockdevOptions' } } 2256 2257## 2258# @x-blockdev-del: 2259# 2260# Deletes a block device that has been added using blockdev-add. 2261# The selected device can be either a block backend or a graph node. 2262# 2263# In the former case the backend will be destroyed, along with its 2264# inserted medium if there's any. The command will fail if the backend 2265# or its medium are in use. 2266# 2267# In the latter case the node will be destroyed. The command will fail 2268# if the node is attached to a block backend or is otherwise being 2269# used. 2270# 2271# One of @id or @node-name must be specified, but not both. 2272# 2273# This command is still a work in progress and is considered 2274# experimental. Stay away from it unless you want to help with its 2275# development. 2276# 2277# @id: #optional Name of the block backend device to delete. 2278# 2279# @node-name: #optional Name of the graph node to delete. 2280# 2281# Since: 2.5 2282## 2283{ 'command': 'x-blockdev-del', 'data': { '*id': 'str', '*node-name': 'str' } } 2284 2285## 2286# @blockdev-open-tray: 2287# 2288# Opens a block device's tray. If there is a block driver state tree inserted as 2289# a medium, it will become inaccessible to the guest (but it will remain 2290# associated to the block device, so closing the tray will make it accessible 2291# again). 2292# 2293# If the tray was already open before, this will be a no-op. 2294# 2295# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in 2296# which no such event will be generated, these include: 2297# - if the guest has locked the tray, @force is false and the guest does not 2298# respond to the eject request 2299# - if the BlockBackend denoted by @device does not have a guest device attached 2300# to it 2301# - if the guest device does not have an actual tray 2302# 2303# @device: block device name 2304# 2305# @force: #optional if false (the default), an eject request will be sent to 2306# the guest if it has locked the tray (and the tray will not be opened 2307# immediately); if true, the tray will be opened regardless of whether 2308# it is locked 2309# 2310# Since: 2.5 2311## 2312{ 'command': 'blockdev-open-tray', 2313 'data': { 'device': 'str', 2314 '*force': 'bool' } } 2315 2316## 2317# @blockdev-close-tray: 2318# 2319# Closes a block device's tray. If there is a block driver state tree associated 2320# with the block device (which is currently ejected), that tree will be loaded 2321# as the medium. 2322# 2323# If the tray was already closed before, this will be a no-op. 2324# 2325# @device: block device name 2326# 2327# Since: 2.5 2328## 2329{ 'command': 'blockdev-close-tray', 2330 'data': { 'device': 'str' } } 2331 2332## 2333# @x-blockdev-remove-medium: 2334# 2335# Removes a medium (a block driver state tree) from a block device. That block 2336# device's tray must currently be open (unless there is no attached guest 2337# device). 2338# 2339# If the tray is open and there is no medium inserted, this will be a no-op. 2340# 2341# This command is still a work in progress and is considered experimental. 2342# Stay away from it unless you want to help with its development. 2343# 2344# @device: block device name 2345# 2346# Since: 2.5 2347## 2348{ 'command': 'x-blockdev-remove-medium', 2349 'data': { 'device': 'str' } } 2350 2351## 2352# @x-blockdev-insert-medium: 2353# 2354# Inserts a medium (a block driver state tree) into a block device. That block 2355# device's tray must currently be open (unless there is no attached guest 2356# device) and there must be no medium inserted already. 2357# 2358# This command is still a work in progress and is considered experimental. 2359# Stay away from it unless you want to help with its development. 2360# 2361# @device: block device name 2362# 2363# @node-name: name of a node in the block driver state graph 2364# 2365# Since: 2.5 2366## 2367{ 'command': 'x-blockdev-insert-medium', 2368 'data': { 'device': 'str', 2369 'node-name': 'str'} } 2370 2371 2372## 2373# @BlockdevChangeReadOnlyMode: 2374# 2375# Specifies the new read-only mode of a block device subject to the 2376# @blockdev-change-medium command. 2377# 2378# @retain: Retains the current read-only mode 2379# 2380# @read-only: Makes the device read-only 2381# 2382# @read-write: Makes the device writable 2383# 2384# Since: 2.3 2385## 2386{ 'enum': 'BlockdevChangeReadOnlyMode', 2387 'data': ['retain', 'read-only', 'read-write'] } 2388 2389 2390## 2391# @blockdev-change-medium: 2392# 2393# Changes the medium inserted into a block device by ejecting the current medium 2394# and loading a new image file which is inserted as the new medium (this command 2395# combines blockdev-open-tray, x-blockdev-remove-medium, 2396# x-blockdev-insert-medium and blockdev-close-tray). 2397# 2398# @device: block device name 2399# 2400# @filename: filename of the new image to be loaded 2401# 2402# @format: #optional, format to open the new image with (defaults to 2403# the probed format) 2404# 2405# @read-only-mode: #optional, change the read-only mode of the device; defaults 2406# to 'retain' 2407# 2408# Since: 2.5 2409## 2410{ 'command': 'blockdev-change-medium', 2411 'data': { 'device': 'str', 2412 'filename': 'str', 2413 '*format': 'str', 2414 '*read-only-mode': 'BlockdevChangeReadOnlyMode' } } 2415 2416 2417## 2418# @BlockErrorAction 2419# 2420# An enumeration of action that has been taken when a DISK I/O occurs 2421# 2422# @ignore: error has been ignored 2423# 2424# @report: error has been reported to the device 2425# 2426# @stop: error caused VM to be stopped 2427# 2428# Since: 2.1 2429## 2430{ 'enum': 'BlockErrorAction', 2431 'data': [ 'ignore', 'report', 'stop' ] } 2432 2433 2434## 2435# @BLOCK_IMAGE_CORRUPTED 2436# 2437# Emitted when a corruption has been detected in a disk image 2438# 2439# @device: device name. This is always present for compatibility 2440# reasons, but it can be empty ("") if the image does not 2441# have a device name associated. 2442# 2443# @node-name: #optional node name (Since: 2.4) 2444# 2445# @msg: informative message for human consumption, such as the kind of 2446# corruption being detected. It should not be parsed by machine as it is 2447# not guaranteed to be stable 2448# 2449# @offset: #optional, if the corruption resulted from an image access, this is 2450# the host's access offset into the image 2451# 2452# @size: #optional, if the corruption resulted from an image access, this is 2453# the access size 2454# 2455# fatal: if set, the image is marked corrupt and therefore unusable after this 2456# event and must be repaired (Since 2.2; before, every 2457# BLOCK_IMAGE_CORRUPTED event was fatal) 2458# 2459# Since: 1.7 2460## 2461{ 'event': 'BLOCK_IMAGE_CORRUPTED', 2462 'data': { 'device' : 'str', 2463 '*node-name' : 'str', 2464 'msg' : 'str', 2465 '*offset' : 'int', 2466 '*size' : 'int', 2467 'fatal' : 'bool' } } 2468 2469## 2470# @BLOCK_IO_ERROR 2471# 2472# Emitted when a disk I/O error occurs 2473# 2474# @device: device name 2475# 2476# @operation: I/O operation 2477# 2478# @action: action that has been taken 2479# 2480# @nospace: #optional true if I/O error was caused due to a no-space 2481# condition. This key is only present if query-block's 2482# io-status is present, please see query-block documentation 2483# for more information (since: 2.2) 2484# 2485# @reason: human readable string describing the error cause. 2486# (This field is a debugging aid for humans, it should not 2487# be parsed by applications) (since: 2.2) 2488# 2489# Note: If action is "stop", a STOP event will eventually follow the 2490# BLOCK_IO_ERROR event 2491# 2492# Since: 0.13.0 2493## 2494{ 'event': 'BLOCK_IO_ERROR', 2495 'data': { 'device': 'str', 'operation': 'IoOperationType', 2496 'action': 'BlockErrorAction', '*nospace': 'bool', 2497 'reason': 'str' } } 2498 2499## 2500# @BLOCK_JOB_COMPLETED 2501# 2502# Emitted when a block job has completed 2503# 2504# @type: job type 2505# 2506# @device: The job identifier. Originally the device name but other 2507# values are allowed since QEMU 2.7 2508# 2509# @len: maximum progress value 2510# 2511# @offset: current progress value. On success this is equal to len. 2512# On failure this is less than len 2513# 2514# @speed: rate limit, bytes per second 2515# 2516# @error: #optional, error message. Only present on failure. This field 2517# contains a human-readable error message. There are no semantics 2518# other than that streaming has failed and clients should not try to 2519# interpret the error string 2520# 2521# Since: 1.1 2522## 2523{ 'event': 'BLOCK_JOB_COMPLETED', 2524 'data': { 'type' : 'BlockJobType', 2525 'device': 'str', 2526 'len' : 'int', 2527 'offset': 'int', 2528 'speed' : 'int', 2529 '*error': 'str' } } 2530 2531## 2532# @BLOCK_JOB_CANCELLED 2533# 2534# Emitted when a block job has been cancelled 2535# 2536# @type: job type 2537# 2538# @device: The job identifier. Originally the device name but other 2539# values are allowed since QEMU 2.7 2540# 2541# @len: maximum progress value 2542# 2543# @offset: current progress value. On success this is equal to len. 2544# On failure this is less than len 2545# 2546# @speed: rate limit, bytes per second 2547# 2548# Since: 1.1 2549## 2550{ 'event': 'BLOCK_JOB_CANCELLED', 2551 'data': { 'type' : 'BlockJobType', 2552 'device': 'str', 2553 'len' : 'int', 2554 'offset': 'int', 2555 'speed' : 'int' } } 2556 2557## 2558# @BLOCK_JOB_ERROR 2559# 2560# Emitted when a block job encounters an error 2561# 2562# @device: The job identifier. Originally the device name but other 2563# values are allowed since QEMU 2.7 2564# 2565# @operation: I/O operation 2566# 2567# @action: action that has been taken 2568# 2569# Since: 1.3 2570## 2571{ 'event': 'BLOCK_JOB_ERROR', 2572 'data': { 'device' : 'str', 2573 'operation': 'IoOperationType', 2574 'action' : 'BlockErrorAction' } } 2575 2576## 2577# @BLOCK_JOB_READY 2578# 2579# Emitted when a block job is ready to complete 2580# 2581# @type: job type 2582# 2583# @device: The job identifier. Originally the device name but other 2584# values are allowed since QEMU 2.7 2585# 2586# @len: maximum progress value 2587# 2588# @offset: current progress value. On success this is equal to len. 2589# On failure this is less than len 2590# 2591# @speed: rate limit, bytes per second 2592# 2593# Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR 2594# event 2595# 2596# Since: 1.3 2597## 2598{ 'event': 'BLOCK_JOB_READY', 2599 'data': { 'type' : 'BlockJobType', 2600 'device': 'str', 2601 'len' : 'int', 2602 'offset': 'int', 2603 'speed' : 'int' } } 2604 2605# @PreallocMode 2606# 2607# Preallocation mode of QEMU image file 2608# 2609# @off: no preallocation 2610# @metadata: preallocate only for metadata 2611# @falloc: like @full preallocation but allocate disk space by 2612# posix_fallocate() rather than writing zeros. 2613# @full: preallocate all data by writing zeros to device to ensure disk 2614# space is really available. @full preallocation also sets up 2615# metadata correctly. 2616# 2617# Since 2.2 2618## 2619{ 'enum': 'PreallocMode', 2620 'data': [ 'off', 'metadata', 'falloc', 'full' ] } 2621 2622## 2623# @BLOCK_WRITE_THRESHOLD 2624# 2625# Emitted when writes on block device reaches or exceeds the 2626# configured write threshold. For thin-provisioned devices, this 2627# means the device should be extended to avoid pausing for 2628# disk exhaustion. 2629# The event is one shot. Once triggered, it needs to be 2630# re-registered with another block-set-threshold command. 2631# 2632# @node-name: graph node name on which the threshold was exceeded. 2633# 2634# @amount-exceeded: amount of data which exceeded the threshold, in bytes. 2635# 2636# @write-threshold: last configured threshold, in bytes. 2637# 2638# Since: 2.3 2639## 2640{ 'event': 'BLOCK_WRITE_THRESHOLD', 2641 'data': { 'node-name': 'str', 2642 'amount-exceeded': 'uint64', 2643 'write-threshold': 'uint64' } } 2644 2645## 2646# @block-set-write-threshold 2647# 2648# Change the write threshold for a block drive. An event will be delivered 2649# if a write to this block drive crosses the configured threshold. 2650# This is useful to transparently resize thin-provisioned drives without 2651# the guest OS noticing. 2652# 2653# @node-name: graph node name on which the threshold must be set. 2654# 2655# @write-threshold: configured threshold for the block device, bytes. 2656# Use 0 to disable the threshold. 2657# 2658# Since: 2.3 2659## 2660{ 'command': 'block-set-write-threshold', 2661 'data': { 'node-name': 'str', 'write-threshold': 'uint64' } } 2662 2663## 2664# @x-blockdev-change 2665# 2666# Dynamically reconfigure the block driver state graph. It can be used 2667# to add, remove, insert or replace a graph node. Currently only the 2668# Quorum driver implements this feature to add or remove its child. This 2669# is useful to fix a broken quorum child. 2670# 2671# If @node is specified, it will be inserted under @parent. @child 2672# may not be specified in this case. If both @parent and @child are 2673# specified but @node is not, @child will be detached from @parent. 2674# 2675# @parent: the id or name of the parent node. 2676# 2677# @child: #optional the name of a child under the given parent node. 2678# 2679# @node: #optional the name of the node that will be added. 2680# 2681# Note: this command is experimental, and its API is not stable. It 2682# does not support all kinds of operations, all kinds of children, nor 2683# all block drivers. 2684# 2685# Warning: The data in a new quorum child MUST be consistent with that of 2686# the rest of the array. 2687# 2688# Since: 2.7 2689## 2690{ 'command': 'x-blockdev-change', 2691 'data' : { 'parent': 'str', 2692 '*child': 'str', 2693 '*node': 'str' } } 2694