# -*- Mode: Python -*-
# vim: filetype=python
#

##
# @RTC_CHANGE:
#
# Emitted when the guest changes the RTC time.
#
# @offset: offset between base RTC clock (as specified by -rtc base), and
#          new RTC clock value
#
# Note: This event is rate-limited.
#
# Since: 0.13
#
# Example:
#
# <-   { "event": "RTC_CHANGE",
#        "data": { "offset": 78 },
#        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
#
##
{ 'event': 'RTC_CHANGE',
  'data': { 'offset': 'int' },
  'if': 'defined(TARGET_ALPHA) || defined(TARGET_ARM) || defined(TARGET_HPPA) || defined(TARGET_I386) || defined(TARGET_MIPS) || defined(TARGET_MIPS64) || defined(TARGET_MOXIE) || defined(TARGET_PPC) || defined(TARGET_PPC64) || defined(TARGET_S390X) || defined(TARGET_SH4) || defined(TARGET_SPARC)' }

##
# @rtc-reset-reinjection:
#
# This command will reset the RTC interrupt reinjection backlog.
# Can be used if another mechanism to synchronize guest time
# is in effect, for example QEMU guest agent's guest-set-time
# command.
#
# Since: 2.1
#
# Example:
#
# -> { "execute": "rtc-reset-reinjection" }
# <- { "return": {} }
#
##
{ 'command': 'rtc-reset-reinjection',
  'if': 'defined(TARGET_I386)' }


##
# @SevState:
#
# An enumeration of SEV state information used during @query-sev.
#
# @uninit: The guest is uninitialized.
#
# @launch-update: The guest is currently being launched; plaintext data and
#                 register state is being imported.
#
# @launch-secret: The guest is currently being launched; ciphertext data
#                 is being imported.
#
# @running: The guest is fully launched or migrated in.
#
# @send-update: The guest is currently being migrated out to another machine.
#
# @receive-update: The guest is currently being migrated from another machine.
#
# Since: 2.12
##
{ 'enum': 'SevState',
  'data': ['uninit', 'launch-update', 'launch-secret', 'running',
           'send-update', 'receive-update' ],
  'if': 'defined(TARGET_I386)' }

##
# @SevInfo:
#
# Information about Secure Encrypted Virtualization (SEV) support
#
# @enabled: true if SEV is active
#
# @api-major: SEV API major version
#
# @api-minor: SEV API minor version
#
# @build-id: SEV FW build id
#
# @policy: SEV policy value
#
# @state: SEV guest state
#
# @handle: SEV firmware handle
#
# Since: 2.12
##
{ 'struct': 'SevInfo',
    'data': { 'enabled': 'bool',
              'api-major': 'uint8',
              'api-minor' : 'uint8',
              'build-id' : 'uint8',
              'policy' : 'uint32',
              'state' : 'SevState',
              'handle' : 'uint32'
            },
  'if': 'defined(TARGET_I386)'
}

##
# @query-sev:
#
# Returns information about SEV
#
# Returns: @SevInfo
#
# Since: 2.12
#
# Example:
#
# -> { "execute": "query-sev" }
# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
#                  "build-id" : 0, "policy" : 0, "state" : "running",
#                  "handle" : 1 } }
#
##
{ 'command': 'query-sev', 'returns': 'SevInfo',
  'if': 'defined(TARGET_I386)' }


##
# @SevLaunchMeasureInfo:
#
# SEV Guest Launch measurement information
#
# @data: the measurement value encoded in base64
#
# Since: 2.12
#
##
{ 'struct': 'SevLaunchMeasureInfo', 'data': {'data': 'str'},
  'if': 'defined(TARGET_I386)' }

##
# @query-sev-launch-measure:
#
# Query the SEV guest launch information.
#
# Returns: The @SevLaunchMeasureInfo for the guest
#
# Since: 2.12
#
# Example:
#
# -> { "execute": "query-sev-launch-measure" }
# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
#
##
{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo',
  'if': 'defined(TARGET_I386)' }


##
# @SevCapability:
#
# The struct describes capability for a Secure Encrypted Virtualization
# feature.
#
# @pdh:  Platform Diffie-Hellman key (base64 encoded)
#
# @cert-chain:  PDH certificate chain (base64 encoded)
#
# @cbitpos: C-bit location in page table entry
#
# @reduced-phys-bits: Number of physical Address bit reduction when SEV is
#                     enabled
#
# Since: 2.12
##
{ 'struct': 'SevCapability',
  'data': { 'pdh': 'str',
            'cert-chain': 'str',
            'cbitpos': 'int',
            'reduced-phys-bits': 'int'},
  'if': 'defined(TARGET_I386)' }

##
# @query-sev-capabilities:
#
# This command is used to get the SEV capabilities, and is supported on AMD
# X86 platforms only.
#
# Returns: SevCapability objects.
#
# Since: 2.12
#
# Example:
#
# -> { "execute": "query-sev-capabilities" }
# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
#                  "cbitpos": 47, "reduced-phys-bits": 5}}
#
##
{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability',
  'if': 'defined(TARGET_I386)' }

##
# @sev-inject-launch-secret:
#
# This command injects a secret blob into memory of SEV guest.
#
# @packet-header: the launch secret packet header encoded in base64
#
# @secret: the launch secret data to be injected encoded in base64
#
# @gpa: the guest physical address where secret will be injected.
#
# Since: 6.0
#
##
{ 'command': 'sev-inject-launch-secret',
  'data': { 'packet-header': 'str', 'secret': 'str', 'gpa': 'uint64' },
  'if': 'defined(TARGET_I386)' }

##
# @dump-skeys:
#
# Dump guest's storage keys
#
# @filename: the path to the file to dump to
#
# This command is only supported on s390 architecture.
#
# Since: 2.5
#
# Example:
#
# -> { "execute": "dump-skeys",
#      "arguments": { "filename": "/tmp/skeys" } }
# <- { "return": {} }
#
##
{ 'command': 'dump-skeys',
  'data': { 'filename': 'str' },
  'if': 'defined(TARGET_S390X)' }

##
# @GICCapability:
#
# The struct describes capability for a specific GIC (Generic
# Interrupt Controller) version. These bits are not only decided by
# QEMU/KVM software version, but also decided by the hardware that
# the program is running upon.
#
# @version: version of GIC to be described. Currently, only 2 and 3
#           are supported.
#
# @emulated: whether current QEMU/hardware supports emulated GIC
#            device in user space.
#
# @kernel: whether current QEMU/hardware supports hardware
#          accelerated GIC device in kernel.
#
# Since: 2.6
##
{ 'struct': 'GICCapability',
  'data': { 'version': 'int',
            'emulated': 'bool',
            'kernel': 'bool' },
  'if': 'defined(TARGET_ARM)' }

##
# @query-gic-capabilities:
#
# This command is ARM-only. It will return a list of GICCapability
# objects that describe its capability bits.
#
# Returns: a list of GICCapability objects.
#
# Since: 2.6
#
# Example:
#
# -> { "execute": "query-gic-capabilities" }
# <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
#                 { "version": 3, "emulated": false, "kernel": true } ] }
#
##
{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'],
  'if': 'defined(TARGET_ARM)' }