xref: /openbmc/qemu/qapi/control.json (revision 3aefee3e)
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 # @enable: An optional list of QMPCapability values to enable.  The
15 #     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)
18 #
19 # .. qmp-example::
20 #
21 #     -> { "execute": "qmp_capabilities",
22 #          "arguments": { "enable": [ "oob" ] } }
23 #     <- { "return": {} }
24 #
25 # .. 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`)
29 #
30 # .. note:: The QMP client needs to explicitly enable QMP
31 #    capabilities, otherwise all the QMP capabilities will be turned
32 #    off by default.
33 #
34 # Since: 0.13
35 ##
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 #
46 # @oob: QMP ability to support out-of-band requests.  (Please refer to
47 #     qmp-spec.rst for more information on OOB)
48 #
49 # Since: 2.12
50 ##
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 
70 ##
71 # @VersionInfo:
72 #
73 # A description of QEMU's version.
74 #
75 # @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.
80 #
81 # @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.
85 #
86 # Since: 0.14
87 ##
88 { 'struct': 'VersionInfo',
89   'data': {'qemu': 'VersionTriple', 'package': 'str'} }
90 
91 ##
92 # @query-version:
93 #
94 # Returns the current version of QEMU.
95 #
96 # Returns: A @VersionInfo object describing the current version of
97 #     QEMU.
98 #
99 # Since: 0.14
100 #
101 # .. qmp-example::
102 #
103 #     -> { "execute": "query-version" }
104 #     <- {
105 #           "return":{
106 #              "qemu":{
107 #                 "major":0,
108 #                 "minor":11,
109 #                 "micro":5
110 #              },
111 #              "package":""
112 #           }
113 #        }
114 ##
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 #
125 # Since: 0.14
126 ##
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 #
136 # Since: 0.14
137 #
138 # .. qmp-example::
139 #
140 #     -> { "execute": "query-commands" }
141 #     <- {
142 #          "return":[
143 #             {
144 #                "name":"query-balloon"
145 #             },
146 #             {
147 #                "name":"system_powerdown"
148 #             },
149 #             ...
150 #          ]
151 #        }
152 #
153 # This example has been shortened as the real response is too long.
154 ##
155 { 'command': 'query-commands', 'returns': ['CommandInfo'],
156   'allow-preconfig': true }
157 
158 ##
159 # @quit:
160 #
161 # 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.
165 #
166 # Since: 0.14
167 #
168 # .. qmp-example::
169 #
170 #     -> { "execute": "quit" }
171 #     <- { "return": {} }
172 ##
173 { 'command': 'quit',
174   'allow-preconfig': true }
175 
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 #
194 # @id: Name of the monitor
195 #
196 # @mode: Selects the monitor mode (default: readline in the system
197 #     emulator, control in qemu-storage-daemon)
198 #
199 # @pretty: Enables pretty printing (QMP only)
200 #
201 # @chardev: Name of a character device to expose the monitor on
202 #
203 # Since: 5.0
204 ##
205 { 'struct': 'MonitorOptions',
206   'data': {
207       '*id': 'str',
208       '*mode': 'MonitorMode',
209       '*pretty': 'bool',
210       'chardev': 'str'
211   } }
212