12 # An enumeration of VM run states.
14 # @debug: QEMU is running on a debugger
16 # @finish-migrate: guest is paused to finish the migration process
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
24 # @internal-error: An internal error that prevents further guest execution
27 # @io-error: the last IOP has failed and the device is configured to pause
30 # @paused: guest has been paused via the 'stop' command
32 # @postmigrate: guest is paused following a successful 'migrate'
34 # @prelaunch: QEMU was started with -S and guest has not started
36 # @restore-vm: guest is paused to restore VM state
38 # @running: guest is actively running
40 # @save-vm: guest is paused to save the VM state
42 # @shutdown: guest is shut down (and -no-shutdown is in use)
44 # @suspended: guest is suspended (ACPI S3)
46 # @watchdog: the watchdog action is configured to pause and has been triggered
48 # @guest-panicked: guest has been panicked as a result of guest OS panic
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)
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' ] }
63 # An enumeration of reasons for a Shutdown.
65 # @none: No shutdown request pending
67 # @host-error: An error prevents further use of guest
69 # @host-qmp-quit: Reaction to the QMP command 'quit'
71 # @host-qmp-system-reset: Reaction to the QMP command 'system_reset'
73 # @host-signal: Reaction to a signal, such as SIGINT
75 # @host-ui: Reaction to a UI event, like window close
77 # @guest-shutdown: Guest shutdown/suspend request, via ACPI or other
78 # hardware-specific means
80 # @guest-reset: Guest reset request, and command line turns that into
83 # @guest-panic: Guest panicked, and command line turns that into a shutdown
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
89 # @snapshot-load: A snapshot is being loaded by the record & replay
90 # subsystem. This value is used only within QEMU. It
91 # doesn't occur in QMP. (since 7.2)
94 { 'enum': 'ShutdownCause',
95 # Beware, shutdown_caused_by_guest() depends on enumeration order
96 'data': [ 'none', 'host-error', 'host-qmp-quit', 'host-qmp-system-reset',
97 'host-signal', 'host-ui', 'guest-shutdown', 'guest-reset',
98 'guest-panic', 'subsystem-reset', 'snapshot-load'] }
103 # Information about VCPU run state
105 # @running: true if all VCPUs are runnable, false if not runnable
107 # @singlestep: true if using TCG with one guest instruction
108 # per translation block
110 # @status: the virtual machine @RunState
113 # @deprecated: Member 'singlestep' is deprecated (with no replacement).
117 # Notes: @singlestep is enabled on the command line with
118 # '-accel tcg,one-insn-per-tb=on', or with the HMP
119 # 'one-insn-per-tb' command.
121 { 'struct': 'StatusInfo',
122 'data': {'running': 'bool',
123 'singlestep': { 'type': 'bool', 'features': [ 'deprecated' ]},
124 'status': 'RunState'} }
129 # Query the run status of all VCPUs
131 # Returns: @StatusInfo reflecting all VCPUs
137 # -> { "execute": "query-status" }
138 # <- { "return": { "running": true,
139 # "singlestep": false,
140 # "status": "running" } }
143 { 'command': 'query-status', 'returns': 'StatusInfo',
144 'allow-preconfig': true }
149 # Emitted when the virtual machine has shut down, indicating that qemu is
152 # @guest: If true, the shutdown was triggered by a guest request (such as
153 # a guest-initiated ACPI shutdown request or other hardware-specific action)
154 # rather than a host request (such as sending qemu a SIGINT). (since 2.10)
156 # @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
158 # Note: If the command-line option "-no-shutdown" has been specified, qemu will
159 # not exit, and a STOP event will eventually follow the SHUTDOWN event
165 # <- { "event": "SHUTDOWN",
166 # "data": { "guest": true, "reason": "guest-shutdown" },
167 # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
170 { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
175 # Emitted when the virtual machine is powered down through the power control
176 # system, such as via ACPI.
182 # <- { "event": "POWERDOWN",
183 # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
186 { 'event': 'POWERDOWN' }
191 # Emitted when the virtual machine is reset
193 # @guest: If true, the reset was triggered by a guest request (such as
194 # a guest-initiated ACPI reboot request or other hardware-specific action)
195 # rather than a host request (such as the QMP command system_reset).
198 # @reason: The @ShutdownCause of the RESET. (since 4.0)
204 # <- { "event": "RESET",
205 # "data": { "guest": false, "reason": "guest-reset" },
206 # "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
209 { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }
214 # Emitted when the virtual machine is stopped
220 # <- { "event": "STOP",
221 # "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
229 # Emitted when the virtual machine resumes execution
235 # <- { "event": "RESUME",
236 # "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
239 { 'event': 'RESUME' }
244 # Emitted when guest enters a hardware suspension state, for example, S3 state,
245 # which is sometimes called standby state
251 # <- { "event": "SUSPEND",
252 # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
255 { 'event': 'SUSPEND' }
260 # Emitted when guest enters a hardware suspension state with data saved on
261 # disk, for example, S4 state, which is sometimes called hibernate state
263 # Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state
269 # <- { "event": "SUSPEND_DISK",
270 # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
272 { 'event': 'SUSPEND_DISK' }
277 # Emitted when the guest has woken up from suspend state and is running
283 # <- { "event": "WAKEUP",
284 # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
287 { 'event': 'WAKEUP' }
292 # Emitted when the watchdog device's timer is expired
294 # @action: action that has been taken
296 # Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
297 # followed respectively by the RESET, SHUTDOWN, or STOP events
299 # Note: This event is rate-limited.
305 # <- { "event": "WATCHDOG",
306 # "data": { "action": "reset" },
307 # "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
310 { 'event': 'WATCHDOG',
311 'data': { 'action': 'WatchdogAction' } }
316 # An enumeration of the actions taken when the watchdog device's timer is
319 # @reset: system resets
321 # @shutdown: system shutdown, note that it is similar to @powerdown, which
322 # tries to set to system status and notify guest
324 # @poweroff: system poweroff, the emulator program exits
326 # @pause: system pauses, similar to @stop
328 # @debug: system enters debug state
330 # @none: nothing is done
332 # @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all
333 # VCPUS on x86) (since 2.4)
337 { 'enum': 'WatchdogAction',
338 'data': [ 'reset', 'shutdown', 'poweroff', 'pause', 'debug', 'none',
344 # Possible QEMU actions upon guest reboot
346 # @reset: Reset the VM
348 # @shutdown: Shutdown the VM and exit, according to the shutdown action
352 { 'enum': 'RebootAction',
353 'data': [ 'reset', 'shutdown' ] }
358 # Possible QEMU actions upon guest shutdown
360 # @poweroff: Shutdown the VM and exit
362 # @pause: pause the VM
366 { 'enum': 'ShutdownAction',
367 'data': [ 'poweroff', 'pause' ] }
372 # @none: Continue VM execution
374 # @pause: Pause the VM
376 # @shutdown: Shutdown the VM and exit, according to the shutdown action
378 # @exit-failure: Shutdown the VM and exit with nonzero status
383 { 'enum': 'PanicAction',
384 'data': [ 'pause', 'shutdown', 'exit-failure', 'none' ] }
387 # @watchdog-set-action:
389 # Set watchdog action
393 { 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }
398 # Set the actions that will be taken by the emulator in response to guest
401 # @reboot: @RebootAction action taken on guest reboot.
403 # @shutdown: @ShutdownAction action taken on guest shutdown.
405 # @panic: @PanicAction action taken on guest panic.
407 # @watchdog: @WatchdogAction action taken when watchdog timer expires .
409 # Returns: Nothing on success.
415 # -> { "execute": "set-action",
416 # "arguments": { "reboot": "shutdown",
417 # "shutdown" : "pause",
419 # "watchdog": "inject-nmi" } }
420 # <- { "return": {} }
422 { 'command': 'set-action',
423 'data': { '*reboot': 'RebootAction',
424 '*shutdown': 'ShutdownAction',
425 '*panic': 'PanicAction',
426 '*watchdog': 'WatchdogAction' },
427 'allow-preconfig': true }
432 # Emitted when guest OS panic is detected
434 # @action: action that has been taken, currently always "pause"
436 # @info: information about a panic (since 2.9)
442 # <- { "event": "GUEST_PANICKED",
443 # "data": { "action": "pause" },
444 # "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
447 { 'event': 'GUEST_PANICKED',
448 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
451 # @GUEST_CRASHLOADED:
453 # Emitted when guest OS crash loaded is detected
455 # @action: action that has been taken, currently always "run"
457 # @info: information about a panic
463 # <- { "event": "GUEST_CRASHLOADED",
464 # "data": { "action": "run" },
465 # "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
468 { 'event': 'GUEST_CRASHLOADED',
469 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }
474 # An enumeration of the actions taken when guest OS panic is detected
476 # @pause: system pauses
478 # @poweroff: system powers off (since 2.8)
480 # @run: system continues to run (since 5.0)
484 { 'enum': 'GuestPanicAction',
485 'data': [ 'pause', 'poweroff', 'run' ] }
488 # @GuestPanicInformationType:
490 # An enumeration of the guest panic information types
492 # @hyper-v: hyper-v guest panic information type
494 # @s390: s390 guest panic information type (Since: 2.12)
498 { 'enum': 'GuestPanicInformationType',
499 'data': [ 'hyper-v', 's390' ] }
502 # @GuestPanicInformation:
504 # Information about a guest panic
506 # @type: Crash type that defines the hypervisor specific information
510 {'union': 'GuestPanicInformation',
511 'base': {'type': 'GuestPanicInformationType'},
512 'discriminator': 'type',
513 'data': { 'hyper-v': 'GuestPanicInformationHyperV',
514 's390': 'GuestPanicInformationS390' } }
517 # @GuestPanicInformationHyperV:
519 # Hyper-V specific guest panic information (HV crash MSRs)
523 {'struct': 'GuestPanicInformationHyperV',
524 'data': { 'arg1': 'uint64',
533 # Reason why the CPU is in a crashed state.
535 # @unknown: no crash reason was set
537 # @disabled-wait: the CPU has entered a disabled wait state
539 # @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled
540 # for external interrupts
542 # @pgmint-loop: program interrupt with BAD new PSW
544 # @opint-loop: operation exception interrupt with invalid code at the program
549 { 'enum': 'S390CrashReason',
557 # @GuestPanicInformationS390:
559 # S390 specific guest panic information (PSW)
561 # @core: core id of the CPU that crashed
562 # @psw-mask: control fields of guest PSW
563 # @psw-addr: guest instruction address
564 # @reason: guest crash reason
568 {'struct': 'GuestPanicInformationS390',
569 'data': { 'core': 'uint32',
570 'psw-mask': 'uint64',
571 'psw-addr': 'uint64',
572 'reason': 'S390CrashReason' } }
577 # Emitted when a memory failure occurs on host side.
579 # @recipient: recipient is defined as @MemoryFailureRecipient.
581 # @action: action that has been taken. action is defined as @MemoryFailureAction.
583 # @flags: flags for MemoryFailureAction. action is defined as @MemoryFailureFlags.
589 # <- { "event": "MEMORY_FAILURE",
590 # "data": { "recipient": "hypervisor",
592 # "flags": { "action-required": false,
593 # "recursive": false } },
594 # "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
597 { 'event': 'MEMORY_FAILURE',
598 'data': { 'recipient': 'MemoryFailureRecipient',
599 'action': 'MemoryFailureAction',
600 'flags': 'MemoryFailureFlags'} }
603 # @MemoryFailureRecipient:
605 # Hardware memory failure occurs, handled by recipient.
607 # @hypervisor: memory failure at QEMU process address space.
608 # (none guest memory, but used by QEMU itself).
610 # @guest: memory failure at guest memory,
614 { 'enum': 'MemoryFailureRecipient',
615 'data': [ 'hypervisor',
619 # @MemoryFailureAction:
621 # Actions taken by QEMU in response to a hardware memory failure.
623 # @ignore: the memory failure could be ignored. This will only be the case
624 # for action-optional failures.
626 # @inject: memory failure occurred in guest memory, the guest enabled MCE
627 # handling mechanism, and QEMU could inject the MCE into the guest
630 # @fatal: the failure is unrecoverable. This occurs for action-required
631 # failures if the recipient is the hypervisor; QEMU will exit.
633 # @reset: the failure is unrecoverable but confined to the guest. This
634 # occurs if the recipient is a guest guest which is not ready
635 # to handle memory failures.
639 { 'enum': 'MemoryFailureAction',
646 # @MemoryFailureFlags:
648 # Additional information on memory failures.
650 # @action-required: whether a memory failure event is action-required
651 # or action-optional (e.g. a failure during memory scrub).
653 # @recursive: whether the failure occurred while the previous
654 # failure was still in progress.
658 { 'struct': 'MemoryFailureFlags',
659 'data': { 'action-required': 'bool',
660 'recursive': 'bool'} }
663 # @NotifyVmexitOption:
665 # An enumeration of the options specified when enabling notify VM exit
667 # @run: enable the feature, do nothing and continue if the notify VM exit happens.
669 # @internal-error: enable the feature, raise a internal error if the notify
672 # @disable: disable the feature.
676 { 'enum': 'NotifyVmexitOption',
677 'data': [ 'run', 'internal-error', 'disable' ] }