capstone: Update to upstream "next" branch
[qemu.git] / qapi / run-state.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
4
5 ##
6 # = VM run state
7 ##
8
9 ##
10 # @RunState:
11 #
12 # An enumeration of VM run states.
13 #
14 # @debug: QEMU is running on a debugger
15 #
16 # @finish-migrate: guest is paused to finish the migration process
17 #
18 # @inmigrate: guest is paused waiting for an incoming migration.  Note
19 #             that this state does not tell whether the machine will start at the
20 #             end of the migration.  This depends on the command-line -S option and
21 #             any invocation of 'stop' or 'cont' that has happened since QEMU was
22 #             started.
23 #
24 # @internal-error: An internal error that prevents further guest execution
25 #                  has occurred
26 #
27 # @io-error: the last IOP has failed and the device is configured to pause
28 #            on I/O errors
29 #
30 # @paused: guest has been paused via the 'stop' command
31 #
32 # @postmigrate: guest is paused following a successful 'migrate'
33 #
34 # @prelaunch: QEMU was started with -S and guest has not started
35 #
36 # @restore-vm: guest is paused to restore VM state
37 #
38 # @running: guest is actively running
39 #
40 # @save-vm: guest is paused to save the VM state
41 #
42 # @shutdown: guest is shut down (and -no-shutdown is in use)
43 #
44 # @suspended: guest is suspended (ACPI S3)
45 #
46 # @watchdog: the watchdog action is configured to pause and has been triggered
47 #
48 # @guest-panicked: guest has been panicked as a result of guest OS panic
49 #
50 # @colo: guest is paused to save/restore VM state under colo checkpoint,
51 #        VM can not get into this state unless colo capability is enabled
52 #        for migration. (since 2.8)
53 # @preconfig: QEMU is paused before board specific init callback is executed.
54 #             The state is reachable only if the --preconfig CLI option is used.
55 #             (Since 3.0)
56 ##
57 { 'enum': 'RunState',
58   'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
59             'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
60             'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',
61             'guest-panicked', 'colo', 'preconfig' ] }
62
63 ##
64 # @ShutdownCause:
65 #
66 # An enumeration of reasons for a Shutdown.
67 #
68 # @none: No shutdown request pending
69 #
70 # @host-error: An error prevents further use of guest
71 #
72 # @host-qmp-quit: Reaction to the QMP command 'quit'
73 #
74 # @host-qmp-system-reset: Reaction to the QMP command 'system_reset'
75 #
76 # @host-signal: Reaction to a signal, such as SIGINT
77 #
78 # @host-ui: Reaction to a UI event, like window close
79 #
80 # @guest-shutdown: Guest shutdown/suspend request, via ACPI or other
81 #                  hardware-specific means
82 #
83 # @guest-reset: Guest reset request, and command line turns that into
84 #               a shutdown
85 #
86 # @guest-panic: Guest panicked, and command line turns that into a shutdown
87 #
88 # @subsystem-reset: Partial guest reset that does not trigger QMP events and
89 #                   ignores --no-reboot. This is useful for sanitizing
90 #                   hypercalls on s390 that are used during kexec/kdump/boot
91 #
92 ##
93 { 'enum': 'ShutdownCause',
94   # Beware, shutdown_caused_by_guest() depends on enumeration order
95   'data': [ 'none', 'host-error', 'host-qmp-quit', 'host-qmp-system-reset',
96             'host-signal', 'host-ui', 'guest-shutdown', 'guest-reset',
97             'guest-panic', 'subsystem-reset'] }
98
99 ##
100 # @StatusInfo:
101 #
102 # Information about VCPU run state
103 #
104 # @running: true if all VCPUs are runnable, false if not runnable
105 #
106 # @singlestep: true if VCPUs are in single-step mode
107 #
108 # @status: the virtual machine @RunState
109 #
110 # Since:  0.14.0
111 #
112 # Notes: @singlestep is enabled through the GDB stub
113 ##
114 { 'struct': 'StatusInfo',
115   'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
116
117 ##
118 # @query-status:
119 #
120 # Query the run status of all VCPUs
121 #
122 # Returns: @StatusInfo reflecting all VCPUs
123 #
124 # Since:  0.14.0
125 #
126 # Example:
127 #
128 # -> { "execute": "query-status" }
129 # <- { "return": { "running": true,
130 #                  "singlestep": false,
131 #                  "status": "running" } }
132 #
133 ##
134 { 'command': 'query-status', 'returns': 'StatusInfo',
135   'allow-preconfig': true }
136
137 ##
138 # @SHUTDOWN:
139 #
140 # Emitted when the virtual machine has shut down, indicating that qemu is
141 # about to exit.
142 #
143 # @guest: If true, the shutdown was triggered by a guest request (such as
144 #         a guest-initiated ACPI shutdown request or other hardware-specific action)
145 #         rather than a host request (such as sending qemu a SIGINT). (since 2.10)
146 #
147 # @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
148 #
149 # Note: If the command-line option "-no-shutdown" has been specified, qemu will
150 #       not exit, and a STOP event will eventually follow the SHUTDOWN event
151 #
152 # Since: 0.12.0
153 #
154 # Example:
155 #
156 # <- { "event": "SHUTDOWN", "data": { "guest": true },
157 #      "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
158 #
159 ##
160 { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
161
162 ##
163 # @POWERDOWN:
164 #
165 # Emitted when the virtual machine is powered down through the power control
166 # system, such as via ACPI.
167 #
168 # Since: 0.12.0
169 #
170 # Example:
171 #
172 # <- { "event": "POWERDOWN",
173 #      "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
174 #
175 ##
176 { 'event': 'POWERDOWN' }
177
178 ##
179 # @RESET:
180 #
181 # Emitted when the virtual machine is reset
182 #
183 # @guest: If true, the reset was triggered by a guest request (such as
184 #         a guest-initiated ACPI reboot request or other hardware-specific action)
185 #         rather than a host request (such as the QMP command system_reset).
186 #         (since 2.10)
187 #
188 # @reason: The @ShutdownCause of the RESET. (since 4.0)
189 #
190 # Since: 0.12.0
191 #
192 # Example:
193 #
194 # <- { "event": "RESET", "data": { "guest": false },
195 #      "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
196 #
197 ##
198 { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
199
200 ##
201 # @STOP:
202 #
203 # Emitted when the virtual machine is stopped
204 #
205 # Since: 0.12.0
206 #
207 # Example:
208 #
209 # <- { "event": "STOP",
210 #      "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
211 #
212 ##
213 { 'event': 'STOP' }
214
215 ##
216 # @RESUME:
217 #
218 # Emitted when the virtual machine resumes execution
219 #
220 # Since: 0.12.0
221 #
222 # Example:
223 #
224 # <- { "event": "RESUME",
225 #      "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
226 #
227 ##
228 { 'event': 'RESUME' }
229
230 ##
231 # @SUSPEND:
232 #
233 # Emitted when guest enters a hardware suspension state, for example, S3 state,
234 # which is sometimes called standby state
235 #
236 # Since: 1.1
237 #
238 # Example:
239 #
240 # <- { "event": "SUSPEND",
241 #      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
242 #
243 ##
244 { 'event': 'SUSPEND' }
245
246 ##
247 # @SUSPEND_DISK:
248 #
249 # Emitted when guest enters a hardware suspension state with data saved on
250 # disk, for example, S4 state, which is sometimes called hibernate state
251 #
252 # Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state
253 #
254 # Since: 1.2
255 #
256 # Example:
257 #
258 # <-   { "event": "SUSPEND_DISK",
259 #        "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
260 #
261 ##
262 { 'event': 'SUSPEND_DISK' }
263
264 ##
265 # @WAKEUP:
266 #
267 # Emitted when the guest has woken up from suspend state and is running
268 #
269 # Since: 1.1
270 #
271 # Example:
272 #
273 # <- { "event": "WAKEUP",
274 #      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
275 #
276 ##
277 { 'event': 'WAKEUP' }
278
279 ##
280 # @WATCHDOG:
281 #
282 # Emitted when the watchdog device's timer is expired
283 #
284 # @action: action that has been taken
285 #
286 # Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
287 #       followed respectively by the RESET, SHUTDOWN, or STOP events
288 #
289 # Note: This event is rate-limited.
290 #
291 # Since: 0.13.0
292 #
293 # Example:
294 #
295 # <- { "event": "WATCHDOG",
296 #      "data": { "action": "reset" },
297 #      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
298 #
299 ##
300 { 'event': 'WATCHDOG',
301   'data': { 'action': 'WatchdogAction' } }
302
303 ##
304 # @WatchdogAction:
305 #
306 # An enumeration of the actions taken when the watchdog device's timer is
307 # expired
308 #
309 # @reset: system resets
310 #
311 # @shutdown: system shutdown, note that it is similar to @powerdown, which
312 #            tries to set to system status and notify guest
313 #
314 # @poweroff: system poweroff, the emulator program exits
315 #
316 # @pause: system pauses, similar to @stop
317 #
318 # @debug: system enters debug state
319 #
320 # @none: nothing is done
321 #
322 # @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all
323 #              VCPUS on x86) (since 2.4)
324 #
325 # Since: 2.1
326 ##
327 { 'enum': 'WatchdogAction',
328   'data': [ 'reset', 'shutdown', 'poweroff', 'pause', 'debug', 'none',
329             'inject-nmi' ] }
330
331 ##
332 # @watchdog-set-action:
333 #
334 # Set watchdog action
335 #
336 # Since: 2.11
337 ##
338 { 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }
339
340 ##
341 # @GUEST_PANICKED:
342 #
343 # Emitted when guest OS panic is detected
344 #
345 # @action: action that has been taken, currently always "pause"
346 #
347 # @info: information about a panic (since 2.9)
348 #
349 # Since: 1.5
350 #
351 # Example:
352 #
353 # <- { "event": "GUEST_PANICKED",
354 #      "data": { "action": "pause" } }
355 #
356 ##
357 { 'event': 'GUEST_PANICKED',
358   'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
359
360 ##
361 # @GUEST_CRASHLOADED:
362 #
363 # Emitted when guest OS crash loaded is detected
364 #
365 # @action: action that has been taken, currently always "run"
366 #
367 # @info: information about a panic
368 #
369 # Since: 5.0
370 #
371 # Example:
372 #
373 # <- { "event": "GUEST_CRASHLOADED",
374 #      "data": { "action": "run" } }
375 #
376 ##
377 { 'event': 'GUEST_CRASHLOADED',
378   'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
379
380 ##
381 # @GuestPanicAction:
382 #
383 # An enumeration of the actions taken when guest OS panic is detected
384 #
385 # @pause: system pauses
386 #
387 # Since: 2.1 (poweroff since 2.8, run since 5.0)
388 ##
389 { 'enum': 'GuestPanicAction',
390   'data': [ 'pause', 'poweroff', 'run' ] }
391
392 ##
393 # @GuestPanicInformationType:
394 #
395 # An enumeration of the guest panic information types
396 #
397 # @hyper-v: hyper-v guest panic information type
398 #
399 # @s390: s390 guest panic information type (Since: 2.12)
400 #
401 # Since: 2.9
402 ##
403 { 'enum': 'GuestPanicInformationType',
404   'data': [ 'hyper-v', 's390' ] }
405
406 ##
407 # @GuestPanicInformation:
408 #
409 # Information about a guest panic
410 #
411 # @type: Crash type that defines the hypervisor specific information
412 #
413 # Since: 2.9
414 ##
415 {'union': 'GuestPanicInformation',
416  'base': {'type': 'GuestPanicInformationType'},
417  'discriminator': 'type',
418  'data': { 'hyper-v': 'GuestPanicInformationHyperV',
419            's390': 'GuestPanicInformationS390' } }
420
421 ##
422 # @GuestPanicInformationHyperV:
423 #
424 # Hyper-V specific guest panic information (HV crash MSRs)
425 #
426 # Since: 2.9
427 ##
428 {'struct': 'GuestPanicInformationHyperV',
429  'data': { 'arg1': 'uint64',
430            'arg2': 'uint64',
431            'arg3': 'uint64',
432            'arg4': 'uint64',
433            'arg5': 'uint64' } }
434
435 ##
436 # @S390CrashReason:
437 #
438 # Reason why the CPU is in a crashed state.
439 #
440 # @unknown: no crash reason was set
441 #
442 # @disabled-wait: the CPU has entered a disabled wait state
443 #
444 # @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled
445 #               for external interrupts
446 #
447 # @pgmint-loop: program interrupt with BAD new PSW
448 #
449 # @opint-loop: operation exception interrupt with invalid code at the program
450 #              interrupt new PSW
451 #
452 # Since: 2.12
453 ##
454 { 'enum': 'S390CrashReason',
455   'data': [ 'unknown',
456             'disabled-wait',
457             'extint-loop',
458             'pgmint-loop',
459             'opint-loop' ] }
460
461 ##
462 # @GuestPanicInformationS390:
463 #
464 # S390 specific guest panic information (PSW)
465 #
466 # @core: core id of the CPU that crashed
467 # @psw-mask: control fields of guest PSW
468 # @psw-addr: guest instruction address
469 # @reason: guest crash reason
470 #
471 # Since: 2.12
472 ##
473 {'struct': 'GuestPanicInformationS390',
474  'data': { 'core': 'uint32',
475            'psw-mask': 'uint64',
476            'psw-addr': 'uint64',
477            'reason': 'S390CrashReason' } }