9 { 'include': 'common.json' }
14 # Allow client connections for VNC, Spice and socket based
15 # character devices to be passed in to QEMU via SCM_RIGHTS.
17 # @protocol: protocol name. Valid names are "vnc", "spice" or the
18 # name of a character device (eg. from -chardev id=XXXX)
20 # @fdname: file descriptor name previously passed via 'getfd' command
22 # @skipauth: whether to skip authentication. Only applies
23 # to "vnc" and "spice" protocols
25 # @tls: whether to perform TLS. Only applies to the "spice"
28 # Returns: nothing on success.
34 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
35 # "fdname": "myclient" } }
39 { 'command': 'add_client',
40 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
46 # Guest name information.
48 # @name: The name of the guest
52 { 'struct': 'NameInfo', 'data': {'*name': 'str'} }
57 # Return the name information of a guest.
59 # Returns: @NameInfo of the guest
65 # -> { "execute": "query-name" }
66 # <- { "return": { "name": "qemu-name" } }
69 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
74 # Information about support for KVM acceleration
76 # @enabled: true if KVM acceleration is active
78 # @present: true if KVM acceleration is built into this executable
82 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
87 # Returns information about KVM acceleration
95 # -> { "execute": "query-kvm" }
96 # <- { "return": { "enabled": true, "present": true } }
99 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
104 # Information about an iothread
106 # @id: the identifier of the iothread
108 # @thread-id: ID of the underlying host thread
110 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
113 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
114 # configured (since 2.9)
116 # @poll-shrink: how many ns will be removed from polling time, 0 means that
117 # it's not configured (since 2.9)
121 { 'struct': 'IOThreadInfo',
122 'data': {'id': 'str',
124 'poll-max-ns': 'int',
126 'poll-shrink': 'int' } }
131 # Returns a list of information about each iothread.
133 # Note: this list excludes the QEMU main loop thread, which is not declared
134 # using the -object iothread command-line option. It is always the main thread
137 # Returns: a list of @IOThreadInfo for each iothread
143 # -> { "execute": "query-iothreads" }
157 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
158 'allow-preconfig': true }
163 # A PCI device memory region
165 # @base: the starting address (guest physical)
167 # @limit: the ending address (guest physical)
171 { 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
176 # Information about a PCI device I/O region.
178 # @bar: the index of the Base Address Register for this region
180 # @type: - 'io' if the region is a PIO region
181 # - 'memory' if the region is a MMIO region
185 # @prefetch: if @type is 'memory', true if the memory is prefetchable
187 # @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
191 { 'struct': 'PciMemoryRegion',
192 'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
193 '*prefetch': 'bool', '*mem_type_64': 'bool' } }
198 # Information about a bus of a PCI Bridge device
200 # @number: primary bus interface number. This should be the number of the
201 # bus the device resides on.
203 # @secondary: secondary bus interface number. This is the number of the
204 # main bus for the bridge
206 # @subordinate: This is the highest number bus that resides below the
209 # @io_range: The PIO range for all devices on this bridge
211 # @memory_range: The MMIO range for all devices on this bridge
213 # @prefetchable_range: The range of prefetchable MMIO for all devices on
218 { 'struct': 'PciBusInfo',
219 'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
220 'io_range': 'PciMemoryRange',
221 'memory_range': 'PciMemoryRange',
222 'prefetchable_range': 'PciMemoryRange' } }
227 # Information about a PCI Bridge device
229 # @bus: information about the bus the device resides on
231 # @devices: a list of @PciDeviceInfo for each device on this bridge
235 { 'struct': 'PciBridgeInfo',
236 'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
241 # Information about the Class of a PCI device
243 # @desc: a string description of the device's class
245 # @class: the class code of the device
249 { 'struct': 'PciDeviceClass',
250 'data': {'*desc': 'str', 'class': 'int'} }
255 # Information about the Id of a PCI device
257 # @device: the PCI device id
259 # @vendor: the PCI vendor id
261 # @subsystem: the PCI subsystem id (since 3.1)
263 # @subsystem-vendor: the PCI subsystem vendor id (since 3.1)
267 { 'struct': 'PciDeviceId',
268 'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int',
269 '*subsystem-vendor': 'int'} }
274 # Information about a PCI device
276 # @bus: the bus number of the device
278 # @slot: the slot the device is located in
280 # @function: the function of the slot used by the device
282 # @class_info: the class of the device
284 # @id: the PCI device id
286 # @irq: if an IRQ is assigned to the device, the IRQ number
288 # @irq_pin: the IRQ pin, zero means no IRQ (since 5.1)
290 # @qdev_id: the device name of the PCI device
292 # @pci_bridge: if the device is a PCI bridge, the bridge information
294 # @regions: a list of the PCI I/O regions associated with the device
296 # Notes: the contents of @class_info.desc are not stable and should only be
297 # treated as informational.
301 { 'struct': 'PciDeviceInfo',
302 'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
303 'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
304 '*irq': 'int', 'irq_pin': 'int', 'qdev_id': 'str',
305 '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion'] }}
310 # Information about a PCI bus
312 # @bus: the bus index
314 # @devices: a list of devices on this bus
318 { 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
323 # Return information about the PCI bus topology of the guest.
325 # Returns: a list of @PciInfo for each PCI bus. Each bus is
326 # represented by a json-object, which has a key with a json-array of
327 # all PCI devices attached to it. Each device is represented by a
334 # -> { "execute": "query-pci" }
345 # "desc": "Host bridge"
361 # "desc": "ISA bridge"
377 # "desc": "IDE controller"
399 # "desc": "VGA controller"
409 # "mem_type_64": false,
412 # "address": 4026531840,
417 # "mem_type_64": false,
420 # "address": 4060086272,
425 # "mem_type_64": false,
440 # "desc": "RAM controller"
461 # Note: This example has been shortened as the real response is too long.
464 { 'command': 'query-pci', 'returns': ['PciInfo'] }
469 # Stop all guest VCPU execution.
473 # Notes: This function will succeed even if the guest is already in the stopped
474 # state. In "inmigrate" state, it will ensure that the guest
475 # remains paused once migration finishes, as if the -S option was
476 # passed on the command line.
480 # -> { "execute": "stop" }
481 # <- { "return": {} }
484 { 'command': 'stop' }
489 # Performs a hard reset of a guest.
495 # -> { "execute": "system_reset" }
496 # <- { "return": {} }
499 { 'command': 'system_reset' }
504 # Requests that a guest perform a powerdown operation.
508 # Notes: A guest may or may not respond to this command. This command
509 # returning does not indicate that a guest has accepted the request or
510 # that it has shut down. Many guests will respond to this command by
511 # prompting the user in some way.
514 # -> { "execute": "system_powerdown" }
515 # <- { "return": {} }
518 { 'command': 'system_powerdown' }
523 # Save a portion of guest memory to a file.
525 # @val: the virtual address of the guest to start from
527 # @size: the size of memory region to save
529 # @filename: the file to save the memory to as binary data
531 # @cpu-index: the index of the virtual CPU to use for translating the
532 # virtual address (defaults to CPU 0)
534 # Returns: Nothing on success
538 # Notes: Errors were not reliably returned until 1.1
542 # -> { "execute": "memsave",
543 # "arguments": { "val": 10,
545 # "filename": "/tmp/virtual-mem-dump" } }
546 # <- { "return": {} }
549 { 'command': 'memsave',
550 'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
555 # Save a portion of guest physical memory to a file.
557 # @val: the physical address of the guest to start from
559 # @size: the size of memory region to save
561 # @filename: the file to save the memory to as binary data
563 # Returns: Nothing on success
567 # Notes: Errors were not reliably returned until 1.1
571 # -> { "execute": "pmemsave",
572 # "arguments": { "val": 10,
574 # "filename": "/tmp/physical-mem-dump" } }
575 # <- { "return": {} }
578 { 'command': 'pmemsave',
579 'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
584 # Resume guest VCPU execution.
588 # Returns: If successful, nothing
590 # Notes: This command will succeed if the guest is currently running. It
591 # will also succeed if the guest is in the "inmigrate" state; in
592 # this case, the effect of the command is to make sure the guest
593 # starts once migration finishes, removing the effect of the -S
594 # command line option if it was passed.
598 # -> { "execute": "cont" }
599 # <- { "return": {} }
602 { 'command': 'cont' }
607 # Exit from "preconfig" state
609 # This command makes QEMU exit the preconfig state and proceed with
610 # VM initialization using configuration data provided on the command line
611 # and via the QMP monitor during the preconfig state. The command is only
612 # available during the preconfig state (i.e. when the --preconfig command
613 # line option was in use).
621 # -> { "execute": "x-exit-preconfig" }
622 # <- { "return": {} }
625 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
630 # Wake up guest from suspend. If the guest has wake-up from suspend
631 # support enabled (wakeup-suspend-support flag from
632 # query-current-machine), wake-up guest from suspend if the guest is
633 # in SUSPENDED state. Return an error otherwise.
639 # Note: prior to 4.0, this command does nothing in case the guest
644 # -> { "execute": "system_wakeup" }
645 # <- { "return": {} }
648 { 'command': 'system_wakeup' }
653 # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
654 # The command fails when the guest doesn't support injecting.
656 # Returns: If successful, nothing
660 # Note: prior to 2.1, this command was only supported for x86 and s390 VMs
664 # -> { "execute": "inject-nmi" }
665 # <- { "return": {} }
668 { 'command': 'inject-nmi' }
671 # @human-monitor-command:
673 # Execute a command on the human monitor and return the output.
675 # @command-line: the command to execute in the human monitor
677 # @cpu-index: The CPU to use for commands that require an implicit CPU
680 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
681 # monitor-owned nodes if they have no parents.
682 # This allows the use of 'savevm' with
683 # -blockdev. (since 4.2)
685 # Returns: the output of the command as a string
689 # Notes: This command only exists as a stop-gap. Its use is highly
690 # discouraged. The semantics of this command are not
691 # guaranteed: this means that command names, arguments and
692 # responses can change or be removed at ANY time. Applications
693 # that rely on long term stability guarantees should NOT
698 # * This command is stateless, this means that commands that depend
699 # on state information (such as getfd) might not work
701 # * Commands that prompt the user for data don't currently work
705 # -> { "execute": "human-monitor-command",
706 # "arguments": { "command-line": "info kvm" } }
707 # <- { "return": "kvm support: enabled\r\n" }
710 { 'command': 'human-monitor-command',
711 'data': {'command-line': 'str', '*cpu-index': 'int'},
713 'features': [ 'savevm-monitor-nodes' ] }
718 # This command is multiple commands multiplexed together.
720 # @device: This is normally the name of a block device but it may also be 'vnc'.
721 # when it's 'vnc', then sub command depends on @target
723 # @target: If @device is a block device, then this is the new filename.
724 # If @device is 'vnc', then if the value 'password' selects the vnc
725 # change password command. Otherwise, this specifies a new server URI
726 # address to listen to for VNC connections.
728 # @arg: If @device is a block device, then this is an optional format to open
730 # If @device is 'vnc' and @target is 'password', this is the new VNC
731 # password to set. See change-vnc-password for additional notes.
734 # @deprecated: This command is deprecated. For changing block
735 # devices, use 'blockdev-change-medium' instead; for changing VNC
736 # parameters, use 'change-vnc-password' instead.
738 # Returns: - Nothing on success.
739 # - If @device is not a valid block device, DeviceNotFound
745 # 1. Change a removable medium
747 # -> { "execute": "change",
748 # "arguments": { "device": "ide1-cd0",
749 # "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
750 # <- { "return": {} }
752 # 2. Change VNC password
754 # -> { "execute": "change",
755 # "arguments": { "device": "vnc", "target": "password",
756 # "arg": "foobar1" } }
757 # <- { "return": {} }
760 { 'command': 'change',
761 'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
762 'features': [ 'deprecated' ] }
765 # @xen-set-global-dirty-log:
767 # Enable or disable the global dirty log mode.
769 # @enable: true to enable, false to disable.
777 # -> { "execute": "xen-set-global-dirty-log",
778 # "arguments": { "enable": true } }
779 # <- { "return": {} }
782 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
787 # Receive a file descriptor via SCM rights and assign it a name
789 # @fdname: file descriptor name
791 # Returns: Nothing on success
795 # Notes: If @fdname already exists, the file descriptor assigned to
796 # it will be closed and replaced by the received file
799 # The 'closefd' command can be used to explicitly close the
800 # file descriptor when it is no longer needed.
804 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
805 # <- { "return": {} }
808 { 'command': 'getfd', 'data': {'fdname': 'str'} }
813 # Close a file descriptor previously passed via SCM rights
815 # @fdname: file descriptor name
817 # Returns: Nothing on success
823 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
824 # <- { "return": {} }
827 { 'command': 'closefd', 'data': {'fdname': 'str'} }
832 # Information about a file descriptor that was added to an fd set.
834 # @fdset-id: The ID of the fd set that @fd was added to.
836 # @fd: The file descriptor that was received via SCM rights and
837 # added to the fd set.
841 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
846 # Add a file descriptor, that was passed via SCM rights, to an fd set.
848 # @fdset-id: The ID of the fd set to add the file descriptor to.
850 # @opaque: A free-form string that can be used to describe the fd.
852 # Returns: - @AddfdInfo on success
853 # - If file descriptor was not received, FdNotSupplied
854 # - If @fdset-id is a negative value, InvalidParameterValue
856 # Notes: The list of fd sets is shared by all monitor connections.
858 # If @fdset-id is not specified, a new fd set will be created.
864 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
865 # <- { "return": { "fdset-id": 1, "fd": 3 } }
868 { 'command': 'add-fd',
869 'data': { '*fdset-id': 'int',
871 'returns': 'AddfdInfo' }
876 # Remove a file descriptor from an fd set.
878 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
880 # @fd: The file descriptor that is to be removed.
882 # Returns: - Nothing on success
883 # - If @fdset-id or @fd is not found, FdNotFound
887 # Notes: The list of fd sets is shared by all monitor connections.
889 # If @fd is not specified, all file descriptors in @fdset-id
894 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
895 # <- { "return": {} }
898 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
903 # Information about a file descriptor that belongs to an fd set.
905 # @fd: The file descriptor value.
907 # @opaque: A free-form string that can be used to describe the fd.
911 { 'struct': 'FdsetFdInfo',
912 'data': {'fd': 'int', '*opaque': 'str'} }
917 # Information about an fd set.
919 # @fdset-id: The ID of the fd set.
921 # @fds: A list of file descriptors that belong to this fd set.
925 { 'struct': 'FdsetInfo',
926 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
931 # Return information describing all fd sets.
933 # Returns: A list of @FdsetInfo
937 # Note: The list of fd sets is shared by all monitor connections.
941 # -> { "execute": "query-fdsets" }
947 # "opaque": "rdonly:/path/to/file"
951 # "opaque": "rdwr:/path/to/file"
971 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
974 # @CommandLineParameterType:
976 # Possible types for an option parameter.
978 # @string: accepts a character string
980 # @boolean: accepts "on" or "off"
982 # @number: accepts a number
984 # @size: accepts a number followed by an optional suffix (K)ilo,
985 # (M)ega, (G)iga, (T)era
989 { 'enum': 'CommandLineParameterType',
990 'data': ['string', 'boolean', 'number', 'size'] }
993 # @CommandLineParameterInfo:
995 # Details about a single parameter of a command line option.
997 # @name: parameter name
999 # @type: parameter @CommandLineParameterType
1001 # @help: human readable text string, not suitable for parsing.
1003 # @default: default value string (since 2.1)
1007 { 'struct': 'CommandLineParameterInfo',
1008 'data': { 'name': 'str',
1009 'type': 'CommandLineParameterType',
1011 '*default': 'str' } }
1014 # @CommandLineOptionInfo:
1016 # Details about a command line option, including its list of parameter details
1018 # @option: option name
1020 # @parameters: an array of @CommandLineParameterInfo
1024 { 'struct': 'CommandLineOptionInfo',
1025 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
1028 # @query-command-line-options:
1030 # Query command line option schema.
1032 # @option: option name
1034 # Returns: list of @CommandLineOptionInfo for all options (or for the given
1035 # @option). Returns an error if the given @option doesn't exist.
1041 # -> { "execute": "query-command-line-options",
1042 # "arguments": { "option": "option-rom" } }
1047 # "name": "romfile",
1051 # "name": "bootindex",
1055 # "option": "option-rom"
1061 {'command': 'query-command-line-options',
1062 'data': { '*option': 'str' },
1063 'returns': ['CommandLineOptionInfo'],
1064 'allow-preconfig': true }
1069 # Mode of the replay subsystem.
1071 # @none: normal execution mode. Replay or record are not enabled.
1073 # @record: record mode. All non-deterministic data is written into the
1076 # @play: replay mode. Non-deterministic data required for system execution
1077 # is read from the log.
1081 { 'enum': 'ReplayMode',
1082 'data': [ 'none', 'record', 'play' ] }
1085 # @xen-load-devices-state:
1087 # Load the state of all devices from file. The RAM and the block devices
1088 # of the VM are not loaded by this command.
1090 # @filename: the file to load the state of the devices from as binary
1091 # data. See xen-save-devices-state.txt for a description of the binary
1098 # -> { "execute": "xen-load-devices-state",
1099 # "arguments": { "filename": "/tmp/resume" } }
1100 # <- { "return": {} }
1103 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }