target/riscv: vmfirst find-first-set mask bit
[qemu.git] / qapi / control.json
1 # -*- Mode: Python -*-
2 #
3
4 ##
5 # = QMP monitor control
6 ##
7
8 ##
9 # @qmp_capabilities:
10 #
11 # Enable QMP capabilities.
12 #
13 # Arguments:
14 #
15 # @enable: An optional list of QMPCapability values to enable.  The
16 #          client must not enable any capability that is not
17 #          mentioned in the QMP greeting message.  If the field is not
18 #          provided, it means no QMP capabilities will be enabled.
19 #          (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 be
28 #        issued before any other command will be accepted, and will fail once the
29 #        monitor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
30 #
31 #        The QMP client needs to explicitly enable QMP capabilities, otherwise
32 #        all the QMP capabilities will be turned off by default.
33 #
34 # Since: 0.13
35 #
36 ##
37 { 'command': 'qmp_capabilities',
38   'data': { '*enable': [ 'QMPCapability' ] },
39   'allow-preconfig': true }
40
41 ##
42 # @QMPCapability:
43 #
44 # Enumeration of capabilities to be advertised during initial client
45 # connection, used for agreeing on particular QMP extension behaviors.
46 #
47 # @oob: QMP ability to support out-of-band requests.
48 #       (Please refer to qmp-spec.txt for more information on OOB)
49 #
50 # Since: 2.12
51 #
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 ##
74 # @VersionInfo:
75 #
76 # A description of QEMU's version.
77 #
78 # @qemu: The version of QEMU.  By current convention, a micro
79 #        version of 50 signifies a development branch.  A micro version
80 #        greater than or equal to 90 signifies a release candidate for
81 #        the next minor version.  A micro version of less than 50
82 #        signifies a stable release.
83 #
84 # @package: QEMU will always set this field to an empty string.  Downstream
85 #           versions of QEMU should set this to a non-empty string.  The
86 #           exact format depends on the downstream however it highly
87 #           recommended that a unique name is used.
88 #
89 # Since: 0.14.0
90 ##
91 { 'struct': 'VersionInfo',
92   'data': {'qemu': 'VersionTriple', 'package': 'str'} }
93
94 ##
95 # @query-version:
96 #
97 # Returns the current version of QEMU.
98 #
99 # Returns: A @VersionInfo object describing the current version of QEMU.
100 #
101 # Since: 0.14.0
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 ##
118 { 'command': 'query-version', 'returns': 'VersionInfo',
119   'allow-preconfig': true }
120
121 ##
122 # @CommandInfo:
123 #
124 # Information about a QMP command
125 #
126 # @name: The command name
127 #
128 # Since: 0.14.0
129 ##
130 { 'struct': 'CommandInfo', 'data': {'name': 'str'} }
131
132 ##
133 # @query-commands:
134 #
135 # Return a list of supported QMP commands by this server
136 #
137 # Returns: A list of @CommandInfo for all supported commands
138 #
139 # Since: 0.14.0
140 #
141 # Example:
142 #
143 # -> { "execute": "query-commands" }
144 # <- {
145 #      "return":[
146 #         {
147 #            "name":"query-balloon"
148 #         },
149 #         {
150 #            "name":"system_powerdown"
151 #         }
152 #      ]
153 #    }
154 #
155 # Note: This example has been shortened as the real response is too long.
156 #
157 ##
158 { 'command': 'query-commands', 'returns': ['CommandInfo'],
159   'allow-preconfig': true }
160
161 ##
162 # @EventInfo:
163 #
164 # Information about a QMP event
165 #
166 # @name: The event name
167 #
168 # Since: 1.2.0
169 ##
170 { 'struct': 'EventInfo', 'data': {'name': 'str'} }
171
172 ##
173 # @query-events:
174 #
175 # Return information on QMP events.
176 #
177 # Features:
178 # @deprecated: This command is deprecated, because its output doesn't
179 #     reflect compile-time configuration.  Use 'query-qmp-schema'
180 #     instead.
181 #
182 # Returns: A list of @EventInfo.
183 #
184 # Since: 1.2.0
185 #
186 # Example:
187 #
188 # -> { "execute": "query-events" }
189 # <- {
190 #      "return": [
191 #          {
192 #             "name":"SHUTDOWN"
193 #          },
194 #          {
195 #             "name":"RESET"
196 #          }
197 #       ]
198 #    }
199 #
200 # Note: This example has been shortened as the real response is too long.
201 #
202 ##
203 { 'command': 'query-events', 'returns': ['EventInfo'],
204   'features': [ 'deprecated' ] }
205
206 ##
207 # @quit:
208 #
209 # This command will cause the QEMU process to exit gracefully.  While every
210 # attempt is made to send the QMP response before terminating, this is not
211 # guaranteed.  When using this interface, a premature EOF would not be
212 # unexpected.
213 #
214 # Since: 0.14.0
215 #
216 # Example:
217 #
218 # -> { "execute": "quit" }
219 # <- { "return": {} }
220 ##
221 { 'command': 'quit' }
222
223 ##
224 # @MonitorMode:
225 #
226 # An enumeration of monitor modes.
227 #
228 # @readline: HMP monitor (human-oriented command line interface)
229 #
230 # @control: QMP monitor (JSON-based machine interface)
231 #
232 # Since: 5.0
233 ##
234 { 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] }
235
236 ##
237 # @MonitorOptions:
238 #
239 # Options to be used for adding a new monitor.
240 #
241 # @id:          Name of the monitor
242 #
243 # @mode:        Selects the monitor mode (default: readline in the system
244 #               emulator, control in qemu-storage-daemon)
245 #
246 # @pretty:      Enables pretty printing (QMP only)
247 #
248 # @chardev:     Name of a character device to expose the monitor on
249 #
250 # Since: 5.0
251 ##
252 { 'struct': 'MonitorOptions',
253   'data': {
254       '*id': 'str',
255       '*mode': 'MonitorMode',
256       '*pretty': 'bool',
257       'chardev': 'str'
258   } }