fridtjof/qemu-cr16
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

QAPI patches for 2025-11-04

Browse source 
-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmkJ9+kSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZT3iwP/0t5o3xciGFgElQ+b/+5zv+tveUMHgec
 DXJk5gVrk5jS66QB9vxPkq6II1eunqP83KnxsaNi4D1b68+yrMj45amKpUKXV/Am
 GW8LJt1FTfbNhf7dLmXZ5K5q6unTqnyJdSjpCXqvAQ6yJVa3yG2U4TsRz6ZkFrEa
 gRluVAM0YGys30FXWOJ5bS4JB7VKAXIUzYQjvGRugdCdSTbs3VU/235KAQ87cK4H
 TRb0jTMdah8K+CmXBZLduxRTKaFqho/+hNBBlX23jgSdgNwsTcDPbz4ZaeSrVFEU
 frwKX5v4EwebyOFAzTlhRFGtENvDPCQNHIw3LpSseHCQeeWGulcymAintBty32A2
 3CcK/7mgRC3ElvNpE0hYw910M3Cg0OVPOgME2NzuRKRiJ86mHgn/a90dLsKugNH7
 +v9bCzzeTHRtzgeyBC7oQ3omEpLxXGSD+MAzRR0iLY+f01ynQ+g2NorJsdELfY4S
 +A2sEq9+YnvoCbu3cMob5KaNyeKe6B4rjeo3Evketm+hdiaxuqLXcUuE6mgzAXDP
 s7n6JR2Li2cnzP/3RLWAHFNwqjaMUUd4gdhfTxTyiJsB/qTkGQsulK3iJX2EXQRI
 Me99IJsV78gLR/pFbeYOqCW7ySlx7+ykcAMyqc+4RaF3g72E05p+oncYTs9rmpBS
 UOy/PN3a7PP4
 =ub6L
 -----END PGP SIGNATURE-----

Merge tag 'pull-qapi-2025-11-04' of https://repo.or.cz/qemu/armbru into staging

QAPI patches for 2025-11-04

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmkJ9+kSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZT3iwP/0t5o3xciGFgElQ+b/+5zv+tveUMHgec
# DXJk5gVrk5jS66QB9vxPkq6II1eunqP83KnxsaNi4D1b68+yrMj45amKpUKXV/Am
# GW8LJt1FTfbNhf7dLmXZ5K5q6unTqnyJdSjpCXqvAQ6yJVa3yG2U4TsRz6ZkFrEa
# gRluVAM0YGys30FXWOJ5bS4JB7VKAXIUzYQjvGRugdCdSTbs3VU/235KAQ87cK4H
# TRb0jTMdah8K+CmXBZLduxRTKaFqho/+hNBBlX23jgSdgNwsTcDPbz4ZaeSrVFEU
# frwKX5v4EwebyOFAzTlhRFGtENvDPCQNHIw3LpSseHCQeeWGulcymAintBty32A2
# 3CcK/7mgRC3ElvNpE0hYw910M3Cg0OVPOgME2NzuRKRiJ86mHgn/a90dLsKugNH7
# +v9bCzzeTHRtzgeyBC7oQ3omEpLxXGSD+MAzRR0iLY+f01ynQ+g2NorJsdELfY4S
# +A2sEq9+YnvoCbu3cMob5KaNyeKe6B4rjeo3Evketm+hdiaxuqLXcUuE6mgzAXDP
# s7n6JR2Li2cnzP/3RLWAHFNwqjaMUUd4gdhfTxTyiJsB/qTkGQsulK3iJX2EXQRI
# Me99IJsV78gLR/pFbeYOqCW7ySlx7+ykcAMyqc+4RaF3g72E05p+oncYTs9rmpBS
# UOy/PN3a7PP4
# =ub6L
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 04 Nov 2025 01:56:09 PM CET
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [unknown]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [unknown]
# gpg: WARNING: The key's User ID is not certified with a trusted signature!
# gpg:          There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2025-11-04' of https://repo.or.cz/qemu/armbru:
  qapi: Add documentation format validation
  docs/interop: Add test to keep vhost-user.json sane
  docs/interop/firmware: Literal block markup
  docs/interop/vhost-user: Belatedly convert "Example" section
  docs/interop: Refill QAPI doc comments to conform to conventions
  qga/qapi-schema: Clean up whitespace between definitions
  qga/qapi-schema: Refill doc comments to conform to conventions
  qapi: Clean up whitespace between definitions
  qapi: Refill doc comments to conform to conventions
  qapi/audio: Fix description markup of AudiodevDBusOptions @nsamples
  meson: Add missing backends.py to qapi_gen_depends
  qapi/command: Avoid generating unused qmp_marshal_output_T()

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
This commit is contained in:
Richard Henderson 2025-11-05 08:54:57 +01:00
commit d752763d0b
38 changed files with 710 additions and 630 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/devel/qapi-code-gen.rst
View file

