]> git.proxmox.com Git - mirror_qemu.git/blame - qapi-schema.json
iostatus: reorganize io error code
[mirror_qemu.git] / qapi-schema.json
CommitLineData
e3193601
AL
1# -*- Mode: Python -*-
2#
3# QAPI Schema
48a32bed 4
dcafd323
LC
5##
6# @ErrorClass
7#
8# QEMU error classes
9#
10# @GenericError: this is used for errors that don't require a specific error
11# class. This should be the default case for most errors
12#
13# @CommandNotFound: the requested command has not been found
14#
15# @DeviceEncrypted: the requested operation can't be fulfilled because the
16# selected device is encrypted
17#
18# @DeviceNotActive: a device has failed to be become active
19#
20# @DeviceNotFound: the requested device has not been found
21#
22# @KVMMissingCap: the requested operation can't be fulfilled because a
23# required KVM capability is missing
24#
25# @MigrationExpected: the requested operation can't be fulfilled because a
26# migration process is expected
27#
28# Since: 1.2
29##
30{ 'enum': 'ErrorClass',
31 'data': [ 'GenericError', 'CommandNotFound', 'DeviceEncrypted',
32 'DeviceNotActive', 'DeviceNotFound', 'KVMMissingCap',
33 'MigrationExpected' ] }
34
48a32bed
AL
35##
36# @NameInfo:
37#
38# Guest name information.
39#
40# @name: #optional The name of the guest
41#
42# Since 0.14.0
43##
44{ 'type': 'NameInfo', 'data': {'*name': 'str'} }
45
46##
47# @query-name:
48#
49# Return the name information of a guest.
50#
51# Returns: @NameInfo of the guest
52#
53# Since 0.14.0
54##
55{ 'command': 'query-name', 'returns': 'NameInfo' }
b9c15f16
LC
56
57##
58# @VersionInfo:
59#
60# A description of QEMU's version.
61#
62# @qemu.major: The major version of QEMU
63#
64# @qemu.minor: The minor version of QEMU
65#
66# @qemu.micro: The micro version of QEMU. By current convention, a micro
67# version of 50 signifies a development branch. A micro version
68# greater than or equal to 90 signifies a release candidate for
69# the next minor version. A micro version of less than 50
70# signifies a stable release.
71#
72# @package: QEMU will always set this field to an empty string. Downstream
73# versions of QEMU should set this to a non-empty string. The
74# exact format depends on the downstream however it highly
75# recommended that a unique name is used.
76#
77# Since: 0.14.0
78##
79{ 'type': 'VersionInfo',
80 'data': {'qemu': {'major': 'int', 'minor': 'int', 'micro': 'int'},
81 'package': 'str'} }
82
83##
84# @query-version:
85#
86# Returns the current version of QEMU.
87#
88# Returns: A @VersionInfo object describing the current version of QEMU.
89#
90# Since: 0.14.0
91##
92{ 'command': 'query-version', 'returns': 'VersionInfo' }
292a2602
LC
93
94##
95# @KvmInfo:
96#
97# Information about support for KVM acceleration
98#
99# @enabled: true if KVM acceleration is active
100#
101# @present: true if KVM acceleration is built into this executable
102#
103# Since: 0.14.0
104##
105{ 'type': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
106
107##
108# @query-kvm:
109#
110# Returns information about KVM acceleration
111#
112# Returns: @KvmInfo
113#
114# Since: 0.14.0
115##
116{ 'command': 'query-kvm', 'returns': 'KvmInfo' }
117
1fa9a5e4
LC
118##
119# @RunState
120#
6932a69b 121# An enumeration of VM run states.
1fa9a5e4
LC
122#
123# @debug: QEMU is running on a debugger
124#
0a24c7b1
LC
125# @finish-migrate: guest is paused to finish the migration process
126#
1fa9a5e4
LC
127# @inmigrate: guest is paused waiting for an incoming migration
128#
129# @internal-error: An internal error that prevents further guest execution
130# has occurred
131#
132# @io-error: the last IOP has failed and the device is configured to pause
133# on I/O errors
134#
135# @paused: guest has been paused via the 'stop' command
136#
137# @postmigrate: guest is paused following a successful 'migrate'
138#
139# @prelaunch: QEMU was started with -S and guest has not started
140#
1fa9a5e4
LC
141# @restore-vm: guest is paused to restore VM state
142#
143# @running: guest is actively running
144#
145# @save-vm: guest is paused to save the VM state
146#
147# @shutdown: guest is shut down (and -no-shutdown is in use)
148#
ad02b96a
LC
149# @suspended: guest is suspended (ACPI S3)
150#
1fa9a5e4
LC
151# @watchdog: the watchdog action is configured to pause and has been triggered
152##
153{ 'enum': 'RunState',
154 'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
155 'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
ad02b96a 156 'running', 'save-vm', 'shutdown', 'suspended', 'watchdog' ] }
1fa9a5e4 157
c249ee68
BC
158##
159# @SnapshotInfo
160#
161# @id: unique snapshot id
162#
163# @name: user chosen name
164#
165# @vm-state-size: size of the VM state
166#
167# @date-sec: UTC date of the snapshot in seconds
168#
169# @date-nsec: fractional part in nano seconds to be used with date-sec
170#
171# @vm-clock-sec: VM clock relative to boot in seconds
172#
173# @vm-clock-nsec: fractional part in nano seconds to be used with vm-clock-sec
174#
175# Since: 1.3
176#
177##
178
179{ 'type': 'SnapshotInfo',
180 'data': { 'id': 'str', 'name': 'str', 'vm-state-size': 'int',
181 'date-sec': 'int', 'date-nsec': 'int',
182 'vm-clock-sec': 'int', 'vm-clock-nsec': 'int' } }
183
184##
185# @ImageInfo:
186#
187# Information about a QEMU image file
188#
189# @filename: name of the image file
190#
191# @format: format of the image file
192#
193# @virtual-size: maximum capacity in bytes of the image
194#
195# @actual-size: #optional actual size on disk in bytes of the image
196#
197# @dirty-flag: #optional true if image is not cleanly closed
198#
199# @cluster-size: #optional size of a cluster in bytes
200#
201# @encrypted: #optional true if the image is encrypted
202#
203# @backing-filename: #optional name of the backing file
204#
205# @full-backing-filename: #optional full path of the backing file
206#
207# @backing-filename-format: #optional the format of the backing file
208#
209# @snapshots: #optional list of VM snapshots
210#
211# Since: 1.3
212#
213##
214
215{ 'type': 'ImageInfo',
216 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool',
217 '*actual-size': 'int', 'virtual-size': 'int',
218 '*cluster-size': 'int', '*encrypted': 'bool',
219 '*backing-filename': 'str', '*full-backing-filename': 'str',
220 '*backing-filename-format': 'str', '*snapshots': ['SnapshotInfo'] } }
221
1fa9a5e4
LC
222##
223# @StatusInfo:
224#
225# Information about VCPU run state
226#
227# @running: true if all VCPUs are runnable, false if not runnable
228#
229# @singlestep: true if VCPUs are in single-step mode
230#
231# @status: the virtual machine @RunState
232#
233# Since: 0.14.0
234#
235# Notes: @singlestep is enabled through the GDB stub
236##
237{ 'type': 'StatusInfo',
238 'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
239
240##
241# @query-status:
242#
243# Query the run status of all VCPUs
244#
245# Returns: @StatusInfo reflecting all VCPUs
246#
247# Since: 0.14.0
248##
249{ 'command': 'query-status', 'returns': 'StatusInfo' }
250
efab767e
LC
251##
252# @UuidInfo:
253#
254# Guest UUID information.
255#
256# @UUID: the UUID of the guest
257#
258# Since: 0.14.0
259#
260# Notes: If no UUID was specified for the guest, a null UUID is returned.
261##
262{ 'type': 'UuidInfo', 'data': {'UUID': 'str'} }
263
264##
265# @query-uuid:
266#
267# Query the guest UUID information.
268#
269# Returns: The @UuidInfo for the guest
270#
271# Since 0.14.0
272##
273{ 'command': 'query-uuid', 'returns': 'UuidInfo' }
274
c5a415a0
LC
275##
276# @ChardevInfo:
277#
278# Information about a character device.
279#
280# @label: the label of the character device
281#
282# @filename: the filename of the character device
283#
284# Notes: @filename is encoded using the QEMU command line character device
285# encoding. See the QEMU man page for details.
286#
287# Since: 0.14.0
288##
289{ 'type': 'ChardevInfo', 'data': {'label': 'str', 'filename': 'str'} }
290
291##
292# @query-chardev:
293#
294# Returns information about current character devices.
295#
296# Returns: a list of @ChardevInfo
297#
298# Since: 0.14.0
299##
300{ 'command': 'query-chardev', 'returns': ['ChardevInfo'] }
aa9b79bc
LC
301
302##
303# @CommandInfo:
304#
305# Information about a QMP command
306#
307# @name: The command name
308#
309# Since: 0.14.0
310##
311{ 'type': 'CommandInfo', 'data': {'name': 'str'} }
312
313##
314# @query-commands:
315#
316# Return a list of supported QMP commands by this server
317#
318# Returns: A list of @CommandInfo for all supported commands
319#
320# Since: 0.14.0
321##
322{ 'command': 'query-commands', 'returns': ['CommandInfo'] }
323
4860853d
DB
324##
325# @EventInfo:
326#
327# Information about a QMP event
328#
329# @name: The event name
330#
331# Since: 1.2.0
332##
333{ 'type': 'EventInfo', 'data': {'name': 'str'} }
334
335##
336# @query-events:
337#
338# Return a list of supported QMP events by this server
339#
340# Returns: A list of @EventInfo for all supported events
341#
342# Since: 1.2.0
343##
344{ 'command': 'query-events', 'returns': ['EventInfo'] }
345
791e7c82
LC
346##
347# @MigrationStats
348#
349# Detailed migration status.
350#
351# @transferred: amount of bytes already transferred to the target VM
352#
353# @remaining: amount of bytes remaining to be transferred to the target VM
354#
355# @total: total amount of bytes involved in the migration process
356#
004d4c10
OW
357# @duplicate: number of duplicate pages (since 1.2)
358#
359# @normal : number of normal pages (since 1.2)
360#
361# @normal-bytes : number of normal bytes sent (since 1.2)
362#
363# Since: 0.14.0
791e7c82
LC
364##
365{ 'type': 'MigrationStats',
d5f8a570 366 'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
7aa939af 367 'duplicate': 'int', 'normal': 'int', 'normal-bytes': 'int' } }
791e7c82 368
f36d55af
OW
369##
370# @XBZRLECacheStats
371#
372# Detailed XBZRLE migration cache statistics
373#
374# @cache-size: XBZRLE cache size
375#
376# @bytes: amount of bytes already transferred to the target VM
377#
378# @pages: amount of pages transferred to the target VM
379#
380# @cache-miss: number of cache miss
381#
382# @overflow: number of overflows
383#
384# Since: 1.2
385##
386{ 'type': 'XBZRLECacheStats',
387 'data': {'cache-size': 'int', 'bytes': 'int', 'pages': 'int',
388 'cache-miss': 'int', 'overflow': 'int' } }
389
791e7c82
LC
390##
391# @MigrationInfo
392#
393# Information about current migration process.
394#
395# @status: #optional string describing the current migration status.
396# As of 0.14.0 this can be 'active', 'completed', 'failed' or
397# 'cancelled'. If this field is not returned, no migration process
398# has been initiated
399#
d5f8a570
JQ
400# @ram: #optional @MigrationStats containing detailed migration
401# status, only returned if status is 'active' or
402# 'completed'. 'comppleted' (since 1.2)
791e7c82
LC
403#
404# @disk: #optional @MigrationStats containing detailed disk migration
405# status, only returned if status is 'active' and it is a block
406# migration
407#
f36d55af
OW
408# @xbzrle-cache: #optional @XBZRLECacheStats containing detailed XBZRLE
409# migration statistics, only returned if XBZRLE feature is on and
410# status is 'active' or 'completed' (since 1.2)
411#
7aa939af
JQ
412# @total-time: #optional total amount of milliseconds since migration started.
413# If migration has ended, it returns the total migration
414# time. (since 1.2)
415#
791e7c82
LC
416# Since: 0.14.0
417##
418{ 'type': 'MigrationInfo',
419 'data': {'*status': 'str', '*ram': 'MigrationStats',
f36d55af 420 '*disk': 'MigrationStats',
7aa939af
JQ
421 '*xbzrle-cache': 'XBZRLECacheStats',
422 '*total-time': 'int'} }
791e7c82
LC
423
424##
425# @query-migrate
426#
427# Returns information about current migration process.
428#
429# Returns: @MigrationInfo
430#
431# Since: 0.14.0
432##
433{ 'command': 'query-migrate', 'returns': 'MigrationInfo' }
434
bbf6da32
OW
435##
436# @MigrationCapability
437#
438# Migration capabilities enumeration
439#
440# @xbzrle: Migration supports xbzrle (Xor Based Zero Run Length Encoding).
441# This feature allows us to minimize migration traffic for certain work
442# loads, by sending compressed difference of the pages
443#
444# Since: 1.2
445##
446{ 'enum': 'MigrationCapability',
447 'data': ['xbzrle'] }
448
449##
450# @MigrationCapabilityStatus
451#
452# Migration capability information
453#
454# @capability: capability enum
455#
456# @state: capability state bool
457#
458# Since: 1.2
459##
460{ 'type': 'MigrationCapabilityStatus',
461 'data': { 'capability' : 'MigrationCapability', 'state' : 'bool' } }
462
463##
00458433
OW
464# @migrate-set-capabilities
465#
466# Enable/Disable the following migration capabilities (like xbzrle)
467#
468# @capabilities: json array of capability modifications to make
469#
470# Since: 1.2
471##
472{ 'command': 'migrate-set-capabilities',
473 'data': { 'capabilities': ['MigrationCapabilityStatus'] } }
474
475##
bbf6da32
OW
476# @query-migrate-capabilities
477#
478# Returns information about the current migration capabilities status
479#
480# Returns: @MigrationCapabilitiesStatus
481#
482# Since: 1.2
483##
484{ 'command': 'query-migrate-capabilities', 'returns': ['MigrationCapabilityStatus']}
485
e235cec3
LC
486##
487# @MouseInfo:
488#
489# Information about a mouse device.
490#
491# @name: the name of the mouse device
492#
493# @index: the index of the mouse device
494#
495# @current: true if this device is currently receiving mouse events
496#
497# @absolute: true if this device supports absolute coordinates as input
498#
499# Since: 0.14.0
500##
501{ 'type': 'MouseInfo',
502 'data': {'name': 'str', 'index': 'int', 'current': 'bool',
503 'absolute': 'bool'} }
504
505##
506# @query-mice:
507#
508# Returns information about each active mouse device
509#
510# Returns: a list of @MouseInfo for each device
511#
512# Since: 0.14.0
513##
514{ 'command': 'query-mice', 'returns': ['MouseInfo'] }
515
de0b36b6
LC
516##
517# @CpuInfo:
518#
519# Information about a virtual CPU
520#
521# @CPU: the index of the virtual CPU
522#
523# @current: this only exists for backwards compatible and should be ignored
b80e560b 524#
de0b36b6
LC
525# @halted: true if the virtual CPU is in the halt state. Halt usually refers
526# to a processor specific low power mode.
527#
528# @pc: #optional If the target is i386 or x86_64, this is the 64-bit instruction
529# pointer.
530# If the target is Sparc, this is the PC component of the
531# instruction pointer.
532#
533# @nip: #optional If the target is PPC, the instruction pointer
534#
535# @npc: #optional If the target is Sparc, the NPC component of the instruction
536# pointer
537#
538# @PC: #optional If the target is MIPS, the instruction pointer
539#
540# @thread_id: ID of the underlying host thread
541#
542# Since: 0.14.0
543#
544# Notes: @halted is a transient state that changes frequently. By the time the
545# data is sent to the client, the guest may no longer be halted.
546##
547{ 'type': 'CpuInfo',
548 'data': {'CPU': 'int', 'current': 'bool', 'halted': 'bool', '*pc': 'int',
549 '*nip': 'int', '*npc': 'int', '*PC': 'int', 'thread_id': 'int'} }
550
551##
552# @query-cpus:
553#
554# Returns a list of information about each virtual CPU.
555#
556# Returns: a list of @CpuInfo for each virtual CPU
557#
558# Since: 0.14.0
559##
560{ 'command': 'query-cpus', 'returns': ['CpuInfo'] }
561
b2023818
LC
562##
563# @BlockDeviceInfo:
564#
565# Information about the backing device for a block device.
566#
567# @file: the filename of the backing device
568#
569# @ro: true if the backing device was open read-only
570#
571# @drv: the name of the block format used to open the backing device. As of
572# 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
573# 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
574# 'host_floppy', 'http', 'https', 'nbd', 'parallels', 'qcow',
575# 'qcow2', 'raw', 'tftp', 'vdi', 'vmdk', 'vpc', 'vvfat'
576#
577# @backing_file: #optional the name of the backing file (for copy-on-write)
578#
2e3e3317
BC
579# @backing_file_depth: number of files in the backing file chain (since: 1.2)
580#
b2023818
LC
581# @encrypted: true if the backing device is encrypted
582#
c75a1a8a
LC
583# @encryption_key_missing: true if the backing device is encrypted but an
584# valid encryption key is missing
585#
727f005e
ZYW
586# @bps: total throughput limit in bytes per second is specified
587#
588# @bps_rd: read throughput limit in bytes per second is specified
589#
590# @bps_wr: write throughput limit in bytes per second is specified
591#
592# @iops: total I/O operations per second is specified
593#
594# @iops_rd: read I/O operations per second is specified
595#
596# @iops_wr: write I/O operations per second is specified
597#
b2023818
LC
598# Since: 0.14.0
599#
600# Notes: This interface is only found in @BlockInfo.
601##
602{ 'type': 'BlockDeviceInfo',
603 'data': { 'file': 'str', 'ro': 'bool', 'drv': 'str',
2e3e3317 604 '*backing_file': 'str', 'backing_file_depth': 'int',
c75a1a8a
LC
605 'encrypted': 'bool', 'encryption_key_missing': 'bool',
606 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
607 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int'} }
b2023818
LC
608
609##
610# @BlockDeviceIoStatus:
611#
612# An enumeration of block device I/O status.
613#
614# @ok: The last I/O operation has succeeded
615#
616# @failed: The last I/O operation has failed
617#
618# @nospace: The last I/O operation has failed due to a no-space condition
619#
620# Since: 1.0
621##
622{ 'enum': 'BlockDeviceIoStatus', 'data': [ 'ok', 'failed', 'nospace' ] }
623
624##
625# @BlockInfo:
626#
627# Block device information. This structure describes a virtual device and
628# the backing device associated with it.
629#
630# @device: The device name associated with the virtual device.
631#
632# @type: This field is returned only for compatibility reasons, it should
633# not be used (always returns 'unknown')
634#
635# @removable: True if the device supports removable media.
636#
637# @locked: True if the guest has locked this device from having its media
638# removed
639#
640# @tray_open: #optional True if the device has a tray and it is open
641# (only present if removable is true)
642#
643# @io-status: #optional @BlockDeviceIoStatus. Only present if the device
644# supports it and the VM is configured to stop on errors
645#
646# @inserted: #optional @BlockDeviceInfo describing the device if media is
647# present
648#
649# Since: 0.14.0
650##
651{ 'type': 'BlockInfo',
652 'data': {'device': 'str', 'type': 'str', 'removable': 'bool',
653 'locked': 'bool', '*inserted': 'BlockDeviceInfo',
654 '*tray_open': 'bool', '*io-status': 'BlockDeviceIoStatus'} }
655
656##
657# @query-block:
658#
659# Get a list of BlockInfo for all virtual block devices.
660#
661# Returns: a list of @BlockInfo describing each virtual block device
662#
663# Since: 0.14.0
664##
665{ 'command': 'query-block', 'returns': ['BlockInfo'] }
666
f11f57e4
LC
667##
668# @BlockDeviceStats:
669#
670# Statistics of a virtual block device or a block backing device.
671#
672# @rd_bytes: The number of bytes read by the device.
673#
674# @wr_bytes: The number of bytes written by the device.
675#
676# @rd_operations: The number of read operations performed by the device.
677#
678# @wr_operations: The number of write operations performed by the device.
679#
680# @flush_operations: The number of cache flush operations performed by the
681# device (since 0.15.0)
682#
683# @flush_total_time_ns: Total time spend on cache flushes in nano-seconds
684# (since 0.15.0).
685#
686# @wr_total_time_ns: Total time spend on writes in nano-seconds (since 0.15.0).
687#
688# @rd_total_time_ns: Total_time_spend on reads in nano-seconds (since 0.15.0).
689#
690# @wr_highest_offset: The offset after the greatest byte written to the
691# device. The intended use of this information is for
692# growable sparse files (like qcow2) that are used on top
693# of a physical device.
694#
695# Since: 0.14.0
696##
697{ 'type': 'BlockDeviceStats',
698 'data': {'rd_bytes': 'int', 'wr_bytes': 'int', 'rd_operations': 'int',
699 'wr_operations': 'int', 'flush_operations': 'int',
700 'flush_total_time_ns': 'int', 'wr_total_time_ns': 'int',
701 'rd_total_time_ns': 'int', 'wr_highest_offset': 'int' } }
702
703##
704# @BlockStats:
705#
706# Statistics of a virtual block device or a block backing device.
707#
708# @device: #optional If the stats are for a virtual block device, the name
709# corresponding to the virtual block device.
710#
711# @stats: A @BlockDeviceStats for the device.
712#
713# @parent: #optional This may point to the backing block device if this is a
714# a virtual block device. If it's a backing block, this will point
715# to the backing file is one is present.
716#
717# Since: 0.14.0
718##
719{ 'type': 'BlockStats',
720 'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
721 '*parent': 'BlockStats'} }
722
723##
724# @query-blockstats:
725#
726# Query the @BlockStats for all virtual block devices.
727#
728# Returns: A list of @BlockStats for each virtual block devices.
729#
730# Since: 0.14.0
731##
732{ 'command': 'query-blockstats', 'returns': ['BlockStats'] }
733
2b54aa87
LC
734##
735# @VncClientInfo:
736#
737# Information about a connected VNC client.
738#
739# @host: The host name of the client. QEMU tries to resolve this to a DNS name
740# when possible.
741#
742# @family: 'ipv6' if the client is connected via IPv6 and TCP
743# 'ipv4' if the client is connected via IPv4 and TCP
744# 'unix' if the client is connected via a unix domain socket
745# 'unknown' otherwise
746#
747# @service: The service name of the client's port. This may depends on the
748# host system's service database so symbolic names should not be
749# relied on.
750#
751# @x509_dname: #optional If x509 authentication is in use, the Distinguished
752# Name of the client.
753#
754# @sasl_username: #optional If SASL authentication is in use, the SASL username
755# used for authentication.
756#
757# Since: 0.14.0
758##
759{ 'type': 'VncClientInfo',
760 'data': {'host': 'str', 'family': 'str', 'service': 'str',
761 '*x509_dname': 'str', '*sasl_username': 'str'} }
762
763##
764# @VncInfo:
765#
766# Information about the VNC session.
767#
768# @enabled: true if the VNC server is enabled, false otherwise
769#
770# @host: #optional The hostname the VNC server is bound to. This depends on
771# the name resolution on the host and may be an IP address.
772#
773# @family: #optional 'ipv6' if the host is listening for IPv6 connections
774# 'ipv4' if the host is listening for IPv4 connections
775# 'unix' if the host is listening on a unix domain socket
776# 'unknown' otherwise
777#
778# @service: #optional The service name of the server's port. This may depends
779# on the host system's service database so symbolic names should not
780# be relied on.
781#
782# @auth: #optional the current authentication type used by the server
783# 'none' if no authentication is being used
784# 'vnc' if VNC authentication is being used
785# 'vencrypt+plain' if VEncrypt is used with plain text authentication
786# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
787# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
788# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
789# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
790# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
791# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
792# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
793# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth
794#
795# @clients: a list of @VncClientInfo of all currently connected clients
796#
797# Since: 0.14.0
798##
799{ 'type': 'VncInfo',
800 'data': {'enabled': 'bool', '*host': 'str', '*family': 'str',
801 '*service': 'str', '*auth': 'str', '*clients': ['VncClientInfo']} }
802
803##
804# @query-vnc:
805#
806# Returns information about the current VNC server
807#
808# Returns: @VncInfo
2b54aa87
LC
809#
810# Since: 0.14.0
811##
812{ 'command': 'query-vnc', 'returns': 'VncInfo' }
813
d1f29646
LC
814##
815# @SpiceChannel
816#
817# Information about a SPICE client channel.
818#
819# @host: The host name of the client. QEMU tries to resolve this to a DNS name
820# when possible.
821#
822# @family: 'ipv6' if the client is connected via IPv6 and TCP
823# 'ipv4' if the client is connected via IPv4 and TCP
824# 'unix' if the client is connected via a unix domain socket
825# 'unknown' otherwise
826#
827# @port: The client's port number.
828#
829# @connection-id: SPICE connection id number. All channels with the same id
830# belong to the same SPICE session.
831#
419e1bdf
AL
832# @connection-type: SPICE channel type number. "1" is the main control
833# channel, filter for this one if you want to track spice
834# sessions only
d1f29646 835#
419e1bdf
AL
836# @channel-id: SPICE channel ID number. Usually "0", might be different when
837# multiple channels of the same type exist, such as multiple
d1f29646
LC
838# display channels in a multihead setup
839#
840# @tls: true if the channel is encrypted, false otherwise.
841#
842# Since: 0.14.0
843##
844{ 'type': 'SpiceChannel',
845 'data': {'host': 'str', 'family': 'str', 'port': 'str',
846 'connection-id': 'int', 'channel-type': 'int', 'channel-id': 'int',
847 'tls': 'bool'} }
848
4efee029
AL
849##
850# @SpiceQueryMouseMode
851#
6932a69b 852# An enumeration of Spice mouse states.
4efee029
AL
853#
854# @client: Mouse cursor position is determined by the client.
855#
856# @server: Mouse cursor position is determined by the server.
857#
858# @unknown: No information is available about mouse mode used by
859# the spice server.
860#
861# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
862#
863# Since: 1.1
864##
865{ 'enum': 'SpiceQueryMouseMode',
866 'data': [ 'client', 'server', 'unknown' ] }
867
d1f29646
LC
868##
869# @SpiceInfo
870#
871# Information about the SPICE session.
b80e560b 872#
d1f29646
LC
873# @enabled: true if the SPICE server is enabled, false otherwise
874#
61c4efe2
YH
875# @migrated: true if the last guest migration completed and spice
876# migration had completed as well. false otherwise.
877#
d1f29646
LC
878# @host: #optional The hostname the SPICE server is bound to. This depends on
879# the name resolution on the host and may be an IP address.
880#
881# @port: #optional The SPICE server's port number.
882#
883# @compiled-version: #optional SPICE server version.
884#
885# @tls-port: #optional The SPICE server's TLS port number.
886#
887# @auth: #optional the current authentication type used by the server
419e1bdf
AL
888# 'none' if no authentication is being used
889# 'spice' uses SASL or direct TLS authentication, depending on command
890# line options
d1f29646 891#
4efee029
AL
892# @mouse-mode: The mode in which the mouse cursor is displayed currently. Can
893# be determined by the client or the server, or unknown if spice
894# server doesn't provide this information.
895#
896# Since: 1.1
897#
d1f29646
LC
898# @channels: a list of @SpiceChannel for each active spice channel
899#
900# Since: 0.14.0
901##
902{ 'type': 'SpiceInfo',
61c4efe2 903 'data': {'enabled': 'bool', 'migrated': 'bool', '*host': 'str', '*port': 'int',
d1f29646 904 '*tls-port': 'int', '*auth': 'str', '*compiled-version': 'str',
4efee029 905 'mouse-mode': 'SpiceQueryMouseMode', '*channels': ['SpiceChannel']} }
d1f29646
LC
906
907##
908# @query-spice
909#
910# Returns information about the current SPICE server
911#
912# Returns: @SpiceInfo
913#
914# Since: 0.14.0
915##
916{ 'command': 'query-spice', 'returns': 'SpiceInfo' }
917
96637bcd
LC
918##
919# @BalloonInfo:
920#
921# Information about the guest balloon device.
922#
923# @actual: the number of bytes the balloon currently contains
924#
925# @mem_swapped_in: #optional number of pages swapped in within the guest
926#
927# @mem_swapped_out: #optional number of pages swapped out within the guest
928#
929# @major_page_faults: #optional number of major page faults within the guest
930#
931# @minor_page_faults: #optional number of minor page faults within the guest
932#
933# @free_mem: #optional amount of memory (in bytes) free in the guest
934#
935# @total_mem: #optional amount of memory (in bytes) visible to the guest
936#
937# Since: 0.14.0
938#
939# Notes: all current versions of QEMU do not fill out optional information in
940# this structure.
941##
942{ 'type': 'BalloonInfo',
943 'data': {'actual': 'int', '*mem_swapped_in': 'int',
944 '*mem_swapped_out': 'int', '*major_page_faults': 'int',
945 '*minor_page_faults': 'int', '*free_mem': 'int',
946 '*total_mem': 'int'} }
947
948##
949# @query-balloon:
950#
951# Return information about the balloon device.
952#
953# Returns: @BalloonInfo on success
954# If the balloon driver is enabled but not functional because the KVM
955# kernel module cannot support it, KvmMissingCap
956# If no balloon device is present, DeviceNotActive
957#
958# Since: 0.14.0
959##
960{ 'command': 'query-balloon', 'returns': 'BalloonInfo' }
961
79627472
LC
962##
963# @PciMemoryRange:
964#
965# A PCI device memory region
966#
967# @base: the starting address (guest physical)
968#
969# @limit: the ending address (guest physical)
970#
971# Since: 0.14.0
972##
973{ 'type': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
974
975##
976# @PciMemoryRegion
977#
978# Information about a PCI device I/O region.
979#
980# @bar: the index of the Base Address Register for this region
981#
982# @type: 'io' if the region is a PIO region
983# 'memory' if the region is a MMIO region
984#
985# @prefetch: #optional if @type is 'memory', true if the memory is prefetchable
986#
987# @mem_type_64: #optional if @type is 'memory', true if the BAR is 64-bit
988#
989# Since: 0.14.0
990##
991{ 'type': 'PciMemoryRegion',
992 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
993 '*prefetch': 'bool', '*mem_type_64': 'bool' } }
994
995##
996# @PciBridgeInfo:
997#
998# Information about a PCI Bridge device
999#
1000# @bus.number: primary bus interface number. This should be the number of the
1001# bus the device resides on.
1002#
1003# @bus.secondary: secondary bus interface number. This is the number of the
1004# main bus for the bridge
1005#
1006# @bus.subordinate: This is the highest number bus that resides below the
1007# bridge.
1008#
1009# @bus.io_range: The PIO range for all devices on this bridge
1010#
1011# @bus.memory_range: The MMIO range for all devices on this bridge
1012#
1013# @bus.prefetchable_range: The range of prefetchable MMIO for all devices on
1014# this bridge
1015#
1016# @devices: a list of @PciDeviceInfo for each device on this bridge
1017#
1018# Since: 0.14.0
1019##
1020{ 'type': 'PciBridgeInfo',
1021 'data': {'bus': { 'number': 'int', 'secondary': 'int', 'subordinate': 'int',
1022 'io_range': 'PciMemoryRange',
1023 'memory_range': 'PciMemoryRange',
1024 'prefetchable_range': 'PciMemoryRange' },
1025 '*devices': ['PciDeviceInfo']} }
1026
1027##
1028# @PciDeviceInfo:
1029#
1030# Information about a PCI device
1031#
1032# @bus: the bus number of the device
1033#
1034# @slot: the slot the device is located in
1035#
1036# @function: the function of the slot used by the device
1037#
1038# @class_info.desc: #optional a string description of the device's class
1039#
1040# @class_info.class: the class code of the device
1041#
1042# @id.device: the PCI device id
1043#
1044# @id.vendor: the PCI vendor id
1045#
1046# @irq: #optional if an IRQ is assigned to the device, the IRQ number
1047#
1048# @qdev_id: the device name of the PCI device
1049#
1050# @pci_bridge: if the device is a PCI bridge, the bridge information
1051#
1052# @regions: a list of the PCI I/O regions associated with the device
1053#
1054# Notes: the contents of @class_info.desc are not stable and should only be
1055# treated as informational.
1056#
1057# Since: 0.14.0
1058##
1059{ 'type': 'PciDeviceInfo',
1060 'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
1061 'class_info': {'*desc': 'str', 'class': 'int'},
1062 'id': {'device': 'int', 'vendor': 'int'},
1063 '*irq': 'int', 'qdev_id': 'str', '*pci_bridge': 'PciBridgeInfo',
1064 'regions': ['PciMemoryRegion']} }
1065
1066##
1067# @PciInfo:
1068#
1069# Information about a PCI bus
1070#
1071# @bus: the bus index
1072#
1073# @devices: a list of devices on this bus
1074#
1075# Since: 0.14.0
1076##
1077{ 'type': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
1078
1079##
1080# @query-pci:
1081#
1082# Return information about the PCI bus topology of the guest.
1083#
1084# Returns: a list of @PciInfo for each PCI bus
1085#
1086# Since: 0.14.0
1087##
1088{ 'command': 'query-pci', 'returns': ['PciInfo'] }
1089
92aa5c6d
PB
1090##
1091# @BlockdevOnError:
1092#
1093# An enumeration of possible behaviors for errors on I/O operations.
1094# The exact meaning depends on whether the I/O was initiated by a guest
1095# or by a block job
1096#
1097# @report: for guest operations, report the error to the guest;
1098# for jobs, cancel the job
1099#
1100# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR
1101# or BLOCK_JOB_ERROR)
1102#
1103# @enospc: same as @stop on ENOSPC, same as @report otherwise.
1104#
1105# @stop: for guest operations, stop the virtual machine;
1106# for jobs, pause the job
1107#
1108# Since: 1.3
1109##
1110{ 'enum': 'BlockdevOnError',
1111 'data': ['report', 'ignore', 'enospc', 'stop'] }
1112
fb5458cd
SH
1113##
1114# @BlockJobInfo:
1115#
1116# Information about a long-running block device operation.
1117#
1118# @type: the job type ('stream' for image streaming)
1119#
1120# @device: the block device name
1121#
1122# @len: the maximum progress value
1123#
8d65883f
PB
1124# @busy: false if the job is known to be in a quiescent state, with
1125# no pending I/O. Since 1.3.
1126#
8acc72a4
PB
1127# @paused: whether the job is paused or, if @busy is true, will
1128# pause itself as soon as possible. Since 1.3.
1129#
fb5458cd
SH
1130# @offset: the current progress value
1131#
1132# @speed: the rate limit, bytes per second
1133#
1134# Since: 1.1
1135##
1136{ 'type': 'BlockJobInfo',
1137 'data': {'type': 'str', 'device': 'str', 'len': 'int',
8acc72a4 1138 'offset': 'int', 'busy': 'bool', 'paused': 'bool', 'speed': 'int'} }
fb5458cd
SH
1139
1140##
1141# @query-block-jobs:
1142#
1143# Return information about long-running block device operations.
1144#
1145# Returns: a list of @BlockJobInfo for each active block job
1146#
1147# Since: 1.1
1148##
1149{ 'command': 'query-block-jobs', 'returns': ['BlockJobInfo'] }
1150
7a7f325e
LC
1151##
1152# @quit:
1153#
1154# This command will cause the QEMU process to exit gracefully. While every
1155# attempt is made to send the QMP response before terminating, this is not
1156# guaranteed. When using this interface, a premature EOF would not be
1157# unexpected.
1158#
1159# Since: 0.14.0
1160##
1161{ 'command': 'quit' }
5f158f21
LC
1162
1163##
1164# @stop:
1165#
1166# Stop all guest VCPU execution.
1167#
1168# Since: 0.14.0
1169#
1170# Notes: This function will succeed even if the guest is already in the stopped
1171# state
1172##
1173{ 'command': 'stop' }
38d22653
LC
1174
1175##
1176# @system_reset:
1177#
1178# Performs a hard reset of a guest.
1179#
1180# Since: 0.14.0
1181##
1182{ 'command': 'system_reset' }
5bc465e4
LC
1183
1184##
1185# @system_powerdown:
1186#
1187# Requests that a guest perform a powerdown operation.
1188#
1189# Since: 0.14.0
1190#
1191# Notes: A guest may or may not respond to this command. This command
1192# returning does not indicate that a guest has accepted the request or
1193# that it has shut down. Many guests will respond to this command by
1194# prompting the user in some way.
1195##
1196{ 'command': 'system_powerdown' }
755f1968
LC
1197
1198##
1199# @cpu:
1200#
1201# This command is a nop that is only provided for the purposes of compatibility.
1202#
1203# Since: 0.14.0
1204#
1205# Notes: Do not use this command.
1206##
1207{ 'command': 'cpu', 'data': {'index': 'int'} }
0cfd6a9a
LC
1208
1209##
1210# @memsave:
1211#
1212# Save a portion of guest memory to a file.
1213#
1214# @val: the virtual address of the guest to start from
1215#
1216# @size: the size of memory region to save
1217#
1218# @filename: the file to save the memory to as binary data
1219#
1220# @cpu-index: #optional the index of the virtual CPU to use for translating the
1221# virtual address (defaults to CPU 0)
1222#
1223# Returns: Nothing on success
0cfd6a9a
LC
1224#
1225# Since: 0.14.0
1226#
1227# Notes: Errors were not reliably returned until 1.1
1228##
1229{ 'command': 'memsave',
1230 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
6d3962bf
LC
1231
1232##
1233# @pmemsave:
1234#
1235# Save a portion of guest physical memory to a file.
1236#
1237# @val: the physical address of the guest to start from
1238#
1239# @size: the size of memory region to save
1240#
1241# @filename: the file to save the memory to as binary data
1242#
1243# Returns: Nothing on success
6d3962bf
LC
1244#
1245# Since: 0.14.0
1246#
1247# Notes: Errors were not reliably returned until 1.1
1248##
1249{ 'command': 'pmemsave',
1250 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
e42e818b
LC
1251
1252##
1253# @cont:
1254#
1255# Resume guest VCPU execution.
1256#
1257# Since: 0.14.0
1258#
1259# Returns: If successful, nothing
1260# If the QEMU is waiting for an incoming migration, MigrationExpected
1261# If QEMU was started with an encrypted block device and a key has
1262# not yet been set, DeviceEncrypted.
1263#
1264# Notes: This command will succeed if the guest is currently running.
1265##
1266{ 'command': 'cont' }
1267
9b9df25a
GH
1268##
1269# @system_wakeup:
1270#
1271# Wakeup guest from suspend. Does nothing in case the guest isn't suspended.
1272#
1273# Since: 1.1
1274#
1275# Returns: nothing.
1276##
1277{ 'command': 'system_wakeup' }
1278
ab49ab5c
LC
1279##
1280# @inject-nmi:
1281#
1282# Injects an Non-Maskable Interrupt into all guest's VCPUs.
1283#
1284# Returns: If successful, nothing
ab49ab5c
LC
1285#
1286# Since: 0.14.0
1287#
1288# Notes: Only x86 Virtual Machines support this command.
1289##
1290{ 'command': 'inject-nmi' }
4b37156c
LC
1291
1292##
1293# @set_link:
1294#
1295# Sets the link status of a virtual network adapter.
1296#
1297# @name: the device name of the virtual network adapter
1298#
1299# @up: true to set the link status to be up
1300#
1301# Returns: Nothing on success
1302# If @name is not a valid network device, DeviceNotFound
1303#
1304# Since: 0.14.0
1305#
1306# Notes: Not all network adapters support setting link status. This command
1307# will succeed even if the network adapter does not support link status
1308# notification.
1309##
1310{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
a4dea8a9
LC
1311
1312##
1313# @block_passwd:
1314#
1315# This command sets the password of a block device that has not been open
1316# with a password and requires one.
1317#
1318# The two cases where this can happen are a block device is created through
1319# QEMU's initial command line or a block device is changed through the legacy
1320# @change interface.
1321#
1322# In the event that the block device is created through the initial command
1323# line, the VM will start in the stopped state regardless of whether '-S' is
1324# used. The intention is for a management tool to query the block devices to
1325# determine which ones are encrypted, set the passwords with this command, and
1326# then start the guest with the @cont command.
1327#
1328# @device: the name of the device to set the password on
1329#
1330# @password: the password to use for the device
1331#
1332# Returns: nothing on success
1333# If @device is not a valid block device, DeviceNotFound
1334# If @device is not encrypted, DeviceNotEncrypted
a4dea8a9
LC
1335#
1336# Notes: Not all block formats support encryption and some that do are not
1337# able to validate that a password is correct. Disk corruption may
1338# occur if an invalid password is specified.
1339#
1340# Since: 0.14.0
1341##
1342{ 'command': 'block_passwd', 'data': {'device': 'str', 'password': 'str'} }
d72f3264
LC
1343
1344##
1345# @balloon:
1346#
1347# Request the balloon driver to change its balloon size.
1348#
1349# @value: the target size of the balloon in bytes
1350#
1351# Returns: Nothing on success
1352# If the balloon driver is enabled but not functional because the KVM
1353# kernel module cannot support it, KvmMissingCap
1354# If no balloon device is present, DeviceNotActive
1355#
1356# Notes: This command just issues a request to the guest. When it returns,
1357# the balloon size may not have changed. A guest can change the balloon
1358# size independent of this command.
1359#
1360# Since: 0.14.0
1361##
1362{ 'command': 'balloon', 'data': {'value': 'int'} }
5e7caacb
LC
1363
1364##
1365# @block_resize
1366#
1367# Resize a block image while a guest is running.
1368#
1369# @device: the name of the device to get the image resized
1370#
1371# @size: new image size in bytes
1372#
1373# Returns: nothing on success
1374# If @device is not a valid block device, DeviceNotFound
5e7caacb
LC
1375#
1376# Since: 0.14.0
1377##
1378{ 'command': 'block_resize', 'data': { 'device': 'str', 'size': 'int' }}
6106e249 1379
8802d1fd 1380##
bc8b094f
PB
1381# @NewImageMode
1382#
1383# An enumeration that tells QEMU how to set the backing file path in
1384# a new image file.
1385#
1386# @existing: QEMU should look for an existing image file.
1387#
1388# @absolute-paths: QEMU should create a new image with absolute paths
1389# for the backing file.
1390#
1391# Since: 1.1
1392##
1393{ 'enum': 'NewImageMode'
1394 'data': [ 'existing', 'absolute-paths' ] }
1395
8802d1fd 1396##
52e7c241 1397# @BlockdevSnapshot
8802d1fd
JC
1398#
1399# @device: the name of the device to generate the snapshot from.
1400#
1401# @snapshot-file: the target of the new image. A new file will be created.
1402#
1403# @format: #optional the format of the snapshot image, default is 'qcow2'.
6cc2a415
PB
1404#
1405# @mode: #optional whether and how QEMU should create a new image, default is
1406# 'absolute-paths'.
8802d1fd 1407##
52e7c241 1408{ 'type': 'BlockdevSnapshot',
bc8b094f
PB
1409 'data': { 'device': 'str', 'snapshot-file': 'str', '*format': 'str',
1410 '*mode': 'NewImageMode' } }
8802d1fd
JC
1411
1412##
52e7c241 1413# @BlockdevAction
8802d1fd 1414#
52e7c241
PB
1415# A discriminated record of operations that can be performed with
1416# @transaction.
8802d1fd 1417##
52e7c241
PB
1418{ 'union': 'BlockdevAction',
1419 'data': {
1420 'blockdev-snapshot-sync': 'BlockdevSnapshot',
1421 } }
8802d1fd
JC
1422
1423##
52e7c241 1424# @transaction
8802d1fd 1425#
52e7c241
PB
1426# Atomically operate on a group of one or more block devices. If
1427# any operation fails, then the entire set of actions will be
1428# abandoned and the appropriate error returned. The only operation
1429# supported is currently blockdev-snapshot-sync.
8802d1fd
JC
1430#
1431# List of:
52e7c241 1432# @BlockdevAction: information needed for the device snapshot
8802d1fd
JC
1433#
1434# Returns: nothing on success
1435# If @device is not a valid block device, DeviceNotFound
8802d1fd 1436#
52e7c241
PB
1437# Note: The transaction aborts on the first failure. Therefore, there will
1438# be only one device or snapshot file returned in an error condition, and
1439# subsequent actions will not have been attempted.
1440#
1441# Since 1.1
8802d1fd 1442##
52e7c241
PB
1443{ 'command': 'transaction',
1444 'data': { 'actions': [ 'BlockdevAction' ] } }
8802d1fd 1445
6106e249
LC
1446##
1447# @blockdev-snapshot-sync
1448#
1449# Generates a synchronous snapshot of a block device.
1450#
1451# @device: the name of the device to generate the snapshot from.
1452#
1453# @snapshot-file: the target of the new image. If the file exists, or if it
1454# is a device, the snapshot will be created in the existing
1455# file/device. If does not exist, a new file will be created.
1456#
1457# @format: #optional the format of the snapshot image, default is 'qcow2'.
1458#
6cc2a415
PB
1459# @mode: #optional whether and how QEMU should create a new image, default is
1460# 'absolute-paths'.
1461#
6106e249
LC
1462# Returns: nothing on success
1463# If @device is not a valid block device, DeviceNotFound
6106e249 1464#
6106e249
LC
1465# Since 0.14.0
1466##
1467{ 'command': 'blockdev-snapshot-sync',
6cc2a415
PB
1468 'data': { 'device': 'str', 'snapshot-file': 'str', '*format': 'str',
1469 '*mode': 'NewImageMode'} }
d51a67b4
LC
1470
1471##
1472# @human-monitor-command:
1473#
1474# Execute a command on the human monitor and return the output.
1475#
1476# @command-line: the command to execute in the human monitor
1477#
1478# @cpu-index: #optional The CPU to use for commands that require an implicit CPU
1479#
1480# Returns: the output of the command as a string
1481#
1482# Since: 0.14.0
1483#
1484# Notes: This command only exists as a stop-gap. It's use is highly
1485# discouraged. The semantics of this command are not guaranteed.
1486#
1487# Known limitations:
1488#
1489# o This command is stateless, this means that commands that depend
1490# on state information (such as getfd) might not work
1491#
1492# o Commands that prompt the user for data (eg. 'cont' when the block
1493# device is encrypted) don't currently work
1494##
1495{ 'command': 'human-monitor-command',
1496 'data': {'command-line': 'str', '*cpu-index': 'int'},
b80e560b 1497 'returns': 'str' }
6cdedb07
LC
1498
1499##
ed61fc10
JC
1500# @block-commit
1501#
1502# Live commit of data from overlay image nodes into backing nodes - i.e.,
1503# writes data between 'top' and 'base' into 'base'.
1504#
1505# @device: the name of the device
1506#
1507# @base: #optional The file name of the backing image to write data into.
1508# If not specified, this is the deepest backing image
1509#
1510# @top: The file name of the backing image within the image chain,
1511# which contains the topmost data to be committed down.
1512# Note, the active layer as 'top' is currently unsupported.
1513#
1514# If top == base, that is an error.
1515#
1516#
1517# @speed: #optional the maximum speed, in bytes per second
1518#
1519# Returns: Nothing on success
1520# If commit or stream is already active on this device, DeviceInUse
1521# If @device does not exist, DeviceNotFound
1522# If image commit is not supported by this device, NotSupported
1523# If @base or @top is invalid, a generic error is returned
1524# If @top is the active layer, or omitted, a generic error is returned
1525# If @speed is invalid, InvalidParameter
1526#
1527# Since: 1.3
1528#
1529##
1530{ 'command': 'block-commit',
1531 'data': { 'device': 'str', '*base': 'str', 'top': 'str',
1532 '*speed': 'int' } }
1533
6cdedb07
LC
1534# @migrate_cancel
1535#
1536# Cancel the current executing migration process.
1537#
1538# Returns: nothing on success
1539#
1540# Notes: This command succeeds even if there is no migration process running.
1541#
1542# Since: 0.14.0
1543##
1544{ 'command': 'migrate_cancel' }
4f0a993b
LC
1545
1546##
1547# @migrate_set_downtime
1548#
1549# Set maximum tolerated downtime for migration.
1550#
1551# @value: maximum downtime in seconds
1552#
1553# Returns: nothing on success
1554#
1555# Since: 0.14.0
1556##
1557{ 'command': 'migrate_set_downtime', 'data': {'value': 'number'} }
3dc85383
LC
1558
1559##
1560# @migrate_set_speed
1561#
1562# Set maximum speed for migration.
1563#
1564# @value: maximum speed in bytes.
1565#
1566# Returns: nothing on success
1567#
1568# Notes: A value lesser than zero will be automatically round up to zero.
1569#
1570# Since: 0.14.0
1571##
1572{ 'command': 'migrate_set_speed', 'data': {'value': 'int'} }
b4b12c62 1573
9e1ba4cc
OW
1574##
1575# @migrate-set-cache-size
1576#
1577# Set XBZRLE cache size
1578#
1579# @value: cache size in bytes
1580#
1581# The size will be rounded down to the nearest power of 2.
1582# The cache size can be modified before and during ongoing migration
1583#
1584# Returns: nothing on success
1585#
1586# Since: 1.2
1587##
1588{ 'command': 'migrate-set-cache-size', 'data': {'value': 'int'} }
1589
1590##
1591# @query-migrate-cache-size
1592#
1593# query XBZRLE cache size
1594#
1595# Returns: XBZRLE cache size in bytes
1596#
1597# Since: 1.2
1598##
1599{ 'command': 'query-migrate-cache-size', 'returns': 'int' }
1600
b4b12c62 1601##
d03ee401 1602# @ObjectPropertyInfo:
b4b12c62
AL
1603#
1604# @name: the name of the property
1605#
1606# @type: the type of the property. This will typically come in one of four
1607# forms:
1608#
1609# 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
1610# These types are mapped to the appropriate JSON type.
1611#
1612# 2) A legacy type in the form 'legacy<subtype>' where subtype is the
1613# legacy qdev typename. These types are always treated as strings.
1614#
1615# 3) A child type in the form 'child<subtype>' where subtype is a qdev
1616# device type name. Child properties create the composition tree.
1617#
1618# 4) A link type in the form 'link<subtype>' where subtype is a qdev
1619# device type name. Link properties form the device model graph.
1620#
51920820 1621# Since: 1.2
b4b12c62 1622##
57c9fafe 1623{ 'type': 'ObjectPropertyInfo',
b4b12c62
AL
1624 'data': { 'name': 'str', 'type': 'str' } }
1625
1626##
1627# @qom-list:
1628#
57c9fafe 1629# This command will list any properties of a object given a path in the object
b4b12c62
AL
1630# model.
1631#
57c9fafe 1632# @path: the path within the object model. See @qom-get for a description of
b4b12c62
AL
1633# this parameter.
1634#
57c9fafe
AL
1635# Returns: a list of @ObjectPropertyInfo that describe the properties of the
1636# object.
b4b12c62 1637#
51920820 1638# Since: 1.2
b4b12c62
AL
1639##
1640{ 'command': 'qom-list',
1641 'data': { 'path': 'str' },
57c9fafe 1642 'returns': [ 'ObjectPropertyInfo' ] }
eb6e8ea5
AL
1643
1644##
1645# @qom-get:
1646#
57c9fafe 1647# This command will get a property from a object model path and return the
eb6e8ea5
AL
1648# value.
1649#
57c9fafe 1650# @path: The path within the object model. There are two forms of supported
eb6e8ea5
AL
1651# paths--absolute and partial paths.
1652#
57c9fafe 1653# Absolute paths are derived from the root object and can follow child<>
eb6e8ea5
AL
1654# or link<> properties. Since they can follow link<> properties, they
1655# can be arbitrarily long. Absolute paths look like absolute filenames
1656# and are prefixed with a leading slash.
1657#
1658# Partial paths look like relative filenames. They do not begin
1659# with a prefix. The matching rules for partial paths are subtle but
57c9fafe 1660# designed to make specifying objects easy. At each level of the
eb6e8ea5
AL
1661# composition tree, the partial path is matched as an absolute path.
1662# The first match is not returned. At least two matches are searched
1663# for. A successful result is only returned if only one match is
1664# found. If more than one match is found, a flag is return to
1665# indicate that the match was ambiguous.
1666#
1667# @property: The property name to read
1668#
1669# Returns: The property value. The type depends on the property type. legacy<>
1670# properties are returned as #str. child<> and link<> properties are
1671# returns as #str pathnames. All integer property types (u8, u16, etc)
1672# are returned as #int.
1673#
51920820 1674# Since: 1.2
eb6e8ea5
AL
1675##
1676{ 'command': 'qom-get',
1677 'data': { 'path': 'str', 'property': 'str' },
1678 'returns': 'visitor',
1679 'gen': 'no' }
1680
1681##
1682# @qom-set:
1683#
57c9fafe 1684# This command will set a property from a object model path.
eb6e8ea5
AL
1685#
1686# @path: see @qom-get for a description of this parameter
1687#
1688# @property: the property name to set
1689#
1690# @value: a value who's type is appropriate for the property type. See @qom-get
1691# for a description of type mapping.
1692#
51920820 1693# Since: 1.2
eb6e8ea5
AL
1694##
1695{ 'command': 'qom-set',
1696 'data': { 'path': 'str', 'property': 'str', 'value': 'visitor' },
1697 'gen': 'no' }
fbf796fd
LC
1698
1699##
1700# @set_password:
1701#
1702# Sets the password of a remote display session.
1703#
1704# @protocol: `vnc' to modify the VNC server password
1705# `spice' to modify the Spice server password
1706#
1707# @password: the new password
1708#
1709# @connected: #optional how to handle existing clients when changing the
b80e560b 1710# password. If nothing is specified, defaults to `keep'
fbf796fd
LC
1711# `fail' to fail the command if clients are connected
1712# `disconnect' to disconnect existing clients
1713# `keep' to maintain existing clients
1714#
1715# Returns: Nothing on success
1716# If Spice is not enabled, DeviceNotFound
fbf796fd
LC
1717#
1718# Since: 0.14.0
1719##
1720{ 'command': 'set_password',
1721 'data': {'protocol': 'str', 'password': 'str', '*connected': 'str'} }
9ad5372d
LC
1722
1723##
1724# @expire_password:
1725#
1726# Expire the password of a remote display server.
1727#
1728# @protocol: the name of the remote display protocol `vnc' or `spice'
1729#
1730# @time: when to expire the password.
1731# `now' to expire the password immediately
1732# `never' to cancel password expiration
1733# `+INT' where INT is the number of seconds from now (integer)
1734# `INT' where INT is the absolute time in seconds
1735#
1736# Returns: Nothing on success
1737# If @protocol is `spice' and Spice is not active, DeviceNotFound
9ad5372d
LC
1738#
1739# Since: 0.14.0
1740#
1741# Notes: Time is relative to the server and currently there is no way to
1742# coordinate server time with client time. It is not recommended to
1743# use the absolute time version of the @time parameter unless you're
1744# sure you are on the same machine as the QEMU instance.
1745##
1746{ 'command': 'expire_password', 'data': {'protocol': 'str', 'time': 'str'} }
c245b6a3
LC
1747
1748##
1749# @eject:
1750#
1751# Ejects a device from a removable drive.
1752#
1753# @device: The name of the device
1754#
1755# @force: @optional If true, eject regardless of whether the drive is locked.
1756# If not specified, the default value is false.
1757#
1758# Returns: Nothing on success
1759# If @device is not a valid block device, DeviceNotFound
c245b6a3
LC
1760#
1761# Notes: Ejecting a device will no media results in success
1762#
1763# Since: 0.14.0
1764##
1765{ 'command': 'eject', 'data': {'device': 'str', '*force': 'bool'} }
270b243f
LC
1766
1767##
1768# @change-vnc-password:
1769#
1770# Change the VNC server password.
1771#
1772# @target: the new password to use with VNC authentication
1773#
1774# Since: 1.1
1775#
1776# Notes: An empty password in this command will set the password to the empty
1777# string. Existing clients are unaffected by executing this command.
1778##
1779{ 'command': 'change-vnc-password', 'data': {'password': 'str'} }
333a96ec
LC
1780
1781##
1782# @change:
1783#
1784# This command is multiple commands multiplexed together.
1785#
1786# @device: This is normally the name of a block device but it may also be 'vnc'.
1787# when it's 'vnc', then sub command depends on @target
1788#
1789# @target: If @device is a block device, then this is the new filename.
1790# If @device is 'vnc', then if the value 'password' selects the vnc
1791# change password command. Otherwise, this specifies a new server URI
1792# address to listen to for VNC connections.
1793#
1794# @arg: If @device is a block device, then this is an optional format to open
1795# the device with.
1796# If @device is 'vnc' and @target is 'password', this is the new VNC
1797# password to set. If this argument is an empty string, then no future
1798# logins will be allowed.
1799#
1800# Returns: Nothing on success.
1801# If @device is not a valid block device, DeviceNotFound
333a96ec
LC
1802# If the new block device is encrypted, DeviceEncrypted. Note that
1803# if this error is returned, the device has been opened successfully
1804# and an additional call to @block_passwd is required to set the
1805# device's password. The behavior of reads and writes to the block
1806# device between when these calls are executed is undefined.
1807#
1808# Notes: It is strongly recommended that this interface is not used especially
1809# for changing block devices.
1810#
1811# Since: 0.14.0
1812##
1813{ 'command': 'change',
1814 'data': {'device': 'str', 'target': 'str', '*arg': 'str'} }
80047da5
LC
1815
1816##
1817# @block_set_io_throttle:
1818#
1819# Change I/O throttle limits for a block drive.
1820#
1821# @device: The name of the device
1822#
1823# @bps: total throughput limit in bytes per second
1824#
1825# @bps_rd: read throughput limit in bytes per second
1826#
1827# @bps_wr: write throughput limit in bytes per second
1828#
1829# @iops: total I/O operations per second
1830#
1831# @ops_rd: read I/O operations per second
1832#
1833# @iops_wr: write I/O operations per second
1834#
1835# Returns: Nothing on success
1836# If @device is not a valid block device, DeviceNotFound
80047da5
LC
1837#
1838# Since: 1.1
b80e560b 1839##
80047da5
LC
1840{ 'command': 'block_set_io_throttle',
1841 'data': { 'device': 'str', 'bps': 'int', 'bps_rd': 'int', 'bps_wr': 'int',
1842 'iops': 'int', 'iops_rd': 'int', 'iops_wr': 'int' } }
12bd451f 1843
db58f9c0
SH
1844##
1845# @block-stream:
12bd451f
SH
1846#
1847# Copy data from a backing file into a block device.
1848#
1849# The block streaming operation is performed in the background until the entire
1850# backing file has been copied. This command returns immediately once streaming
1851# has started. The status of ongoing block streaming operations can be checked
1852# with query-block-jobs. The operation can be stopped before it has completed
db58f9c0 1853# using the block-job-cancel command.
12bd451f
SH
1854#
1855# If a base file is specified then sectors are not copied from that base file and
1856# its backing chain. When streaming completes the image file will have the base
1857# file as its backing file. This can be used to stream a subset of the backing
1858# file chain instead of flattening the entire image.
1859#
1860# On successful completion the image file is updated to drop the backing file
1861# and the BLOCK_JOB_COMPLETED event is emitted.
1862#
1863# @device: the device name
1864#
1865# @base: #optional the common backing file name
1866#
c83c66c3
SH
1867# @speed: #optional the maximum speed, in bytes per second
1868#
12bd451f 1869# Returns: Nothing on success
12bd451f 1870# If @device does not exist, DeviceNotFound
12bd451f
SH
1871#
1872# Since: 1.1
1873##
c83c66c3
SH
1874{ 'command': 'block-stream', 'data': { 'device': 'str', '*base': 'str',
1875 '*speed': 'int' } }
2d47c6e9
SH
1876
1877##
db58f9c0 1878# @block-job-set-speed:
2d47c6e9
SH
1879#
1880# Set maximum speed for a background block operation.
1881#
1882# This command can only be issued when there is an active block job.
1883#
1884# Throttling can be disabled by setting the speed to 0.
1885#
1886# @device: the device name
1887#
c83c66c3
SH
1888# @speed: the maximum speed, in bytes per second, or 0 for unlimited.
1889# Defaults to 0.
2d47c6e9
SH
1890#
1891# Returns: Nothing on success
05290d80 1892# If no background operation is active on this device, DeviceNotActive
2d47c6e9
SH
1893#
1894# Since: 1.1
1895##
db58f9c0 1896{ 'command': 'block-job-set-speed',
882ec7ce 1897 'data': { 'device': 'str', 'speed': 'int' } }
370521a1
SH
1898
1899##
db58f9c0 1900# @block-job-cancel:
370521a1 1901#
05290d80 1902# Stop an active background block operation.
370521a1 1903#
05290d80 1904# This command returns immediately after marking the active background block
370521a1
SH
1905# operation for cancellation. It is an error to call this command if no
1906# operation is in progress.
1907#
1908# The operation will cancel as soon as possible and then emit the
1909# BLOCK_JOB_CANCELLED event. Before that happens the job is still visible when
1910# enumerated using query-block-jobs.
1911#
05290d80
PB
1912# For streaming, the image file retains its backing file unless the streaming
1913# operation happens to complete just as it is being cancelled. A new streaming
1914# operation can be started at a later time to finish copying all data from the
1915# backing file.
370521a1
SH
1916#
1917# @device: the device name
1918#
6e37fb81
PB
1919# @force: #optional whether to allow cancellation of a paused job (default
1920# false). Since 1.3.
1921#
370521a1 1922# Returns: Nothing on success
05290d80 1923# If no background operation is active on this device, DeviceNotActive
370521a1
SH
1924#
1925# Since: 1.1
1926##
6e37fb81
PB
1927{ 'command': 'block-job-cancel', 'data': { 'device': 'str', '*force': 'bool' } }
1928
1929##
1930# @block-job-pause:
1931#
1932# Pause an active background block operation.
1933#
1934# This command returns immediately after marking the active background block
1935# operation for pausing. It is an error to call this command if no
1936# operation is in progress. Pausing an already paused job has no cumulative
1937# effect; a single block-job-resume command will resume the job.
1938#
1939# The operation will pause as soon as possible. No event is emitted when
1940# the operation is actually paused. Cancelling a paused job automatically
1941# resumes it.
1942#
1943# @device: the device name
1944#
1945# Returns: Nothing on success
1946# If no background operation is active on this device, DeviceNotActive
1947#
1948# Since: 1.3
1949##
1950{ 'command': 'block-job-pause', 'data': { 'device': 'str' } }
1951
1952##
1953# @block-job-resume:
1954#
1955# Resume an active background block operation.
1956#
1957# This command returns immediately after resuming a paused background block
1958# operation. It is an error to call this command if no operation is in
1959# progress. Resuming an already running job is not an error.
1960#
1961# @device: the device name
1962#
1963# Returns: Nothing on success
1964# If no background operation is active on this device, DeviceNotActive
1965#
1966# Since: 1.3
1967##
1968{ 'command': 'block-job-resume', 'data': { 'device': 'str' } }
5eeee3fa
AL
1969
1970##
1971# @ObjectTypeInfo:
1972#
1973# This structure describes a search result from @qom-list-types
1974#
1975# @name: the type name found in the search
1976#
1977# Since: 1.1
1978#
1979# Notes: This command is experimental and may change syntax in future releases.
1980##
1981{ 'type': 'ObjectTypeInfo',
1982 'data': { 'name': 'str' } }
1983
1984##
1985# @qom-list-types:
1986#
1987# This command will return a list of types given search parameters
1988#
1989# @implements: if specified, only return types that implement this type name
1990#
1991# @abstract: if true, include abstract types in the results
1992#
1993# Returns: a list of @ObjectTypeInfo or an empty list if no results are found
1994#
1995# Since: 1.1
5eeee3fa
AL
1996##
1997{ 'command': 'qom-list-types',
1998 'data': { '*implements': 'str', '*abstract': 'bool' },
1999 'returns': [ 'ObjectTypeInfo' ] }
e1c37d0e 2000
1daa31b9
AL
2001##
2002# @DevicePropertyInfo:
2003#
2004# Information about device properties.
2005#
2006# @name: the name of the property
2007# @type: the typename of the property
2008#
2009# Since: 1.2
2010##
2011{ 'type': 'DevicePropertyInfo',
2012 'data': { 'name': 'str', 'type': 'str' } }
2013
2014##
2015# @device-list-properties:
2016#
2017# List properties associated with a device.
2018#
2019# @typename: the type name of a device
2020#
2021# Returns: a list of DevicePropertyInfo describing a devices properties
2022#
2023# Since: 1.2
2024##
2025{ 'command': 'device-list-properties',
2026 'data': { 'typename': 'str'},
2027 'returns': [ 'DevicePropertyInfo' ] }
2028
e1c37d0e
LC
2029##
2030# @migrate
2031#
2032# Migrates the current running guest to another Virtual Machine.
2033#
2034# @uri: the Uniform Resource Identifier of the destination VM
2035#
2036# @blk: #optional do block migration (full disk copy)
2037#
2038# @inc: #optional incremental disk copy migration
2039#
2040# @detach: this argument exists only for compatibility reasons and
2041# is ignored by QEMU
2042#
2043# Returns: nothing on success
2044#
2045# Since: 0.14.0
2046##
2047{ 'command': 'migrate',
2048 'data': {'uri': 'str', '*blk': 'bool', '*inc': 'bool', '*detach': 'bool' } }
33cf629a 2049
a7ae8355
SS
2050# @xen-save-devices-state:
2051#
2052# Save the state of all devices to file. The RAM and the block devices
2053# of the VM are not saved by this command.
2054#
2055# @filename: the file to save the state of the devices to as binary
2056# data. See xen-save-devices-state.txt for a description of the binary
2057# format.
2058#
2059# Returns: Nothing on success
a7ae8355
SS
2060#
2061# Since: 1.1
2062##
2063{ 'command': 'xen-save-devices-state', 'data': {'filename': 'str'} }
a15fef21
LC
2064
2065##
2066# @device_del:
2067#
2068# Remove a device from a guest
2069#
2070# @id: the name of the device
2071#
2072# Returns: Nothing on success
2073# If @id is not a valid device, DeviceNotFound
a15fef21
LC
2074#
2075# Notes: When this command completes, the device may not be removed from the
2076# guest. Hot removal is an operation that requires guest cooperation.
2077# This command merely requests that the guest begin the hot removal
2078# process.
2079#
2080# Since: 0.14.0
2081##
2082{ 'command': 'device_del', 'data': {'id': 'str'} }
783e9b48
WC
2083
2084##
2085# @dump-guest-memory
2086#
2087# Dump guest's memory to vmcore. It is a synchronous operation that can take
2088# very long depending on the amount of guest memory. This command is only
f5b0d93b
LC
2089# supported on i386 and x86_64.
2090#
2091# @paging: if true, do paging to get guest's memory mapping. This allows
2092# using gdb to process the core file. However, setting @paging to false
2093# may be desirable because of two reasons:
2094#
2095# 1. The guest may be in a catastrophic state or can have corrupted
2096# memory, which cannot be trusted
2097# 2. The guest can be in real-mode even if paging is enabled. For example,
2098# the guest uses ACPI to sleep, and ACPI sleep state goes in real-mode
2099#
783e9b48 2100# @protocol: the filename or file descriptor of the vmcore. The supported
f5b0d93b
LC
2101# protocols are:
2102#
783e9b48
WC
2103# 1. file: the protocol starts with "file:", and the following string is
2104# the file's path.
2105# 2. fd: the protocol starts with "fd:", and the following string is the
2106# fd's name.
f5b0d93b 2107#
783e9b48 2108# @begin: #optional if specified, the starting physical address.
f5b0d93b 2109#
783e9b48 2110# @length: #optional if specified, the memory size, in bytes. If you don't
f5b0d93b 2111# want to dump all guest's memory, please specify the start @begin and @length
783e9b48
WC
2112#
2113# Returns: nothing on success
783e9b48
WC
2114#
2115# Since: 1.2
2116##
2117{ 'command': 'dump-guest-memory',
2118 'data': { 'paging': 'bool', 'protocol': 'str', '*begin': 'int',
2119 '*length': 'int' } }
928059a3
LC
2120##
2121# @netdev_add:
2122#
2123# Add a network backend.
2124#
2125# @type: the type of network backend. Current valid values are 'user', 'tap',
2126# 'vde', 'socket', 'dump' and 'bridge'
2127#
2128# @id: the name of the new network backend
2129#
2130# @props: #optional a list of properties to be passed to the backend in
2131# the format 'name=value', like 'ifname=tap0,script=no'
2132#
2133# Notes: The semantics of @props is not well defined. Future commands will be
2134# introduced that provide stronger typing for backend creation.
2135#
2136# Since: 0.14.0
2137#
2138# Returns: Nothing on success
2139# If @type is not a valid network backend, DeviceNotFound
928059a3
LC
2140##
2141{ 'command': 'netdev_add',
2142 'data': {'type': 'str', 'id': 'str', '*props': '**'},
2143 'gen': 'no' }
5f964155
LC
2144
2145##
2146# @netdev_del:
2147#
2148# Remove a network backend.
2149#
2150# @id: the name of the network backend to remove
2151#
2152# Returns: Nothing on success
2153# If @id is not a valid network backend, DeviceNotFound
2154#
2155# Since: 0.14.0
2156##
2157{ 'command': 'netdev_del', 'data': {'id': 'str'} }
208c9d1b 2158
14aa0c2d
LE
2159##
2160# @NetdevNoneOptions
2161#
2162# Use it alone to have zero network devices.
2163#
2164# Since 1.2
2165##
2166{ 'type': 'NetdevNoneOptions',
2167 'data': { } }
2168
2169##
2170# @NetLegacyNicOptions
2171#
2172# Create a new Network Interface Card.
2173#
2174# @netdev: #optional id of -netdev to connect to
2175#
2176# @macaddr: #optional MAC address
2177#
2178# @model: #optional device model (e1000, rtl8139, virtio etc.)
2179#
2180# @addr: #optional PCI device address
2181#
2182# @vectors: #optional number of MSI-x vectors, 0 to disable MSI-X
2183#
2184# Since 1.2
2185##
2186{ 'type': 'NetLegacyNicOptions',
2187 'data': {
2188 '*netdev': 'str',
2189 '*macaddr': 'str',
2190 '*model': 'str',
2191 '*addr': 'str',
2192 '*vectors': 'uint32' } }
2193
2194##
2195# @String
2196#
2197# A fat type wrapping 'str', to be embedded in lists.
2198#
2199# Since 1.2
2200##
2201{ 'type': 'String',
2202 'data': {
2203 'str': 'str' } }
2204
2205##
2206# @NetdevUserOptions
2207#
2208# Use the user mode network stack which requires no administrator privilege to
2209# run.
2210#
2211# @hostname: #optional client hostname reported by the builtin DHCP server
2212#
2213# @restrict: #optional isolate the guest from the host
2214#
2215# @ip: #optional legacy parameter, use net= instead
2216#
2217# @net: #optional IP address and optional netmask
2218#
2219# @host: #optional guest-visible address of the host
2220#
2221# @tftp: #optional root directory of the built-in TFTP server
2222#
2223# @bootfile: #optional BOOTP filename, for use with tftp=
2224#
2225# @dhcpstart: #optional the first of the 16 IPs the built-in DHCP server can
2226# assign
2227#
2228# @dns: #optional guest-visible address of the virtual nameserver
2229#
2230# @smb: #optional root directory of the built-in SMB server
2231#
2232# @smbserver: #optional IP address of the built-in SMB server
2233#
2234# @hostfwd: #optional redirect incoming TCP or UDP host connections to guest
2235# endpoints
2236#
2237# @guestfwd: #optional forward guest TCP connections
2238#
2239# Since 1.2
2240##
2241{ 'type': 'NetdevUserOptions',
2242 'data': {
2243 '*hostname': 'str',
2244 '*restrict': 'bool',
2245 '*ip': 'str',
2246 '*net': 'str',
2247 '*host': 'str',
2248 '*tftp': 'str',
2249 '*bootfile': 'str',
2250 '*dhcpstart': 'str',
2251 '*dns': 'str',
2252 '*smb': 'str',
2253 '*smbserver': 'str',
2254 '*hostfwd': ['String'],
2255 '*guestfwd': ['String'] } }
2256
2257##
2258# @NetdevTapOptions
2259#
2260# Connect the host TAP network interface name to the VLAN.
2261#
2262# @ifname: #optional interface name
2263#
2264# @fd: #optional file descriptor of an already opened tap
2265#
2266# @script: #optional script to initialize the interface
2267#
2268# @downscript: #optional script to shut down the interface
2269#
2270# @helper: #optional command to execute to configure bridge
2271#
2272# @sndbuf: #optional send buffer limit. Understands [TGMKkb] suffixes.
2273#
2274# @vnet_hdr: #optional enable the IFF_VNET_HDR flag on the tap interface
2275#
2276# @vhost: #optional enable vhost-net network accelerator
2277#
2278# @vhostfd: #optional file descriptor of an already opened vhost net device
2279#
2280# @vhostforce: #optional vhost on for non-MSIX virtio guests
2281#
2282# Since 1.2
2283##
2284{ 'type': 'NetdevTapOptions',
2285 'data': {
2286 '*ifname': 'str',
2287 '*fd': 'str',
2288 '*script': 'str',
2289 '*downscript': 'str',
2290 '*helper': 'str',
2291 '*sndbuf': 'size',
2292 '*vnet_hdr': 'bool',
2293 '*vhost': 'bool',
2294 '*vhostfd': 'str',
2295 '*vhostforce': 'bool' } }
2296
2297##
2298# @NetdevSocketOptions
2299#
2300# Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP
2301# socket connection.
2302#
2303# @fd: #optional file descriptor of an already opened socket
2304#
2305# @listen: #optional port number, and optional hostname, to listen on
2306#
2307# @connect: #optional port number, and optional hostname, to connect to
2308#
2309# @mcast: #optional UDP multicast address and port number
2310#
2311# @localaddr: #optional source address and port for multicast and udp packets
2312#
2313# @udp: #optional UDP unicast address and port number
2314#
2315# Since 1.2
2316##
2317{ 'type': 'NetdevSocketOptions',
2318 'data': {
2319 '*fd': 'str',
2320 '*listen': 'str',
2321 '*connect': 'str',
2322 '*mcast': 'str',
2323 '*localaddr': 'str',
2324 '*udp': 'str' } }
2325
2326##
2327# @NetdevVdeOptions
2328#
2329# Connect the VLAN to a vde switch running on the host.
2330#
2331# @sock: #optional socket path
2332#
2333# @port: #optional port number
2334#
2335# @group: #optional group owner of socket
2336#
2337# @mode: #optional permissions for socket
2338#
2339# Since 1.2
2340##
2341{ 'type': 'NetdevVdeOptions',
2342 'data': {
2343 '*sock': 'str',
2344 '*port': 'uint16',
2345 '*group': 'str',
2346 '*mode': 'uint16' } }
2347
2348##
2349# @NetdevDumpOptions
2350#
2351# Dump VLAN network traffic to a file.
2352#
2353# @len: #optional per-packet size limit (64k default). Understands [TGMKkb]
2354# suffixes.
2355#
2356# @file: #optional dump file path (default is qemu-vlan0.pcap)
2357#
2358# Since 1.2
2359##
2360{ 'type': 'NetdevDumpOptions',
2361 'data': {
2362 '*len': 'size',
2363 '*file': 'str' } }
2364
2365##
2366# @NetdevBridgeOptions
2367#
2368# Connect a host TAP network interface to a host bridge device.
2369#
2370# @br: #optional bridge name
2371#
2372# @helper: #optional command to execute to configure bridge
2373#
2374# Since 1.2
2375##
2376{ 'type': 'NetdevBridgeOptions',
2377 'data': {
2378 '*br': 'str',
2379 '*helper': 'str' } }
2380
f6c874e3
SH
2381##
2382# @NetdevHubPortOptions
2383#
2384# Connect two or more net clients through a software hub.
2385#
2386# @hubid: hub identifier number
2387#
2388# Since 1.2
2389##
2390{ 'type': 'NetdevHubPortOptions',
2391 'data': {
2392 'hubid': 'int32' } }
2393
14aa0c2d
LE
2394##
2395# @NetClientOptions
2396#
2397# A discriminated record of network device traits.
2398#
2399# Since 1.2
2400##
2401{ 'union': 'NetClientOptions',
2402 'data': {
f6c874e3
SH
2403 'none': 'NetdevNoneOptions',
2404 'nic': 'NetLegacyNicOptions',
2405 'user': 'NetdevUserOptions',
2406 'tap': 'NetdevTapOptions',
2407 'socket': 'NetdevSocketOptions',
2408 'vde': 'NetdevVdeOptions',
2409 'dump': 'NetdevDumpOptions',
2410 'bridge': 'NetdevBridgeOptions',
2411 'hubport': 'NetdevHubPortOptions' } }
14aa0c2d
LE
2412
2413##
2414# @NetLegacy
2415#
2416# Captures the configuration of a network device; legacy.
2417#
2418# @vlan: #optional vlan number
2419#
2420# @id: #optional identifier for monitor commands
2421#
2422# @name: #optional identifier for monitor commands, ignored if @id is present
2423#
2424# @opts: device type specific properties (legacy)
2425#
2426# Since 1.2
2427##
2428{ 'type': 'NetLegacy',
2429 'data': {
2430 '*vlan': 'int32',
2431 '*id': 'str',
2432 '*name': 'str',
2433 'opts': 'NetClientOptions' } }
2434
2435##
2436# @Netdev
2437#
2438# Captures the configuration of a network device.
2439#
2440# @id: identifier for monitor commands.
2441#
2442# @opts: device type specific properties
2443#
2444# Since 1.2
2445##
2446{ 'type': 'Netdev',
2447 'data': {
2448 'id': 'str',
2449 'opts': 'NetClientOptions' } }
2450
208c9d1b
CB
2451##
2452# @getfd:
2453#
2454# Receive a file descriptor via SCM rights and assign it a name
2455#
2456# @fdname: file descriptor name
2457#
2458# Returns: Nothing on success
208c9d1b
CB
2459#
2460# Since: 0.14.0
2461#
2462# Notes: If @fdname already exists, the file descriptor assigned to
2463# it will be closed and replaced by the received file
2464# descriptor.
2465# The 'closefd' command can be used to explicitly close the
2466# file descriptor when it is no longer needed.
2467##
2468{ 'command': 'getfd', 'data': {'fdname': 'str'} }
2469
2470##
2471# @closefd:
2472#
2473# Close a file descriptor previously passed via SCM rights
2474#
2475# @fdname: file descriptor name
2476#
2477# Returns: Nothing on success
208c9d1b
CB
2478#
2479# Since: 0.14.0
2480##
2481{ 'command': 'closefd', 'data': {'fdname': 'str'} }
01d3c80d
AL
2482
2483##
2484# @MachineInfo:
2485#
2486# Information describing a machine.
2487#
2488# @name: the name of the machine
2489#
2490# @alias: #optional an alias for the machine name
2491#
2492# @default: #optional whether the machine is default
2493#
2494# Since: 1.2.0
2495##
2496{ 'type': 'MachineInfo',
2497 'data': { 'name': 'str', '*alias': 'str',
2498 '*is-default': 'bool' } }
2499
2500##
2501# @query-machines:
2502#
2503# Return a list of supported machines
2504#
2505# Returns: a list of MachineInfo
2506#
2507# Since: 1.2.0
2508##
2509{ 'command': 'query-machines', 'returns': ['MachineInfo'] }
e4e31c63
AL
2510
2511##
2512# @CpuDefinitionInfo:
2513#
2514# Virtual CPU definition.
2515#
2516# @name: the name of the CPU definition
2517#
2518# Since: 1.2.0
2519##
2520{ 'type': 'CpuDefinitionInfo',
2521 'data': { 'name': 'str' } }
2522
2523##
2524# @query-cpu-definitions:
2525#
2526# Return a list of supported virtual CPU definitions
2527#
2528# Returns: a list of CpuDefInfo
2529#
2530# Since: 1.2.0
2531##
2532{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }
ba1c048a
CB
2533
2534# @AddfdInfo:
2535#
2536# Information about a file descriptor that was added to an fd set.
2537#
2538# @fdset-id: The ID of the fd set that @fd was added to.
2539#
2540# @fd: The file descriptor that was received via SCM rights and
2541# added to the fd set.
2542#
2543# Since: 1.2.0
2544##
2545{ 'type': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
2546
2547##
2548# @add-fd:
2549#
2550# Add a file descriptor, that was passed via SCM rights, to an fd set.
2551#
2552# @fdset-id: #optional The ID of the fd set to add the file descriptor to.
2553#
2554# @opaque: #optional A free-form string that can be used to describe the fd.
2555#
2556# Returns: @AddfdInfo on success
2557# If file descriptor was not received, FdNotSupplied
2558# If @fdset-id does not exist, InvalidParameterValue
2559#
2560# Notes: The list of fd sets is shared by all monitor connections.
2561#
2562# If @fdset-id is not specified, a new fd set will be created.
2563#
2564# Since: 1.2.0
2565##
2566{ 'command': 'add-fd', 'data': {'*fdset-id': 'int', '*opaque': 'str'},
2567 'returns': 'AddfdInfo' }
2568
2569##
2570# @remove-fd:
2571#
2572# Remove a file descriptor from an fd set.
2573#
2574# @fdset-id: The ID of the fd set that the file descriptor belongs to.
2575#
2576# @fd: #optional The file descriptor that is to be removed.
2577#
2578# Returns: Nothing on success
2579# If @fdset-id or @fd is not found, FdNotFound
2580#
2581# Since: 1.2.0
2582#
2583# Notes: The list of fd sets is shared by all monitor connections.
2584#
2585# If @fd is not specified, all file descriptors in @fdset-id
2586# will be removed.
2587##
2588{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
2589
2590##
2591# @FdsetFdInfo:
2592#
2593# Information about a file descriptor that belongs to an fd set.
2594#
2595# @fd: The file descriptor value.
2596#
2597# @opaque: #optional A free-form string that can be used to describe the fd.
2598#
2599# Since: 1.2.0
2600##
2601{ 'type': 'FdsetFdInfo',
2602 'data': {'fd': 'int', '*opaque': 'str'} }
2603
2604##
2605# @FdsetInfo:
2606#
2607# Information about an fd set.
2608#
2609# @fdset-id: The ID of the fd set.
2610#
2611# @fds: A list of file descriptors that belong to this fd set.
2612#
2613# Since: 1.2.0
2614##
2615{ 'type': 'FdsetInfo',
2616 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
2617
2618##
2619# @query-fdsets:
2620#
2621# Return information describing all fd sets.
2622#
2623# Returns: A list of @FdsetInfo
2624#
2625# Since: 1.2.0
2626#
2627# Note: The list of fd sets is shared by all monitor connections.
2628#
2629##
2630{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
99afc91d
DB
2631
2632##
2633# @TargetType
2634#
2635# Target CPU emulation type
2636#
2637# These parameters correspond to the softmmu binary CPU name that is currently
2638# running.
2639#
2640# Since: 1.2.0
2641##
2642{ 'enum': 'TargetType',
2643 'data': [ 'alpha', 'arm', 'cris', 'i386', 'lm32', 'm68k', 'microblazeel',
2644 'microblaze', 'mips64el', 'mips64', 'mipsel', 'mips', 'or32',
2645 'ppc64', 'ppcemb', 'ppc', 's390x', 'sh4eb', 'sh4', 'sparc64',
2646 'sparc', 'unicore32', 'x86_64', 'xtensaeb', 'xtensa' ] }
2647
2648##
2649# @TargetInfo:
2650#
2651# Information describing the QEMU target.
2652#
2653# @arch: the target architecture (eg "x86_64", "i386", etc)
2654#
2655# Since: 1.2.0
2656##
2657{ 'type': 'TargetInfo',
2658 'data': { 'arch': 'TargetType' } }
2659
2660##
2661# @query-target:
2662#
2663# Return information about the target for this QEMU
2664#
2665# Returns: TargetInfo
2666#
2667# Since: 1.2.0
2668##
2669{ 'command': 'query-target', 'returns': 'TargetInfo' }
411656f4
AK
2670
2671##
2672# @QKeyCode:
2673#
2674# An enumeration of key name.
2675#
2676# This is used by the send-key command.
2677#
2678# Since: 1.3.0
2679##
2680{ 'enum': 'QKeyCode',
2681 'data': [ 'shift', 'shift_r', 'alt', 'alt_r', 'altgr', 'altgr_r', 'ctrl',
2682 'ctrl_r', 'menu', 'esc', '1', '2', '3', '4', '5', '6', '7', '8',
2683 '9', '0', 'minus', 'equal', 'backspace', 'tab', 'q', 'w', 'e',
2684 'r', 't', 'y', 'u', 'i', 'o', 'p', 'bracket_left', 'bracket_right',
2685 'ret', 'a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'semicolon',
2686 'apostrophe', 'grave_accent', 'backslash', 'z', 'x', 'c', 'v', 'b',
2687 'n', 'm', 'comma', 'dot', 'slash', 'asterisk', 'spc', 'caps_lock',
2688 'f1', 'f2', 'f3', 'f4', 'f5', 'f6', 'f7', 'f8', 'f9', 'f10',
2689 'num_lock', 'scroll_lock', 'kp_divide', 'kp_multiply',
2690 'kp_subtract', 'kp_add', 'kp_enter', 'kp_decimal', 'sysrq', 'kp_0',
2691 'kp_1', 'kp_2', 'kp_3', 'kp_4', 'kp_5', 'kp_6', 'kp_7', 'kp_8',
2692 'kp_9', 'less', 'f11', 'f12', 'print', 'home', 'pgup', 'pgdn', 'end',
2693 'left', 'up', 'down', 'right', 'insert', 'delete', 'stop', 'again',
2694 'props', 'undo', 'front', 'copy', 'open', 'paste', 'find', 'cut',
2695 'lf', 'help', 'meta_l', 'meta_r', 'compose' ] }
e4c8f004
AK
2696
2697##
2698# @send-key:
2699#
2700# Send keys to guest.
2701#
2702# @keys: key sequence. 'keys' is the name of the key. Use a JSON array to
2703# press several keys simultaneously.
2704#
2705# @hold-time: #optional time to delay key up events, milliseconds. Defaults
2706# to 100
2707#
2708# Returns: Nothing on success
2709# If key is unknown or redundant, InvalidParameter
2710#
2711# Since: 1.3.0
2712#
2713##
2714{ 'command': 'send-key',
2715 'data': { 'keys': ['QKeyCode'], '*hold-time': 'int' } }
ad39cf6d
LC
2716
2717##
2718# @screendump:
2719#
2720# Write a PPM of the VGA screen to a file.
2721#
2722# @filename: the path of a new PPM file to store the image
2723#
2724# Returns: Nothing on success
2725#
2726# Since: 0.14.0
2727##
2728{ 'command': 'screendump', 'data': {'filename': 'str'} }