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