@ -1809,27 +1809,13 @@ Example::
$ cat qapi-generated/example-qapi-commands.c
[Uninteresting stuff omitted...]
static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in,
QObject **ret_out, Error **errp)
{
Visitor *v;
v = qobject_output_visitor_new_qmp(ret_out);
if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) {
visit_complete(v, ret_out);
}
visit_free(v);
v = qapi_dealloc_visitor_new();
visit_type_UserDefOne(v, "unused", &ret_in, NULL);
visit_free(v);
}
void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp)
{
Error *err = NULL;
bool ok = false;
Visitor *v;
UserDefOne *retval;
Visitor *ov;
q_obj_my_command_arg arg = {0};
v = qobject_input_visitor_new_qmp(QOBJECT(args));
@ -1857,7 +1843,14 @@ Example::
goto out;
}
qmp_marshal_output_UserDefOne(retval, ret, errp);
ov = qobject_output_visitor_new_qmp(ret);
if (visit_type_UserDefOne(ov, "unused", &retval, errp)) {
visit_complete(ov, ret);
}
visit_free(ov);
ov = qapi_dealloc_visitor_new();
visit_type_UserDefOne(ov, "unused", &retval, NULL);
visit_free(ov);
if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) {
g_autoptr(GString) ret_json = qobject_to_json(*ret);

454
docs/interop/firmware.json
View file

@ -27,18 +27,18 @@
# Lists the firmware-OS interface types provided by various firmware
# that is commonly used with QEMU virtual machines.
#
# @bios: Traditional x86 BIOS interface. For example, firmware built
# from the SeaBIOS project usually provides this interface.
# @bios: Traditional x86 BIOS interface. For example, firmware built
# from the SeaBIOS project usually provides this interface.
#
# @openfirmware: The interface is defined by the (historical) IEEE
# 1275-1994 standard. Examples for firmware projects that
# provide this interface are: OpenBIOS and SLOF.
# 1275-1994 standard. Examples for firmware projects that provide
# this interface are: OpenBIOS and SLOF.
#
# @uboot: Firmware interface defined by the U-Boot project.
#
# @uefi: Firmware interface defined by the UEFI specification. For
# example, firmware built from the edk2 (EFI Development Kit II)
# project usually provides this interface.
# @uefi: Firmware interface defined by the UEFI specification. For
# example, firmware built from the edk2 (EFI Development Kit II)
# project usually provides this interface.
#
# Since: 3.0
##
@ -50,21 +50,21 @@
#
# Defines the device types that firmware can be mapped into.
#
# @flash: The firmware executable and its accompanying NVRAM file are to
# be mapped into a pflash chip each.
# @flash: The firmware executable and its accompanying NVRAM file are
# to be mapped into a pflash chip each.
#
# @kernel: The firmware is to be loaded like a Linux kernel. This is
# similar to @memory but may imply additional processing that
# is specific to the target architecture and machine type.
# @kernel: The firmware is to be loaded like a Linux kernel. This is
# similar to @memory but may imply additional processing that is
# specific to the target architecture and machine type.
#
# @memory: The firmware is to be mapped into memory.
#
# @igvm: The firmware is defined by a file conforming to the IGVM
# specification and mapped into memory according to directives
# defined in the file. This is similar to @memory but may
# include additional processing defined by the IGVM file
# including initial CPU state or population of metadata into
# the guest address space. Since: 10.1
# specification and mapped into memory according to directives
# defined in the file. This is similar to @memory but may include
# additional processing defined by the IGVM file including initial
# CPU state or population of metadata into the guest address
# space. Since: 10.1
#
# Since: 3.0
##
@ -74,8 +74,8 @@
##
# @FirmwareArchitecture:
#
# Enumeration of architectures for which Qemu uses additional
# firmware files.
# Enumeration of architectures for which Qemu uses additional firmware
# files.
#
# @aarch64: 64-bit Arm.
#
@ -83,7 +83,7 @@
#
# @i386: 32-bit x86.
#
# @loongarch64: 64-bit LoongArch. (since: 7.1)
# @loongarch64: 64-bit LoongArch. (since: 7.1)
#
# @riscv64: 64-bit RISC-V.
#
@ -100,17 +100,16 @@
# Defines the machine types that firmware may execute on.
#
# @architecture: Determines the emulation target (the QEMU system
# emulator) that can execute the firmware.
# emulator) that can execute the firmware.
#
# @machines: Lists the machine types (known by the emulator that is
# specified through @architecture) that can execute the
# firmware. Elements of @machines are supposed to be concrete
# machine types, not aliases. Glob patterns are understood,
# which is especially useful for versioned machine types.
# (For example, the glob pattern "pc-i440fx-*" matches
# "pc-i440fx-2.12".) On the QEMU command line, "-machine
# type=..." specifies the requested machine type (but that
# option does not accept glob patterns).
# specified through @architecture) that can execute the firmware.
# Elements of @machines are supposed to be concrete machine types,
# not aliases. Glob patterns are understood, which is especially
# useful for versioned machine types. (For example, the glob
# pattern "pc-i440fx-*" matches "pc-i440fx-2.12".) On the QEMU
# command line, "-machine type=..." specifies the requested
# machine type (but that option does not accept glob patterns).
#
# Since: 3.0
##
@ -124,115 +123,104 @@
# Defines the features that firmware may support, and the platform
# requirements that firmware may present.
#
# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined
# in the ACPI specification. On the "pc-i440fx-*" machine
# types of the @i386 and @x86_64 emulation targets, S3 can be
# enabled with "-global PIIX4_PM.disable_s3=0" and disabled
# with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*"
# machine types of the @i386 and @x86_64 emulation targets, S3
# can be enabled with "-global ICH9-LPC.disable_s3=0" and
# disabled with "-global ICH9-LPC.disable_s3=1".
# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as
# defined in the ACPI specification. On the "pc-i440fx-*" machine
# types of the @i386 and @x86_64 emulation targets, S3 can be
# enabled with "-global PIIX4_PM.disable_s3=0" and disabled with
# "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*" machine
# types of the @i386 and @x86_64 emulation targets, S3 can be
# enabled with "-global ICH9-LPC.disable_s3=0" and disabled with
# "-global ICH9-LPC.disable_s3=1".
#
# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as
# defined in the ACPI specification. On the "pc-i440fx-*"
# machine types of the @i386 and @x86_64 emulation targets, S4
# can be enabled with "-global PIIX4_PM.disable_s4=0" and
# disabled with "-global PIIX4_PM.disable_s4=1". On the
# "pc-q35-*" machine types of the @i386 and @x86_64 emulation
# targets, S4 can be enabled with "-global
# ICH9-LPC.disable_s4=0" and disabled with "-global
# ICH9-LPC.disable_s4=1".
# defined in the ACPI specification. On the "pc-i440fx-*" machine
# types of the @i386 and @x86_64 emulation targets, S4 can be
# enabled with "-global PIIX4_PM.disable_s4=0" and disabled with
# "-global PIIX4_PM.disable_s4=1". On the "pc-q35-*" machine
# types of the @i386 and @x86_64 emulation targets, S4 can be
# enabled with "-global ICH9-LPC.disable_s4=0" and disabled with
# "-global ICH9-LPC.disable_s4=1".
#
# @amd-sev: The firmware supports running under AMD Secure Encrypted
# Virtualization, as specified in the AMD64 Architecture
# Programmer's Manual. QEMU command line options related to
# this feature are documented in
# "docs/system/i386/amd-memory-encryption.rst".
# Virtualization, as specified in the AMD64 Architecture
# Programmer's Manual. QEMU command line options related to this
# feature are documented in
# "docs/system/i386/amd-memory-encryption.rst".
#
# @amd-sev-es: The firmware supports running under AMD Secure Encrypted
# Virtualization - Encrypted State, as specified in the AMD64
# Architecture Programmer's Manual. QEMU command line options
# related to this feature are documented in
# "docs/system/i386/amd-memory-encryption.rst".
# @amd-sev-es: The firmware supports running under AMD Secure
# Encrypted Virtualization - Encrypted State, as specified in the
# AMD64 Architecture Programmer's Manual. QEMU command line
# options related to this feature are documented in
# "docs/system/i386/amd-memory-encryption.rst".
#
# @amd-sev-snp: The firmware supports running under AMD Secure Encrypted
# Virtualization - Secure Nested Paging, as specified in the
# AMD64 Architecture Programmer's Manual. QEMU command line
# options related to this feature are documented in
# "docs/system/i386/amd-memory-encryption.rst".
# @amd-sev-snp: The firmware supports running under AMD Secure
# Encrypted Virtualization - Secure Nested Paging, as specified in
# the AMD64 Architecture Programmer's Manual. QEMU command line
# options related to this feature are documented in
# "docs/system/i386/amd-memory-encryption.rst".
#
# @intel-tdx: The firmware supports running under Intel Trust Domain
# Extensions (TDX).
# Extensions (TDX).
#
# @enrolled-keys: The variable store (NVRAM) template associated with
# the firmware binary has the UEFI Secure Boot
# operational mode turned on, with certificates
# enrolled.
# the firmware binary has the UEFI Secure Boot operational mode
# turned on, with certificates enrolled.
#
# @requires-smm: The firmware requires the platform to emulate SMM
# (System Management Mode), as defined in the AMD64
# Architecture Programmer's Manual, and in the Intel(R)64
# and IA-32 Architectures Software Developer's Manual. On
# the "pc-q35-*" machine types of the @i386 and @x86_64
# emulation targets, SMM emulation can be enabled with
# "-machine smm=on". (On the "pc-q35-*" machine types of
# the @i386 emulation target, @requires-smm presents
# further CPU requirements; one combination known to work
# is "-cpu coreduo,nx=off".) If the firmware is marked as
# both @secure-boot and @requires-smm, then write
# accesses to the pflash chip (NVRAM) that holds the UEFI
# variable store must be restricted to code that executes
# in SMM, using the additional option "-global
# driver=cfi.pflash01,property=secure,value=on".
# Furthermore, a large guest-physical address space
# (comprising guest RAM, memory hotplug range, and 64-bit
# PCI MMIO aperture), and/or a high VCPU count, may
# present high SMRAM requirements from the firmware. On
# the "pc-q35-*" machine types of the @i386 and @x86_64
# emulation targets, the SMRAM size may be increased
# above the default 16MB with the "-global
# mch.extended-tseg-mbytes=uint16" option. As a rule of
# thumb, the default 16MB size suffices for 1TB of
# guest-phys address space and a few tens of VCPUs; for
# every further TB of guest-phys address space, add 8MB
# of SMRAM. 48MB should suffice for 4TB of guest-phys
# address space and 2-3 hundred VCPUs.
# (System Management Mode), as defined in the AMD64 Architecture
# Programmer's Manual, and in the Intel(R)64 and IA-32
# Architectures Software Developer's Manual. On the "pc-q35-*"
# machine types of the @i386 and @x86_64 emulation targets, SMM
# emulation can be enabled with "-machine smm=on". (On the
# "pc-q35-*" machine types of the @i386 emulation target,
# @requires-smm presents further CPU requirements; one combination
# known to work is "-cpu coreduo,nx=off".) If the firmware is
# marked as both @secure-boot and @requires-smm, then write
# accesses to the pflash chip (NVRAM) that holds the UEFI variable
# store must be restricted to code that executes in SMM, using the
# additional option "-global
# driver=cfi.pflash01,property=secure,value=on". Furthermore, a
# large guest-physical address space (comprising guest RAM, memory
# hotplug range, and 64-bit PCI MMIO aperture), and/or a high VCPU
# count, may present high SMRAM requirements from the firmware.
# On the "pc-q35-*" machine types of the @i386 and @x86_64
# emulation targets, the SMRAM size may be increased above the
# default 16MB with the "-global mch.extended-tseg-mbytes=uint16"
# option. As a rule of thumb, the default 16MB size suffices for
# 1TB of guest-phys address space and a few tens of VCPUs; for
# every further TB of guest-phys address space, add 8MB of SMRAM.
# 48MB should suffice for 4TB of guest-phys address space and 2-3
# hundred VCPUs.
#
# @secure-boot: The firmware implements the software interfaces for UEFI
# Secure Boot, as defined in the UEFI specification. Note
# that without @requires-smm, guest code running with
# kernel privileges can undermine the security of Secure
# Boot.
# @secure-boot: The firmware implements the software interfaces for
# UEFI Secure Boot, as defined in the UEFI specification. Note
# that without @requires-smm, guest code running with kernel
# privileges can undermine the security of Secure Boot.
#
# @verbose-dynamic: When firmware log capture is enabled, the firmware
# logs a large amount of debug messages, which may
# impact boot performance. With log capture disabled,
# there is no boot performance impact. On the
# "pc-i440fx-*" and "pc-q35-*" machine types of the
# @i386 and @x86_64 emulation targets, firmware log
# capture can be enabled with the QEMU command line
# options "-chardev file,id=fwdebug,path=LOGFILEPATH
# -device isa-debugcon,iobase=0x402,chardev=fwdebug".
# @verbose-dynamic is mutually exclusive with
# @verbose-static.
# logs a large amount of debug messages, which may impact boot
# performance. With log capture disabled, there is no boot
# performance impact. On the "pc-i440fx-*" and "pc-q35-*" machine
# types of the @i386 and @x86_64 emulation targets, firmware log
# capture can be enabled with the QEMU command line options
# "-chardev file,id=fwdebug,path=LOGFILEPATH -device
# isa-debugcon,iobase=0x402,chardev=fwdebug". @verbose-dynamic is
# mutually exclusive with @verbose-static.
#
# @verbose-static: The firmware unconditionally produces a large amount
# of debug messages, which may impact boot performance.
# This feature may typically be carried by certain UEFI
# firmware for the "virt-*" machine types of the @arm
# and @aarch64 emulation targets, where the debug
# messages are written to the first (always present)
# PL011 UART. @verbose-static is mutually exclusive
# with @verbose-dynamic.
# @verbose-static: The firmware unconditionally produces a large
# amount of debug messages, which may impact boot performance.
# This feature may typically be carried by certain UEFI firmware
# for the "virt-*" machine types of the @arm and @aarch64
# emulation targets, where the debug messages are written to the
# first (always present) PL011 UART. @verbose-static is mutually
# exclusive with @verbose-dynamic.
#
# @host-uefi-vars: The firmware expects the host to provide an uefi
# variable store. qemu supports that via
# "uefi-vars-sysbus" (aarch64, riscv64, loongarch64)
# or "uefi-vars-x64" (x86_64) devices. The firmware
# will not use flash for nvram. When loading the
# firmware into flash the 'stateless' setup should be
# used. It is recommened to load the firmware into
# memory though.
# variable store. qemu supports that via "uefi-vars-sysbus"
# (aarch64, riscv64, loongarch64) or "uefi-vars-x64" (x86_64)
# devices. The firmware will not use flash for nvram. When
# loading the firmware into flash the 'stateless' setup should be
# used. It is recommened to load the firmware into memory though.
#
# Since: 3.0
##
@ -262,16 +250,16 @@
# @FirmwareFlashFile:
#
# Defines common properties that are necessary for loading a firmware
# file into a pflash chip. The corresponding QEMU command line option is
# "-drive file=@filename,format=@format". Note however that the
# file into a pflash chip. The corresponding QEMU command line option
# is "-drive file=@filename,format=@format". Note however that the
# option-argument shown here is incomplete; it is completed under
# @FirmwareMappingFlash.
#
# @filename: Specifies the filename on the host filesystem where the
# firmware file can be found.
# firmware file can be found.
#
# @format: Specifies the block format of the file pointed-to by
# @filename, such as @raw or @qcow2.
# @filename, such as @raw or @qcow2.
#
# Since: 3.0
##
@ -286,22 +274,20 @@
# Describes how the firmware build handles code versus variable
# persistence.
#
# @split: the executable file contains code while the NVRAM
# template provides variable storage. The executable
# must be configured read-only and can be shared between
# multiple guests. The NVRAM template must be cloned
# for each new guest and configured read-write.
# @split: the executable file contains code while the NVRAM template
# provides variable storage. The executable must be configured
# read-only and can be shared between multiple guests. The NVRAM
# template must be cloned for each new guest and configured
# read-write.
#
# @combined: the executable file contains both code and
# variable storage. The executable must be cloned
# for each new guest and configured read-write.
# No NVRAM template will be specified.
# @combined: the executable file contains both code and variable
# storage. The executable must be cloned for each new guest and
# configured read-write. No NVRAM template will be specified.
#
# @stateless: the executable file contains code and variable
# storage is not persisted. The executable must
# be configured read-only and can be shared
# between multiple guests. No NVRAM template
# will be specified.
# @stateless: the executable file contains code and variable storage
# is not persisted. The executable must be configured read-only
# and can be shared between multiple guests. No NVRAM template
# will be specified.
#
# Since: 7.0.0
##
@ -315,39 +301,50 @@
# and its accompanying NVRAM file, when @FirmwareDevice is @flash.
#
# @mode: Describes how the firmware build handles code versus variable
# storage. If not present, it must be treated as if it was
# configured with value @split. Since: 7.0.0
# storage. If not present, it must be treated as if it was
# configured with value @split. Since: 7.0.0
#
# @executable: Identifies the firmware executable. The @mode
# indicates whether there will be an associated
# NVRAM template present. The preferred
# corresponding QEMU command line options are
# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
# -machine pflash0=pflash0
# or equivalent -blockdev instead of -drive. When
# @mode is @combined the executable must be
# cloned before use and configured with readonly=off.
# With QEMU versions older than 4.0, you have to use
# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
# @executable: Identifies the firmware executable. The @mode
# indicates whether there will be an associated NVRAM template
# present. The preferred corresponding QEMU command line options
# are
#
# ::
#
# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
# -machine pflash0=pflash0
#
# or equivalent -blockdev instead of -drive. When @mode is
# @combined the executable must be cloned before use and
# configured with readonly=off. With QEMU versions older than
# 4.0, you have to use
#
# ::
#
# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
#
# @nvram-template: Identifies the NVRAM template compatible with
# @executable, when @mode is set to @split,
# otherwise it should not be present.
# Management software instantiates an
# individual copy -- a specific NVRAM file -- from
# @nvram-template.@filename for each new virtual
# machine definition created. @nvram-template.@filename
# itself is never mapped into virtual machines, only
# individual copies of it are. An NVRAM file is
# typically used for persistently storing the
# non-volatile UEFI variables of a virtual machine
# definition. The preferred corresponding QEMU
# command line options are
# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
# -machine pflash1=pflash1
# or equivalent -blockdev instead of -drive.
# With QEMU versions older than 4.0, you have to use
# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
# @executable, when @mode is set to @split, otherwise it should
# not be present. Management software instantiates an individual
# copy -- a specific NVRAM file -- from @nvram-template.@filename
# for each new virtual machine definition created.
# @nvram-template.@filename itself is never mapped into virtual
# machines, only individual copies of it are. An NVRAM file is
# typically used for persistently storing the non-volatile UEFI
# variables of a virtual machine definition. The preferred
# corresponding QEMU command line options are
#
# ::
#
# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
# -machine pflash1=pflash1
#
# or equivalent -blockdev instead of -drive. With QEMU versions
# older than 4.0, you have to use
#
# ::
#
# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
#
# Since: 3.0
##
@ -359,13 +356,13 @@
##
# @FirmwareMappingKernel:
#
# Describes loading and mapping properties for the firmware executable,
# when @FirmwareDevice is @kernel.
# Describes loading and mapping properties for the firmware
# executable, when @FirmwareDevice is @kernel.
#
# @filename: Identifies the firmware executable. The firmware executable
# may be shared by multiple virtual machine definitions. The
# corresponding QEMU command line option is "-kernel
# @filename".
# @filename: Identifies the firmware executable. The firmware
# executable may be shared by multiple virtual machine
# definitions. The corresponding QEMU command line option is
# "-kernel @filename".
#
# Since: 3.0
##
@ -375,13 +372,13 @@
##
# @FirmwareMappingMemory:
#
# Describes loading and mapping properties for the firmware executable,
# when @FirmwareDevice is @memory.
# Describes loading and mapping properties for the firmware
# executable, when @FirmwareDevice is @memory.
#
# @filename: Identifies the firmware executable. The firmware executable
# may be shared by multiple virtual machine definitions. The
# corresponding QEMU command line option is "-bios
# @filename".
# @filename: Identifies the firmware executable. The firmware
# executable may be shared by multiple virtual machine
# definitions. The corresponding QEMU command line option is
# "-bios @filename".
#
# Since: 3.0
##
@ -391,15 +388,15 @@
##
# @FirmwareMappingIgvm:
#
# Describes loading and mapping properties for the firmware executable,
# when @FirmwareDevice is @igvm.
# Describes loading and mapping properties for the firmware
# executable, when @FirmwareDevice is @igvm.
#
# @filename: Identifies the IGVM file containing the firmware executable
# along with other information used to configure the initial
# state of the guest. The IGVM file may be shared by multiple
# virtual machine definitions. This corresponds to creating
# an object on the command line with "-object igvm-cfg,
# file=@filename".
# @filename: Identifies the IGVM file containing the firmware
# executable along with other information used to configure the
# initial state of the guest. The IGVM file may be shared by
# multiple virtual machine definitions. This corresponds to
# creating an object on the command line with "-object igvm-cfg,
# file=@filename".
#
# Since: 10.1
##
@ -413,7 +410,7 @@
# loading / mapping properties.
#
# @device: Selects the device type that the firmware must be mapped
# into.
# into.
#
# Since: 3.0
##
@ -428,46 +425,49 @@
##
# @Firmware:
#
# Describes a firmware (or a firmware use case) to management software.
# Describes a firmware (or a firmware use case) to management
# software.
#
# It is possible for multiple @Firmware elements to match the search
# criteria of management software. Applications thus need rules to pick
# one of the many matches, and users need the ability to override distro
# defaults.
# criteria of management software. Applications thus need rules to
# pick one of the many matches, and users need the ability to override
# distro defaults.
#
# It is recommended to create firmware JSON files (each containing a
# single @Firmware root element) with a double-digit prefix, for example
# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
# predictable order. The firmware JSON files should be searched for in
# three directories:
# single @Firmware root element) with a double-digit prefix, for
# example "50-ovmf.json", "50-seabios-256k.json", etc, so they can be
# sorted in predictable order. The firmware JSON files should be
# searched for in three directories:
#
# - /usr/share/qemu/firmware -- populated by distro-provided firmware
# packages (XDG_DATA_DIRS covers
# /usr/share by default),
# - /usr/share/qemu/firmware -- populated by distro-provided firmware
# packages (XDG_DATA_DIRS covers
# /usr/share by default),
#
# - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
# - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
#
# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
# additions (XDG_CONFIG_HOME
# defaults to $HOME/.config).
# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
# additions (XDG_CONFIG_HOME
# defaults to $HOME/.config).
#
# Top-down, the list of directories goes from general to specific.
#
# Management software should build a list of files from all three
# locations, then sort the list by filename (i.e., last pathname
# component). Management software should choose the first JSON file on
# the sorted list that matches the search criteria. If a more specific
# directory has a file with same name as a less specific directory, then
# the file in the more specific directory takes effect. If the more
# specific file is zero length, it hides the less specific one.
# component). Management software should choose the first JSON file
# on the sorted list that matches the search criteria. If a more
# specific directory has a file with same name as a less specific
# directory, then the file in the more specific directory takes
# effect. If the more specific file is zero length, it hides the less
# specific one.
#
# For example, if a distro ships
#
# - /usr/share/qemu/firmware/50-ovmf.json
# - /usr/share/qemu/firmware/50-ovmf.json
#
# - /usr/share/qemu/firmware/50-seabios-256k.json
# - /usr/share/qemu/firmware/50-seabios-256k.json
#
# then the sysadmin can prevent the default OVMF being used at all with
# then the sysadmin can prevent the default OVMF being used at all
# with
#
# $ touch /etc/qemu/firmware/50-ovmf.json
#
@ -484,29 +484,29 @@
# $ vim /etc/qemu/firmware/99-ovmf.json
#
# @description: Provides a human-readable description of the firmware.
# Management software may or may not display @description.
# Management software may or may not display @description.
#
# @interface-types: Lists the types of interfaces that the firmware can
# expose to the guest OS. This is a non-empty, ordered
# list; entries near the beginning of @interface-types
# are considered more native to the firmware, and/or
# to have a higher quality implementation in the
# firmware, than entries near the end of
# @interface-types.
# @interface-types: Lists the types of interfaces that the firmware
# can expose to the guest OS. This is a non-empty, ordered list;
# entries near the beginning of @interface-types are considered
# more native to the firmware, and/or to have a higher quality
# implementation in the firmware, than entries near the end of
# @interface-types.
#
# @mapping: Describes the loading / mapping properties of the firmware.
# @mapping: Describes the loading / mapping properties of the
# firmware.
#
# @targets: Collects the target architectures (QEMU system emulators)
# and their machine types that may execute the firmware.
# and their machine types that may execute the firmware.
#
# @features: Lists the features that the firmware supports, and the
# platform requirements it presents.
# platform requirements it presents.
#
# @tags: A list of auxiliary strings associated with the firmware for
# which @description is not appropriate, due to the latter's
# possible exposure to the end-user. @tags serves development and
# debugging purposes only, and management software shall
# explicitly ignore it.
# which @description is not appropriate, due to the latter's
# possible exposure to the end-user. @tags serves development and
# debugging purposes only, and management software shall
# explicitly ignore it.
#
# Since: 3.0
#

59
docs/interop/vhost-user.json
View file

@ -21,19 +21,33 @@
# List the various vhost user backend types.
#
# @9p: 9p virtio console
#
# @balloon: virtio balloon
#
# @block: virtio block
#
# @caif: virtio caif
#
# @console: virtio console
#
# @crypto: virtio crypto
#
# @gpu: virtio gpu
#
# @input: virtio input
#
# @net: virtio net
#
# @rng: virtio rng
#
# @rpmsg: virtio remote processor messaging
#
# @rproc-serial: virtio remoteproc serial link
#
# @scsi: virtio scsi
#
# @vsock: virtio vsock transport
#
# @fs: virtio fs (since 4.2)
#
# Since: 4.0
@ -65,6 +79,7 @@
# List of vhost user "block" features.
#
# @read-only: The --read-only command line option is supported.
#
# @blk-file: The --blk-file command line option is supported.
#
# Since: 5.0
@ -96,6 +111,7 @@
# List of vhost user "input" features.
#
# @evdev-path: The --evdev-path command line option is supported.
#
# @no-grab: The --no-grab command line option is supported.
#
# Since: 4.0
@ -127,6 +143,7 @@
# List of vhost user "gpu" features.
#
# @render-node: The --render-node command line option is supported.
#
# @virgl: The --virgl command line option is supported.
#
# Since: 4.0
@ -177,36 +194,39 @@
# Describes a vhost user backend to management software.
#
# It is possible for multiple @VhostUserBackend elements to match the
# search criteria of management software. Applications thus need rules
# to pick one of the many matches, and users need the ability to
# search criteria of management software. Applications thus need
# rules to pick one of the many matches, and users need the ability to
# override distro defaults.
#
# It is recommended to create vhost user backend JSON files (each
# containing a single @VhostUserBackend root element) with a
# double-digit prefix, for example "50-qemu-gpu.json",
# "50-crosvm-gpu.json", etc, so they can be sorted in predictable
# order. The backend JSON files should be searched for in three
# order. The backend JSON files should be searched for in three
# directories:
#
# - /usr/share/qemu/vhost-user -- populated by distro-provided
# packages (XDG_DATA_DIRS covers
# /usr/share by default),
#
# - /etc/qemu/vhost-user -- exclusively for sysadmins' local additions,
# - /etc/qemu/vhost-user -- exclusively for sysadmins' local
# additions,
#
# - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user local
# additions (XDG_CONFIG_HOME
# defaults to $HOME/.config).
# - $XDG_CONFIG_HOME/qemu/vhost-user -- exclusively for per-user
# local additions
# (XDG_CONFIG_HOME defaults to
# $HOME/.config).
#
# Top-down, the list of directories goes from general to specific.
#
# Management software should build a list of files from all three
# locations, then sort the list by filename (i.e., basename
# component). Management software should choose the first JSON file on
# the sorted list that matches the search criteria. If a more specific
# directory has a file with same name as a less specific directory,
# then the file in the more specific directory takes effect. If the
# more specific file is zero length, it hides the less specific one.
# component). Management software should choose the first JSON file
# on the sorted list that matches the search criteria. If a more
# specific directory has a file with same name as a less specific
# directory, then the file in the more specific directory takes
# effect. If the more specific file is zero length, it hides the less
# specific one.
#
# For example, if a distro ships
#
@ -214,7 +234,8 @@
#
# - /usr/share/qemu/vhost-user/50-crosvm-gpu.json
#
# then the sysadmin can prevent the default QEMU GPU being used at all with
# then the sysadmin can prevent the default QEMU GPU being used at all
# with
#
# $ touch /etc/qemu/vhost-user/50-qemu-gpu.json
#
@ -233,19 +254,19 @@
# @type: The vhost user backend type.
#
# @description: Provides a human-readable description of the backend.
# Management software may or may not display @description.
# Management software may or may not display @description.
#
# @binary: Absolute path to the backend binary.
#
# @tags: An optional list of auxiliary strings associated with the
# backend for which @description is not appropriate, due to the
# latter's possible exposure to the end-user. @tags serves
# development and debugging purposes only, and management
# software shall explicitly ignore it.
# backend for which @description is not appropriate, due to the
# latter's possible exposure to the end-user. @tags serves
# development and debugging purposes only, and management software
# shall explicitly ignore it.
#
# Since: 4.0
#
# Example:
# .. qmp-example:
#
# {
# "description": "QEMU vhost-user-gpu",

9
docs/meson.build
View file

@ -99,7 +99,12 @@ if build_docs
alias_target('man', sphinxmans)
endif
test('QAPI firmware.json regression tests', qapi_gen,
args: ['-o', meson.current_build_dir() / 'qapi',
test('QAPI firmware.json regression test', qapi_gen,
args: ['-o', meson.current_build_dir() / 'qapi-firmware',
meson.current_source_dir() / 'interop/firmware.json'],
suite: ['qapi-schema', 'qapi-interop'])
test('QAPI vhost-user.json regression test', qapi_gen,
args: ['-o', meson.current_build_dir() / 'qapi-vhost-user',
meson.current_source_dir() / 'interop/vhost-user.json'],
suite: ['qapi-schema', 'qapi-interop'])

3
meson.build
View file

@ -3508,11 +3508,13 @@ hxtool = find_program('scripts/hxtool')
shaderinclude = find_program('scripts/shaderinclude.py')
qapi_gen = find_program('scripts/qapi-gen.py')
qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
meson.current_source_dir() / 'scripts/qapi/backend.py',
meson.current_source_dir() / 'scripts/qapi/commands.py',
meson.current_source_dir() / 'scripts/qapi/common.py',
meson.current_source_dir() / 'scripts/qapi/error.py',
meson.current_source_dir() / 'scripts/qapi/events.py',
meson.current_source_dir() / 'scripts/qapi/expr.py',
meson.current_source_dir() / 'scripts/qapi/features.py',
meson.current_source_dir() / 'scripts/qapi/gen.py',
meson.current_source_dir() / 'scripts/qapi/introspect.py',
meson.current_source_dir() / 'scripts/qapi/main.py',
@ -3520,7 +3522,6 @@ qapi_gen_depends = [ meson.current_source_dir() / 'scripts/qapi/__init__.py',
meson.current_source_dir() / 'scripts/qapi/schema.py',
meson.current_source_dir() / 'scripts/qapi/source.py',
meson.current_source_dir() / 'scripts/qapi/types.py',
meson.current_source_dir() / 'scripts/qapi/features.py',
meson.current_source_dir() / 'scripts/qapi/visit.py',
meson.current_source_dir() / 'scripts/qapi-gen.py'
]

3
qapi/accelerator.json
View file

@ -87,7 +87,8 @@
#
# @enabled: the accelerator that is in use
#
# @present: the list of accelerators that are built into this executable
# @present: the list of accelerators that are built into this
# executable
#
# Since: 10.2.0
##

5
qapi/acpi-hest.json
View file

@ -5,13 +5,12 @@
##
# == GHESv2 CPER Error Injection
#
# Defined since ACPI Specification 6.1,
# section 18.3.2.8 Generic Hardware Error Source version 2. See:
# Defined since ACPI Specification 6.1, section 18.3.2.8 Generic
# Hardware Error Source version 2. See:
#
# https://uefi.org/sites/default/files/resources/ACPI_6_1.pdf
##
##
# @inject-ghes-v2-error:
#

4
qapi/audio.json
View file

@ -76,8 +76,8 @@
#
# @out: options of the playback stream
#
# @nsamples: set the number of samples per read/write calls (default to 480,
# 10ms at 48kHz).
# @nsamples: set the number of samples per read/write calls
# (default to 480, 10ms at 48kHz).
#
# Since: 10.0
##

158
qapi/block-core.json
View file

@ -159,14 +159,15 @@
##
# @ImageInfoSpecificRbd:
#
# @encryption-format: Image encryption format. If encryption is enabled for the
# image (see encrypted in BlockNodeInfo), this is the actual format in which the
# image is accessed. If encryption is not enabled, this is the result of
# probing when the image was opened, to give a suggestion which encryption
# format could be enabled. Note that probing results can be changed by the
# guest by writing a (possibly partial) encryption format header to the
# image, so don't treat this information as trusted if the guest is not
# trusted.
# @encryption-format: Image encryption format. If encryption is
# enabled for the image (see encrypted in BlockNodeInfo), this is
# the actual format in which the image is accessed. If encryption
# is not enabled, this is the result of probing when the image was
# opened, to give a suggestion which encryption format could be
# enabled. Note that probing results can be changed by the guest
# by writing a (possibly partial) encryption format header to the
# image, so don't treat this information as trusted if the guest
# is not trusted.
#
# Since: 6.1
##
@ -406,8 +407,8 @@
# node, annotated with information about that node in relation to its
# parent.
#
# @name: Child name of the root node in the `BlockGraphInfo` struct, in
# its role as the child of some undescribed parent node
# @name: Child name of the root node in the `BlockGraphInfo` struct,
# in its role as the child of some undescribed parent node
#
# @info: Block graph information starting at this node
#
@ -573,11 +574,12 @@
# @backing_file_depth: number of files in the backing file chain
# (since: 1.2)
#
# @children: Information about child block nodes. (since: 10.1)
# @children: Information about child block nodes. (since: 10.1)
#
# @active: true if the backend is active; typical cases for inactive backends
# are on the migration source instance after migration completes and on the
# destination before it completes. (since: 10.0)
# @active: true if the backend is active; typical cases for inactive
# backends are on the migration source instance after migration
# completes and on the destination before it completes.
# (since: 10.0)
#
# @encrypted: true if the backing device is encrypted
#
@ -853,8 +855,8 @@
#
# Get a list of `BlockInfo` for all virtual block devices.
#
# Returns: a list describing each virtual block device.
# Filter nodes that were created implicitly are skipped over.
# Returns: a list describing each virtual block device. Filter nodes
# that were created implicitly are skipped over.
#
# Since: 0.14
#
@ -1693,11 +1695,12 @@
# different block device than @device).
#
# @on-cbw-error: policy defining behavior on I/O errors in
# copy-before-write jobs; defaults to break-guest-write. (Since 10.1)
# copy-before-write jobs; defaults to break-guest-write.
# (Since 10.1)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# after it has finished its work, waiting for `job-finalize`
# before making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 2.12)
#
@ -1809,7 +1812,8 @@
#
# @allow-write-only-overlay: If present, the check whether this
# operation is safe was relaxed so that it can be used to change
# backing file of a destination of a `blockdev-mirror`. (since 5.0)
# backing file of a destination of a `blockdev-mirror`.
# (since 5.0)
#
# Since: 2.5
#
@ -1873,8 +1877,8 @@
#
# If top == base, that is an error. If top has no overlays on top of
# it, or if it is in use by a writer, the job will not be completed by
# itself. The user needs to complete the job with the
# `job-complete` command after getting the ready event. (Since 2.0)
# itself. The user needs to complete the job with the `job-complete`
# command after getting the ready event. (Since 2.0)
#
# If the base image is smaller than top, then the base image will be
# resized to be the same size as top. If top is smaller than the base
@ -1936,8 +1940,8 @@
# autogenerated. (Since: 2.9)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# after it has finished its work, waiting for `job-finalize`
# before making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
@ -2010,10 +2014,10 @@
# @blockdev-backup:
#
# Start a point-in-time copy of a block device to a new destination.
# The status of ongoing `blockdev-backup` operations can be checked with
# `query-block-jobs` where the `BlockJobInfo`.type field has the value
# 'backup'. The operation can be stopped before it has completed
# using the `job-cancel` or `block-job-cancel` command.
# The status of ongoing `blockdev-backup` operations can be checked
# with `query-block-jobs` where the `BlockJobInfo`.type field has the
# value 'backup'. The operation can be stopped before it has
# completed using the `job-cancel` or `block-job-cancel` command.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
@ -2297,8 +2301,8 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# after it has finished its work, waiting for `job-finalize`
# before making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
@ -2348,7 +2352,8 @@
#
# @disabled: the bitmap is created in the disabled state, which means
# that it will not track drive changes. The bitmap may be enabled
# with `block-dirty-bitmap-enable`. Default is false. (Since: 4.0)
# with `block-dirty-bitmap-enable`. Default is false.
# (Since: 4.0)
#
# Since: 2.4
##
@ -2413,8 +2418,8 @@
# @block-dirty-bitmap-remove:
#
# Stop write tracking and remove the dirty bitmap that was created
# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove it
# from its storage too.
# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove
# it from its storage too.
#
# Errors:
# - If @node is not a valid block device or node, DeviceNotFound
@ -2612,8 +2617,8 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# after it has finished its work, waiting for `job-finalize`
# before making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
@ -2939,8 +2944,8 @@
# autogenerated. (Since: 6.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
# after it has finished its work, waiting for `job-finalize` before
# making any block graph changes. When true, this job will
# after it has finished its work, waiting for `job-finalize`
# before making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
@ -3110,16 +3115,16 @@
#
# This is supported only for drive mirroring, where it also switches
# the device to write to the target path only. Note that drive
# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
# job (only in case of "active commit", when the node being commited
# is used by the guest). The ability to complete is signaled with a
# `BLOCK_JOB_READY` event.
# mirroring includes `drive-mirror`, `blockdev-mirror` and
# `block-commit` job (only in case of "active commit", when the node
# being commited is used by the guest). The ability to complete is
# signaled with a `BLOCK_JOB_READY` event.
#
# This command completes an active background block operation
# synchronously. The ordering of this command's return with the
# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error
# occurs during the processing of this command: 1) the command itself
# will fail; 2) the error will be processed according to the
# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O
# error occurs during the processing of this command: 1) the command
# itself will fail; 2) the error will be processed according to the
# rerror/werror arguments that were specified when starting the
# operation.
#
@ -3147,10 +3152,10 @@
#
# Deletes a job that is in the CONCLUDED state. This command only
# needs to be run explicitly for jobs that don't have automatic
# dismiss enabled. In turn, automatic dismiss may be enabled only
# for jobs that have @auto-dismiss option, which are `drive-backup`,
# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
# `block-stream`. @auto-dismiss is enabled by default for these
# dismiss enabled. In turn, automatic dismiss may be enabled only for
# jobs that have @auto-dismiss option, which are `drive-backup`,
# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
# and `block-stream`. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
@ -3183,8 +3188,8 @@
# force ALL jobs in the transaction to finalize, so it is only
# necessary to instruct a single member job to finalize.
#
# The command is applicable only to jobs which have @auto-finalize option
# and only when this option is set to false.
# The command is applicable only to jobs which have @auto-finalize
# option and only when this option is set to false.
#
# @id: The job identifier.
#
@ -4814,9 +4819,9 @@
# @cache: cache-related options
#
# @active: whether the block node should be activated (default: true).
# Having inactive block nodes is useful primarily for migration because it
# allows opening an image on the destination while the source is still
# holding locks for it. (Since 10.0)
# Having inactive block nodes is useful primarily for migration
# because it allows opening an image on the destination while the
# source is still holding locks for it. (Since 10.0)
#
# @read-only: whether the block device should be read-only (default:
# false). Note that some block drivers support only read-only
@ -5008,11 +5013,12 @@
# cancelled.
#
# The command receives a list of block devices to reopen. For each
# one of them, the top-level @node-name option (from `BlockdevOptions`)
# must be specified and is used to select the block device to be
# reopened. Other @node-name options must be either omitted or set to
# the current name of the appropriate node. This command won't change
# any node name and any attempt to do it will result in an error.
# one of them, the top-level @node-name option (from
# `BlockdevOptions`) must be specified and is used to select the block
# device to be reopened. Other @node-name options must be either
# omitted or set to the current name of the appropriate node. This
# command won't change any node name and any attempt to do it will
# result in an error.
#
# In the case of options that refer to child nodes, the behavior of
# this command depends on the value:
@ -5031,10 +5037,10 @@
# Options (1) and (2) are supported in all cases. Option (3) is
# supported for @file and @backing, and option (4) for @backing only.
#
# Unlike with `blockdev-add`, the @backing option must always be present
# unless the node being reopened does not have a backing file and its
# image does not have a default backing file name as part of its
# metadata.
# Unlike with `blockdev-add`, the @backing option must always be
# present unless the node being reopened does not have a backing file
# and its image does not have a default backing file name as part of
# its metadata.
#
# Since: 6.1
##
@ -5045,8 +5051,8 @@
##
# @blockdev-del:
#
# Deletes a block device that has been added using `blockdev-add`. The
# command will fail if the node is attached to a device or is
# Deletes a block device that has been added using `blockdev-add`.
# The command will fail if the node is attached to a device or is
# otherwise being used.
#
# @node-name: Name of the graph node to delete.
@ -5078,18 +5084,18 @@
##
# @blockdev-set-active:
#
# Activate or inactivate a block device. Use this to manage the handover of
# block devices on migration with qemu-storage-daemon.
# Activate or inactivate a block device. Use this to manage the
# handover of block devices on migration with qemu-storage-daemon.
#
# Activating a node automatically activates all of its child nodes first.
# Inactivating a node automatically inactivates any of its child nodes that are
# not in use by a still active node.
# Activating a node automatically activates all of its child nodes
# first. Inactivating a node automatically inactivates any of its
# child nodes that are not in use by a still active node.
#
# @node-name: Name of the graph node to activate or inactivate. By default, all
# nodes are affected by the operation.
# @node-name: Name of the graph node to activate or inactivate. By
# default, all nodes are affected by the operation.
#
# @active: true if the nodes should be active when the command returns success,
# false if they should be inactive.
# @active: true if the nodes should be active when the command returns
# success, false if they should be inactive.
#
# Since: 10.0
#
@ -5945,9 +5951,9 @@
# @BLOCK_JOB_PENDING:
#
# Emitted when a block job is awaiting explicit authorization to
# finalize graph changes via `job-finalize`. If this job is part
# of a transaction, it will not emit this event until the transaction
# has converged first.
# finalize graph changes via `job-finalize`. If this job is part of a
# transaction, it will not emit this event until the transaction has
# converged first.
#
# @type: job type
#

26
qapi/block-export.json
View file

@ -38,8 +38,8 @@
##
# @NbdServerOptions:
#
# Keep this type consistent with the `NbdServerOptionsLegacy` type. The
# only intended difference is using `SocketAddress` instead of
# Keep this type consistent with the `NbdServerOptionsLegacy` type.
# The only intended difference is using `SocketAddress` instead of
# `SocketAddressLegacy`.
#
# @addr: Address on which to listen (since 4.2).
@ -51,8 +51,8 @@
##
# @NbdServerOptionsLegacy:
#
# Keep this type consistent with the `NbdServerOptions` type. The only
# intended difference is using `SocketAddressLegacy` instead of
# Keep this type consistent with the `NbdServerOptions` type. The
# only intended difference is using `SocketAddressLegacy` instead of
# `SocketAddress`.
#
# @addr: Address on which to listen (since 1.3).
@ -125,8 +125,8 @@
# A vhost-user-blk block export.
#
# @addr: The vhost-user socket on which to listen. Both 'unix' and
# 'fd' `SocketAddress` types are supported. Passed fds must be UNIX
# domain sockets.
# 'fd' `SocketAddress` types are supported. Passed fds must be
# UNIX domain sockets.
#
# @logical-block-size: Logical block size in bytes. Defaults to 512
# bytes.
@ -373,11 +373,12 @@
# cannot be moved to the iothread. The default is false.
# (since: 5.2)
#
# @allow-inactive: If true, the export allows the exported node to be inactive.
# If it is created for an inactive block node, the node remains inactive. If
# the export type doesn't support running on an inactive node, an error is
# returned. If false, inactive block nodes are automatically activated before
# creating the export and trying to inactivate them later fails.
# @allow-inactive: If true, the export allows the exported node to be
# inactive. If it is created for an inactive block node, the node
# remains inactive. If the export type doesn't support running on
# an inactive node, an error is returned. If false, inactive
# block nodes are automatically activated before creating the
# export and trying to inactivate them later fails.
# (since: 10.0; default: false)
#
# Since: 4.2
@ -460,7 +461,8 @@
# @node-name: The node name of the block node that is exported
#
# @shutting-down: True if the export is shutting down (e.g. after a
# `block-export-del` command, but before the shutdown has completed)
# `block-export-del` command, but before the shutdown has
# completed)
#
# Since: 5.2
##

1
qapi/char.json
View file

@ -681,7 +681,6 @@
{ 'struct': 'ChardevRingbufWrapper',
'data': { 'data': 'ChardevRingbuf' } }
##
# @ChardevPtyWrapper:
#

8
qapi/crypto.json
View file

@ -46,7 +46,8 @@
#
# @md5: MD5. Should not be used in any new code, legacy compat only
#
# @sha1: SHA-1. Should not be used in any new code, legacy compat only
# @sha1: SHA-1. Should not be used in any new code, legacy compat
# only
#
# @sha224: SHA-224. (since 2.7)
#
@ -377,8 +378,8 @@
# deactivate all keyslots that match password located in
# QCryptoSecret with this ID
#
# @iter-time: Optional (for activation only). Number of milliseconds to
# spend in PBKDF passphrase processing for the newly activated
# @iter-time: Optional (for activation only). Number of milliseconds
# to spend in PBKDF passphrase processing for the newly activated
# keyslot. Currently defaults to 2000.
#
# @keyslot: Optional. ID of the keyslot to activate/deactivate. For
@ -546,6 +547,7 @@
'base': 'TlsCredsProperties',
'data': { '*sanity-check': 'bool',
'*passwordid': 'str' } }
##
# @QCryptoAkCipherAlgo:
#

1
qapi/cxl.json
View file

@ -262,7 +262,6 @@
#
# Since: 8.0
##
{ 'enum': 'CxlUncorErrorType',
'data': ['cache-data-parity',
'cache-address-parity',

8
qapi/introspect.json
View file

@ -22,10 +22,10 @@
# `SchemaInfo`. This lets QMP clients figure out what commands and
# events are available in this QEMU, and their parameters and results.
#
# However, the `SchemaInfo` can't reflect all the rules and restrictions
# that apply to QMP. It's interface introspection (figuring out
# what's there), not interface specification. The specification is in
# the QAPI schema.
# However, the `SchemaInfo` can't reflect all the rules and
# restrictions that apply to QMP. It's interface introspection
# (figuring out what's there), not interface specification. The
# specification is in the QAPI schema.
#
# Furthermore, while we strive to keep the QMP wire format
# backwards-compatible across QEMU versions, the introspection output

30
qapi/job.json
View file

@ -194,16 +194,16 @@
#
# This is supported only for drive mirroring, where it also switches
# the device to write to the target path only. Note that drive
# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit`
# job (only in case of "active commit", when the node being commited
# is used by the guest). The ability to complete is signaled with a
# `BLOCK_JOB_READY` event.
# mirroring includes `drive-mirror`, `blockdev-mirror` and
# `block-commit` job (only in case of "active commit", when the node
# being commited is used by the guest). The ability to complete is
# signaled with a `BLOCK_JOB_READY` event.
#
# This command completes an active background block operation
# synchronously. The ordering of this command's return with the
# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error
# occurs during the processing of this command: 1) the command itself
# will fail; 2) the error will be processed according to the
# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O
# error occurs during the processing of this command: 1) the command
# itself will fail; 2) the error will be processed according to the
# rerror/werror arguments that were specified when starting the
# operation.
#
@ -218,16 +218,16 @@
#
# Deletes a job that is in the CONCLUDED state. This command only
# needs to be run explicitly for jobs that don't have automatic
# dismiss enabled. In turn, automatic dismiss may be enabled only
# for jobs that have @auto-dismiss option, which are `drive-backup`,
# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and
# `block-stream`. @auto-dismiss is enabled by default for these
# dismiss enabled. In turn, automatic dismiss may be enabled only for
# jobs that have @auto-dismiss option, which are `drive-backup`,
# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
# and `block-stream`. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
# reached its terminal state, CONCLUDED. For jobs that make use of
# the JOB_READY event, `job-cancel` or `job-complete` will still need to
# be used as appropriate.
# the JOB_READY event, `job-cancel` or `job-complete` will still need
# to be used as appropriate.
#
# @id: The job identifier.
#
@ -247,8 +247,8 @@
# force ALL jobs in the transaction to finalize, so it is only
# necessary to instruct a single member job to finalize.
#
# The command is applicable only to jobs which have @auto-finalize option
# and only when this option is set to false.
# The command is applicable only to jobs which have @auto-finalize
# option and only when this option is set to false.
#
# @id: The identifier of any job in the transaction, or of a job that
# is not part of any transaction.

4
qapi/machine-common.json
View file

@ -87,8 +87,8 @@
#
# Cache information for SMP system.
#
# @cache: Cache name, which is the combination of cache level
# and cache type.
# @cache: Cache name, which is the combination of cache level and
# cache type.
#
# @topology: Cache topology level. It accepts the CPU topology
# enumeration as the parameter, i.e., CPUs in the same

4
qapi/machine-s390x.json
View file

@ -123,8 +123,8 @@
##
# @SCLP_CPI_INFO_AVAILABLE:
#
# Emitted when the Control-Program Identification data is available
# in the QOM tree.
# Emitted when the Control-Program Identification data is available in
# the QOM tree.
#
# Features:
#

49
qapi/machine.json
View file

@ -620,8 +620,8 @@
##
# @NumaCpuOptions:
#
# Option "-numa cpu" overrides default cpu to node mapping. It accepts
# the same set of cpu properties as returned by
# Option "-numa cpu" overrides default cpu to node mapping. It
# accepts the same set of cpu properties as returned by
# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where
# node-id could be used to override default node mapping.
#
@ -686,8 +686,8 @@
# Set the system locality latency and bandwidth information between
# Initiator and Target proximity Domains.
#
# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4:
# Table 5-146 of ACPI 6.3 spec.
# For more information about `NumaHmatLBOptions`, see chapter
# 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
#
# @initiator: the Initiator Proximity Domain.
#
@ -743,8 +743,8 @@
# Cache write policy in the Memory Side Cache Information Structure of
# HMAT
#
# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5:
# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
# For more information of `HmatCacheWritePolicy`, see chapter
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @none: None (no memory side cache in this proximity domain, or cache
# write policy unknown)
@ -763,8 +763,8 @@
#
# Set the memory side cache information for a given memory domain.
#
# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5:
# Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
# For more information of `NumaHmatCacheOptions`, see chapter
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
#
# @node-id: the memory proximity domain to which the memory belongs.
#
@ -959,7 +959,7 @@
# belongs to (since 7.1)
#
# @module-id: module number within the parent container the CPU
# belongs to (since 9.1)
# belongs to (since 9.1)
#
# @core-id: core number within the parent container the CPU belongs to
#
@ -1090,7 +1090,7 @@
# @value: the target logical size of the VM in bytes. We can deduce
# the size of the balloon using this formula:
#
# logical_vm_size = vm_ram_size - balloon_size
# logical_vm_size = vm_ram_size - balloon_size
#
# From it we have: balloon_size = vm_ram_size - @value
#
@ -1845,7 +1845,7 @@
# @version: Firmware version.
#
# @log: Firmware debug log, in base64 encoding. First and last log
# line might be incomplete.
# line might be incomplete.
#
# Since: 10.2
##
@ -1859,8 +1859,8 @@
# Find firmware memory log buffer in guest memory, return content.
#
# @max-size: limit the amount of log data returned. Up to 1 MiB of
# log data is allowed. In case the amount of log data is
# larger than @max-size the tail of the log is returned.
# log data is allowed. In case the amount of log data is larger
# than @max-size the tail of the log is returned.
#
# Since: 10.2
##
@ -2004,11 +2004,11 @@
# @query-cpu-model-comparison:
#
# Compares two CPU models, @modela and @modelb, returning how they
# compare in a specific configuration. The results indicates how
# both models compare regarding runnability. This result can be
# used by tooling to make decisions if a certain CPU model will
# run in a certain configuration or if a compatible CPU model has
# to be created by baselining.
# compare in a specific configuration. The results indicates how both
# models compare regarding runnability. This result can be used by
# tooling to make decisions if a certain CPU model will run in a
# certain configuration or if a compatible CPU model has to be created
# by baselining.
#
# Usually, a CPU model is compared against the maximum possible CPU
# model of a certain configuration (e.g. the "host" model for KVM).
@ -2029,7 +2029,8 @@
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using `query-cpu-model-expansion` while using these is not advised.
# Using `query-cpu-model-expansion` while using these is not
# advised.
#
# Some architectures may not support comparing CPU models. s390x
# supports comparing CPU models.
@ -2083,7 +2084,8 @@
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using `query-cpu-model-expansion` while using these is not advised.
# Using `query-cpu-model-expansion` while using these is not
# advised.
#
# Some architectures may not support baselining CPU models. s390x
# supports baselining CPU models.
@ -2114,8 +2116,8 @@
#
# @model: the expanded `CpuModelInfo`.
#
# @deprecated-props: an optional list of properties that are flagged as
# deprecated by the CPU vendor. The list depends on the
# @deprecated-props: an optional list of properties that are flagged
# as deprecated by the CPU vendor. The list depends on the
# `CpuModelExpansionType`: "static" properties are a subset of the
# enabled-properties for the expanded model; "full" properties are
# a set of properties that are deprecated across all models for
@ -2151,7 +2153,8 @@
# `query-cpu-definitions`.)
# * "-cpu" arguments and global properties: arguments to the -cpu
# option and global properties may affect expansion of CPU models.
# Using `query-cpu-model-expansion` while using these is not advised.
# Using `query-cpu-model-expansion` while using these is not
# advised.
#
# Some architectures may not support all expansion types. s390x
# supports "full" and "static". Arm only supports "full".

126
qapi/migration.json
View file

@ -166,11 +166,11 @@
#
# @pre-switchover: Paused before device serialisation. (since 2.11)
#
# @device: During device serialisation (also known as switchover phase).
# Before 9.2, this is only used when (1) in precopy, and (2) when
# pre-switchover capability is enabled. After 10.0, this state will
# always be present for every migration procedure as the switchover
# phase. (since 2.11)
# @device: During device serialisation (also known as switchover
# phase). Before 9.2, this is only used when (1) in precopy, and
# (2) when pre-switchover capability is enabled. After 10.0, this
# state will always be present for every migration procedure as
# the switchover phase. (since 2.11)
#
# @wait-unplug: wait for device unplug request by guest OS to be
# completed. (since 4.2)
@ -183,6 +183,7 @@
'postcopy-paused', 'postcopy-recover-setup',
'postcopy-recover', 'completed', 'failed', 'colo',
'pre-switchover', 'device', 'wait-unplug' ] }
##
# @VfioStats:
#
@ -244,31 +245,34 @@
# This is only present when the postcopy-blocktime migration
# capability is enabled. (Since 3.0)
#
# @postcopy-latency: average remote page fault latency (in ns). Note that
# this doesn't include all faults, but only the ones that require a
# remote page request. So it should be always bigger than the real
# average page fault latency. This is only present when the
# postcopy-blocktime migration capability is enabled. (Since 10.1)
#
# @postcopy-latency-dist: remote page fault latency distributions. Each
# element of the array is the number of faults that fall into the
# bucket period. For the N-th bucket (N>=0), the latency window is
# [2^Nus, 2^(N+1)us). For example, the 8th element stores how many
# remote faults got resolved within [256us, 512us) window. This is only
# present when the postcopy-blocktime migration capability is enabled.
# @postcopy-latency: average remote page fault latency (in ns). Note
# that this doesn't include all faults, but only the ones that
# require a remote page request. So it should be always bigger
# than the real average page fault latency. This is only present
# when the postcopy-blocktime migration capability is enabled.
# (Since 10.1)
#
# @postcopy-vcpu-latency: average remote page fault latency per vCPU (in
# ns). It has the same definition of @postcopy-latency, but instead
# this is the per-vCPU statistics. This is only present when the
# postcopy-blocktime migration capability is enabled. (Since 10.1)
#
# @postcopy-non-vcpu-latency: average remote page fault latency for all
# faults happend in non-vCPU threads (in ns). It has the same
# definition of @postcopy-latency but this only provides statistics to
# non-vCPU faults. This is only present when the postcopy-blocktime
# @postcopy-latency-dist: remote page fault latency distributions.
# Each element of the array is the number of faults that fall into
# the bucket period. For the N-th bucket (N>=0), the latency
# window is [2^Nus, 2^(N+1)us). For example, the 8th element
# stores how many remote faults got resolved within [256us, 512us)
# window. This is only present when the postcopy-blocktime
# migration capability is enabled. (Since 10.1)
#
# @postcopy-vcpu-latency: average remote page fault latency per vCPU
# (in ns). It has the same definition of @postcopy-latency, but
# instead this is the per-vCPU statistics. This is only present
# when the postcopy-blocktime migration capability is enabled.
# (Since 10.1)
#
# @postcopy-non-vcpu-latency: average remote page fault latency for
# all faults happend in non-vCPU threads (in ns). It has the same
# definition of @postcopy-latency but this only provides
# statistics to non-vCPU faults. This is only present when the
# postcopy-blocktime migration capability is enabled.
# (Since 10.1)
#
# @socket-address: Only used for tcp, to know what the real port is
# (Since 4.0)
#
@ -296,7 +300,8 @@
# Features:
#
# @unstable: Members @postcopy-latency, @postcopy-vcpu-latency,
# @postcopy-latency-dist, @postcopy-non-vcpu-latency are experimental.
# @postcopy-latency-dist, @postcopy-non-vcpu-latency are
# experimental.
#
# Since: 0.14
##
@ -328,9 +333,8 @@
##
# @query-migrate:
#
# Return information about current migration process. If migration
# is active there will be another json-object with RAM migration
# status.
# Return information about current migration process. If migration is
# active there will be another json-object with RAM migration status.
#
# Since: 0.14
#
@ -526,6 +530,7 @@
# Features:
#
# @unstable: Members @x-colo and @x-ignore-shared are experimental.
#
# @deprecated: Member @zero-blocks is deprecated as being part of
# block migration which was already removed.
#
@ -633,8 +638,8 @@
#
# @normal: the original form of migration. (since 8.2)
#
# @cpr-reboot: The `migrate` command stops the VM and saves state to the
# URI. After quitting QEMU, the user resumes by running QEMU
# @cpr-reboot: The `migrate` command stops the VM and saves state to
# the URI. After quitting QEMU, the user resumes by running QEMU
# -incoming.
#
# This mode allows the user to quit QEMU, optionally update and
@ -665,15 +670,15 @@
# time by preserving guest RAM in place.
#
# Devices and their pinned pages are also preserved for VFIO and
# IOMMUFD. (since 10.1)
# IOMMUFD. (since 10.1)
#
# The user starts new QEMU on the same host as old QEMU, with
# command-line arguments to create the same machine, plus the
# -incoming option for the main migration channel, like normal
# live migration. In addition, the user adds a second -incoming
# option with channel type "cpr". This CPR channel must support
# file descriptor transfer with SCM_RIGHTS, i.e. it must be a
# UNIX domain socket.
# file descriptor transfer with SCM_RIGHTS, i.e. it must be a UNIX
# domain socket.
#
# To initiate CPR, the user issues a migrate command to old QEMU,
# adding a second migration channel of type "cpr" in the channels
@ -714,8 +719,8 @@
# QEMU binary.
#
# Because old QEMU terminates when new QEMU starts, one cannot
# stream data between the two, so the channel must be a type,
# such as a file, that accepts all data before old QEMU exits.
# stream data between the two, so the channel must be a type, such
# as a file, that accepts all data before old QEMU exits.
# Otherwise, old QEMU may quietly block writing to the channel.
#
# Memory-backend objects must have the share=on attribute, but
@ -909,9 +914,10 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
# migration. The level is an integer between 1 and 9, where 1
# means the best compression speed, and 9 means the best
# compression ratio which will consume more CPU. Defaults to 1.
# (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@ -945,8 +951,8 @@
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
# @zero-page-detection: Whether and how to detect zero pages.
# See description in `ZeroPageDetection`. Default is 'multifd'.
# @zero-page-detection: Whether and how to detect zero pages. See
# description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@ -1095,9 +1101,10 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
# migration. The level is an integer between 1 and 9, where 1
# means the best compression speed, and 9 means the best
# compression ratio which will consume more CPU. Defaults to 1.
# (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@ -1131,8 +1138,8 @@
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
# @zero-page-detection: Whether and how to detect zero pages.
# See description in `ZeroPageDetection`. Default is 'multifd'.
# @zero-page-detection: Whether and how to detect zero pages. See
# description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@ -1310,9 +1317,10 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
# migration. The level is an integer between 1 and 9, where 1
# means the best compression speed, and 9 means the best
# compression ratio which will consume more CPU. Defaults to 1.
# (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@ -1346,8 +1354,8 @@
# @mode: Migration mode. See description in `MigMode`. Default is
# 'normal'. (Since 8.2)
#
# @zero-page-detection: Whether and how to detect zero pages.
# See description in `ZeroPageDetection`. Default is 'multifd'.
# @zero-page-detection: Whether and how to detect zero pages. See
# description in `ZeroPageDetection`. Default is 'multifd'.
# (since 9.0)
#
# @direct-io: Open migration files with O_DIRECT when possible. This
@ -1702,6 +1710,7 @@
# The migration channel-type request options.
#
# @main: Main outbound migration channel.
#
# @cpr: Checkpoint and restart state channel.
#
# Since: 8.1
@ -1822,9 +1831,9 @@
# list connected to a destination interface endpoint.
#
# @exit-on-error: Exit on incoming migration failure. Default true.
# When set to false, the failure triggers a :qapi:event:`MIGRATION`
# event, and error details could be retrieved with `query-migrate`.
# (since 9.1)
# When set to false, the failure triggers a
# :qapi:event:`MIGRATION` event, and error details could be
# retrieved with `query-migrate`. (since 9.1)
#
# Since: 2.3
#
@ -2377,8 +2386,7 @@
##
# @query-vcpu-dirty-limit:
#
# Return information about virtual CPU dirty page rate limits, if
# any.
# Return information about virtual CPU dirty page rate limits, if any.
#
# Since: 7.1
#
@ -2516,8 +2524,8 @@
# time it takes to load the snapshot.
#
# It is strongly recommended that @devices contain all writable block
# device nodes that can have changed since the original `snapshot-save`
# command execution.
# device nodes that can have changed since the original
# `snapshot-save` command execution.
#
# .. qmp-example::
#

2
qapi/misc-i386.json
View file

@ -122,7 +122,6 @@
'sev': 'SevGuestInfo',
'sev-snp': 'SevSnpGuestInfo' } }
##
# @query-sev:
#
@ -418,7 +417,6 @@
'pending': 'bool',
'masked': 'bool'} }
##
# @xen-event-list:
#

