preserve-emulation/xemu
1
0
Fork 0
mirror of https://github.com/xemu-project/xemu.git synced 2026-07-11 01:24:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
parent ff0601d128 8107ba47fd
commit d752763d0b
38 changed files with 710 additions and 630 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/devel/qapi-code-gen.rst
+9 -16
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);
docs/interop/firmware.json
+227 -227
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
#
docs/interop/vhost-user.json
+40 -19
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",
docs/meson.build
+7 -2
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'])