virtio-scsi: work around bug in old BIOSes
[qemu.git] / qapi / block-core.json
1 # -*- Mode: Python -*-
2 #
3 # QAPI block core definitions (vm unrelated)
4
5 # QAPI common definitions
6 { 'include': 'common.json' }
7
8 ##
9 # @SnapshotInfo
10 #
11 # @id: unique snapshot id
12 #
13 # @name: user chosen name
14 #
15 # @vm-state-size: size of the VM state
16 #
17 # @date-sec: UTC date of the snapshot in seconds
18 #
19 # @date-nsec: fractional part in nano seconds to be used with date-sec
20 #
21 # @vm-clock-sec: VM clock relative to boot in seconds
22 #
23 # @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec
24 #
25 # Since: 1.3
26 #
27 ##
28
29 { 'type': 'SnapshotInfo',
30   'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int',
31             'date-sec': 'int', 'date-nsec': 'int',
32             'vm-clock-sec': 'int', 'vm-clock-nsec': 'int' } }
33
34 ##
35 # @ImageInfoSpecificQCow2:
36 #
37 # @compat: compatibility level
38 #
39 # @lazy-refcounts: #optional on or off; only valid for compat >= 1.1
40 #
41 # @corrupt: #optional true if the image has been marked corrupt; only valid for
42 #           compat >= 1.1 (since 2.2)
43 #
44 # Since: 1.7
45 ##
46 { 'type': 'ImageInfoSpecificQCow2',
47   'data': {
48       'compat': 'str',
49       '*lazy-refcounts': 'bool',
50       '*corrupt': 'bool'
51   } }
52
53 ##
54 # @ImageInfoSpecificVmdk:
55 #
56 # @create-type: The create type of VMDK image
57 #
58 # @cid: Content id of image
59 #
60 # @parent-cid: Parent VMDK image's cid
61 #
62 # @extents: List of extent files
63 #
64 # Since: 1.7
65 ##
66 { 'type': 'ImageInfoSpecificVmdk',
67   'data': {
68       'create-type': 'str',
69       'cid': 'int',
70       'parent-cid': 'int',
71       'extents': ['ImageInfo']
72   } }
73
74 ##
75 # @ImageInfoSpecific:
76 #
77 # A discriminated record of image format specific information structures.
78 #
79 # Since: 1.7
80 ##
81
82 { 'union': 'ImageInfoSpecific',
83   'data': {
84       'qcow2': 'ImageInfoSpecificQCow2',
85       'vmdk': 'ImageInfoSpecificVmdk'
86   } }
87
88 ##
89 # @ImageInfo:
90 #
91 # Information about a QEMU image file
92 #
93 # @filename: name of the image file
94 #
95 # @format: format of the image file
96 #
97 # @virtual-size: maximum capacity in bytes of the image
98 #
99 # @actual-size: #optional actual size on disk in bytes of the image
100 #
101 # @dirty-flag: #optional true if image is not cleanly closed
102 #
103 # @cluster-size: #optional size of a cluster in bytes
104 #
105 # @encrypted: #optional true if the image is encrypted
106 #
107 # @compressed: #optional true if the image is compressed (Since 1.7)
108 #
109 # @backing-filename: #optional name of the backing file
110 #
111 # @full-backing-filename: #optional full path of the backing file
112 #
113 # @backing-filename-format: #optional the format of the backing file
114 #
115 # @snapshots: #optional list of VM snapshots
116 #
117 # @backing-image: #optional info of the backing image (since 1.6)
118 #
119 # @format-specific: #optional structure supplying additional format-specific
120 # information (since 1.7)
121 #
122 # @nocow: #optional info of whether NOCOW flag is set or not. (since 2.2)
123 #
124 # Since: 1.3
125 #
126 ##
127
128 { 'type': 'ImageInfo',
129   'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool',
130            '*actual-size': 'int', 'virtual-size': 'int',
131            '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool',
132            '*backing-filename': 'str', '*full-backing-filename': 'str',
133            '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'],
134            '*backing-image': 'ImageInfo',
135            '*format-specific': 'ImageInfoSpecific',
136            '*nocow': 'bool' } }
137
138 ##
139 # @ImageCheck:
140 #
141 # Information about a QEMU image file check
142 #
143 # @filename: name of the image file checked
144 #
145 # @format: format of the image file checked
146 #
147 # @check-errors: number of unexpected errors occurred during check
148 #
149 # @image-end-offset: #optional offset (in bytes) where the image ends, this
150 #                    field is present if the driver for the image format
151 #                    supports it
152 #
153 # @corruptions: #optional number of corruptions found during the check if any
154 #
155 # @leaks: #optional number of leaks found during the check if any
156 #
157 # @corruptions-fixed: #optional number of corruptions fixed during the check
158 #                     if any
159 #
160 # @leaks-fixed: #optional number of leaks fixed during the check if any
161 #
162 # @total-clusters: #optional total number of clusters, this field is present
163 #                  if the driver for the image format supports it
164 #
165 # @allocated-clusters: #optional total number of allocated clusters, this
166 #                      field is present if the driver for the image format
167 #                      supports it
168 #
169 # @fragmented-clusters: #optional total number of fragmented clusters, this
170 #                       field is present if the driver for the image format
171 #                       supports it
172 #
173 # @compressed-clusters: #optional total number of compressed clusters, this
174 #                       field is present if the driver for the image format
175 #                       supports it
176 #
177 # Since: 1.4
178 #
179 ##
180
181 { 'type': 'ImageCheck',
182   'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int',
183            '*image-end-offset': 'int', '*corruptions': 'int', '*leaks': 'int',
184            '*corruptions-fixed': 'int', '*leaks-fixed': 'int',
185            '*total-clusters': 'int', '*allocated-clusters': 'int',
186            '*fragmented-clusters': 'int', '*compressed-clusters': 'int' } }
187
188 ##
189 # @BlockDeviceInfo:
190 #
191 # Information about the backing device for a block device.
192 #
193 # @file: the filename of the backing device
194 #
195 # @node-name: #optional the name of the block driver node (Since 2.0)
196 #
197 # @ro: true if the backing device was open read-only
198 #
199 # @drv: the name of the block format used to open the backing device. As of
200 #       0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
201 #       'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
202 #       'host_floppy', 'http', 'https', 'nbd', 'parallels', 'qcow',
203 #       'qcow2', 'raw', 'tftp', 'vdi', 'vmdk', 'vpc', 'vvfat'
204 #       2.2: 'archipelago' added, 'cow' dropped
205 #
206 # @backing_file: #optional the name of the backing file (for copy-on-write)
207 #
208 # @backing_file_depth: number of files in the backing file chain (since: 1.2)
209 #
210 # @encrypted: true if the backing device is encrypted
211 #
212 # @encryption_key_missing: true if the backing device is encrypted but an
213 #                          valid encryption key is missing
214 #
215 # @detect_zeroes: detect and optimize zero writes (Since 2.1)
216 #
217 # @bps: total throughput limit in bytes per second is specified
218 #
219 # @bps_rd: read throughput limit in bytes per second is specified
220 #
221 # @bps_wr: write throughput limit in bytes per second is specified
222 #
223 # @iops: total I/O operations per second is specified
224 #
225 # @iops_rd: read I/O operations per second is specified
226 #
227 # @iops_wr: write I/O operations per second is specified
228 #
229 # @image: the info of image used (since: 1.6)
230 #
231 # @bps_max: #optional total max in bytes (Since 1.7)
232 #
233 # @bps_rd_max: #optional read max in bytes (Since 1.7)
234 #
235 # @bps_wr_max: #optional write max in bytes (Since 1.7)
236 #
237 # @iops_max: #optional total I/O operations max (Since 1.7)
238 #
239 # @iops_rd_max: #optional read I/O operations max (Since 1.7)
240 #
241 # @iops_wr_max: #optional write I/O operations max (Since 1.7)
242 #
243 # @iops_size: #optional an I/O size in bytes (Since 1.7)
244 #
245 # Since: 0.14.0
246 #
247 ##
248 { 'type': 'BlockDeviceInfo',
249   'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str',
250             '*backing_file': 'str', 'backing_file_depth': 'int',
251             'encrypted': 'bool', 'encryption_key_missing': 'bool',
252             'detect_zeroes': 'BlockdevDetectZeroesOptions',
253             'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
254             'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
255             'image': 'ImageInfo',
256             '*bps_max': 'int', '*bps_rd_max': 'int',
257             '*bps_wr_max': 'int', '*iops_max': 'int',
258             '*iops_rd_max': 'int', '*iops_wr_max': 'int',
259             '*iops_size': 'int' } }
260
261 ##
262 # @BlockDeviceIoStatus:
263 #
264 # An enumeration of block device I/O status.
265 #
266 # @ok: The last I/O operation has succeeded
267 #
268 # @failed: The last I/O operation has failed
269 #
270 # @nospace: The last I/O operation has failed due to a no-space condition
271 #
272 # Since: 1.0
273 ##
274 { 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
275
276 ##
277 # @BlockDeviceMapEntry:
278 #
279 # Entry in the metadata map of the device (returned by "qemu-img map")
280 #
281 # @start: Offset in the image of the first byte described by this entry
282 #         (in bytes)
283 #
284 # @length: Length of the range described by this entry (in bytes)
285 #
286 # @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.)
287 #         before reaching one for which the range is allocated.  The value is
288 #         in the range 0 to the depth of the image chain - 1.
289 #
290 # @zero: the sectors in this range read as zeros
291 #
292 # @data: reading the image will actually read data from a file (in particular,
293 #        if @offset is present this means that the sectors are not simply
294 #        preallocated, but contain actual data in raw format)
295 #
296 # @offset: if present, the image file stores the data for this range in
297 #          raw format at the given offset.
298 #
299 # Since 1.7
300 ##
301 { 'type': 'BlockDeviceMapEntry',
302   'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool',
303             'data': 'bool', '*offset': 'int' } }
304
305 ##
306 # @BlockDirtyInfo:
307 #
308 # Block dirty bitmap information.
309 #
310 # @count: number of dirty bytes according to the dirty bitmap
311 #
312 # @granularity: granularity of the dirty bitmap in bytes (since 1.4)
313 #
314 # Since: 1.3
315 ##
316 { 'type': 'BlockDirtyInfo',
317   'data': {'count': 'int', 'granularity': 'int'} }
318
319 ##
320 # @BlockInfo:
321 #
322 # Block device information.  This structure describes a virtual device and
323 # the backing device associated with it.
324 #
325 # @device: The device name associated with the virtual device.
326 #
327 # @type: This field is returned only for compatibility reasons, it should
328 #        not be used (always returns 'unknown')
329 #
330 # @removable: True if the device supports removable media.
331 #
332 # @locked: True if the guest has locked this device from having its media
333 #          removed
334 #
335 # @tray_open: #optional True if the device has a tray and it is open
336 #             (only present if removable is true)
337 #
338 # @dirty-bitmaps: #optional dirty bitmaps information (only present if the
339 #                 driver has one or more dirty bitmaps) (Since 2.0)
340 #
341 # @io-status: #optional @BlockDeviceIoStatus. Only present if the device
342 #             supports it and the VM is configured to stop on errors
343 #             (supported device models: virtio-blk, ide, scsi-disk)
344 #
345 # @inserted: #optional @BlockDeviceInfo describing the device if media is
346 #            present
347 #
348 # Since:  0.14.0
349 ##
350 { 'type': 'BlockInfo',
351   'data': {'device': 'str', 'type': 'str', 'removable': 'bool',
352            'locked': 'bool', '*inserted': 'BlockDeviceInfo',
353            '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus',
354            '*dirty-bitmaps': ['BlockDirtyInfo'] } }
355
356 ##
357 # @query-block:
358 #
359 # Get a list of BlockInfo for all virtual block devices.
360 #
361 # Returns: a list of @BlockInfo describing each virtual block device
362 #
363 # Since: 0.14.0
364 ##
365 { 'command': 'query-block', 'returns': ['BlockInfo'] }
366
367 ##
368 # @BlockDeviceStats:
369 #
370 # Statistics of a virtual block device or a block backing device.
371 #
372 # @rd_bytes:      The number of bytes read by the device.
373 #
374 # @wr_bytes:      The number of bytes written by the device.
375 #
376 # @rd_operations: The number of read operations performed by the device.
377 #
378 # @wr_operations: The number of write operations performed by the device.
379 #
380 # @flush_operations: The number of cache flush operations performed by the
381 #                    device (since 0.15.0)
382 #
383 # @flush_total_time_ns: Total time spend on cache flushes in nano-seconds
384 #                       (since 0.15.0).
385 #
386 # @wr_total_time_ns: Total time spend on writes in nano-seconds (since 0.15.0).
387 #
388 # @rd_total_time_ns: Total_time_spend on reads in nano-seconds (since 0.15.0).
389 #
390 # @wr_highest_offset: The offset after the greatest byte written to the
391 #                     device.  The intended use of this information is for
392 #                     growable sparse files (like qcow2) that are used on top
393 #                     of a physical device.
394 #
395 # Since: 0.14.0
396 ##
397 { 'type': 'BlockDeviceStats',
398   'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'rd_operations': 'int',
399            'wr_operations': 'int', 'flush_operations': 'int',
400            'flush_total_time_ns': 'int', 'wr_total_time_ns': 'int',
401            'rd_total_time_ns': 'int', 'wr_highest_offset': 'int' } }
402
403 ##
404 # @BlockStats:
405 #
406 # Statistics of a virtual block device or a block backing device.
407 #
408 # @device: #optional If the stats are for a virtual block device, the name
409 #          corresponding to the virtual block device.
410 #
411 # @stats:  A @BlockDeviceStats for the device.
412 #
413 # @parent: #optional This describes the file block device if it has one.
414 #
415 # @backing: #optional This describes the backing block device if it has one.
416 #           (Since 2.0)
417 #
418 # Since: 0.14.0
419 ##
420 { 'type': 'BlockStats',
421   'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
422            '*parent': 'BlockStats',
423            '*backing': 'BlockStats'} }
424
425 ##
426 # @query-blockstats:
427 #
428 # Query the @BlockStats for all virtual block devices.
429 #
430 # Returns: A list of @BlockStats for each virtual block devices.
431 #
432 # Since: 0.14.0
433 ##
434 { 'command': 'query-blockstats', 'returns': ['BlockStats'] }
435
436 ##
437 # @BlockdevOnError:
438 #
439 # An enumeration of possible behaviors for errors on I/O operations.
440 # The exact meaning depends on whether the I/O was initiated by a guest
441 # or by a block job
442 #
443 # @report: for guest operations, report the error to the guest;
444 #          for jobs, cancel the job
445 #
446 # @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
447 #          or BLOCK_JOB_ERROR)
448 #
449 # @enospc: same as @stop on ENOSPC, same as @report otherwise.
450 #
451 # @stop: for guest operations, stop the virtual machine;
452 #        for jobs, pause the job
453 #
454 # Since: 1.3
455 ##
456 { 'enum': 'BlockdevOnError',
457   'data': ['report', 'ignore', 'enospc', 'stop'] }
458
459 ##
460 # @MirrorSyncMode:
461 #
462 # An enumeration of possible behaviors for the initial synchronization
463 # phase of storage mirroring.
464 #
465 # @top: copies data in the topmost image to the destination
466 #
467 # @full: copies data from all images to the destination
468 #
469 # @none: only copy data written from now on
470 #
471 # Since: 1.3
472 ##
473 { 'enum': 'MirrorSyncMode',
474   'data': ['top', 'full', 'none'] }
475
476 ##
477 # @BlockJobType:
478 #
479 # Type of a block job.
480 #
481 # @commit: block commit job type, see "block-commit"
482 #
483 # @stream: block stream job type, see "block-stream"
484 #
485 # @mirror: drive mirror job type, see "drive-mirror"
486 #
487 # @backup: drive backup job type, see "drive-backup"
488 #
489 # Since: 1.7
490 ##
491 { 'enum': 'BlockJobType',
492   'data': ['commit', 'stream', 'mirror', 'backup'] }
493
494 ##
495 # @BlockJobInfo:
496 #
497 # Information about a long-running block device operation.
498 #
499 # @type: the job type ('stream' for image streaming)
500 #
501 # @device: the block device name
502 #
503 # @len: the maximum progress value
504 #
505 # @busy: false if the job is known to be in a quiescent state, with
506 #        no pending I/O.  Since 1.3.
507 #
508 # @paused: whether the job is paused or, if @busy is true, will
509 #          pause itself as soon as possible.  Since 1.3.
510 #
511 # @offset: the current progress value
512 #
513 # @speed: the rate limit, bytes per second
514 #
515 # @io-status: the status of the job (since 1.3)
516 #
517 # @ready: true if the job may be completed (since 2.2)
518 #
519 # Since: 1.1
520 ##
521 { 'type': 'BlockJobInfo',
522   'data': {'type': 'str', 'device': 'str', 'len': 'int',
523            'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int',
524            'io-status': 'BlockDeviceIoStatus', 'ready': 'bool'} }
525
526 ##
527 # @query-block-jobs:
528 #
529 # Return information about long-running block device operations.
530 #
531 # Returns: a list of @BlockJobInfo for each active block job
532 #
533 # Since: 1.1
534 ##
535 { 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] }
536
537 ##
538 # @block_passwd:
539 #
540 # This command sets the password of a block device that has not been open
541 # with a password and requires one.
542 #
543 # The two cases where this can happen are a block device is created through
544 # QEMU's initial command line or a block device is changed through the legacy
545 # @change interface.
546 #
547 # In the event that the block device is created through the initial command
548 # line, the VM will start in the stopped state regardless of whether '-S' is
549 # used.  The intention is for a management tool to query the block devices to
550 # determine which ones are encrypted, set the passwords with this command, and
551 # then start the guest with the @cont command.
552 #
553 # Either @device or @node-name must be set but not both.
554 #
555 # @device: #optional the name of the block backend device to set the password on
556 #
557 # @node-name: #optional graph node name to set the password on (Since 2.0)
558 #
559 # @password: the password to use for the device
560 #
561 # Returns: nothing on success
562 #          If @device is not a valid block device, DeviceNotFound
563 #          If @device is not encrypted, DeviceNotEncrypted
564 #
565 # Notes:  Not all block formats support encryption and some that do are not
566 #         able to validate that a password is correct.  Disk corruption may
567 #         occur if an invalid password is specified.
568 #
569 # Since: 0.14.0
570 ##
571 { 'command': 'block_passwd', 'data': {'*device': 'str',
572                                       '*node-name': 'str', 'password': 'str'} }
573
574 ##
575 # @block_resize
576 #
577 # Resize a block image while a guest is running.
578 #
579 # Either @device or @node-name must be set but not both.
580 #
581 # @device: #optional the name of the device to get the image resized
582 #
583 # @node-name: #optional graph node name to get the image resized (Since 2.0)
584 #
585 # @size:  new image size in bytes
586 #
587 # Returns: nothing on success
588 #          If @device is not a valid block device, DeviceNotFound
589 #
590 # Since: 0.14.0
591 ##
592 { 'command': 'block_resize', 'data': { '*device': 'str',
593                                        '*node-name': 'str',
594                                        'size': 'int' }}
595
596 ##
597 # @NewImageMode
598 #
599 # An enumeration that tells QEMU how to set the backing file path in
600 # a new image file.
601 #
602 # @existing: QEMU should look for an existing image file.
603 #
604 # @absolute-paths: QEMU should create a new image with absolute paths
605 # for the backing file. If there is no backing file available, the new
606 # image will not be backed either.
607 #
608 # Since: 1.1
609 ##
610 { 'enum': 'NewImageMode',
611   'data': [ 'existing', 'absolute-paths' ] }
612
613 ##
614 # @BlockdevSnapshot
615 #
616 # Either @device or @node-name must be set but not both.
617 #
618 # @device: #optional the name of the device to generate the snapshot from.
619 #
620 # @node-name: #optional graph node name to generate the snapshot from (Since 2.0)
621 #
622 # @snapshot-file: the target of the new image. A new file will be created.
623 #
624 # @snapshot-node-name: #optional the graph node name of the new image (Since 2.0)
625 #
626 # @format: #optional the format of the snapshot image, default is 'qcow2'.
627 #
628 # @mode: #optional whether and how QEMU should create a new image, default is
629 #        'absolute-paths'.
630 ##
631 { 'type': 'BlockdevSnapshot',
632   'data': { '*device': 'str', '*node-name': 'str',
633             'snapshot-file': 'str', '*snapshot-node-name': 'str',
634             '*format': 'str', '*mode': 'NewImageMode' } }
635
636 ##
637 # @DriveBackup
638 #
639 # @device: the name of the device which should be copied.
640 #
641 # @target: the target of the new image. If the file exists, or if it
642 #          is a device, the existing file/device will be used as the new
643 #          destination.  If it does not exist, a new file will be created.
644 #
645 # @format: #optional the format of the new destination, default is to
646 #          probe if @mode is 'existing', else the format of the source
647 #
648 # @sync: what parts of the disk image should be copied to the destination
649 #        (all the disk, only the sectors allocated in the topmost image, or
650 #        only new I/O).
651 #
652 # @mode: #optional whether and how QEMU should create a new image, default is
653 #        'absolute-paths'.
654 #
655 # @speed: #optional the maximum speed, in bytes per second
656 #
657 # @on-source-error: #optional the action to take on an error on the source,
658 #                   default 'report'.  'stop' and 'enospc' can only be used
659 #                   if the block device supports io-status (see BlockInfo).
660 #
661 # @on-target-error: #optional the action to take on an error on the target,
662 #                   default 'report' (no limitations, since this applies to
663 #                   a different block device than @device).
664 #
665 # Note that @on-source-error and @on-target-error only affect background I/O.
666 # If an error occurs during a guest write request, the device's rerror/werror
667 # actions will be used.
668 #
669 # Since: 1.6
670 ##
671 { 'type': 'DriveBackup',
672   'data': { 'device': 'str', 'target': 'str', '*format': 'str',
673             'sync': 'MirrorSyncMode', '*mode': 'NewImageMode',
674             '*speed': 'int',
675             '*on-source-error': 'BlockdevOnError',
676             '*on-target-error': 'BlockdevOnError' } }
677
678 ##
679 # @blockdev-snapshot-sync
680 #
681 # Generates a synchronous snapshot of a block device.
682 #
683 # For the arguments, see the documentation of BlockdevSnapshot.
684 #
685 # Returns: nothing on success
686 #          If @device is not a valid block device, DeviceNotFound
687 #
688 # Since 0.14.0
689 ##
690 { 'command': 'blockdev-snapshot-sync',
691   'data': 'BlockdevSnapshot' }
692
693 ##
694 # @change-backing-file
695 #
696 # Change the backing file in the image file metadata.  This does not
697 # cause QEMU to reopen the image file to reparse the backing filename
698 # (it may, however, perform a reopen to change permissions from
699 # r/o -> r/w -> r/o, if needed). The new backing file string is written
700 # into the image file metadata, and the QEMU internal strings are
701 # updated.
702 #
703 # @image-node-name: The name of the block driver state node of the
704 #                   image to modify.
705 #
706 # @device:          The name of the device that owns image-node-name.
707 #
708 # @backing-file:    The string to write as the backing file.  This
709 #                   string is not validated, so care should be taken
710 #                   when specifying the string or the image chain may
711 #                   not be able to be reopened again.
712 #
713 # Since: 2.1
714 ##
715 { 'command': 'change-backing-file',
716   'data': { 'device': 'str', 'image-node-name': 'str',
717             'backing-file': 'str' } }
718
719 ##
720 # @block-commit
721 #
722 # Live commit of data from overlay image nodes into backing nodes - i.e.,
723 # writes data between 'top' and 'base' into 'base'.
724 #
725 # @device:  the name of the device
726 #
727 # @base:   #optional The file name of the backing image to write data into.
728 #                    If not specified, this is the deepest backing image
729 #
730 # @top:    #optional The file name of the backing image within the image chain,
731 #                    which contains the topmost data to be committed down. If
732 #                    not specified, this is the active layer.
733 #
734 # @backing-file:  #optional The backing file string to write into the overlay
735 #                           image of 'top'.  If 'top' is the active layer,
736 #                           specifying a backing file string is an error. This
737 #                           filename is not validated.
738 #
739 #                           If a pathname string is such that it cannot be
740 #                           resolved by QEMU, that means that subsequent QMP or
741 #                           HMP commands must use node-names for the image in
742 #                           question, as filename lookup methods will fail.
743 #
744 #                           If not specified, QEMU will automatically determine
745 #                           the backing file string to use, or error out if
746 #                           there is no obvious choice. Care should be taken
747 #                           when specifying the string, to specify a valid
748 #                           filename or protocol.
749 #                           (Since 2.1)
750 #
751 #                    If top == base, that is an error.
752 #                    If top == active, the job will not be completed by itself,
753 #                    user needs to complete the job with the block-job-complete
754 #                    command after getting the ready event. (Since 2.0)
755 #
756 #                    If the base image is smaller than top, then the base image
757 #                    will be resized to be the same size as top.  If top is
758 #                    smaller than the base image, the base will not be
759 #                    truncated.  If you want the base image size to match the
760 #                    size of the smaller top, you can safely truncate it
761 #                    yourself once the commit operation successfully completes.
762 #
763 # @speed:  #optional the maximum speed, in bytes per second
764 #
765 # Returns: Nothing on success
766 #          If commit or stream is already active on this device, DeviceInUse
767 #          If @device does not exist, DeviceNotFound
768 #          If image commit is not supported by this device, NotSupported
769 #          If @base or @top is invalid, a generic error is returned
770 #          If @speed is invalid, InvalidParameter
771 #
772 # Since: 1.3
773 #
774 ##
775 { 'command': 'block-commit',
776   'data': { 'device': 'str', '*base': 'str', '*top': 'str',
777             '*backing-file': 'str', '*speed': 'int' } }
778
779 ##
780 # @drive-backup
781 #
782 # Start a point-in-time copy of a block device to a new destination.  The
783 # status of ongoing drive-backup operations can be checked with
784 # query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
785 # The operation can be stopped before it has completed using the
786 # block-job-cancel command.
787 #
788 # For the arguments, see the documentation of DriveBackup.
789 #
790 # Returns: nothing on success
791 #          If @device is not a valid block device, DeviceNotFound
792 #
793 # Since 1.6
794 ##
795 { 'command': 'drive-backup', 'data': 'DriveBackup' }
796
797 ##
798 # @query-named-block-nodes
799 #
800 # Get the named block driver list
801 #
802 # Returns: the list of BlockDeviceInfo
803 #
804 # Since 2.0
805 ##
806 { 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ] }
807
808 ##
809 # @drive-mirror
810 #
811 # Start mirroring a block device's writes to a new destination.
812 #
813 # @device:  the name of the device whose writes should be mirrored.
814 #
815 # @target: the target of the new image. If the file exists, or if it
816 #          is a device, the existing file/device will be used as the new
817 #          destination.  If it does not exist, a new file will be created.
818 #
819 # @format: #optional the format of the new destination, default is to
820 #          probe if @mode is 'existing', else the format of the source
821 #
822 # @node-name: #optional the new block driver state node name in the graph
823 #             (Since 2.1)
824 #
825 # @replaces: #optional with sync=full graph node name to be replaced by the new
826 #            image when a whole image copy is done. This can be used to repair
827 #            broken Quorum files. (Since 2.1)
828 #
829 # @mode: #optional whether and how QEMU should create a new image, default is
830 #        'absolute-paths'.
831 #
832 # @speed:  #optional the maximum speed, in bytes per second
833 #
834 # @sync: what parts of the disk image should be copied to the destination
835 #        (all the disk, only the sectors allocated in the topmost image, or
836 #        only new I/O).
837 #
838 # @granularity: #optional granularity of the dirty bitmap, default is 64K
839 #               if the image format doesn't have clusters, 4K if the clusters
840 #               are smaller than that, else the cluster size.  Must be a
841 #               power of 2 between 512 and 64M (since 1.4).
842 #
843 # @buf-size: #optional maximum amount of data in flight from source to
844 #            target (since 1.4).
845 #
846 # @on-source-error: #optional the action to take on an error on the source,
847 #                   default 'report'.  'stop' and 'enospc' can only be used
848 #                   if the block device supports io-status (see BlockInfo).
849 #
850 # @on-target-error: #optional the action to take on an error on the target,
851 #                   default 'report' (no limitations, since this applies to
852 #                   a different block device than @device).
853 #
854 # Returns: nothing on success
855 #          If @device is not a valid block device, DeviceNotFound
856 #
857 # Since 1.3
858 ##
859 { 'command': 'drive-mirror',
860   'data': { 'device': 'str', 'target': 'str', '*format': 'str',
861             '*node-name': 'str', '*replaces': 'str',
862             'sync': 'MirrorSyncMode', '*mode': 'NewImageMode',
863             '*speed': 'int', '*granularity': 'uint32',
864             '*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
865             '*on-target-error': 'BlockdevOnError' } }
866
867 ##
868 # @block_set_io_throttle:
869 #
870 # Change I/O throttle limits for a block drive.
871 #
872 # @device: The name of the device
873 #
874 # @bps: total throughput limit in bytes per second
875 #
876 # @bps_rd: read throughput limit in bytes per second
877 #
878 # @bps_wr: write throughput limit in bytes per second
879 #
880 # @iops: total I/O operations per second
881 #
882 # @ops_rd: read I/O operations per second
883 #
884 # @iops_wr: write I/O operations per second
885 #
886 # @bps_max: #optional total max in bytes (Since 1.7)
887 #
888 # @bps_rd_max: #optional read max in bytes (Since 1.7)
889 #
890 # @bps_wr_max: #optional write max in bytes (Since 1.7)
891 #
892 # @iops_max: #optional total I/O operations max (Since 1.7)
893 #
894 # @iops_rd_max: #optional read I/O operations max (Since 1.7)
895 #
896 # @iops_wr_max: #optional write I/O operations max (Since 1.7)
897 #
898 # @iops_size: #optional an I/O size in bytes (Since 1.7)
899 #
900 # Returns: Nothing on success
901 #          If @device is not a valid block device, DeviceNotFound
902 #
903 # Since: 1.1
904 ##
905 { 'command': 'block_set_io_throttle',
906   'data': { 'device': 'str', 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
907             'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
908             '*bps_max': 'int', '*bps_rd_max': 'int',
909             '*bps_wr_max': 'int', '*iops_max': 'int',
910             '*iops_rd_max': 'int', '*iops_wr_max': 'int',
911             '*iops_size': 'int' } }
912
913 ##
914 # @block-stream:
915 #
916 # Copy data from a backing file into a block device.
917 #
918 # The block streaming operation is performed in the background until the entire
919 # backing file has been copied.  This command returns immediately once streaming
920 # has started.  The status of ongoing block streaming operations can be checked
921 # with query-block-jobs.  The operation can be stopped before it has completed
922 # using the block-job-cancel command.
923 #
924 # If a base file is specified then sectors are not copied from that base file and
925 # its backing chain.  When streaming completes the image file will have the base
926 # file as its backing file.  This can be used to stream a subset of the backing
927 # file chain instead of flattening the entire image.
928 #
929 # On successful completion the image file is updated to drop the backing file
930 # and the BLOCK_JOB_COMPLETED event is emitted.
931 #
932 # @device: the device name
933 #
934 # @base:   #optional the common backing file name
935 #
936 # @backing-file: #optional The backing file string to write into the active
937 #                          layer. This filename is not validated.
938 #
939 #                          If a pathname string is such that it cannot be
940 #                          resolved by QEMU, that means that subsequent QMP or
941 #                          HMP commands must use node-names for the image in
942 #                          question, as filename lookup methods will fail.
943 #
944 #                          If not specified, QEMU will automatically determine
945 #                          the backing file string to use, or error out if there
946 #                          is no obvious choice.  Care should be taken when
947 #                          specifying the string, to specify a valid filename or
948 #                          protocol.
949 #                          (Since 2.1)
950 #
951 # @speed:  #optional the maximum speed, in bytes per second
952 #
953 # @on-error: #optional the action to take on an error (default report).
954 #            'stop' and 'enospc' can only be used if the block device
955 #            supports io-status (see BlockInfo).  Since 1.3.
956 #
957 # Returns: Nothing on success
958 #          If @device does not exist, DeviceNotFound
959 #
960 # Since: 1.1
961 ##
962 { 'command': 'block-stream',
963   'data': { 'device': 'str', '*base': 'str', '*backing-file': 'str',
964             '*speed': 'int', '*on-error': 'BlockdevOnError' } }
965
966 ##
967 # @block-job-set-speed:
968 #
969 # Set maximum speed for a background block operation.
970 #
971 # This command can only be issued when there is an active block job.
972 #
973 # Throttling can be disabled by setting the speed to 0.
974 #
975 # @device: the device name
976 #
977 # @speed:  the maximum speed, in bytes per second, or 0 for unlimited.
978 #          Defaults to 0.
979 #
980 # Returns: Nothing on success
981 #          If no background operation is active on this device, DeviceNotActive
982 #
983 # Since: 1.1
984 ##
985 { 'command': 'block-job-set-speed',
986   'data': { 'device': 'str', 'speed': 'int' } }
987
988 ##
989 # @block-job-cancel:
990 #
991 # Stop an active background block operation.
992 #
993 # This command returns immediately after marking the active background block
994 # operation for cancellation.  It is an error to call this command if no
995 # operation is in progress.
996 #
997 # The operation will cancel as soon as possible and then emit the
998 # BLOCK_JOB_CANCELLED event.  Before that happens the job is still visible when
999 # enumerated using query-block-jobs.
1000 #
1001 # For streaming, the image file retains its backing file unless the streaming
1002 # operation happens to complete just as it is being cancelled.  A new streaming
1003 # operation can be started at a later time to finish copying all data from the
1004 # backing file.
1005 #
1006 # @device: the device name
1007 #
1008 # @force: #optional whether to allow cancellation of a paused job (default
1009 #         false).  Since 1.3.
1010 #
1011 # Returns: Nothing on success
1012 #          If no background operation is active on this device, DeviceNotActive
1013 #
1014 # Since: 1.1
1015 ##
1016 { 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } }
1017
1018 ##
1019 # @block-job-pause:
1020 #
1021 # Pause an active background block operation.
1022 #
1023 # This command returns immediately after marking the active background block
1024 # operation for pausing.  It is an error to call this command if no
1025 # operation is in progress.  Pausing an already paused job has no cumulative
1026 # effect; a single block-job-resume command will resume the job.
1027 #
1028 # The operation will pause as soon as possible.  No event is emitted when
1029 # the operation is actually paused.  Cancelling a paused job automatically
1030 # resumes it.
1031 #
1032 # @device: the device name
1033 #
1034 # Returns: Nothing on success
1035 #          If no background operation is active on this device, DeviceNotActive
1036 #
1037 # Since: 1.3
1038 ##
1039 { 'command': 'block-job-pause', 'data': { 'device': 'str' } }
1040
1041 ##
1042 # @block-job-resume:
1043 #
1044 # Resume an active background block operation.
1045 #
1046 # This command returns immediately after resuming a paused background block
1047 # operation.  It is an error to call this command if no operation is in
1048 # progress.  Resuming an already running job is not an error.
1049 #
1050 # This command also clears the error status of the job.
1051 #
1052 # @device: the device name
1053 #
1054 # Returns: Nothing on success
1055 #          If no background operation is active on this device, DeviceNotActive
1056 #
1057 # Since: 1.3
1058 ##
1059 { 'command': 'block-job-resume', 'data': { 'device': 'str' } }
1060
1061 ##
1062 # @block-job-complete:
1063 #
1064 # Manually trigger completion of an active background block operation.  This
1065 # is supported for drive mirroring, where it also switches the device to
1066 # write to the target path only.  The ability to complete is signaled with
1067 # a BLOCK_JOB_READY event.
1068 #
1069 # This command completes an active background block operation synchronously.
1070 # The ordering of this command's return with the BLOCK_JOB_COMPLETED event
1071 # is not defined.  Note that if an I/O error occurs during the processing of
1072 # this command: 1) the command itself will fail; 2) the error will be processed
1073 # according to the rerror/werror arguments that were specified when starting
1074 # the operation.
1075 #
1076 # A cancelled or paused job cannot be completed.
1077 #
1078 # @device: the device name
1079 #
1080 # Returns: Nothing on success
1081 #          If no background operation is active on this device, DeviceNotActive
1082 #
1083 # Since: 1.3
1084 ##
1085 { 'command': 'block-job-complete', 'data': { 'device': 'str' } }
1086
1087 ##
1088 # @BlockdevDiscardOptions
1089 #
1090 # Determines how to handle discard requests.
1091 #
1092 # @ignore:      Ignore the request
1093 # @unmap:       Forward as an unmap request
1094 #
1095 # Since: 1.7
1096 ##
1097 { 'enum': 'BlockdevDiscardOptions',
1098   'data': [ 'ignore', 'unmap' ] }
1099
1100 ##
1101 # @BlockdevDetectZeroesOptions
1102 #
1103 # Describes the operation mode for the automatic conversion of plain
1104 # zero writes by the OS to driver specific optimized zero write commands.
1105 #
1106 # @off:      Disabled (default)
1107 # @on:       Enabled
1108 # @unmap:    Enabled and even try to unmap blocks if possible. This requires
1109 #            also that @BlockdevDiscardOptions is set to unmap for this device.
1110 #
1111 # Since: 2.1
1112 ##
1113 { 'enum': 'BlockdevDetectZeroesOptions',
1114   'data': [ 'off', 'on', 'unmap' ] }
1115
1116 ##
1117 # @BlockdevAioOptions
1118 #
1119 # Selects the AIO backend to handle I/O requests
1120 #
1121 # @threads:     Use qemu's thread pool
1122 # @native:      Use native AIO backend (only Linux and Windows)
1123 #
1124 # Since: 1.7
1125 ##
1126 { 'enum': 'BlockdevAioOptions',
1127   'data': [ 'threads', 'native' ] }
1128
1129 ##
1130 # @BlockdevCacheOptions
1131 #
1132 # Includes cache-related options for block devices
1133 #
1134 # @writeback:   #optional enables writeback mode for any caches (default: true)
1135 # @direct:      #optional enables use of O_DIRECT (bypass the host page cache;
1136 #               default: false)
1137 # @no-flush:    #optional ignore any flush requests for the device (default:
1138 #               false)
1139 #
1140 # Since: 1.7
1141 ##
1142 { 'type': 'BlockdevCacheOptions',
1143   'data': { '*writeback': 'bool',
1144             '*direct': 'bool',
1145             '*no-flush': 'bool' } }
1146
1147 ##
1148 # @BlockdevDriver
1149 #
1150 # Drivers that are supported in block device operations.
1151 #
1152 # @host_device, @host_cdrom, @host_floppy: Since 2.1
1153 #
1154 # Since: 2.0
1155 ##
1156 { 'enum': 'BlockdevDriver',
1157   'data': [ 'archipelago', 'blkdebug', 'blkverify', 'bochs', 'cloop',
1158             'dmg', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
1159             'host_floppy', 'http', 'https', 'null-aio', 'null-co', 'parallels',
1160             'qcow', 'qcow2', 'qed', 'quorum', 'raw', 'tftp', 'vdi', 'vhdx',
1161             'vmdk', 'vpc', 'vvfat' ] }
1162
1163 ##
1164 # @BlockdevOptionsBase
1165 #
1166 # Options that are available for all block devices, independent of the block
1167 # driver.
1168 #
1169 # @driver:        block driver name
1170 # @id:            #optional id by which the new block device can be referred to.
1171 #                 This is a required option on the top level of blockdev-add, and
1172 #                 currently not allowed on any other level.
1173 # @node-name:     #optional the name of a block driver state node (Since 2.0)
1174 # @discard:       #optional discard-related options (default: ignore)
1175 # @cache:         #optional cache-related options
1176 # @aio:           #optional AIO backend (default: threads)
1177 # @rerror:        #optional how to handle read errors on the device
1178 #                 (default: report)
1179 # @werror:        #optional how to handle write errors on the device
1180 #                 (default: enospc)
1181 # @read-only:     #optional whether the block device should be read-only
1182 #                 (default: false)
1183 # @detect-zeroes: #optional detect and optimize zero writes (Since 2.1)
1184 #                 (default: off)
1185 #
1186 # Since: 1.7
1187 ##
1188 { 'type': 'BlockdevOptionsBase',
1189   'data': { 'driver': 'BlockdevDriver',
1190             '*id': 'str',
1191             '*node-name': 'str',
1192             '*discard': 'BlockdevDiscardOptions',
1193             '*cache': 'BlockdevCacheOptions',
1194             '*aio': 'BlockdevAioOptions',
1195             '*rerror': 'BlockdevOnError',
1196             '*werror': 'BlockdevOnError',
1197             '*read-only': 'bool',
1198             '*detect-zeroes': 'BlockdevDetectZeroesOptions' } }
1199
1200 ##
1201 # @BlockdevOptionsFile
1202 #
1203 # Driver specific block device options for the file backend and similar
1204 # protocols.
1205 #
1206 # @filename:    path to the image file
1207 #
1208 # Since: 1.7
1209 ##
1210 { 'type': 'BlockdevOptionsFile',
1211   'data': { 'filename': 'str' } }
1212
1213 ##
1214 # @BlockdevOptionsNull
1215 #
1216 # Driver specific block device options for the null backend.
1217 #
1218 # @size:    #optional size of the device in bytes.
1219 #
1220 # Since: 2.2
1221 ##
1222 { 'type': 'BlockdevOptionsNull',
1223   'data': { '*size': 'int' } }
1224
1225 ##
1226 # @BlockdevOptionsVVFAT
1227 #
1228 # Driver specific block device options for the vvfat protocol.
1229 #
1230 # @dir:         directory to be exported as FAT image
1231 # @fat-type:    #optional FAT type: 12, 16 or 32
1232 # @floppy:      #optional whether to export a floppy image (true) or
1233 #               partitioned hard disk (false; default)
1234 # @rw:          #optional whether to allow write operations (default: false)
1235 #
1236 # Since: 1.7
1237 ##
1238 { 'type': 'BlockdevOptionsVVFAT',
1239   'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool',
1240             '*rw': 'bool' } }
1241
1242 ##
1243 # @BlockdevOptionsGenericFormat
1244 #
1245 # Driver specific block device options for image format that have no option
1246 # besides their data source.
1247 #
1248 # @file:        reference to or definition of the data source block device
1249 #
1250 # Since: 1.7
1251 ##
1252 { 'type': 'BlockdevOptionsGenericFormat',
1253   'data': { 'file': 'BlockdevRef' } }
1254
1255 ##
1256 # @BlockdevOptionsGenericCOWFormat
1257 #
1258 # Driver specific block device options for image format that have no option
1259 # besides their data source and an optional backing file.
1260 #
1261 # @backing:     #optional reference to or definition of the backing file block
1262 #               device (if missing, taken from the image file content). It is
1263 #               allowed to pass an empty string here in order to disable the
1264 #               default backing file.
1265 #
1266 # Since: 1.7
1267 ##
1268 { 'type': 'BlockdevOptionsGenericCOWFormat',
1269   'base': 'BlockdevOptionsGenericFormat',
1270   'data': { '*backing': 'BlockdevRef' } }
1271
1272 ##
1273 # @Qcow2OverlapCheckMode
1274 #
1275 # General overlap check modes.
1276 #
1277 # @none:        Do not perform any checks
1278 #
1279 # @constant:    Perform only checks which can be done in constant time and
1280 #               without reading anything from disk
1281 #
1282 # @cached:      Perform only checks which can be done without reading anything
1283 #               from disk
1284 #
1285 # @all:         Perform all available overlap checks
1286 #
1287 # Since: 2.2
1288 ##
1289 { 'enum': 'Qcow2OverlapCheckMode',
1290   'data': [ 'none', 'constant', 'cached', 'all' ] }
1291
1292 ##
1293 # @Qcow2OverlapCheckFlags
1294 #
1295 # Structure of flags for each metadata structure. Setting a field to 'true'
1296 # makes qemu guard that structure against unintended overwriting. The default
1297 # value is chosen according to the template given.
1298 #
1299 # @template: Specifies a template mode which can be adjusted using the other
1300 #            flags, defaults to 'cached'
1301 #
1302 # Since: 2.2
1303 ##
1304 { 'type': 'Qcow2OverlapCheckFlags',
1305   'data': { '*template':       'Qcow2OverlapCheckMode',
1306             '*main-header':    'bool',
1307             '*active-l1':      'bool',
1308             '*active-l2':      'bool',
1309             '*refcount-table': 'bool',
1310             '*refcount-block': 'bool',
1311             '*snapshot-table': 'bool',
1312             '*inactive-l1':    'bool',
1313             '*inactive-l2':    'bool' } }
1314
1315 ##
1316 # @Qcow2OverlapChecks
1317 #
1318 # Specifies which metadata structures should be guarded against unintended
1319 # overwriting.
1320 #
1321 # @flags:   set of flags for separate specification of each metadata structure
1322 #           type
1323 #
1324 # @mode:    named mode which chooses a specific set of flags
1325 #
1326 # Since: 2.2
1327 ##
1328 { 'union': 'Qcow2OverlapChecks',
1329   'discriminator': {},
1330   'data': { 'flags': 'Qcow2OverlapCheckFlags',
1331             'mode':  'Qcow2OverlapCheckMode' } }
1332
1333 ##
1334 # @BlockdevOptionsQcow2
1335 #
1336 # Driver specific block device options for qcow2.
1337 #
1338 # @lazy-refcounts:        #optional whether to enable the lazy refcounts
1339 #                         feature (default is taken from the image file)
1340 #
1341 # @pass-discard-request:  #optional whether discard requests to the qcow2
1342 #                         device should be forwarded to the data source
1343 #
1344 # @pass-discard-snapshot: #optional whether discard requests for the data source
1345 #                         should be issued when a snapshot operation (e.g.
1346 #                         deleting a snapshot) frees clusters in the qcow2 file
1347 #
1348 # @pass-discard-other:    #optional whether discard requests for the data source
1349 #                         should be issued on other occasions where a cluster
1350 #                         gets freed
1351 #
1352 # @overlap-check:         #optional which overlap checks to perform for writes
1353 #                         to the image, defaults to 'cached' (since 2.2)
1354 #
1355 # @cache-size:            #optional the maximum total size of the L2 table and
1356 #                         refcount block caches in bytes (since 2.2)
1357 #
1358 # @l2-cache-size:         #optional the maximum size of the L2 table cache in
1359 #                         bytes (since 2.2)
1360 #
1361 # @refcount-cache-size:   #optional the maximum size of the refcount block cache
1362 #                         in bytes (since 2.2)
1363 #
1364 # Since: 1.7
1365 ##
1366 { 'type': 'BlockdevOptionsQcow2',
1367   'base': 'BlockdevOptionsGenericCOWFormat',
1368   'data': { '*lazy-refcounts': 'bool',
1369             '*pass-discard-request': 'bool',
1370             '*pass-discard-snapshot': 'bool',
1371             '*pass-discard-other': 'bool',
1372             '*overlap-check': 'Qcow2OverlapChecks',
1373             '*cache-size': 'int',
1374             '*l2-cache-size': 'int',
1375             '*refcount-cache-size': 'int' } }
1376
1377
1378 ##
1379 # @BlockdevOptionsArchipelago
1380 #
1381 # Driver specific block device options for Archipelago.
1382 #
1383 # @volume:              Name of the Archipelago volume image
1384 #
1385 # @mport:               #optional The port number on which mapperd is
1386 #                       listening. This is optional
1387 #                       and if not specified, QEMU will make Archipelago
1388 #                       use the default port (1001).
1389 #
1390 # @vport:               #optional The port number on which vlmcd is
1391 #                       listening. This is optional
1392 #                       and if not specified, QEMU will make Archipelago
1393 #                       use the default port (501).
1394 #
1395 # @segment:             #optional The name of the shared memory segment
1396 #                       Archipelago stack is using. This is optional
1397 #                       and if not specified, QEMU will make Archipelago
1398 #                       use the default value, 'archipelago'.
1399 # Since: 2.2
1400 ##
1401 { 'type': 'BlockdevOptionsArchipelago',
1402   'data': { 'volume': 'str',
1403             '*mport': 'int',
1404             '*vport': 'int',
1405             '*segment': 'str' } }
1406
1407
1408 ##
1409 # @BlkdebugEvent
1410 #
1411 # Trigger events supported by blkdebug.
1412 ##
1413 { 'enum': 'BlkdebugEvent',
1414   'data': [ 'l1_update', 'l1_grow.alloc_table', 'l1_grow.write_table',
1415             'l1_grow.activate_table', 'l2_load', 'l2_update',
1416             'l2_update_compressed', 'l2_alloc.cow_read', 'l2_alloc.write',
1417             'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio',
1418             'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read',
1419             'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update',
1420             'refblock_load', 'refblock_update', 'refblock_update_part',
1421             'refblock_alloc', 'refblock_alloc.hookup', 'refblock_alloc.write',
1422             'refblock_alloc.write_blocks', 'refblock_alloc.write_table',
1423             'refblock_alloc.switch_table', 'cluster_alloc',
1424             'cluster_alloc_bytes', 'cluster_free', 'flush_to_os',
1425             'flush_to_disk' ] }
1426
1427 ##
1428 # @BlkdebugInjectErrorOptions
1429 #
1430 # Describes a single error injection for blkdebug.
1431 #
1432 # @event:       trigger event
1433 #
1434 # @state:       #optional the state identifier blkdebug needs to be in to
1435 #               actually trigger the event; defaults to "any"
1436 #
1437 # @errno:       #optional error identifier (errno) to be returned; defaults to
1438 #               EIO
1439 #
1440 # @sector:      #optional specifies the sector index which has to be affected
1441 #               in order to actually trigger the event; defaults to "any
1442 #               sector"
1443 #
1444 # @once:        #optional disables further events after this one has been
1445 #               triggered; defaults to false
1446 #
1447 # @immediately: #optional fail immediately; defaults to false
1448 #
1449 # Since: 2.0
1450 ##
1451 { 'type': 'BlkdebugInjectErrorOptions',
1452   'data': { 'event': 'BlkdebugEvent',
1453             '*state': 'int',
1454             '*errno': 'int',
1455             '*sector': 'int',
1456             '*once': 'bool',
1457             '*immediately': 'bool' } }
1458
1459 ##
1460 # @BlkdebugSetStateOptions
1461 #
1462 # Describes a single state-change event for blkdebug.
1463 #
1464 # @event:       trigger event
1465 #
1466 # @state:       #optional the current state identifier blkdebug needs to be in;
1467 #               defaults to "any"
1468 #
1469 # @new_state:   the state identifier blkdebug is supposed to assume if
1470 #               this event is triggered
1471 #
1472 # Since: 2.0
1473 ##
1474 { 'type': 'BlkdebugSetStateOptions',
1475   'data': { 'event': 'BlkdebugEvent',
1476             '*state': 'int',
1477             'new_state': 'int' } }
1478
1479 ##
1480 # @BlockdevOptionsBlkdebug
1481 #
1482 # Driver specific block device options for blkdebug.
1483 #
1484 # @image:           underlying raw block device (or image file)
1485 #
1486 # @config:          #optional filename of the configuration file
1487 #
1488 # @align:           #optional required alignment for requests in bytes
1489 #
1490 # @inject-error:    #optional array of error injection descriptions
1491 #
1492 # @set-state:       #optional array of state-change descriptions
1493 #
1494 # Since: 2.0
1495 ##
1496 { 'type': 'BlockdevOptionsBlkdebug',
1497   'data': { 'image': 'BlockdevRef',
1498             '*config': 'str',
1499             '*align': 'int',
1500             '*inject-error': ['BlkdebugInjectErrorOptions'],
1501             '*set-state': ['BlkdebugSetStateOptions'] } }
1502
1503 ##
1504 # @BlockdevOptionsBlkverify
1505 #
1506 # Driver specific block device options for blkverify.
1507 #
1508 # @test:    block device to be tested
1509 #
1510 # @raw:     raw image used for verification
1511 #
1512 # Since: 2.0
1513 ##
1514 { 'type': 'BlockdevOptionsBlkverify',
1515   'data': { 'test': 'BlockdevRef',
1516             'raw': 'BlockdevRef' } }
1517
1518 ##
1519 # @QuorumReadPattern
1520 #
1521 # An enumeration of quorum read patterns.
1522 #
1523 # @quorum: read all the children and do a quorum vote on reads
1524 #
1525 # @fifo: read only from the first child that has not failed
1526 #
1527 # Since: 2.2
1528 ##
1529 { 'enum': 'QuorumReadPattern', 'data': [ 'quorum', 'fifo' ] }
1530
1531 ##
1532 # @BlockdevOptionsQuorum
1533 #
1534 # Driver specific block device options for Quorum
1535 #
1536 # @blkverify:      #optional true if the driver must print content mismatch
1537 #                  set to false by default
1538 #
1539 # @children:       the children block devices to use
1540 #
1541 # @vote-threshold: the vote limit under which a read will fail
1542 #
1543 # @rewrite-corrupted: #optional rewrite corrupted data when quorum is reached
1544 #                     (Since 2.1)
1545 #
1546 # @read-pattern: #optional choose read pattern and set to quorum by default
1547 #                (Since 2.2)
1548 #
1549 # Since: 2.0
1550 ##
1551 { 'type': 'BlockdevOptionsQuorum',
1552   'data': { '*blkverify': 'bool',
1553             'children': [ 'BlockdevRef' ],
1554             'vote-threshold': 'int',
1555             '*rewrite-corrupted': 'bool',
1556             '*read-pattern': 'QuorumReadPattern' } }
1557
1558 ##
1559 # @BlockdevOptions
1560 #
1561 # Options for creating a block device.
1562 #
1563 # Since: 1.7
1564 ##
1565 { 'union': 'BlockdevOptions',
1566   'base': 'BlockdevOptionsBase',
1567   'discriminator': 'driver',
1568   'data': {
1569       'archipelago':'BlockdevOptionsArchipelago',
1570       'blkdebug':   'BlockdevOptionsBlkdebug',
1571       'blkverify':  'BlockdevOptionsBlkverify',
1572       'bochs':      'BlockdevOptionsGenericFormat',
1573       'cloop':      'BlockdevOptionsGenericFormat',
1574       'dmg':        'BlockdevOptionsGenericFormat',
1575       'file':       'BlockdevOptionsFile',
1576       'ftp':        'BlockdevOptionsFile',
1577       'ftps':       'BlockdevOptionsFile',
1578 # TODO gluster: Wait for structured options
1579       'host_cdrom': 'BlockdevOptionsFile',
1580       'host_device':'BlockdevOptionsFile',
1581       'host_floppy':'BlockdevOptionsFile',
1582       'http':       'BlockdevOptionsFile',
1583       'https':      'BlockdevOptionsFile',
1584 # TODO iscsi: Wait for structured options
1585 # TODO nbd: Should take InetSocketAddress for 'host'?
1586 # TODO nfs: Wait for structured options
1587       'null-aio':   'BlockdevOptionsNull',
1588       'null-co':    'BlockdevOptionsNull',
1589       'parallels':  'BlockdevOptionsGenericFormat',
1590       'qcow2':      'BlockdevOptionsQcow2',
1591       'qcow':       'BlockdevOptionsGenericCOWFormat',
1592       'qed':        'BlockdevOptionsGenericCOWFormat',
1593       'quorum':     'BlockdevOptionsQuorum',
1594       'raw':        'BlockdevOptionsGenericFormat',
1595 # TODO rbd: Wait for structured options
1596 # TODO sheepdog: Wait for structured options
1597 # TODO ssh: Should take InetSocketAddress for 'host'?
1598       'tftp':       'BlockdevOptionsFile',
1599       'vdi':        'BlockdevOptionsGenericFormat',
1600       'vhdx':       'BlockdevOptionsGenericFormat',
1601       'vmdk':       'BlockdevOptionsGenericCOWFormat',
1602       'vpc':        'BlockdevOptionsGenericFormat',
1603       'vvfat':      'BlockdevOptionsVVFAT'
1604   } }
1605
1606 ##
1607 # @BlockdevRef
1608 #
1609 # Reference to a block device.
1610 #
1611 # @definition:      defines a new block device inline
1612 # @reference:       references the ID of an existing block device. An
1613 #                   empty string means that no block device should be
1614 #                   referenced.
1615 #
1616 # Since: 1.7
1617 ##
1618 { 'union': 'BlockdevRef',
1619   'discriminator': {},
1620   'data': { 'definition': 'BlockdevOptions',
1621             'reference': 'str' } }
1622
1623 ##
1624 # @blockdev-add:
1625 #
1626 # Creates a new block device.
1627 #
1628 # @options: block device options for the new device
1629 #
1630 # Since: 1.7
1631 ##
1632 { 'command': 'blockdev-add', 'data': { 'options': 'BlockdevOptions' } }
1633
1634
1635 ##
1636 # @BlockErrorAction
1637 #
1638 # An enumeration of action that has been taken when a DISK I/O occurs
1639 #
1640 # @ignore: error has been ignored
1641 #
1642 # @report: error has been reported to the device
1643 #
1644 # @stop: error caused VM to be stopped
1645 #
1646 # Since: 2.1
1647 ##
1648 { 'enum': 'BlockErrorAction',
1649   'data': [ 'ignore', 'report', 'stop' ] }
1650
1651
1652 ##
1653 # @BLOCK_IMAGE_CORRUPTED
1654 #
1655 # Emitted when a corruption has been detected in a disk image
1656 #
1657 # @device: device name
1658 #
1659 # @msg: informative message for human consumption, such as the kind of
1660 #       corruption being detected. It should not be parsed by machine as it is
1661 #       not guaranteed to be stable
1662 #
1663 # @offset: #optional, if the corruption resulted from an image access, this is
1664 #          the access offset into the image
1665 #
1666 # @size: #optional, if the corruption resulted from an image access, this is
1667 #        the access size
1668 #
1669 # fatal: if set, the image is marked corrupt and therefore unusable after this
1670 #        event and must be repaired (Since 2.2; before, every
1671 #        BLOCK_IMAGE_CORRUPTED event was fatal)
1672 #
1673 # Since: 1.7
1674 ##
1675 { 'event': 'BLOCK_IMAGE_CORRUPTED',
1676   'data': { 'device' : 'str',
1677             'msg'    : 'str',
1678             '*offset': 'int',
1679             '*size'  : 'int',
1680             'fatal'  : 'bool' } }
1681
1682 ##
1683 # @BLOCK_IO_ERROR
1684 #
1685 # Emitted when a disk I/O error occurs
1686 #
1687 # @device: device name
1688 #
1689 # @operation: I/O operation
1690 #
1691 # @action: action that has been taken
1692 #
1693 # @nospace: #optional true if I/O error was caused due to a no-space
1694 #           condition. This key is only present if query-block's
1695 #           io-status is present, please see query-block documentation
1696 #           for more information (since: 2.2)
1697 #
1698 # @reason: human readable string describing the error cause.
1699 #          (This field is a debugging aid for humans, it should not
1700 #           be parsed by applications) (since: 2.2)
1701 #
1702 # Note: If action is "stop", a STOP event will eventually follow the
1703 # BLOCK_IO_ERROR event
1704 #
1705 # Since: 0.13.0
1706 ##
1707 { 'event': 'BLOCK_IO_ERROR',
1708   'data': { 'device': 'str', 'operation': 'IoOperationType',
1709             'action': 'BlockErrorAction', '*nospace': 'bool',
1710             'reason': 'str' } }
1711
1712 ##
1713 # @BLOCK_JOB_COMPLETED
1714 #
1715 # Emitted when a block job has completed
1716 #
1717 # @type: job type
1718 #
1719 # @device: device name
1720 #
1721 # @len: maximum progress value
1722 #
1723 # @offset: current progress value. On success this is equal to len.
1724 #          On failure this is less than len
1725 #
1726 # @speed: rate limit, bytes per second
1727 #
1728 # @error: #optional, error message. Only present on failure. This field
1729 #         contains a human-readable error message. There are no semantics
1730 #         other than that streaming has failed and clients should not try to
1731 #         interpret the error string
1732 #
1733 # Since: 1.1
1734 ##
1735 { 'event': 'BLOCK_JOB_COMPLETED',
1736   'data': { 'type'  : 'BlockJobType',
1737             'device': 'str',
1738             'len'   : 'int',
1739             'offset': 'int',
1740             'speed' : 'int',
1741             '*error': 'str' } }
1742
1743 ##
1744 # @BLOCK_JOB_CANCELLED
1745 #
1746 # Emitted when a block job has been cancelled
1747 #
1748 # @type: job type
1749 #
1750 # @device: device name
1751 #
1752 # @len: maximum progress value
1753 #
1754 # @offset: current progress value. On success this is equal to len.
1755 #          On failure this is less than len
1756 #
1757 # @speed: rate limit, bytes per second
1758 #
1759 # Since: 1.1
1760 ##
1761 { 'event': 'BLOCK_JOB_CANCELLED',
1762   'data': { 'type'  : 'BlockJobType',
1763             'device': 'str',
1764             'len'   : 'int',
1765             'offset': 'int',
1766             'speed' : 'int' } }
1767
1768 ##
1769 # @BLOCK_JOB_ERROR
1770 #
1771 # Emitted when a block job encounters an error
1772 #
1773 # @device: device name
1774 #
1775 # @operation: I/O operation
1776 #
1777 # @action: action that has been taken
1778 #
1779 # Since: 1.3
1780 ##
1781 { 'event': 'BLOCK_JOB_ERROR',
1782   'data': { 'device'   : 'str',
1783             'operation': 'IoOperationType',
1784             'action'   : 'BlockErrorAction' } }
1785
1786 ##
1787 # @BLOCK_JOB_READY
1788 #
1789 # Emitted when a block job is ready to complete
1790 #
1791 # @type: job type
1792 #
1793 # @device: device name
1794 #
1795 # @len: maximum progress value
1796 #
1797 # @offset: current progress value. On success this is equal to len.
1798 #          On failure this is less than len
1799 #
1800 # @speed: rate limit, bytes per second
1801 #
1802 # Note: The "ready to complete" status is always reset by a @BLOCK_JOB_ERROR
1803 # event
1804 #
1805 # Since: 1.3
1806 ##
1807 { 'event': 'BLOCK_JOB_READY',
1808   'data': { 'type'  : 'BlockJobType',
1809             'device': 'str',
1810             'len'   : 'int',
1811             'offset': 'int',
1812             'speed' : 'int' } }
1813
1814 # @PreallocMode
1815 #
1816 # Preallocation mode of QEMU image file
1817 #
1818 # @off: no preallocation
1819 # @metadata: preallocate only for metadata
1820 # @falloc: like @full preallocation but allocate disk space by
1821 #          posix_fallocate() rather than writing zeros.
1822 # @full: preallocate all data by writing zeros to device to ensure disk
1823 #        space is really available. @full preallocation also sets up
1824 #        metadata correctly.
1825 #
1826 # Since 2.2
1827 ##
1828 { 'enum': 'PreallocMode',
1829   'data': [ 'off', 'metadata', 'falloc', 'full' ] }