diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index d97602f464..3a632b4a64 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -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); diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json index ccbfaf828d..da0362a2c0 100644 --- a/docs/interop/firmware.json +++ b/docs/interop/firmware.json @@ -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 # diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json index 095eb99cf7..29c84e86e5 100644 --- a/docs/interop/vhost-user.json +++ b/docs/interop/vhost-user.json @@ -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", diff --git a/docs/meson.build b/docs/meson.build index 3676f81c4d..7e54b01e6a 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -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']) diff --git a/meson.build b/meson.build index b8c1296d3b..48c1795b0f 100644 --- a/meson.build +++ b/meson.build @@ -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' ] diff --git a/qapi/accelerator.json b/qapi/accelerator.json index 2b92060884..0cf5e0f9d9 100644 --- a/qapi/accelerator.json +++ b/qapi/accelerator.json @@ -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 ## diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json index 28af1266a7..a01f1dee09 100644 --- a/qapi/acpi-hest.json +++ b/qapi/acpi-hest.json @@ -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: # diff --git a/qapi/audio.json b/qapi/audio.json index 53142080f7..2df87b9710 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -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 ## diff --git a/qapi/block-core.json b/qapi/block-core.json index 2c037183f0..b82af74256 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -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 # diff --git a/qapi/block-export.json b/qapi/block-export.json index 6878b89dcf..076954ef1a 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -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 ## diff --git a/qapi/char.json b/qapi/char.json index b07e3bb827..140614f82c 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -681,7 +681,6 @@ { 'struct': 'ChardevRingbufWrapper', 'data': { 'data': 'ChardevRingbuf' } } - ## # @ChardevPtyWrapper: # diff --git a/qapi/crypto.json b/qapi/crypto.json index ab6eda4c2f..2b55befef9 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -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: # diff --git a/qapi/cxl.json b/qapi/cxl.json index 52cc5d4f33..eeddb58d1d 100644 --- a/qapi/cxl.json +++ b/qapi/cxl.json @@ -262,7 +262,6 @@ # # Since: 8.0 ## - { 'enum': 'CxlUncorErrorType', 'data': ['cache-data-parity', 'cache-address-parity', diff --git a/qapi/introspect.json b/qapi/introspect.json index 53100714a8..c8432c8ed8 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -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 diff --git a/qapi/job.json b/qapi/job.json index 8b08350af2..0a301fc094 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -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. diff --git a/qapi/machine-common.json b/qapi/machine-common.json index ed3d20a2fb..92e84dfb14 100644 --- a/qapi/machine-common.json +++ b/qapi/machine-common.json @@ -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 diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json index 8412668b67..ea430e1b88 100644 --- a/qapi/machine-s390x.json +++ b/qapi/machine-s390x.json @@ -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: # diff --git a/qapi/machine.json b/qapi/machine.json index c6dc6fe69b..907cb25f75 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -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 `, 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". diff --git a/qapi/migration.json b/qapi/migration.json index 93f71de3fe..6acd9e4b16 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -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:: # diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index d1ce8caf25..05a94d6c41 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -122,7 +122,6 @@ 'sev': 'SevGuestInfo', 'sev-snp': 'SevSnpGuestInfo' } } - ## # @query-sev: # @@ -418,7 +417,6 @@ 'pending': 'bool', 'masked': 'bool'} } - ## # @xen-event-list: # diff --git a/qapi/net.json b/qapi/net.json index 7f62f8cc39..118bd34965 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -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' } } diff --git a/qapi/qdev.json b/qapi/qdev.json index e14a0c9259..974cf9c583 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -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 # diff --git a/qapi/qom.json b/qapi/qom.json index 830cb2ffe7..6f5c9de0f0 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -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: # diff --git a/qapi/run-state.json b/qapi/run-state.json index 4757947ca6..a6bc94a44b 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -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', diff --git a/qapi/sockets.json b/qapi/sockets.json index 32fac51728..473be2ac58 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -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) # diff --git a/qapi/stats.json b/qapi/stats.json index 151ac43c48..a98624531c 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -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). diff --git a/qapi/ui.json b/qapi/ui.json index 1b2f4a4769..e3da77632a 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -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 ## diff --git a/qapi/virtio.json b/qapi/virtio.json index 05295ab665..cd67c4f52e 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -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'] } } diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 8162d888bb..5791b49dde 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -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', diff --git a/scripts/qapi/commands.py b/scripts/qapi/commands.py index 7914227382..a82b5a2a5e 100644 --- a/scripts/qapi/commands.py +++ b/scripts/qapi/commands.py @@ -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)) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 9fbf80a541..1bb1af7051 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -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]]: diff --git a/tests/qapi-schema/doc-bad-space-between-sentences.err b/tests/qapi-schema/doc-bad-space-between-sentences.err new file mode 100644 index 0000000000..479982ce22 --- /dev/null +++ b/tests/qapi-schema/doc-bad-space-between-sentences.err @@ -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. diff --git a/tests/qapi-schema/doc-bad-space-between-sentences.json b/tests/qapi-schema/doc-bad-space-between-sentences.json new file mode 100644 index 0000000000..87b6f6eb4e --- /dev/null +++ b/tests/qapi-schema/doc-bad-space-between-sentences.json @@ -0,0 +1,6 @@ +## +# @foo: +# +# Sentences should be separated by two spaces. But here is only one. +## +{ 'command': 'foo' } diff --git a/tests/qapi-schema/doc-bad-space-between-sentences.out b/tests/qapi-schema/doc-bad-space-between-sentences.out new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/doc-long-line.err b/tests/qapi-schema/doc-long-line.err new file mode 100644 index 0000000000..7baa5297cf --- /dev/null +++ b/tests/qapi-schema/doc-long-line.err @@ -0,0 +1 @@ +doc-long-line.json:4:1: documentation line longer than 70 characters diff --git a/tests/qapi-schema/doc-long-line.json b/tests/qapi-schema/doc-long-line.json new file mode 100644 index 0000000000..c10153b0d5 --- /dev/null +++ b/tests/qapi-schema/doc-long-line.json @@ -0,0 +1,6 @@ +## +# @foo: +# +# This line has exactly 71 chars, including the leading hash and space. +## +{ 'command': 'foo' } diff --git a/tests/qapi-schema/doc-long-line.out b/tests/qapi-schema/doc-long-line.out new file mode 100644 index 0000000000..e69de29bb2 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index c47025d16d..debff633ac 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -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',