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# 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 specified, 150# qemu will not exit, and a STOP event will eventually follow the 151# SHUTDOWN event 152# 153# Since: 0.12 154# 155# 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# 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# 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# 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# 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# 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# 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# 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# 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# Since: 2.11 382## 383{ 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} } 384 385## 386# @set-action: 387# 388# Set the actions that will be taken by the emulator in response to 389# guest events. 390# 391# @reboot: @RebootAction action taken on guest reboot. 392# 393# @shutdown: @ShutdownAction action taken on guest shutdown. 394# 395# @panic: @PanicAction action taken on guest panic. 396# 397# @watchdog: @WatchdogAction action taken when watchdog timer expires. 398# 399# Since: 6.0 400# 401# Example: 402# 403# -> { "execute": "set-action", 404# "arguments": { "reboot": "shutdown", 405# "shutdown" : "pause", 406# "panic": "pause", 407# "watchdog": "inject-nmi" } } 408# <- { "return": {} } 409## 410{ 'command': 'set-action', 411 'data': { '*reboot': 'RebootAction', 412 '*shutdown': 'ShutdownAction', 413 '*panic': 'PanicAction', 414 '*watchdog': 'WatchdogAction' }, 415 'allow-preconfig': true } 416 417## 418# @GUEST_PANICKED: 419# 420# Emitted when guest OS panic is detected 421# 422# @action: action that has been taken, currently always "pause" 423# 424# @info: information about a panic (since 2.9) 425# 426# Since: 1.5 427# 428# Example: 429# 430# <- { "event": "GUEST_PANICKED", 431# "data": { "action": "pause" }, 432# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } } 433## 434{ 'event': 'GUEST_PANICKED', 435 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } 436 437## 438# @GUEST_CRASHLOADED: 439# 440# Emitted when guest OS crash loaded is detected 441# 442# @action: action that has been taken, currently always "run" 443# 444# @info: information about a panic 445# 446# Since: 5.0 447# 448# Example: 449# 450# <- { "event": "GUEST_CRASHLOADED", 451# "data": { "action": "run" }, 452# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } 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# @poweroff: system powers off (since 2.8) 465# 466# @run: system continues to run (since 5.0) 467# 468# Since: 2.1 469## 470{ 'enum': 'GuestPanicAction', 471 'data': [ 'pause', 'poweroff', 'run' ] } 472 473## 474# @GuestPanicInformationType: 475# 476# An enumeration of the guest panic information types 477# 478# @hyper-v: hyper-v guest panic information type 479# 480# @s390: s390 guest panic information type (Since: 2.12) 481# 482# Since: 2.9 483## 484{ 'enum': 'GuestPanicInformationType', 485 'data': [ 'hyper-v', 's390' ] } 486 487## 488# @GuestPanicInformation: 489# 490# Information about a guest panic 491# 492# @type: Crash type that defines the hypervisor specific information 493# 494# Since: 2.9 495## 496{'union': 'GuestPanicInformation', 497 'base': {'type': 'GuestPanicInformationType'}, 498 'discriminator': 'type', 499 'data': {'hyper-v': 'GuestPanicInformationHyperV', 500 's390': 'GuestPanicInformationS390'}} 501 502## 503# @GuestPanicInformationHyperV: 504# 505# Hyper-V specific guest panic information (HV crash MSRs) 506# 507# Since: 2.9 508## 509{'struct': 'GuestPanicInformationHyperV', 510 'data': {'arg1': 'uint64', 511 'arg2': 'uint64', 512 'arg3': 'uint64', 513 'arg4': 'uint64', 514 'arg5': 'uint64'}} 515 516## 517# @S390CrashReason: 518# 519# Reason why the CPU is in a crashed state. 520# 521# @unknown: no crash reason was set 522# 523# @disabled-wait: the CPU has entered a disabled wait state 524# 525# @extint-loop: clock comparator or cpu timer interrupt with new PSW 526# enabled for external interrupts 527# 528# @pgmint-loop: program interrupt with BAD new PSW 529# 530# @opint-loop: operation exception interrupt with invalid code at the 531# program interrupt new PSW 532# 533# Since: 2.12 534## 535{ 'enum': 'S390CrashReason', 536 'data': [ 'unknown', 537 'disabled-wait', 538 'extint-loop', 539 'pgmint-loop', 540 'opint-loop' ] } 541 542## 543# @GuestPanicInformationS390: 544# 545# S390 specific guest panic information (PSW) 546# 547# @core: core id of the CPU that crashed 548# 549# @psw-mask: control fields of guest PSW 550# 551# @psw-addr: guest instruction address 552# 553# @reason: guest crash reason 554# 555# Since: 2.12 556## 557{'struct': 'GuestPanicInformationS390', 558 'data': {'core': 'uint32', 559 'psw-mask': 'uint64', 560 'psw-addr': 'uint64', 561 'reason': 'S390CrashReason'}} 562 563## 564# @MEMORY_FAILURE: 565# 566# Emitted when a memory failure occurs on host side. 567# 568# @recipient: recipient is defined as @MemoryFailureRecipient. 569# 570# @action: action that has been taken. 571# 572# @flags: flags for MemoryFailureAction. 573# 574# Since: 5.2 575# 576# Example: 577# 578# <- { "event": "MEMORY_FAILURE", 579# "data": { "recipient": "hypervisor", 580# "action": "fatal", 581# "flags": { "action-required": false, 582# "recursive": false } }, 583# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } 584## 585{ 'event': 'MEMORY_FAILURE', 586 'data': { 'recipient': 'MemoryFailureRecipient', 587 'action': 'MemoryFailureAction', 588 'flags': 'MemoryFailureFlags'} } 589 590## 591# @MemoryFailureRecipient: 592# 593# Hardware memory failure occurs, handled by recipient. 594# 595# @hypervisor: memory failure at QEMU process address space. (none 596# guest memory, but used by QEMU itself). 597# 598# @guest: memory failure at guest memory, 599# 600# Since: 5.2 601## 602{ 'enum': 'MemoryFailureRecipient', 603 'data': [ 'hypervisor', 604 'guest' ] } 605 606## 607# @MemoryFailureAction: 608# 609# Actions taken by QEMU in response to a hardware memory failure. 610# 611# @ignore: the memory failure could be ignored. This will only be the 612# case for action-optional failures. 613# 614# @inject: memory failure occurred in guest memory, the guest enabled 615# MCE handling mechanism, and QEMU could inject the MCE into the 616# guest successfully. 617# 618# @fatal: the failure is unrecoverable. This occurs for 619# action-required failures if the recipient is the hypervisor; 620# QEMU will exit. 621# 622# @reset: the failure is unrecoverable but confined to the guest. 623# This occurs if the recipient is a guest guest which is not ready 624# to handle memory failures. 625# 626# Since: 5.2 627## 628{ 'enum': 'MemoryFailureAction', 629 'data': [ 'ignore', 630 'inject', 631 'fatal', 632 'reset' ] } 633 634## 635# @MemoryFailureFlags: 636# 637# Additional information on memory failures. 638# 639# @action-required: whether a memory failure event is action-required 640# or action-optional (e.g. a failure during memory scrub). 641# 642# @recursive: whether the failure occurred while the previous failure 643# was still in progress. 644# 645# Since: 5.2 646## 647{ 'struct': 'MemoryFailureFlags', 648 'data': { 'action-required': 'bool', 649 'recursive': 'bool'} } 650 651## 652# @NotifyVmexitOption: 653# 654# An enumeration of the options specified when enabling notify VM exit 655# 656# @run: enable the feature, do nothing and continue if the notify VM 657# exit happens. 658# 659# @internal-error: enable the feature, raise a internal error if the 660# notify VM exit happens. 661# 662# @disable: disable the feature. 663# 664# Since: 7.2 665## 666{ 'enum': 'NotifyVmexitOption', 667 'data': [ 'run', 'internal-error', 'disable' ] } 668