1# -*- Mode: Python -*- 2 3## 4# == QAPI block core definitions (vm unrelated) 5## 6 7# QAPI common definitions 8{ 'include': 'common.json' } 9 10## 11# @SnapshotInfo: 12# 13# @id: unique snapshot id 14# 15# @name: user chosen name 16# 17# @vm-state-size: size of the VM state 18# 19# @date-sec: UTC date of the snapshot in seconds 20# 21# @date-nsec: fractional part in nano seconds to be used with date-sec 22# 23# @vm-clock-sec: VM clock relative to boot in seconds 24# 25# @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec 26# 27# Since: 1.3 28# 29## 30{ 'struct': 'SnapshotInfo', 31 'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int', 32 'date-sec': 'int', 'date-nsec': 'int', 33 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int' } } 34 35## 36# @ImageInfoSpecificQCow2: 37# 38# @compat: compatibility level 39# 40# @lazy-refcounts: #optional on or off; only valid for compat >= 1.1 41# 42# @corrupt: #optional true if the image has been marked corrupt; only valid for 43# compat >= 1.1 (since 2.2) 44# 45# @refcount-bits: width of a refcount entry in bits (since 2.3) 46# 47# Since: 1.7 48## 49{ 'struct': 'ImageInfoSpecificQCow2', 50 'data': { 51 'compat': 'str', 52 '*lazy-refcounts': 'bool', 53 '*corrupt': 'bool', 54 'refcount-bits': 'int' 55 } } 56 57## 58# @ImageInfoSpecificVmdk: 59# 60# @create-type: The create type of VMDK image 61# 62# @cid: Content id of image 63# 64# @parent-cid: Parent VMDK image's cid 65# 66# @extents: List of extent files 67# 68# Since: 1.7 69## 70{ 'struct': 'ImageInfoSpecificVmdk', 71 'data': { 72 'create-type': 'str', 73 'cid': 'int', 74 'parent-cid': 'int', 75 'extents': ['ImageInfo'] 76 } } 77 78## 79# @ImageInfoSpecific: 80# 81# A discriminated record of image format specific information structures. 82# 83# Since: 1.7 84## 85{ 'union': 'ImageInfoSpecific', 86 'data': { 87 'qcow2': 'ImageInfoSpecificQCow2', 88 'vmdk': 'ImageInfoSpecificVmdk', 89 # If we need to add block driver specific parameters for 90 # LUKS in future, then we'll subclass QCryptoBlockInfoLUKS 91 # to define a ImageInfoSpecificLUKS 92 'luks': 'QCryptoBlockInfoLUKS' 93 } } 94 95## 96# @ImageInfo: 97# 98# Information about a QEMU image file 99# 100# @filename: name of the image file 101# 102# @format: format of the image file 103# 104# @virtual-size: maximum capacity in bytes of the image 105# 106# @actual-size: #optional actual size on disk in bytes of the image 107# 108# @dirty-flag: #optional true if image is not cleanly closed 109# 110# @cluster-size: #optional size of a cluster in bytes 111# 112# @encrypted: #optional true if the image is encrypted 113# 114# @compressed: #optional true if the image is compressed (Since 1.7) 115# 116# @backing-filename: #optional name of the backing file 117# 118# @full-backing-filename: #optional full path of the backing file 119# 120# @backing-filename-format: #optional the format of the backing file 121# 122# @snapshots: #optional list of VM snapshots 123# 124# @backing-image: #optional info of the backing image (since 1.6) 125# 126# @format-specific: #optional structure supplying additional format-specific 127# information (since 1.7) 128# 129# Since: 1.3 130# 131## 132{ 'struct': 'ImageInfo', 133 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool', 134 '*actual-size': 'int', 'virtual-size': 'int', 135 '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool', 136 '*backing-filename': 'str', '*full-backing-filename': 'str', 137 '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'], 138 '*backing-image': 'ImageInfo', 139 '*format-specific': 'ImageInfoSpecific' } } 140 141## 142# @ImageCheck: 143# 144# Information about a QEMU image file check 145# 146# @filename: name of the image file checked 147# 148# @format: format of the image file checked 149# 150# @check-errors: number of unexpected errors occurred during check 151# 152# @image-end-offset: #optional offset (in bytes) where the image ends, this 153# field is present if the driver for the image format 154# supports it 155# 156# @corruptions: #optional number of corruptions found during the check if any 157# 158# @leaks: #optional number of leaks found during the check if any 159# 160# @corruptions-fixed: #optional number of corruptions fixed during the check 161# if any 162# 163# @leaks-fixed: #optional number of leaks fixed during the check if any 164# 165# @total-clusters: #optional total number of clusters, this field is present 166# if the driver for the image format supports it 167# 168# @allocated-clusters: #optional total number of allocated clusters, this 169# field is present if the driver for the image format 170# supports it 171# 172# @fragmented-clusters: #optional total number of fragmented clusters, this 173# field is present if the driver for the image format 174# supports it 175# 176# @compressed-clusters: #optional total number of compressed clusters, this 177# field is present if the driver for the image format 178# supports it 179# 180# Since: 1.4 181# 182## 183{ 'struct': 'ImageCheck', 184 'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int', 185 '*image-end-offset': 'int', '*corruptions': 'int', '*leaks': 'int', 186 '*corruptions-fixed': 'int', '*leaks-fixed': 'int', 187 '*total-clusters': 'int', '*allocated-clusters': 'int', 188 '*fragmented-clusters': 'int', '*compressed-clusters': 'int' } } 189 190## 191# @MapEntry: 192# 193# Mapping information from a virtual block range to a host file range 194# 195# @start: the start byte of the mapped virtual range 196# 197# @length: the number of bytes of the mapped virtual range 198# 199# @data: whether the mapped range has data 200# 201# @zero: whether the virtual blocks are zeroed 202# 203# @depth: the depth of the mapping 204# 205# @offset: #optional the offset in file that the virtual sectors are mapped to 206# 207# @filename: #optional filename that is referred to by @offset 208# 209# Since: 2.6 210# 211## 212{ 'struct': 'MapEntry', 213 'data': {'start': 'int', 'length': 'int', 'data': 'bool', 214 'zero': 'bool', 'depth': 'int', '*offset': 'int', 215 '*filename': 'str' } } 216 217## 218# @BlockdevCacheInfo: 219# 220# Cache mode information for a block device 221# 222# @writeback: true if writeback mode is enabled 223# @direct: true if the host page cache is bypassed (O_DIRECT) 224# @no-flush: true if flush requests are ignored for the device 225# 226# Since: 2.3 227## 228{ 'struct': 'BlockdevCacheInfo', 229 'data': { 'writeback': 'bool', 230 'direct': 'bool', 231 'no-flush': 'bool' } } 232 233## 234# @BlockDeviceInfo: 235# 236# Information about the backing device for a block device. 237# 238# @file: the filename of the backing device 239# 240# @node-name: #optional the name of the block driver node (Since 2.0) 241# 242# @ro: true if the backing device was open read-only 243# 244# @drv: the name of the block format used to open the backing device. As of 245# 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg', 246# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 247# 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 248# 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 249# 2.2: 'archipelago' added, 'cow' dropped 250# 2.3: 'host_floppy' deprecated 251# 2.5: 'host_floppy' dropped 252# 2.6: 'luks' added 253# 2.8: 'replication' added, 'tftp' dropped 254# 255# @backing_file: #optional the name of the backing file (for copy-on-write) 256# 257# @backing_file_depth: number of files in the backing file chain (since: 1.2) 258# 259# @encrypted: true if the backing device is encrypted 260# 261# @encryption_key_missing: true if the backing device is encrypted but an 262# valid encryption key is missing 263# 264# @detect_zeroes: detect and optimize zero writes (Since 2.1) 265# 266# @bps: total throughput limit in bytes per second is specified 267# 268# @bps_rd: read throughput limit in bytes per second is specified 269# 270# @bps_wr: write throughput limit in bytes per second is specified 271# 272# @iops: total I/O operations per second is specified 273# 274# @iops_rd: read I/O operations per second is specified 275# 276# @iops_wr: write I/O operations per second is specified 277# 278# @image: the info of image used (since: 1.6) 279# 280# @bps_max: #optional total throughput limit during bursts, 281# in bytes (Since 1.7) 282# 283# @bps_rd_max: #optional read throughput limit during bursts, 284# in bytes (Since 1.7) 285# 286# @bps_wr_max: #optional write throughput limit during bursts, 287# in bytes (Since 1.7) 288# 289# @iops_max: #optional total I/O operations per second during bursts, 290# in bytes (Since 1.7) 291# 292# @iops_rd_max: #optional read I/O operations per second during bursts, 293# in bytes (Since 1.7) 294# 295# @iops_wr_max: #optional write I/O operations per second during bursts, 296# in bytes (Since 1.7) 297# 298# @bps_max_length: #optional maximum length of the @bps_max burst 299# period, in seconds. (Since 2.6) 300# 301# @bps_rd_max_length: #optional maximum length of the @bps_rd_max 302# burst period, in seconds. (Since 2.6) 303# 304# @bps_wr_max_length: #optional maximum length of the @bps_wr_max 305# burst period, in seconds. (Since 2.6) 306# 307# @iops_max_length: #optional maximum length of the @iops burst 308# period, in seconds. (Since 2.6) 309# 310# @iops_rd_max_length: #optional maximum length of the @iops_rd_max 311# burst period, in seconds. (Since 2.6) 312# 313# @iops_wr_max_length: #optional maximum length of the @iops_wr_max 314# burst period, in seconds. (Since 2.6) 315# 316# @iops_size: #optional an I/O size in bytes (Since 1.7) 317# 318# @group: #optional throttle group name (Since 2.4) 319# 320# @cache: the cache mode used for the block device (since: 2.3) 321# 322# @write_threshold: configured write threshold for the device. 323# 0 if disabled. (Since 2.3) 324# 325# Since: 0.14.0 326# 327## 328{ 'struct': 'BlockDeviceInfo', 329 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str', 330 '*backing_file': 'str', 'backing_file_depth': 'int', 331 'encrypted': 'bool', 'encryption_key_missing': 'bool', 332 'detect_zeroes': 'BlockdevDetectZeroesOptions', 333 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int', 334 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int', 335 'image': 'ImageInfo', 336 '*bps_max': 'int', '*bps_rd_max': 'int', 337 '*bps_wr_max': 'int', '*iops_max': 'int', 338 '*iops_rd_max': 'int', '*iops_wr_max': 'int', 339 '*bps_max_length': 'int', '*bps_rd_max_length': 'int', 340 '*bps_wr_max_length': 'int', '*iops_max_length': 'int', 341 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int', 342 '*iops_size': 'int', '*group': 'str', 'cache': 'BlockdevCacheInfo', 343 'write_threshold': 'int' } } 344 345## 346# @BlockDeviceIoStatus: 347# 348# An enumeration of block device I/O status. 349# 350# @ok: The last I/O operation has succeeded 351# 352# @failed: The last I/O operation has failed 353# 354# @nospace: The last I/O operation has failed due to a no-space condition 355# 356# Since: 1.0 357## 358{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] } 359 360## 361# @BlockDeviceMapEntry: 362# 363# Entry in the metadata map of the device (returned by "qemu-img map") 364# 365# @start: Offset in the image of the first byte described by this entry 366# (in bytes) 367# 368# @length: Length of the range described by this entry (in bytes) 369# 370# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.) 371# before reaching one for which the range is allocated. The value is 372# in the range 0 to the depth of the image chain - 1. 373# 374# @zero: the sectors in this range read as zeros 375# 376# @data: reading the image will actually read data from a file (in particular, 377# if @offset is present this means that the sectors are not simply 378# preallocated, but contain actual data in raw format) 379# 380# @offset: if present, the image file stores the data for this range in 381# raw format at the given offset. 382# 383# Since: 1.7 384## 385{ 'struct': 'BlockDeviceMapEntry', 386 'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool', 387 'data': 'bool', '*offset': 'int' } } 388 389## 390# @DirtyBitmapStatus: 391# 392# An enumeration of possible states that a dirty bitmap can report to the user. 393# 394# @frozen: The bitmap is currently in-use by a backup operation or block job, 395# and is immutable. 396# 397# @disabled: The bitmap is currently in-use by an internal operation and is 398# read-only. It can still be deleted. 399# 400# @active: The bitmap is actively monitoring for new writes, and can be cleared, 401# deleted, or used for backup operations. 402# 403# Since: 2.4 404## 405{ 'enum': 'DirtyBitmapStatus', 406 'data': ['active', 'disabled', 'frozen'] } 407 408## 409# @BlockDirtyInfo: 410# 411# Block dirty bitmap information. 412# 413# @name: #optional the name of the dirty bitmap (Since 2.4) 414# 415# @count: number of dirty bytes according to the dirty bitmap 416# 417# @granularity: granularity of the dirty bitmap in bytes (since 1.4) 418# 419# @status: current status of the dirty bitmap (since 2.4) 420# 421# Since: 1.3 422## 423{ 'struct': 'BlockDirtyInfo', 424 'data': {'*name': 'str', 'count': 'int', 'granularity': 'uint32', 425 'status': 'DirtyBitmapStatus'} } 426 427## 428# @BlockInfo: 429# 430# Block device information. This structure describes a virtual device and 431# the backing device associated with it. 432# 433# @device: The device name associated with the virtual device. 434# 435# @type: This field is returned only for compatibility reasons, it should 436# not be used (always returns 'unknown') 437# 438# @removable: True if the device supports removable media. 439# 440# @locked: True if the guest has locked this device from having its media 441# removed 442# 443# @tray_open: #optional True if the device's tray is open 444# (only present if it has a tray) 445# 446# @dirty-bitmaps: #optional dirty bitmaps information (only present if the 447# driver has one or more dirty bitmaps) (Since 2.0) 448# 449# @io-status: #optional @BlockDeviceIoStatus. Only present if the device 450# supports it and the VM is configured to stop on errors 451# (supported device models: virtio-blk, ide, scsi-disk) 452# 453# @inserted: #optional @BlockDeviceInfo describing the device if media is 454# present 455# 456# Since: 0.14.0 457## 458{ 'struct': 'BlockInfo', 459 'data': {'device': 'str', 'type': 'str', 'removable': 'bool', 460 'locked': 'bool', '*inserted': 'BlockDeviceInfo', 461 '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus', 462 '*dirty-bitmaps': ['BlockDirtyInfo'] } } 463 464## 465# @query-block: 466# 467# Get a list of BlockInfo for all virtual block devices. 468# 469# Returns: a list of @BlockInfo describing each virtual block device 470# 471# Since: 0.14.0 472# 473# Example: 474# 475# -> { "execute": "query-block" } 476# <- { 477# "return":[ 478# { 479# "io-status": "ok", 480# "device":"ide0-hd0", 481# "locked":false, 482# "removable":false, 483# "inserted":{ 484# "ro":false, 485# "drv":"qcow2", 486# "encrypted":false, 487# "file":"disks/test.qcow2", 488# "backing_file_depth":1, 489# "bps":1000000, 490# "bps_rd":0, 491# "bps_wr":0, 492# "iops":1000000, 493# "iops_rd":0, 494# "iops_wr":0, 495# "bps_max": 8000000, 496# "bps_rd_max": 0, 497# "bps_wr_max": 0, 498# "iops_max": 0, 499# "iops_rd_max": 0, 500# "iops_wr_max": 0, 501# "iops_size": 0, 502# "detect_zeroes": "on", 503# "write_threshold": 0, 504# "image":{ 505# "filename":"disks/test.qcow2", 506# "format":"qcow2", 507# "virtual-size":2048000, 508# "backing_file":"base.qcow2", 509# "full-backing-filename":"disks/base.qcow2", 510# "backing-filename-format":"qcow2", 511# "snapshots":[ 512# { 513# "id": "1", 514# "name": "snapshot1", 515# "vm-state-size": 0, 516# "date-sec": 10000200, 517# "date-nsec": 12, 518# "vm-clock-sec": 206, 519# "vm-clock-nsec": 30 520# } 521# ], 522# "backing-image":{ 523# "filename":"disks/base.qcow2", 524# "format":"qcow2", 525# "virtual-size":2048000 526# } 527# } 528# }, 529# "type":"unknown" 530# }, 531# { 532# "io-status": "ok", 533# "device":"ide1-cd0", 534# "locked":false, 535# "removable":true, 536# "type":"unknown" 537# }, 538# { 539# "device":"floppy0", 540# "locked":false, 541# "removable":true, 542# "type":"unknown" 543# }, 544# { 545# "device":"sd0", 546# "locked":false, 547# "removable":true, 548# "type":"unknown" 549# } 550# ] 551# } 552# 553## 554{ 'command': 'query-block', 'returns': ['BlockInfo'] } 555 556 557## 558# @BlockDeviceTimedStats: 559# 560# Statistics of a block device during a given interval of time. 561# 562# @interval_length: Interval used for calculating the statistics, 563# in seconds. 564# 565# @min_rd_latency_ns: Minimum latency of read operations in the 566# defined interval, in nanoseconds. 567# 568# @min_wr_latency_ns: Minimum latency of write operations in the 569# defined interval, in nanoseconds. 570# 571# @min_flush_latency_ns: Minimum latency of flush operations in the 572# defined interval, in nanoseconds. 573# 574# @max_rd_latency_ns: Maximum latency of read operations in the 575# defined interval, in nanoseconds. 576# 577# @max_wr_latency_ns: Maximum latency of write operations in the 578# defined interval, in nanoseconds. 579# 580# @max_flush_latency_ns: Maximum latency of flush operations in the 581# defined interval, in nanoseconds. 582# 583# @avg_rd_latency_ns: Average latency of read operations in the 584# defined interval, in nanoseconds. 585# 586# @avg_wr_latency_ns: Average latency of write operations in the 587# defined interval, in nanoseconds. 588# 589# @avg_flush_latency_ns: Average latency of flush operations in the 590# defined interval, in nanoseconds. 591# 592# @avg_rd_queue_depth: Average number of pending read operations 593# in the defined interval. 594# 595# @avg_wr_queue_depth: Average number of pending write operations 596# in the defined interval. 597# 598# Since: 2.5 599## 600{ 'struct': 'BlockDeviceTimedStats', 601 'data': { 'interval_length': 'int', 'min_rd_latency_ns': 'int', 602 'max_rd_latency_ns': 'int', 'avg_rd_latency_ns': 'int', 603 'min_wr_latency_ns': 'int', 'max_wr_latency_ns': 'int', 604 'avg_wr_latency_ns': 'int', 'min_flush_latency_ns': 'int', 605 'max_flush_latency_ns': 'int', 'avg_flush_latency_ns': 'int', 606 'avg_rd_queue_depth': 'number', 'avg_wr_queue_depth': 'number' } } 607 608## 609# @BlockDeviceStats: 610# 611# Statistics of a virtual block device or a block backing device. 612# 613# @rd_bytes: The number of bytes read by the device. 614# 615# @wr_bytes: The number of bytes written by the device. 616# 617# @rd_operations: The number of read operations performed by the device. 618# 619# @wr_operations: The number of write operations performed by the device. 620# 621# @flush_operations: The number of cache flush operations performed by the 622# device (since 0.15.0) 623# 624# @flush_total_time_ns: Total time spend on cache flushes in nano-seconds 625# (since 0.15.0). 626# 627# @wr_total_time_ns: Total time spend on writes in nano-seconds (since 0.15.0). 628# 629# @rd_total_time_ns: Total_time_spend on reads in nano-seconds (since 0.15.0). 630# 631# @wr_highest_offset: The offset after the greatest byte written to the 632# device. The intended use of this information is for 633# growable sparse files (like qcow2) that are used on top 634# of a physical device. 635# 636# @rd_merged: Number of read requests that have been merged into another 637# request (Since 2.3). 638# 639# @wr_merged: Number of write requests that have been merged into another 640# request (Since 2.3). 641# 642# @idle_time_ns: #optional Time since the last I/O operation, in 643# nanoseconds. If the field is absent it means that 644# there haven't been any operations yet (Since 2.5). 645# 646# @failed_rd_operations: The number of failed read operations 647# performed by the device (Since 2.5) 648# 649# @failed_wr_operations: The number of failed write operations 650# performed by the device (Since 2.5) 651# 652# @failed_flush_operations: The number of failed flush operations 653# performed by the device (Since 2.5) 654# 655# @invalid_rd_operations: The number of invalid read operations 656# performed by the device (Since 2.5) 657# 658# @invalid_wr_operations: The number of invalid write operations 659# performed by the device (Since 2.5) 660# 661# @invalid_flush_operations: The number of invalid flush operations 662# performed by the device (Since 2.5) 663# 664# @account_invalid: Whether invalid operations are included in the 665# last access statistics (Since 2.5) 666# 667# @account_failed: Whether failed operations are included in the 668# latency and last access statistics (Since 2.5) 669# 670# @timed_stats: Statistics specific to the set of previously defined 671# intervals of time (Since 2.5) 672# 673# Since: 0.14.0 674## 675{ 'struct': 'BlockDeviceStats', 676 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'rd_operations': 'int', 677 'wr_operations': 'int', 'flush_operations': 'int', 678 'flush_total_time_ns': 'int', 'wr_total_time_ns': 'int', 679 'rd_total_time_ns': 'int', 'wr_highest_offset': 'int', 680 'rd_merged': 'int', 'wr_merged': 'int', '*idle_time_ns': 'int', 681 'failed_rd_operations': 'int', 'failed_wr_operations': 'int', 682 'failed_flush_operations': 'int', 'invalid_rd_operations': 'int', 683 'invalid_wr_operations': 'int', 'invalid_flush_operations': 'int', 684 'account_invalid': 'bool', 'account_failed': 'bool', 685 'timed_stats': ['BlockDeviceTimedStats'] } } 686 687## 688# @BlockStats: 689# 690# Statistics of a virtual block device or a block backing device. 691# 692# @device: #optional If the stats are for a virtual block device, the name 693# corresponding to the virtual block device. 694# 695# @node-name: #optional The node name of the device. (Since 2.3) 696# 697# @stats: A @BlockDeviceStats for the device. 698# 699# @parent: #optional This describes the file block device if it has one. 700# Contains recursively the statistics of the underlying 701# protocol (e.g. the host file for a qcow2 image). If there is 702# no underlying protocol, this field is omitted 703# 704# @backing: #optional This describes the backing block device if it has one. 705# (Since 2.0) 706# 707# Since: 0.14.0 708## 709{ 'struct': 'BlockStats', 710 'data': {'*device': 'str', '*node-name': 'str', 711 'stats': 'BlockDeviceStats', 712 '*parent': 'BlockStats', 713 '*backing': 'BlockStats'} } 714 715## 716# @query-blockstats: 717# 718# Query the @BlockStats for all virtual block devices. 719# 720# @query-nodes: #optional If true, the command will query all the block nodes 721# that have a node name, in a list which will include "parent" 722# information, but not "backing". 723# If false or omitted, the behavior is as before - query all the 724# device backends, recursively including their "parent" and 725# "backing". (Since 2.3) 726# 727# Returns: A list of @BlockStats for each virtual block devices. 728# 729# Since: 0.14.0 730# 731# Example: 732# 733# -> { "execute": "query-blockstats" } 734# <- { 735# "return":[ 736# { 737# "device":"ide0-hd0", 738# "parent":{ 739# "stats":{ 740# "wr_highest_offset":3686448128, 741# "wr_bytes":9786368, 742# "wr_operations":751, 743# "rd_bytes":122567168, 744# "rd_operations":36772 745# "wr_total_times_ns":313253456 746# "rd_total_times_ns":3465673657 747# "flush_total_times_ns":49653 748# "flush_operations":61, 749# "rd_merged":0, 750# "wr_merged":0, 751# "idle_time_ns":2953431879, 752# "account_invalid":true, 753# "account_failed":false 754# } 755# }, 756# "stats":{ 757# "wr_highest_offset":2821110784, 758# "wr_bytes":9786368, 759# "wr_operations":692, 760# "rd_bytes":122739200, 761# "rd_operations":36604 762# "flush_operations":51, 763# "wr_total_times_ns":313253456 764# "rd_total_times_ns":3465673657 765# "flush_total_times_ns":49653, 766# "rd_merged":0, 767# "wr_merged":0, 768# "idle_time_ns":2953431879, 769# "account_invalid":true, 770# "account_failed":false 771# } 772# }, 773# { 774# "device":"ide1-cd0", 775# "stats":{ 776# "wr_highest_offset":0, 777# "wr_bytes":0, 778# "wr_operations":0, 779# "rd_bytes":0, 780# "rd_operations":0 781# "flush_operations":0, 782# "wr_total_times_ns":0 783# "rd_total_times_ns":0 784# "flush_total_times_ns":0, 785# "rd_merged":0, 786# "wr_merged":0, 787# "account_invalid":false, 788# "account_failed":false 789# } 790# }, 791# { 792# "device":"floppy0", 793# "stats":{ 794# "wr_highest_offset":0, 795# "wr_bytes":0, 796# "wr_operations":0, 797# "rd_bytes":0, 798# "rd_operations":0 799# "flush_operations":0, 800# "wr_total_times_ns":0 801# "rd_total_times_ns":0 802# "flush_total_times_ns":0, 803# "rd_merged":0, 804# "wr_merged":0, 805# "account_invalid":false, 806# "account_failed":false 807# } 808# }, 809# { 810# "device":"sd0", 811# "stats":{ 812# "wr_highest_offset":0, 813# "wr_bytes":0, 814# "wr_operations":0, 815# "rd_bytes":0, 816# "rd_operations":0 817# "flush_operations":0, 818# "wr_total_times_ns":0 819# "rd_total_times_ns":0 820# "flush_total_times_ns":0, 821# "rd_merged":0, 822# "wr_merged":0, 823# "account_invalid":false, 824# "account_failed":false 825# } 826# } 827# ] 828# } 829# 830## 831{ 'command': 'query-blockstats', 832 'data': { '*query-nodes': 'bool' }, 833 'returns': ['BlockStats'] } 834 835## 836# @BlockdevOnError: 837# 838# An enumeration of possible behaviors for errors on I/O operations. 839# The exact meaning depends on whether the I/O was initiated by a guest 840# or by a block job 841# 842# @report: for guest operations, report the error to the guest; 843# for jobs, cancel the job 844# 845# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR 846# or BLOCK_JOB_ERROR) 847# 848# @enospc: same as @stop on ENOSPC, same as @report otherwise. 849# 850# @stop: for guest operations, stop the virtual machine; 851# for jobs, pause the job 852# 853# @auto: inherit the error handling policy of the backend (since: 2.7) 854# 855# Since: 1.3 856## 857{ 'enum': 'BlockdevOnError', 858 'data': ['report', 'ignore', 'enospc', 'stop', 'auto'] } 859 860## 861# @MirrorSyncMode: 862# 863# An enumeration of possible behaviors for the initial synchronization 864# phase of storage mirroring. 865# 866# @top: copies data in the topmost image to the destination 867# 868# @full: copies data from all images to the destination 869# 870# @none: only copy data written from now on 871# 872# @incremental: only copy data described by the dirty bitmap. Since: 2.4 873# 874# Since: 1.3 875## 876{ 'enum': 'MirrorSyncMode', 877 'data': ['top', 'full', 'none', 'incremental'] } 878 879## 880# @BlockJobType: 881# 882# Type of a block job. 883# 884# @commit: block commit job type, see "block-commit" 885# 886# @stream: block stream job type, see "block-stream" 887# 888# @mirror: drive mirror job type, see "drive-mirror" 889# 890# @backup: drive backup job type, see "drive-backup" 891# 892# Since: 1.7 893## 894{ 'enum': 'BlockJobType', 895 'data': ['commit', 'stream', 'mirror', 'backup'] } 896 897## 898# @BlockJobInfo: 899# 900# Information about a long-running block device operation. 901# 902# @type: the job type ('stream' for image streaming) 903# 904# @device: The job identifier. Originally the device name but other 905# values are allowed since QEMU 2.7 906# 907# @len: the maximum progress value 908# 909# @busy: false if the job is known to be in a quiescent state, with 910# no pending I/O. Since 1.3. 911# 912# @paused: whether the job is paused or, if @busy is true, will 913# pause itself as soon as possible. Since 1.3. 914# 915# @offset: the current progress value 916# 917# @speed: the rate limit, bytes per second 918# 919# @io-status: the status of the job (since 1.3) 920# 921# @ready: true if the job may be completed (since 2.2) 922# 923# Since: 1.1 924## 925{ 'struct': 'BlockJobInfo', 926 'data': {'type': 'str', 'device': 'str', 'len': 'int', 927 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int', 928 'io-status': 'BlockDeviceIoStatus', 'ready': 'bool'} } 929 930## 931# @query-block-jobs: 932# 933# Return information about long-running block device operations. 934# 935# Returns: a list of @BlockJobInfo for each active block job 936# 937# Since: 1.1 938## 939{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] } 940 941## 942# @block_passwd: 943# 944# This command sets the password of a block device that has not been open 945# with a password and requires one. 946# 947# The two cases where this can happen are a block device is created through 948# QEMU's initial command line or a block device is changed through the legacy 949# @change interface. 950# 951# In the event that the block device is created through the initial command 952# line, the VM will start in the stopped state regardless of whether '-S' is 953# used. The intention is for a management tool to query the block devices to 954# determine which ones are encrypted, set the passwords with this command, and 955# then start the guest with the @cont command. 956# 957# Either @device or @node-name must be set but not both. 958# 959# @device: #optional the name of the block backend device to set the password on 960# 961# @node-name: #optional graph node name to set the password on (Since 2.0) 962# 963# @password: the password to use for the device 964# 965# Returns: nothing on success 966# If @device is not a valid block device, DeviceNotFound 967# If @device is not encrypted, DeviceNotEncrypted 968# 969# Notes: Not all block formats support encryption and some that do are not 970# able to validate that a password is correct. Disk corruption may 971# occur if an invalid password is specified. 972# 973# Since: 0.14.0 974# 975# Example: 976# 977# -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0", 978# "password": "12345" } } 979# <- { "return": {} } 980# 981## 982{ 'command': 'block_passwd', 'data': {'*device': 'str', 983 '*node-name': 'str', 'password': 'str'} } 984 985## 986# @block_resize: 987# 988# Resize a block image while a guest is running. 989# 990# Either @device or @node-name must be set but not both. 991# 992# @device: #optional the name of the device to get the image resized 993# 994# @node-name: #optional graph node name to get the image resized (Since 2.0) 995# 996# @size: new image size in bytes 997# 998# Returns: nothing on success 999# If @device is not a valid block device, DeviceNotFound 1000# 1001# Since: 0.14.0 1002# 1003# Example: 1004# 1005# -> { "execute": "block_resize", 1006# "arguments": { "device": "scratch", "size": 1073741824 } } 1007# <- { "return": {} } 1008# 1009## 1010{ 'command': 'block_resize', 'data': { '*device': 'str', 1011 '*node-name': 'str', 1012 'size': 'int' }} 1013 1014## 1015# @NewImageMode: 1016# 1017# An enumeration that tells QEMU how to set the backing file path in 1018# a new image file. 1019# 1020# @existing: QEMU should look for an existing image file. 1021# 1022# @absolute-paths: QEMU should create a new image with absolute paths 1023# for the backing file. If there is no backing file available, the new 1024# image will not be backed either. 1025# 1026# Since: 1.1 1027## 1028{ 'enum': 'NewImageMode', 1029 'data': [ 'existing', 'absolute-paths' ] } 1030 1031## 1032# @BlockdevSnapshotSync: 1033# 1034# Either @device or @node-name must be set but not both. 1035# 1036# @device: #optional the name of the device to generate the snapshot from. 1037# 1038# @node-name: #optional graph node name to generate the snapshot from (Since 2.0) 1039# 1040# @snapshot-file: the target of the new image. If the file exists, or 1041# if it is a device, the snapshot will be created in the existing 1042# file/device. Otherwise, a new file will be created. 1043# 1044# @snapshot-node-name: #optional the graph node name of the new image (Since 2.0) 1045# 1046# @format: #optional the format of the snapshot image, default is 'qcow2'. 1047# 1048# @mode: #optional whether and how QEMU should create a new image, default is 1049# 'absolute-paths'. 1050## 1051{ 'struct': 'BlockdevSnapshotSync', 1052 'data': { '*device': 'str', '*node-name': 'str', 1053 'snapshot-file': 'str', '*snapshot-node-name': 'str', 1054 '*format': 'str', '*mode': 'NewImageMode' } } 1055 1056## 1057# @BlockdevSnapshot: 1058# 1059# @node: device or node name that will have a snapshot created. 1060# 1061# @overlay: reference to the existing block device that will become 1062# the overlay of @node, as part of creating the snapshot. 1063# It must not have a current backing file (this can be 1064# achieved by passing "backing": "" to blockdev-add). 1065# 1066# Since: 2.5 1067## 1068{ 'struct': 'BlockdevSnapshot', 1069 'data': { 'node': 'str', 'overlay': 'str' } } 1070 1071## 1072# @DriveBackup: 1073# 1074# @job-id: #optional identifier for the newly-created block job. If 1075# omitted, the device name will be used. (Since 2.7) 1076# 1077# @device: the device name or node-name of a root node which should be copied. 1078# 1079# @target: the target of the new image. If the file exists, or if it 1080# is a device, the existing file/device will be used as the new 1081# destination. If it does not exist, a new file will be created. 1082# 1083# @format: #optional the format of the new destination, default is to 1084# probe if @mode is 'existing', else the format of the source 1085# 1086# @sync: what parts of the disk image should be copied to the destination 1087# (all the disk, only the sectors allocated in the topmost image, from a 1088# dirty bitmap, or only new I/O). 1089# 1090# @mode: #optional whether and how QEMU should create a new image, default is 1091# 'absolute-paths'. 1092# 1093# @speed: #optional the maximum speed, in bytes per second 1094# 1095# @bitmap: #optional the name of dirty bitmap if sync is "incremental". 1096# Must be present if sync is "incremental", must NOT be present 1097# otherwise. (Since 2.4) 1098# 1099# @compress: #optional true to compress data, if the target format supports it. 1100# (default: false) (since 2.8) 1101# 1102# @on-source-error: #optional the action to take on an error on the source, 1103# default 'report'. 'stop' and 'enospc' can only be used 1104# if the block device supports io-status (see BlockInfo). 1105# 1106# @on-target-error: #optional the action to take on an error on the target, 1107# default 'report' (no limitations, since this applies to 1108# a different block device than @device). 1109# 1110# Note: @on-source-error and @on-target-error only affect background 1111# I/O. If an error occurs during a guest write request, the device's 1112# rerror/werror actions will be used. 1113# 1114# Since: 1.6 1115## 1116{ 'struct': 'DriveBackup', 1117 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 1118 '*format': 'str', 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode', 1119 '*speed': 'int', '*bitmap': 'str', '*compress': 'bool', 1120 '*on-source-error': 'BlockdevOnError', 1121 '*on-target-error': 'BlockdevOnError' } } 1122 1123## 1124# @BlockdevBackup: 1125# 1126# @job-id: #optional identifier for the newly-created block job. If 1127# omitted, the device name will be used. (Since 2.7) 1128# 1129# @device: the device name or node-name of a root node which should be copied. 1130# 1131# @target: the device name or node-name of the backup target node. 1132# 1133# @sync: what parts of the disk image should be copied to the destination 1134# (all the disk, only the sectors allocated in the topmost image, or 1135# only new I/O). 1136# 1137# @speed: #optional the maximum speed, in bytes per second. The default is 0, 1138# for unlimited. 1139# 1140# @compress: #optional true to compress data, if the target format supports it. 1141# (default: false) (since 2.8) 1142# 1143# @on-source-error: #optional the action to take on an error on the source, 1144# default 'report'. 'stop' and 'enospc' can only be used 1145# if the block device supports io-status (see BlockInfo). 1146# 1147# @on-target-error: #optional the action to take on an error on the target, 1148# default 'report' (no limitations, since this applies to 1149# a different block device than @device). 1150# 1151# Note: @on-source-error and @on-target-error only affect background 1152# I/O. If an error occurs during a guest write request, the device's 1153# rerror/werror actions will be used. 1154# 1155# Since: 2.3 1156## 1157{ 'struct': 'BlockdevBackup', 1158 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 1159 'sync': 'MirrorSyncMode', 1160 '*speed': 'int', 1161 '*compress': 'bool', 1162 '*on-source-error': 'BlockdevOnError', 1163 '*on-target-error': 'BlockdevOnError' } } 1164 1165## 1166# @blockdev-snapshot-sync: 1167# 1168# Generates a synchronous snapshot of a block device. 1169# 1170# For the arguments, see the documentation of BlockdevSnapshotSync. 1171# 1172# Returns: nothing on success 1173# If @device is not a valid block device, DeviceNotFound 1174# 1175# Since: 0.14.0 1176# 1177# Example: 1178# 1179# -> { "execute": "blockdev-snapshot-sync", 1180# "arguments": { "device": "ide-hd0", 1181# "snapshot-file": 1182# "/some/place/my-image", 1183# "format": "qcow2" } } 1184# <- { "return": {} } 1185# 1186## 1187{ 'command': 'blockdev-snapshot-sync', 1188 'data': 'BlockdevSnapshotSync' } 1189 1190 1191## 1192# @blockdev-snapshot: 1193# 1194# Generates a snapshot of a block device. 1195# 1196# Create a snapshot, by installing 'node' as the backing image of 1197# 'overlay'. Additionally, if 'node' is associated with a block 1198# device, the block device changes to using 'overlay' as its new active 1199# image. 1200# 1201# For the arguments, see the documentation of BlockdevSnapshot. 1202# 1203# Since: 2.5 1204# 1205# Example: 1206# 1207# -> { "execute": "blockdev-add", 1208# "arguments": { "options": { "driver": "qcow2", 1209# "node-name": "node1534", 1210# "file": { "driver": "file", 1211# "filename": "hd1.qcow2" }, 1212# "backing": "" } } } 1213# 1214# <- { "return": {} } 1215# 1216# -> { "execute": "blockdev-snapshot", 1217# "arguments": { "node": "ide-hd0", 1218# "overlay": "node1534" } } 1219# <- { "return": {} } 1220# 1221## 1222{ 'command': 'blockdev-snapshot', 1223 'data': 'BlockdevSnapshot' } 1224 1225## 1226# @change-backing-file: 1227# 1228# Change the backing file in the image file metadata. This does not 1229# cause QEMU to reopen the image file to reparse the backing filename 1230# (it may, however, perform a reopen to change permissions from 1231# r/o -> r/w -> r/o, if needed). The new backing file string is written 1232# into the image file metadata, and the QEMU internal strings are 1233# updated. 1234# 1235# @image-node-name: The name of the block driver state node of the 1236# image to modify. The "device" argument is used 1237# to verify "image-node-name" is in the chain 1238# described by "device". 1239# 1240# @device: The device name or node-name of the root node that owns 1241# image-node-name. 1242# 1243# @backing-file: The string to write as the backing file. This 1244# string is not validated, so care should be taken 1245# when specifying the string or the image chain may 1246# not be able to be reopened again. 1247# 1248# Returns: Nothing on success 1249# 1250# If "device" does not exist or cannot be determined, DeviceNotFound 1251# 1252# Since: 2.1 1253## 1254{ 'command': 'change-backing-file', 1255 'data': { 'device': 'str', 'image-node-name': 'str', 1256 'backing-file': 'str' } } 1257 1258## 1259# @block-commit: 1260# 1261# Live commit of data from overlay image nodes into backing nodes - i.e., 1262# writes data between 'top' and 'base' into 'base'. 1263# 1264# @job-id: #optional identifier for the newly-created block job. If 1265# omitted, the device name will be used. (Since 2.7) 1266# 1267# @device: the device name or node-name of a root node 1268# 1269# @base: #optional The file name of the backing image to write data into. 1270# If not specified, this is the deepest backing image. 1271# 1272# @top: #optional The file name of the backing image within the image chain, 1273# which contains the topmost data to be committed down. If 1274# not specified, this is the active layer. 1275# 1276# @backing-file: #optional The backing file string to write into the overlay 1277# image of 'top'. If 'top' is the active layer, 1278# specifying a backing file string is an error. This 1279# filename is not validated. 1280# 1281# If a pathname string is such that it cannot be 1282# resolved by QEMU, that means that subsequent QMP or 1283# HMP commands must use node-names for the image in 1284# question, as filename lookup methods will fail. 1285# 1286# If not specified, QEMU will automatically determine 1287# the backing file string to use, or error out if 1288# there is no obvious choice. Care should be taken 1289# when specifying the string, to specify a valid 1290# filename or protocol. 1291# (Since 2.1) 1292# 1293# If top == base, that is an error. 1294# If top == active, the job will not be completed by itself, 1295# user needs to complete the job with the block-job-complete 1296# command after getting the ready event. (Since 2.0) 1297# 1298# If the base image is smaller than top, then the base image 1299# will be resized to be the same size as top. If top is 1300# smaller than the base image, the base will not be 1301# truncated. If you want the base image size to match the 1302# size of the smaller top, you can safely truncate it 1303# yourself once the commit operation successfully completes. 1304# 1305# @speed: #optional the maximum speed, in bytes per second 1306# 1307# Returns: Nothing on success 1308# If commit or stream is already active on this device, DeviceInUse 1309# If @device does not exist, DeviceNotFound 1310# If image commit is not supported by this device, NotSupported 1311# If @base or @top is invalid, a generic error is returned 1312# If @speed is invalid, InvalidParameter 1313# 1314# Since: 1.3 1315# 1316# Example: 1317# 1318# -> { "execute": "block-commit", 1319# "arguments": { "device": "virtio0", 1320# "top": "/tmp/snap1.qcow2" } } 1321# <- { "return": {} } 1322# 1323## 1324{ 'command': 'block-commit', 1325 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', '*top': 'str', 1326 '*backing-file': 'str', '*speed': 'int' } } 1327 1328## 1329# @drive-backup: 1330# 1331# Start a point-in-time copy of a block device to a new destination. The 1332# status of ongoing drive-backup operations can be checked with 1333# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1334# The operation can be stopped before it has completed using the 1335# block-job-cancel command. 1336# 1337# For the arguments, see the documentation of DriveBackup. 1338# 1339# Returns: nothing on success 1340# If @device is not a valid block device, GenericError 1341# 1342# Since: 1.6 1343# 1344# Example: 1345# 1346# -> { "execute": "drive-backup", 1347# "arguments": { "device": "drive0", 1348# "sync": "full", 1349# "target": "backup.img" } } 1350# <- { "return": {} } 1351# 1352## 1353{ 'command': 'drive-backup', 'boxed': true, 1354 'data': 'DriveBackup' } 1355 1356## 1357# @blockdev-backup: 1358# 1359# Start a point-in-time copy of a block device to a new destination. The 1360# status of ongoing blockdev-backup operations can be checked with 1361# query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1362# The operation can be stopped before it has completed using the 1363# block-job-cancel command. 1364# 1365# For the arguments, see the documentation of BlockdevBackup. 1366# 1367# Returns: nothing on success 1368# If @device is not a valid block device, DeviceNotFound 1369# 1370# Since: 2.3 1371# 1372# Example: 1373# -> { "execute": "blockdev-backup", 1374# "arguments": { "device": "src-id", 1375# "sync": "full", 1376# "target": "tgt-id" } } 1377# <- { "return": {} } 1378# 1379## 1380{ 'command': 'blockdev-backup', 'boxed': true, 1381 'data': 'BlockdevBackup' } 1382 1383 1384## 1385# @query-named-block-nodes: 1386# 1387# Get the named block driver list 1388# 1389# Returns: the list of BlockDeviceInfo 1390# 1391# Since: 2.0 1392# 1393# Example: 1394# 1395# -> { "execute": "query-named-block-nodes" } 1396# <- { "return": [ { "ro":false, 1397# "drv":"qcow2", 1398# "encrypted":false, 1399# "file":"disks/test.qcow2", 1400# "node-name": "my-node", 1401# "backing_file_depth":1, 1402# "bps":1000000, 1403# "bps_rd":0, 1404# "bps_wr":0, 1405# "iops":1000000, 1406# "iops_rd":0, 1407# "iops_wr":0, 1408# "bps_max": 8000000, 1409# "bps_rd_max": 0, 1410# "bps_wr_max": 0, 1411# "iops_max": 0, 1412# "iops_rd_max": 0, 1413# "iops_wr_max": 0, 1414# "iops_size": 0, 1415# "write_threshold": 0, 1416# "image":{ 1417# "filename":"disks/test.qcow2", 1418# "format":"qcow2", 1419# "virtual-size":2048000, 1420# "backing_file":"base.qcow2", 1421# "full-backing-filename":"disks/base.qcow2", 1422# "backing-filename-format":"qcow2", 1423# "snapshots":[ 1424# { 1425# "id": "1", 1426# "name": "snapshot1", 1427# "vm-state-size": 0, 1428# "date-sec": 10000200, 1429# "date-nsec": 12, 1430# "vm-clock-sec": 206, 1431# "vm-clock-nsec": 30 1432# } 1433# ], 1434# "backing-image":{ 1435# "filename":"disks/base.qcow2", 1436# "format":"qcow2", 1437# "virtual-size":2048000 1438# } 1439# } } ] } 1440# 1441## 1442{ 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ] } 1443 1444## 1445# @drive-mirror: 1446# 1447# Start mirroring a block device's writes to a new destination. target 1448# specifies the target of the new image. If the file exists, or if it 1449# is a device, it will be used as the new destination for writes. If 1450# it does not exist, a new file will be created. format specifies the 1451# format of the mirror image, default is to probe if mode='existing', 1452# else the format of the source. 1453# 1454# See DriveMirror for parameter descriptions 1455# 1456# Returns: nothing on success 1457# If @device is not a valid block device, GenericError 1458# 1459# Since: 1.3 1460# 1461# Example: 1462# 1463# -> { "execute": "drive-mirror", 1464# "arguments": { "device": "ide-hd0", 1465# "target": "/some/place/my-image", 1466# "sync": "full", 1467# "format": "qcow2" } } 1468# <- { "return": {} } 1469# 1470## 1471{ 'command': 'drive-mirror', 'boxed': true, 1472 'data': 'DriveMirror' } 1473 1474## 1475# @DriveMirror: 1476# 1477# A set of parameters describing drive mirror setup. 1478# 1479# @job-id: #optional identifier for the newly-created block job. If 1480# omitted, the device name will be used. (Since 2.7) 1481# 1482# @device: the device name or node-name of a root node whose writes should be 1483# mirrored. 1484# 1485# @target: the target of the new image. If the file exists, or if it 1486# is a device, the existing file/device will be used as the new 1487# destination. If it does not exist, a new file will be created. 1488# 1489# @format: #optional the format of the new destination, default is to 1490# probe if @mode is 'existing', else the format of the source 1491# 1492# @node-name: #optional the new block driver state node name in the graph 1493# (Since 2.1) 1494# 1495# @replaces: #optional with sync=full graph node name to be replaced by the new 1496# image when a whole image copy is done. This can be used to repair 1497# broken Quorum files. (Since 2.1) 1498# 1499# @mode: #optional whether and how QEMU should create a new image, default is 1500# 'absolute-paths'. 1501# 1502# @speed: #optional the maximum speed, in bytes per second 1503# 1504# @sync: what parts of the disk image should be copied to the destination 1505# (all the disk, only the sectors allocated in the topmost image, or 1506# only new I/O). 1507# 1508# @granularity: #optional granularity of the dirty bitmap, default is 64K 1509# if the image format doesn't have clusters, 4K if the clusters 1510# are smaller than that, else the cluster size. Must be a 1511# power of 2 between 512 and 64M (since 1.4). 1512# 1513# @buf-size: #optional maximum amount of data in flight from source to 1514# target (since 1.4). 1515# 1516# @on-source-error: #optional the action to take on an error on the source, 1517# default 'report'. 'stop' and 'enospc' can only be used 1518# if the block device supports io-status (see BlockInfo). 1519# 1520# @on-target-error: #optional the action to take on an error on the target, 1521# default 'report' (no limitations, since this applies to 1522# a different block device than @device). 1523# @unmap: #optional Whether to try to unmap target sectors where source has 1524# only zero. If true, and target unallocated sectors will read as zero, 1525# target image sectors will be unmapped; otherwise, zeroes will be 1526# written. Both will result in identical contents. 1527# Default is true. (Since 2.4) 1528# 1529# Since: 1.3 1530## 1531{ 'struct': 'DriveMirror', 1532 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 1533 '*format': 'str', '*node-name': 'str', '*replaces': 'str', 1534 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode', 1535 '*speed': 'int', '*granularity': 'uint32', 1536 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError', 1537 '*on-target-error': 'BlockdevOnError', 1538 '*unmap': 'bool' } } 1539 1540## 1541# @BlockDirtyBitmap: 1542# 1543# @node: name of device/node which the bitmap is tracking 1544# 1545# @name: name of the dirty bitmap 1546# 1547# Since: 2.4 1548## 1549{ 'struct': 'BlockDirtyBitmap', 1550 'data': { 'node': 'str', 'name': 'str' } } 1551 1552## 1553# @BlockDirtyBitmapAdd: 1554# 1555# @node: name of device/node which the bitmap is tracking 1556# 1557# @name: name of the dirty bitmap 1558# 1559# @granularity: #optional the bitmap granularity, default is 64k for 1560# block-dirty-bitmap-add 1561# 1562# Since: 2.4 1563## 1564{ 'struct': 'BlockDirtyBitmapAdd', 1565 'data': { 'node': 'str', 'name': 'str', '*granularity': 'uint32' } } 1566 1567## 1568# @block-dirty-bitmap-add: 1569# 1570# Create a dirty bitmap with a name on the node, and start tracking the writes. 1571# 1572# Returns: nothing on success 1573# If @node is not a valid block device or node, DeviceNotFound 1574# If @name is already taken, GenericError with an explanation 1575# 1576# Since: 2.4 1577# 1578# Example: 1579# 1580# -> { "execute": "block-dirty-bitmap-add", 1581# "arguments": { "node": "drive0", "name": "bitmap0" } } 1582# <- { "return": {} } 1583# 1584## 1585{ 'command': 'block-dirty-bitmap-add', 1586 'data': 'BlockDirtyBitmapAdd' } 1587 1588## 1589# @block-dirty-bitmap-remove: 1590# 1591# Stop write tracking and remove the dirty bitmap that was created 1592# with block-dirty-bitmap-add. 1593# 1594# Returns: nothing on success 1595# If @node is not a valid block device or node, DeviceNotFound 1596# If @name is not found, GenericError with an explanation 1597# if @name is frozen by an operation, GenericError 1598# 1599# Since: 2.4 1600# 1601# Example: 1602# 1603# -> { "execute": "block-dirty-bitmap-remove", 1604# "arguments": { "node": "drive0", "name": "bitmap0" } } 1605# <- { "return": {} } 1606# 1607## 1608{ 'command': 'block-dirty-bitmap-remove', 1609 'data': 'BlockDirtyBitmap' } 1610 1611## 1612# @block-dirty-bitmap-clear: 1613# 1614# Clear (reset) a dirty bitmap on the device, so that an incremental 1615# backup from this point in time forward will only backup clusters 1616# modified after this clear operation. 1617# 1618# Returns: nothing on success 1619# If @node is not a valid block device, DeviceNotFound 1620# If @name is not found, GenericError with an explanation 1621# 1622# Since: 2.4 1623# 1624# Example: 1625# 1626# -> { "execute": "block-dirty-bitmap-clear", 1627# "arguments": { "node": "drive0", "name": "bitmap0" } } 1628# <- { "return": {} } 1629# 1630## 1631{ 'command': 'block-dirty-bitmap-clear', 1632 'data': 'BlockDirtyBitmap' } 1633 1634## 1635# @blockdev-mirror: 1636# 1637# Start mirroring a block device's writes to a new destination. 1638# 1639# @job-id: #optional identifier for the newly-created block job. If 1640# omitted, the device name will be used. (Since 2.7) 1641# 1642# @device: The device name or node-name of a root node whose writes should be 1643# mirrored. 1644# 1645# @target: the id or node-name of the block device to mirror to. This mustn't be 1646# attached to guest. 1647# 1648# @replaces: #optional with sync=full graph node name to be replaced by the new 1649# image when a whole image copy is done. This can be used to repair 1650# broken Quorum files. 1651# 1652# @speed: #optional the maximum speed, in bytes per second 1653# 1654# @sync: what parts of the disk image should be copied to the destination 1655# (all the disk, only the sectors allocated in the topmost image, or 1656# only new I/O). 1657# 1658# @granularity: #optional granularity of the dirty bitmap, default is 64K 1659# if the image format doesn't have clusters, 4K if the clusters 1660# are smaller than that, else the cluster size. Must be a 1661# power of 2 between 512 and 64M 1662# 1663# @buf-size: #optional maximum amount of data in flight from source to 1664# target 1665# 1666# @on-source-error: #optional the action to take on an error on the source, 1667# default 'report'. 'stop' and 'enospc' can only be used 1668# if the block device supports io-status (see BlockInfo). 1669# 1670# @on-target-error: #optional the action to take on an error on the target, 1671# default 'report' (no limitations, since this applies to 1672# a different block device than @device). 1673# 1674# Returns: nothing on success. 1675# 1676# Since: 2.6 1677# 1678# Example: 1679# 1680# -> { "execute": "blockdev-mirror", 1681# "arguments": { "device": "ide-hd0", 1682# "target": "target0", 1683# "sync": "full" } } 1684# <- { "return": {} } 1685# 1686## 1687{ 'command': 'blockdev-mirror', 1688 'data': { '*job-id': 'str', 'device': 'str', 'target': 'str', 1689 '*replaces': 'str', 1690 'sync': 'MirrorSyncMode', 1691 '*speed': 'int', '*granularity': 'uint32', 1692 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError', 1693 '*on-target-error': 'BlockdevOnError' } } 1694 1695## 1696# @block_set_io_throttle: 1697# 1698# Change I/O throttle limits for a block drive. 1699# 1700# Since QEMU 2.4, each device with I/O limits is member of a throttle 1701# group. 1702# 1703# If two or more devices are members of the same group, the limits 1704# will apply to the combined I/O of the whole group in a round-robin 1705# fashion. Therefore, setting new I/O limits to a device will affect 1706# the whole group. 1707# 1708# The name of the group can be specified using the 'group' parameter. 1709# If the parameter is unset, it is assumed to be the current group of 1710# that device. If it's not in any group yet, the name of the device 1711# will be used as the name for its group. 1712# 1713# The 'group' parameter can also be used to move a device to a 1714# different group. In this case the limits specified in the parameters 1715# will be applied to the new group only. 1716# 1717# I/O limits can be disabled by setting all of them to 0. In this case 1718# the device will be removed from its group and the rest of its 1719# members will not be affected. The 'group' parameter is ignored. 1720# 1721# See BlockIOThrottle for parameter descriptions. 1722# 1723# Returns: Nothing on success 1724# If @device is not a valid block device, DeviceNotFound 1725# 1726# Since: 1.1 1727# 1728# Example: 1729# 1730# -> { "execute": "block_set_io_throttle", 1731# "arguments": { "id": "ide0-1-0", 1732# "bps": 1000000, 1733# "bps_rd": 0, 1734# "bps_wr": 0, 1735# "iops": 0, 1736# "iops_rd": 0, 1737# "iops_wr": 0, 1738# "bps_max": 8000000, 1739# "bps_rd_max": 0, 1740# "bps_wr_max": 0, 1741# "iops_max": 0, 1742# "iops_rd_max": 0, 1743# "iops_wr_max": 0, 1744# "bps_max_length": 60, 1745# "iops_size": 0 } } 1746# <- { "return": {} } 1747## 1748{ 'command': 'block_set_io_throttle', 'boxed': true, 1749 'data': 'BlockIOThrottle' } 1750 1751## 1752# @BlockIOThrottle: 1753# 1754# A set of parameters describing block throttling. 1755# 1756# @device: #optional Block device name (deprecated, use @id instead) 1757# 1758# @id: #optional The name or QOM path of the guest device (since: 2.8) 1759# 1760# @bps: total throughput limit in bytes per second 1761# 1762# @bps_rd: read throughput limit in bytes per second 1763# 1764# @bps_wr: write throughput limit in bytes per second 1765# 1766# @iops: total I/O operations per second 1767# 1768# @iops_rd: read I/O operations per second 1769# 1770# @iops_wr: write I/O operations per second 1771# 1772# @bps_max: #optional total throughput limit during bursts, 1773# in bytes (Since 1.7) 1774# 1775# @bps_rd_max: #optional read throughput limit during bursts, 1776# in bytes (Since 1.7) 1777# 1778# @bps_wr_max: #optional write throughput limit during bursts, 1779# in bytes (Since 1.7) 1780# 1781# @iops_max: #optional total I/O operations per second during bursts, 1782# in bytes (Since 1.7) 1783# 1784# @iops_rd_max: #optional read I/O operations per second during bursts, 1785# in bytes (Since 1.7) 1786# 1787# @iops_wr_max: #optional write I/O operations per second during bursts, 1788# in bytes (Since 1.7) 1789# 1790# @bps_max_length: #optional maximum length of the @bps_max burst 1791# period, in seconds. It must only 1792# be set if @bps_max is set as well. 1793# Defaults to 1. (Since 2.6) 1794# 1795# @bps_rd_max_length: #optional maximum length of the @bps_rd_max 1796# burst period, in seconds. It must only 1797# be set if @bps_rd_max is set as well. 1798# Defaults to 1. (Since 2.6) 1799# 1800# @bps_wr_max_length: #optional maximum length of the @bps_wr_max 1801# burst period, in seconds. It must only 1802# be set if @bps_wr_max is set as well. 1803# Defaults to 1. (Since 2.6) 1804# 1805# @iops_max_length: #optional maximum length of the @iops burst 1806# period, in seconds. It must only 1807# be set if @iops_max is set as well. 1808# Defaults to 1. (Since 2.6) 1809# 1810# @iops_rd_max_length: #optional maximum length of the @iops_rd_max 1811# burst period, in seconds. It must only 1812# be set if @iops_rd_max is set as well. 1813# Defaults to 1. (Since 2.6) 1814# 1815# @iops_wr_max_length: #optional maximum length of the @iops_wr_max 1816# burst period, in seconds. It must only 1817# be set if @iops_wr_max is set as well. 1818# Defaults to 1. (Since 2.6) 1819# 1820# @iops_size: #optional an I/O size in bytes (Since 1.7) 1821# 1822# @group: #optional throttle group name (Since 2.4) 1823# 1824# Since: 1.1 1825## 1826{ 'struct': 'BlockIOThrottle', 1827 'data': { '*device': 'str', '*id': 'str', 'bps': 'int', 'bps_rd': 'int', 1828 'bps_wr': 'int', 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int', 1829 '*bps_max': 'int', '*bps_rd_max': 'int', 1830 '*bps_wr_max': 'int', '*iops_max': 'int', 1831 '*iops_rd_max': 'int', '*iops_wr_max': 'int', 1832 '*bps_max_length': 'int', '*bps_rd_max_length': 'int', 1833 '*bps_wr_max_length': 'int', '*iops_max_length': 'int', 1834 '*iops_rd_max_length': 'int', '*iops_wr_max_length': 'int', 1835 '*iops_size': 'int', '*group': 'str' } } 1836 1837## 1838# @block-stream: 1839# 1840# Copy data from a backing file into a block device. 1841# 1842# The block streaming operation is performed in the background until the entire 1843# backing file has been copied. This command returns immediately once streaming 1844# has started. The status of ongoing block streaming operations can be checked 1845# with query-block-jobs. The operation can be stopped before it has completed 1846# using the block-job-cancel command. 1847# 1848# The node that receives the data is called the top image, can be located in 1849# any part of the chain (but always above the base image; see below) and can be 1850# specified using its device or node name. Earlier qemu versions only allowed 1851# 'device' to name the top level node; presence of the 'base-node' parameter 1852# during introspection can be used as a witness of the enhanced semantics 1853# of 'device'. 1854# 1855# If a base file is specified then sectors are not copied from that base file and 1856# its backing chain. When streaming completes the image file will have the base 1857# file as its backing file. This can be used to stream a subset of the backing 1858# file chain instead of flattening the entire image. 1859# 1860# On successful completion the image file is updated to drop the backing file 1861# and the BLOCK_JOB_COMPLETED event is emitted. 1862# 1863# @job-id: #optional identifier for the newly-created block job. If 1864# omitted, the device name will be used. (Since 2.7) 1865# 1866# @device: the device or node name of the top image 1867# 1868# @base: #optional the common backing file name. 1869# It cannot be set if @base-node is also set. 1870# 1871# @base-node: #optional the node name of the backing file. 1872# It cannot be set if @base is also set. (Since 2.8) 1873# 1874# @backing-file: #optional The backing file string to write into the top 1875# image. This filename is not validated. 1876# 1877# If a pathname string is such that it cannot be 1878# resolved by QEMU, that means that subsequent QMP or 1879# HMP commands must use node-names for the image in 1880# question, as filename lookup methods will fail. 1881# 1882# If not specified, QEMU will automatically determine 1883# the backing file string to use, or error out if there 1884# is no obvious choice. Care should be taken when 1885# specifying the string, to specify a valid filename or 1886# protocol. 1887# (Since 2.1) 1888# 1889# @speed: #optional the maximum speed, in bytes per second 1890# 1891# @on-error: #optional the action to take on an error (default report). 1892# 'stop' and 'enospc' can only be used if the block device 1893# supports io-status (see BlockInfo). Since 1.3. 1894# 1895# Returns: Nothing on success. If @device does not exist, DeviceNotFound. 1896# 1897# Since: 1.1 1898# 1899# Example: 1900# 1901# -> { "execute": "block-stream", 1902# "arguments": { "device": "virtio0", 1903# "base": "/tmp/master.qcow2" } } 1904# <- { "return": {} } 1905# 1906## 1907{ 'command': 'block-stream', 1908 'data': { '*job-id': 'str', 'device': 'str', '*base': 'str', 1909 '*base-node': 'str', '*backing-file': 'str', '*speed': 'int', 1910 '*on-error': 'BlockdevOnError' } } 1911 1912## 1913# @block-job-set-speed: 1914# 1915# Set maximum speed for a background block operation. 1916# 1917# This command can only be issued when there is an active block job. 1918# 1919# Throttling can be disabled by setting the speed to 0. 1920# 1921# @device: The job identifier. This used to be a device name (hence 1922# the name of the parameter), but since QEMU 2.7 it can have 1923# other values. 1924# 1925# @speed: the maximum speed, in bytes per second, or 0 for unlimited. 1926# Defaults to 0. 1927# 1928# Returns: Nothing on success 1929# If no background operation is active on this device, DeviceNotActive 1930# 1931# Since: 1.1 1932## 1933{ 'command': 'block-job-set-speed', 1934 'data': { 'device': 'str', 'speed': 'int' } } 1935 1936## 1937# @block-job-cancel: 1938# 1939# Stop an active background block operation. 1940# 1941# This command returns immediately after marking the active background block 1942# operation for cancellation. It is an error to call this command if no 1943# operation is in progress. 1944# 1945# The operation will cancel as soon as possible and then emit the 1946# BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when 1947# enumerated using query-block-jobs. 1948# 1949# For streaming, the image file retains its backing file unless the streaming 1950# operation happens to complete just as it is being cancelled. A new streaming 1951# operation can be started at a later time to finish copying all data from the 1952# backing file. 1953# 1954# @device: The job identifier. This used to be a device name (hence 1955# the name of the parameter), but since QEMU 2.7 it can have 1956# other values. 1957# 1958# @force: #optional whether to allow cancellation of a paused job (default 1959# false). Since 1.3. 1960# 1961# Returns: Nothing on success 1962# If no background operation is active on this device, DeviceNotActive 1963# 1964# Since: 1.1 1965## 1966{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } } 1967 1968## 1969# @block-job-pause: 1970# 1971# Pause an active background block operation. 1972# 1973# This command returns immediately after marking the active background block 1974# operation for pausing. It is an error to call this command if no 1975# operation is in progress. Pausing an already paused job has no cumulative 1976# effect; a single block-job-resume command will resume the job. 1977# 1978# The operation will pause as soon as possible. No event is emitted when 1979# the operation is actually paused. Cancelling a paused job automatically 1980# resumes it. 1981# 1982# @device: The job identifier. This used to be a device name (hence 1983# the name of the parameter), but since QEMU 2.7 it can have 1984# other values. 1985# 1986# Returns: Nothing on success 1987# If no background operation is active on this device, DeviceNotActive 1988# 1989# Since: 1.3 1990## 1991{ 'command': 'block-job-pause', 'data': { 'device': 'str' } } 1992 1993## 1994# @block-job-resume: 1995# 1996# Resume an active background block operation. 1997# 1998# This command returns immediately after resuming a paused background block 1999# operation. It is an error to call this command if no operation is in 2000# progress. Resuming an already running job is not an error. 2001# 2002# This command also clears the error status of the job. 2003# 2004# @device: The job identifier. This used to be a device name (hence 2005# the name of the parameter), but since QEMU 2.7 it can have 2006# other values. 2007# 2008# Returns: Nothing on success 2009# If no background operation is active on this device, DeviceNotActive 2010# 2011# Since: 1.3 2012## 2013{ 'command': 'block-job-resume', 'data': { 'device': 'str' } } 2014 2015## 2016# @block-job-complete: 2017# 2018# Manually trigger completion of an active background block operation. This 2019# is supported for drive mirroring, where it also switches the device to 2020# write to the target path only. The ability to complete is signaled with 2021# a BLOCK_JOB_READY event. 2022# 2023# This command completes an active background block operation synchronously. 2024# The ordering of this command's return with the BLOCK_JOB_COMPLETED event 2025# is not defined. Note that if an I/O error occurs during the processing of 2026# this command: 1) the command itself will fail; 2) the error will be processed 2027# according to the rerror/werror arguments that were specified when starting 2028# the operation. 2029# 2030# A cancelled or paused job cannot be completed. 2031# 2032# @device: The job identifier. This used to be a device name (hence 2033# the name of the parameter), but since QEMU 2.7 it can have 2034# other values. 2035# 2036# Returns: Nothing on success 2037# If no background operation is active on this device, DeviceNotActive 2038# 2039# Since: 1.3 2040## 2041{ 'command': 'block-job-complete', 'data': { 'device': 'str' } } 2042 2043## 2044# @BlockdevDiscardOptions: 2045# 2046# Determines how to handle discard requests. 2047# 2048# @ignore: Ignore the request 2049# @unmap: Forward as an unmap request 2050# 2051# Since: 1.7 2052## 2053{ 'enum': 'BlockdevDiscardOptions', 2054 'data': [ 'ignore', 'unmap' ] } 2055 2056## 2057# @BlockdevDetectZeroesOptions: 2058# 2059# Describes the operation mode for the automatic conversion of plain 2060# zero writes by the OS to driver specific optimized zero write commands. 2061# 2062# @off: Disabled (default) 2063# @on: Enabled 2064# @unmap: Enabled and even try to unmap blocks if possible. This requires 2065# also that @BlockdevDiscardOptions is set to unmap for this device. 2066# 2067# Since: 2.1 2068## 2069{ 'enum': 'BlockdevDetectZeroesOptions', 2070 'data': [ 'off', 'on', 'unmap' ] } 2071 2072## 2073# @BlockdevAioOptions: 2074# 2075# Selects the AIO backend to handle I/O requests 2076# 2077# @threads: Use qemu's thread pool 2078# @native: Use native AIO backend (only Linux and Windows) 2079# 2080# Since: 1.7 2081## 2082{ 'enum': 'BlockdevAioOptions', 2083 'data': [ 'threads', 'native' ] } 2084 2085## 2086# @BlockdevCacheOptions: 2087# 2088# Includes cache-related options for block devices 2089# 2090# @direct: #optional enables use of O_DIRECT (bypass the host page cache; 2091# default: false) 2092# @no-flush: #optional ignore any flush requests for the device (default: 2093# false) 2094# 2095# Since: 1.7 2096## 2097{ 'struct': 'BlockdevCacheOptions', 2098 'data': { '*direct': 'bool', 2099 '*no-flush': 'bool' } } 2100 2101## 2102# @BlockdevDriver: 2103# 2104# Drivers that are supported in block device operations. 2105# 2106# @host_device: Since 2.1 2107# @host_cdrom: Since 2.1 2108# @gluster: Since 2.7 2109# @nbd: Since 2.8 2110# @nfs: Since 2.8 2111# @replication: Since 2.8 2112# @ssh: Since 2.8 2113# @iscsi: Since 2.9 2114# 2115# Since: 2.0 2116## 2117{ 'enum': 'BlockdevDriver', 2118 'data': [ 'archipelago', 'blkdebug', 'blkverify', 'bochs', 'cloop', 2119 'dmg', 'file', 'ftp', 'ftps', 'gluster', 'host_cdrom', 2120 'host_device', 'http', 'https', 'iscsi', 'luks', 'nbd', 'nfs', 2121 'null-aio', 'null-co', 'parallels', 'qcow', 'qcow2', 'qed', 2122 'quorum', 'raw', 'replication', 'ssh', 'vdi', 'vhdx', 'vmdk', 2123 'vpc', 'vvfat' ] } 2124 2125## 2126# @BlockdevOptionsFile: 2127# 2128# Driver specific block device options for the file backend. 2129# 2130# @filename: path to the image file 2131# @aio: #optional AIO backend (default: threads) (since: 2.8) 2132# 2133# Since: 1.7 2134## 2135{ 'struct': 'BlockdevOptionsFile', 2136 'data': { 'filename': 'str', 2137 '*aio': 'BlockdevAioOptions' } } 2138 2139## 2140# @BlockdevOptionsNull: 2141# 2142# Driver specific block device options for the null backend. 2143# 2144# @size: #optional size of the device in bytes. 2145# @latency-ns: #optional emulated latency (in nanoseconds) in processing 2146# requests. Default to zero which completes requests immediately. 2147# (Since 2.4) 2148# 2149# Since: 2.2 2150## 2151{ 'struct': 'BlockdevOptionsNull', 2152 'data': { '*size': 'int', '*latency-ns': 'uint64' } } 2153 2154## 2155# @BlockdevOptionsVVFAT: 2156# 2157# Driver specific block device options for the vvfat protocol. 2158# 2159# @dir: directory to be exported as FAT image 2160# @fat-type: #optional FAT type: 12, 16 or 32 2161# @floppy: #optional whether to export a floppy image (true) or 2162# partitioned hard disk (false; default) 2163# @label: #optional set the volume label, limited to 11 bytes. FAT16 and 2164# FAT32 traditionally have some restrictions on labels, which are 2165# ignored by most operating systems. Defaults to "QEMU VVFAT". 2166# (since 2.4) 2167# @rw: #optional whether to allow write operations (default: false) 2168# 2169# Since: 1.7 2170## 2171{ 'struct': 'BlockdevOptionsVVFAT', 2172 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool', 2173 '*label': 'str', '*rw': 'bool' } } 2174 2175## 2176# @BlockdevOptionsGenericFormat: 2177# 2178# Driver specific block device options for image format that have no option 2179# besides their data source. 2180# 2181# @file: reference to or definition of the data source block device 2182# 2183# Since: 1.7 2184## 2185{ 'struct': 'BlockdevOptionsGenericFormat', 2186 'data': { 'file': 'BlockdevRef' } } 2187 2188## 2189# @BlockdevOptionsLUKS: 2190# 2191# Driver specific block device options for LUKS. 2192# 2193# @key-secret: #optional the ID of a QCryptoSecret object providing 2194# the decryption key (since 2.6). Mandatory except when 2195# doing a metadata-only probe of the image. 2196# 2197# Since: 2.6 2198## 2199{ 'struct': 'BlockdevOptionsLUKS', 2200 'base': 'BlockdevOptionsGenericFormat', 2201 'data': { '*key-secret': 'str' } } 2202 2203 2204## 2205# @BlockdevOptionsGenericCOWFormat: 2206# 2207# Driver specific block device options for image format that have no option 2208# besides their data source and an optional backing file. 2209# 2210# @backing: #optional reference to or definition of the backing file block 2211# device (if missing, taken from the image file content). It is 2212# allowed to pass an empty string here in order to disable the 2213# default backing file. 2214# 2215# Since: 1.7 2216## 2217{ 'struct': 'BlockdevOptionsGenericCOWFormat', 2218 'base': 'BlockdevOptionsGenericFormat', 2219 'data': { '*backing': 'BlockdevRef' } } 2220 2221## 2222# @Qcow2OverlapCheckMode: 2223# 2224# General overlap check modes. 2225# 2226# @none: Do not perform any checks 2227# 2228# @constant: Perform only checks which can be done in constant time and 2229# without reading anything from disk 2230# 2231# @cached: Perform only checks which can be done without reading anything 2232# from disk 2233# 2234# @all: Perform all available overlap checks 2235# 2236# Since: 2.2 2237## 2238{ 'enum': 'Qcow2OverlapCheckMode', 2239 'data': [ 'none', 'constant', 'cached', 'all' ] } 2240 2241## 2242# @Qcow2OverlapCheckFlags: 2243# 2244# Structure of flags for each metadata structure. Setting a field to 'true' 2245# makes qemu guard that structure against unintended overwriting. The default 2246# value is chosen according to the template given. 2247# 2248# @template: Specifies a template mode which can be adjusted using the other 2249# flags, defaults to 'cached' 2250# 2251# Since: 2.2 2252## 2253{ 'struct': 'Qcow2OverlapCheckFlags', 2254 'data': { '*template': 'Qcow2OverlapCheckMode', 2255 '*main-header': 'bool', 2256 '*active-l1': 'bool', 2257 '*active-l2': 'bool', 2258 '*refcount-table': 'bool', 2259 '*refcount-block': 'bool', 2260 '*snapshot-table': 'bool', 2261 '*inactive-l1': 'bool', 2262 '*inactive-l2': 'bool' } } 2263 2264## 2265# @Qcow2OverlapChecks: 2266# 2267# Specifies which metadata structures should be guarded against unintended 2268# overwriting. 2269# 2270# @flags: set of flags for separate specification of each metadata structure 2271# type 2272# 2273# @mode: named mode which chooses a specific set of flags 2274# 2275# Since: 2.2 2276## 2277{ 'alternate': 'Qcow2OverlapChecks', 2278 'data': { 'flags': 'Qcow2OverlapCheckFlags', 2279 'mode': 'Qcow2OverlapCheckMode' } } 2280 2281## 2282# @BlockdevOptionsQcow2: 2283# 2284# Driver specific block device options for qcow2. 2285# 2286# @lazy-refcounts: #optional whether to enable the lazy refcounts 2287# feature (default is taken from the image file) 2288# 2289# @pass-discard-request: #optional whether discard requests to the qcow2 2290# device should be forwarded to the data source 2291# 2292# @pass-discard-snapshot: #optional whether discard requests for the data source 2293# should be issued when a snapshot operation (e.g. 2294# deleting a snapshot) frees clusters in the qcow2 file 2295# 2296# @pass-discard-other: #optional whether discard requests for the data source 2297# should be issued on other occasions where a cluster 2298# gets freed 2299# 2300# @overlap-check: #optional which overlap checks to perform for writes 2301# to the image, defaults to 'cached' (since 2.2) 2302# 2303# @cache-size: #optional the maximum total size of the L2 table and 2304# refcount block caches in bytes (since 2.2) 2305# 2306# @l2-cache-size: #optional the maximum size of the L2 table cache in 2307# bytes (since 2.2) 2308# 2309# @refcount-cache-size: #optional the maximum size of the refcount block cache 2310# in bytes (since 2.2) 2311# 2312# @cache-clean-interval: #optional clean unused entries in the L2 and refcount 2313# caches. The interval is in seconds. The default value 2314# is 0 and it disables this feature (since 2.5) 2315# 2316# Since: 1.7 2317## 2318{ 'struct': 'BlockdevOptionsQcow2', 2319 'base': 'BlockdevOptionsGenericCOWFormat', 2320 'data': { '*lazy-refcounts': 'bool', 2321 '*pass-discard-request': 'bool', 2322 '*pass-discard-snapshot': 'bool', 2323 '*pass-discard-other': 'bool', 2324 '*overlap-check': 'Qcow2OverlapChecks', 2325 '*cache-size': 'int', 2326 '*l2-cache-size': 'int', 2327 '*refcount-cache-size': 'int', 2328 '*cache-clean-interval': 'int' } } 2329 2330 2331## 2332# @BlockdevOptionsArchipelago: 2333# 2334# Driver specific block device options for Archipelago. 2335# 2336# @volume: Name of the Archipelago volume image 2337# 2338# @mport: #optional The port number on which mapperd is 2339# listening. This is optional 2340# and if not specified, QEMU will make Archipelago 2341# use the default port (1001). 2342# 2343# @vport: #optional The port number on which vlmcd is 2344# listening. This is optional 2345# and if not specified, QEMU will make Archipelago 2346# use the default port (501). 2347# 2348# @segment: #optional The name of the shared memory segment 2349# Archipelago stack is using. This is optional 2350# and if not specified, QEMU will make Archipelago 2351# use the default value, 'archipelago'. 2352# Since: 2.2 2353## 2354{ 'struct': 'BlockdevOptionsArchipelago', 2355 'data': { 'volume': 'str', 2356 '*mport': 'int', 2357 '*vport': 'int', 2358 '*segment': 'str' } } 2359 2360## 2361# @BlockdevOptionsSsh: 2362# 2363# @server: host address 2364# 2365# @path: path to the image on the host 2366# 2367# @user: #optional user as which to connect, defaults to current 2368# local user name 2369# 2370# TODO: Expose the host_key_check option in QMP 2371# 2372# Since: 2.8 2373## 2374{ 'struct': 'BlockdevOptionsSsh', 2375 'data': { 'server': 'InetSocketAddress', 2376 'path': 'str', 2377 '*user': 'str' } } 2378 2379 2380## 2381# @BlkdebugEvent: 2382# 2383# Trigger events supported by blkdebug. 2384# 2385# Since: 2.0 2386## 2387{ 'enum': 'BlkdebugEvent', 'prefix': 'BLKDBG', 2388 'data': [ 'l1_update', 'l1_grow_alloc_table', 'l1_grow_write_table', 2389 'l1_grow_activate_table', 'l2_load', 'l2_update', 2390 'l2_update_compressed', 'l2_alloc_cow_read', 'l2_alloc_write', 2391 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio', 2392 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read', 2393 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update', 2394 'refblock_load', 'refblock_update', 'refblock_update_part', 2395 'refblock_alloc', 'refblock_alloc_hookup', 'refblock_alloc_write', 2396 'refblock_alloc_write_blocks', 'refblock_alloc_write_table', 2397 'refblock_alloc_switch_table', 'cluster_alloc', 2398 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os', 2399 'flush_to_disk', 'pwritev_rmw_head', 'pwritev_rmw_after_head', 2400 'pwritev_rmw_tail', 'pwritev_rmw_after_tail', 'pwritev', 2401 'pwritev_zero', 'pwritev_done', 'empty_image_prepare' ] } 2402 2403## 2404# @BlkdebugInjectErrorOptions: 2405# 2406# Describes a single error injection for blkdebug. 2407# 2408# @event: trigger event 2409# 2410# @state: #optional the state identifier blkdebug needs to be in to 2411# actually trigger the event; defaults to "any" 2412# 2413# @errno: #optional error identifier (errno) to be returned; defaults to 2414# EIO 2415# 2416# @sector: #optional specifies the sector index which has to be affected 2417# in order to actually trigger the event; defaults to "any 2418# sector" 2419# 2420# @once: #optional disables further events after this one has been 2421# triggered; defaults to false 2422# 2423# @immediately: #optional fail immediately; defaults to false 2424# 2425# Since: 2.0 2426## 2427{ 'struct': 'BlkdebugInjectErrorOptions', 2428 'data': { 'event': 'BlkdebugEvent', 2429 '*state': 'int', 2430 '*errno': 'int', 2431 '*sector': 'int', 2432 '*once': 'bool', 2433 '*immediately': 'bool' } } 2434 2435## 2436# @BlkdebugSetStateOptions: 2437# 2438# Describes a single state-change event for blkdebug. 2439# 2440# @event: trigger event 2441# 2442# @state: #optional the current state identifier blkdebug needs to be in; 2443# defaults to "any" 2444# 2445# @new_state: the state identifier blkdebug is supposed to assume if 2446# this event is triggered 2447# 2448# Since: 2.0 2449## 2450{ 'struct': 'BlkdebugSetStateOptions', 2451 'data': { 'event': 'BlkdebugEvent', 2452 '*state': 'int', 2453 'new_state': 'int' } } 2454 2455## 2456# @BlockdevOptionsBlkdebug: 2457# 2458# Driver specific block device options for blkdebug. 2459# 2460# @image: underlying raw block device (or image file) 2461# 2462# @config: #optional filename of the configuration file 2463# 2464# @align: #optional required alignment for requests in bytes, 2465# must be power of 2, or 0 for default 2466# 2467# @inject-error: #optional array of error injection descriptions 2468# 2469# @set-state: #optional array of state-change descriptions 2470# 2471# Since: 2.0 2472## 2473{ 'struct': 'BlockdevOptionsBlkdebug', 2474 'data': { 'image': 'BlockdevRef', 2475 '*config': 'str', 2476 '*align': 'int', 2477 '*inject-error': ['BlkdebugInjectErrorOptions'], 2478 '*set-state': ['BlkdebugSetStateOptions'] } } 2479 2480## 2481# @BlockdevOptionsBlkverify: 2482# 2483# Driver specific block device options for blkverify. 2484# 2485# @test: block device to be tested 2486# 2487# @raw: raw image used for verification 2488# 2489# Since: 2.0 2490## 2491{ 'struct': 'BlockdevOptionsBlkverify', 2492 'data': { 'test': 'BlockdevRef', 2493 'raw': 'BlockdevRef' } } 2494 2495## 2496# @QuorumReadPattern: 2497# 2498# An enumeration of quorum read patterns. 2499# 2500# @quorum: read all the children and do a quorum vote on reads 2501# 2502# @fifo: read only from the first child that has not failed 2503# 2504# Since: 2.2 2505## 2506{ 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] } 2507 2508## 2509# @BlockdevOptionsQuorum: 2510# 2511# Driver specific block device options for Quorum 2512# 2513# @blkverify: #optional true if the driver must print content mismatch 2514# set to false by default 2515# 2516# @children: the children block devices to use 2517# 2518# @vote-threshold: the vote limit under which a read will fail 2519# 2520# @rewrite-corrupted: #optional rewrite corrupted data when quorum is reached 2521# (Since 2.1) 2522# 2523# @read-pattern: #optional choose read pattern and set to quorum by default 2524# (Since 2.2) 2525# 2526# Since: 2.0 2527## 2528{ 'struct': 'BlockdevOptionsQuorum', 2529 'data': { '*blkverify': 'bool', 2530 'children': [ 'BlockdevRef' ], 2531 'vote-threshold': 'int', 2532 '*rewrite-corrupted': 'bool', 2533 '*read-pattern': 'QuorumReadPattern' } } 2534 2535## 2536# @GlusterTransport: 2537# 2538# An enumeration of Gluster transport types 2539# 2540# @tcp: TCP - Transmission Control Protocol 2541# 2542# @unix: UNIX - Unix domain socket 2543# 2544# Since: 2.7 2545## 2546{ 'enum': 'GlusterTransport', 2547 'data': [ 'unix', 'tcp' ] } 2548 2549 2550## 2551# @GlusterServer: 2552# 2553# Captures the address of a socket 2554# 2555# Details for connecting to a gluster server 2556# 2557# @type: Transport type used for gluster connection 2558# 2559# This is similar to SocketAddress, only distinction: 2560# 2561# 1. GlusterServer is a flat union, SocketAddress is a simple union. 2562# A flat union is nicer than simple because it avoids nesting 2563# (i.e. more {}) on the wire. 2564# 2565# 2. GlusterServer lacks case 'fd', since gluster doesn't let you 2566# pass in a file descriptor. 2567# 2568# GlusterServer is actually not Gluster-specific, its a 2569# compatibility evolved into an alternate for SocketAddress. 2570# 2571# Since: 2.7 2572## 2573{ 'union': 'GlusterServer', 2574 'base': { 'type': 'GlusterTransport' }, 2575 'discriminator': 'type', 2576 'data': { 'unix': 'UnixSocketAddress', 2577 'tcp': 'InetSocketAddress' } } 2578 2579## 2580# @BlockdevOptionsGluster: 2581# 2582# Driver specific block device options for Gluster 2583# 2584# @volume: name of gluster volume where VM image resides 2585# 2586# @path: absolute path to image file in gluster volume 2587# 2588# @server: gluster servers description 2589# 2590# @debug: #optional libgfapi log level (default '4' which is Error) 2591# (Since 2.8) 2592# 2593# @logfile: #optional libgfapi log file (default /dev/stderr) (Since 2.8) 2594# 2595# Since: 2.7 2596## 2597{ 'struct': 'BlockdevOptionsGluster', 2598 'data': { 'volume': 'str', 2599 'path': 'str', 2600 'server': ['GlusterServer'], 2601 '*debug': 'int', 2602 '*logfile': 'str' } } 2603 2604## 2605# @IscsiTransport: 2606# 2607# An enumeration of libiscsi transport types 2608# 2609# Since: 2.9 2610## 2611{ 'enum': 'IscsiTransport', 2612 'data': [ 'tcp', 'iser' ] } 2613 2614## 2615# @IscsiHeaderDigest: 2616# 2617# An enumeration of header digests supported by libiscsi 2618# 2619# Since: 2.9 2620## 2621{ 'enum': 'IscsiHeaderDigest', 2622 'prefix': 'QAPI_ISCSI_HEADER_DIGEST', 2623 'data': [ 'crc32c', 'none', 'crc32c-none', 'none-crc32c' ] } 2624 2625## 2626# @BlockdevOptionsIscsi: 2627# 2628# @transport: The iscsi transport type 2629# 2630# @portal: The address of the iscsi portal 2631# 2632# @target: The target iqn name 2633# 2634# @lun: #optional LUN to connect to. Defaults to 0. 2635# 2636# @user: #optional User name to log in with. If omitted, no CHAP 2637# authentication is performed. 2638# 2639# @password-secret: #optional The ID of a QCryptoSecret object providing 2640# the password for the login. This option is required if 2641# @user is specified. 2642# 2643# @initiator-name: #optional The iqn name we want to identify to the target 2644# as. If this option is not specified, an initiator name is 2645# generated automatically. 2646# 2647# @header-digest: #optional The desired header digest. Defaults to 2648# none-crc32c. 2649# 2650# @timeout: #optional Timeout in seconds after which a request will 2651# timeout. 0 means no timeout and is the default. 2652# 2653# Driver specific block device options for iscsi 2654# 2655# Since: 2.9 2656## 2657{ 'struct': 'BlockdevOptionsIscsi', 2658 'data': { 'transport': 'IscsiTransport', 2659 'portal': 'str', 2660 'target': 'str', 2661 '*lun': 'int', 2662 '*user': 'str', 2663 '*password-secret': 'str', 2664 '*initiator-name': 'str', 2665 '*header-digest': 'IscsiHeaderDigest', 2666 '*timeout': 'int' } } 2667 2668## 2669# @ReplicationMode: 2670# 2671# An enumeration of replication modes. 2672# 2673# @primary: Primary mode, the vm's state will be sent to secondary QEMU. 2674# 2675# @secondary: Secondary mode, receive the vm's state from primary QEMU. 2676# 2677# Since: 2.8 2678## 2679{ 'enum' : 'ReplicationMode', 'data' : [ 'primary', 'secondary' ] } 2680 2681## 2682# @BlockdevOptionsReplication: 2683# 2684# Driver specific block device options for replication 2685# 2686# @mode: the replication mode 2687# 2688# @top-id: #optional In secondary mode, node name or device ID of the root 2689# node who owns the replication node chain. Must not be given in 2690# primary mode. 2691# 2692# Since: 2.8 2693## 2694{ 'struct': 'BlockdevOptionsReplication', 2695 'base': 'BlockdevOptionsGenericFormat', 2696 'data': { 'mode': 'ReplicationMode', 2697 '*top-id': 'str' } } 2698 2699## 2700# @NFSTransport: 2701# 2702# An enumeration of NFS transport types 2703# 2704# @inet: TCP transport 2705# 2706# Since: 2.8 2707## 2708{ 'enum': 'NFSTransport', 2709 'data': [ 'inet' ] } 2710 2711## 2712# @NFSServer: 2713# 2714# Captures the address of the socket 2715# 2716# @type: transport type used for NFS (only TCP supported) 2717# 2718# @host: host address for NFS server 2719# 2720# Since: 2.8 2721## 2722{ 'struct': 'NFSServer', 2723 'data': { 'type': 'NFSTransport', 2724 'host': 'str' } } 2725 2726## 2727# @BlockdevOptionsNfs: 2728# 2729# Driver specific block device option for NFS 2730# 2731# @server: host address 2732# 2733# @path: path of the image on the host 2734# 2735# @user: #optional UID value to use when talking to the 2736# server (defaults to 65534 on Windows and getuid() 2737# on unix) 2738# 2739# @group: #optional GID value to use when talking to the 2740# server (defaults to 65534 on Windows and getgid() 2741# in unix) 2742# 2743# @tcp-syn-count: #optional number of SYNs during the session 2744# establishment (defaults to libnfs default) 2745# 2746# @readahead-size: #optional set the readahead size in bytes (defaults 2747# to libnfs default) 2748# 2749# @page-cache-size: #optional set the pagecache size in bytes (defaults 2750# to libnfs default) 2751# 2752# @debug: #optional set the NFS debug level (max 2) (defaults 2753# to libnfs default) 2754# 2755# Since: 2.8 2756## 2757{ 'struct': 'BlockdevOptionsNfs', 2758 'data': { 'server': 'NFSServer', 2759 'path': 'str', 2760 '*user': 'int', 2761 '*group': 'int', 2762 '*tcp-syn-count': 'int', 2763 '*readahead-size': 'int', 2764 '*page-cache-size': 'int', 2765 '*debug': 'int' } } 2766 2767## 2768# @BlockdevOptionsCurl: 2769# 2770# Driver specific block device options for the curl backend. 2771# 2772# @filename: path to the image file 2773# 2774# Since: 1.7 2775## 2776{ 'struct': 'BlockdevOptionsCurl', 2777 'data': { 'filename': 'str' } } 2778 2779## 2780# @BlockdevOptionsNbd: 2781# 2782# Driver specific block device options for NBD. 2783# 2784# @server: NBD server address 2785# 2786# @export: #optional export name 2787# 2788# @tls-creds: #optional TLS credentials ID 2789# 2790# Since: 2.8 2791## 2792{ 'struct': 'BlockdevOptionsNbd', 2793 'data': { 'server': 'SocketAddress', 2794 '*export': 'str', 2795 '*tls-creds': 'str' } } 2796 2797## 2798# @BlockdevOptionsRaw: 2799# 2800# Driver specific block device options for the raw driver. 2801# 2802# @offset: #optional position where the block device starts 2803# @size: #optional the assumed size of the device 2804# 2805# Since: 2.8 2806## 2807{ 'struct': 'BlockdevOptionsRaw', 2808 'base': 'BlockdevOptionsGenericFormat', 2809 'data': { '*offset': 'int', '*size': 'int' } } 2810 2811## 2812# @BlockdevOptions: 2813# 2814# Options for creating a block device. Many options are available for all 2815# block devices, independent of the block driver: 2816# 2817# @driver: block driver name 2818# @node-name: #optional the node name of the new node (Since 2.0). 2819# This option is required on the top level of blockdev-add. 2820# @discard: #optional discard-related options (default: ignore) 2821# @cache: #optional cache-related options 2822# @read-only: #optional whether the block device should be read-only 2823# (default: false) 2824# @detect-zeroes: #optional detect and optimize zero writes (Since 2.1) 2825# (default: off) 2826# 2827# Remaining options are determined by the block driver. 2828# 2829# Since: 1.7 2830## 2831{ 'union': 'BlockdevOptions', 2832 'base': { 'driver': 'BlockdevDriver', 2833 '*node-name': 'str', 2834 '*discard': 'BlockdevDiscardOptions', 2835 '*cache': 'BlockdevCacheOptions', 2836 '*read-only': 'bool', 2837 '*detect-zeroes': 'BlockdevDetectZeroesOptions' }, 2838 'discriminator': 'driver', 2839 'data': { 2840 'archipelago':'BlockdevOptionsArchipelago', 2841 'blkdebug': 'BlockdevOptionsBlkdebug', 2842 'blkverify': 'BlockdevOptionsBlkverify', 2843 'bochs': 'BlockdevOptionsGenericFormat', 2844 'cloop': 'BlockdevOptionsGenericFormat', 2845 'dmg': 'BlockdevOptionsGenericFormat', 2846 'file': 'BlockdevOptionsFile', 2847 'ftp': 'BlockdevOptionsCurl', 2848 'ftps': 'BlockdevOptionsCurl', 2849 'gluster': 'BlockdevOptionsGluster', 2850 'host_cdrom': 'BlockdevOptionsFile', 2851 'host_device':'BlockdevOptionsFile', 2852 'http': 'BlockdevOptionsCurl', 2853 'https': 'BlockdevOptionsCurl', 2854 'iscsi': 'BlockdevOptionsIscsi', 2855 'luks': 'BlockdevOptionsLUKS', 2856 'nbd': 'BlockdevOptionsNbd', 2857 'nfs': 'BlockdevOptionsNfs', 2858 'null-aio': 'BlockdevOptionsNull', 2859 'null-co': 'BlockdevOptionsNull', 2860 'parallels': 'BlockdevOptionsGenericFormat', 2861 'qcow2': 'BlockdevOptionsQcow2', 2862 'qcow': 'BlockdevOptionsGenericCOWFormat', 2863 'qed': 'BlockdevOptionsGenericCOWFormat', 2864 'quorum': 'BlockdevOptionsQuorum', 2865 'raw': 'BlockdevOptionsRaw', 2866# TODO rbd: Wait for structured options 2867 'replication':'BlockdevOptionsReplication', 2868# TODO sheepdog: Wait for structured options 2869 'ssh': 'BlockdevOptionsSsh', 2870 'vdi': 'BlockdevOptionsGenericFormat', 2871 'vhdx': 'BlockdevOptionsGenericFormat', 2872 'vmdk': 'BlockdevOptionsGenericCOWFormat', 2873 'vpc': 'BlockdevOptionsGenericFormat', 2874 'vvfat': 'BlockdevOptionsVVFAT' 2875 } } 2876 2877## 2878# @BlockdevRef: 2879# 2880# Reference to a block device. 2881# 2882# @definition: defines a new block device inline 2883# @reference: references the ID of an existing block device. An 2884# empty string means that no block device should be 2885# referenced. 2886# 2887# Since: 1.7 2888## 2889{ 'alternate': 'BlockdevRef', 2890 'data': { 'definition': 'BlockdevOptions', 2891 'reference': 'str' } } 2892 2893## 2894# @blockdev-add: 2895# 2896# Creates a new block device. If the @id option is given at the top level, a 2897# BlockBackend will be created; otherwise, @node-name is mandatory at the top 2898# level and no BlockBackend will be created. 2899# 2900# For the arguments, see the documentation of BlockdevOptions. 2901# 2902# Note: This command is still a work in progress. It doesn't support all 2903# block drivers among other things. Stay away from it unless you want 2904# to help with its development. 2905# 2906# Since: 1.7 2907# 2908# Example: 2909# 2910# 1. 2911# -> { "execute": "blockdev-add", 2912# "arguments": { 2913# "driver": "qcow2", 2914# "node-name": "test1", 2915# "file": { 2916# "driver": "file", 2917# "filename": "test.qcow2" 2918# } 2919# } 2920# } 2921# <- { "return": {} } 2922# 2923# 2. 2924# -> { "execute": "blockdev-add", 2925# "arguments": { 2926# "driver": "qcow2", 2927# "node-name": "node0", 2928# "discard": "unmap", 2929# "cache": { 2930# "direct": true 2931# }, 2932# "file": { 2933# "driver": "file", 2934# "filename": "/tmp/test.qcow2" 2935# }, 2936# "backing": { 2937# "driver": "raw", 2938# "file": { 2939# "driver": "file", 2940# "filename": "/dev/fdset/4" 2941# } 2942# } 2943# } 2944# } 2945# 2946# <- { "return": {} } 2947# 2948## 2949{ 'command': 'blockdev-add', 'data': 'BlockdevOptions', 'boxed': true } 2950 2951## 2952# @x-blockdev-del: 2953# 2954# Deletes a block device that has been added using blockdev-add. 2955# The command will fail if the node is attached to a device or is 2956# otherwise being used. 2957# 2958# @node-name: Name of the graph node to delete. 2959# 2960# Note: This command is still a work in progress and is considered 2961# experimental. Stay away from it unless you want to help with its 2962# development. 2963# 2964# Since: 2.5 2965# 2966# Example: 2967# 2968# -> { "execute": "blockdev-add", 2969# "arguments": { 2970# "driver": "qcow2", 2971# "node-name": "node0", 2972# "file": { 2973# "driver": "file", 2974# "filename": "test.qcow2" 2975# } 2976# } 2977# } 2978# <- { "return": {} } 2979# 2980# -> { "execute": "x-blockdev-del", 2981# "arguments": { "node-name": "node0" } 2982# } 2983# <- { "return": {} } 2984# 2985## 2986{ 'command': 'x-blockdev-del', 'data': { 'node-name': 'str' } } 2987 2988## 2989# @blockdev-open-tray: 2990# 2991# Opens a block device's tray. If there is a block driver state tree inserted as 2992# a medium, it will become inaccessible to the guest (but it will remain 2993# associated to the block device, so closing the tray will make it accessible 2994# again). 2995# 2996# If the tray was already open before, this will be a no-op. 2997# 2998# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in 2999# which no such event will be generated, these include: 3000# - if the guest has locked the tray, @force is false and the guest does not 3001# respond to the eject request 3002# - if the BlockBackend denoted by @device does not have a guest device attached 3003# to it 3004# - if the guest device does not have an actual tray 3005# 3006# @device: #optional Block device name (deprecated, use @id instead) 3007# 3008# @id: #optional The name or QOM path of the guest device (since: 2.8) 3009# 3010# @force: #optional if false (the default), an eject request will be sent to 3011# the guest if it has locked the tray (and the tray will not be opened 3012# immediately); if true, the tray will be opened regardless of whether 3013# it is locked 3014# 3015# Since: 2.5 3016# 3017# Example: 3018# 3019# -> { "execute": "blockdev-open-tray", 3020# "arguments": { "id": "ide0-1-0" } } 3021# 3022# <- { "timestamp": { "seconds": 1418751016, 3023# "microseconds": 716996 }, 3024# "event": "DEVICE_TRAY_MOVED", 3025# "data": { "device": "ide1-cd0", 3026# "id": "ide0-1-0", 3027# "tray-open": true } } 3028# 3029# <- { "return": {} } 3030# 3031## 3032{ 'command': 'blockdev-open-tray', 3033 'data': { '*device': 'str', 3034 '*id': 'str', 3035 '*force': 'bool' } } 3036 3037## 3038# @blockdev-close-tray: 3039# 3040# Closes a block device's tray. If there is a block driver state tree associated 3041# with the block device (which is currently ejected), that tree will be loaded 3042# as the medium. 3043# 3044# If the tray was already closed before, this will be a no-op. 3045# 3046# @device: #optional Block device name (deprecated, use @id instead) 3047# 3048# @id: #optional The name or QOM path of the guest device (since: 2.8) 3049# 3050# Since: 2.5 3051# 3052# Example: 3053# 3054# -> { "execute": "blockdev-close-tray", 3055# "arguments": { "id": "ide0-1-0" } } 3056# 3057# <- { "timestamp": { "seconds": 1418751345, 3058# "microseconds": 272147 }, 3059# "event": "DEVICE_TRAY_MOVED", 3060# "data": { "device": "ide1-cd0", 3061# "id": "ide0-1-0", 3062# "tray-open": false } } 3063# 3064# <- { "return": {} } 3065# 3066## 3067{ 'command': 'blockdev-close-tray', 3068 'data': { '*device': 'str', 3069 '*id': 'str' } } 3070 3071## 3072# @x-blockdev-remove-medium: 3073# 3074# Removes a medium (a block driver state tree) from a block device. That block 3075# device's tray must currently be open (unless there is no attached guest 3076# device). 3077# 3078# If the tray is open and there is no medium inserted, this will be a no-op. 3079# 3080# @device: #optional Block device name (deprecated, use @id instead) 3081# 3082# @id: #optional The name or QOM path of the guest device (since: 2.8) 3083# 3084# Note: This command is still a work in progress and is considered experimental. 3085# Stay away from it unless you want to help with its development. 3086# 3087# Since: 2.5 3088# 3089# Example: 3090# 3091# -> { "execute": "x-blockdev-remove-medium", 3092# "arguments": { "id": "ide0-1-0" } } 3093# 3094# <- { "error": { "class": "GenericError", 3095# "desc": "Tray of device 'ide0-1-0' is not open" } } 3096# 3097# -> { "execute": "blockdev-open-tray", 3098# "arguments": { "id": "ide0-1-0" } } 3099# 3100# <- { "timestamp": { "seconds": 1418751627, 3101# "microseconds": 549958 }, 3102# "event": "DEVICE_TRAY_MOVED", 3103# "data": { "device": "ide1-cd0", 3104# "id": "ide0-1-0", 3105# "tray-open": true } } 3106# 3107# <- { "return": {} } 3108# 3109# -> { "execute": "x-blockdev-remove-medium", 3110# "arguments": { "device": "ide0-1-0" } } 3111# 3112# <- { "return": {} } 3113# 3114## 3115{ 'command': 'x-blockdev-remove-medium', 3116 'data': { '*device': 'str', 3117 '*id': 'str' } } 3118 3119## 3120# @x-blockdev-insert-medium: 3121# 3122# Inserts a medium (a block driver state tree) into a block device. That block 3123# device's tray must currently be open (unless there is no attached guest 3124# device) and there must be no medium inserted already. 3125# 3126# @device: #optional Block device name (deprecated, use @id instead) 3127# 3128# @id: #optional The name or QOM path of the guest device (since: 2.8) 3129# 3130# @node-name: name of a node in the block driver state graph 3131# 3132# Note: This command is still a work in progress and is considered experimental. 3133# Stay away from it unless you want to help with its development. 3134# 3135# Since: 2.5 3136# 3137# Example: 3138# 3139# -> { "execute": "blockdev-add", 3140# "arguments": { 3141# "options": { "node-name": "node0", 3142# "driver": "raw", 3143# "file": { "driver": "file", 3144# "filename": "fedora.iso" } } } } 3145# <- { "return": {} } 3146# 3147# -> { "execute": "x-blockdev-insert-medium", 3148# "arguments": { "id": "ide0-1-0", 3149# "node-name": "node0" } } 3150# 3151# <- { "return": {} } 3152# 3153## 3154{ 'command': 'x-blockdev-insert-medium', 3155 'data': { '*device': 'str', 3156 '*id': 'str', 3157 'node-name': 'str'} } 3158 3159 3160## 3161# @BlockdevChangeReadOnlyMode: 3162# 3163# Specifies the new read-only mode of a block device subject to the 3164# @blockdev-change-medium command. 3165# 3166# @retain: Retains the current read-only mode 3167# 3168# @read-only: Makes the device read-only 3169# 3170# @read-write: Makes the device writable 3171# 3172# Since: 2.3 3173# 3174## 3175{ 'enum': 'BlockdevChangeReadOnlyMode', 3176 'data': ['retain', 'read-only', 'read-write'] } 3177 3178 3179## 3180# @blockdev-change-medium: 3181# 3182# Changes the medium inserted into a block device by ejecting the current medium 3183# and loading a new image file which is inserted as the new medium (this command 3184# combines blockdev-open-tray, x-blockdev-remove-medium, 3185# x-blockdev-insert-medium and blockdev-close-tray). 3186# 3187# @device: #optional Block device name (deprecated, use @id instead) 3188# 3189# @id: #optional The name or QOM path of the guest device 3190# (since: 2.8) 3191# 3192# @filename: filename of the new image to be loaded 3193# 3194# @format: #optional format to open the new image with (defaults to 3195# the probed format) 3196# 3197# @read-only-mode: #optional change the read-only mode of the device; defaults 3198# to 'retain' 3199# 3200# Since: 2.5 3201# 3202# Examples: 3203# 3204# 1. Change a removable medium 3205# 3206# -> { "execute": "blockdev-change-medium", 3207# "arguments": { "id": "ide0-1-0", 3208# "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", 3209# "format": "raw" } } 3210# <- { "return": {} } 3211# 3212# 2. Load a read-only medium into a writable drive 3213# 3214# -> { "execute": "blockdev-change-medium", 3215# "arguments": { "id": "floppyA", 3216# "filename": "/srv/images/ro.img", 3217# "format": "raw", 3218# "read-only-mode": "retain" } } 3219# 3220# <- { "error": 3221# { "class": "GenericError", 3222# "desc": "Could not open '/srv/images/ro.img': Permission denied" } } 3223# 3224# -> { "execute": "blockdev-change-medium", 3225# "arguments": { "id": "floppyA", 3226# "filename": "/srv/images/ro.img", 3227# "format": "raw", 3228# "read-only-mode": "read-only" } } 3229# 3230# <- { "return": {} } 3231# 3232## 3233{ 'command': 'blockdev-change-medium', 3234 'data': { '*device': 'str', 3235 '*id': 'str', 3236 'filename': 'str', 3237 '*format': 'str', 3238 '*read-only-mode': 'BlockdevChangeReadOnlyMode' } } 3239 3240 3241## 3242# @BlockErrorAction: 3243# 3244# An enumeration of action that has been taken when a DISK I/O occurs 3245# 3246# @ignore: error has been ignored 3247# 3248# @report: error has been reported to the device 3249# 3250# @stop: error caused VM to be stopped 3251# 3252# Since: 2.1 3253## 3254{ 'enum': 'BlockErrorAction', 3255 'data': [ 'ignore', 'report', 'stop' ] } 3256 3257 3258## 3259# @BLOCK_IMAGE_CORRUPTED: 3260# 3261# Emitted when a disk image is being marked corrupt. The image can be 3262# identified by its device or node name. The 'device' field is always 3263# present for compatibility reasons, but it can be empty ("") if the 3264# image does not have a device name associated. 3265# 3266# @device: device name. This is always present for compatibility 3267# reasons, but it can be empty ("") if the image does not 3268# have a device name associated. 3269# 3270# @node-name: #optional node name (Since: 2.4) 3271# 3272# @msg: informative message for human consumption, such as the kind of 3273# corruption being detected. It should not be parsed by machine as it is 3274# not guaranteed to be stable 3275# 3276# @offset: #optional if the corruption resulted from an image access, this is 3277# the host's access offset into the image 3278# 3279# @size: #optional if the corruption resulted from an image access, this is 3280# the access size 3281# 3282# @fatal: if set, the image is marked corrupt and therefore unusable after this 3283# event and must be repaired (Since 2.2; before, every 3284# BLOCK_IMAGE_CORRUPTED event was fatal) 3285# 3286# Note: If action is "stop", a STOP event will eventually follow the 3287# BLOCK_IO_ERROR event. 3288# 3289# Example: 3290# 3291# <- { "event": "BLOCK_IMAGE_CORRUPTED", 3292# "data": { "device": "ide0-hd0", "node-name": "node0", 3293# "msg": "Prevented active L1 table overwrite", "offset": 196608, 3294# "size": 65536 }, 3295# "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } 3296# 3297# Since: 1.7 3298## 3299{ 'event': 'BLOCK_IMAGE_CORRUPTED', 3300 'data': { 'device' : 'str', 3301 '*node-name' : 'str', 3302 'msg' : 'str', 3303 '*offset' : 'int', 3304 '*size' : 'int', 3305 'fatal' : 'bool' } } 3306 3307## 3308# @BLOCK_IO_ERROR: 3309# 3310# Emitted when a disk I/O error occurs 3311# 3312# @device: device name. This is always present for compatibility 3313# reasons, but it can be empty ("") if the image does not 3314# have a device name associated. 3315# 3316# @node-name: node name. Note that errors may be reported for the root node 3317# that is directly attached to a guest device rather than for the 3318# node where the error occurred. (Since: 2.8) 3319# 3320# @operation: I/O operation 3321# 3322# @action: action that has been taken 3323# 3324# @nospace: #optional true if I/O error was caused due to a no-space 3325# condition. This key is only present if query-block's 3326# io-status is present, please see query-block documentation 3327# for more information (since: 2.2) 3328# 3329# @reason: human readable string describing the error cause. 3330# (This field is a debugging aid for humans, it should not 3331# be parsed by applications) (since: 2.2) 3332# 3333# Note: If action is "stop", a STOP event will eventually follow the 3334# BLOCK_IO_ERROR event 3335# 3336# Since: 0.13.0 3337# 3338# Example: 3339# 3340# <- { "event": "BLOCK_IO_ERROR", 3341# "data": { "device": "ide0-hd1", 3342# "node-name": "#block212", 3343# "operation": "write", 3344# "action": "stop" }, 3345# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 3346# 3347## 3348{ 'event': 'BLOCK_IO_ERROR', 3349 'data': { 'device': 'str', 'node-name': 'str', 'operation': 'IoOperationType', 3350 'action': 'BlockErrorAction', '*nospace': 'bool', 3351 'reason': 'str' } } 3352 3353## 3354# @BLOCK_JOB_COMPLETED: 3355# 3356# Emitted when a block job has completed 3357# 3358# @type: job type 3359# 3360# @device: The job identifier. Originally the device name but other 3361# values are allowed since QEMU 2.7 3362# 3363# @len: maximum progress value 3364# 3365# @offset: current progress value. On success this is equal to len. 3366# On failure this is less than len 3367# 3368# @speed: rate limit, bytes per second 3369# 3370# @error: #optional error message. Only present on failure. This field 3371# contains a human-readable error message. There are no semantics 3372# other than that streaming has failed and clients should not try to 3373# interpret the error string 3374# 3375# Since: 1.1 3376# 3377# Example: 3378# 3379# <- { "event": "BLOCK_JOB_COMPLETED", 3380# "data": { "type": "stream", "device": "virtio-disk0", 3381# "len": 10737418240, "offset": 10737418240, 3382# "speed": 0 }, 3383# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 3384# 3385## 3386{ 'event': 'BLOCK_JOB_COMPLETED', 3387 'data': { 'type' : 'BlockJobType', 3388 'device': 'str', 3389 'len' : 'int', 3390 'offset': 'int', 3391 'speed' : 'int', 3392 '*error': 'str' } } 3393 3394## 3395# @BLOCK_JOB_CANCELLED: 3396# 3397# Emitted when a block job has been cancelled 3398# 3399# @type: job type 3400# 3401# @device: The job identifier. Originally the device name but other 3402# values are allowed since QEMU 2.7 3403# 3404# @len: maximum progress value 3405# 3406# @offset: current progress value. On success this is equal to len. 3407# On failure this is less than len 3408# 3409# @speed: rate limit, bytes per second 3410# 3411# Since: 1.1 3412# 3413# Example: 3414# 3415# <- { "event": "BLOCK_JOB_CANCELLED", 3416# "data": { "type": "stream", "device": "virtio-disk0", 3417# "len": 10737418240, "offset": 134217728, 3418# "speed": 0 }, 3419# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 3420# 3421## 3422{ 'event': 'BLOCK_JOB_CANCELLED', 3423 'data': { 'type' : 'BlockJobType', 3424 'device': 'str', 3425 'len' : 'int', 3426 'offset': 'int', 3427 'speed' : 'int' } } 3428 3429## 3430# @BLOCK_JOB_ERROR: 3431# 3432# Emitted when a block job encounters an error 3433# 3434# @device: The job identifier. Originally the device name but other 3435# values are allowed since QEMU 2.7 3436# 3437# @operation: I/O operation 3438# 3439# @action: action that has been taken 3440# 3441# Since: 1.3 3442# 3443# Example: 3444# 3445# <- { "event": "BLOCK_JOB_ERROR", 3446# "data": { "device": "ide0-hd1", 3447# "operation": "write", 3448# "action": "stop" }, 3449# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 3450# 3451## 3452{ 'event': 'BLOCK_JOB_ERROR', 3453 'data': { 'device' : 'str', 3454 'operation': 'IoOperationType', 3455 'action' : 'BlockErrorAction' } } 3456 3457## 3458# @BLOCK_JOB_READY: 3459# 3460# Emitted when a block job is ready to complete 3461# 3462# @type: job type 3463# 3464# @device: The job identifier. Originally the device name but other 3465# values are allowed since QEMU 2.7 3466# 3467# @len: maximum progress value 3468# 3469# @offset: current progress value. On success this is equal to len. 3470# On failure this is less than len 3471# 3472# @speed: rate limit, bytes per second 3473# 3474# Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR 3475# event 3476# 3477# Since: 1.3 3478# 3479# Example: 3480# 3481# <- { "event": "BLOCK_JOB_READY", 3482# "data": { "device": "drive0", "type": "mirror", "speed": 0, 3483# "len": 2097152, "offset": 2097152 } 3484# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 3485# 3486## 3487{ 'event': 'BLOCK_JOB_READY', 3488 'data': { 'type' : 'BlockJobType', 3489 'device': 'str', 3490 'len' : 'int', 3491 'offset': 'int', 3492 'speed' : 'int' } } 3493 3494## 3495# @PreallocMode: 3496# 3497# Preallocation mode of QEMU image file 3498# 3499# @off: no preallocation 3500# @metadata: preallocate only for metadata 3501# @falloc: like @full preallocation but allocate disk space by 3502# posix_fallocate() rather than writing zeros. 3503# @full: preallocate all data by writing zeros to device to ensure disk 3504# space is really available. @full preallocation also sets up 3505# metadata correctly. 3506# 3507# Since: 2.2 3508## 3509{ 'enum': 'PreallocMode', 3510 'data': [ 'off', 'metadata', 'falloc', 'full' ] } 3511 3512## 3513# @BLOCK_WRITE_THRESHOLD: 3514# 3515# Emitted when writes on block device reaches or exceeds the 3516# configured write threshold. For thin-provisioned devices, this 3517# means the device should be extended to avoid pausing for 3518# disk exhaustion. 3519# The event is one shot. Once triggered, it needs to be 3520# re-registered with another block-set-threshold command. 3521# 3522# @node-name: graph node name on which the threshold was exceeded. 3523# 3524# @amount-exceeded: amount of data which exceeded the threshold, in bytes. 3525# 3526# @write-threshold: last configured threshold, in bytes. 3527# 3528# Since: 2.3 3529## 3530{ 'event': 'BLOCK_WRITE_THRESHOLD', 3531 'data': { 'node-name': 'str', 3532 'amount-exceeded': 'uint64', 3533 'write-threshold': 'uint64' } } 3534 3535## 3536# @block-set-write-threshold: 3537# 3538# Change the write threshold for a block drive. An event will be 3539# delivered if a write to this block drive crosses the configured 3540# threshold. The threshold is an offset, thus must be 3541# non-negative. Default is no write threshold. Setting the threshold 3542# to zero disables it. 3543# 3544# This is useful to transparently resize thin-provisioned drives without 3545# the guest OS noticing. 3546# 3547# @node-name: graph node name on which the threshold must be set. 3548# 3549# @write-threshold: configured threshold for the block device, bytes. 3550# Use 0 to disable the threshold. 3551# 3552# Since: 2.3 3553# 3554# Example: 3555# 3556# -> { "execute": "block-set-write-threshold", 3557# "arguments": { "node-name": "mydev", 3558# "write-threshold": 17179869184 } } 3559# <- { "return": {} } 3560# 3561## 3562{ 'command': 'block-set-write-threshold', 3563 'data': { 'node-name': 'str', 'write-threshold': 'uint64' } } 3564 3565## 3566# @x-blockdev-change: 3567# 3568# Dynamically reconfigure the block driver state graph. It can be used 3569# to add, remove, insert or replace a graph node. Currently only the 3570# Quorum driver implements this feature to add or remove its child. This 3571# is useful to fix a broken quorum child. 3572# 3573# If @node is specified, it will be inserted under @parent. @child 3574# may not be specified in this case. If both @parent and @child are 3575# specified but @node is not, @child will be detached from @parent. 3576# 3577# @parent: the id or name of the parent node. 3578# 3579# @child: #optional the name of a child under the given parent node. 3580# 3581# @node: #optional the name of the node that will be added. 3582# 3583# Note: this command is experimental, and its API is not stable. It 3584# does not support all kinds of operations, all kinds of children, nor 3585# all block drivers. 3586# 3587# Warning: The data in a new quorum child MUST be consistent with that of 3588# the rest of the array. 3589# 3590# Since: 2.7 3591# 3592# Example: 3593# 3594# 1. Add a new node to a quorum 3595# -> { "execute": "blockdev-add", 3596# "arguments": { 3597# "options": { "driver": "raw", 3598# "node-name": "new_node", 3599# "file": { "driver": "file", 3600# "filename": "test.raw" } } } } 3601# <- { "return": {} } 3602# -> { "execute": "x-blockdev-change", 3603# "arguments": { "parent": "disk1", 3604# "node": "new_node" } } 3605# <- { "return": {} } 3606# 3607# 2. Delete a quorum's node 3608# -> { "execute": "x-blockdev-change", 3609# "arguments": { "parent": "disk1", 3610# "child": "children.1" } } 3611# <- { "return": {} } 3612# 3613## 3614{ 'command': 'x-blockdev-change', 3615 'data' : { 'parent': 'str', 3616 '*child': 'str', 3617 '*node': 'str' } } 3618