vhost: switch to use IOTLB v2 format
[qemu.git] / qapi / control.json
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
18 #          mentioned in the QMP greeting message.  If the field is not
19 #          provided, it means no QMP capabilities will be enabled.
20 #          (since 2.12)
21 #
22 # Example:
23 #
24 # -> { "execute": "qmp_capabilities",
25 #      "arguments": { "enable": [ "oob" ] } }
26 # <- { "return": {} }
27 #
28 # Notes: This command is valid exactly when first connecting: it must be
29 #        issued before any other command will be accepted, and will fail once the
30 #        monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
31 #
32 #        The QMP client needs to explicitly enable QMP capabilities, otherwise
33 #        all the QMP capabilities will be turned off by default.
34 #
35 # Since: 0.13
36 #
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.
49 #       (Please refer to qmp-spec.txt for more information on OOB)
50 #
51 # Since: 2.12
52 #
53 ##
54 { 'enum': 'QMPCapability',
55   'data': [ 'oob' ] }
56
57 ##
58 # @VersionTriple:
59 #
60 # A three-part version number.
61 #
62 # @major: The major version number.
63 #
64 # @minor: The minor version number.
65 #
66 # @micro: The micro version number.
67 #
68 # Since: 2.4
69 ##
70 { 'struct': 'VersionTriple',
71   'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} }
72
73
74 ##
75 # @VersionInfo:
76 #
77 # A description of QEMU's version.
78 #
79 # @qemu: The version of QEMU.  By current convention, a micro
80 #        version of 50 signifies a development branch.  A micro version
81 #        greater than or equal to 90 signifies a release candidate for
82 #        the next minor version.  A micro version of less than 50
83 #        signifies a stable release.
84 #
85 # @package: QEMU will always set this field to an empty string.  Downstream
86 #           versions of QEMU should set this to a non-empty string.  The
87 #           exact format depends on the downstream however it highly
88 #           recommended that a unique name is used.
89 #
90 # Since: 0.14.0
91 ##
92 { 'struct': 'VersionInfo',
93   'data': {'qemu': 'VersionTriple', 'package': 'str'} }
94
95 ##
96 # @query-version:
97 #
98 # Returns the current version of QEMU.
99 #
100 # Returns: A @VersionInfo object describing the current version of QEMU.
101 #
102 # Since: 0.14.0
103 #
104 # Example:
105 #
106 # -> { "execute": "query-version" }
107 # <- {
108 #       "return":{
109 #          "qemu":{
110 #             "major":0,
111 #             "minor":11,
112 #             "micro":5
113 #          },
114 #          "package":""
115 #       }
116 #    }
117 #
118 ##
119 { 'command': 'query-version', 'returns': 'VersionInfo',
120   'allow-preconfig': true }
121
122 ##
123 # @CommandInfo:
124 #
125 # Information about a QMP command
126 #
127 # @name: The command name
128 #
129 # Since: 0.14.0
130 ##
131 { 'struct': 'CommandInfo', 'data': {'name': 'str'} }
132
133 ##
134 # @query-commands:
135 #
136 # Return a list of supported QMP commands by this server
137 #
138 # Returns: A list of @CommandInfo for all supported commands
139 #
140 # Since: 0.14.0
141 #
142 # Example:
143 #
144 # -> { "execute": "query-commands" }
145 # <- {
146 #      "return":[
147 #         {
148 #            "name":"query-balloon"
149 #         },
150 #         {
151 #            "name":"system_powerdown"
152 #         }
153 #      ]
154 #    }
155 #
156 # Note: This example has been shortened as the real response is too long.
157 #
158 ##
159 { 'command': 'query-commands', 'returns': ['CommandInfo'],
160   'allow-preconfig': true }
161
162 ##
163 # @EventInfo:
164 #
165 # Information about a QMP event
166 #
167 # @name: The event name
168 #
169 # Since: 1.2.0
170 ##
171 { 'struct': 'EventInfo', 'data': {'name': 'str'} }
172
173 ##
174 # @query-events:
175 #
176 # Return information on QMP events.
177 #
178 # Features:
179 # @deprecated: This command is deprecated, because its output doesn't
180 #              reflect compile-time configuration.  Use 'query-qmp-schema'
181 #              instead.
182 #
183 # Returns: A list of @EventInfo.
184 #
185 # Since: 1.2.0
186 #
187 # Example:
188 #
189 # -> { "execute": "query-events" }
190 # <- {
191 #      "return": [
192 #          {
193 #             "name":"SHUTDOWN"
194 #          },
195 #          {
196 #             "name":"RESET"
197 #          }
198 #       ]
199 #    }
200 #
201 # Note: This example has been shortened as the real response is too long.
202 #
203 ##
204 { 'command': 'query-events', 'returns': ['EventInfo'],
205   'features': [ 'deprecated' ] }
206
207 ##
208 # @quit:
209 #
210 # This command will cause the QEMU process to exit gracefully.  While every
211 # attempt is made to send the QMP response before terminating, this is not
212 # guaranteed.  When using this interface, a premature EOF would not be
213 # unexpected.
214 #
215 # Since: 0.14.0
216 #
217 # Example:
218 #
219 # -> { "execute": "quit" }
220 # <- { "return": {} }
221 ##
222 { 'command': 'quit' }
223
224 ##
225 # @MonitorMode:
226 #
227 # An enumeration of monitor modes.
228 #
229 # @readline: HMP monitor (human-oriented command line interface)
230 #
231 # @control: QMP monitor (JSON-based machine interface)
232 #
233 # Since: 5.0
234 ##
235 { 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }
236
237 ##
238 # @MonitorOptions:
239 #
240 # Options to be used for adding a new monitor.
241 #
242 # @id:          Name of the monitor
243 #
244 # @mode:        Selects the monitor mode (default: readline in the system
245 #               emulator, control in qemu-storage-daemon)
246 #
247 # @pretty:      Enables pretty printing (QMP only)
248 #
249 # @chardev:     Name of a character device to expose the monitor on
250 #
251 # Since: 5.0
252 ##
253 { 'struct': 'MonitorOptions',
254   'data': {
255       '*id': 'str',
256       '*mode': 'MonitorMode',
257       '*pretty': 'bool',
258       'chardev': 'str'
259   } }