blob: 7d47f4dff45546af1dee240c47489b5ad437425b [file] [log] [blame]
Anthony Liguorie3193602011-09-02 12:34:47 -05001# -*- Mode: Python -*-
2#
3# QAPI Schema
Anthony Liguori48a32be2011-09-02 12:34:48 -05004
Benoît Canetd34bda72014-06-05 13:45:29 +02005# QAPI common definitions
6{ 'include': 'qapi/common.json' }
Paolo Bonzini104059d2014-02-08 11:01:55 +01007
Benoît Canet5db15092014-06-05 13:45:30 +02008# QAPI block definitions
9{ 'include': 'qapi/block.json' }
10
Luiz Capitulinodcafd322012-07-27 09:34:50 -030011##
Paolo Bonzini104059d2014-02-08 11:01:55 +010012# LostTickPolicy:
13#
14# Policy for handling lost ticks in timer devices.
15#
16# @discard: throw away the missed tick(s) and continue with future injection
17# normally. Guest time may be delayed, unless the OS has explicit
18# handling of lost ticks
19#
20# @delay: continue to deliver ticks at the normal rate. Guest time will be
21# delayed due to the late tick
22#
23# @merge: merge the missed tick(s) into one tick and inject. Guest time
24# may be delayed, depending on how the OS reacts to the merging
25# of ticks
26#
27# @slew: deliver ticks at a higher rate to catch up with the missed tick. The
28# guest time should not be delayed once catchup is complete.
29#
30# Since: 2.0
31##
32{ 'enum': 'LostTickPolicy',
33 'data': ['discard', 'delay', 'merge', 'slew' ] }
34
35##
36# BiosAtaTranslation:
37#
38# Policy that BIOS should use to interpret cylinder/head/sector
39# addresses. Note that Bochs BIOS and SeaBIOS will not actually
40# translate logical CHS to physical; instead, they will use logical
41# block addressing.
42#
43# @auto: If cylinder/heads/sizes are passed, choose between none and LBA
44# depending on the size of the disk. If they are not passed,
45# choose none if QEMU can guess that the disk had 16 or fewer
46# heads, large if QEMU can guess that the disk had 131072 or
47# fewer tracks across all heads (i.e. cylinders*heads<131072),
48# otherwise LBA.
49#
50# @none: The physical disk geometry is equal to the logical geometry.
51#
52# @lba: Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
53# heads (if fewer than 255 are enough to cover the whole disk
54# with 1024 cylinders/head). The number of cylinders/head is
55# then computed based on the number of sectors and heads.
56#
57# @large: The number of cylinders per head is scaled down to 1024
58# by correspondingly scaling up the number of heads.
59#
60# @rechs: Same as @large, but first convert a 16-head geometry to
61# 15-head, by proportionally scaling up the number of
62# cylinders/head.
63#
64# Since: 2.0
65##
66{ 'enum': 'BiosAtaTranslation',
67 'data': ['auto', 'none', 'lba', 'large', 'rechs']}
68
Luiz Capitulinob224e5e2012-09-13 16:52:20 -030069# @add_client
70#
71# Allow client connections for VNC, Spice and socket based
72# character devices to be passed in to QEMU via SCM_RIGHTS.
73#
74# @protocol: protocol name. Valid names are "vnc", "spice" or the
75# name of a character device (eg. from -chardev id=XXXX)
76#
77# @fdname: file descriptor name previously passed via 'getfd' command
78#
79# @skipauth: #optional whether to skip authentication. Only applies
80# to "vnc" and "spice" protocols
81#
82# @tls: #optional whether to perform TLS. Only applies to the "spice"
83# protocol
84#
85# Returns: nothing on success.
86#
87# Since: 0.14.0
88##
89{ 'command': 'add_client',
90 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
91 '*tls': 'bool' } }
92
93##
Anthony Liguori48a32be2011-09-02 12:34:48 -050094# @NameInfo:
95#
96# Guest name information.
97#
98# @name: #optional The name of the guest
99#
100# Since 0.14.0
101##
102{ 'type': 'NameInfo', 'data': {'*name': 'str'} }
103
104##
105# @query-name:
106#
107# Return the name information of a guest.
108#
109# Returns: @NameInfo of the guest
110#
111# Since 0.14.0
112##
113{ 'command': 'query-name', 'returns': 'NameInfo' }
Luiz Capitulinob9c15f12011-08-26 17:38:13 -0300114
115##
Luiz Capitulino292a2602011-09-12 15:10:53 -0300116# @KvmInfo:
117#
118# Information about support for KVM acceleration
119#
120# @enabled: true if KVM acceleration is active
121#
122# @present: true if KVM acceleration is built into this executable
123#
124# Since: 0.14.0
125##
126{ 'type': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
127
128##
129# @query-kvm:
130#
131# Returns information about KVM acceleration
132#
133# Returns: @KvmInfo
134#
135# Since: 0.14.0
136##
137{ 'command': 'query-kvm', 'returns': 'KvmInfo' }
138
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300139##
140# @RunState
141#
Lei Li6932a692012-08-23 13:14:25 +0800142# An enumeration of VM run states.
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300143#
144# @debug: QEMU is running on a debugger
145#
Luiz Capitulino0a24c7b2012-04-27 13:16:41 -0300146# @finish-migrate: guest is paused to finish the migration process
147#
Paolo Bonzini1e998142012-10-23 14:54:21 +0200148# @inmigrate: guest is paused waiting for an incoming migration. Note
149# that this state does not tell whether the machine will start at the
150# end of the migration. This depends on the command-line -S option and
151# any invocation of 'stop' or 'cont' that has happened since QEMU was
152# started.
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300153#
154# @internal-error: An internal error that prevents further guest execution
155# has occurred
156#
157# @io-error: the last IOP has failed and the device is configured to pause
158# on I/O errors
159#
160# @paused: guest has been paused via the 'stop' command
161#
162# @postmigrate: guest is paused following a successful 'migrate'
163#
164# @prelaunch: QEMU was started with -S and guest has not started
165#
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300166# @restore-vm: guest is paused to restore VM state
167#
168# @running: guest is actively running
169#
170# @save-vm: guest is paused to save the VM state
171#
172# @shutdown: guest is shut down (and -no-shutdown is in use)
173#
Luiz Capitulinoad02b962012-04-27 13:33:36 -0300174# @suspended: guest is suspended (ACPI S3)
175#
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300176# @watchdog: the watchdog action is configured to pause and has been triggered
Hu Taoede085b2013-04-26 11:24:40 +0800177#
178# @guest-panicked: guest has been panicked as a result of guest OS panic
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300179##
180{ 'enum': 'RunState',
181 'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
182 'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
Hu Taoede085b2013-04-26 11:24:40 +0800183 'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',
184 'guest-panicked' ] }
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300185
186##
Benoît Canetc249ee62012-09-05 13:09:01 +0200187# @SnapshotInfo
188#
189# @id: unique snapshot id
190#
191# @name: user chosen name
192#
193# @vm-state-size: size of the VM state
194#
195# @date-sec: UTC date of the snapshot in seconds
196#
197# @date-nsec: fractional part in nano seconds to be used with date-sec
198#
199# @vm-clock-sec: VM clock relative to boot in seconds
200#
201# @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec
202#
203# Since: 1.3
204#
205##
206
207{ 'type': 'SnapshotInfo',
208 'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int',
209 'date-sec': 'int', 'date-nsec': 'int',
210 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int' } }
211
212##
Max Reitz37764df2013-10-09 10:46:18 +0200213# @ImageInfoSpecificQCow2:
214#
215# @compat: compatibility level
216#
217# @lazy-refcounts: #optional on or off; only valid for compat >= 1.1
218#
219# Since: 1.7
220##
221{ 'type': 'ImageInfoSpecificQCow2',
222 'data': {
223 'compat': 'str',
224 '*lazy-refcounts': 'bool'
225 } }
226
227##
Fam Zhengf4c129a2013-10-31 10:06:23 +0800228# @ImageInfoSpecificVmdk:
229#
Fam Zhenga9a443c2013-11-01 17:35:29 +0800230# @create-type: The create type of VMDK image
Fam Zhengf4c129a2013-10-31 10:06:23 +0800231#
232# @cid: Content id of image
233#
234# @parent-cid: Parent VMDK image's cid
235#
236# @extents: List of extent files
237#
238# Since: 1.7
239##
240{ 'type': 'ImageInfoSpecificVmdk',
241 'data': {
242 'create-type': 'str',
243 'cid': 'int',
244 'parent-cid': 'int',
245 'extents': ['ImageInfo']
246 } }
247
248##
Max Reitzf2bb8a82013-10-09 10:46:15 +0200249# @ImageInfoSpecific:
250#
251# A discriminated record of image format specific information structures.
252#
253# Since: 1.7
254##
255
256{ 'union': 'ImageInfoSpecific',
257 'data': {
Fam Zhengf4c129a2013-10-31 10:06:23 +0800258 'qcow2': 'ImageInfoSpecificQCow2',
259 'vmdk': 'ImageInfoSpecificVmdk'
Max Reitzf2bb8a82013-10-09 10:46:15 +0200260 } }
261
262##
Benoît Canetc249ee62012-09-05 13:09:01 +0200263# @ImageInfo:
264#
265# Information about a QEMU image file
266#
267# @filename: name of the image file
268#
269# @format: format of the image file
270#
271# @virtual-size: maximum capacity in bytes of the image
272#
273# @actual-size: #optional actual size on disk in bytes of the image
274#
275# @dirty-flag: #optional true if image is not cleanly closed
276#
277# @cluster-size: #optional size of a cluster in bytes
278#
279# @encrypted: #optional true if the image is encrypted
280#
Fam Zhengcbe82d72013-10-18 11:12:44 +0800281# @compressed: #optional true if the image is compressed (Since 1.7)
282#
Benoît Canetc249ee62012-09-05 13:09:01 +0200283# @backing-filename: #optional name of the backing file
284#
285# @full-backing-filename: #optional full path of the backing file
286#
287# @backing-filename-format: #optional the format of the backing file
288#
289# @snapshots: #optional list of VM snapshots
290#
Wenchao Xia553a7e82013-06-06 12:27:59 +0800291# @backing-image: #optional info of the backing image (since 1.6)
292#
Max Reitzf2bb8a82013-10-09 10:46:15 +0200293# @format-specific: #optional structure supplying additional format-specific
294# information (since 1.7)
295#
Benoît Canetc249ee62012-09-05 13:09:01 +0200296# Since: 1.3
297#
298##
299
300{ 'type': 'ImageInfo',
301 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool',
302 '*actual-size': 'int', 'virtual-size': 'int',
Fam Zhengcbe82d72013-10-18 11:12:44 +0800303 '*cluster-size': 'int', '*encrypted': 'bool', '*compressed': 'bool',
Benoît Canetc249ee62012-09-05 13:09:01 +0200304 '*backing-filename': 'str', '*full-backing-filename': 'str',
Wenchao Xia553a7e82013-06-06 12:27:59 +0800305 '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'],
Max Reitzf2bb8a82013-10-09 10:46:15 +0200306 '*backing-image': 'ImageInfo',
307 '*format-specific': 'ImageInfoSpecific' } }
Benoît Canetc249ee62012-09-05 13:09:01 +0200308
309##
Federico Simoncelli8599ea42013-01-28 06:59:47 -0500310# @ImageCheck:
311#
312# Information about a QEMU image file check
313#
314# @filename: name of the image file checked
315#
316# @format: format of the image file checked
317#
318# @check-errors: number of unexpected errors occurred during check
319#
320# @image-end-offset: #optional offset (in bytes) where the image ends, this
321# field is present if the driver for the image format
322# supports it
323#
324# @corruptions: #optional number of corruptions found during the check if any
325#
326# @leaks: #optional number of leaks found during the check if any
327#
328# @corruptions-fixed: #optional number of corruptions fixed during the check
329# if any
330#
331# @leaks-fixed: #optional number of leaks fixed during the check if any
332#
333# @total-clusters: #optional total number of clusters, this field is present
334# if the driver for the image format supports it
335#
336# @allocated-clusters: #optional total number of allocated clusters, this
337# field is present if the driver for the image format
338# supports it
339#
340# @fragmented-clusters: #optional total number of fragmented clusters, this
341# field is present if the driver for the image format
342# supports it
343#
Stefan Hajnoczie6439d72013-02-07 17:15:04 +0100344# @compressed-clusters: #optional total number of compressed clusters, this
345# field is present if the driver for the image format
346# supports it
347#
Federico Simoncelli8599ea42013-01-28 06:59:47 -0500348# Since: 1.4
349#
350##
351
352{ 'type': 'ImageCheck',
353 'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int',
354 '*image-end-offset': 'int', '*corruptions': 'int', '*leaks': 'int',
355 '*corruptions-fixed': 'int', '*leaks-fixed': 'int',
356 '*total-clusters': 'int', '*allocated-clusters': 'int',
Stefan Hajnoczie6439d72013-02-07 17:15:04 +0100357 '*fragmented-clusters': 'int', '*compressed-clusters': 'int' } }
Federico Simoncelli8599ea42013-01-28 06:59:47 -0500358
359##
Luiz Capitulino1fa9a5e2011-09-12 17:54:20 -0300360# @StatusInfo:
361#
362# Information about VCPU run state
363#
364# @running: true if all VCPUs are runnable, false if not runnable
365#
366# @singlestep: true if VCPUs are in single-step mode
367#
368# @status: the virtual machine @RunState
369#
370# Since: 0.14.0
371#
372# Notes: @singlestep is enabled through the GDB stub
373##
374{ 'type': 'StatusInfo',
375 'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
376
377##
378# @query-status:
379#
380# Query the run status of all VCPUs
381#
382# Returns: @StatusInfo reflecting all VCPUs
383#
384# Since: 0.14.0
385##
386{ 'command': 'query-status', 'returns': 'StatusInfo' }
387
Luiz Capitulinoefab7672011-09-13 17:16:25 -0300388##
389# @UuidInfo:
390#
391# Guest UUID information.
392#
393# @UUID: the UUID of the guest
394#
395# Since: 0.14.0
396#
397# Notes: If no UUID was specified for the guest, a null UUID is returned.
398##
399{ 'type': 'UuidInfo', 'data': {'UUID': 'str'} }
400
401##
402# @query-uuid:
403#
404# Query the guest UUID information.
405#
406# Returns: The @UuidInfo for the guest
407#
408# Since 0.14.0
409##
410{ 'command': 'query-uuid', 'returns': 'UuidInfo' }
411
Luiz Capitulinoc5a415a2011-09-14 16:05:49 -0300412##
413# @ChardevInfo:
414#
415# Information about a character device.
416#
417# @label: the label of the character device
418#
419# @filename: the filename of the character device
420#
421# Notes: @filename is encoded using the QEMU command line character device
422# encoding. See the QEMU man page for details.
423#
424# Since: 0.14.0
425##
426{ 'type': 'ChardevInfo', 'data': {'label': 'str', 'filename': 'str'} }
427
428##
429# @query-chardev:
430#
431# Returns information about current character devices.
432#
433# Returns: a list of @ChardevInfo
434#
435# Since: 0.14.0
436##
437{ 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
Luiz Capitulinoaa9b79b2011-09-21 14:31:51 -0300438
439##
Martin Kletzander77d1c3c2014-02-01 12:52:42 +0100440# @ChardevBackendInfo:
441#
442# Information about a character device backend
443#
444# @name: The backend name
445#
446# Since: 2.0
447##
448{ 'type': 'ChardevBackendInfo', 'data': {'name': 'str'} }
449
450##
451# @query-chardev-backends:
452#
453# Returns information about character device backends.
454#
455# Returns: a list of @ChardevBackendInfo
456#
457# Since: 2.0
458##
459{ 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
460
461##
Lei Li1f590cf2013-01-25 00:03:20 +0800462# @DataFormat:
463#
464# An enumeration of data format.
465#
Markus Armbruster3949e592013-02-06 21:27:24 +0100466# @utf8: Data is a UTF-8 string (RFC 3629)
Lei Li1f590cf2013-01-25 00:03:20 +0800467#
Markus Armbruster3949e592013-02-06 21:27:24 +0100468# @base64: Data is Base64 encoded binary (RFC 3548)
Lei Li1f590cf2013-01-25 00:03:20 +0800469#
470# Since: 1.4
471##
Amos Kongad0f1712013-06-19 17:23:27 +0800472{ 'enum': 'DataFormat',
Lei Li1f590cf2013-01-25 00:03:20 +0800473 'data': [ 'utf8', 'base64' ] }
474
475##
Markus Armbruster3949e592013-02-06 21:27:24 +0100476# @ringbuf-write:
Lei Li1f590cf2013-01-25 00:03:20 +0800477#
Markus Armbruster3949e592013-02-06 21:27:24 +0100478# Write to a ring buffer character device.
Lei Li1f590cf2013-01-25 00:03:20 +0800479#
Markus Armbruster3949e592013-02-06 21:27:24 +0100480# @device: the ring buffer character device name
Lei Li1f590cf2013-01-25 00:03:20 +0800481#
Markus Armbruster3949e592013-02-06 21:27:24 +0100482# @data: data to write
Lei Li1f590cf2013-01-25 00:03:20 +0800483#
Markus Armbruster3949e592013-02-06 21:27:24 +0100484# @format: #optional data encoding (default 'utf8').
485# - base64: data must be base64 encoded text. Its binary
486# decoding gets written.
487# Bug: invalid base64 is currently not rejected.
488# Whitespace *is* invalid.
489# - utf8: data's UTF-8 encoding is written
490# - data itself is always Unicode regardless of format, like
491# any other string.
Lei Li1f590cf2013-01-25 00:03:20 +0800492#
493# Returns: Nothing on success
Lei Li1f590cf2013-01-25 00:03:20 +0800494#
495# Since: 1.4
496##
Markus Armbruster3949e592013-02-06 21:27:24 +0100497{ 'command': 'ringbuf-write',
Markus Armbruster82e59a62013-02-06 21:27:14 +0100498 'data': {'device': 'str', 'data': 'str',
Lei Li1f590cf2013-01-25 00:03:20 +0800499 '*format': 'DataFormat'} }
500
501##
Markus Armbruster3949e592013-02-06 21:27:24 +0100502# @ringbuf-read:
Lei Li49b6d722013-01-25 00:03:21 +0800503#
Markus Armbruster3949e592013-02-06 21:27:24 +0100504# Read from a ring buffer character device.
Lei Li49b6d722013-01-25 00:03:21 +0800505#
Markus Armbruster3949e592013-02-06 21:27:24 +0100506# @device: the ring buffer character device name
Lei Li49b6d722013-01-25 00:03:21 +0800507#
Markus Armbruster3949e592013-02-06 21:27:24 +0100508# @size: how many bytes to read at most
Lei Li49b6d722013-01-25 00:03:21 +0800509#
Markus Armbruster3949e592013-02-06 21:27:24 +0100510# @format: #optional data encoding (default 'utf8').
511# - base64: the data read is returned in base64 encoding.
512# - utf8: the data read is interpreted as UTF-8.
513# Bug: can screw up when the buffer contains invalid UTF-8
514# sequences, NUL characters, after the ring buffer lost
515# data, and when reading stops because the size limit is
516# reached.
517# - The return value is always Unicode regardless of format,
518# like any other string.
Lei Li49b6d722013-01-25 00:03:21 +0800519#
Markus Armbruster3ab651f2013-02-06 21:27:15 +0100520# Returns: data read from the device
Lei Li49b6d722013-01-25 00:03:21 +0800521#
522# Since: 1.4
523##
Markus Armbruster3949e592013-02-06 21:27:24 +0100524{ 'command': 'ringbuf-read',
Lei Li49b6d722013-01-25 00:03:21 +0800525 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
Markus Armbruster3ab651f2013-02-06 21:27:15 +0100526 'returns': 'str' }
Lei Li49b6d722013-01-25 00:03:21 +0800527
528##
Daniel P. Berrange48608532012-05-21 17:59:51 +0100529# @EventInfo:
530#
531# Information about a QMP event
532#
533# @name: The event name
534#
535# Since: 1.2.0
536##
537{ 'type': 'EventInfo', 'data': {'name': 'str'} }
538
539##
540# @query-events:
541#
542# Return a list of supported QMP events by this server
543#
544# Returns: A list of @EventInfo for all supported events
545#
546# Since: 1.2.0
547##
548{ 'command': 'query-events', 'returns': ['EventInfo'] }
549
550##
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300551# @MigrationStats
552#
553# Detailed migration status.
554#
555# @transferred: amount of bytes already transferred to the target VM
556#
557# @remaining: amount of bytes remaining to be transferred to the target VM
558#
559# @total: total amount of bytes involved in the migration process
560#
Peter Lievenf1c72792013-03-26 10:58:37 +0100561# @duplicate: number of duplicate (zero) pages (since 1.2)
562#
563# @skipped: number of skipped zero pages (since 1.5)
Orit Wasserman004d4c12012-08-06 21:42:56 +0300564#
565# @normal : number of normal pages (since 1.2)
566#
Juan Quintela8d017192012-08-13 12:31:25 +0200567# @normal-bytes: number of normal bytes sent (since 1.2)
568#
569# @dirty-pages-rate: number of pages dirtied by second by the
570# guest (since 1.3)
Orit Wasserman004d4c12012-08-06 21:42:56 +0300571#
Michael R. Hines7e114f82013-06-25 21:35:30 -0400572# @mbps: throughput in megabits/sec. (since 1.6)
573#
ChenLiang58570ed2014-04-04 17:57:55 +0800574# @dirty-sync-count: number of times that dirty ram was synchronized (since 2.1)
575#
Orit Wasserman004d4c12012-08-06 21:42:56 +0300576# Since: 0.14.0
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300577##
578{ 'type': 'MigrationStats',
Juan Quintelad5f8a572012-05-21 22:01:07 +0200579 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
Peter Lievenf1c72792013-03-26 10:58:37 +0100580 'duplicate': 'int', 'skipped': 'int', 'normal': 'int',
Michael R. Hines7e114f82013-06-25 21:35:30 -0400581 'normal-bytes': 'int', 'dirty-pages-rate' : 'int',
ChenLiang58570ed2014-04-04 17:57:55 +0800582 'mbps' : 'number', 'dirty-sync-count' : 'int' } }
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300583
584##
Orit Wassermanf36d55a2012-08-06 21:42:57 +0300585# @XBZRLECacheStats
586#
587# Detailed XBZRLE migration cache statistics
588#
589# @cache-size: XBZRLE cache size
590#
591# @bytes: amount of bytes already transferred to the target VM
592#
593# @pages: amount of pages transferred to the target VM
594#
595# @cache-miss: number of cache miss
596#
ChenLiang8bc39232014-04-04 17:57:56 +0800597# @cache-miss-rate: rate of cache miss (since 2.1)
598#
Orit Wassermanf36d55a2012-08-06 21:42:57 +0300599# @overflow: number of overflows
600#
601# Since: 1.2
602##
603{ 'type': 'XBZRLECacheStats',
604 'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
ChenLiang8bc39232014-04-04 17:57:56 +0800605 'cache-miss': 'int', 'cache-miss-rate': 'number',
606 'overflow': 'int' } }
Orit Wassermanf36d55a2012-08-06 21:42:57 +0300607
608##
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300609# @MigrationInfo
610#
611# Information about current migration process.
612#
613# @status: #optional string describing the current migration status.
Peter Feiner3b695952014-05-16 10:40:47 -0400614# As of 0.14.0 this can be 'setup', 'active', 'completed', 'failed' or
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300615# 'cancelled'. If this field is not returned, no migration process
616# has been initiated
617#
Juan Quintelad5f8a572012-05-21 22:01:07 +0200618# @ram: #optional @MigrationStats containing detailed migration
619# status, only returned if status is 'active' or
620# 'completed'. 'comppleted' (since 1.2)
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300621#
622# @disk: #optional @MigrationStats containing detailed disk migration
623# status, only returned if status is 'active' and it is a block
624# migration
625#
Orit Wassermanf36d55a2012-08-06 21:42:57 +0300626# @xbzrle-cache: #optional @XBZRLECacheStats containing detailed XBZRLE
627# migration statistics, only returned if XBZRLE feature is on and
628# status is 'active' or 'completed' (since 1.2)
629#
Juan Quintela7aa939a2012-08-18 13:17:10 +0200630# @total-time: #optional total amount of milliseconds since migration started.
631# If migration has ended, it returns the total migration
632# time. (since 1.2)
633#
Juan Quintela9c5a9fc2012-08-13 09:35:16 +0200634# @downtime: #optional only present when migration finishes correctly
635# total downtime in milliseconds for the guest.
636# (since 1.3)
637#
Juan Quintela2c52ddf2012-08-13 09:53:12 +0200638# @expected-downtime: #optional only present while migration is active
639# expected downtime in milliseconds for the guest in last walk
640# of the dirty bitmap. (since 1.3)
641#
Michael R. Hinesed4fbd12013-07-22 10:01:58 -0400642# @setup-time: #optional amount of setup time in milliseconds _before_ the
643# iterations begin but _after_ the QMP command is issued. This is designed
644# to provide an accounting of any activities (such as RDMA pinning) which
645# may be expensive, but do not actually occur during the iterative
646# migration rounds themselves. (since 1.6)
647#
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300648# Since: 0.14.0
649##
650{ 'type': 'MigrationInfo',
651 'data': {'*status': 'str', '*ram': 'MigrationStats',
Orit Wassermanf36d55a2012-08-06 21:42:57 +0300652 '*disk': 'MigrationStats',
Juan Quintela7aa939a2012-08-18 13:17:10 +0200653 '*xbzrle-cache': 'XBZRLECacheStats',
Juan Quintela9c5a9fc2012-08-13 09:35:16 +0200654 '*total-time': 'int',
Juan Quintela2c52ddf2012-08-13 09:53:12 +0200655 '*expected-downtime': 'int',
Michael R. Hinesed4fbd12013-07-22 10:01:58 -0400656 '*downtime': 'int',
657 '*setup-time': 'int'} }
Luiz Capitulino791e7c82011-09-13 17:37:16 -0300658
659##
660# @query-migrate
661#
662# Returns information about current migration process.
663#
664# Returns: @MigrationInfo
665#
666# Since: 0.14.0
667##
668{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
669
670##
Orit Wassermanbbf6da32012-08-06 21:42:47 +0300671# @MigrationCapability
672#
673# Migration capabilities enumeration
674#
675# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
676# This feature allows us to minimize migration traffic for certain work
677# loads, by sending compressed difference of the pages
678#
Michael R. Hines41310c62013-12-19 04:52:01 +0800679# @rdma-pin-all: Controls whether or not the entire VM memory footprint is
Michael R. Hines60d92222013-06-25 21:35:36 -0400680# mlock()'d on demand or all at once. Refer to docs/rdma.txt for usage.
Michael R. Hines41310c62013-12-19 04:52:01 +0800681# Disabled by default. (since 2.0)
Michael R. Hines60d92222013-06-25 21:35:36 -0400682#
Peter Lieven323004a2013-07-18 09:48:50 +0200683# @zero-blocks: During storage migration encode blocks of zeroes efficiently. This
684# essentially saves 1MB of zeroes per block on the wire. Enabling requires
685# source and target VM to support this feature. To enable it is sufficient
686# to enable the capability on the source VM. The feature is disabled by
687# default. (since 1.6)
688#
Juan Quintela9781c372013-07-23 15:21:09 +0200689# @auto-converge: If enabled, QEMU will automatically throttle down the guest
690# to speed up convergence of RAM migration. (since 1.6)
691#
Orit Wassermanbbf6da32012-08-06 21:42:47 +0300692# Since: 1.2
693##
694{ 'enum': 'MigrationCapability',
Michael R. Hines41310c62013-12-19 04:52:01 +0800695 'data': ['xbzrle', 'rdma-pin-all', 'auto-converge', 'zero-blocks'] }
Orit Wassermanbbf6da32012-08-06 21:42:47 +0300696
697##
698# @MigrationCapabilityStatus
699#
700# Migration capability information
701#
702# @capability: capability enum
703#
704# @state: capability state bool
705#
706# Since: 1.2
707##
708{ 'type': 'MigrationCapabilityStatus',
709 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
710
711##
Orit Wasserman00458432012-08-06 21:42:48 +0300712# @migrate-set-capabilities
713#
714# Enable/Disable the following migration capabilities (like xbzrle)
715#
716# @capabilities: json array of capability modifications to make
717#
718# Since: 1.2
719##
720{ 'command': 'migrate-set-capabilities',
721 'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
722
723##
Orit Wassermanbbf6da32012-08-06 21:42:47 +0300724# @query-migrate-capabilities
725#
726# Returns information about the current migration capabilities status
727#
728# Returns: @MigrationCapabilitiesStatus
729#
730# Since: 1.2
731##
732{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']}
733
734##
Luiz Capitulinoe235cec2011-09-21 15:29:55 -0300735# @MouseInfo:
736#
737# Information about a mouse device.
738#
739# @name: the name of the mouse device
740#
741# @index: the index of the mouse device
742#
743# @current: true if this device is currently receiving mouse events
744#
745# @absolute: true if this device supports absolute coordinates as input
746#
747# Since: 0.14.0
748##
749{ 'type': 'MouseInfo',
750 'data': {'name': 'str', 'index': 'int', 'current': 'bool',
751 'absolute': 'bool'} }
752
753##
754# @query-mice:
755#
756# Returns information about each active mouse device
757#
758# Returns: a list of @MouseInfo for each device
759#
760# Since: 0.14.0
761##
762{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
763
764##
Luiz Capitulinode0b36b2011-09-21 16:38:35 -0300765# @CpuInfo:
766#
767# Information about a virtual CPU
768#
769# @CPU: the index of the virtual CPU
770#
771# @current: this only exists for backwards compatible and should be ignored
Laszlo Ersekb80e5602012-07-17 16:17:10 +0200772#
Luiz Capitulinode0b36b2011-09-21 16:38:35 -0300773# @halted: true if the virtual CPU is in the halt state. Halt usually refers
774# to a processor specific low power mode.
775#
776# @pc: #optional If the target is i386 or x86_64, this is the 64-bit instruction
777# pointer.
778# If the target is Sparc, this is the PC component of the
779# instruction pointer.
780#
781# @nip: #optional If the target is PPC, the instruction pointer
782#
783# @npc: #optional If the target is Sparc, the NPC component of the instruction
784# pointer
785#
786# @PC: #optional If the target is MIPS, the instruction pointer
787#
788# @thread_id: ID of the underlying host thread
789#
790# Since: 0.14.0
791#
792# Notes: @halted is a transient state that changes frequently. By the time the
793# data is sent to the client, the guest may no longer be halted.
794##
795{ 'type': 'CpuInfo',
796 'data': {'CPU': 'int', 'current': 'bool', 'halted': 'bool', '*pc': 'int',
797 '*nip': 'int', '*npc': 'int', '*PC': 'int', 'thread_id': 'int'} }
798
799##
800# @query-cpus:
801#
802# Returns a list of information about each virtual CPU.
803#
804# Returns: a list of @CpuInfo for each virtual CPU
805#
806# Since: 0.14.0
807##
808{ 'command': 'query-cpus', 'returns': ['CpuInfo'] }
809
810##
Stefan Hajnoczidc3dd0d2014-02-27 11:48:42 +0100811# @IOThreadInfo:
812#
813# Information about an iothread
814#
815# @id: the identifier of the iothread
816#
817# @thread-id: ID of the underlying host thread
818#
819# Since: 2.0
820##
821{ 'type': 'IOThreadInfo',
822 'data': {'id': 'str', 'thread-id': 'int'} }
823
824##
825# @query-iothreads:
826#
827# Returns a list of information about each iothread.
828#
829# Note this list excludes the QEMU main loop thread, which is not declared
830# using the -object iothread command-line option. It is always the main thread
831# of the process.
832#
833# Returns: a list of @IOThreadInfo for each iothread
834#
835# Since: 2.0
836##
837{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'] }
838
839##
Luiz Capitulinob2023812011-09-21 17:16:47 -0300840# @BlockDeviceInfo:
841#
842# Information about the backing device for a block device.
843#
844# @file: the filename of the backing device
845#
Benoît Canetc13163f2014-01-23 21:31:34 +0100846# @node-name: #optional the name of the block driver node (Since 2.0)
847#
Luiz Capitulinob2023812011-09-21 17:16:47 -0300848# @ro: true if the backing device was open read-only
849#
850# @drv: the name of the block format used to open the backing device. As of
851# 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
852# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
853# 'host_floppy', 'http', 'https', 'nbd', 'parallels', 'qcow',
854# 'qcow2', 'raw', 'tftp', 'vdi', 'vmdk', 'vpc', 'vvfat'
855#
856# @backing_file: #optional the name of the backing file (for copy-on-write)
857#
Benoît Canet2e3e3312012-08-02 10:22:48 +0200858# @backing_file_depth: number of files in the backing file chain (since: 1.2)
859#
Luiz Capitulinob2023812011-09-21 17:16:47 -0300860# @encrypted: true if the backing device is encrypted
861#
Luiz Capitulinoc75a1a82012-07-26 20:28:44 -0300862# @encryption_key_missing: true if the backing device is encrypted but an
863# valid encryption key is missing
864#
Peter Lieven465bee12014-05-18 00:58:19 +0200865# @detect_zeroes: detect and optimize zero writes (Since 2.1)
866#
Zhi Yong Wu727f0052011-11-08 13:00:31 +0800867# @bps: total throughput limit in bytes per second is specified
868#
869# @bps_rd: read throughput limit in bytes per second is specified
870#
871# @bps_wr: write throughput limit in bytes per second is specified
872#
873# @iops: total I/O operations per second is specified
874#
875# @iops_rd: read I/O operations per second is specified
876#
877# @iops_wr: write I/O operations per second is specified
878#
Wenchao Xia553a7e82013-06-06 12:27:59 +0800879# @image: the info of image used (since: 1.6)
880#
Benoît Canet3e9fab62013-09-02 14:14:40 +0200881# @bps_max: #optional total max in bytes (Since 1.7)
882#
883# @bps_rd_max: #optional read max in bytes (Since 1.7)
884#
885# @bps_wr_max: #optional write max in bytes (Since 1.7)
886#
887# @iops_max: #optional total I/O operations max (Since 1.7)
888#
889# @iops_rd_max: #optional read I/O operations max (Since 1.7)
890#
891# @iops_wr_max: #optional write I/O operations max (Since 1.7)
892#
Benoît Canet2024c1d2013-09-02 14:14:41 +0200893# @iops_size: #optional an I/O size in bytes (Since 1.7)
894#
Luiz Capitulinob2023812011-09-21 17:16:47 -0300895# Since: 0.14.0
896#
Luiz Capitulinob2023812011-09-21 17:16:47 -0300897##
898{ 'type': 'BlockDeviceInfo',
Benoît Canetc13163f2014-01-23 21:31:34 +0100899 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str',
Benoît Canet2e3e3312012-08-02 10:22:48 +0200900 '*backing_file': 'str', 'backing_file_depth': 'int',
Luiz Capitulinoc75a1a82012-07-26 20:28:44 -0300901 'encrypted': 'bool', 'encryption_key_missing': 'bool',
Peter Lieven465bee12014-05-18 00:58:19 +0200902 'detect_zeroes': 'BlockdevDetectZeroesOptions',
Luiz Capitulinoc75a1a82012-07-26 20:28:44 -0300903 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
Wenchao Xia553a7e82013-06-06 12:27:59 +0800904 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
Benoît Canet3e9fab62013-09-02 14:14:40 +0200905 'image': 'ImageInfo',
906 '*bps_max': 'int', '*bps_rd_max': 'int',
907 '*bps_wr_max': 'int', '*iops_max': 'int',
Benoît Canet2024c1d2013-09-02 14:14:41 +0200908 '*iops_rd_max': 'int', '*iops_wr_max': 'int',
909 '*iops_size': 'int' } }
Luiz Capitulinob2023812011-09-21 17:16:47 -0300910
911##
912# @BlockDeviceIoStatus:
913#
914# An enumeration of block device I/O status.
915#
916# @ok: The last I/O operation has succeeded
917#
918# @failed: The last I/O operation has failed
919#
920# @nospace: The last I/O operation has failed due to a no-space condition
921#
922# Since: 1.0
923##
924{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
925
926##
Paolo Bonzinifacd6e22013-09-04 19:00:34 +0200927# @BlockDeviceMapEntry:
928#
929# Entry in the metadata map of the device (returned by "qemu-img map")
930#
931# @start: Offset in the image of the first byte described by this entry
932# (in bytes)
933#
934# @length: Length of the range described by this entry (in bytes)
935#
936# @depth: Number of layers (0 = top image, 1 = top image's backing file, etc.)
937# before reaching one for which the range is allocated. The value is
938# in the range 0 to the depth of the image chain - 1.
939#
940# @zero: the sectors in this range read as zeros
941#
942# @data: reading the image will actually read data from a file (in particular,
943# if @offset is present this means that the sectors are not simply
944# preallocated, but contain actual data in raw format)
945#
946# @offset: if present, the image file stores the data for this range in
947# raw format at the given offset.
948#
949# Since 1.7
950##
951{ 'type': 'BlockDeviceMapEntry',
952 'data': { 'start': 'int', 'length': 'int', 'depth': 'int', 'zero': 'bool',
953 'data': 'bool', '*offset': 'int' } }
954
955##
Paolo Bonzinib9a9b3a2012-08-01 15:23:44 +0200956# @BlockDirtyInfo:
957#
958# Block dirty bitmap information.
959#
960# @count: number of dirty bytes according to the dirty bitmap
961#
Paolo Bonzini50717e92013-01-21 17:09:45 +0100962# @granularity: granularity of the dirty bitmap in bytes (since 1.4)
963#
Paolo Bonzinib9a9b3a2012-08-01 15:23:44 +0200964# Since: 1.3
965##
966{ 'type': 'BlockDirtyInfo',
Paolo Bonzini50717e92013-01-21 17:09:45 +0100967 'data': {'count': 'int', 'granularity': 'int'} }
Paolo Bonzinib9a9b3a2012-08-01 15:23:44 +0200968
969##
Luiz Capitulinob2023812011-09-21 17:16:47 -0300970# @BlockInfo:
971#
972# Block device information. This structure describes a virtual device and
973# the backing device associated with it.
974#
975# @device: The device name associated with the virtual device.
976#
977# @type: This field is returned only for compatibility reasons, it should
978# not be used (always returns 'unknown')
979#
980# @removable: True if the device supports removable media.
981#
982# @locked: True if the guest has locked this device from having its media
983# removed
984#
985# @tray_open: #optional True if the device has a tray and it is open
986# (only present if removable is true)
987#
Fam Zheng21b56832013-11-13 18:29:44 +0800988# @dirty-bitmaps: #optional dirty bitmaps information (only present if the
Kevin Wolf01443e12013-12-10 14:01:27 +0100989# driver has one or more dirty bitmaps) (Since 2.0)
Paolo Bonzinib9a9b3a2012-08-01 15:23:44 +0200990#
Luiz Capitulinob2023812011-09-21 17:16:47 -0300991# @io-status: #optional @BlockDeviceIoStatus. Only present if the device
992# supports it and the VM is configured to stop on errors
993#
994# @inserted: #optional @BlockDeviceInfo describing the device if media is
995# present
996#
997# Since: 0.14.0
998##
999{ 'type': 'BlockInfo',
1000 'data': {'device': 'str', 'type': 'str', 'removable': 'bool',
1001 'locked': 'bool', '*inserted': 'BlockDeviceInfo',
Paolo Bonzinib9a9b3a2012-08-01 15:23:44 +02001002 '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus',
Fam Zheng21b56832013-11-13 18:29:44 +08001003 '*dirty-bitmaps': ['BlockDirtyInfo'] } }
Luiz Capitulinob2023812011-09-21 17:16:47 -03001004
1005##
1006# @query-block:
1007#
1008# Get a list of BlockInfo for all virtual block devices.
1009#
1010# Returns: a list of @BlockInfo describing each virtual block device
1011#
1012# Since: 0.14.0
1013##
1014{ 'command': 'query-block', 'returns': ['BlockInfo'] }
1015
1016##
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03001017# @BlockDeviceStats:
1018#
1019# Statistics of a virtual block device or a block backing device.
1020#
1021# @rd_bytes: The number of bytes read by the device.
1022#
1023# @wr_bytes: The number of bytes written by the device.
1024#
1025# @rd_operations: The number of read operations performed by the device.
1026#
1027# @wr_operations: The number of write operations performed by the device.
1028#
1029# @flush_operations: The number of cache flush operations performed by the
1030# device (since 0.15.0)
1031#
1032# @flush_total_time_ns: Total time spend on cache flushes in nano-seconds
1033# (since 0.15.0).
1034#
1035# @wr_total_time_ns: Total time spend on writes in nano-seconds (since 0.15.0).
1036#
1037# @rd_total_time_ns: Total_time_spend on reads in nano-seconds (since 0.15.0).
1038#
1039# @wr_highest_offset: The offset after the greatest byte written to the
1040# device. The intended use of this information is for
1041# growable sparse files (like qcow2) that are used on top
1042# of a physical device.
1043#
1044# Since: 0.14.0
1045##
1046{ 'type': 'BlockDeviceStats',
1047 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'rd_operations': 'int',
1048 'wr_operations': 'int', 'flush_operations': 'int',
1049 'flush_total_time_ns': 'int', 'wr_total_time_ns': 'int',
1050 'rd_total_time_ns': 'int', 'wr_highest_offset': 'int' } }
1051
1052##
1053# @BlockStats:
1054#
1055# Statistics of a virtual block device or a block backing device.
1056#
1057# @device: #optional If the stats are for a virtual block device, the name
1058# corresponding to the virtual block device.
1059#
1060# @stats: A @BlockDeviceStats for the device.
1061#
Fam Zhengc8059b92014-01-23 10:03:26 +08001062# @parent: #optional This describes the file block device if it has one.
1063#
1064# @backing: #optional This describes the backing block device if it has one.
1065# (Since 2.0)
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03001066#
1067# Since: 0.14.0
1068##
1069{ 'type': 'BlockStats',
1070 'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
Fam Zhengc8059b92014-01-23 10:03:26 +08001071 '*parent': 'BlockStats',
1072 '*backing': 'BlockStats'} }
Luiz Capitulinof11f57e2011-09-22 15:56:36 -03001073
1074##
1075# @query-blockstats:
1076#
1077# Query the @BlockStats for all virtual block devices.
1078#
1079# Returns: A list of @BlockStats for each virtual block devices.
1080#
1081# Since: 0.14.0
1082##
1083{ 'command': 'query-blockstats', 'returns': ['BlockStats'] }
1084
1085##
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02001086# @VncClientInfo:
1087#
1088# Information about a connected VNC client.
1089#
1090# @host: The host name of the client. QEMU tries to resolve this to a DNS name
1091# when possible.
1092#
1093# @family: 'ipv6' if the client is connected via IPv6 and TCP
1094# 'ipv4' if the client is connected via IPv4 and TCP
1095# 'unix' if the client is connected via a unix domain socket
1096# 'unknown' otherwise
1097#
1098# @service: The service name of the client's port. This may depends on the
1099# host system's service database so symbolic names should not be
1100# relied on.
1101#
1102# @x509_dname: #optional If x509 authentication is in use, the Distinguished
1103# Name of the client.
1104#
1105# @sasl_username: #optional If SASL authentication is in use, the SASL username
1106# used for authentication.
1107#
1108# Since: 0.14.0
1109##
1110{ 'type': 'VncClientInfo',
1111 'data': {'host': 'str', 'family': 'str', 'service': 'str',
1112 '*x509_dname': 'str', '*sasl_username': 'str'} }
1113
1114##
1115# @VncInfo:
1116#
1117# Information about the VNC session.
1118#
1119# @enabled: true if the VNC server is enabled, false otherwise
1120#
1121# @host: #optional The hostname the VNC server is bound to. This depends on
1122# the name resolution on the host and may be an IP address.
1123#
1124# @family: #optional 'ipv6' if the host is listening for IPv6 connections
1125# 'ipv4' if the host is listening for IPv4 connections
1126# 'unix' if the host is listening on a unix domain socket
1127# 'unknown' otherwise
1128#
1129# @service: #optional The service name of the server's port. This may depends
1130# on the host system's service database so symbolic names should not
1131# be relied on.
1132#
1133# @auth: #optional the current authentication type used by the server
1134# 'none' if no authentication is being used
1135# 'vnc' if VNC authentication is being used
1136# 'vencrypt+plain' if VEncrypt is used with plain text authentication
1137# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
1138# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
1139# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
1140# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
1141# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
1142# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
1143# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
1144# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
1145#
1146# @clients: a list of @VncClientInfo of all currently connected clients
1147#
1148# Since: 0.14.0
1149##
1150{ 'type': 'VncInfo',
1151 'data': {'enabled': 'bool', '*host': 'str', '*family': 'str',
1152 '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
1153
1154##
1155# @query-vnc:
1156#
1157# Returns information about the current VNC server
1158#
1159# Returns: @VncInfo
Luiz Capitulino2b54aa82011-10-17 16:41:22 -02001160#
1161# Since: 0.14.0
1162##
1163{ 'command': 'query-vnc', 'returns': 'VncInfo' }
1164
1165##
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001166# @SpiceChannel
1167#
1168# Information about a SPICE client channel.
1169#
1170# @host: The host name of the client. QEMU tries to resolve this to a DNS name
1171# when possible.
1172#
1173# @family: 'ipv6' if the client is connected via IPv6 and TCP
1174# 'ipv4' if the client is connected via IPv4 and TCP
1175# 'unix' if the client is connected via a unix domain socket
1176# 'unknown' otherwise
1177#
1178# @port: The client's port number.
1179#
1180# @connection-id: SPICE connection id number. All channels with the same id
1181# belong to the same SPICE session.
1182#
Alon Levy419e1bd2012-03-05 15:13:27 +02001183# @connection-type: SPICE channel type number. "1" is the main control
1184# channel, filter for this one if you want to track spice
1185# sessions only
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001186#
Alon Levy419e1bd2012-03-05 15:13:27 +02001187# @channel-id: SPICE channel ID number. Usually "0", might be different when
1188# multiple channels of the same type exist, such as multiple
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001189# display channels in a multihead setup
1190#
1191# @tls: true if the channel is encrypted, false otherwise.
1192#
1193# Since: 0.14.0
1194##
1195{ 'type': 'SpiceChannel',
1196 'data': {'host': 'str', 'family': 'str', 'port': 'str',
1197 'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
1198 'tls': 'bool'} }
1199
1200##
Alon Levy4efee022012-03-29 23:23:14 +02001201# @SpiceQueryMouseMode
1202#
Lei Li6932a692012-08-23 13:14:25 +08001203# An enumeration of Spice mouse states.
Alon Levy4efee022012-03-29 23:23:14 +02001204#
1205# @client: Mouse cursor position is determined by the client.
1206#
1207# @server: Mouse cursor position is determined by the server.
1208#
1209# @unknown: No information is available about mouse mode used by
1210# the spice server.
1211#
1212# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
1213#
1214# Since: 1.1
1215##
1216{ 'enum': 'SpiceQueryMouseMode',
1217 'data': [ 'client', 'server', 'unknown' ] }
1218
1219##
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001220# @SpiceInfo
1221#
1222# Information about the SPICE session.
Laszlo Ersekb80e5602012-07-17 16:17:10 +02001223#
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001224# @enabled: true if the SPICE server is enabled, false otherwise
1225#
Yonit Halperin61c4efe2012-08-21 11:51:58 +03001226# @migrated: true if the last guest migration completed and spice
1227# migration had completed as well. false otherwise.
1228#
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001229# @host: #optional The hostname the SPICE server is bound to. This depends on
1230# the name resolution on the host and may be an IP address.
1231#
1232# @port: #optional The SPICE server's port number.
1233#
1234# @compiled-version: #optional SPICE server version.
1235#
1236# @tls-port: #optional The SPICE server's TLS port number.
1237#
1238# @auth: #optional the current authentication type used by the server
Alon Levy419e1bd2012-03-05 15:13:27 +02001239# 'none' if no authentication is being used
1240# 'spice' uses SASL or direct TLS authentication, depending on command
1241# line options
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001242#
Alon Levy4efee022012-03-29 23:23:14 +02001243# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
1244# be determined by the client or the server, or unknown if spice
1245# server doesn't provide this information.
1246#
1247# Since: 1.1
1248#
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001249# @channels: a list of @SpiceChannel for each active spice channel
1250#
1251# Since: 0.14.0
1252##
1253{ 'type': 'SpiceInfo',
Yonit Halperin61c4efe2012-08-21 11:51:58 +03001254 'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001255 '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
Alon Levy4efee022012-03-29 23:23:14 +02001256 'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
Luiz Capitulinod1f29642011-10-20 17:01:33 -02001257
1258##
1259# @query-spice
1260#
1261# Returns information about the current SPICE server
1262#
1263# Returns: @SpiceInfo
1264#
1265# Since: 0.14.0
1266##
1267{ 'command': 'query-spice', 'returns': 'SpiceInfo' }
1268
1269##
Luiz Capitulino96637bc2011-10-21 11:41:37 -02001270# @BalloonInfo:
1271#
1272# Information about the guest balloon device.
1273#
1274# @actual: the number of bytes the balloon currently contains
1275#
Luiz Capitulino96637bc2011-10-21 11:41:37 -02001276# Since: 0.14.0
1277#
Luiz Capitulino96637bc2011-10-21 11:41:37 -02001278##
Luiz Capitulino01ceb972012-12-03 15:56:41 -02001279{ 'type': 'BalloonInfo', 'data': {'actual': 'int' } }
Luiz Capitulino96637bc2011-10-21 11:41:37 -02001280
1281##
1282# @query-balloon:
1283#
1284# Return information about the balloon device.
1285#
1286# Returns: @BalloonInfo on success
1287# If the balloon driver is enabled but not functional because the KVM
1288# kernel module cannot support it, KvmMissingCap
1289# If no balloon device is present, DeviceNotActive
1290#
1291# Since: 0.14.0
1292##
1293{ 'command': 'query-balloon', 'returns': 'BalloonInfo' }
1294
1295##
Luiz Capitulino79627472011-10-21 14:15:33 -02001296# @PciMemoryRange:
1297#
1298# A PCI device memory region
1299#
1300# @base: the starting address (guest physical)
1301#
1302# @limit: the ending address (guest physical)
1303#
1304# Since: 0.14.0
1305##
1306{ 'type': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
1307
1308##
1309# @PciMemoryRegion
1310#
1311# Information about a PCI device I/O region.
1312#
1313# @bar: the index of the Base Address Register for this region
1314#
1315# @type: 'io' if the region is a PIO region
1316# 'memory' if the region is a MMIO region
1317#
1318# @prefetch: #optional if @type is 'memory', true if the memory is prefetchable
1319#
1320# @mem_type_64: #optional if @type is 'memory', true if the BAR is 64-bit
1321#
1322# Since: 0.14.0
1323##
1324{ 'type': 'PciMemoryRegion',
1325 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
1326 '*prefetch': 'bool', '*mem_type_64': 'bool' } }
1327
1328##
1329# @PciBridgeInfo:
1330#
1331# Information about a PCI Bridge device
1332#
1333# @bus.number: primary bus interface number. This should be the number of the
1334# bus the device resides on.
1335#
1336# @bus.secondary: secondary bus interface number. This is the number of the
1337# main bus for the bridge
1338#
1339# @bus.subordinate: This is the highest number bus that resides below the
1340# bridge.
1341#
1342# @bus.io_range: The PIO range for all devices on this bridge
1343#
1344# @bus.memory_range: The MMIO range for all devices on this bridge
1345#
1346# @bus.prefetchable_range: The range of prefetchable MMIO for all devices on
1347# this bridge
1348#
1349# @devices: a list of @PciDeviceInfo for each device on this bridge
1350#
1351# Since: 0.14.0
1352##
1353{ 'type': 'PciBridgeInfo',
1354 'data': {'bus': { 'number': 'int', 'secondary': 'int', 'subordinate': 'int',
1355 'io_range': 'PciMemoryRange',
1356 'memory_range': 'PciMemoryRange',
1357 'prefetchable_range': 'PciMemoryRange' },
1358 '*devices': ['PciDeviceInfo']} }
1359
1360##
1361# @PciDeviceInfo:
1362#
1363# Information about a PCI device
1364#
1365# @bus: the bus number of the device
1366#
1367# @slot: the slot the device is located in
1368#
1369# @function: the function of the slot used by the device
1370#
1371# @class_info.desc: #optional a string description of the device's class
1372#
1373# @class_info.class: the class code of the device
1374#
1375# @id.device: the PCI device id
1376#
1377# @id.vendor: the PCI vendor id
1378#
1379# @irq: #optional if an IRQ is assigned to the device, the IRQ number
1380#
1381# @qdev_id: the device name of the PCI device
1382#
1383# @pci_bridge: if the device is a PCI bridge, the bridge information
1384#
1385# @regions: a list of the PCI I/O regions associated with the device
1386#
1387# Notes: the contents of @class_info.desc are not stable and should only be
1388# treated as informational.
1389#
1390# Since: 0.14.0
1391##
1392{ 'type': 'PciDeviceInfo',
1393 'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
1394 'class_info': {'*desc': 'str', 'class': 'int'},
1395 'id': {'device': 'int', 'vendor': 'int'},
1396 '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo',
1397 'regions': ['PciMemoryRegion']} }
1398
1399##
1400# @PciInfo:
1401#
1402# Information about a PCI bus
1403#
1404# @bus: the bus index
1405#
1406# @devices: a list of devices on this bus
1407#
1408# Since: 0.14.0
1409##
1410{ 'type': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
1411
1412##
1413# @query-pci:
1414#
1415# Return information about the PCI bus topology of the guest.
1416#
1417# Returns: a list of @PciInfo for each PCI bus
1418#
1419# Since: 0.14.0
1420##
1421{ 'command': 'query-pci', 'returns': ['PciInfo'] }
1422
1423##
Paolo Bonzini92aa5c62012-09-28 17:22:55 +02001424# @BlockdevOnError:
1425#
1426# An enumeration of possible behaviors for errors on I/O operations.
1427# The exact meaning depends on whether the I/O was initiated by a guest
1428# or by a block job
1429#
1430# @report: for guest operations, report the error to the guest;
1431# for jobs, cancel the job
1432#
1433# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
1434# or BLOCK_JOB_ERROR)
1435#
1436# @enospc: same as @stop on ENOSPC, same as @report otherwise.
1437#
1438# @stop: for guest operations, stop the virtual machine;
1439# for jobs, pause the job
1440#
1441# Since: 1.3
1442##
1443{ 'enum': 'BlockdevOnError',
1444 'data': ['report', 'ignore', 'enospc', 'stop'] }
1445
1446##
Paolo Bonzini893f7eb2012-10-18 16:49:23 +02001447# @MirrorSyncMode:
1448#
1449# An enumeration of possible behaviors for the initial synchronization
1450# phase of storage mirroring.
1451#
1452# @top: copies data in the topmost image to the destination
1453#
1454# @full: copies data from all images to the destination
1455#
1456# @none: only copy data written from now on
1457#
1458# Since: 1.3
1459##
1460{ 'enum': 'MirrorSyncMode',
1461 'data': ['top', 'full', 'none'] }
1462
1463##
Fam Zheng2cb5b222013-10-08 17:29:39 +08001464# @BlockJobType:
1465#
1466# Type of a block job.
1467#
1468# @commit: block commit job type, see "block-commit"
1469#
1470# @stream: block stream job type, see "block-stream"
1471#
1472# @mirror: drive mirror job type, see "drive-mirror"
1473#
1474# @backup: drive backup job type, see "drive-backup"
1475#
1476# Since: 1.7
1477##
1478{ 'enum': 'BlockJobType',
1479 'data': ['commit', 'stream', 'mirror', 'backup'] }
1480
1481##
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00001482# @BlockJobInfo:
1483#
1484# Information about a long-running block device operation.
1485#
1486# @type: the job type ('stream' for image streaming)
1487#
1488# @device: the block device name
1489#
1490# @len: the maximum progress value
1491#
Paolo Bonzini8d658832012-09-28 17:22:49 +02001492# @busy: false if the job is known to be in a quiescent state, with
1493# no pending I/O. Since 1.3.
1494#
Paolo Bonzini8acc72a2012-09-28 17:22:50 +02001495# @paused: whether the job is paused or, if @busy is true, will
1496# pause itself as soon as possible. Since 1.3.
1497#
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00001498# @offset: the current progress value
1499#
1500# @speed: the rate limit, bytes per second
1501#
Paolo Bonzini32c81a42012-09-28 17:22:58 +02001502# @io-status: the status of the job (since 1.3)
1503#
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00001504# Since: 1.1
1505##
1506{ 'type': 'BlockJobInfo',
1507 'data': {'type': 'str', 'device': 'str', 'len': 'int',
Paolo Bonzini32c81a42012-09-28 17:22:58 +02001508 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int',
1509 'io-status': 'BlockDeviceIoStatus'} }
Stefan Hajnoczifb5458c2012-01-18 14:40:49 +00001510
1511##
1512# @query-block-jobs:
1513#
1514# Return information about long-running block device operations.
1515#
1516# Returns: a list of @BlockJobInfo for each active block job
1517#
1518# Since: 1.1
1519##
1520{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] }
1521
1522##
Luiz Capitulino7a7f3252011-09-15 14:20:28 -03001523# @quit:
1524#
1525# This command will cause the QEMU process to exit gracefully. While every
1526# attempt is made to send the QMP response before terminating, this is not
1527# guaranteed. When using this interface, a premature EOF would not be
1528# unexpected.
1529#
1530# Since: 0.14.0
1531##
1532{ 'command': 'quit' }
Luiz Capitulino5f158f22011-09-15 14:34:39 -03001533
1534##
1535# @stop:
1536#
1537# Stop all guest VCPU execution.
1538#
1539# Since: 0.14.0
1540#
1541# Notes: This function will succeed even if the guest is already in the stopped
Paolo Bonzini1e998142012-10-23 14:54:21 +02001542# state. In "inmigrate" state, it will ensure that the guest
1543# remains paused once migration finishes, as if the -S option was
1544# passed on the command line.
Luiz Capitulino5f158f22011-09-15 14:34:39 -03001545##
1546{ 'command': 'stop' }
Luiz Capitulino38d22652011-09-15 14:41:46 -03001547
1548##
1549# @system_reset:
1550#
1551# Performs a hard reset of a guest.
1552#
1553# Since: 0.14.0
1554##
1555{ 'command': 'system_reset' }
Luiz Capitulino5bc465e2011-09-28 11:06:15 -03001556
1557##
1558# @system_powerdown:
1559#
1560# Requests that a guest perform a powerdown operation.
1561#
1562# Since: 0.14.0
1563#
1564# Notes: A guest may or may not respond to this command. This command
1565# returning does not indicate that a guest has accepted the request or
1566# that it has shut down. Many guests will respond to this command by
1567# prompting the user in some way.
1568##
1569{ 'command': 'system_powerdown' }
Luiz Capitulino755f1962011-10-06 14:31:39 -03001570
1571##
1572# @cpu:
1573#
1574# This command is a nop that is only provided for the purposes of compatibility.
1575#
1576# Since: 0.14.0
1577#
1578# Notes: Do not use this command.
1579##
1580{ 'command': 'cpu', 'data': {'index': 'int'} }
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -02001581
1582##
Igor Mammedov69ca3ea2013-04-30 15:41:25 +02001583# @cpu-add
1584#
1585# Adds CPU with specified ID
1586#
1587# @id: ID of CPU to be created, valid values [0..max_cpus)
1588#
1589# Returns: Nothing on success
1590#
1591# Since 1.5
1592##
1593{ 'command': 'cpu-add', 'data': {'id': 'int'} }
1594
1595##
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -02001596# @memsave:
1597#
1598# Save a portion of guest memory to a file.
1599#
1600# @val: the virtual address of the guest to start from
1601#
1602# @size: the size of memory region to save
1603#
1604# @filename: the file to save the memory to as binary data
1605#
1606# @cpu-index: #optional the index of the virtual CPU to use for translating the
1607# virtual address (defaults to CPU 0)
1608#
1609# Returns: Nothing on success
Luiz Capitulino0cfd6a92011-11-22 16:32:37 -02001610#
1611# Since: 0.14.0
1612#
1613# Notes: Errors were not reliably returned until 1.1
1614##
1615{ 'command': 'memsave',
1616 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
Luiz Capitulino6d3962b2011-11-22 17:26:46 -02001617
1618##
1619# @pmemsave:
1620#
1621# Save a portion of guest physical memory to a file.
1622#
1623# @val: the physical address of the guest to start from
1624#
1625# @size: the size of memory region to save
1626#
1627# @filename: the file to save the memory to as binary data
1628#
1629# Returns: Nothing on success
Luiz Capitulino6d3962b2011-11-22 17:26:46 -02001630#
1631# Since: 0.14.0
1632#
1633# Notes: Errors were not reliably returned until 1.1
1634##
1635{ 'command': 'pmemsave',
1636 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
Luiz Capitulinoe42e8182011-11-22 17:58:31 -02001637
1638##
1639# @cont:
1640#
1641# Resume guest VCPU execution.
1642#
1643# Since: 0.14.0
1644#
1645# Returns: If successful, nothing
Luiz Capitulinoe42e8182011-11-22 17:58:31 -02001646# If QEMU was started with an encrypted block device and a key has
1647# not yet been set, DeviceEncrypted.
1648#
Paolo Bonzini1e998142012-10-23 14:54:21 +02001649# Notes: This command will succeed if the guest is currently running. It
1650# will also succeed if the guest is in the "inmigrate" state; in
1651# this case, the effect of the command is to make sure the guest
1652# starts once migration finishes, removing the effect of the -S
1653# command line option if it was passed.
Luiz Capitulinoe42e8182011-11-22 17:58:31 -02001654##
1655{ 'command': 'cont' }
1656
Luiz Capitulinoab49ab52011-11-23 12:55:53 -02001657##
Gerd Hoffmann9b9df252012-02-23 13:45:21 +01001658# @system_wakeup:
1659#
1660# Wakeup guest from suspend. Does nothing in case the guest isn't suspended.
1661#
1662# Since: 1.1
1663#
1664# Returns: nothing.
1665##
1666{ 'command': 'system_wakeup' }
1667
1668##
Luiz Capitulinoab49ab52011-11-23 12:55:53 -02001669# @inject-nmi:
1670#
1671# Injects an Non-Maskable Interrupt into all guest's VCPUs.
1672#
1673# Returns: If successful, nothing
Luiz Capitulinoab49ab52011-11-23 12:55:53 -02001674#
1675# Since: 0.14.0
1676#
1677# Notes: Only x86 Virtual Machines support this command.
1678##
1679{ 'command': 'inject-nmi' }
Luiz Capitulino4b371562011-11-23 13:11:55 -02001680
1681##
1682# @set_link:
1683#
1684# Sets the link status of a virtual network adapter.
1685#
1686# @name: the device name of the virtual network adapter
1687#
1688# @up: true to set the link status to be up
1689#
1690# Returns: Nothing on success
1691# If @name is not a valid network device, DeviceNotFound
1692#
1693# Since: 0.14.0
1694#
1695# Notes: Not all network adapters support setting link status. This command
1696# will succeed even if the network adapter does not support link status
1697# notification.
1698##
1699{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
Luiz Capitulinoa4dea8a2011-11-23 13:28:21 -02001700
1701##
1702# @block_passwd:
1703#
1704# This command sets the password of a block device that has not been open
1705# with a password and requires one.
1706#
1707# The two cases where this can happen are a block device is created through
1708# QEMU's initial command line or a block device is changed through the legacy
1709# @change interface.
1710#
1711# In the event that the block device is created through the initial command
1712# line, the VM will start in the stopped state regardless of whether '-S' is
1713# used. The intention is for a management tool to query the block devices to
1714# determine which ones are encrypted, set the passwords with this command, and
1715# then start the guest with the @cont command.
1716#
Benoît Canet12d3ba82014-01-23 21:31:35 +01001717# Either @device or @node-name must be set but not both.
1718#
1719# @device: #optional the name of the block backend device to set the password on
1720#
1721# @node-name: #optional graph node name to set the password on (Since 2.0)
Luiz Capitulinoa4dea8a2011-11-23 13:28:21 -02001722#
1723# @password: the password to use for the device
1724#
1725# Returns: nothing on success
1726# If @device is not a valid block device, DeviceNotFound
1727# If @device is not encrypted, DeviceNotEncrypted
Luiz Capitulinoa4dea8a2011-11-23 13:28:21 -02001728#
1729# Notes: Not all block formats support encryption and some that do are not
1730# able to validate that a password is correct. Disk corruption may
1731# occur if an invalid password is specified.
1732#
1733# Since: 0.14.0
1734##
Benoît Canet12d3ba82014-01-23 21:31:35 +01001735{ 'command': 'block_passwd', 'data': {'*device': 'str',
1736 '*node-name': 'str', 'password': 'str'} }
Luiz Capitulinod72f3262011-11-25 14:38:09 -02001737
1738##
1739# @balloon:
1740#
1741# Request the balloon driver to change its balloon size.
1742#
1743# @value: the target size of the balloon in bytes
1744#
1745# Returns: Nothing on success
1746# If the balloon driver is enabled but not functional because the KVM
1747# kernel module cannot support it, KvmMissingCap
1748# If no balloon device is present, DeviceNotActive
1749#
1750# Notes: This command just issues a request to the guest. When it returns,
1751# the balloon size may not have changed. A guest can change the balloon
1752# size independent of this command.
1753#
1754# Since: 0.14.0
1755##
1756{ 'command': 'balloon', 'data': {'value': 'int'} }
Luiz Capitulino5e7caac2011-11-25 14:57:10 -02001757
1758##
1759# @block_resize
1760#
1761# Resize a block image while a guest is running.
1762#
Benoît Canet3b1dbd12014-01-23 21:31:37 +01001763# Either @device or @node-name must be set but not both.
1764#
1765# @device: #optional the name of the device to get the image resized
1766#
1767# @node-name: #optional graph node name to get the image resized (Since 2.0)
Luiz Capitulino5e7caac2011-11-25 14:57:10 -02001768#
1769# @size: new image size in bytes
1770#
1771# Returns: nothing on success
1772# If @device is not a valid block device, DeviceNotFound
Luiz Capitulino5e7caac2011-11-25 14:57:10 -02001773#
1774# Since: 0.14.0
1775##
Benoît Canet3b1dbd12014-01-23 21:31:37 +01001776{ 'command': 'block_resize', 'data': { '*device': 'str',
1777 '*node-name': 'str',
1778 'size': 'int' }}
Luiz Capitulino6106e242011-11-25 16:15:19 -02001779
1780##
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001781# @NewImageMode
1782#
1783# An enumeration that tells QEMU how to set the backing file path in
1784# a new image file.
1785#
1786# @existing: QEMU should look for an existing image file.
1787#
1788# @absolute-paths: QEMU should create a new image with absolute paths
Max Reitz1296c2f2013-11-07 19:47:48 +01001789# for the backing file. If there is no backing file available, the new
1790# image will not be backed either.
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001791#
1792# Since: 1.1
1793##
Amos Kongad0f1712013-06-19 17:23:27 +08001794{ 'enum': 'NewImageMode',
Paolo Bonzinibc8b0942012-03-06 18:55:58 +01001795 'data': [ 'existing', 'absolute-paths' ] }
1796
1797##
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001798# @BlockdevSnapshot
Jeff Cody8802d1f2012-02-28 15:54:06 -05001799#
Benoît Canet0901f672014-01-23 21:31:38 +01001800# Either @device or @node-name must be set but not both.
1801#
1802# @device: #optional the name of the device to generate the snapshot from.
1803#
1804# @node-name: #optional graph node name to generate the snapshot from (Since 2.0)
Jeff Cody8802d1f2012-02-28 15:54:06 -05001805#
1806# @snapshot-file: the target of the new image. A new file will be created.
1807#
Benoît Canet0901f672014-01-23 21:31:38 +01001808# @snapshot-node-name: #optional the graph node name of the new image (Since 2.0)
1809#
Jeff Cody8802d1f2012-02-28 15:54:06 -05001810# @format: #optional the format of the snapshot image, default is 'qcow2'.
Paolo Bonzini6cc2a412012-03-06 18:55:59 +01001811#
1812# @mode: #optional whether and how QEMU should create a new image, default is
Paolo Bonzini8bde9b62012-09-26 16:34:29 +02001813# 'absolute-paths'.
Jeff Cody8802d1f2012-02-28 15:54:06 -05001814##
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001815{ 'type': 'BlockdevSnapshot',
Benoît Canet0901f672014-01-23 21:31:38 +01001816 'data': { '*device': 'str', '*node-name': 'str',
1817 'snapshot-file': 'str', '*snapshot-node-name': 'str',
1818 '*format': 'str', '*mode': 'NewImageMode' } }
Jeff Cody8802d1f2012-02-28 15:54:06 -05001819
1820##
Wenchao Xiabbe86012013-09-11 14:04:34 +08001821# @BlockdevSnapshotInternal
1822#
1823# @device: the name of the device to generate the snapshot from
1824#
1825# @name: the name of the internal snapshot to be created
1826#
1827# Notes: In transaction, if @name is empty, or any snapshot matching @name
1828# exists, the operation will fail. Only some image formats support it,
1829# for example, qcow2, rbd, and sheepdog.
1830#
1831# Since: 1.7
1832##
1833{ 'type': 'BlockdevSnapshotInternal',
1834 'data': { 'device': 'str', 'name': 'str' } }
1835
1836##
Stefan Hajnoczi3037f362013-06-24 17:13:17 +02001837# @DriveBackup
1838#
1839# @device: the name of the device which should be copied.
1840#
1841# @target: the target of the new image. If the file exists, or if it
1842# is a device, the existing file/device will be used as the new
1843# destination. If it does not exist, a new file will be created.
1844#
1845# @format: #optional the format of the new destination, default is to
1846# probe if @mode is 'existing', else the format of the source
1847#
Stefan Hajnoczib53169e2013-06-26 14:11:57 +02001848# @sync: what parts of the disk image should be copied to the destination
1849# (all the disk, only the sectors allocated in the topmost image, or
1850# only new I/O).
1851#
Stefan Hajnoczi3037f362013-06-24 17:13:17 +02001852# @mode: #optional whether and how QEMU should create a new image, default is
1853# 'absolute-paths'.
1854#
1855# @speed: #optional the maximum speed, in bytes per second
1856#
1857# @on-source-error: #optional the action to take on an error on the source,
1858# default 'report'. 'stop' and 'enospc' can only be used
1859# if the block device supports io-status (see BlockInfo).
1860#
1861# @on-target-error: #optional the action to take on an error on the target,
1862# default 'report' (no limitations, since this applies to
1863# a different block device than @device).
1864#
1865# Note that @on-source-error and @on-target-error only affect background I/O.
1866# If an error occurs during a guest write request, the device's rerror/werror
1867# actions will be used.
1868#
1869# Since: 1.6
1870##
1871{ 'type': 'DriveBackup',
1872 'data': { 'device': 'str', 'target': 'str', '*format': 'str',
Stefan Hajnoczib53169e2013-06-26 14:11:57 +02001873 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode',
1874 '*speed': 'int',
Stefan Hajnoczi3037f362013-06-24 17:13:17 +02001875 '*on-source-error': 'BlockdevOnError',
1876 '*on-target-error': 'BlockdevOnError' } }
1877
1878##
Stefan Hajnoczi78b18b72013-06-24 17:13:18 +02001879# @Abort
1880#
1881# This action can be used to test transaction failure.
1882#
1883# Since: 1.6
1884###
1885{ 'type': 'Abort',
1886 'data': { } }
1887
1888##
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001889# @TransactionAction
Jeff Cody8802d1f2012-02-28 15:54:06 -05001890#
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001891# A discriminated record of operations that can be performed with
1892# @transaction.
1893##
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001894{ 'union': 'TransactionAction',
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001895 'data': {
Stefan Hajnoczi3037f362013-06-24 17:13:17 +02001896 'blockdev-snapshot-sync': 'BlockdevSnapshot',
Stefan Hajnoczi78b18b72013-06-24 17:13:18 +02001897 'drive-backup': 'DriveBackup',
Wenchao Xiabbe86012013-09-11 14:04:34 +08001898 'abort': 'Abort',
1899 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternal'
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001900 } }
1901
1902##
1903# @transaction
1904#
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001905# Executes a number of transactionable QMP commands atomically. If any
1906# operation fails, then the entire set of actions will be abandoned and the
1907# appropriate error returned.
Jeff Cody8802d1f2012-02-28 15:54:06 -05001908#
1909# List of:
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001910# @TransactionAction: information needed for the respective operation
Jeff Cody8802d1f2012-02-28 15:54:06 -05001911#
1912# Returns: nothing on success
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001913# Errors depend on the operations of the transaction
Jeff Cody8802d1f2012-02-28 15:54:06 -05001914#
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001915# Note: The transaction aborts on the first failure. Therefore, there will be
1916# information on only one failed operation returned in an error condition, and
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001917# subsequent actions will not have been attempted.
1918#
1919# Since 1.1
Jeff Cody8802d1f2012-02-28 15:54:06 -05001920##
Paolo Bonzini52e7c242012-03-06 18:55:57 +01001921{ 'command': 'transaction',
Kevin Wolfc8a83e82013-05-13 10:43:43 +02001922 'data': { 'actions': [ 'TransactionAction' ] } }
Jeff Cody8802d1f2012-02-28 15:54:06 -05001923
1924##
Luiz Capitulino6106e242011-11-25 16:15:19 -02001925# @blockdev-snapshot-sync
1926#
1927# Generates a synchronous snapshot of a block device.
1928#
Kevin Wolf852ad1a2013-07-01 16:31:52 +02001929# For the arguments, see the documentation of BlockdevSnapshot.
Paolo Bonzini6cc2a412012-03-06 18:55:59 +01001930#
Luiz Capitulino6106e242011-11-25 16:15:19 -02001931# Returns: nothing on success
1932# If @device is not a valid block device, DeviceNotFound
Luiz Capitulino6106e242011-11-25 16:15:19 -02001933#
Luiz Capitulino6106e242011-11-25 16:15:19 -02001934# Since 0.14.0
1935##
1936{ 'command': 'blockdev-snapshot-sync',
Kevin Wolf852ad1a2013-07-01 16:31:52 +02001937 'data': 'BlockdevSnapshot' }
Luiz Capitulinod51a67b2011-11-25 17:52:45 -02001938
1939##
Wenchao Xiaf323bc92013-09-11 14:04:35 +08001940# @blockdev-snapshot-internal-sync
1941#
1942# Synchronously take an internal snapshot of a block device, when the format
1943# of the image used supports it.
1944#
1945# For the arguments, see the documentation of BlockdevSnapshotInternal.
1946#
1947# Returns: nothing on success
1948# If @device is not a valid block device, DeviceNotFound
1949# If any snapshot matching @name exists, or @name is empty,
1950# GenericError
1951# If the format of the image used does not support it,
1952# BlockFormatFeatureNotSupported
1953#
1954# Since 1.7
1955##
1956{ 'command': 'blockdev-snapshot-internal-sync',
1957 'data': 'BlockdevSnapshotInternal' }
1958
1959##
Wenchao Xia44e3e052013-09-11 14:04:36 +08001960# @blockdev-snapshot-delete-internal-sync
1961#
1962# Synchronously delete an internal snapshot of a block device, when the format
1963# of the image used support it. The snapshot is identified by name or id or
1964# both. One of the name or id is required. Return SnapshotInfo for the
1965# successfully deleted snapshot.
1966#
1967# @device: the name of the device to delete the snapshot from
1968#
1969# @id: optional the snapshot's ID to be deleted
1970#
1971# @name: optional the snapshot's name to be deleted
1972#
1973# Returns: SnapshotInfo on success
1974# If @device is not a valid block device, DeviceNotFound
1975# If snapshot not found, GenericError
1976# If the format of the image used does not support it,
1977# BlockFormatFeatureNotSupported
1978# If @id and @name are both not specified, GenericError
1979#
1980# Since 1.7
1981##
1982{ 'command': 'blockdev-snapshot-delete-internal-sync',
1983 'data': { 'device': 'str', '*id': 'str', '*name': 'str'},
1984 'returns': 'SnapshotInfo' }
1985
1986##
Luiz Capitulinod51a67b2011-11-25 17:52:45 -02001987# @human-monitor-command:
1988#
1989# Execute a command on the human monitor and return the output.
1990#
1991# @command-line: the command to execute in the human monitor
1992#
1993# @cpu-index: #optional The CPU to use for commands that require an implicit CPU
1994#
1995# Returns: the output of the command as a string
1996#
1997# Since: 0.14.0
1998#
Stefan Weil59b00962013-10-11 21:34:33 +02001999# Notes: This command only exists as a stop-gap. Its use is highly
Luiz Capitulinod51a67b2011-11-25 17:52:45 -02002000# discouraged. The semantics of this command are not guaranteed.
2001#
2002# Known limitations:
2003#
2004# o This command is stateless, this means that commands that depend
2005# on state information (such as getfd) might not work
2006#
2007# o Commands that prompt the user for data (eg. 'cont' when the block
2008# device is encrypted) don't currently work
2009##
2010{ 'command': 'human-monitor-command',
2011 'data': {'command-line': 'str', '*cpu-index': 'int'},
Laszlo Ersekb80e5602012-07-17 16:17:10 +02002012 'returns': 'str' }
Luiz Capitulino6cdedb02011-11-27 22:54:09 -02002013
2014##
Jeff Codyed61fc12012-09-27 13:29:16 -04002015# @block-commit
2016#
2017# Live commit of data from overlay image nodes into backing nodes - i.e.,
2018# writes data between 'top' and 'base' into 'base'.
2019#
2020# @device: the name of the device
2021#
2022# @base: #optional The file name of the backing image to write data into.
2023# If not specified, this is the deepest backing image
2024#
2025# @top: The file name of the backing image within the image chain,
2026# which contains the topmost data to be committed down.
Jeff Codyed61fc12012-09-27 13:29:16 -04002027#
2028# If top == base, that is an error.
Fam Zheng20a63d22013-12-16 14:45:31 +08002029# If top == active, the job will not be completed by itself,
2030# user needs to complete the job with the block-job-complete
2031# command after getting the ready event. (Since 2.0)
Jeff Codyed61fc12012-09-27 13:29:16 -04002032#
Jeff Cody37222902014-01-24 09:02:37 -05002033# If the base image is smaller than top, then the base image
2034# will be resized to be the same size as top. If top is
2035# smaller than the base image, the base will not be
2036# truncated. If you want the base image size to match the
2037# size of the smaller top, you can safely truncate it
2038# yourself once the commit operation successfully completes.
2039#
Jeff Codyed61fc12012-09-27 13:29:16 -04002040#
2041# @speed: #optional the maximum speed, in bytes per second
2042#
2043# Returns: Nothing on success
2044# If commit or stream is already active on this device, DeviceInUse
2045# If @device does not exist, DeviceNotFound
2046# If image commit is not supported by this device, NotSupported
2047# If @base or @top is invalid, a generic error is returned
Jeff Codyed61fc12012-09-27 13:29:16 -04002048# If @speed is invalid, InvalidParameter
2049#
2050# Since: 1.3
2051#
2052##
2053{ 'command': 'block-commit',
2054 'data': { 'device': 'str', '*base': 'str', 'top': 'str',
2055 '*speed': 'int' } }
2056
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02002057##
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02002058# @drive-backup
2059#
2060# Start a point-in-time copy of a block device to a new destination. The
2061# status of ongoing drive-backup operations can be checked with
2062# query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
2063# The operation can be stopped before it has completed using the
2064# block-job-cancel command.
2065#
Kevin Wolff53cae52013-07-09 10:05:35 +02002066# For the arguments, see the documentation of DriveBackup.
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02002067#
2068# Returns: nothing on success
2069# If @device is not a valid block device, DeviceNotFound
2070#
2071# Since 1.6
2072##
Kevin Wolff53cae52013-07-09 10:05:35 +02002073{ 'command': 'drive-backup', 'data': 'DriveBackup' }
Stefan Hajnoczi99a9add2013-06-24 17:13:14 +02002074
2075##
Benoît Canetc13163f2014-01-23 21:31:34 +01002076# @query-named-block-nodes
2077#
2078# Get the named block driver list
2079#
2080# Returns: the list of BlockDeviceInfo
2081#
2082# Since 2.0
2083##
2084{ 'command': 'query-named-block-nodes', 'returns': [ 'BlockDeviceInfo' ] }
2085
2086##
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02002087# @drive-mirror
2088#
2089# Start mirroring a block device's writes to a new destination.
2090#
2091# @device: the name of the device whose writes should be mirrored.
2092#
2093# @target: the target of the new image. If the file exists, or if it
2094# is a device, the existing file/device will be used as the new
2095# destination. If it does not exist, a new file will be created.
2096#
2097# @format: #optional the format of the new destination, default is to
2098# probe if @mode is 'existing', else the format of the source
2099#
2100# @mode: #optional whether and how QEMU should create a new image, default is
2101# 'absolute-paths'.
2102#
2103# @speed: #optional the maximum speed, in bytes per second
2104#
2105# @sync: what parts of the disk image should be copied to the destination
2106# (all the disk, only the sectors allocated in the topmost image, or
2107# only new I/O).
2108#
Paolo Bonzinieee13df2013-01-21 17:09:46 +01002109# @granularity: #optional granularity of the dirty bitmap, default is 64K
2110# if the image format doesn't have clusters, 4K if the clusters
2111# are smaller than that, else the cluster size. Must be a
2112# power of 2 between 512 and 64M (since 1.4).
2113#
Paolo Bonzini08e4ed62013-01-22 09:03:13 +01002114# @buf-size: #optional maximum amount of data in flight from source to
2115# target (since 1.4).
2116#
Paolo Bonzinib952b552012-10-18 16:49:28 +02002117# @on-source-error: #optional the action to take on an error on the source,
2118# default 'report'. 'stop' and 'enospc' can only be used
2119# if the block device supports io-status (see BlockInfo).
2120#
2121# @on-target-error: #optional the action to take on an error on the target,
2122# default 'report' (no limitations, since this applies to
2123# a different block device than @device).
2124#
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02002125# Returns: nothing on success
2126# If @device is not a valid block device, DeviceNotFound
2127#
2128# Since 1.3
2129##
2130{ 'command': 'drive-mirror',
2131 'data': { 'device': 'str', 'target': 'str', '*format': 'str',
2132 'sync': 'MirrorSyncMode', '*mode': 'NewImageMode',
Paolo Bonzinieee13df2013-01-21 17:09:46 +01002133 '*speed': 'int', '*granularity': 'uint32',
Paolo Bonzini08e4ed62013-01-22 09:03:13 +01002134 '*buf-size': 'int', '*on-source-error': 'BlockdevOnError',
Paolo Bonzinib952b552012-10-18 16:49:28 +02002135 '*on-target-error': 'BlockdevOnError' } }
Paolo Bonzinid9b902d2012-10-18 16:49:24 +02002136
2137##
Luiz Capitulino6cdedb02011-11-27 22:54:09 -02002138# @migrate_cancel
2139#
2140# Cancel the current executing migration process.
2141#
2142# Returns: nothing on success
2143#
2144# Notes: This command succeeds even if there is no migration process running.
2145#
2146# Since: 0.14.0
2147##
2148{ 'command': 'migrate_cancel' }
Luiz Capitulino4f0a9932011-11-27 23:18:01 -02002149
2150##
2151# @migrate_set_downtime
2152#
2153# Set maximum tolerated downtime for migration.
2154#
2155# @value: maximum downtime in seconds
2156#
2157# Returns: nothing on success
2158#
2159# Since: 0.14.0
2160##
2161{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
Luiz Capitulino3dc85382011-11-28 11:59:37 -02002162
2163##
2164# @migrate_set_speed
2165#
2166# Set maximum speed for migration.
2167#
2168# @value: maximum speed in bytes.
2169#
2170# Returns: nothing on success
2171#
2172# Notes: A value lesser than zero will be automatically round up to zero.
2173#
2174# Since: 0.14.0
2175##
2176{ 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002177
2178##
Orit Wasserman9e1ba4c2012-08-06 21:42:54 +03002179# @migrate-set-cache-size
2180#
2181# Set XBZRLE cache size
2182#
2183# @value: cache size in bytes
2184#
2185# The size will be rounded down to the nearest power of 2.
2186# The cache size can be modified before and during ongoing migration
2187#
2188# Returns: nothing on success
2189#
2190# Since: 1.2
2191##
2192{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} }
2193
2194##
2195# @query-migrate-cache-size
2196#
2197# query XBZRLE cache size
2198#
2199# Returns: XBZRLE cache size in bytes
2200#
2201# Since: 1.2
2202##
2203{ 'command': 'query-migrate-cache-size', 'returns': 'int' }
2204
2205##
Alon Levyd03ee402012-03-05 15:13:28 +02002206# @ObjectPropertyInfo:
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002207#
2208# @name: the name of the property
2209#
2210# @type: the type of the property. This will typically come in one of four
2211# forms:
2212#
2213# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
2214# These types are mapped to the appropriate JSON type.
2215#
2216# 2) A legacy type in the form 'legacy<subtype>' where subtype is the
2217# legacy qdev typename. These types are always treated as strings.
2218#
2219# 3) A child type in the form 'child<subtype>' where subtype is a qdev
2220# device type name. Child properties create the composition tree.
2221#
2222# 4) A link type in the form 'link<subtype>' where subtype is a qdev
2223# device type name. Link properties form the device model graph.
2224#
Anthony Liguori51920822012-08-10 11:04:10 -05002225# Since: 1.2
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002226##
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002227{ 'type': 'ObjectPropertyInfo',
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002228 'data': { 'name': 'str', 'type': 'str' } }
2229
2230##
2231# @qom-list:
2232#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002233# This command will list any properties of a object given a path in the object
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002234# model.
2235#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002236# @path: the path within the object model. See @qom-get for a description of
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002237# this parameter.
2238#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002239# Returns: a list of @ObjectPropertyInfo that describe the properties of the
2240# object.
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002241#
Anthony Liguori51920822012-08-10 11:04:10 -05002242# Since: 1.2
Anthony Liguorib4b12c62011-12-12 14:29:34 -06002243##
2244{ 'command': 'qom-list',
2245 'data': { 'path': 'str' },
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002246 'returns': [ 'ObjectPropertyInfo' ] }
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002247
2248##
2249# @qom-get:
2250#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002251# This command will get a property from a object model path and return the
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002252# value.
2253#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002254# @path: The path within the object model. There are two forms of supported
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002255# paths--absolute and partial paths.
2256#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002257# Absolute paths are derived from the root object and can follow child<>
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002258# or link<> properties. Since they can follow link<> properties, they
2259# can be arbitrarily long. Absolute paths look like absolute filenames
2260# and are prefixed with a leading slash.
2261#
2262# Partial paths look like relative filenames. They do not begin
2263# with a prefix. The matching rules for partial paths are subtle but
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002264# designed to make specifying objects easy. At each level of the
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002265# composition tree, the partial path is matched as an absolute path.
2266# The first match is not returned. At least two matches are searched
2267# for. A successful result is only returned if only one match is
2268# found. If more than one match is found, a flag is return to
2269# indicate that the match was ambiguous.
2270#
2271# @property: The property name to read
2272#
2273# Returns: The property value. The type depends on the property type. legacy<>
2274# properties are returned as #str. child<> and link<> properties are
2275# returns as #str pathnames. All integer property types (u8, u16, etc)
2276# are returned as #int.
2277#
Anthony Liguori51920822012-08-10 11:04:10 -05002278# Since: 1.2
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002279##
2280{ 'command': 'qom-get',
2281 'data': { 'path': 'str', 'property': 'str' },
2282 'returns': 'visitor',
2283 'gen': 'no' }
2284
2285##
2286# @qom-set:
2287#
Anthony Liguori57c9faf2012-01-30 08:55:55 -06002288# This command will set a property from a object model path.
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002289#
2290# @path: see @qom-get for a description of this parameter
2291#
2292# @property: the property name to set
2293#
2294# @value: a value who's type is appropriate for the property type. See @qom-get
2295# for a description of type mapping.
2296#
Anthony Liguori51920822012-08-10 11:04:10 -05002297# Since: 1.2
Anthony Liguorieb6e8ea2011-12-12 14:29:35 -06002298##
2299{ 'command': 'qom-set',
2300 'data': { 'path': 'str', 'property': 'str', 'value': 'visitor' },
2301 'gen': 'no' }
Luiz Capitulinofbf796f2011-12-07 11:17:51 -02002302
2303##
2304# @set_password:
2305#
2306# Sets the password of a remote display session.
2307#
2308# @protocol: `vnc' to modify the VNC server password
2309# `spice' to modify the Spice server password
2310#
2311# @password: the new password
2312#
2313# @connected: #optional how to handle existing clients when changing the
Laszlo Ersekb80e5602012-07-17 16:17:10 +02002314# password. If nothing is specified, defaults to `keep'
Luiz Capitulinofbf796f2011-12-07 11:17:51 -02002315# `fail' to fail the command if clients are connected
2316# `disconnect' to disconnect existing clients
2317# `keep' to maintain existing clients
2318#
2319# Returns: Nothing on success
2320# If Spice is not enabled, DeviceNotFound
Luiz Capitulinofbf796f2011-12-07 11:17:51 -02002321#
2322# Since: 0.14.0
2323##
2324{ 'command': 'set_password',
2325 'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
Luiz Capitulino9ad53722011-12-07 11:47:57 -02002326
2327##
2328# @expire_password:
2329#
2330# Expire the password of a remote display server.
2331#
2332# @protocol: the name of the remote display protocol `vnc' or `spice'
2333#
2334# @time: when to expire the password.
2335# `now' to expire the password immediately
2336# `never' to cancel password expiration
2337# `+INT' where INT is the number of seconds from now (integer)
2338# `INT' where INT is the absolute time in seconds
2339#
2340# Returns: Nothing on success
2341# If @protocol is `spice' and Spice is not active, DeviceNotFound
Luiz Capitulino9ad53722011-12-07 11:47:57 -02002342#
2343# Since: 0.14.0
2344#
2345# Notes: Time is relative to the server and currently there is no way to
2346# coordinate server time with client time. It is not recommended to
2347# use the absolute time version of the @time parameter unless you're
2348# sure you are on the same machine as the QEMU instance.
2349##
2350{ 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
Luiz Capitulinoc245b6a2011-12-07 16:02:36 -02002351
2352##
2353# @eject:
2354#
2355# Ejects a device from a removable drive.
2356#
2357# @device: The name of the device
2358#
2359# @force: @optional If true, eject regardless of whether the drive is locked.
2360# If not specified, the default value is false.
2361#
2362# Returns: Nothing on success
2363# If @device is not a valid block device, DeviceNotFound
Luiz Capitulinoc245b6a2011-12-07 16:02:36 -02002364#
2365# Notes: Ejecting a device will no media results in success
2366#
2367# Since: 0.14.0
2368##
2369{ 'command': 'eject', 'data': {'device': 'str', '*force': 'bool'} }
Luiz Capitulino270b2432011-12-08 11:45:55 -02002370
2371##
2372# @change-vnc-password:
2373#
2374# Change the VNC server password.
2375#
2376# @target: the new password to use with VNC authentication
2377#
2378# Since: 1.1
2379#
2380# Notes: An empty password in this command will set the password to the empty
2381# string. Existing clients are unaffected by executing this command.
2382##
2383{ 'command': 'change-vnc-password', 'data': {'password': 'str'} }
Luiz Capitulino333a96e2011-12-08 11:13:50 -02002384
2385##
2386# @change:
2387#
2388# This command is multiple commands multiplexed together.
2389#
2390# @device: This is normally the name of a block device but it may also be 'vnc'.
2391# when it's 'vnc', then sub command depends on @target
2392#
2393# @target: If @device is a block device, then this is the new filename.
2394# If @device is 'vnc', then if the value 'password' selects the vnc
2395# change password command. Otherwise, this specifies a new server URI
2396# address to listen to for VNC connections.
2397#
2398# @arg: If @device is a block device, then this is an optional format to open
2399# the device with.
2400# If @device is 'vnc' and @target is 'password', this is the new VNC
2401# password to set. If this argument is an empty string, then no future
2402# logins will be allowed.
2403#
2404# Returns: Nothing on success.
2405# If @device is not a valid block device, DeviceNotFound
Luiz Capitulino333a96e2011-12-08 11:13:50 -02002406# If the new block device is encrypted, DeviceEncrypted. Note that
2407# if this error is returned, the device has been opened successfully
2408# and an additional call to @block_passwd is required to set the
2409# device's password. The behavior of reads and writes to the block
2410# device between when these calls are executed is undefined.
2411#
2412# Notes: It is strongly recommended that this interface is not used especially
2413# for changing block devices.
2414#
2415# Since: 0.14.0
2416##
2417{ 'command': 'change',
2418 'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
Luiz Capitulino80047da2011-12-14 16:49:14 -02002419
2420##
2421# @block_set_io_throttle:
2422#
2423# Change I/O throttle limits for a block drive.
2424#
2425# @device: The name of the device
2426#
2427# @bps: total throughput limit in bytes per second
2428#
2429# @bps_rd: read throughput limit in bytes per second
2430#
2431# @bps_wr: write throughput limit in bytes per second
2432#
2433# @iops: total I/O operations per second
2434#
2435# @ops_rd: read I/O operations per second
2436#
2437# @iops_wr: write I/O operations per second
2438#
Benoît Canet3e9fab62013-09-02 14:14:40 +02002439# @bps_max: #optional total max in bytes (Since 1.7)
2440#
2441# @bps_rd_max: #optional read max in bytes (Since 1.7)
2442#
2443# @bps_wr_max: #optional write max in bytes (Since 1.7)
2444#
2445# @iops_max: #optional total I/O operations max (Since 1.7)
2446#
2447# @iops_rd_max: #optional read I/O operations max (Since 1.7)
2448#
2449# @iops_wr_max: #optional write I/O operations max (Since 1.7)
2450#
Benoît Canet2024c1d2013-09-02 14:14:41 +02002451# @iops_size: #optional an I/O size in bytes (Since 1.7)
2452#
Luiz Capitulino80047da2011-12-14 16:49:14 -02002453# Returns: Nothing on success
2454# If @device is not a valid block device, DeviceNotFound
Luiz Capitulino80047da2011-12-14 16:49:14 -02002455#
2456# Since: 1.1
Laszlo Ersekb80e5602012-07-17 16:17:10 +02002457##
Luiz Capitulino80047da2011-12-14 16:49:14 -02002458{ 'command': 'block_set_io_throttle',
2459 'data': { 'device': 'str', 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
Benoît Canet3e9fab62013-09-02 14:14:40 +02002460 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int',
2461 '*bps_max': 'int', '*bps_rd_max': 'int',
2462 '*bps_wr_max': 'int', '*iops_max': 'int',
Benoît Canet2024c1d2013-09-02 14:14:41 +02002463 '*iops_rd_max': 'int', '*iops_wr_max': 'int',
2464 '*iops_size': 'int' } }
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00002465
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01002466##
2467# @block-stream:
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00002468#
2469# Copy data from a backing file into a block device.
2470#
2471# The block streaming operation is performed in the background until the entire
2472# backing file has been copied. This command returns immediately once streaming
2473# has started. The status of ongoing block streaming operations can be checked
2474# with query-block-jobs. The operation can be stopped before it has completed
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01002475# using the block-job-cancel command.
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00002476#
2477# If a base file is specified then sectors are not copied from that base file and
2478# its backing chain. When streaming completes the image file will have the base
2479# file as its backing file. This can be used to stream a subset of the backing
2480# file chain instead of flattening the entire image.
2481#
2482# On successful completion the image file is updated to drop the backing file
2483# and the BLOCK_JOB_COMPLETED event is emitted.
2484#
2485# @device: the device name
2486#
2487# @base: #optional the common backing file name
2488#
Stefan Hajnoczic83c66c2012-04-25 16:51:03 +01002489# @speed: #optional the maximum speed, in bytes per second
2490#
Paolo Bonzini1d809092012-09-28 17:22:59 +02002491# @on-error: #optional the action to take on an error (default report).
2492# 'stop' and 'enospc' can only be used if the block device
2493# supports io-status (see BlockInfo). Since 1.3.
2494#
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00002495# Returns: Nothing on success
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00002496# If @device does not exist, DeviceNotFound
Stefan Hajnoczi12bd4512012-01-18 14:40:46 +00002497#
2498# Since: 1.1
2499##
Paolo Bonzini1d809092012-09-28 17:22:59 +02002500{ 'command': 'block-stream',
2501 'data': { 'device': 'str', '*base': 'str', '*speed': 'int',
2502 '*on-error': 'BlockdevOnError' } }
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +00002503
2504##
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01002505# @block-job-set-speed:
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +00002506#
2507# Set maximum speed for a background block operation.
2508#
2509# This command can only be issued when there is an active block job.
2510#
2511# Throttling can be disabled by setting the speed to 0.
2512#
2513# @device: the device name
2514#
Stefan Hajnoczic83c66c2012-04-25 16:51:03 +01002515# @speed: the maximum speed, in bytes per second, or 0 for unlimited.
2516# Defaults to 0.
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +00002517#
2518# Returns: Nothing on success
Paolo Bonzini05290d82012-07-24 13:03:39 +02002519# If no background operation is active on this device, DeviceNotActive
Stefan Hajnoczi2d47c6e2012-01-18 14:40:47 +00002520#
2521# Since: 1.1
2522##
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01002523{ 'command': 'block-job-set-speed',
Stefan Hajnoczi882ec7c2012-04-25 16:51:02 +01002524 'data': { 'device': 'str', 'speed': 'int' } }
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002525
2526##
Stefan Hajnoczidb58f9c2012-04-11 16:27:10 +01002527# @block-job-cancel:
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002528#
Paolo Bonzini05290d82012-07-24 13:03:39 +02002529# Stop an active background block operation.
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002530#
Paolo Bonzini05290d82012-07-24 13:03:39 +02002531# This command returns immediately after marking the active background block
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002532# operation for cancellation. It is an error to call this command if no
2533# operation is in progress.
2534#
2535# The operation will cancel as soon as possible and then emit the
2536# BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when
2537# enumerated using query-block-jobs.
2538#
Paolo Bonzini05290d82012-07-24 13:03:39 +02002539# For streaming, the image file retains its backing file unless the streaming
2540# operation happens to complete just as it is being cancelled. A new streaming
2541# operation can be started at a later time to finish copying all data from the
2542# backing file.
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002543#
2544# @device: the device name
2545#
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02002546# @force: #optional whether to allow cancellation of a paused job (default
2547# false). Since 1.3.
2548#
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002549# Returns: Nothing on success
Paolo Bonzini05290d82012-07-24 13:03:39 +02002550# If no background operation is active on this device, DeviceNotActive
Stefan Hajnoczi370521a2012-01-18 14:40:48 +00002551#
2552# Since: 1.1
2553##
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02002554{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } }
2555
2556##
2557# @block-job-pause:
2558#
2559# Pause an active background block operation.
2560#
2561# This command returns immediately after marking the active background block
2562# operation for pausing. It is an error to call this command if no
2563# operation is in progress. Pausing an already paused job has no cumulative
2564# effect; a single block-job-resume command will resume the job.
2565#
2566# The operation will pause as soon as possible. No event is emitted when
2567# the operation is actually paused. Cancelling a paused job automatically
2568# resumes it.
2569#
2570# @device: the device name
2571#
2572# Returns: Nothing on success
2573# If no background operation is active on this device, DeviceNotActive
2574#
2575# Since: 1.3
2576##
2577{ 'command': 'block-job-pause', 'data': { 'device': 'str' } }
2578
2579##
2580# @block-job-resume:
2581#
2582# Resume an active background block operation.
2583#
2584# This command returns immediately after resuming a paused background block
2585# operation. It is an error to call this command if no operation is in
2586# progress. Resuming an already running job is not an error.
2587#
Paolo Bonzini32c81a42012-09-28 17:22:58 +02002588# This command also clears the error status of the job.
2589#
Paolo Bonzini6e37fb82012-09-28 17:22:51 +02002590# @device: the device name
2591#
2592# Returns: Nothing on success
2593# If no background operation is active on this device, DeviceNotActive
2594#
2595# Since: 1.3
2596##
2597{ 'command': 'block-job-resume', 'data': { 'device': 'str' } }
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06002598
2599##
Paolo Bonziniaeae8832012-10-18 16:49:21 +02002600# @block-job-complete:
2601#
2602# Manually trigger completion of an active background block operation. This
2603# is supported for drive mirroring, where it also switches the device to
Paolo Bonzinia66a2a32012-07-23 15:15:47 +02002604# write to the target path only. The ability to complete is signaled with
2605# a BLOCK_JOB_READY event.
Paolo Bonziniaeae8832012-10-18 16:49:21 +02002606#
2607# This command completes an active background block operation synchronously.
2608# The ordering of this command's return with the BLOCK_JOB_COMPLETED event
2609# is not defined. Note that if an I/O error occurs during the processing of
2610# this command: 1) the command itself will fail; 2) the error will be processed
2611# according to the rerror/werror arguments that were specified when starting
2612# the operation.
2613#
2614# A cancelled or paused job cannot be completed.
2615#
2616# @device: the device name
2617#
2618# Returns: Nothing on success
2619# If no background operation is active on this device, DeviceNotActive
2620#
2621# Since: 1.3
2622##
2623{ 'command': 'block-job-complete', 'data': { 'device': 'str' } }
2624
2625##
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06002626# @ObjectTypeInfo:
2627#
2628# This structure describes a search result from @qom-list-types
2629#
2630# @name: the type name found in the search
2631#
2632# Since: 1.1
2633#
2634# Notes: This command is experimental and may change syntax in future releases.
2635##
2636{ 'type': 'ObjectTypeInfo',
2637 'data': { 'name': 'str' } }
2638
2639##
2640# @qom-list-types:
2641#
2642# This command will return a list of types given search parameters
2643#
2644# @implements: if specified, only return types that implement this type name
2645#
2646# @abstract: if true, include abstract types in the results
2647#
2648# Returns: a list of @ObjectTypeInfo or an empty list if no results are found
2649#
2650# Since: 1.1
Anthony Liguori5eeee3f2011-12-22 14:40:54 -06002651##
2652{ 'command': 'qom-list-types',
2653 'data': { '*implements': 'str', '*abstract': 'bool' },
2654 'returns': [ 'ObjectTypeInfo' ] }
Luiz Capitulinoe1c37d02011-12-05 14:48:01 -02002655
2656##
Anthony Liguori1daa31b2012-08-10 11:04:09 -05002657# @DevicePropertyInfo:
2658#
2659# Information about device properties.
2660#
2661# @name: the name of the property
2662# @type: the typename of the property
2663#
2664# Since: 1.2
2665##
2666{ 'type': 'DevicePropertyInfo',
2667 'data': { 'name': 'str', 'type': 'str' } }
2668
2669##
2670# @device-list-properties:
2671#
2672# List properties associated with a device.
2673#
2674# @typename: the type name of a device
2675#
2676# Returns: a list of DevicePropertyInfo describing a devices properties
2677#
2678# Since: 1.2
2679##
2680{ 'command': 'device-list-properties',
2681 'data': { 'typename': 'str'},
2682 'returns': [ 'DevicePropertyInfo' ] }
2683
2684##
Luiz Capitulinoe1c37d02011-12-05 14:48:01 -02002685# @migrate
2686#
2687# Migrates the current running guest to another Virtual Machine.
2688#
2689# @uri: the Uniform Resource Identifier of the destination VM
2690#
2691# @blk: #optional do block migration (full disk copy)
2692#
2693# @inc: #optional incremental disk copy migration
2694#
2695# @detach: this argument exists only for compatibility reasons and
2696# is ignored by QEMU
2697#
2698# Returns: nothing on success
2699#
2700# Since: 0.14.0
2701##
2702{ 'command': 'migrate',
2703 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
Anthony Liguori33cf6292012-03-19 13:39:42 -05002704
Stefano Stabellinia7ae8352012-01-25 12:24:51 +00002705# @xen-save-devices-state:
2706#
2707# Save the state of all devices to file. The RAM and the block devices
2708# of the VM are not saved by this command.
2709#
2710# @filename: the file to save the state of the devices to as binary
2711# data. See xen-save-devices-state.txt for a description of the binary
2712# format.
2713#
2714# Returns: Nothing on success
Stefano Stabellinia7ae8352012-01-25 12:24:51 +00002715#
2716# Since: 1.1
2717##
2718{ 'command': 'xen-save-devices-state', 'data': {'filename': 'str'} }
Luiz Capitulinoa15fef22012-03-29 12:38:50 -03002719
2720##
Anthony PERARD39f42432012-10-03 13:48:19 +00002721# @xen-set-global-dirty-log
2722#
2723# Enable or disable the global dirty log mode.
2724#
2725# @enable: true to enable, false to disable.
2726#
2727# Returns: nothing
2728#
2729# Since: 1.3
2730##
2731{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
2732
2733##
Luiz Capitulinoa15fef22012-03-29 12:38:50 -03002734# @device_del:
2735#
2736# Remove a device from a guest
2737#
2738# @id: the name of the device
2739#
2740# Returns: Nothing on success
2741# If @id is not a valid device, DeviceNotFound
Luiz Capitulinoa15fef22012-03-29 12:38:50 -03002742#
2743# Notes: When this command completes, the device may not be removed from the
2744# guest. Hot removal is an operation that requires guest cooperation.
2745# This command merely requests that the guest begin the hot removal
Michael S. Tsirkin0402a5d2013-03-06 14:58:59 +02002746# process. Completion of the device removal process is signaled with a
2747# DEVICE_DELETED event. Guest reset will automatically complete removal
2748# for all devices.
Luiz Capitulinoa15fef22012-03-29 12:38:50 -03002749#
2750# Since: 0.14.0
2751##
2752{ 'command': 'device_del', 'data': {'id': 'str'} }
Wen Congyang783e9b42012-05-07 12:10:47 +08002753
2754##
qiaonuohanb53ccc32014-02-18 14:11:36 +08002755# @DumpGuestMemoryFormat:
2756#
2757# An enumeration of guest-memory-dump's format.
2758#
2759# @elf: elf format
2760#
2761# @kdump-zlib: kdump-compressed format with zlib-compressed
2762#
2763# @kdump-lzo: kdump-compressed format with lzo-compressed
2764#
2765# @kdump-snappy: kdump-compressed format with snappy-compressed
2766#
2767# Since: 2.0
2768##
2769{ 'enum': 'DumpGuestMemoryFormat',
2770 'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy' ] }
2771
2772##
Wen Congyang783e9b42012-05-07 12:10:47 +08002773# @dump-guest-memory
2774#
2775# Dump guest's memory to vmcore. It is a synchronous operation that can take
2776# very long depending on the amount of guest memory. This command is only
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002777# supported on i386 and x86_64.
Wen Congyang783e9b42012-05-07 12:10:47 +08002778#
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002779# @paging: if true, do paging to get guest's memory mapping. This allows
Luiz Capitulinod6911802012-09-21 13:10:58 -03002780# using gdb to process the core file.
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002781#
Luiz Capitulinod6911802012-09-21 13:10:58 -03002782# IMPORTANT: this option can make QEMU allocate several gigabytes
2783# of RAM. This can happen for a large guest, or a
2784# malicious guest pretending to be large.
2785#
2786# Also, paging=true has the following limitations:
2787#
2788# 1. The guest may be in a catastrophic state or can have corrupted
2789# memory, which cannot be trusted
2790# 2. The guest can be in real-mode even if paging is enabled. For
2791# example, the guest uses ACPI to sleep, and ACPI sleep state
2792# goes in real-mode
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002793#
Wen Congyang783e9b42012-05-07 12:10:47 +08002794# @protocol: the filename or file descriptor of the vmcore. The supported
Luiz Capitulinod6911802012-09-21 13:10:58 -03002795# protocols are:
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002796#
Luiz Capitulinod6911802012-09-21 13:10:58 -03002797# 1. file: the protocol starts with "file:", and the following
2798# string is the file's path.
2799# 2. fd: the protocol starts with "fd:", and the following string
2800# is the fd's name.
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002801#
Wen Congyang783e9b42012-05-07 12:10:47 +08002802# @begin: #optional if specified, the starting physical address.
Luiz Capitulinof5b0d932012-06-28 11:59:15 -03002803#
Wen Congyang783e9b42012-05-07 12:10:47 +08002804# @length: #optional if specified, the memory size, in bytes. If you don't
Luiz Capitulinod6911802012-09-21 13:10:58 -03002805# want to dump all guest's memory, please specify the start @begin
2806# and @length
Wen Congyang783e9b42012-05-07 12:10:47 +08002807#
qiaonuohanb53ccc32014-02-18 14:11:36 +08002808# @format: #optional if specified, the format of guest memory dump. But non-elf
2809# format is conflict with paging and filter, ie. @paging, @begin and
2810# @length is not allowed to be specified with non-elf @format at the
2811# same time (since 2.0)
2812#
Wen Congyang783e9b42012-05-07 12:10:47 +08002813# Returns: nothing on success
Wen Congyang783e9b42012-05-07 12:10:47 +08002814#
2815# Since: 1.2
2816##
2817{ 'command': 'dump-guest-memory',
2818 'data': { 'paging': 'bool', 'protocol': 'str', '*begin': 'int',
qiaonuohanb53ccc32014-02-18 14:11:36 +08002819 '*length': 'int', '*format': 'DumpGuestMemoryFormat' } }
Luiz Capitulinod6911802012-09-21 13:10:58 -03002820
Luiz Capitulino928059a2012-04-18 17:34:15 -03002821##
qiaonuohan7d6dc7f2014-02-18 14:11:38 +08002822# @DumpGuestMemoryCapability:
2823#
2824# A list of the available formats for dump-guest-memory
2825#
2826# Since: 2.0
2827##
2828{ 'type': 'DumpGuestMemoryCapability',
2829 'data': {
2830 'formats': ['DumpGuestMemoryFormat'] } }
2831
2832##
2833# @query-dump-guest-memory-capability:
2834#
2835# Returns the available formats for dump-guest-memory
2836#
2837# Returns: A @DumpGuestMemoryCapability object listing available formats for
2838# dump-guest-memory
2839#
2840# Since: 2.0
2841##
2842{ 'command': 'query-dump-guest-memory-capability',
2843 'returns': 'DumpGuestMemoryCapability' }
Luiz Capitulino928059a2012-04-18 17:34:15 -03002844
2845##
2846# @netdev_add:
2847#
2848# Add a network backend.
2849#
2850# @type: the type of network backend. Current valid values are 'user', 'tap',
2851# 'vde', 'socket', 'dump' and 'bridge'
2852#
2853# @id: the name of the new network backend
2854#
2855# @props: #optional a list of properties to be passed to the backend in
2856# the format 'name=value', like 'ifname=tap0,script=no'
Luiz Capitulino928059a2012-04-18 17:34:15 -03002857#
2858# Notes: The semantics of @props is not well defined. Future commands will be
2859# introduced that provide stronger typing for backend creation.
2860#
Luiz Capitulino5f964152012-04-16 14:36:32 -03002861# Since: 0.14.0
2862#
2863# Returns: Nothing on success
2864# If @type is not a valid network backend, DeviceNotFound
2865##
2866{ 'command': 'netdev_add',
2867 'data': {'type': 'str', 'id': 'str', '*props': '**'},
2868 'gen': 'no' }
2869
2870##
2871# @netdev_del:
2872#
2873# Remove a network backend.
2874#
Corey Bryant208c9d12012-06-22 14:36:09 -04002875# @id: the name of the network backend to remove
2876#
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02002877# Returns: Nothing on success
2878# If @id is not a valid network backend, DeviceNotFound
2879#
2880# Since: 0.14.0
2881##
2882{ 'command': 'netdev_del', 'data': {'id': 'str'} }
2883
2884##
Paolo Bonzinicff8b2c2013-12-20 23:21:10 +01002885# @object-add:
2886#
2887# Create a QOM object.
2888#
2889# @qom-type: the class name for the object to be created
2890#
2891# @id: the name of the new object
2892#
2893# @props: #optional a dictionary of properties to be passed to the backend
2894#
2895# Returns: Nothing on success
2896# Error if @qom-type is not a valid class name
2897#
2898# Since: 2.0
2899##
2900{ 'command': 'object-add',
2901 'data': {'qom-type': 'str', 'id': 'str', '*props': 'dict'},
2902 'gen': 'no' }
2903
2904##
Paolo Bonziniab2d0532013-12-20 23:21:09 +01002905# @object-del:
2906#
2907# Remove a QOM object.
2908#
2909# @id: the name of the QOM object to remove
2910#
2911# Returns: Nothing on success
2912# Error if @id is not a valid id for a QOM object
2913#
2914# Since: 2.0
2915##
2916{ 'command': 'object-del', 'data': {'id': 'str'} }
2917
2918##
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02002919# @NetdevNoneOptions
2920#
2921# Use it alone to have zero network devices.
2922#
2923# Since 1.2
2924##
2925{ 'type': 'NetdevNoneOptions',
2926 'data': { } }
2927
2928##
2929# @NetLegacyNicOptions
2930#
2931# Create a new Network Interface Card.
2932#
2933# @netdev: #optional id of -netdev to connect to
2934#
2935# @macaddr: #optional MAC address
2936#
2937# @model: #optional device model (e1000, rtl8139, virtio etc.)
2938#
2939# @addr: #optional PCI device address
2940#
2941# @vectors: #optional number of MSI-x vectors, 0 to disable MSI-X
2942#
2943# Since 1.2
2944##
2945{ 'type': 'NetLegacyNicOptions',
2946 'data': {
2947 '*netdev': 'str',
2948 '*macaddr': 'str',
2949 '*model': 'str',
2950 '*addr': 'str',
2951 '*vectors': 'uint32' } }
2952
2953##
2954# @String
2955#
2956# A fat type wrapping 'str', to be embedded in lists.
2957#
2958# Since 1.2
2959##
2960{ 'type': 'String',
2961 'data': {
2962 'str': 'str' } }
2963
2964##
2965# @NetdevUserOptions
2966#
2967# Use the user mode network stack which requires no administrator privilege to
2968# run.
2969#
2970# @hostname: #optional client hostname reported by the builtin DHCP server
2971#
2972# @restrict: #optional isolate the guest from the host
2973#
2974# @ip: #optional legacy parameter, use net= instead
2975#
2976# @net: #optional IP address and optional netmask
2977#
2978# @host: #optional guest-visible address of the host
2979#
2980# @tftp: #optional root directory of the built-in TFTP server
2981#
2982# @bootfile: #optional BOOTP filename, for use with tftp=
2983#
2984# @dhcpstart: #optional the first of the 16 IPs the built-in DHCP server can
2985# assign
2986#
2987# @dns: #optional guest-visible address of the virtual nameserver
2988#
Klaus Stengel63d29602012-10-27 19:53:39 +02002989# @dnssearch: #optional list of DNS suffixes to search, passed as DHCP option
2990# to the guest
2991#
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02002992# @smb: #optional root directory of the built-in SMB server
2993#
2994# @smbserver: #optional IP address of the built-in SMB server
2995#
2996# @hostfwd: #optional redirect incoming TCP or UDP host connections to guest
2997# endpoints
2998#
2999# @guestfwd: #optional forward guest TCP connections
3000#
3001# Since 1.2
3002##
3003{ 'type': 'NetdevUserOptions',
3004 'data': {
3005 '*hostname': 'str',
3006 '*restrict': 'bool',
3007 '*ip': 'str',
3008 '*net': 'str',
3009 '*host': 'str',
3010 '*tftp': 'str',
3011 '*bootfile': 'str',
3012 '*dhcpstart': 'str',
3013 '*dns': 'str',
Klaus Stengel63d29602012-10-27 19:53:39 +02003014 '*dnssearch': ['String'],
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003015 '*smb': 'str',
3016 '*smbserver': 'str',
3017 '*hostfwd': ['String'],
3018 '*guestfwd': ['String'] } }
3019
3020##
3021# @NetdevTapOptions
3022#
3023# Connect the host TAP network interface name to the VLAN.
3024#
3025# @ifname: #optional interface name
3026#
3027# @fd: #optional file descriptor of an already opened tap
3028#
Jason Wang2ca81ba2013-02-20 18:04:01 +08003029# @fds: #optional multiple file descriptors of already opened multiqueue capable
3030# tap
3031#
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003032# @script: #optional script to initialize the interface
3033#
3034# @downscript: #optional script to shut down the interface
3035#
3036# @helper: #optional command to execute to configure bridge
3037#
3038# @sndbuf: #optional send buffer limit. Understands [TGMKkb] suffixes.
3039#
3040# @vnet_hdr: #optional enable the IFF_VNET_HDR flag on the tap interface
3041#
3042# @vhost: #optional enable vhost-net network accelerator
3043#
3044# @vhostfd: #optional file descriptor of an already opened vhost net device
3045#
Jason Wang2ca81ba2013-02-20 18:04:01 +08003046# @vhostfds: #optional file descriptors of multiple already opened vhost net
3047# devices
3048#
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003049# @vhostforce: #optional vhost on for non-MSIX virtio guests
3050#
Jason Wangec396012013-02-22 22:57:52 +08003051# @queues: #optional number of queues to be created for multiqueue capable tap
3052#
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003053# Since 1.2
3054##
3055{ 'type': 'NetdevTapOptions',
3056 'data': {
3057 '*ifname': 'str',
3058 '*fd': 'str',
Jason Wang264986e2013-01-30 19:12:34 +08003059 '*fds': 'str',
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003060 '*script': 'str',
3061 '*downscript': 'str',
3062 '*helper': 'str',
3063 '*sndbuf': 'size',
3064 '*vnet_hdr': 'bool',
3065 '*vhost': 'bool',
3066 '*vhostfd': 'str',
Jason Wang264986e2013-01-30 19:12:34 +08003067 '*vhostfds': 'str',
3068 '*vhostforce': 'bool',
3069 '*queues': 'uint32'} }
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003070
3071##
3072# @NetdevSocketOptions
3073#
3074# Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP
3075# socket connection.
3076#
3077# @fd: #optional file descriptor of an already opened socket
3078#
3079# @listen: #optional port number, and optional hostname, to listen on
3080#
3081# @connect: #optional port number, and optional hostname, to connect to
3082#
3083# @mcast: #optional UDP multicast address and port number
3084#
3085# @localaddr: #optional source address and port for multicast and udp packets
3086#
3087# @udp: #optional UDP unicast address and port number
3088#
3089# Since 1.2
3090##
3091{ 'type': 'NetdevSocketOptions',
3092 'data': {
3093 '*fd': 'str',
3094 '*listen': 'str',
3095 '*connect': 'str',
3096 '*mcast': 'str',
3097 '*localaddr': 'str',
3098 '*udp': 'str' } }
3099
3100##
3101# @NetdevVdeOptions
3102#
3103# Connect the VLAN to a vde switch running on the host.
3104#
3105# @sock: #optional socket path
3106#
3107# @port: #optional port number
3108#
3109# @group: #optional group owner of socket
3110#
3111# @mode: #optional permissions for socket
3112#
3113# Since 1.2
3114##
3115{ 'type': 'NetdevVdeOptions',
3116 'data': {
3117 '*sock': 'str',
3118 '*port': 'uint16',
3119 '*group': 'str',
3120 '*mode': 'uint16' } }
3121
3122##
3123# @NetdevDumpOptions
3124#
3125# Dump VLAN network traffic to a file.
3126#
3127# @len: #optional per-packet size limit (64k default). Understands [TGMKkb]
3128# suffixes.
3129#
3130# @file: #optional dump file path (default is qemu-vlan0.pcap)
3131#
3132# Since 1.2
3133##
3134{ 'type': 'NetdevDumpOptions',
3135 'data': {
3136 '*len': 'size',
3137 '*file': 'str' } }
3138
3139##
3140# @NetdevBridgeOptions
3141#
3142# Connect a host TAP network interface to a host bridge device.
3143#
3144# @br: #optional bridge name
3145#
3146# @helper: #optional command to execute to configure bridge
3147#
3148# Since 1.2
3149##
3150{ 'type': 'NetdevBridgeOptions',
3151 'data': {
3152 '*br': 'str',
3153 '*helper': 'str' } }
3154
3155##
Stefan Hajnoczif6c874e2012-07-24 16:35:04 +01003156# @NetdevHubPortOptions
3157#
3158# Connect two or more net clients through a software hub.
3159#
3160# @hubid: hub identifier number
3161#
3162# Since 1.2
3163##
3164{ 'type': 'NetdevHubPortOptions',
3165 'data': {
3166 'hubid': 'int32' } }
3167
3168##
Vincenzo Maffione58952132013-11-06 11:44:06 +01003169# @NetdevNetmapOptions
3170#
3171# Connect a client to a netmap-enabled NIC or to a VALE switch port
3172#
3173# @ifname: Either the name of an existing network interface supported by
3174# netmap, or the name of a VALE port (created on the fly).
3175# A VALE port name is in the form 'valeXXX:YYY', where XXX and
3176# YYY are non-negative integers. XXX identifies a switch and
3177# YYY identifies a port of the switch. VALE ports having the
3178# same XXX are therefore connected to the same switch.
3179#
3180# @devname: #optional path of the netmap device (default: '/dev/netmap').
3181#
Stefan Hajnoczic27de2a2013-12-11 09:49:14 +01003182# Since 2.0
Vincenzo Maffione58952132013-11-06 11:44:06 +01003183##
3184{ 'type': 'NetdevNetmapOptions',
3185 'data': {
3186 'ifname': 'str',
3187 '*devname': 'str' } }
3188
3189##
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003190# @NetClientOptions
3191#
3192# A discriminated record of network device traits.
3193#
3194# Since 1.2
3195##
3196{ 'union': 'NetClientOptions',
3197 'data': {
Stefan Hajnoczif6c874e2012-07-24 16:35:04 +01003198 'none': 'NetdevNoneOptions',
3199 'nic': 'NetLegacyNicOptions',
3200 'user': 'NetdevUserOptions',
3201 'tap': 'NetdevTapOptions',
3202 'socket': 'NetdevSocketOptions',
3203 'vde': 'NetdevVdeOptions',
3204 'dump': 'NetdevDumpOptions',
3205 'bridge': 'NetdevBridgeOptions',
Vincenzo Maffione58952132013-11-06 11:44:06 +01003206 'hubport': 'NetdevHubPortOptions',
3207 'netmap': 'NetdevNetmapOptions' } }
Laszlo Ersek14aa0c22012-07-17 16:17:11 +02003208
3209##
3210# @NetLegacy
3211#
3212# Captures the configuration of a network device; legacy.
3213#
3214# @vlan: #optional vlan number
3215#
3216# @id: #optional identifier for monitor commands
3217#
3218# @name: #optional identifier for monitor commands, ignored if @id is present
3219#
3220# @opts: device type specific properties (legacy)
3221#
3222# Since 1.2
3223##
3224{ 'type': 'NetLegacy',
3225 'data': {
3226 '*vlan': 'int32',
3227 '*id': 'str',
3228 '*name': 'str',
3229 'opts': 'NetClientOptions' } }
3230
3231##
3232# @Netdev
3233#
3234# Captures the configuration of a network device.
3235#
3236# @id: identifier for monitor commands.
3237#
3238# @opts: device type specific properties
3239#
3240# Since 1.2
3241##
3242{ 'type': 'Netdev',
3243 'data': {
3244 'id': 'str',
3245 'opts': 'NetClientOptions' } }
3246
3247##
Paolo Bonzini5be8c752012-09-19 14:03:35 +02003248# @InetSocketAddress
3249#
3250# Captures a socket address or address range in the Internet namespace.
3251#
3252# @host: host part of the address
3253#
3254# @port: port part of the address, or lowest port if @to is present
3255#
3256# @to: highest port to try
3257#
3258# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6
3259# #optional
3260#
3261# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6
3262# #optional
3263#
3264# Since 1.3
3265##
3266{ 'type': 'InetSocketAddress',
3267 'data': {
3268 'host': 'str',
3269 'port': 'str',
3270 '*to': 'uint16',
3271 '*ipv4': 'bool',
3272 '*ipv6': 'bool' } }
3273
3274##
3275# @UnixSocketAddress
3276#
3277# Captures a socket address in the local ("Unix socket") namespace.
3278#
3279# @path: filesystem path to use
3280#
3281# Since 1.3
3282##
3283{ 'type': 'UnixSocketAddress',
3284 'data': {
3285 'path': 'str' } }
3286
3287##
3288# @SocketAddress
3289#
3290# Captures the address of a socket, which could also be a named file descriptor
3291#
3292# Since 1.3
3293##
3294{ 'union': 'SocketAddress',
3295 'data': {
3296 'inet': 'InetSocketAddress',
3297 'unix': 'UnixSocketAddress',
3298 'fd': 'String' } }
3299
3300##
Corey Bryant208c9d12012-06-22 14:36:09 -04003301# @getfd:
3302#
3303# Receive a file descriptor via SCM rights and assign it a name
3304#
3305# @fdname: file descriptor name
3306#
3307# Returns: Nothing on success
Corey Bryant208c9d12012-06-22 14:36:09 -04003308#
3309# Since: 0.14.0
3310#
3311# Notes: If @fdname already exists, the file descriptor assigned to
3312# it will be closed and replaced by the received file
3313# descriptor.
3314# The 'closefd' command can be used to explicitly close the
3315# file descriptor when it is no longer needed.
3316##
3317{ 'command': 'getfd', 'data': {'fdname': 'str'} }
3318
3319##
3320# @closefd:
3321#
3322# Close a file descriptor previously passed via SCM rights
3323#
3324# @fdname: file descriptor name
3325#
3326# Returns: Nothing on success
Corey Bryant208c9d12012-06-22 14:36:09 -04003327#
3328# Since: 0.14.0
3329##
3330{ 'command': 'closefd', 'data': {'fdname': 'str'} }
Anthony Liguori01d3c802012-08-10 11:04:11 -05003331
3332##
3333# @MachineInfo:
3334#
3335# Information describing a machine.
3336#
3337# @name: the name of the machine
3338#
3339# @alias: #optional an alias for the machine name
3340#
3341# @default: #optional whether the machine is default
3342#
Michal Novotnyc72e7682013-04-08 18:21:02 +02003343# @cpu-max: maximum number of CPUs supported by the machine type
3344# (since 1.5.0)
3345#
Anthony Liguori01d3c802012-08-10 11:04:11 -05003346# Since: 1.2.0
3347##
3348{ 'type': 'MachineInfo',
3349 'data': { 'name': 'str', '*alias': 'str',
Michal Novotnyc72e7682013-04-08 18:21:02 +02003350 '*is-default': 'bool', 'cpu-max': 'int' } }
Anthony Liguori01d3c802012-08-10 11:04:11 -05003351
3352##
3353# @query-machines:
3354#
3355# Return a list of supported machines
3356#
3357# Returns: a list of MachineInfo
3358#
3359# Since: 1.2.0
3360##
3361{ 'command': 'query-machines', 'returns': ['MachineInfo'] }
Anthony Liguorie4e31c62012-08-10 11:04:13 -05003362
3363##
3364# @CpuDefinitionInfo:
3365#
3366# Virtual CPU definition.
3367#
3368# @name: the name of the CPU definition
3369#
3370# Since: 1.2.0
3371##
3372{ 'type': 'CpuDefinitionInfo',
3373 'data': { 'name': 'str' } }
3374
3375##
3376# @query-cpu-definitions:
3377#
3378# Return a list of supported virtual CPU definitions
3379#
3380# Returns: a list of CpuDefInfo
3381#
3382# Since: 1.2.0
3383##
3384{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }
Corey Bryantba1c0482012-08-14 16:43:43 -04003385
3386# @AddfdInfo:
3387#
3388# Information about a file descriptor that was added to an fd set.
3389#
3390# @fdset-id: The ID of the fd set that @fd was added to.
3391#
3392# @fd: The file descriptor that was received via SCM rights and
3393# added to the fd set.
3394#
3395# Since: 1.2.0
3396##
3397{ 'type': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
3398
3399##
3400# @add-fd:
3401#
3402# Add a file descriptor, that was passed via SCM rights, to an fd set.
3403#
3404# @fdset-id: #optional The ID of the fd set to add the file descriptor to.
3405#
3406# @opaque: #optional A free-form string that can be used to describe the fd.
3407#
3408# Returns: @AddfdInfo on success
3409# If file descriptor was not received, FdNotSupplied
Corey Bryant9ac54af2012-10-18 15:19:31 -04003410# If @fdset-id is a negative value, InvalidParameterValue
Corey Bryantba1c0482012-08-14 16:43:43 -04003411#
3412# Notes: The list of fd sets is shared by all monitor connections.
3413#
3414# If @fdset-id is not specified, a new fd set will be created.
3415#
3416# Since: 1.2.0
3417##
3418{ 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'},
3419 'returns': 'AddfdInfo' }
3420
3421##
3422# @remove-fd:
3423#
3424# Remove a file descriptor from an fd set.
3425#
3426# @fdset-id: The ID of the fd set that the file descriptor belongs to.
3427#
3428# @fd: #optional The file descriptor that is to be removed.
3429#
3430# Returns: Nothing on success
3431# If @fdset-id or @fd is not found, FdNotFound
3432#
3433# Since: 1.2.0
3434#
3435# Notes: The list of fd sets is shared by all monitor connections.
3436#
3437# If @fd is not specified, all file descriptors in @fdset-id
3438# will be removed.
3439##
3440{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
3441
3442##
3443# @FdsetFdInfo:
3444#
3445# Information about a file descriptor that belongs to an fd set.
3446#
3447# @fd: The file descriptor value.
3448#
3449# @opaque: #optional A free-form string that can be used to describe the fd.
3450#
3451# Since: 1.2.0
3452##
3453{ 'type': 'FdsetFdInfo',
3454 'data': {'fd': 'int', '*opaque': 'str'} }
3455
3456##
3457# @FdsetInfo:
3458#
3459# Information about an fd set.
3460#
3461# @fdset-id: The ID of the fd set.
3462#
3463# @fds: A list of file descriptors that belong to this fd set.
3464#
3465# Since: 1.2.0
3466##
3467{ 'type': 'FdsetInfo',
3468 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
3469
3470##
3471# @query-fdsets:
3472#
3473# Return information describing all fd sets.
3474#
3475# Returns: A list of @FdsetInfo
3476#
3477# Since: 1.2.0
3478#
3479# Note: The list of fd sets is shared by all monitor connections.
3480#
3481##
3482{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003483
3484##
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003485# @TargetInfo:
3486#
3487# Information describing the QEMU target.
3488#
3489# @arch: the target architecture (eg "x86_64", "i386", etc)
3490#
3491# Since: 1.2.0
3492##
3493{ 'type': 'TargetInfo',
Paolo Bonzinic02a9552013-06-04 14:45:28 +02003494 'data': { 'arch': 'str' } }
Daniel P. Berrange99afc912012-08-20 15:31:38 +01003495
3496##
3497# @query-target:
3498#
3499# Return information about the target for this QEMU
3500#
3501# Returns: TargetInfo
3502#
3503# Since: 1.2.0
3504##
3505{ 'command': 'query-target', 'returns': 'TargetInfo' }
Amos Kong411656f2012-08-31 10:56:24 +08003506
3507##
3508# @QKeyCode:
3509#
3510# An enumeration of key name.
3511#
3512# This is used by the send-key command.
3513#
3514# Since: 1.3.0
Gerd Hoffmannbbd1b1c2013-12-13 12:10:14 +01003515#
Gerd Hoffmann8b6b0c52013-12-16 10:34:53 +01003516# 'unmapped' and 'pause' since 2.0
Amos Kong411656f2012-08-31 10:56:24 +08003517##
3518{ 'enum': 'QKeyCode',
Gerd Hoffmannbbd1b1c2013-12-13 12:10:14 +01003519 'data': [ 'unmapped',
3520 'shift', 'shift_r', 'alt', 'alt_r', 'altgr', 'altgr_r', 'ctrl',
Amos Kong411656f2012-08-31 10:56:24 +08003521 'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
3522 '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
3523 'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
3524 'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
3525 'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
3526 'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
3527 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
3528 'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
3529 'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
3530 'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
3531 'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
3532 'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
3533 'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
Gerd Hoffmann8b6b0c52013-12-16 10:34:53 +01003534 'lf', 'help', 'meta_l', 'meta_r', 'compose', 'pause' ] }
Amos Konge4c8f002012-08-31 10:56:26 +08003535
3536##
Luiz Capitulino9f328972012-09-20 14:19:47 -03003537# @KeyValue
3538#
3539# Represents a keyboard key.
3540#
3541# Since: 1.3.0
3542##
3543{ 'union': 'KeyValue',
3544 'data': {
3545 'number': 'int',
3546 'qcode': 'QKeyCode' } }
3547
3548##
Amos Konge4c8f002012-08-31 10:56:26 +08003549# @send-key:
3550#
3551# Send keys to guest.
3552#
Luiz Capitulino9f328972012-09-20 14:19:47 -03003553# @keys: An array of @KeyValue elements. All @KeyValues in this array are
3554# simultaneously sent to the guest. A @KeyValue.number value is sent
3555# directly to the guest, while @KeyValue.qcode must be a valid
3556# @QKeyCode value
Amos Konge4c8f002012-08-31 10:56:26 +08003557#
3558# @hold-time: #optional time to delay key up events, milliseconds. Defaults
3559# to 100
3560#
3561# Returns: Nothing on success
3562# If key is unknown or redundant, InvalidParameter
3563#
3564# Since: 1.3.0
3565#
3566##
3567{ 'command': 'send-key',
Luiz Capitulino9f328972012-09-20 14:19:47 -03003568 'data': { 'keys': ['KeyValue'], '*hold-time': 'int' } }
Luiz Capitulinoad39cf62012-05-24 13:48:23 -03003569
3570##
3571# @screendump:
3572#
3573# Write a PPM of the VGA screen to a file.
3574#
3575# @filename: the path of a new PPM file to store the image
3576#
3577# Returns: Nothing on success
3578#
3579# Since: 0.14.0
3580##
3581{ 'command': 'screendump', 'data': {'filename': 'str'} }
Paolo Bonzini6dd844d2012-08-22 16:43:07 +02003582
3583##
3584# @nbd-server-start:
3585#
3586# Start an NBD server listening on the given host and port. Block
3587# devices can then be exported using @nbd-server-add. The NBD
3588# server will present them as named exports; for example, another
3589# QEMU instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
3590#
3591# @addr: Address on which to listen.
3592#
3593# Returns: error if the server is already running.
3594#
3595# Since: 1.3.0
3596##
3597{ 'command': 'nbd-server-start',
3598 'data': { 'addr': 'SocketAddress' } }
3599
3600##
3601# @nbd-server-add:
3602#
3603# Export a device to QEMU's embedded NBD server.
3604#
3605# @device: Block device to be exported
3606#
3607# @writable: Whether clients should be able to write to the device via the
3608# NBD connection (default false). #optional
3609#
3610# Returns: error if the device is already marked for export.
3611#
3612# Since: 1.3.0
3613##
3614{ 'command': 'nbd-server-add', 'data': {'device': 'str', '*writable': 'bool'} }
3615
3616##
3617# @nbd-server-stop:
3618#
3619# Stop QEMU's embedded NBD server, and unregister all devices previously
3620# added via @nbd-server-add.
3621#
3622# Since: 1.3.0
3623##
3624{ 'command': 'nbd-server-stop' }
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003625
3626##
Gerd Hoffmannffbdbe52012-12-19 13:13:57 +01003627# @ChardevFile:
3628#
3629# Configuration info for file chardevs.
3630#
3631# @in: #optional The name of the input file
3632# @out: The name of the output file
3633#
3634# Since: 1.4
3635##
3636{ 'type': 'ChardevFile', 'data': { '*in' : 'str',
3637 'out' : 'str' } }
3638
3639##
Markus Armbrusterd36b2b92013-02-13 15:54:16 +01003640# @ChardevHostdev:
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01003641#
Gerd Hoffmann548cbb32013-02-25 11:50:55 +01003642# Configuration info for device and pipe chardevs.
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01003643#
3644# @device: The name of the special file for the device,
3645# i.e. /dev/ttyS0 on Unix or COM1: on Windows
3646# @type: What kind of device this is.
3647#
3648# Since: 1.4
3649##
Markus Armbrusterd36b2b92013-02-13 15:54:16 +01003650{ 'type': 'ChardevHostdev', 'data': { 'device' : 'str' } }
Gerd Hoffmannd59044e2012-12-19 13:50:29 +01003651
3652##
Gerd Hoffmannf6bd5d62012-12-20 13:53:12 +01003653# @ChardevSocket:
3654#
Gerd Hoffmann3ecc0592013-02-27 14:10:47 +01003655# Configuration info for (stream) socket chardevs.
Gerd Hoffmannf6bd5d62012-12-20 13:53:12 +01003656#
3657# @addr: socket address to listen on (server=true)
3658# or connect to (server=false)
3659# @server: #optional create server socket (default: true)
Gerd Hoffmannef993ba2013-06-24 08:39:50 +02003660# @wait: #optional wait for incoming connection on server
3661# sockets (default: false).
Gerd Hoffmannf6bd5d62012-12-20 13:53:12 +01003662# @nodelay: #optional set TCP_NODELAY socket option (default: false)
Gerd Hoffmannef993ba2013-06-24 08:39:50 +02003663# @telnet: #optional enable telnet protocol on server
3664# sockets (default: false)
Gerd Hoffmannf6bd5d62012-12-20 13:53:12 +01003665#
3666# Since: 1.4
3667##
3668{ 'type': 'ChardevSocket', 'data': { 'addr' : 'SocketAddress',
3669 '*server' : 'bool',
3670 '*wait' : 'bool',
3671 '*nodelay' : 'bool',
3672 '*telnet' : 'bool' } }
3673
3674##
Lei Li08d0ab32013-05-20 14:51:03 +08003675# @ChardevUdp:
Gerd Hoffmann3ecc0592013-02-27 14:10:47 +01003676#
3677# Configuration info for datagram socket chardevs.
3678#
3679# @remote: remote address
3680# @local: #optional local address
3681#
3682# Since: 1.5
3683##
Lei Li08d0ab32013-05-20 14:51:03 +08003684{ 'type': 'ChardevUdp', 'data': { 'remote' : 'SocketAddress',
3685 '*local' : 'SocketAddress' } }
Gerd Hoffmann3ecc0592013-02-27 14:10:47 +01003686
3687##
Gerd Hoffmannedb2fb32013-02-21 16:16:42 +01003688# @ChardevMux:
3689#
3690# Configuration info for mux chardevs.
3691#
3692# @chardev: name of the base chardev.
3693#
3694# Since: 1.5
3695##
3696{ 'type': 'ChardevMux', 'data': { 'chardev' : 'str' } }
3697
3698##
Gerd Hoffmann7c358032013-02-21 12:34:58 +01003699# @ChardevStdio:
3700#
3701# Configuration info for stdio chardevs.
3702#
3703# @signal: #optional Allow signals (such as SIGINT triggered by ^C)
3704# be delivered to qemu. Default: true in -nographic mode,
3705# false otherwise.
3706#
3707# Since: 1.5
3708##
3709{ 'type': 'ChardevStdio', 'data': { '*signal' : 'bool' } }
3710
3711##
Gerd Hoffmanncd153e22013-02-25 12:39:06 +01003712# @ChardevSpiceChannel:
3713#
3714# Configuration info for spice vm channel chardevs.
3715#
3716# @type: kind of channel (for example vdagent).
3717#
3718# Since: 1.5
3719##
3720{ 'type': 'ChardevSpiceChannel', 'data': { 'type' : 'str' } }
3721
3722##
3723# @ChardevSpicePort:
3724#
3725# Configuration info for spice port chardevs.
3726#
3727# @fqdn: name of the channel (see docs/spice-port-fqdn.txt)
3728#
3729# Since: 1.5
3730##
3731{ 'type': 'ChardevSpicePort', 'data': { 'fqdn' : 'str' } }
3732
3733##
Gerd Hoffmann702ec692013-02-25 15:52:32 +01003734# @ChardevVC:
3735#
3736# Configuration info for virtual console chardevs.
3737#
3738# @width: console width, in pixels
3739# @height: console height, in pixels
3740# @cols: console width, in chars
3741# @rows: console height, in chars
3742#
3743# Since: 1.5
3744##
3745{ 'type': 'ChardevVC', 'data': { '*width' : 'int',
3746 '*height' : 'int',
3747 '*cols' : 'int',
3748 '*rows' : 'int' } }
3749
3750##
Markus Armbruster4f573782013-07-26 16:44:32 +02003751# @ChardevRingbuf:
Gerd Hoffmann1da48c62013-02-26 16:21:11 +01003752#
Markus Armbruster3a1da422013-07-26 16:44:34 +02003753# Configuration info for ring buffer chardevs.
Gerd Hoffmann1da48c62013-02-26 16:21:11 +01003754#
Markus Armbruster3a1da422013-07-26 16:44:34 +02003755# @size: #optional ring buffer size, must be power of two, default is 65536
Gerd Hoffmann1da48c62013-02-26 16:21:11 +01003756#
3757# Since: 1.5
3758##
Markus Armbruster4f573782013-07-26 16:44:32 +02003759{ 'type': 'ChardevRingbuf', 'data': { '*size' : 'int' } }
Gerd Hoffmann1da48c62013-02-26 16:21:11 +01003760
3761##
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003762# @ChardevBackend:
3763#
3764# Configuration info for the new chardev backend.
3765#
3766# Since: 1.4
3767##
3768{ 'type': 'ChardevDummy', 'data': { } }
3769
Gerd Hoffmannf6bd5d62012-12-20 13:53:12 +01003770{ 'union': 'ChardevBackend', 'data': { 'file' : 'ChardevFile',
Markus Armbrusterd36b2b92013-02-13 15:54:16 +01003771 'serial' : 'ChardevHostdev',
3772 'parallel': 'ChardevHostdev',
Gerd Hoffmann548cbb32013-02-25 11:50:55 +01003773 'pipe' : 'ChardevHostdev',
Gerd Hoffmannf6bd5d62012-12-20 13:53:12 +01003774 'socket' : 'ChardevSocket',
Lei Li08d0ab32013-05-20 14:51:03 +08003775 'udp' : 'ChardevUdp',
Gerd Hoffmann0a1a7fa2012-12-20 14:39:13 +01003776 'pty' : 'ChardevDummy',
Gerd Hoffmannedb2fb32013-02-21 16:16:42 +01003777 'null' : 'ChardevDummy',
Gerd Hoffmannf5a51ca2013-02-21 11:58:44 +01003778 'mux' : 'ChardevMux',
Gerd Hoffmann2d572862013-02-21 12:56:10 +01003779 'msmouse': 'ChardevDummy',
Gerd Hoffmann7c358032013-02-21 12:34:58 +01003780 'braille': 'ChardevDummy',
Gerd Hoffmannd9ac3742013-02-25 11:48:06 +01003781 'stdio' : 'ChardevStdio',
Gerd Hoffmanncd153e22013-02-25 12:39:06 +01003782 'console': 'ChardevDummy',
3783 'spicevmc' : 'ChardevSpiceChannel',
Gerd Hoffmann702ec692013-02-25 15:52:32 +01003784 'spiceport' : 'ChardevSpicePort',
Gerd Hoffmann1da48c62013-02-26 16:21:11 +01003785 'vc' : 'ChardevVC',
Markus Armbruster3a1da422013-07-26 16:44:34 +02003786 'ringbuf': 'ChardevRingbuf',
3787 # next one is just for compatibility
Markus Armbruster4f573782013-07-26 16:44:32 +02003788 'memory' : 'ChardevRingbuf' } }
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003789
3790##
3791# @ChardevReturn:
3792#
3793# Return info about the chardev backend just created.
3794#
Markus Armbruster58fa4322013-02-11 18:05:48 +01003795# @pty: #optional name of the slave pseudoterminal device, present if
3796# and only if a chardev of type 'pty' was created
3797#
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003798# Since: 1.4
3799##
Gerd Hoffmann0a1a7fa2012-12-20 14:39:13 +01003800{ 'type' : 'ChardevReturn', 'data': { '*pty' : 'str' } }
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003801
3802##
3803# @chardev-add:
3804#
Markus Armbruster58fa4322013-02-11 18:05:48 +01003805# Add a character device backend
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003806#
3807# @id: the chardev's ID, must be unique
3808# @backend: backend type and parameters
3809#
Markus Armbruster58fa4322013-02-11 18:05:48 +01003810# Returns: ChardevReturn.
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003811#
3812# Since: 1.4
3813##
3814{ 'command': 'chardev-add', 'data': {'id' : 'str',
3815 'backend' : 'ChardevBackend' },
3816 'returns': 'ChardevReturn' }
3817
3818##
3819# @chardev-remove:
3820#
Markus Armbruster58fa4322013-02-11 18:05:48 +01003821# Remove a character device backend
Gerd Hoffmannf1a1a352012-12-19 10:33:56 +01003822#
3823# @id: the chardev's ID, must exist and not be in use
3824#
3825# Returns: Nothing on success
3826#
3827# Since: 1.4
3828##
3829{ 'command': 'chardev-remove', 'data': {'id': 'str'} }
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003830
3831##
3832# @TpmModel:
3833#
3834# An enumeration of TPM models
3835#
3836# @tpm-tis: TPM TIS model
3837#
3838# Since: 1.5
3839##
3840{ 'enum': 'TpmModel', 'data': [ 'tpm-tis' ] }
3841
3842##
3843# @query-tpm-models:
3844#
3845# Return a list of supported TPM models
3846#
3847# Returns: a list of TpmModel
3848#
3849# Since: 1.5
3850##
3851{ 'command': 'query-tpm-models', 'returns': ['TpmModel'] }
3852
3853##
3854# @TpmType:
3855#
3856# An enumeration of TPM types
3857#
3858# @passthrough: TPM passthrough type
3859#
3860# Since: 1.5
3861##
3862{ 'enum': 'TpmType', 'data': [ 'passthrough' ] }
3863
3864##
3865# @query-tpm-types:
3866#
3867# Return a list of supported TPM types
3868#
3869# Returns: a list of TpmType
3870#
3871# Since: 1.5
3872##
3873{ 'command': 'query-tpm-types', 'returns': ['TpmType'] }
3874
3875##
3876# @TPMPassthroughOptions:
3877#
3878# Information about the TPM passthrough type
3879#
3880# @path: #optional string describing the path used for accessing the TPM device
3881#
3882# @cancel-path: #optional string showing the TPM's sysfs cancel file
3883# for cancellation of TPM commands while they are executing
3884#
3885# Since: 1.5
3886##
3887{ 'type': 'TPMPassthroughOptions', 'data': { '*path' : 'str',
3888 '*cancel-path' : 'str'} }
3889
3890##
3891# @TpmTypeOptions:
3892#
3893# A union referencing different TPM backend types' configuration options
3894#
Corey Bryant88ca7bc2013-03-20 12:34:48 -04003895# @passthrough: The configuration options for the TPM passthrough type
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003896#
3897# Since: 1.5
3898##
3899{ 'union': 'TpmTypeOptions',
Corey Bryant88ca7bc2013-03-20 12:34:48 -04003900 'data': { 'passthrough' : 'TPMPassthroughOptions' } }
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003901
3902##
3903# @TpmInfo:
3904#
3905# Information about the TPM
3906#
3907# @id: The Id of the TPM
3908#
3909# @model: The TPM frontend model
3910#
Corey Bryant88ca7bc2013-03-20 12:34:48 -04003911# @options: The TPM (backend) type configuration options
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003912#
3913# Since: 1.5
3914##
3915{ 'type': 'TPMInfo',
3916 'data': {'id': 'str',
3917 'model': 'TpmModel',
Corey Bryant88ca7bc2013-03-20 12:34:48 -04003918 'options': 'TpmTypeOptions' } }
Stefan Bergerd1a0cf72013-02-27 12:47:49 -05003919
3920##
3921# @query-tpm:
3922#
3923# Return information about the TPM device
3924#
3925# Returns: @TPMInfo on success
3926#
3927# Since: 1.5
3928##
3929{ 'command': 'query-tpm', 'returns': ['TPMInfo'] }
Laszlo Ersek8ccbad52013-03-21 00:23:16 +01003930
3931##
3932# @AcpiTableOptions
3933#
3934# Specify an ACPI table on the command line to load.
3935#
3936# At most one of @file and @data can be specified. The list of files specified
3937# by any one of them is loaded and concatenated in order. If both are omitted,
3938# @data is implied.
3939#
3940# Other fields / optargs can be used to override fields of the generic ACPI
3941# table header; refer to the ACPI specification 5.0, section 5.2.6 System
3942# Description Table Header. If a header field is not overridden, then the
3943# corresponding value from the concatenated blob is used (in case of @file), or
3944# it is filled in with a hard-coded value (in case of @data).
3945#
3946# String fields are copied into the matching ACPI member from lowest address
3947# upwards, and silently truncated / NUL-padded to length.
3948#
3949# @sig: #optional table signature / identifier (4 bytes)
3950#
3951# @rev: #optional table revision number (dependent on signature, 1 byte)
3952#
3953# @oem_id: #optional OEM identifier (6 bytes)
3954#
3955# @oem_table_id: #optional OEM table identifier (8 bytes)
3956#
3957# @oem_rev: #optional OEM-supplied revision number (4 bytes)
3958#
3959# @asl_compiler_id: #optional identifier of the utility that created the table
3960# (4 bytes)
3961#
3962# @asl_compiler_rev: #optional revision number of the utility that created the
3963# table (4 bytes)
3964#
3965# @file: #optional colon (:) separated list of pathnames to load and
3966# concatenate as table data. The resultant binary blob is expected to
3967# have an ACPI table header. At least one file is required. This field
3968# excludes @data.
3969#
3970# @data: #optional colon (:) separated list of pathnames to load and
3971# concatenate as table data. The resultant binary blob must not have an
3972# ACPI table header. At least one file is required. This field excludes
3973# @file.
3974#
3975# Since 1.5
3976##
3977{ 'type': 'AcpiTableOptions',
3978 'data': {
3979 '*sig': 'str',
3980 '*rev': 'uint8',
3981 '*oem_id': 'str',
3982 '*oem_table_id': 'str',
3983 '*oem_rev': 'uint32',
3984 '*asl_compiler_id': 'str',
3985 '*asl_compiler_rev': 'uint32',
3986 '*file': 'str',
3987 '*data': 'str' }}
Amos Kong1f8f9872013-04-25 17:50:35 +08003988
3989##
3990# @CommandLineParameterType:
3991#
3992# Possible types for an option parameter.
3993#
3994# @string: accepts a character string
3995#
3996# @boolean: accepts "on" or "off"
3997#
3998# @number: accepts a number
3999#
4000# @size: accepts a number followed by an optional suffix (K)ilo,
4001# (M)ega, (G)iga, (T)era
4002#
4003# Since 1.5
4004##
4005{ 'enum': 'CommandLineParameterType',
4006 'data': ['string', 'boolean', 'number', 'size'] }
4007
4008##
4009# @CommandLineParameterInfo:
4010#
4011# Details about a single parameter of a command line option.
4012#
4013# @name: parameter name
4014#
4015# @type: parameter @CommandLineParameterType
4016#
4017# @help: #optional human readable text string, not suitable for parsing.
4018#
4019# Since 1.5
4020##
4021{ 'type': 'CommandLineParameterInfo',
4022 'data': { 'name': 'str',
4023 'type': 'CommandLineParameterType',
4024 '*help': 'str' } }
4025
4026##
4027# @CommandLineOptionInfo:
4028#
4029# Details about a command line option, including its list of parameter details
4030#
4031# @option: option name
4032#
4033# @parameters: an array of @CommandLineParameterInfo
4034#
4035# Since 1.5
4036##
4037{ 'type': 'CommandLineOptionInfo',
4038 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
4039
4040##
4041# @query-command-line-options:
4042#
4043# Query command line option schema.
4044#
4045# @option: #optional option name
4046#
4047# Returns: list of @CommandLineOptionInfo for all options (or for the given
4048# @option). Returns an error if the given @option doesn't exist.
4049#
4050# Since 1.5
4051##
4052{'command': 'query-command-line-options', 'data': { '*option': 'str' },
4053 'returns': ['CommandLineOptionInfo'] }
Eduardo Habkost8e8aba52013-05-06 13:20:07 -03004054
4055##
4056# @X86CPURegister32
4057#
4058# A X86 32-bit register
4059#
4060# Since: 1.5
4061##
4062{ 'enum': 'X86CPURegister32',
4063 'data': [ 'EAX', 'EBX', 'ECX', 'EDX', 'ESP', 'EBP', 'ESI', 'EDI' ] }
4064
4065##
4066# @X86CPUFeatureWordInfo
4067#
4068# Information about a X86 CPU feature word
4069#
4070# @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
4071#
4072# @cpuid-input-ecx: #optional Input ECX value for CPUID instruction for that
4073# feature word
4074#
4075# @cpuid-register: Output register containing the feature bits
4076#
4077# @features: value of output register, containing the feature bits
4078#
4079# Since: 1.5
4080##
4081{ 'type': 'X86CPUFeatureWordInfo',
4082 'data': { 'cpuid-input-eax': 'int',
4083 '*cpuid-input-ecx': 'int',
4084 'cpuid-register': 'X86CPURegister32',
4085 'features': 'int' } }
Amos Kongb1be4282013-06-14 15:45:52 +08004086
4087##
4088# @RxState:
4089#
4090# Packets receiving state
4091#
4092# @normal: filter assigned packets according to the mac-table
4093#
4094# @none: don't receive any assigned packet
4095#
4096# @all: receive all assigned packets
4097#
4098# Since: 1.6
4099##
4100{ 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
4101
4102##
4103# @RxFilterInfo:
4104#
4105# Rx-filter information for a NIC.
4106#
4107# @name: net client name
4108#
4109# @promiscuous: whether promiscuous mode is enabled
4110#
4111# @multicast: multicast receive state
4112#
4113# @unicast: unicast receive state
4114#
Amos Kongf7bc8ef2014-03-26 08:19:43 +08004115# @vlan: vlan receive state (Since 2.0)
4116#
Amos Kongb1be4282013-06-14 15:45:52 +08004117# @broadcast-allowed: whether to receive broadcast
4118#
4119# @multicast-overflow: multicast table is overflowed or not
4120#
4121# @unicast-overflow: unicast table is overflowed or not
4122#
4123# @main-mac: the main macaddr string
4124#
4125# @vlan-table: a list of active vlan id
4126#
4127# @unicast-table: a list of unicast macaddr string
4128#
4129# @multicast-table: a list of multicast macaddr string
4130#
4131# Since 1.6
4132##
4133
4134{ 'type': 'RxFilterInfo',
4135 'data': {
4136 'name': 'str',
4137 'promiscuous': 'bool',
4138 'multicast': 'RxState',
4139 'unicast': 'RxState',
Amos Kongf7bc8ef2014-03-26 08:19:43 +08004140 'vlan': 'RxState',
Amos Kongb1be4282013-06-14 15:45:52 +08004141 'broadcast-allowed': 'bool',
4142 'multicast-overflow': 'bool',
4143 'unicast-overflow': 'bool',
4144 'main-mac': 'str',
4145 'vlan-table': ['int'],
4146 'unicast-table': ['str'],
4147 'multicast-table': ['str'] }}
4148
4149##
4150# @query-rx-filter:
4151#
4152# Return rx-filter information for all NICs (or for the given NIC).
4153#
4154# @name: #optional net client name
4155#
4156# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
4157# Returns an error if the given @name doesn't exist, or given
4158# NIC doesn't support rx-filter querying, or given net client
4159# isn't a NIC.
4160#
4161# Since: 1.6
4162##
4163{ 'command': 'query-rx-filter', 'data': { '*name': 'str' },
4164 'returns': ['RxFilterInfo'] }
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004165
4166
4167##
4168# @BlockdevDiscardOptions
4169#
4170# Determines how to handle discard requests.
4171#
4172# @ignore: Ignore the request
4173# @unmap: Forward as an unmap request
4174#
4175# Since: 1.7
4176##
4177{ 'enum': 'BlockdevDiscardOptions',
4178 'data': [ 'ignore', 'unmap' ] }
4179
4180##
Peter Lieven465bee12014-05-18 00:58:19 +02004181# @BlockdevDetectZeroesOptions
4182#
4183# Describes the operation mode for the automatic conversion of plain
4184# zero writes by the OS to driver specific optimized zero write commands.
4185#
4186# @off: Disabled (default)
4187# @on: Enabled
4188# @unmap: Enabled and even try to unmap blocks if possible. This requires
4189# also that @BlockdevDiscardOptions is set to unmap for this device.
4190#
4191# Since: 2.1
4192##
4193{ 'enum': 'BlockdevDetectZeroesOptions',
4194 'data': [ 'off', 'on', 'unmap' ] }
4195
4196##
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004197# @BlockdevAioOptions
4198#
4199# Selects the AIO backend to handle I/O requests
4200#
4201# @threads: Use qemu's thread pool
4202# @native: Use native AIO backend (only Linux and Windows)
4203#
4204# Since: 1.7
4205##
4206{ 'enum': 'BlockdevAioOptions',
4207 'data': [ 'threads', 'native' ] }
4208
4209##
4210# @BlockdevCacheOptions
4211#
4212# Includes cache-related options for block devices
4213#
4214# @writeback: #optional enables writeback mode for any caches (default: true)
4215# @direct: #optional enables use of O_DIRECT (bypass the host page cache;
4216# default: false)
4217# @no-flush: #optional ignore any flush requests for the device (default:
4218# false)
4219#
4220# Since: 1.7
4221##
4222{ 'type': 'BlockdevCacheOptions',
4223 'data': { '*writeback': 'bool',
4224 '*direct': 'bool',
4225 '*no-flush': 'bool' } }
4226
4227##
Wenchao Xia59ca6642014-03-04 18:44:38 -08004228# @BlockdevDriver
4229#
4230# Drivers that are supported in block device operations.
4231#
Kevin Wolfa28315e2014-04-24 15:02:39 +02004232# @host_device, @host_cdrom, @host_floppy: Since 2.1
4233#
Wenchao Xia59ca6642014-03-04 18:44:38 -08004234# Since: 2.0
4235##
4236{ 'enum': 'BlockdevDriver',
Kevin Wolfa28315e2014-04-24 15:02:39 +02004237 'data': [ 'file', 'host_device', 'host_cdrom', 'host_floppy',
4238 'http', 'https', 'ftp', 'ftps', 'tftp', 'vvfat', 'blkdebug',
Wenchao Xia59ca6642014-03-04 18:44:38 -08004239 'blkverify', 'bochs', 'cloop', 'cow', 'dmg', 'parallels', 'qcow',
4240 'qcow2', 'qed', 'raw', 'vdi', 'vhdx', 'vmdk', 'vpc', 'quorum' ] }
4241
4242##
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004243# @BlockdevOptionsBase
4244#
4245# Options that are available for all block devices, independent of the block
4246# driver.
4247#
Peter Lieven465bee12014-05-18 00:58:19 +02004248# @driver: block driver name
4249# @id: #optional id by which the new block device can be referred to.
4250# This is a required option on the top level of blockdev-add, and
4251# currently not allowed on any other level.
4252# @node-name: #optional the name of a block driver state node (Since 2.0)
4253# @discard: #optional discard-related options (default: ignore)
4254# @cache: #optional cache-related options
4255# @aio: #optional AIO backend (default: threads)
4256# @rerror: #optional how to handle read errors on the device
4257# (default: report)
4258# @werror: #optional how to handle write errors on the device
4259# (default: enospc)
4260# @read-only: #optional whether the block device should be read-only
4261# (default: false)
4262# @detect-zeroes: #optional detect and optimize zero writes (Since 2.1)
4263# (default: off)
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004264#
4265# Since: 1.7
4266##
4267{ 'type': 'BlockdevOptionsBase',
Wenchao Xia59ca6642014-03-04 18:44:38 -08004268 'data': { 'driver': 'BlockdevDriver',
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004269 '*id': 'str',
Benoît Canet6913c0c2014-01-23 21:31:33 +01004270 '*node-name': 'str',
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004271 '*discard': 'BlockdevDiscardOptions',
4272 '*cache': 'BlockdevCacheOptions',
4273 '*aio': 'BlockdevAioOptions',
4274 '*rerror': 'BlockdevOnError',
4275 '*werror': 'BlockdevOnError',
Peter Lieven465bee12014-05-18 00:58:19 +02004276 '*read-only': 'bool',
4277 '*detect-zeroes': 'BlockdevDetectZeroesOptions' } }
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004278
4279##
4280# @BlockdevOptionsFile
4281#
4282# Driver specific block device options for the file backend and similar
4283# protocols.
4284#
4285# @filename: path to the image file
4286#
4287# Since: 1.7
4288##
4289{ 'type': 'BlockdevOptionsFile',
4290 'data': { 'filename': 'str' } }
4291
4292##
4293# @BlockdevOptionsVVFAT
4294#
4295# Driver specific block device options for the vvfat protocol.
4296#
4297# @dir: directory to be exported as FAT image
4298# @fat-type: #optional FAT type: 12, 16 or 32
4299# @floppy: #optional whether to export a floppy image (true) or
4300# partitioned hard disk (false; default)
4301# @rw: #optional whether to allow write operations (default: false)
4302#
4303# Since: 1.7
4304##
4305{ 'type': 'BlockdevOptionsVVFAT',
4306 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool',
4307 '*rw': 'bool' } }
4308
4309##
4310# @BlockdevOptionsGenericFormat
4311#
4312# Driver specific block device options for image format that have no option
4313# besides their data source.
4314#
4315# @file: reference to or definition of the data source block device
4316#
4317# Since: 1.7
4318##
4319{ 'type': 'BlockdevOptionsGenericFormat',
4320 'data': { 'file': 'BlockdevRef' } }
4321
4322##
4323# @BlockdevOptionsGenericCOWFormat
4324#
4325# Driver specific block device options for image format that have no option
4326# besides their data source and an optional backing file.
4327#
4328# @backing: #optional reference to or definition of the backing file block
4329# device (if missing, taken from the image file content). It is
4330# allowed to pass an empty string here in order to disable the
4331# default backing file.
4332#
4333# Since: 1.7
4334##
4335{ 'type': 'BlockdevOptionsGenericCOWFormat',
4336 'base': 'BlockdevOptionsGenericFormat',
4337 'data': { '*backing': 'BlockdevRef' } }
4338
4339##
4340# @BlockdevOptionsQcow2
4341#
4342# Driver specific block device options for qcow2.
4343#
4344# @lazy-refcounts: #optional whether to enable the lazy refcounts
4345# feature (default is taken from the image file)
4346#
4347# @pass-discard-request: #optional whether discard requests to the qcow2
4348# device should be forwarded to the data source
4349#
4350# @pass-discard-snapshot: #optional whether discard requests for the data source
4351# should be issued when a snapshot operation (e.g.
4352# deleting a snapshot) frees clusters in the qcow2 file
4353#
4354# @pass-discard-other: #optional whether discard requests for the data source
4355# should be issued on other occasions where a cluster
4356# gets freed
4357#
4358# Since: 1.7
4359##
4360{ 'type': 'BlockdevOptionsQcow2',
4361 'base': 'BlockdevOptionsGenericCOWFormat',
4362 'data': { '*lazy-refcounts': 'bool',
4363 '*pass-discard-request': 'bool',
4364 '*pass-discard-snapshot': 'bool',
4365 '*pass-discard-other': 'bool' } }
4366
4367##
Max Reitz1bf20b82013-12-20 19:28:19 +01004368# @BlkdebugEvent
4369#
4370# Trigger events supported by blkdebug.
4371##
4372{ 'enum': 'BlkdebugEvent',
4373 'data': [ 'l1_update', 'l1_grow.alloc_table', 'l1_grow.write_table',
4374 'l1_grow.activate_table', 'l2_load', 'l2_update',
4375 'l2_update_compressed', 'l2_alloc.cow_read', 'l2_alloc.write',
4376 'read_aio', 'read_backing_aio', 'read_compressed', 'write_aio',
4377 'write_compressed', 'vmstate_load', 'vmstate_save', 'cow_read',
4378 'cow_write', 'reftable_load', 'reftable_grow', 'reftable_update',
4379 'refblock_load', 'refblock_update', 'refblock_update_part',
4380 'refblock_alloc', 'refblock_alloc.hookup', 'refblock_alloc.write',
4381 'refblock_alloc.write_blocks', 'refblock_alloc.write_table',
4382 'refblock_alloc.switch_table', 'cluster_alloc',
4383 'cluster_alloc_bytes', 'cluster_free', 'flush_to_os',
4384 'flush_to_disk' ] }
4385
4386##
4387# @BlkdebugInjectErrorOptions
4388#
4389# Describes a single error injection for blkdebug.
4390#
4391# @event: trigger event
4392#
4393# @state: #optional the state identifier blkdebug needs to be in to
4394# actually trigger the event; defaults to "any"
4395#
4396# @errno: #optional error identifier (errno) to be returned; defaults to
4397# EIO
4398#
4399# @sector: #optional specifies the sector index which has to be affected
4400# in order to actually trigger the event; defaults to "any
4401# sector"
4402#
4403# @once: #optional disables further events after this one has been
4404# triggered; defaults to false
4405#
4406# @immediately: #optional fail immediately; defaults to false
4407#
4408# Since: 2.0
4409##
4410{ 'type': 'BlkdebugInjectErrorOptions',
4411 'data': { 'event': 'BlkdebugEvent',
4412 '*state': 'int',
4413 '*errno': 'int',
4414 '*sector': 'int',
4415 '*once': 'bool',
4416 '*immediately': 'bool' } }
4417
4418##
4419# @BlkdebugSetStateOptions
4420#
4421# Describes a single state-change event for blkdebug.
4422#
4423# @event: trigger event
4424#
4425# @state: #optional the current state identifier blkdebug needs to be in;
4426# defaults to "any"
4427#
4428# @new_state: the state identifier blkdebug is supposed to assume if
4429# this event is triggered
4430#
4431# Since: 2.0
4432##
4433{ 'type': 'BlkdebugSetStateOptions',
4434 'data': { 'event': 'BlkdebugEvent',
4435 '*state': 'int',
4436 'new_state': 'int' } }
4437
4438##
4439# @BlockdevOptionsBlkdebug
4440#
4441# Driver specific block device options for blkdebug.
4442#
4443# @image: underlying raw block device (or image file)
4444#
4445# @config: #optional filename of the configuration file
4446#
Kevin Wolfb35ee7f2014-01-14 13:44:35 +01004447# @align: #optional required alignment for requests in bytes
4448#
Max Reitz1bf20b82013-12-20 19:28:19 +01004449# @inject-error: #optional array of error injection descriptions
4450#
4451# @set-state: #optional array of state-change descriptions
4452#
4453# Since: 2.0
4454##
4455{ 'type': 'BlockdevOptionsBlkdebug',
4456 'data': { 'image': 'BlockdevRef',
4457 '*config': 'str',
Kevin Wolfb35ee7f2014-01-14 13:44:35 +01004458 '*align': 'int',
Max Reitz1bf20b82013-12-20 19:28:19 +01004459 '*inject-error': ['BlkdebugInjectErrorOptions'],
4460 '*set-state': ['BlkdebugSetStateOptions'] } }
4461
4462##
4463# @BlockdevOptionsBlkverify
4464#
4465# Driver specific block device options for blkverify.
4466#
4467# @test: block device to be tested
4468#
4469# @raw: raw image used for verification
4470#
4471# Since: 2.0
4472##
4473{ 'type': 'BlockdevOptionsBlkverify',
4474 'data': { 'test': 'BlockdevRef',
4475 'raw': 'BlockdevRef' } }
4476
4477##
Benoît Canetc88a1de2014-02-21 22:21:20 +01004478# @BlockdevOptionsQuorum
4479#
4480# Driver specific block device options for Quorum
4481#
4482# @blkverify: #optional true if the driver must print content mismatch
Benoît Caneta9e6a0c2014-02-22 18:43:40 +01004483# set to false by default
Benoît Canetc88a1de2014-02-21 22:21:20 +01004484#
Benoît Caneta9e6a0c2014-02-22 18:43:40 +01004485# @children: the children block devices to use
Benoît Canetc88a1de2014-02-21 22:21:20 +01004486#
Benoît Caneta9e6a0c2014-02-22 18:43:40 +01004487# @vote-threshold: the vote limit under which a read will fail
Benoît Canetc88a1de2014-02-21 22:21:20 +01004488#
4489# Since: 2.0
4490##
4491{ 'type': 'BlockdevOptionsQuorum',
4492 'data': { '*blkverify': 'bool',
4493 'children': [ 'BlockdevRef' ],
4494 'vote-threshold': 'int' } }
4495
4496##
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004497# @BlockdevOptions
4498#
4499# Options for creating a block device.
4500#
4501# Since: 1.7
4502##
4503{ 'union': 'BlockdevOptions',
4504 'base': 'BlockdevOptionsBase',
4505 'discriminator': 'driver',
4506 'data': {
4507 'file': 'BlockdevOptionsFile',
Kevin Wolfa28315e2014-04-24 15:02:39 +02004508 'host_device':'BlockdevOptionsFile',
4509 'host_cdrom': 'BlockdevOptionsFile',
4510 'host_floppy':'BlockdevOptionsFile',
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004511 'http': 'BlockdevOptionsFile',
4512 'https': 'BlockdevOptionsFile',
4513 'ftp': 'BlockdevOptionsFile',
4514 'ftps': 'BlockdevOptionsFile',
4515 'tftp': 'BlockdevOptionsFile',
4516# TODO gluster: Wait for structured options
4517# TODO iscsi: Wait for structured options
4518# TODO nbd: Should take InetSocketAddress for 'host'?
Peter Lieven6542aa92014-02-03 10:26:13 +01004519# TODO nfs: Wait for structured options
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004520# TODO rbd: Wait for structured options
4521# TODO sheepdog: Wait for structured options
4522# TODO ssh: Should take InetSocketAddress for 'host'?
4523 'vvfat': 'BlockdevOptionsVVFAT',
Max Reitz1bf20b82013-12-20 19:28:19 +01004524 'blkdebug': 'BlockdevOptionsBlkdebug',
4525 'blkverify': 'BlockdevOptionsBlkverify',
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004526 'bochs': 'BlockdevOptionsGenericFormat',
4527 'cloop': 'BlockdevOptionsGenericFormat',
4528 'cow': 'BlockdevOptionsGenericCOWFormat',
4529 'dmg': 'BlockdevOptionsGenericFormat',
4530 'parallels': 'BlockdevOptionsGenericFormat',
4531 'qcow': 'BlockdevOptionsGenericCOWFormat',
4532 'qcow2': 'BlockdevOptionsQcow2',
4533 'qed': 'BlockdevOptionsGenericCOWFormat',
4534 'raw': 'BlockdevOptionsGenericFormat',
4535 'vdi': 'BlockdevOptionsGenericFormat',
4536 'vhdx': 'BlockdevOptionsGenericFormat',
4537 'vmdk': 'BlockdevOptionsGenericCOWFormat',
Benoît Canetc88a1de2014-02-21 22:21:20 +01004538 'vpc': 'BlockdevOptionsGenericFormat',
4539 'quorum': 'BlockdevOptionsQuorum'
Kevin Wolfd26c9a12013-09-23 15:26:03 +02004540 } }
4541
4542##
4543# @BlockdevRef
4544#
4545# Reference to a block device.
4546#
4547# @definition: defines a new block device inline
4548# @reference: references the ID of an existing block device. An
4549# empty string means that no block device should be
4550# referenced.
4551#
4552# Since: 1.7
4553##
4554{ 'union': 'BlockdevRef',
4555 'discriminator': {},
4556 'data': { 'definition': 'BlockdevOptions',
4557 'reference': 'str' } }
4558
4559##
4560# @blockdev-add:
4561#
4562# Creates a new block device.
4563#
4564# @options: block device options for the new device
4565#
4566# Since: 1.7
4567##
4568{ 'command': 'blockdev-add', 'data': { 'options': 'BlockdevOptions' } }
Gerd Hoffmann031fa962013-11-27 09:08:40 +01004569
4570##
4571# @InputButton
4572#
4573# Button of a pointer input device (mouse, tablet).
4574#
4575# Since: 2.0
4576##
4577{ 'enum' : 'InputButton',
4578 'data' : [ 'Left', 'Middle', 'Right', 'WheelUp', 'WheelDown' ] }
4579
4580##
4581# @InputButton
4582#
4583# Position axis of a pointer input device (mouse, tablet).
4584#
4585# Since: 2.0
4586##
4587{ 'enum' : 'InputAxis',
4588 'data' : [ 'X', 'Y' ] }
4589
4590##
4591# @InputKeyEvent
4592#
4593# Keyboard input event.
4594#
4595# @key: Which key this event is for.
4596# @down: True for key-down and false for key-up events.
4597#
4598# Since: 2.0
4599##
4600{ 'type' : 'InputKeyEvent',
4601 'data' : { 'key' : 'KeyValue',
4602 'down' : 'bool' } }
4603
4604##
4605# @InputBtnEvent
4606#
4607# Pointer button input event.
4608#
4609# @button: Which button this event is for.
4610# @down: True for key-down and false for key-up events.
4611#
4612# Since: 2.0
4613##
4614{ 'type' : 'InputBtnEvent',
4615 'data' : { 'button' : 'InputButton',
4616 'down' : 'bool' } }
4617
4618##
4619# @InputMoveEvent
4620#
4621# Pointer motion input event.
4622#
4623# @axis: Which axis is referenced by @value.
4624# @value: Pointer position. For absolute coordinates the
4625# valid range is 0 -> 0x7ffff
4626#
4627# Since: 2.0
4628##
4629{ 'type' : 'InputMoveEvent',
4630 'data' : { 'axis' : 'InputAxis',
4631 'value' : 'int' } }
4632
4633##
4634# @InputEvent
4635#
4636# Input event union.
4637#
4638# Since: 2.0
4639##
4640{ 'union' : 'InputEvent',
4641 'data' : { 'key' : 'InputKeyEvent',
4642 'btn' : 'InputBtnEvent',
4643 'rel' : 'InputMoveEvent',
4644 'abs' : 'InputMoveEvent' } }