blob: 336386f79e10cb5088a89547f7b2649348086757 [file] [log] [blame]
Kevin Wolffa4dcf52020-01-29 11:22:37 +01001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Kevin Wolffa4dcf52020-01-29 11:22:37 +01003#
4
5##
6# = QMP monitor control
7##
8
9##
10# @qmp_capabilities:
11#
12# Enable QMP capabilities.
13#
Kevin Wolffa4dcf52020-01-29 11:22:37 +010014# @enable: An optional list of QMPCapability values to enable. The
Markus Armbrustera937b6a2023-04-28 12:54:29 +020015# client must not enable any capability that is not mentioned in
16# the QMP greeting message. If the field is not provided, it
17# means no QMP capabilities will be enabled. (since 2.12)
Kevin Wolffa4dcf52020-01-29 11:22:37 +010018#
John Snow14b48aa2024-07-16 22:13:08 -040019# .. qmp-example::
Kevin Wolffa4dcf52020-01-29 11:22:37 +010020#
Markus Armbrusterd23055b2024-02-16 15:58:34 +010021# -> { "execute": "qmp_capabilities",
22# "arguments": { "enable": [ "oob" ] } }
23# <- { "return": {} }
Kevin Wolffa4dcf52020-01-29 11:22:37 +010024#
Markus Armbruster01bed0f2024-07-29 08:52:20 +020025# .. note:: This command is valid exactly when first connecting: it
26# must be issued before any other command will be accepted, and
27# will fail once the monitor is accepting other commands. (see
28# :doc:`/interop/qmp-spec`)
Kevin Wolffa4dcf52020-01-29 11:22:37 +010029#
Markus Armbruster01bed0f2024-07-29 08:52:20 +020030# .. note:: The QMP client needs to explicitly enable QMP
31# capabilities, otherwise all the QMP capabilities will be turned
32# off by default.
Kevin Wolffa4dcf52020-01-29 11:22:37 +010033#
34# Since: 0.13
Kevin Wolffa4dcf52020-01-29 11:22:37 +010035##
36{ 'command': 'qmp_capabilities',
37 'data': { '*enable': [ 'QMPCapability' ] },
38 'allow-preconfig': true }
39
40##
41# @QMPCapability:
42#
43# Enumeration of capabilities to be advertised during initial client
44# connection, used for agreeing on particular QMP extension behaviors.
45#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020046# @oob: QMP ability to support out-of-band requests. (Please refer to
Peter Maydelld5657252023-05-15 17:22:43 +010047# qmp-spec.rst for more information on OOB)
Kevin Wolffa4dcf52020-01-29 11:22:37 +010048#
49# Since: 2.12
Kevin Wolffa4dcf52020-01-29 11:22:37 +010050##
51{ 'enum': 'QMPCapability',
52 'data': [ 'oob' ] }
53
54##
55# @VersionTriple:
56#
57# A three-part version number.
58#
59# @major: The major version number.
60#
61# @minor: The minor version number.
62#
63# @micro: The micro version number.
64#
65# Since: 2.4
66##
67{ 'struct': 'VersionTriple',
68 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
69
Kevin Wolffa4dcf52020-01-29 11:22:37 +010070##
71# @VersionInfo:
72#
73# A description of QEMU's version.
74#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020075# @qemu: The version of QEMU. By current convention, a micro version
76# of 50 signifies a development branch. A micro version greater
77# than or equal to 90 signifies a release candidate for the next
78# minor version. A micro version of less than 50 signifies a
79# stable release.
Kevin Wolffa4dcf52020-01-29 11:22:37 +010080#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020081# @package: QEMU will always set this field to an empty string.
82# Downstream versions of QEMU should set this to a non-empty
83# string. The exact format depends on the downstream however it
84# highly recommended that a unique name is used.
Kevin Wolffa4dcf52020-01-29 11:22:37 +010085#
Markus Armbruster9bc6e892020-11-18 07:41:58 +010086# Since: 0.14
Kevin Wolffa4dcf52020-01-29 11:22:37 +010087##
88{ 'struct': 'VersionInfo',
89 'data': {'qemu': 'VersionTriple', 'package': 'str'} }
90
91##
92# @query-version:
93#
94# Returns the current version of QEMU.
95#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020096# Returns: A @VersionInfo object describing the current version of
97# QEMU.
Kevin Wolffa4dcf52020-01-29 11:22:37 +010098#
Markus Armbruster9bc6e892020-11-18 07:41:58 +010099# Since: 0.14
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100100#
John Snow14b48aa2024-07-16 22:13:08 -0400101# .. qmp-example::
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100102#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100103# -> { "execute": "query-version" }
104# <- {
105# "return":{
106# "qemu":{
107# "major":0,
108# "minor":11,
109# "micro":5
110# },
111# "package":""
112# }
113# }
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100114##
115{ 'command': 'query-version', 'returns': 'VersionInfo',
116 'allow-preconfig': true }
117
118##
119# @CommandInfo:
120#
121# Information about a QMP command
122#
123# @name: The command name
124#
Markus Armbruster9bc6e892020-11-18 07:41:58 +0100125# Since: 0.14
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100126##
127{ 'struct': 'CommandInfo', 'data': {'name': 'str'} }
128
129##
130# @query-commands:
131#
132# Return a list of supported QMP commands by this server
133#
134# Returns: A list of @CommandInfo for all supported commands
135#
Markus Armbruster9bc6e892020-11-18 07:41:58 +0100136# Since: 0.14
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100137#
John Snow14b48aa2024-07-16 22:13:08 -0400138# .. qmp-example::
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100139#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100140# -> { "execute": "query-commands" }
141# <- {
142# "return":[
143# {
144# "name":"query-balloon"
145# },
146# {
147# "name":"system_powerdown"
John Snow9f2b8482024-06-26 18:21:14 -0400148# },
149# ...
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100150# ]
151# }
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100152#
John Snowd461c272024-06-26 18:21:16 -0400153# This example has been shortened as the real response is too long.
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100154##
155{ 'command': 'query-commands', 'returns': ['CommandInfo'],
156 'allow-preconfig': true }
157
158##
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100159# @quit:
160#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200161# This command will cause the QEMU process to exit gracefully. While
162# every attempt is made to send the QMP response before terminating,
163# this is not guaranteed. When using this interface, a premature EOF
164# would not be unexpected.
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100165#
Markus Armbruster9bc6e892020-11-18 07:41:58 +0100166# Since: 0.14
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100167#
John Snow14b48aa2024-07-16 22:13:08 -0400168# .. qmp-example::
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100169#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100170# -> { "execute": "quit" }
171# <- { "return": {} }
Kevin Wolffa4dcf52020-01-29 11:22:37 +0100172##
Paolo Bonziniebe34442020-10-27 06:56:32 -0400173{ 'command': 'quit',
174 'allow-preconfig': true }
Kevin Wolff2098722020-02-24 15:30:04 +0100175
176##
177# @MonitorMode:
178#
179# An enumeration of monitor modes.
180#
181# @readline: HMP monitor (human-oriented command line interface)
182#
183# @control: QMP monitor (JSON-based machine interface)
184#
185# Since: 5.0
186##
187{ 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }
188
189##
190# @MonitorOptions:
191#
192# Options to be used for adding a new monitor.
193#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200194# @id: Name of the monitor
Kevin Wolff2098722020-02-24 15:30:04 +0100195#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200196# @mode: Selects the monitor mode (default: readline in the system
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200197# emulator, control in qemu-storage-daemon)
Kevin Wolff2098722020-02-24 15:30:04 +0100198#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200199# @pretty: Enables pretty printing (QMP only)
Kevin Wolff2098722020-02-24 15:30:04 +0100200#
Andrea Bolognanic0ac5332022-05-03 09:37:36 +0200201# @chardev: Name of a character device to expose the monitor on
Kevin Wolff2098722020-02-24 15:30:04 +0100202#
203# Since: 5.0
204##
205{ 'struct': 'MonitorOptions',
206 'data': {
207 '*id': 'str',
208 '*mode': 'MonitorMode',
209 '*pretty': 'bool',
210 'chardev': 'str'
211 } }