xref: /openbmc/qemu/qapi/control.json (revision eac57306)
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4
5##
6# = QMP monitor control
7##
8
9##
10# @qmp_capabilities:
11#
12# Enable QMP capabilities.
13#
14# Arguments:
15#
16# @enable: An optional list of QMPCapability values to enable.  The
17#     client must not enable any capability that is not mentioned in
18#     the QMP greeting message.  If the field is not provided, it
19#     means no QMP capabilities will be enabled.  (since 2.12)
20#
21# Example:
22#
23#     -> { "execute": "qmp_capabilities",
24#          "arguments": { "enable": [ "oob" ] } }
25#     <- { "return": {} }
26#
27# Notes: This command is valid exactly when first connecting: it must
28#     be issued before any other command will be accepted, and will
29#     fail once the monitor is accepting other commands.  (see qemu
30#     docs/interop/qmp-spec.rst)
31#
32#     The QMP client needs to explicitly enable QMP capabilities,
33#     otherwise all the QMP capabilities will be turned off by
34#     default.
35#
36# Since: 0.13
37##
38{ 'command': 'qmp_capabilities',
39  'data': { '*enable': [ 'QMPCapability' ] },
40  'allow-preconfig': true }
41
42##
43# @QMPCapability:
44#
45# Enumeration of capabilities to be advertised during initial client
46# connection, used for agreeing on particular QMP extension behaviors.
47#
48# @oob: QMP ability to support out-of-band requests.  (Please refer to
49#     qmp-spec.rst for more information on OOB)
50#
51# Since: 2.12
52##
53{ 'enum': 'QMPCapability',
54  'data': [ 'oob' ] }
55
56##
57# @VersionTriple:
58#
59# A three-part version number.
60#
61# @major: The major version number.
62#
63# @minor: The minor version number.
64#
65# @micro: The micro version number.
66#
67# Since: 2.4
68##
69{ 'struct': 'VersionTriple',
70  'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
71
72##
73# @VersionInfo:
74#
75# A description of QEMU's version.
76#
77# @qemu: The version of QEMU.  By current convention, a micro version
78#     of 50 signifies a development branch.  A micro version greater
79#     than or equal to 90 signifies a release candidate for the next
80#     minor version.  A micro version of less than 50 signifies a
81#     stable release.
82#
83# @package: QEMU will always set this field to an empty string.
84#     Downstream versions of QEMU should set this to a non-empty
85#     string.  The exact format depends on the downstream however it
86#     highly recommended that a unique name is used.
87#
88# Since: 0.14
89##
90{ 'struct': 'VersionInfo',
91  'data': {'qemu': 'VersionTriple', 'package': 'str'} }
92
93##
94# @query-version:
95#
96# Returns the current version of QEMU.
97#
98# Returns: A @VersionInfo object describing the current version of
99#     QEMU.
100#
101# Since: 0.14
102#
103# Example:
104#
105#     -> { "execute": "query-version" }
106#     <- {
107#           "return":{
108#              "qemu":{
109#                 "major":0,
110#                 "minor":11,
111#                 "micro":5
112#              },
113#              "package":""
114#           }
115#        }
116##
117{ 'command': 'query-version', 'returns': 'VersionInfo',
118  'allow-preconfig': true }
119
120##
121# @CommandInfo:
122#
123# Information about a QMP command
124#
125# @name: The command name
126#
127# Since: 0.14
128##
129{ 'struct': 'CommandInfo', 'data': {'name': 'str'} }
130
131##
132# @query-commands:
133#
134# Return a list of supported QMP commands by this server
135#
136# Returns: A list of @CommandInfo for all supported commands
137#
138# Since: 0.14
139#
140# Example:
141#
142#     -> { "execute": "query-commands" }
143#     <- {
144#          "return":[
145#             {
146#                "name":"query-balloon"
147#             },
148#             {
149#                "name":"system_powerdown"
150#             }
151#          ]
152#        }
153#
154# Note: This example has been shortened as the real response is too
155#     long.
156##
157{ 'command': 'query-commands', 'returns': ['CommandInfo'],
158  'allow-preconfig': true }
159
160##
161# @quit:
162#
163# This command will cause the QEMU process to exit gracefully.  While
164# every attempt is made to send the QMP response before terminating,
165# this is not guaranteed.  When using this interface, a premature EOF
166# would not be unexpected.
167#
168# Since: 0.14
169#
170# Example:
171#
172#     -> { "execute": "quit" }
173#     <- { "return": {} }
174##
175{ 'command': 'quit',
176  'allow-preconfig': true }
177
178##
179# @MonitorMode:
180#
181# An enumeration of monitor modes.
182#
183# @readline: HMP monitor (human-oriented command line interface)
184#
185# @control: QMP monitor (JSON-based machine interface)
186#
187# Since: 5.0
188##
189{ 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }
190
191##
192# @MonitorOptions:
193#
194# Options to be used for adding a new monitor.
195#
196# @id: Name of the monitor
197#
198# @mode: Selects the monitor mode (default: readline in the system
199#     emulator, control in qemu-storage-daemon)
200#
201# @pretty: Enables pretty printing (QMP only)
202#
203# @chardev: Name of a character device to expose the monitor on
204#
205# Since: 5.0
206##
207{ 'struct': 'MonitorOptions',
208  'data': {
209      '*id': 'str',
210      '*mode': 'MonitorMode',
211      '*pretty': 'bool',
212      'chardev': 'str'
213  } }
214