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