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