26
qapi/net.json
View file

@ -119,9 +119,11 @@
#
# Unprivileged user-mode network connectivity using passt
#
# @path: Filename of the passt program to run (by default 'passt', and use PATH)
# @path: Filename of the passt program to run (by default 'passt', and
# use PATH)
#
# @quiet: don't print informational messages (default, passed as '--quiet')
# @quiet: don't print informational messages (default, passed as
# '--quiet')
#
# @vhost-user: enable vhost-user
#
@ -281,8 +283,8 @@
#
# @smbserver: IP address of the built-in SMB server
#
# @hostfwd: redirect incoming TCP, UDP or UNIX host connections to guest
# endpoints
# @hostfwd: redirect incoming TCP, UDP or UNIX host connections to
# guest endpoints
#
# @guestfwd: forward guest TCP connections
#
@ -569,7 +571,8 @@
# (default: 0).
#
# @inhibit: Don't load a default XDP program, use one already loaded
# to the interface (default: false). Requires @sock-fds or @map-path.
# to the interface (default: false). Requires @sock-fds or
# @map-path.
#
# @sock-fds: A colon (:) separated list of file descriptors for
# already open but not bound AF_XDP sockets in the queue order.
@ -582,7 +585,8 @@
# mutually exclusive. Requires @inhibit. (Since 10.1)
#
# @map-start-index: Use @map-path to insert xsk sockets starting from
# this index number (default: 0). Requires @map-path. (Since 10.1)
# this index number (default: 0). Requires @map-path.
# (Since 10.1)
#
# Since: 8.2
##
@ -770,9 +774,10 @@
#
# @server: create server socket (default: false)
#
# @reconnect-ms: For a client socket, if a socket is disconnected, then
# attempt a reconnect after the given number of milliseconds. Setting
# this to zero disables this function. (default: 0) (Since: 9.2)
# @reconnect-ms: For a client socket, if a socket is disconnected,
# then attempt a reconnect after the given number of milliseconds.
# Setting this to zero disables this function.
# (default: 0) (Since: 9.2)
#
# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
#
@ -1050,7 +1055,6 @@
#
# Since: 4.0
##
{ 'struct': 'AnnounceParameters',
'data': { 'initial': 'int',
'max': 'int',
@ -1166,7 +1170,6 @@
# <- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 },
# "event": "NETDEV_VHOST_USER_CONNECTED",
# "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } }
#
##
{ 'event': 'NETDEV_VHOST_USER_CONNECTED',
'data': { 'netdev-id': 'str', 'chardev-id': 'str' } }
@ -1185,7 +1188,6 @@
# <- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 },
# "event": "NETDEV_VHOST_USER_DISCONNECTED",
# "data": { "netdev-id": "netdev0" } }
#
##
{ 'event': 'NETDEV_VHOST_USER_DISCONNECTED',
'data': { 'netdev-id': 'str' } }

4
qapi/qdev.json
View file

@ -100,8 +100,8 @@
# process is signaled with a `DEVICE_DELETED` event. Guest reset
# will automatically complete removal for all devices. If a
# guest-side error in the hot removal process is detected, the
# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` event
# is sent. Some errors cannot be detected.
# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR`
# event is sent. Some errors cannot be detected.
#
# Since: 0.14
#

47
qapi/qom.json
View file

@ -52,7 +52,8 @@
#
# @name: the name of the property.
#
# @type: the type of the property, as described in `ObjectPropertyInfo`.
# @type: the type of the property, as described in
# `ObjectPropertyInfo`.
#
# @value: the value of the property. Absent when the property cannot
# be read.
@ -74,7 +75,6 @@
{ 'struct': 'ObjectPropertiesValues',
'data': { 'properties': [ 'ObjectPropertyValue' ] }}
##
# @qom-list:
#
@ -112,7 +112,7 @@
# Absolute paths are derived from the root object and can follow
# child<> or link<> properties. Since they can follow link<>
# properties, they can be arbitrarily long. Absolute paths look
# like absolute filenames and are prefixed with a leading slash.
# like absolute filenames and are prefixed with a leading slash.
#
# Partial paths look like relative filenames. They do not begin
# with a prefix. The matching rules for partial paths are subtle
@ -243,7 +243,6 @@
#
# @typename: the type name of an object
#
#
# .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These
# properties are not included in the output of this command.
@ -917,14 +916,14 @@
# combined with information retrieved from the discoverable part
# of the path. An example would use CDAT (see UEFI.org)
# information read from devices and switches in conjunction with
# link characteristics read from PCIe Configuration space.
# To get the full path latency from CPU to CXL attached DRAM
# CXL device: Add the latency from CPU to Generic Port (from
# HMAT indexed via the node ID in this SRAT structure) to
# that for CXL bus links, the latency across intermediate switches
# and from the EP port to the actual memory. Bandwidth is more
# complex as there may be interleaving across multiple devices
# and shared links in the path.
# link characteristics read from PCIe Configuration space. To get
# the full path latency from CPU to CXL attached DRAM CXL device:
# Add the latency from CPU to Generic Port (from HMAT indexed via
# the node ID in this SRAT structure) to that for CXL bus links,
# the latency across intermediate switches and from the EP port to
# the actual memory. Bandwidth is more complex as there may be
# interleaving across multiple devices and shared links in the
# path.
#
# Since: 9.2
##
@ -1040,8 +1039,7 @@
# behave identically to 'on', but will automatically switch to
# using KVM_SEV_INIT2 if the user specifies any additional options
# that require it. If set to 'off', QEMU will require
# KVM_SEV_INIT2 unconditionally.
# (default: off) (since 9.1)
# KVM_SEV_INIT2 unconditionally. (default: off) (since 9.1)
#
# Since: 2.12
##
@ -1082,8 +1080,8 @@
# Authentication Information Structure' for the SNP_LAUNCH_FINISH
# command defined in the SEV-SNP firmware ABI (default: all-zero)
#
# @author-key-enabled: true if 'id-auth' blob contains the 'AUTHOR_KEY'
# field defined SEV-SNP firmware ABI (default: false)
# @author-key-enabled: true if 'id-auth' blob contains the
# 'AUTHOR_KEY' field defined SEV-SNP firmware ABI (default: false)
#
# @host-data: 32-byte, base64-encoded, user-defined blob to provide to
# the guest, as documented for the 'HOST_DATA' parameter of the
@ -1117,17 +1115,17 @@
# @attributes: The 'attributes' of a TD guest that is passed to
# KVM_TDX_INIT_VM
#
# @sept-ve-disable: toggle bit 28 of TD attributes to control disabling
# of EPT violation conversion to #VE on guest TD access of PENDING
# pages. Some guest OS (e.g., Linux TD guest) may require this to
# be set, otherwise they refuse to boot.
# @sept-ve-disable: toggle bit 28 of TD attributes to control
# disabling of EPT violation conversion to #VE on guest TD access
# of PENDING pages. Some guest OS (e.g., Linux TD guest) may
# require this to be set, otherwise they refuse to boot.
#
# @mrconfigid: ID for non-owner-defined configuration of the guest TD,
# e.g., run-time or OS configuration (base64 encoded SHA384 digest).
# Defaults to all zeros.
# e.g., run-time or OS configuration (base64 encoded SHA384
# digest). Defaults to all zeros.
#
# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384 digest).
# Defaults to all zeros.
# @mrowner: ID for the guest TD’s owner (base64 encoded SHA384
# digest). Defaults to all zeros.
#
# @mrownerconfig: ID for owner-defined configuration of the guest TD,
# e.g., specific to the workload rather than the run-time or OS
@ -1169,7 +1167,6 @@
'data': { '*cpu-affinity': ['uint16'],
'*node-affinity': ['uint16'] } }
##
# @ObjectType:
#

20
qapi/run-state.json
View file

@ -247,8 +247,8 @@
# 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.
# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when
# entering this state.
#
# Since: 1.2
#
@ -281,9 +281,9 @@
#
# @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:: 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.
#
@ -402,7 +402,8 @@
#
# @panic: `PanicAction` action taken on guest panic.
#
# @watchdog: `WatchdogAction` action taken when watchdog timer expires.
# @watchdog: `WatchdogAction` action taken when watchdog timer
# expires.
#
# Since: 6.0
#
@ -542,8 +543,8 @@
# @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.
# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux,
# the stack pointer of the guest.
#
# Since: 2.9
##
@ -610,14 +611,13 @@
#
# @error-code: TD-specific error code
#
# @message: Human-readable error message provided by the guest. Not
# @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',

30
qapi/sockets.json
View file

@ -58,24 +58,26 @@
# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and
# IPv6
#
# @keep-alive: enable keep-alive when connecting to/listening on this socket.
# @keep-alive: enable keep-alive when connecting to/listening on this
# socket.
# (Since 4.2, not supported for listening sockets until 10.1)
#
# @keep-alive-count: number of keep-alive packets sent before the connection is
# closed. Only supported for TCP sockets on systems where TCP_KEEPCNT
# socket option is defined (this includes Linux, Windows, macOS, FreeBSD,
# but not OpenBSD). When set to 0, system setting is used. (Since 10.1)
# @keep-alive-count: number of keep-alive packets sent before the
# connection is closed. Only supported for TCP sockets on systems
# where TCP_KEEPCNT socket option is defined (this includes Linux,
# Windows, macOS, FreeBSD, but not OpenBSD). When set to 0,
# system setting is used. (Since 10.1)
#
# @keep-alive-idle: time in seconds the connection needs to be idle before
# sending a keepalive packet. Only supported for TCP sockets on systems
# where TCP_KEEPIDLE socket option is defined (this includes Linux,
# Windows, macOS, FreeBSD, but not OpenBSD). When set to 0, system setting
# is used. (Since 10.1)
# @keep-alive-idle: time in seconds the connection needs to be idle
# before sending a keepalive packet. Only supported for TCP
# sockets on systems where TCP_KEEPIDLE socket option is defined
# (this includes Linux, Windows, macOS, FreeBSD, but not OpenBSD).
# When set to 0, system setting is used. (Since 10.1)
#
# @keep-alive-interval: time in seconds between keep-alive packets. Only
# supported for TCP sockets on systems where TCP_KEEPINTVL is defined (this
# includes Linux, Windows, macOS, FreeBSD, but not OpenBSD). When set to
# 0, system setting is used. (Since 10.1)
# @keep-alive-interval: time in seconds between keep-alive packets.
# Only supported for TCP sockets on systems where TCP_KEEPINTVL is
# defined (this includes Linux, Windows, macOS, FreeBSD, but not
# OpenBSD). When set to 0, system setting is used. (Since 10.1)
#
# @mptcp: enable multi-path TCP. (Since 6.1)
#

4
qapi/stats.json
View file

@ -185,8 +185,8 @@
# Return runtime-collected statistics for objects such as the VM or
# its vCPUs.
#
# The arguments are a `StatsFilter` and specify the provider and objects
# to return statistics about.
# The arguments are a `StatsFilter` and specify the provider and
# objects to return statistics about.
#
# Returns: a list of statistics, one for each provider and object
# (e.g., for each vCPU).

17
qapi/ui.json
View file

@ -682,6 +682,7 @@
##
{ 'command': 'query-vnc', 'returns': 'VncInfo',
'if': 'CONFIG_VNC' }
##
# @query-vnc-servers:
#
@ -1023,10 +1024,10 @@
#
# Send keys to guest.
#
# @keys: An array of `KeyValue` elements. All @KeyValues in this array
# are simultaneously sent to the guest. A `KeyValue`.number value
# is sent directly to the guest, while `KeyValue`.qcode must be a
# valid `QKeyCode` value
# @keys: An array of `KeyValue` elements. All @KeyValues in this
# array are simultaneously sent to the guest. A `KeyValue`.number
# value is sent directly to the guest, while `KeyValue`.qcode must
# be a valid `QKeyCode` value
#
# @hold-time: time to delay key up events, milliseconds. Defaults to
# 100
@ -1094,7 +1095,6 @@
{ 'enum' : 'InputMultiTouchType',
'data' : [ 'begin', 'update', 'end', 'cancel', 'data' ] }
##
# @InputKeyEvent:
#
@ -1335,10 +1335,11 @@
# @show-menubar: Display the main window menubar. Defaults to "on".
# (Since 8.0)
#
# @keep-aspect-ratio: Keep width/height aspect ratio of guest content when
# resizing host window. Defaults to "on". (Since 10.1)
# @keep-aspect-ratio: Keep width/height aspect ratio of guest content
# when resizing host window. Defaults to "on". (Since 10.1)
#
# @scale: Set preferred scale of the display. Defaults to 1.0. (Since 10.1)
# @scale: Set preferred scale of the display. Defaults to 1.0.
# (Since 10.1)
#
# Since: 2.12
##

6
qapi/virtio.json
View file

@ -964,7 +964,6 @@
#
# Since: 9.0
##
{ 'struct': 'IOThreadVirtQueueMapping',
'data': { 'iothread': 'str', '*vqs': ['uint16'] } }
@ -984,12 +983,11 @@
##
# @DummyVirtioForceArrays:
#
# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
# and VirtIOGPUOutputList internally
# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList and
# VirtIOGPUOutputList internally
#
# Since: 9.0
##
{ 'struct': 'DummyVirtioForceArrays',
'data': { 'unused-iothread-vq-mapping': ['IOThreadVirtQueueMapping'],
'unused-virtio-gpu-output': ['VirtIOGPUOutput'] } }

96
qga/qapi-schema.json
View file

@ -2,8 +2,8 @@
# vim: filetype=python
##
# This manual describes the commands supported by the QEMU Guest
# Agent Protocol.
# This manual describes the commands supported by the QEMU Guest Agent
# Protocol.
#
# For locating a particular item, please see the `qapi-qga-index`.
#
@ -96,8 +96,8 @@
# In cases where a partial stale response was previously received by
# the client, this cannot always be done reliably. One particular
# scenario being if qemu-ga responses are fed character-by-character
# into a JSON parser. In these situations, using `guest-sync-delimited`
# may be optimal.
# into a JSON parser. In these situations, using
# `guest-sync-delimited` may be optimal.
#
# For clients that fetch responses line by line and convert them to
# JSON objects, `guest-sync` should be sufficient, but note that in
@ -153,9 +153,9 @@
# This command tries to set guest's System Time to the given value,
# then sets the Hardware Clock (RTC) to the current System Time. This
# will make it easier for a guest to resynchronize without waiting for
# NTP. If no @time is specified, then the time to set is read from
# RTC. However, this may not be supported on all platforms (i.e.
# Windows). If that's the case users are advised to always pass a
# NTP. If no @time is specified, then the time to set is read from
# RTC. However, this may not be supported on all platforms (i.e.
# Windows). If that's the case users are advised to always pass a
# value.
#
# @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in
@ -197,6 +197,7 @@
{ 'struct': 'GuestAgentInfo',
'data': { 'version': 'str',
'supported_commands': ['GuestAgentCommandInfo'] } }
##
# @guest-info:
#
@ -322,7 +323,6 @@
'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
'returns': 'GuestFileWrite' }
##
# @GuestFileSeek:
#
@ -444,8 +444,8 @@
# Returns: Number of file systems currently frozen.
#
# .. note:: On Windows, the command is implemented with the help of a
# Volume Shadow-copy Service DLL helper. The frozen state is limited
# for up to 10 seconds by VSS.
# Volume Shadow-copy Service DLL helper. The frozen state is
# limited for up to 10 seconds by VSS.
#
# Since: 0.15.0
##
@ -482,9 +482,9 @@
# Returns: Number of file systems thawed by this call
#
# .. note:: If the return value does not match the previous call to
# `guest-fsfreeze-freeze`, this likely means some freezable filesystems
# were unfrozen before this call, and that the filesystem state may
# have changed before issuing this command.
# `guest-fsfreeze-freeze`, this likely means some freezable
# filesystems were unfrozen before this call, and that the
# filesystem state may have changed before issuing this command.
#
# Since: 0.15.0
##
@ -513,7 +513,8 @@
##
# @GuestFilesystemTrimResponse:
#
# @paths: list of `GuestFilesystemTrimResult` per path that was trimmed
# @paths: list of `GuestFilesystemTrimResult` per path that was
# trimmed
#
# Since: 2.4
##
@ -557,16 +558,16 @@
#
# This command does NOT return a response on success. There is a high
# chance the command succeeded if the VM exits with a zero exit status
# or, when running with --no-shutdown, by issuing the `query-status` QMP
# command to to confirm the VM status is "shutdown". However, the VM
# could also exit (or set its status to "shutdown") due to other
# or, when running with --no-shutdown, by issuing the `query-status`
# QMP command to to confirm the VM status is "shutdown". However, the
# VM could also exit (or set its status to "shutdown") due to other
# reasons.
#
# Errors:
# - If suspend to disk is not supported, Unsupported
#
# .. note:: It's strongly recommended to issue the `guest-sync` command
# before sending commands when the guest resumes.
# .. note:: It's strongly recommended to issue the `guest-sync`
# command before sending commands when the guest resumes.
#
# Since: 1.1
##
@ -586,7 +587,7 @@
# - manual write into sysfs
#
# IMPORTANT: `guest-suspend-ram` requires working wakeup support in
# QEMU. You should check QMP command `query-current-machine` returns
# QEMU. You should check QMP command `query-current-machine` returns
# wakeup-suspend-support: true before issuing this command. Failure
# in doing so can result in a suspended guest that QEMU will not be
# able to awaken, forcing the user to power cycle the guest to bring
@ -602,8 +603,8 @@
# Errors:
# - If suspend to ram is not supported, Unsupported
#
# .. note:: It's strongly recommended to issue the `guest-sync` command
# before sending commands when the guest resumes.
# .. note:: It's strongly recommended to issue the `guest-sync`
# command before sending commands when the guest resumes.
#
# Since: 1.1
##
@ -622,7 +623,7 @@
# - pm-utils (via pm-suspend-hybrid)
#
# IMPORTANT: `guest-suspend-hybrid` requires working wakeup support in
# QEMU. You should check QMP command `query-current-machine` returns
# QEMU. You should check QMP command `query-current-machine` returns
# wakeup-suspend-support: true before issuing this command. Failure
# in doing so can result in a suspended guest that QEMU will not be
# able to awaken, forcing the user to power cycle the guest to bring
@ -638,8 +639,8 @@
# Errors:
# - If hybrid suspend is not supported, Unsupported
#
# .. note:: It's strongly recommended to issue the `guest-sync` command
# before sending commands when the guest resumes.
# .. note:: It's strongly recommended to issue the `guest-sync`
# command before sending commands when the guest resumes.
#
# Since: 1.1
##
@ -875,7 +876,6 @@
'sas', 'mmc', 'virtual', 'file-backed-virtual', 'nvme' ],
'if': { 'any': [ 'CONFIG_WIN32', 'CONFIG_LINUX' ] } }
##
# @GuestPCIAddress:
#
@ -1048,10 +1048,11 @@
#
# @used-bytes: file system used bytes (since 3.0)
#
# @total-bytes: filesystem capacity in bytes for unprivileged users (since 3.0)
# @total-bytes: filesystem capacity in bytes for unprivileged users
# (since 3.0)
#
# @total-bytes-privileged: filesystem capacity in bytes for privileged users
# (since 9.1)
# @total-bytes-privileged: filesystem capacity in bytes for privileged
# users (since 9.1)
#
# @disk: an array of disk hardware information that the volume lies
# on, which may be empty if the disk type is not supported
@ -1171,7 +1172,8 @@
##
# @GuestMemoryBlockResponse:
#
# @phys-index: same with the 'phys-index' member of `GuestMemoryBlock`.
# @phys-index: same with the 'phys-index' member of
# `GuestMemoryBlock`.
#
# @response: the result of memory block operation.
#
@ -1273,6 +1275,7 @@
'data': { 'exited': 'bool', '*exitcode': 'int', '*signal': 'int',
'*out-data': 'str', '*err-data': 'str',
'*out-truncated': 'bool', '*err-truncated': 'bool' }}
##
# @guest-exec-status:
#
@ -1362,7 +1365,6 @@
'*input-data': 'str', '*capture-output': 'GuestExecCaptureOutput' },
'returns': 'GuestExec' }
##
# @GuestHostName:
#
@ -1389,7 +1391,6 @@
{ 'command': 'guest-get-host-name',
'returns': 'GuestHostName' }
##
# @GuestUser:
#
@ -1491,10 +1492,11 @@
#
# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
# @version, @version-id, @variant and @variant-id follow the
# definition specified in os-release(5). Refer to the manual page for
# exact description of the fields. Their values are taken from the
# os-release file. If the file is not present in the system, or the
# values are not present in the file, the fields are not included.
# definition specified in os-release(5). Refer to the manual page
# for exact description of the fields. Their values are taken from
# the os-release file. If the file is not present in the system,
# or the values are not present in the file, the fields are not
# included.
#
# On Windows the values are filled from information gathered from
# the system.
@ -1639,7 +1641,7 @@
# @guest-ssh-remove-authorized-keys:
#
# Remove public keys from the user .ssh/authorized_keys on Unix
# systems (not implemented for other systems). It's not an error if
# systems (not implemented for other systems). It's not an error if
# the key is already missing.
#
# @username: the user account to remove the authorized keys
@ -1759,7 +1761,6 @@
'data': [ 'linux' ],
'if': 'CONFIG_LINUX' }
##
# @GuestLinuxCpuStats:
#
@ -1834,7 +1835,6 @@
'if': 'CONFIG_LINUX'
}
##
# @GuestLoadAverage:
#
@ -1862,10 +1862,10 @@
#
# Retrieve CPU process load information
#
# .. note:: Windows does not have load average API, so QGA emulates it by
# calculating the average CPU usage in the last 1, 5, 15 minutes
# similar as Linux does this.
# Calculation starts from the first time this command is called.
# .. note:: Windows does not have load average API, so QGA emulates it
# by calculating the average CPU usage in the last 1, 5, 15 minutes
# similar as Linux does this. Calculation starts from the first
# time this command is called.
#
# Returns: load information
#
@ -1881,9 +1881,11 @@
#
# Route information, currently, only linux supported.
#
# @iface: The destination network or host's egress network interface in the routing table
# @iface: The destination network or host's egress network interface
# in the routing table
#
# @destination: The IP address of the target network or host, The final destination of the packet
# @destination: The IP address of the target network or host, The
# final destination of the packet
#
# @metric: Route metric
#
@ -1899,7 +1901,8 @@
#
# @use: Route usage count (not for windows)
#
# @window: TCP window size, used for flow control (not for windows, IPv4 only)
# @window: TCP window size, used for flow control (not for windows,
# IPv4 only)
#
# @mtu: Data link layer maximum packet size (not for windows)
#
@ -1914,7 +1917,6 @@
# @version: IP version (4 or 6)
#
# Since: 9.1
##
{ 'struct': 'GuestNetworkRoute',
'data': {'iface': 'str',

44
scripts/qapi/commands.py
View file

@ -14,15 +14,12 @@ See the COPYING file in the top-level directory.
"""
from typing import (
Dict,
List,
Optional,
Set,
)
from .common import c_name, mcgen
from .gen import (
QAPIGenC,
QAPISchemaModularCVisitor,
build_params,
gen_features,
@ -112,11 +109,7 @@ def gen_call(name: str,
''')
if ret_type:
ret += mcgen('''
qmp_marshal_output_%(c_name)s(retval, ret, errp);
''',
c_name=ret_type.c_name())
ret += gen_marshal_output(ret_type)
if gen_tracing:
if ret_type:
@ -142,22 +135,16 @@ def gen_call(name: str,
def gen_marshal_output(ret_type: QAPISchemaType) -> str:
return mcgen('''
static void qmp_marshal_output_%(c_name)s(%(c_type)s ret_in,
QObject **ret_out, Error **errp)
{
Visitor *v;
v = qobject_output_visitor_new_qmp(ret_out);
if (visit_type_%(c_name)s(v, "unused", &ret_in, errp)) {
visit_complete(v, ret_out);
ov = qobject_output_visitor_new_qmp(ret);
if (visit_type_%(c_name)s(ov, "unused", &retval, errp)) {
visit_complete(ov, ret);
}
visit_free(v);
v = qapi_dealloc_visitor_new();
visit_type_%(c_name)s(v, "unused", &ret_in, NULL);
visit_free(v);
}
visit_free(ov);
ov = qapi_dealloc_visitor_new();
visit_type_%(c_name)s(ov, "unused", &retval, NULL);
visit_free(ov);
''',
c_type=ret_type.c_type(), c_name=ret_type.c_name())
c_name=ret_type.c_name())
def build_marshal_proto(name: str,
@ -209,6 +196,7 @@ def gen_marshal(name: str,
if ret_type:
ret += mcgen('''
%(c_type)s retval;
Visitor *ov;
''',
c_type=ret_type.c_type())
@ -308,11 +296,9 @@ class QAPISchemaGenCommandVisitor(QAPISchemaModularCVisitor):
prefix, 'qapi-commands',
' * Schema-defined QAPI/QMP commands', None, __doc__,
gen_tracing=gen_tracing)
self._visited_ret_types: Dict[QAPIGenC, Set[QAPISchemaType]] = {}
self._gen_tracing = gen_tracing
def _begin_user_module(self, name: str) -> None:
self._visited_ret_types[self._genc] = set()
commands = self._module_basename('qapi-commands', name)
types = self._module_basename('qapi-types', name)
visit = self._module_basename('qapi-visit', name)
@ -386,16 +372,6 @@ void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds)
coroutine: bool) -> None:
if not gen:
return
# FIXME: If T is a user-defined type, the user is responsible
# for making this work, i.e. to make T's condition the
# conjunction of the T-returning commands' conditions. If T
# is a built-in type, this isn't possible: the
# qmp_marshal_output_T() will be generated unconditionally.
if ret_type and ret_type not in self._visited_ret_types[self._genc]:
self._visited_ret_types[self._genc].add(ret_type)
with ifcontext(ret_type.ifcond,
self._genh, self._genc):
self._genc.add(gen_marshal_output(ret_type))
with ifcontext(ifcond, self._genh, self._genc):
self._genh.add(gen_command_decl(name, arg_type, boxed,
ret_type, coroutine))

50
scripts/qapi/parser.py
View file

@ -108,6 +108,11 @@ class QAPISchemaParser:
self.exprs: List[QAPIExpression] = []
self.docs: List[QAPIDoc] = []
# State for tracking qmp-example blocks and simple
# :: literal blocks.
self._literal_mode = False
self._literal_mode_indent = 0
# Showtime!
self._parse()
@ -423,12 +428,55 @@ class QAPISchemaParser:
if self.val != '##':
raise QAPIParseError(
self, "junk after '##' at end of documentation comment")
self._literal_mode = False
return None
if self.val == '#':
return ''
if self.val[1] != ' ':
raise QAPIParseError(self, "missing space after #")
return self.val[2:].rstrip()
line = self.val[2:].rstrip()
if re.match(r'(\.\. +qmp-example)? *::$', line):
self._literal_mode = True
self._literal_mode_indent = 0
elif self._literal_mode and line:
indent = re.match(r'^ *', line).end()
if self._literal_mode_indent == 0:
self._literal_mode_indent = indent
elif indent < self._literal_mode_indent:
# ReST directives stop at decreasing indentation
self._literal_mode = False
if not self._literal_mode:
self._validate_doc_line_format(line)
return line
def _validate_doc_line_format(self, line: str) -> None:
"""
Validate documentation format rules for a single line:
1. Lines should not exceed 70 characters
2. Sentences should be separated by two spaces
"""
full_line_length = len(line) + 2 # "# " = 2 characters
if full_line_length > 70:
# Skip URL lines - they can't be broken
if re.match(r' *(https?|ftp)://[^ ]*$', line):
pass
else:
raise QAPIParseError(
self, "documentation line longer than 70 characters")
single_space_pattern = r'(\be\.g\.|^ *\d\.|([.!?])) [A-Z0-9(]'
for m in list(re.finditer(single_space_pattern, line)):
if not m.group(2):
continue
# HACK so the error message points to the offending spot
self.pos = self.line_pos + 2 + m.start(2) + 1
raise QAPIParseError(
self, "Use two spaces between sentences\n"
"If this not the end of a sentence, please report a bug.")
@staticmethod
def _match_at_name_colon(string: str) -> Optional[Match[str]]:

2
tests/qapi-schema/doc-bad-space-between-sentences.err Normal file
View file

@ -0,0 +1,2 @@
doc-bad-space-between-sentences.json:4:47: Use two spaces between sentences
If this not the end of a sentence, please report a bug.

6
tests/qapi-schema/doc-bad-space-between-sentences.json Normal file
View file

@ -0,0 +1,6 @@
##
# @foo:
#
# Sentences should be separated by two spaces. But here is only one.
##
{ 'command': 'foo' }

0
tests/qapi-schema/doc-bad-space-between-sentences.out Normal file
View file

1
tests/qapi-schema/doc-long-line.err Normal file
View file

@ -0,0 +1 @@
doc-long-line.json:4:1: documentation line longer than 70 characters

6
tests/qapi-schema/doc-long-line.json Normal file
View file

@ -0,0 +1,6 @@
##
# @foo:
#
# This line has exactly 71 chars, including the leading hash and space.
##
{ 'command': 'foo' }

0
tests/qapi-schema/doc-long-line.out Normal file
View file

2
tests/qapi-schema/meson.build
View file

@ -61,6 +61,7 @@ schemas = [
'doc-bad-event-arg.json',
'doc-bad-feature.json',
'doc-bad-indent.json',
'doc-bad-space-between-sentences.json',
'doc-bad-symbol.json',
'doc-bad-union-member.json',
'doc-before-include.json',
@ -81,6 +82,7 @@ schemas = [
'doc-invalid-return2.json',
'doc-invalid-section.json',
'doc-invalid-start.json',
'doc-long-line.json',
'doc-missing-colon.json',
'doc-missing-expr.json',
'doc-missing-space.json',