Update VERSION for v7.2.0-rc3
[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 ##
54 { 'enum': 'RunState',
55   'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
56             'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
57             'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',
58             'guest-panicked', 'colo' ] }
59
60 ##
61 # @ShutdownCause:
62 #
63 # An enumeration of reasons for a Shutdown.
64 #
65 # @none: No shutdown request pending
66 #
67 # @host-error: An error prevents further use of guest
68 #
69 # @host-qmp-quit: Reaction to the QMP command 'quit'
70 #
71 # @host-qmp-system-reset: Reaction to the QMP command 'system_reset'
72 #
73 # @host-signal: Reaction to a signal, such as SIGINT
74 #
75 # @host-ui: Reaction to a UI event, like window close
76 #
77 # @guest-shutdown: Guest shutdown/suspend request, via ACPI or other
78 #                  hardware-specific means
79 #
80 # @guest-reset: Guest reset request, and command line turns that into
81 #               a shutdown
82 #
83 # @guest-panic: Guest panicked, and command line turns that into a shutdown
84 #
85 # @subsystem-reset: Partial guest reset that does not trigger QMP events and
86 #                   ignores --no-reboot. This is useful for sanitizing
87 #                   hypercalls on s390 that are used during kexec/kdump/boot
88 #
89 ##
90 { 'enum': 'ShutdownCause',
91   # Beware, shutdown_caused_by_guest() depends on enumeration order
92   'data': [ 'none', 'host-error', 'host-qmp-quit', 'host-qmp-system-reset',
93             'host-signal', 'host-ui', 'guest-shutdown', 'guest-reset',
94             'guest-panic', 'subsystem-reset'] }
95
96 ##
97 # @StatusInfo:
98 #
99 # Information about VCPU run state
100 #
101 # @running: true if all VCPUs are runnable, false if not runnable
102 #
103 # @singlestep: true if VCPUs are in single-step mode
104 #
105 # @status: the virtual machine @RunState
106 #
107 # Since: 0.14
108 #
109 # Notes: @singlestep is enabled through the GDB stub
110 ##
111 { 'struct': 'StatusInfo',
112   'data': {'running': 'bool', 'singlestep': 'bool', 'status': 'RunState'} }
113
114 ##
115 # @query-status:
116 #
117 # Query the run status of all VCPUs
118 #
119 # Returns: @StatusInfo reflecting all VCPUs
120 #
121 # Since: 0.14
122 #
123 # Example:
124 #
125 # -> { "execute": "query-status" }
126 # <- { "return": { "running": true,
127 #                  "singlestep": false,
128 #                  "status": "running" } }
129 #
130 ##
131 { 'command': 'query-status', 'returns': 'StatusInfo',
132   'allow-preconfig': true }
133
134 ##
135 # @SHUTDOWN:
136 #
137 # Emitted when the virtual machine has shut down, indicating that qemu is
138 # about to exit.
139 #
140 # @guest: If true, the shutdown was triggered by a guest request (such as
141 #         a guest-initiated ACPI shutdown request or other hardware-specific action)
142 #         rather than a host request (such as sending qemu a SIGINT). (since 2.10)
143 #
144 # @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
145 #
146 # Note: If the command-line option "-no-shutdown" has been specified, qemu will
147 #       not exit, and a STOP event will eventually follow the SHUTDOWN event
148 #
149 # Since: 0.12
150 #
151 # Example:
152 #
153 # <- { "event": "SHUTDOWN",
154 #      "data": { "guest": true, "reason": "guest-shutdown" },
155 #      "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
156 #
157 ##
158 { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
159
160 ##
161 # @POWERDOWN:
162 #
163 # Emitted when the virtual machine is powered down through the power control
164 # system, such as via ACPI.
165 #
166 # Since: 0.12
167 #
168 # Example:
169 #
170 # <- { "event": "POWERDOWN",
171 #      "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
172 #
173 ##
174 { 'event': 'POWERDOWN' }
175
176 ##
177 # @RESET:
178 #
179 # Emitted when the virtual machine is reset
180 #
181 # @guest: If true, the reset was triggered by a guest request (such as
182 #         a guest-initiated ACPI reboot request or other hardware-specific action)
183 #         rather than a host request (such as the QMP command system_reset).
184 #         (since 2.10)
185 #
186 # @reason: The @ShutdownCause of the RESET. (since 4.0)
187 #
188 # Since: 0.12
189 #
190 # Example:
191 #
192 # <- { "event": "RESET",
193 #      "data": { "guest": false, "reason": "guest-reset" },
194 #      "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
195 #
196 ##
197 { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
198
199 ##
200 # @STOP:
201 #
202 # Emitted when the virtual machine is stopped
203 #
204 # Since: 0.12
205 #
206 # Example:
207 #
208 # <- { "event": "STOP",
209 #      "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
210 #
211 ##
212 { 'event': 'STOP' }
213
214 ##
215 # @RESUME:
216 #
217 # Emitted when the virtual machine resumes execution
218 #
219 # Since: 0.12
220 #
221 # Example:
222 #
223 # <- { "event": "RESUME",
224 #      "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
225 #
226 ##
227 { 'event': 'RESUME' }
228
229 ##
230 # @SUSPEND:
231 #
232 # Emitted when guest enters a hardware suspension state, for example, S3 state,
233 # which is sometimes called standby state
234 #
235 # Since: 1.1
236 #
237 # Example:
238 #
239 # <- { "event": "SUSPEND",
240 #      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
241 #
242 ##
243 { 'event': 'SUSPEND' }
244
245 ##
246 # @SUSPEND_DISK:
247 #
248 # Emitted when guest enters a hardware suspension state with data saved on
249 # disk, for example, S4 state, which is sometimes called hibernate state
250 #
251 # Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state
252 #
253 # Since: 1.2
254 #
255 # Example:
256 #
257 # <-   { "event": "SUSPEND_DISK",
258 #        "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
259 #
260 ##
261 { 'event': 'SUSPEND_DISK' }
262
263 ##
264 # @WAKEUP:
265 #
266 # Emitted when the guest has woken up from suspend state and is running
267 #
268 # Since: 1.1
269 #
270 # Example:
271 #
272 # <- { "event": "WAKEUP",
273 #      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
274 #
275 ##
276 { 'event': 'WAKEUP' }
277
278 ##
279 # @WATCHDOG:
280 #
281 # Emitted when the watchdog device's timer is expired
282 #
283 # @action: action that has been taken
284 #
285 # Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
286 #       followed respectively by the RESET, SHUTDOWN, or STOP events
287 #
288 # Note: This event is rate-limited.
289 #
290 # Since: 0.13
291 #
292 # Example:
293 #
294 # <- { "event": "WATCHDOG",
295 #      "data": { "action": "reset" },
296 #      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
297 #
298 ##
299 { 'event': 'WATCHDOG',
300   'data': { 'action': 'WatchdogAction' } }
301
302 ##
303 # @WatchdogAction:
304 #
305 # An enumeration of the actions taken when the watchdog device's timer is
306 # expired
307 #
308 # @reset: system resets
309 #
310 # @shutdown: system shutdown, note that it is similar to @powerdown, which
311 #            tries to set to system status and notify guest
312 #
313 # @poweroff: system poweroff, the emulator program exits
314 #
315 # @pause: system pauses, similar to @stop
316 #
317 # @debug: system enters debug state
318 #
319 # @none: nothing is done
320 #
321 # @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all
322 #              VCPUS on x86) (since 2.4)
323 #
324 # Since: 2.1
325 ##
326 { 'enum': 'WatchdogAction',
327   'data': [ 'reset', 'shutdown', 'poweroff', 'pause', 'debug', 'none',
328             'inject-nmi' ] }
329
330 ##
331 # @RebootAction:
332 #
333 # Possible QEMU actions upon guest reboot
334 #
335 # @reset: Reset the VM
336 #
337 # @shutdown: Shutdown the VM and exit, according to the shutdown action
338 #
339 # Since: 6.0
340 ##
341 { 'enum': 'RebootAction',
342   'data': [ 'reset', 'shutdown' ] }
343
344 ##
345 # @ShutdownAction:
346 #
347 # Possible QEMU actions upon guest shutdown
348 #
349 # @poweroff: Shutdown the VM and exit
350 #
351 # @pause: pause the VM
352 #
353 # Since: 6.0
354 ##
355 { 'enum': 'ShutdownAction',
356   'data': [ 'poweroff', 'pause' ] }
357
358 ##
359 # @PanicAction:
360 #
361 # @none: Continue VM execution
362 #
363 # @pause: Pause the VM
364 #
365 # @shutdown: Shutdown the VM and exit, according to the shutdown action
366 #
367 # Since: 6.0
368 ##
369 { 'enum': 'PanicAction',
370   'data': [ 'pause', 'shutdown', 'none' ] }
371
372 ##
373 # @watchdog-set-action:
374 #
375 # Set watchdog action
376 #
377 # Since: 2.11
378 ##
379 { 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }
380
381 ##
382 # @set-action:
383 #
384 # Set the actions that will be taken by the emulator in response to guest
385 # events.
386 #
387 # @reboot: @RebootAction action taken on guest reboot.
388 #
389 # @shutdown: @ShutdownAction action taken on guest shutdown.
390 #
391 # @panic: @PanicAction action taken on guest panic.
392 #
393 # @watchdog: @WatchdogAction action taken when watchdog timer expires .
394 #
395 # Returns: Nothing on success.
396 #
397 # Since: 6.0
398 #
399 # Example:
400 #
401 # -> { "execute": "set-action",
402 #      "arguments": { "reboot": "shutdown",
403 #                     "shutdown" : "pause",
404 #                     "panic": "pause",
405 #                     "watchdog": "inject-nmi" } }
406 # <- { "return": {} }
407 ##
408 { 'command': 'set-action',
409   'data': { '*reboot': 'RebootAction',
410             '*shutdown': 'ShutdownAction',
411             '*panic': 'PanicAction',
412             '*watchdog': 'WatchdogAction' },
413   'allow-preconfig': true }
414
415 ##
416 # @GUEST_PANICKED:
417 #
418 # Emitted when guest OS panic is detected
419 #
420 # @action: action that has been taken, currently always "pause"
421 #
422 # @info: information about a panic (since 2.9)
423 #
424 # Since: 1.5
425 #
426 # Example:
427 #
428 # <- { "event": "GUEST_PANICKED",
429 #      "data": { "action": "pause" },
430 #      "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
431 #
432 ##
433 { 'event': 'GUEST_PANICKED',
434   'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
435
436 ##
437 # @GUEST_CRASHLOADED:
438 #
439 # Emitted when guest OS crash loaded is detected
440 #
441 # @action: action that has been taken, currently always "run"
442 #
443 # @info: information about a panic
444 #
445 # Since: 5.0
446 #
447 # Example:
448 #
449 # <- { "event": "GUEST_CRASHLOADED",
450 #      "data": { "action": "run" },
451 #      "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
452 #
453 ##
454 { 'event': 'GUEST_CRASHLOADED',
455   'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
456
457 ##
458 # @GuestPanicAction:
459 #
460 # An enumeration of the actions taken when guest OS panic is detected
461 #
462 # @pause: system pauses
463 #
464 # Since: 2.1 (poweroff since 2.8, run since 5.0)
465 ##
466 { 'enum': 'GuestPanicAction',
467   'data': [ 'pause', 'poweroff', 'run' ] }
468
469 ##
470 # @GuestPanicInformationType:
471 #
472 # An enumeration of the guest panic information types
473 #
474 # @hyper-v: hyper-v guest panic information type
475 #
476 # @s390: s390 guest panic information type (Since: 2.12)
477 #
478 # Since: 2.9
479 ##
480 { 'enum': 'GuestPanicInformationType',
481   'data': [ 'hyper-v', 's390' ] }
482
483 ##
484 # @GuestPanicInformation:
485 #
486 # Information about a guest panic
487 #
488 # @type: Crash type that defines the hypervisor specific information
489 #
490 # Since: 2.9
491 ##
492 {'union': 'GuestPanicInformation',
493  'base': {'type': 'GuestPanicInformationType'},
494  'discriminator': 'type',
495  'data': { 'hyper-v': 'GuestPanicInformationHyperV',
496            's390': 'GuestPanicInformationS390' } }
497
498 ##
499 # @GuestPanicInformationHyperV:
500 #
501 # Hyper-V specific guest panic information (HV crash MSRs)
502 #
503 # Since: 2.9
504 ##
505 {'struct': 'GuestPanicInformationHyperV',
506  'data': { 'arg1': 'uint64',
507            'arg2': 'uint64',
508            'arg3': 'uint64',
509            'arg4': 'uint64',
510            'arg5': 'uint64' } }
511
512 ##
513 # @S390CrashReason:
514 #
515 # Reason why the CPU is in a crashed state.
516 #
517 # @unknown: no crash reason was set
518 #
519 # @disabled-wait: the CPU has entered a disabled wait state
520 #
521 # @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled
522 #               for external interrupts
523 #
524 # @pgmint-loop: program interrupt with BAD new PSW
525 #
526 # @opint-loop: operation exception interrupt with invalid code at the program
527 #              interrupt new PSW
528 #
529 # Since: 2.12
530 ##
531 { 'enum': 'S390CrashReason',
532   'data': [ 'unknown',
533             'disabled-wait',
534             'extint-loop',
535             'pgmint-loop',
536             'opint-loop' ] }
537
538 ##
539 # @GuestPanicInformationS390:
540 #
541 # S390 specific guest panic information (PSW)
542 #
543 # @core: core id of the CPU that crashed
544 # @psw-mask: control fields of guest PSW
545 # @psw-addr: guest instruction address
546 # @reason: guest crash reason
547 #
548 # Since: 2.12
549 ##
550 {'struct': 'GuestPanicInformationS390',
551  'data': { 'core': 'uint32',
552            'psw-mask': 'uint64',
553            'psw-addr': 'uint64',
554            'reason': 'S390CrashReason' } }
555
556 ##
557 # @MEMORY_FAILURE:
558 #
559 # Emitted when a memory failure occurs on host side.
560 #
561 # @recipient: recipient is defined as @MemoryFailureRecipient.
562 #
563 # @action: action that has been taken. action is defined as @MemoryFailureAction.
564 #
565 # @flags: flags for MemoryFailureAction. action is defined as @MemoryFailureFlags.
566 #
567 # Since: 5.2
568 #
569 # Example:
570 #
571 # <- { "event": "MEMORY_FAILURE",
572 #      "data": { "recipient": "hypervisor",
573 #                "action": "fatal",
574 #                "flags": { "action-required": false,
575 #                           "recursive": false } },
576 #      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
577 #
578 ##
579 { 'event': 'MEMORY_FAILURE',
580   'data': { 'recipient': 'MemoryFailureRecipient',
581             'action': 'MemoryFailureAction',
582             'flags': 'MemoryFailureFlags'} }
583
584 ##
585 # @MemoryFailureRecipient:
586 #
587 # Hardware memory failure occurs, handled by recipient.
588 #
589 # @hypervisor: memory failure at QEMU process address space.
590 #              (none guest memory, but used by QEMU itself).
591 #
592 # @guest: memory failure at guest memory,
593 #
594 # Since: 5.2
595 ##
596 { 'enum': 'MemoryFailureRecipient',
597   'data': [ 'hypervisor',
598             'guest' ] }
599
600 ##
601 # @MemoryFailureAction:
602 #
603 # Actions taken by QEMU in response to a hardware memory failure.
604 #
605 # @ignore: the memory failure could be ignored.  This will only be the case
606 #          for action-optional failures.
607 #
608 # @inject: memory failure occurred in guest memory, the guest enabled MCE
609 #          handling mechanism, and QEMU could inject the MCE into the guest
610 #          successfully.
611 #
612 # @fatal: the failure is unrecoverable.  This occurs for action-required
613 #         failures if the recipient is the hypervisor; QEMU will exit.
614 #
615 # @reset: the failure is unrecoverable but confined to the guest.  This
616 #         occurs if the recipient is a guest guest which is not ready
617 #         to handle memory failures.
618 #
619 # Since: 5.2
620 ##
621 { 'enum': 'MemoryFailureAction',
622   'data': [ 'ignore',
623             'inject',
624             'fatal',
625             'reset' ] }
626
627 ##
628 # @MemoryFailureFlags:
629 #
630 # Additional information on memory failures.
631 #
632 # @action-required: whether a memory failure event is action-required
633 #                   or action-optional (e.g. a failure during memory scrub).
634 #
635 # @recursive: whether the failure occurred while the previous
636 #             failure was still in progress.
637 #
638 # Since: 5.2
639 ##
640 { 'struct': 'MemoryFailureFlags',
641   'data': { 'action-required': 'bool',
642             'recursive': 'bool'} }