qapi/run-state.json - qemu - Git at Google


            
            # -*- Mode: Python -*-

            
            # vim: filetype=python

            
            #


            ##

            
            # ************

            
            # VM run state

            
            # ************

            
            ##


            ##

            
            # @RunState:

            
            #     An enumeration of VM run states.

            
            #

            
            # @debug: QEMU is running on a debugger

            
            #

            
            # @finish-migrate: guest is paused to finish the migration process

            
            #

            
            # @inmigrate: guest is paused waiting for an incoming migration.  Note

            
            #     that this state does not tell whether the machine will start at

            
            #     the end of the migration.  This depends on the command-line -S

            
            #     option and any invocation of `stop` or `cont` that has happened

            
            #     since QEMU was started.

            
            #

            
            # @internal-error: An internal error that prevents further guest

            
            #     execution has occurred

            
            #

            
            # @io-error: the last IOP has failed and the device is configured to

            
            #     pause on I/O errors

            
            #

            
            # @paused: guest has been paused via the 'stop' command

            
            #

            
            # @postmigrate: guest is paused following a successful 'migrate'

            
            #

            
            # @prelaunch: QEMU was started with -S and guest has not started

            
            #

            
            # @restore-vm: guest is paused to restore VM state

            
            #

            
            # @running: guest is actively running

            
            #

            
            # @save-vm: guest is paused to save the VM state

            
            #

            
            # @shutdown: guest is shut down (and -no-shutdown is in use)

            
            #

            
            # @suspended: guest is suspended (ACPI S3)

            
            #

            
            # @watchdog: the watchdog action is configured to pause and has been

            
            #     triggered

            
            #

            
            # @guest-panicked: guest has been panicked as a result of guest OS

            
            #     panic

            
            #

            
            # @colo: guest is paused to save/restore VM state under colo

            
            #     checkpoint, VM can not get into this state unless colo

            
            #     capability is enabled for migration.  (since 2.8)

            
            ##

            
            { 'enum': 'RunState',

            
              'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',

            
                        'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',

            
                        'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',

            
                        'guest-panicked', 'colo' ] }


            ##

            
            # @ShutdownCause:

            
            #     An enumeration of reasons for a shutdown.

            
            #

            
            # @none: No shutdown request pending

            
            #

            
            # @host-error: An error prevents further use of guest

            
            #

            
            # @host-qmp-quit: Reaction to the QMP command `quit`

            
            #

            
            # @host-qmp-system-reset: Reaction to the QMP command `system_reset`

            
            #

            
            # @host-signal: Reaction to a signal, such as SIGINT

            
            #

            
            # @host-ui: Reaction to a UI event, like window close

            
            #

            
            # @guest-shutdown: Guest shutdown/suspend request, via ACPI or other

            
            #     hardware-specific means

            
            #

            
            # @guest-reset: Guest reset request, and command line turns that into

            
            #     a shutdown

            
            #

            
            # @guest-panic: Guest panicked, and command line turns that into a

            
            #     shutdown

            
            #

            
            # @subsystem-reset: Partial guest reset that does not trigger QMP

            
            #     events and ignores --no-reboot.  This is useful for sanitizing

            
            #     hypercalls on s390 that are used during kexec/kdump/boot

            
            #

            
            # @snapshot-load: A snapshot is being loaded by the record & replay

            
            #     subsystem.  This value is used only within QEMU.  It doesn't

            
            #     occur in QMP.  (since 7.2)

            
            ##

            
            { 'enum': 'ShutdownCause',

            
              # Beware, shutdown_caused_by_guest() depends on enumeration order

            
              'data': [ 'none', 'host-error', 'host-qmp-quit', 'host-qmp-system-reset',

            
                        'host-signal', 'host-ui', 'guest-shutdown', 'guest-reset',

            
                        'guest-panic', 'subsystem-reset', 'snapshot-load'] }


            ##

            
            # @StatusInfo:

            
            #     Information about VM run state

            
            #

            
            # @running: true if all VCPUs are runnable, false if not runnable

            
            #

            
            # @status: the virtual machine `RunState`

            
            #

            
            # Since: 0.14

            
            ##

            
            { 'struct': 'StatusInfo',

            
              'data': {'running': 'bool',

            
                       'status': 'RunState'} }


            ##

            
            # @query-status:

            
            #     Query the run status of the VM

            
            #

            
            # Since: 0.14

            
            #

            
            # .. qmp-example::

            
            #

            
            #     -> { "execute": "query-status" }

            
            #     <- { "return": { "running": true,

            
            #                      "status": "running" } }

            
            ##

            
            { 'command': 'query-status', 'returns': 'StatusInfo',

            
              'allow-preconfig': true }


            ##

            
            # @SHUTDOWN:

            
            #     Emitted when the virtual machine has shut down, indicating that

            
            #     QEMU is about to exit.

            
            #

            
            # @guest: If true, the shutdown was triggered by a guest request (such

            
            #     as a guest-initiated ACPI shutdown request or other

            
            #     hardware-specific action) rather than a host request (such as

            
            #     sending QEMU a SIGINT).  (since 2.10)

            
            #

            
            # @reason: The `ShutdownCause` which resulted in the `SHUTDOWN`.

            
            #     (since 4.0)

            
            #

            
            # .. note:: If the command-line option ``-no-shutdown`` has been

            
            #    specified, QEMU will not exit, and a `STOP` event will eventually

            
            #    follow the `SHUTDOWN` event.

            
            #

            
            # Since: 0.12

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "SHUTDOWN",

            
            #          "data": { "guest": true, "reason": "guest-shutdown" },

            
            #          "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }

            
            ##

            
            { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }


            ##

            
            # @POWERDOWN:

            
            #     Emitted when the virtual machine is powered down through the

            
            #     power control system, such as via ACPI.

            
            #

            
            # Since: 0.12

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "POWERDOWN",

            
            #          "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }

            
            ##

            
            { 'event': 'POWERDOWN' }


            ##

            
            # @RESET:

            
            #     Emitted when the virtual machine is reset

            
            #

            
            # @guest: If true, the reset was triggered by a guest request (such as

            
            #     a guest-initiated ACPI reboot request or other hardware-specific

            
            #     action) rather than a host request (such as the QMP command

            
            #     `system_reset`).  (since 2.10)

            
            #

            
            # @reason: The `ShutdownCause` of the `RESET`.  (since 4.0)

            
            #

            
            # Since: 0.12

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "RESET",

            
            #          "data": { "guest": false, "reason": "guest-reset" },

            
            #          "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }

            
            ##

            
            { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }


            ##

            
            # @STOP:

            
            #     Emitted when the virtual machine is stopped

            
            #

            
            # Since: 0.12

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "STOP",

            
            #          "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }

            
            ##

            
            { 'event': 'STOP' }


            ##

            
            # @RESUME:

            
            #     Emitted when the virtual machine resumes execution

            
            #

            
            # Since: 0.12

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "RESUME",

            
            #          "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }

            
            ##

            
            { 'event': 'RESUME' }


            ##

            
            # @SUSPEND:

            
            #     Emitted when guest enters a hardware suspension state, for

            
            #     example, S3 state, which is sometimes called standby state

            
            #

            
            # Since: 1.1

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "SUSPEND",

            
            #          "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }

            
            ##

            
            { 'event': 'SUSPEND' }


            ##

            
            # @SUSPEND_DISK:

            
            #     Emitted when guest enters a hardware suspension state with data

            
            #     saved on disk, for example, S4 state, which is sometimes called

            
            #     hibernate state

            
            #

            
            # .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when

            
            #    entering this state.

            
            #

            
            # Since: 1.2

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "SUSPEND_DISK",

            
            #          "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }

            
            ##

            
            { 'event': 'SUSPEND_DISK' }


            ##

            
            # @WAKEUP:

            
            #     Emitted when the guest has woken up from suspend state and is

            
            #     running

            
            #

            
            # Since: 1.1

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "WAKEUP",

            
            #          "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }

            
            ##

            
            { 'event': 'WAKEUP' }


            ##

            
            # @WATCHDOG:

            
            #     Emitted when the watchdog device's timer is expired

            
            #

            
            # @action: action that has been taken

            
            #

            
            # .. note:: If action is "reset", "shutdown", or "pause" the

            
            #    `WATCHDOG` event is followed respectively by the `RESET`,

            
            #    `SHUTDOWN`, or `STOP` events.

            
            #

            
            # .. note:: This event is rate-limited.

            
            #

            
            # Since: 0.13

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "WATCHDOG",

            
            #          "data": { "action": "reset" },

            
            #          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }

            
            ##

            
            { 'event': 'WATCHDOG',

            
              'data': { 'action': 'WatchdogAction' } }


            ##

            
            # @WatchdogAction:

            
            #     An enumeration of the actions taken when the watchdog device's

            
            #     timer is expired

            
            #

            
            # @reset: system resets

            
            #

            
            # @shutdown: system shutdown, note that it is similar to @powerdown,

            
            #     which tries to set to system status and notify guest

            
            #

            
            # @poweroff: system poweroff, the emulator program exits

            
            #

            
            # @pause: system pauses, similar to @stop

            
            #

            
            # @debug: system enters debug state

            
            #

            
            # @none: nothing is done

            
            #

            
            # @inject-nmi: a non-maskable interrupt is injected (machine

            
            #     specific: for example on s390x CCW only the first vCPU

            
            #     receives the NMI, but on x86 machines all vCPUs receive

            
            #     it).  (since 2.4)

            
            #

            
            # Since: 2.1

            
            ##

            
            { 'enum': 'WatchdogAction',

            
              'data': [ 'reset', 'shutdown', 'poweroff', 'pause', 'debug', 'none',

            
                        'inject-nmi' ] }


            ##

            
            # @RebootAction:

            
            #     Possible QEMU actions upon guest reboot

            
            #

            
            # @reset: Reset the VM

            
            #

            
            # @shutdown: Shutdown the VM and exit, according to the shutdown

            
            #     action

            
            #

            
            # Since: 6.0

            
            ##

            
            { 'enum': 'RebootAction',

            
              'data': [ 'reset', 'shutdown' ] }


            ##

            
            # @ShutdownAction:

            
            #     Possible QEMU actions upon guest shutdown

            
            #

            
            # @poweroff: Shutdown the VM and exit

            
            #

            
            # @pause: pause the VM

            
            #

            
            # Since: 6.0

            
            ##

            
            { 'enum': 'ShutdownAction',

            
              'data': [ 'poweroff', 'pause' ] }


            ##

            
            # @PanicAction:

            
            #

            
            # @none: Continue VM execution

            
            #

            
            # @pause: Pause the VM

            
            #

            
            # @shutdown: Shutdown the VM and exit, according to the shutdown

            
            #     action

            
            #

            
            # @exit-failure: Shutdown the VM and exit with nonzero status

            
            #     (since 7.1)

            
            #

            
            # Since: 6.0

            
            ##

            
            { 'enum': 'PanicAction',

            
              'data': [ 'pause', 'shutdown', 'exit-failure', 'none' ] }


            ##

            
            # @watchdog-set-action:

            
            #     Set watchdog action.

            
            #

            
            # @action: `WatchdogAction` action taken when watchdog timer expires.

            
            #

            
            # Since: 2.11

            
            #

            
            # .. qmp-example::

            
            #

            
            #     -> { "execute": "watchdog-set-action",

            
            #          "arguments": { "action": "inject-nmi" } }

            
            #     <- { "return": {} }

            
            ##

            
            { 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }


            ##

            
            # @set-action:

            
            #     Set the actions that will be taken by the emulator in response

            
            #     to guest events.

            
            #

            
            # @reboot: `RebootAction` action taken on guest reboot.

            
            #

            
            # @shutdown: `ShutdownAction` action taken on guest shutdown.

            
            #

            
            # @panic: `PanicAction` action taken on guest panic.

            
            #

            
            # @watchdog: `WatchdogAction` action taken when watchdog timer

            
            #     expires.

            
            #

            
            # Since: 6.0

            
            #

            
            # .. qmp-example::

            
            #

            
            #     -> { "execute": "set-action",

            
            #          "arguments": { "reboot": "shutdown",

            
            #                         "shutdown" : "pause",

            
            #                         "panic": "pause",

            
            #                         "watchdog": "inject-nmi" } }

            
            #     <- { "return": {} }

            
            ##

            
            { 'command': 'set-action',

            
              'data': { '*reboot': 'RebootAction',

            
                        '*shutdown': 'ShutdownAction',

            
                        '*panic': 'PanicAction',

            
                        '*watchdog': 'WatchdogAction' },

            
              'allow-preconfig': true }


            ##

            
            # @GUEST_PANICKED:

            
            #     Emitted when guest OS panic is detected

            
            #

            
            # @action: action that has been taken, currently always "pause"

            
            #

            
            # @info: information about a panic (since 2.9)

            
            #

            
            # Since: 1.5

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "GUEST_PANICKED",

            
            #          "data": { "action": "pause" },

            
            #          "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }

            
            ##

            
            { 'event': 'GUEST_PANICKED',

            
              'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }


            ##

            
            # @GUEST_CRASHLOADED:

            
            #     Emitted when guest OS crash loaded is detected

            
            #

            
            # @action: action that has been taken, currently always "run"

            
            #

            
            # @info: information about a panic

            
            #

            
            # Since: 5.0

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "GUEST_CRASHLOADED",

            
            #          "data": { "action": "run" },

            
            #          "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }

            
            ##

            
            { 'event': 'GUEST_CRASHLOADED',

            
              'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }


            ##

            
            # @GUEST_PVSHUTDOWN:

            
            #     Emitted when guest submits a shutdown request via pvpanic

            
            #     interface

            
            #

            
            # Since: 9.1

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "GUEST_PVSHUTDOWN",

            
            #          "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }

            
            ##

            
            { 'event': 'GUEST_PVSHUTDOWN' }


            ##

            
            # @GuestPanicAction:

            
            #     An enumeration of the actions taken when guest OS panic is

            
            #     detected

            
            #

            
            # @pause: system pauses

            
            #

            
            # @poweroff: system powers off (since 2.8)

            
            #

            
            # @run: system continues to run (since 5.0)

            
            #

            
            # Since: 2.1

            
            ##

            
            { 'enum': 'GuestPanicAction',

            
              'data': [ 'pause', 'poweroff', 'run' ] }


            ##

            
            # @GuestPanicInformationType:

            
            #     An enumeration of the guest panic information types

            
            #

            
            # @hyper-v: hyper-v guest panic information type

            
            #

            
            # @s390: s390 guest panic information type (Since: 2.12)

            
            #

            
            # @tdx: tdx guest panic information type (Since: 10.1)

            
            #

            
            # @sev: AMD SEV-ES guest termination information type (Since: 11.0)

            
            #

            
            # Since: 2.9

            
            ##

            
            { 'enum': 'GuestPanicInformationType',

            
              'data': [ 'hyper-v', 's390', 'tdx', 'sev' ] }


            ##

            
            # @GuestPanicInformation:

            
            #     Information about a guest panic

            
            #

            
            # @type: Crash type that defines the hypervisor specific information

            
            #

            
            # Since: 2.9

            
            ##

            
            {'union': 'GuestPanicInformation',

            
             'base': {'type': 'GuestPanicInformationType'},

            
             'discriminator': 'type',

            
             'data': {'hyper-v': 'GuestPanicInformationHyperV',

            
                      's390': 'GuestPanicInformationS390',

            
                      'tdx': 'GuestPanicInformationTdx',

            
                      'sev': 'GuestPanicInformationSev' }}


            ##

            
            # @GuestPanicInformationHyperV:

            
            #     Hyper-V specific guest panic information (HV crash MSRs)

            
            #

            
            # @arg1: for Windows, `STOP` code for the guest crash.  For Linux,

            
            #     an error code.

            
            #

            
            # @arg2: for Windows, first argument of the `STOP`.  For Linux, the

            
            #     guest OS ID, which has the kernel version in bits 16-47 and

            
            #     0x8100 in bits 48-63.

            
            #

            
            # @arg3: for Windows, second argument of the `STOP`.  For Linux, the

            
            #     program counter of the guest.

            
            #

            
            # @arg4: for Windows, third argument of the `STOP`.  For Linux, the

            
            #     RAX register (x86) or the stack pointer (aarch64) of the guest.

            
            #

            
            # @arg5: for Windows, fourth argument of the `STOP`.  For x86 Linux,

            
            #     the stack pointer of the guest.

            
            #

            
            # Since: 2.9

            
            ##

            
            {'struct': 'GuestPanicInformationHyperV',

            
             'data': {'arg1': 'uint64',

            
                      'arg2': 'uint64',

            
                      'arg3': 'uint64',

            
                      'arg4': 'uint64',

            
                      'arg5': 'uint64'}}


            ##

            
            # @S390CrashReason:

            
            #     Reason why the CPU is in a crashed state.

            
            #

            
            # @unknown: no crash reason was set

            
            #

            
            # @disabled-wait: the CPU has entered a disabled wait state

            
            #

            
            # @extint-loop: clock comparator or cpu timer interrupt with new PSW

            
            #     enabled for external interrupts

            
            #

            
            # @pgmint-loop: program interrupt with BAD new PSW

            
            #

            
            # @opint-loop: operation exception interrupt with invalid code at the

            
            #     program interrupt new PSW

            
            #

            
            # Since: 2.12

            
            ##

            
            { 'enum': 'S390CrashReason',

            
              'data': [ 'unknown',

            
                        'disabled-wait',

            
                        'extint-loop',

            
                        'pgmint-loop',

            
                        'opint-loop' ] }


            ##

            
            # @GuestPanicInformationS390:

            
            #     S390 specific guest panic information (PSW)

            
            #

            
            # @core: core id of the CPU that crashed

            
            #

            
            # @psw-mask: control fields of guest PSW

            
            #

            
            # @psw-addr: guest instruction address

            
            #

            
            # @reason: guest crash reason

            
            #

            
            # Since: 2.12

            
            ##

            
            {'struct': 'GuestPanicInformationS390',

            
             'data': {'core': 'uint32',

            
                      'psw-mask': 'uint64',

            
                      'psw-addr': 'uint64',

            
                      'reason': 'S390CrashReason'}}


            ##

            
            # @GuestPanicInformationTdx:

            
            #     TDX Guest panic information specific to TDX, as specified in the

            
            #     "Guest-Hypervisor Communication Interface (GHCI) Specification",

            
            #     section TDG.VP.VMCALL<ReportFatalError>.

            
            #

            
            # @error-code: TD-specific error code

            
            #

            
            # @message: Human-readable error message provided by the guest.  Not

            
            #     to be trusted.

            
            #

            
            # @gpa: guest-physical address of a page that contains more verbose

            
            #     error information, as zero-terminated string.  Present when the

            
            #     "GPA valid" bit (bit 63) is set in @error-code.

            
            #

            
            # Since: 10.1

            
            ##

            
            {'struct': 'GuestPanicInformationTdx',

            
             'data': {'error-code': 'uint32',

            
                      'message': 'str',

            
                      '*gpa': 'uint64'}}


            ##

            
            # @GuestPanicInformationSev:

            
            #     Information for AMD SEV-specific termination request (GHCB MSR

            
            #     contents)

            
            #

            
            # @set: The reason code set provided by the guest

            
            #

            
            # @code: The reason code provided by the guest

            
            #

            
            # Since: 11.0

            
            ##

            
            {'struct': 'GuestPanicInformationSev',

            
             'data': {'set': 'uint32',

            
                      'code': 'uint32'}}


            ##

            
            # @MEMORY_FAILURE:

            
            #     Emitted when a memory failure occurs on host side.

            
            #

            
            # @recipient: recipient is defined as `MemoryFailureRecipient`.

            
            #

            
            # @action: action that has been taken.

            
            #

            
            # @flags: flags for `MemoryFailureAction`.

            
            #

            
            # Since: 5.2

            
            #

            
            # .. qmp-example::

            
            #

            
            #     <- { "event": "MEMORY_FAILURE",

            
            #          "data": { "recipient": "hypervisor",

            
            #                    "action": "fatal",

            
            #                    "flags": { "action-required": false,

            
            #                               "recursive": false } },

            
            #          "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }

            
            ##

            
            { 'event': 'MEMORY_FAILURE',

            
              'data': { 'recipient': 'MemoryFailureRecipient',

            
                        'action': 'MemoryFailureAction',

            
                        'flags': 'MemoryFailureFlags'} }


            ##

            
            # @MemoryFailureRecipient:

            
            #     Hardware memory failure occurs, handled by recipient.

            
            #

            
            # @hypervisor: memory failure at QEMU process address space.  (none

            
            #     guest memory, but used by QEMU itself).

            
            #

            
            # @guest: memory failure at guest memory,

            
            #

            
            # Since: 5.2

            
            ##

            
            { 'enum': 'MemoryFailureRecipient',

            
              'data': [ 'hypervisor',

            
                        'guest' ] }


            ##

            
            # @MemoryFailureAction:

            
            #     Actions taken by QEMU in response to a hardware memory failure.

            
            #

            
            # @ignore: the memory failure could be ignored.  This will only be the

            
            #     case for action-optional failures.

            
            #

            
            # @inject: memory failure occurred in guest memory, the guest enabled

            
            #     MCE handling mechanism, and QEMU could inject the MCE into the

            
            #     guest successfully.

            
            #

            
            # @fatal: the failure is unrecoverable.  This occurs for

            
            #     action-required failures if the recipient is the hypervisor;

            
            #     QEMU will exit.

            
            #

            
            # @reset: the failure is unrecoverable but confined to the guest.

            
            #     This occurs if the recipient is a guest guest which is not ready

            
            #     to handle memory failures.

            
            #

            
            # Since: 5.2

            
            ##

            
            { 'enum': 'MemoryFailureAction',

            
              'data': [ 'ignore',

            
                        'inject',

            
                        'fatal',

            
                        'reset' ] }


            ##

            
            # @MemoryFailureFlags:

            
            #     Additional information on memory failures.

            
            #

            
            # @action-required: whether a memory failure event is action-required

            
            #     or action-optional (e.g. a failure during memory scrub).

            
            #

            
            # @recursive: whether the failure occurred while the previous failure

            
            #     was still in progress.

            
            #

            
            # Since: 5.2

            
            ##

            
            { 'struct': 'MemoryFailureFlags',

            
              'data': { 'action-required': 'bool',

            
                        'recursive': 'bool'} }


            ##

            
            # @NotifyVmexitOption:

            
            #     An enumeration of the options specified when enabling notify VM

            
            #     exit

            
            #

            
            # @run: enable the feature, do nothing and continue if the notify VM

            
            #     exit happens.

            
            #

            
            # @internal-error: enable the feature, raise a internal error if the

            
            #     notify VM exit happens.

            
            #

            
            # @disable: disable the feature.

            
            #

            
            # Since: 7.2

            
            ##

            
            { 'enum': 'NotifyVmexitOption',

            
              'data': [ 'run', 'internal-error', 'disable' ] }
	# -- Mode: Python --
	# vim: filetype=python
	#

	##
	# ************
	# VM run state
	# ************
	##

	##
	# @RunState:
	# An enumeration of VM run states.
	#
	# @debug: QEMU is running on a debugger
	#
	# @finish-migrate: guest is paused to finish the migration process
	#
	# @inmigrate: guest is paused waiting for an incoming migration. Note
	# that this state does not tell whether the machine will start at
	# the end of the migration. This depends on the command-line -S
	# option and any invocation of `stop` or `cont` that has happened
	# since QEMU was started.
	#
	# @internal-error: An internal error that prevents further guest
	# execution has occurred
	#
	# @io-error: the last IOP has failed and the device is configured to
	# pause on I/O errors
	#
	# @paused: guest has been paused via the 'stop' command
	#
	# @postmigrate: guest is paused following a successful 'migrate'
	#
	# @prelaunch: QEMU was started with -S and guest has not started
	#
	# @restore-vm: guest is paused to restore VM state
	#
	# @running: guest is actively running
	#
	# @save-vm: guest is paused to save the VM state
	#
	# @shutdown: guest is shut down (and -no-shutdown is in use)
	#
	# @suspended: guest is suspended (ACPI S3)
	#
	# @watchdog: the watchdog action is configured to pause and has been
	# triggered
	#
	# @guest-panicked: guest has been panicked as a result of guest OS
	# panic
	#
	# @colo: guest is paused to save/restore VM state under colo
	# checkpoint, VM can not get into this state unless colo
	# capability is enabled for migration. (since 2.8)
	##
	{ 'enum': 'RunState',
	'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused',
	'postmigrate', 'prelaunch', 'finish-migrate', 'restore-vm',
	'running', 'save-vm', 'shutdown', 'suspended', 'watchdog',
	'guest-panicked', 'colo' ] }

	##
	# @ShutdownCause:
	# An enumeration of reasons for a shutdown.
	#
	# @none: No shutdown request pending
	#
	# @host-error: An error prevents further use of guest
	#
	# @host-qmp-quit: Reaction to the QMP command `quit`
	#
	# @host-qmp-system-reset: Reaction to the QMP command `system_reset`
	#
	# @host-signal: Reaction to a signal, such as SIGINT
	#
	# @host-ui: Reaction to a UI event, like window close
	#
	# @guest-shutdown: Guest shutdown/suspend request, via ACPI or other
	# hardware-specific means
	#
	# @guest-reset: Guest reset request, and command line turns that into
	# a shutdown
	#
	# @guest-panic: Guest panicked, and command line turns that into a
	# shutdown
	#
	# @subsystem-reset: Partial guest reset that does not trigger QMP
	# events and ignores --no-reboot. This is useful for sanitizing
	# hypercalls on s390 that are used during kexec/kdump/boot
	#
	# @snapshot-load: A snapshot is being loaded by the record & replay
	# subsystem. This value is used only within QEMU. It doesn't
	# occur in QMP. (since 7.2)
	##
	{ 'enum': 'ShutdownCause',
	# Beware, shutdown_caused_by_guest() depends on enumeration order
	'data': [ 'none', 'host-error', 'host-qmp-quit', 'host-qmp-system-reset',
	'host-signal', 'host-ui', 'guest-shutdown', 'guest-reset',
	'guest-panic', 'subsystem-reset', 'snapshot-load'] }

	##
	# @StatusInfo:
	# Information about VM run state
	#
	# @running: true if all VCPUs are runnable, false if not runnable
	#
	# @status: the virtual machine `RunState`
	#
	# Since: 0.14
	##
	{ 'struct': 'StatusInfo',
	'data': {'running': 'bool',
	'status': 'RunState'} }

	##
	# @query-status:
	# Query the run status of the VM
	#
	# Since: 0.14
	#
	# .. qmp-example::
	#
	# -> { "execute": "query-status" }
	# <- { "return": { "running": true,
	# "status": "running" } }
	##
	{ 'command': 'query-status', 'returns': 'StatusInfo',
	'allow-preconfig': true }

	##
	# @SHUTDOWN:
	# Emitted when the virtual machine has shut down, indicating that
	# QEMU is about to exit.
	#
	# @guest: If true, the shutdown was triggered by a guest request (such
	# as a guest-initiated ACPI shutdown request or other
	# hardware-specific action) rather than a host request (such as
	# sending QEMU a SIGINT). (since 2.10)
	#
	# @reason: The `ShutdownCause` which resulted in the `SHUTDOWN`.
	# (since 4.0)
	#
	# .. note:: If the command-line option ``-no-shutdown`` has been
	# specified, QEMU will not exit, and a `STOP` event will eventually
	# follow the `SHUTDOWN` event.
	#
	# Since: 0.12
	#
	# .. qmp-example::
	#
	# <- { "event": "SHUTDOWN",
	# "data": { "guest": true, "reason": "guest-shutdown" },
	# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
	##
	{ 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }

	##
	# @POWERDOWN:
	# Emitted when the virtual machine is powered down through the
	# power control system, such as via ACPI.
	#
	# Since: 0.12
	#
	# .. qmp-example::
	#
	# <- { "event": "POWERDOWN",
	# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
	##
	{ 'event': 'POWERDOWN' }

	##
	# @RESET:
	# Emitted when the virtual machine is reset
	#
	# @guest: If true, the reset was triggered by a guest request (such as
	# a guest-initiated ACPI reboot request or other hardware-specific
	# action) rather than a host request (such as the QMP command
	# `system_reset`). (since 2.10)
	#
	# @reason: The `ShutdownCause` of the `RESET`. (since 4.0)
	#
	# Since: 0.12
	#
	# .. qmp-example::
	#
	# <- { "event": "RESET",
	# "data": { "guest": false, "reason": "guest-reset" },
	# "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
	##
	{ 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } }

	##
	# @STOP:
	# Emitted when the virtual machine is stopped
	#
	# Since: 0.12
	#
	# .. qmp-example::
	#
	# <- { "event": "STOP",
	# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
	##
	{ 'event': 'STOP' }

	##
	# @RESUME:
	# Emitted when the virtual machine resumes execution
	#
	# Since: 0.12
	#
	# .. qmp-example::
	#
	# <- { "event": "RESUME",
	# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
	##
	{ 'event': 'RESUME' }

	##
	# @SUSPEND:
	# Emitted when guest enters a hardware suspension state, for
	# example, S3 state, which is sometimes called standby state
	#
	# Since: 1.1
	#
	# .. qmp-example::
	#
	# <- { "event": "SUSPEND",
	# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
	##
	{ 'event': 'SUSPEND' }

	##
	# @SUSPEND_DISK:
	# Emitted when guest enters a hardware suspension state with data
	# saved on disk, for example, S4 state, which is sometimes called
	# hibernate state
	#
	# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when
	# entering this state.
	#
	# Since: 1.2
	#
	# .. qmp-example::
	#
	# <- { "event": "SUSPEND_DISK",
	# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
	##
	{ 'event': 'SUSPEND_DISK' }

	##
	# @WAKEUP:
	# Emitted when the guest has woken up from suspend state and is
	# running
	#
	# Since: 1.1
	#
	# .. qmp-example::
	#
	# <- { "event": "WAKEUP",
	# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
	##
	{ 'event': 'WAKEUP' }

	##
	# @WATCHDOG:
	# Emitted when the watchdog device's timer is expired
	#
	# @action: action that has been taken
	#
	# .. note:: If action is "reset", "shutdown", or "pause" the
	# `WATCHDOG` event is followed respectively by the `RESET`,
	# `SHUTDOWN`, or `STOP` events.
	#
	# .. note:: This event is rate-limited.
	#
	# Since: 0.13
	#
	# .. qmp-example::
	#
	# <- { "event": "WATCHDOG",
	# "data": { "action": "reset" },
	# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
	##
	{ 'event': 'WATCHDOG',
	'data': { 'action': 'WatchdogAction' } }

	##
	# @WatchdogAction:
	# An enumeration of the actions taken when the watchdog device's
	# timer is expired
	#
	# @reset: system resets
	#
	# @shutdown: system shutdown, note that it is similar to @powerdown,
	# which tries to set to system status and notify guest
	#
	# @poweroff: system poweroff, the emulator program exits
	#
	# @pause: system pauses, similar to @stop
	#
	# @debug: system enters debug state
	#
	# @none: nothing is done
	#
	# @inject-nmi: a non-maskable interrupt is injected (machine
	# specific: for example on s390x CCW only the first vCPU
	# receives the NMI, but on x86 machines all vCPUs receive
	# it). (since 2.4)
	#
	# Since: 2.1
	##
	{ 'enum': 'WatchdogAction',
	'data': [ 'reset', 'shutdown', 'poweroff', 'pause', 'debug', 'none',
	'inject-nmi' ] }

	##
	# @RebootAction:
	# Possible QEMU actions upon guest reboot
	#
	# @reset: Reset the VM
	#
	# @shutdown: Shutdown the VM and exit, according to the shutdown
	# action
	#
	# Since: 6.0
	##
	{ 'enum': 'RebootAction',
	'data': [ 'reset', 'shutdown' ] }

	##
	# @ShutdownAction:
	# Possible QEMU actions upon guest shutdown
	#
	# @poweroff: Shutdown the VM and exit
	#
	# @pause: pause the VM
	#
	# Since: 6.0
	##
	{ 'enum': 'ShutdownAction',
	'data': [ 'poweroff', 'pause' ] }

	##
	# @PanicAction:
	#
	# @none: Continue VM execution
	#
	# @pause: Pause the VM
	#
	# @shutdown: Shutdown the VM and exit, according to the shutdown
	# action
	#
	# @exit-failure: Shutdown the VM and exit with nonzero status
	# (since 7.1)
	#
	# Since: 6.0
	##
	{ 'enum': 'PanicAction',
	'data': [ 'pause', 'shutdown', 'exit-failure', 'none' ] }

	##
	# @watchdog-set-action:
	# Set watchdog action.
	#
	# @action: `WatchdogAction` action taken when watchdog timer expires.
	#
	# Since: 2.11
	#
	# .. qmp-example::
	#
	# -> { "execute": "watchdog-set-action",
	# "arguments": { "action": "inject-nmi" } }
	# <- { "return": {} }
	##
	{ 'command': 'watchdog-set-action', 'data' : {'action': 'WatchdogAction'} }

	##
	# @set-action:
	# Set the actions that will be taken by the emulator in response
	# to guest events.
	#
	# @reboot: `RebootAction` action taken on guest reboot.
	#
	# @shutdown: `ShutdownAction` action taken on guest shutdown.
	#
	# @panic: `PanicAction` action taken on guest panic.
	#
	# @watchdog: `WatchdogAction` action taken when watchdog timer
	# expires.
	#
	# Since: 6.0
	#
	# .. qmp-example::
	#
	# -> { "execute": "set-action",
	# "arguments": { "reboot": "shutdown",
	# "shutdown" : "pause",
	# "panic": "pause",
	# "watchdog": "inject-nmi" } }
	# <- { "return": {} }
	##
	{ 'command': 'set-action',
	'data': { '*reboot': 'RebootAction',
	'*shutdown': 'ShutdownAction',
	'*panic': 'PanicAction',
	'*watchdog': 'WatchdogAction' },
	'allow-preconfig': true }

	##
	# @GUEST_PANICKED:
	# Emitted when guest OS panic is detected
	#
	# @action: action that has been taken, currently always "pause"
	#
	# @info: information about a panic (since 2.9)
	#
	# Since: 1.5
	#
	# .. qmp-example::
	#
	# <- { "event": "GUEST_PANICKED",
	# "data": { "action": "pause" },
	# "timestamp": { "seconds": 1648245231, "microseconds": 900001 } }
	##
	{ 'event': 'GUEST_PANICKED',
	'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }

	##
	# @GUEST_CRASHLOADED:
	# Emitted when guest OS crash loaded is detected
	#
	# @action: action that has been taken, currently always "run"
	#
	# @info: information about a panic
	#
	# Since: 5.0
	#
	# .. qmp-example::
	#
	# <- { "event": "GUEST_CRASHLOADED",
	# "data": { "action": "run" },
	# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
	##
	{ 'event': 'GUEST_CRASHLOADED',
	'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } }

	##
	# @GUEST_PVSHUTDOWN:
	# Emitted when guest submits a shutdown request via pvpanic
	# interface
	#
	# Since: 9.1
	#
	# .. qmp-example::
	#
	# <- { "event": "GUEST_PVSHUTDOWN",
	# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
	##
	{ 'event': 'GUEST_PVSHUTDOWN' }

	##
	# @GuestPanicAction:
	# An enumeration of the actions taken when guest OS panic is
	# detected
	#
	# @pause: system pauses
	#
	# @poweroff: system powers off (since 2.8)
	#
	# @run: system continues to run (since 5.0)
	#
	# Since: 2.1
	##
	{ 'enum': 'GuestPanicAction',
	'data': [ 'pause', 'poweroff', 'run' ] }

	##
	# @GuestPanicInformationType:
	# An enumeration of the guest panic information types
	#
	# @hyper-v: hyper-v guest panic information type
	#
	# @s390: s390 guest panic information type (Since: 2.12)
	#
	# @tdx: tdx guest panic information type (Since: 10.1)
	#
	# @sev: AMD SEV-ES guest termination information type (Since: 11.0)
	#
	# Since: 2.9
	##
	{ 'enum': 'GuestPanicInformationType',
	'data': [ 'hyper-v', 's390', 'tdx', 'sev' ] }

	##
	# @GuestPanicInformation:
	# Information about a guest panic
	#
	# @type: Crash type that defines the hypervisor specific information
	#
	# Since: 2.9
	##
	{'union': 'GuestPanicInformation',
	'base': {'type': 'GuestPanicInformationType'},
	'discriminator': 'type',
	'data': {'hyper-v': 'GuestPanicInformationHyperV',
	's390': 'GuestPanicInformationS390',
	'tdx': 'GuestPanicInformationTdx',
	'sev': 'GuestPanicInformationSev' }}

	##
	# @GuestPanicInformationHyperV:
	# Hyper-V specific guest panic information (HV crash MSRs)
	#
	# @arg1: for Windows, `STOP` code for the guest crash. For Linux,
	# an error code.
	#
	# @arg2: for Windows, first argument of the `STOP`. For Linux, the
	# guest OS ID, which has the kernel version in bits 16-47 and
	# 0x8100 in bits 48-63.
	#
	# @arg3: for Windows, second argument of the `STOP`. For Linux, the
	# program counter of the guest.
	#
	# @arg4: for Windows, third argument of the `STOP`. For Linux, the
	# RAX register (x86) or the stack pointer (aarch64) of the guest.
	#
	# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux,
	# the stack pointer of the guest.
	#
	# Since: 2.9
	##
	{'struct': 'GuestPanicInformationHyperV',
	'data': {'arg1': 'uint64',
	'arg2': 'uint64',
	'arg3': 'uint64',
	'arg4': 'uint64',
	'arg5': 'uint64'}}

	##
	# @S390CrashReason:
	# Reason why the CPU is in a crashed state.
	#
	# @unknown: no crash reason was set
	#
	# @disabled-wait: the CPU has entered a disabled wait state
	#
	# @extint-loop: clock comparator or cpu timer interrupt with new PSW
	# enabled for external interrupts
	#
	# @pgmint-loop: program interrupt with BAD new PSW
	#
	# @opint-loop: operation exception interrupt with invalid code at the
	# program interrupt new PSW
	#
	# Since: 2.12
	##
	{ 'enum': 'S390CrashReason',
	'data': [ 'unknown',
	'disabled-wait',
	'extint-loop',
	'pgmint-loop',
	'opint-loop' ] }

	##
	# @GuestPanicInformationS390:
	# S390 specific guest panic information (PSW)
	#
	# @core: core id of the CPU that crashed
	#
	# @psw-mask: control fields of guest PSW
	#
	# @psw-addr: guest instruction address
	#
	# @reason: guest crash reason
	#
	# Since: 2.12
	##
	{'struct': 'GuestPanicInformationS390',
	'data': {'core': 'uint32',
	'psw-mask': 'uint64',
	'psw-addr': 'uint64',
	'reason': 'S390CrashReason'}}

	##
	# @GuestPanicInformationTdx:
	# TDX Guest panic information specific to TDX, as specified in the
	# "Guest-Hypervisor Communication Interface (GHCI) Specification",
	# section TDG.VP.VMCALL<ReportFatalError>.
	#
	# @error-code: TD-specific error code
	#
	# @message: Human-readable error message provided by the guest. Not
	# to be trusted.
	#
	# @gpa: guest-physical address of a page that contains more verbose
	# error information, as zero-terminated string. Present when the
	# "GPA valid" bit (bit 63) is set in @error-code.
	#
	# Since: 10.1
	##
	{'struct': 'GuestPanicInformationTdx',
	'data': {'error-code': 'uint32',
	'message': 'str',
	'*gpa': 'uint64'}}

	##
	# @GuestPanicInformationSev:
	# Information for AMD SEV-specific termination request (GHCB MSR
	# contents)
	#
	# @set: The reason code set provided by the guest
	#
	# @code: The reason code provided by the guest
	#
	# Since: 11.0
	##
	{'struct': 'GuestPanicInformationSev',
	'data': {'set': 'uint32',
	'code': 'uint32'}}

	##
	# @MEMORY_FAILURE:
	# Emitted when a memory failure occurs on host side.
	#
	# @recipient: recipient is defined as `MemoryFailureRecipient`.
	#
	# @action: action that has been taken.
	#
	# @flags: flags for `MemoryFailureAction`.
	#
	# Since: 5.2
	#
	# .. qmp-example::
	#
	# <- { "event": "MEMORY_FAILURE",
	# "data": { "recipient": "hypervisor",
	# "action": "fatal",
	# "flags": { "action-required": false,
	# "recursive": false } },
	# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
	##
	{ 'event': 'MEMORY_FAILURE',
	'data': { 'recipient': 'MemoryFailureRecipient',
	'action': 'MemoryFailureAction',
	'flags': 'MemoryFailureFlags'} }

	##
	# @MemoryFailureRecipient:
	# Hardware memory failure occurs, handled by recipient.
	#
	# @hypervisor: memory failure at QEMU process address space. (none
	# guest memory, but used by QEMU itself).
	#
	# @guest: memory failure at guest memory,
	#
	# Since: 5.2
	##
	{ 'enum': 'MemoryFailureRecipient',
	'data': [ 'hypervisor',
	'guest' ] }

	##
	# @MemoryFailureAction:
	# Actions taken by QEMU in response to a hardware memory failure.
	#
	# @ignore: the memory failure could be ignored. This will only be the
	# case for action-optional failures.
	#
	# @inject: memory failure occurred in guest memory, the guest enabled
	# MCE handling mechanism, and QEMU could inject the MCE into the
	# guest successfully.
	#
	# @fatal: the failure is unrecoverable. This occurs for
	# action-required failures if the recipient is the hypervisor;
	# QEMU will exit.
	#
	# @reset: the failure is unrecoverable but confined to the guest.
	# This occurs if the recipient is a guest guest which is not ready
	# to handle memory failures.
	#
	# Since: 5.2
	##
	{ 'enum': 'MemoryFailureAction',
	'data': [ 'ignore',
	'inject',
	'fatal',
	'reset' ] }

	##
	# @MemoryFailureFlags:
	# Additional information on memory failures.
	#
	# @action-required: whether a memory failure event is action-required
	# or action-optional (e.g. a failure during memory scrub).
	#
	# @recursive: whether the failure occurred while the previous failure
	# was still in progress.
	#
	# Since: 5.2
	##
	{ 'struct': 'MemoryFailureFlags',
	'data': { 'action-required': 'bool',
	'recursive': 'bool'} }

	##
	# @NotifyVmexitOption:
	# An enumeration of the options specified when enabling notify VM
	# exit
	#
	# @run: enable the feature, do nothing and continue if the notify VM
	# exit happens.
	#
	# @internal-error: enable the feature, raise a internal error if the
	# notify VM exit happens.
	#
	# @disable: disable the feature.
	#
	# Since: 7.2
	##
	{ 'enum': 'NotifyVmexitOption',
	'data': [ 'run', 'internal-error', 'disable' ] }