mirror of
https://github.com/qemu/qemu.git
synced 2024-11-27 13:53:45 +08:00
14b48aaab9
Use the no-option form of ".. qmp-example::" to convert any Examples
that do not have any form of caption or explanation whatsoever. Note
that in a few cases, example sections are split into two or more
separate example blocks. This is only done stylistically to create a
delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.
See commit+3: "qapi: remove "Example" doc section" for a detailed
explanation of why.
Note: an empty "TODO" line was added to announce-self to keep the
example from floating up into the body; this will be addressed more
rigorously in the new qapidoc generator.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-7-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Markup fixed in one place]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
529 lines
12 KiB
Python
529 lines
12 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
|
|
##
|
|
# @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
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "rtc-reset-reinjection" }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'rtc-reset-reinjection',
|
|
'if': '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': 'TARGET_I386' }
|
|
|
|
##
|
|
# @SevGuestType:
|
|
#
|
|
# An enumeration indicating the type of SEV guest being run.
|
|
#
|
|
# @sev: The guest is a legacy SEV or SEV-ES guest.
|
|
#
|
|
# @sev-snp: The guest is an SEV-SNP guest.
|
|
#
|
|
# Since: 6.2
|
|
##
|
|
{ 'enum': 'SevGuestType',
|
|
'data': [ 'sev', 'sev-snp' ],
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @SevGuestInfo:
|
|
#
|
|
# Information specific to legacy SEV/SEV-ES guests.
|
|
#
|
|
# @policy: SEV policy value
|
|
#
|
|
# @handle: SEV firmware handle
|
|
#
|
|
# Since: 2.12
|
|
##
|
|
{ 'struct': 'SevGuestInfo',
|
|
'data': { 'policy': 'uint32',
|
|
'handle': 'uint32' },
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @SevSnpGuestInfo:
|
|
#
|
|
# Information specific to SEV-SNP guests.
|
|
#
|
|
# @snp-policy: SEV-SNP policy value
|
|
#
|
|
# Since: 9.1
|
|
##
|
|
{ 'struct': 'SevSnpGuestInfo',
|
|
'data': { 'snp-policy': 'uint64' },
|
|
'if': '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
|
|
#
|
|
# @state: SEV guest state
|
|
#
|
|
# @sev-type: Type of SEV guest being run
|
|
#
|
|
# Since: 2.12
|
|
##
|
|
{ 'union': 'SevInfo',
|
|
'base': { 'enabled': 'bool',
|
|
'api-major': 'uint8',
|
|
'api-minor' : 'uint8',
|
|
'build-id' : 'uint8',
|
|
'state' : 'SevState',
|
|
'sev-type' : 'SevGuestType' },
|
|
'discriminator': 'sev-type',
|
|
'data': {
|
|
'sev': 'SevGuestInfo',
|
|
'sev-snp': 'SevSnpGuestInfo' },
|
|
'if': 'TARGET_I386' }
|
|
|
|
|
|
##
|
|
# @query-sev:
|
|
#
|
|
# Returns information about SEV
|
|
#
|
|
# Returns: @SevInfo
|
|
#
|
|
# Since: 2.12
|
|
#
|
|
# .. qmp-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': 'TARGET_I386' }
|
|
|
|
##
|
|
# @SevLaunchMeasureInfo:
|
|
#
|
|
# SEV Guest Launch measurement information
|
|
#
|
|
# @data: the measurement value encoded in base64
|
|
#
|
|
# Since: 2.12
|
|
##
|
|
{ 'struct': 'SevLaunchMeasureInfo', 'data': {'data': 'str'},
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @query-sev-launch-measure:
|
|
#
|
|
# Query the SEV guest launch information.
|
|
#
|
|
# Returns: The @SevLaunchMeasureInfo for the guest
|
|
#
|
|
# Since: 2.12
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "query-sev-launch-measure" }
|
|
# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
|
|
##
|
|
{ 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo',
|
|
'if': '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)
|
|
#
|
|
# @cpu0-id: Unique ID of CPU0 (base64 encoded) (since 7.1)
|
|
#
|
|
# @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',
|
|
'cpu0-id': 'str',
|
|
'cbitpos': 'int',
|
|
'reduced-phys-bits': 'int'},
|
|
'if': '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
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "query-sev-capabilities" }
|
|
# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
|
|
# "cpu0-id": "2lvmGwo+...61iEinw==",
|
|
# "cbitpos": 47, "reduced-phys-bits": 1}}
|
|
##
|
|
{ 'command': 'query-sev-capabilities', 'returns': 'SevCapability',
|
|
'if': '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': 'TARGET_I386' }
|
|
|
|
##
|
|
# @SevAttestationReport:
|
|
#
|
|
# The struct describes attestation report for a Secure Encrypted
|
|
# Virtualization feature.
|
|
#
|
|
# @data: guest attestation report (base64 encoded)
|
|
#
|
|
# Since: 6.1
|
|
##
|
|
{ 'struct': 'SevAttestationReport',
|
|
'data': { 'data': 'str'},
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @query-sev-attestation-report:
|
|
#
|
|
# This command is used to get the SEV attestation report, and is
|
|
# supported on AMD X86 platforms only.
|
|
#
|
|
# @mnonce: a random 16 bytes value encoded in base64 (it will be
|
|
# included in report)
|
|
#
|
|
# Returns: SevAttestationReport objects.
|
|
#
|
|
# Since: 6.1
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute" : "query-sev-attestation-report",
|
|
# "arguments": { "mnonce": "aaaaaaa" } }
|
|
# <- { "return" : { "data": "aaaaaaaabbbddddd"} }
|
|
##
|
|
{ 'command': 'query-sev-attestation-report',
|
|
'data': { 'mnonce': 'str' },
|
|
'returns': 'SevAttestationReport',
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @dump-skeys:
|
|
#
|
|
# Dump guest's storage keys
|
|
#
|
|
# @filename: the path to the file to dump to
|
|
#
|
|
# Since: 2.5
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "dump-skeys",
|
|
# "arguments": { "filename": "/tmp/skeys" } }
|
|
# <- { "return": {} }
|
|
##
|
|
{ 'command': 'dump-skeys',
|
|
'data': { 'filename': 'str' },
|
|
'if': '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': '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
|
|
#
|
|
# .. qmp-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': 'TARGET_ARM' }
|
|
|
|
##
|
|
# @SGXEPCSection:
|
|
#
|
|
# Information about intel SGX EPC section info
|
|
#
|
|
# @node: the numa node
|
|
#
|
|
# @size: the size of EPC section
|
|
#
|
|
# Since: 7.0
|
|
##
|
|
{ 'struct': 'SGXEPCSection',
|
|
'data': { 'node': 'int',
|
|
'size': 'uint64'}}
|
|
|
|
##
|
|
# @SGXInfo:
|
|
#
|
|
# Information about intel Safe Guard eXtension (SGX) support
|
|
#
|
|
# @sgx: true if SGX is supported
|
|
#
|
|
# @sgx1: true if SGX1 is supported
|
|
#
|
|
# @sgx2: true if SGX2 is supported
|
|
#
|
|
# @flc: true if FLC is supported
|
|
#
|
|
# @sections: The EPC sections info for guest (Since: 7.0)
|
|
#
|
|
# Since: 6.2
|
|
##
|
|
{ 'struct': 'SGXInfo',
|
|
'data': { 'sgx': 'bool',
|
|
'sgx1': 'bool',
|
|
'sgx2': 'bool',
|
|
'flc': 'bool',
|
|
'sections': ['SGXEPCSection']},
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @query-sgx:
|
|
#
|
|
# Returns information about SGX
|
|
#
|
|
# Returns: @SGXInfo
|
|
#
|
|
# Since: 6.2
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "query-sgx" }
|
|
# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
|
|
# "flc": true,
|
|
# "sections": [{"node": 0, "size": 67108864},
|
|
# {"node": 1, "size": 29360128}]} }
|
|
##
|
|
{ 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @query-sgx-capabilities:
|
|
#
|
|
# Returns information from host SGX capabilities
|
|
#
|
|
# Returns: @SGXInfo
|
|
#
|
|
# Since: 6.2
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "query-sgx-capabilities" }
|
|
# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
|
|
# "flc": true,
|
|
# "section" : [{"node": 0, "size": 67108864},
|
|
# {"node": 1, "size": 29360128}]} }
|
|
##
|
|
{ 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
|
|
|
|
|
|
##
|
|
# @EvtchnPortType:
|
|
#
|
|
# An enumeration of Xen event channel port types.
|
|
#
|
|
# @closed: The port is unused.
|
|
#
|
|
# @unbound: The port is allocated and ready to be bound.
|
|
#
|
|
# @interdomain: The port is connected as an interdomain interrupt.
|
|
#
|
|
# @pirq: The port is bound to a physical IRQ (PIRQ).
|
|
#
|
|
# @virq: The port is bound to a virtual IRQ (VIRQ).
|
|
#
|
|
# @ipi: The post is an inter-processor interrupt (IPI).
|
|
#
|
|
# Since: 8.0
|
|
##
|
|
{ 'enum': 'EvtchnPortType',
|
|
'data': ['closed', 'unbound', 'interdomain', 'pirq', 'virq', 'ipi'],
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @EvtchnInfo:
|
|
#
|
|
# Information about a Xen event channel port
|
|
#
|
|
# @port: the port number
|
|
#
|
|
# @vcpu: target vCPU for this port
|
|
#
|
|
# @type: the port type
|
|
#
|
|
# @remote-domain: remote domain for interdomain ports
|
|
#
|
|
# @target: remote port ID, or virq/pirq number
|
|
#
|
|
# @pending: port is currently active pending delivery
|
|
#
|
|
# @masked: port is masked
|
|
#
|
|
# Since: 8.0
|
|
##
|
|
{ 'struct': 'EvtchnInfo',
|
|
'data': {'port': 'uint16',
|
|
'vcpu': 'uint32',
|
|
'type': 'EvtchnPortType',
|
|
'remote-domain': 'str',
|
|
'target': 'uint16',
|
|
'pending': 'bool',
|
|
'masked': 'bool'},
|
|
'if': 'TARGET_I386' }
|
|
|
|
|
|
##
|
|
# @xen-event-list:
|
|
#
|
|
# Query the Xen event channels opened by the guest.
|
|
#
|
|
# Returns: list of open event channel ports.
|
|
#
|
|
# Since: 8.0
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "xen-event-list" }
|
|
# <- { "return": [
|
|
# {
|
|
# "pending": false,
|
|
# "port": 1,
|
|
# "vcpu": 1,
|
|
# "remote-domain": "qemu",
|
|
# "masked": false,
|
|
# "type": "interdomain",
|
|
# "target": 1
|
|
# },
|
|
# {
|
|
# "pending": false,
|
|
# "port": 2,
|
|
# "vcpu": 0,
|
|
# "remote-domain": "",
|
|
# "masked": false,
|
|
# "type": "virq",
|
|
# "target": 0
|
|
# }
|
|
# ]
|
|
# }
|
|
##
|
|
{ 'command': 'xen-event-list',
|
|
'returns': ['EvtchnInfo'],
|
|
'if': 'TARGET_I386' }
|
|
|
|
##
|
|
# @xen-event-inject:
|
|
#
|
|
# Inject a Xen event channel port (interrupt) to the guest.
|
|
#
|
|
# @port: The port number
|
|
#
|
|
# Since: 8.0
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
|
|
# <- { "return": { } }
|
|
##
|
|
{ 'command': 'xen-event-inject',
|
|
'data': { 'port': 'uint32' },
|
|
'if': 'TARGET_I386' }
|