Ping: On 04/21/18 01:12, Laszlo Ersek wrote: > Add a schema that describes the different uses and properties of virtual > machine firmware. > > Each firmware executable installed on a host system should come with at > least one JSON file that conforms to this schema. Each file informs the > management applications about > - the firmware's properties and one possible use case / feature set, > - configuration bits that are required to run the firmware binary. > > In addition, define rules for management apps for picking the highest > priority firmware JSON file when multiple such files match the search > criteria. > > Cc: "Daniel P. Berrange" <berrange@xxxxxxxxxx> > Cc: David Gibson <dgibson@xxxxxxxxxx> > Cc: Eric Blake <eblake@xxxxxxxxxx> > Cc: Gerd Hoffmann <kraxel@xxxxxxxxxx> > Cc: Kashyap Chamarthy <kchamart@xxxxxxxxxx> > Cc: Markus Armbruster <armbru@xxxxxxxxxx> > Cc: Paolo Bonzini <pbonzini@xxxxxxxxxx> > Cc: Thomas Huth <thuth@xxxxxxxxxx> > Signed-off-by: Laszlo Ersek <lersek@xxxxxxxxxx> > --- > > Notes: > RFCv3: > > - Previous version (RFCv2) was posted at: > <http://mid.mail-archive.com/20180417224054.26363-1-lersek@xxxxxxxxxx> > > - Trim the CC list a little. > > - Wrap to a 72-char margin, for an easier reading. [Markus] > > - Run spell-checker. [Markus] > > - Rename @FirmwareType to @FirmwareOSInterface, to better express the > concept. Update the enum constants accordingly (incl. documentation); > in particular replace @slof with @openfirmware. Rename the @type field > in @Firmware to @interface-type. [David, Gerd, Paolo, Thomas] > > - Better yet, rename @interface-type to @interface-types (plural), and > turn it into a list of @FirmwareOSInterface entries, to express an > ordered compat list with multiple firmware<->OS interface types. [Dan, > Eric, Gerd, Paolo] > > - Drop @FirmwareArchitecture, and switch the type of > @FirmwareTarget.@architecture to @SysEmuTarget (now defined in > "common.json"). [Dan, Gerd, Markus] > > - Switch elements of @FirmwareTarget.@machines from aliases ("pc", > "q35", "virt") to concrete machine types, with glob patterns > understood. [Dan, Gerd] > > - Rename @secure-boot-enrolled-keys to @enrolled-keys, and drop the > dependency on @secure-boot in its documentation. [Gerd] > > - Describe the firmware JSON directories and the search rules to > management apps, under the @Firmware element. Relatedly, remove the > language on any concrete certificates under @enrolled-keys, as these > can be customized through the overrides. Also refresh the commit > message. [Dan, Gerd] > > - Rename @pathname fields to @filename. [Markus] > > - Don't replace "@executable.@filename" with "@executable.filename" > (that is, keep the second @ sign), because removing the 2nd @ sign > messes up the documentation ("filename" stops being type-set in > monospace in the HTML, for example). [Markus] > > - Rename @nvram_template to @nvram-template. [Thomas] > > - Keep @x-check-firmware for a while longer. [Dan, Gerd, Markus, Paolo] Any comments on this single patch? Should I post just the schema, identically, for "docs/interop/firmware.json", as a regular PATCH? (Personally I wouldn't like to add any real QAPI integration for this schema. I'm not saying it "shouldn't be done", just that it shouldn't be done by me.) Thanks, Laszlo > RFCv2: > > - previous version (RFCv1) was posted at > <http://mid.mail-archive.com/20180407000117.25640-1-lersek@xxxxxxxxxx> > > - v2 is basically a rewrite from scratch, starting out with Dan's > definitions from > <http://mid.mail-archive.com/20180410102033.GL5155@xxxxxxxxxx> and > <http://mid.mail-archive.com/20180410110357.GP5155@xxxxxxxxxx>, > hopefully addressing others' feedback as well > > RFCv1: > > - Folks on the CC list, please try to see if the suggested schema is > flexible enough to describe the virtual firmware(s) that you are > familiar with. Thanks! > > Makefile | 9 + > Makefile.objs | 4 + > qapi/firmware.json | 554 ++++++++++++++++++++++++++++++++++++++++++++++++++ > qapi/qapi-schema.json | 1 + > qmp.c | 5 + > .gitignore | 4 + > 6 files changed, 577 insertions(+) > create mode 100644 qapi/firmware.json > > diff --git a/Makefile b/Makefile > index d71dd5bea416..32034abe1583 100644 > --- a/Makefile > +++ b/Makefile > @@ -97,6 +97,7 @@ GENERATED_FILES += qapi/qapi-types-block.h qapi/qapi-types-block.c > GENERATED_FILES += qapi/qapi-types-char.h qapi/qapi-types-char.c > GENERATED_FILES += qapi/qapi-types-common.h qapi/qapi-types-common.c > GENERATED_FILES += qapi/qapi-types-crypto.h qapi/qapi-types-crypto.c > +GENERATED_FILES += qapi/qapi-types-firmware.h qapi/qapi-types-firmware.c > GENERATED_FILES += qapi/qapi-types-introspect.h qapi/qapi-types-introspect.c > GENERATED_FILES += qapi/qapi-types-migration.h qapi/qapi-types-migration.c > GENERATED_FILES += qapi/qapi-types-misc.h qapi/qapi-types-misc.c > @@ -115,6 +116,7 @@ GENERATED_FILES += qapi/qapi-visit-block.h qapi/qapi-visit-block.c > GENERATED_FILES += qapi/qapi-visit-char.h qapi/qapi-visit-char.c > GENERATED_FILES += qapi/qapi-visit-common.h qapi/qapi-visit-common.c > GENERATED_FILES += qapi/qapi-visit-crypto.h qapi/qapi-visit-crypto.c > +GENERATED_FILES += qapi/qapi-visit-firmware.h qapi/qapi-visit-firmware.c > GENERATED_FILES += qapi/qapi-visit-introspect.h qapi/qapi-visit-introspect.c > GENERATED_FILES += qapi/qapi-visit-migration.h qapi/qapi-visit-migration.c > GENERATED_FILES += qapi/qapi-visit-misc.h qapi/qapi-visit-misc.c > @@ -132,6 +134,7 @@ GENERATED_FILES += qapi/qapi-commands-block.h qapi/qapi-commands-block.c > GENERATED_FILES += qapi/qapi-commands-char.h qapi/qapi-commands-char.c > GENERATED_FILES += qapi/qapi-commands-common.h qapi/qapi-commands-common.c > GENERATED_FILES += qapi/qapi-commands-crypto.h qapi/qapi-commands-crypto.c > +GENERATED_FILES += qapi/qapi-commands-firmware.h qapi/qapi-commands-firmware.c > GENERATED_FILES += qapi/qapi-commands-introspect.h qapi/qapi-commands-introspect.c > GENERATED_FILES += qapi/qapi-commands-migration.h qapi/qapi-commands-migration.c > GENERATED_FILES += qapi/qapi-commands-misc.h qapi/qapi-commands-misc.c > @@ -149,6 +152,7 @@ GENERATED_FILES += qapi/qapi-events-block.h qapi/qapi-events-block.c > GENERATED_FILES += qapi/qapi-events-char.h qapi/qapi-events-char.c > GENERATED_FILES += qapi/qapi-events-common.h qapi/qapi-events-common.c > GENERATED_FILES += qapi/qapi-events-crypto.h qapi/qapi-events-crypto.c > +GENERATED_FILES += qapi/qapi-events-firmware.h qapi/qapi-events-firmware.c > GENERATED_FILES += qapi/qapi-events-introspect.h qapi/qapi-events-introspect.c > GENERATED_FILES += qapi/qapi-events-migration.h qapi/qapi-events-migration.c > GENERATED_FILES += qapi/qapi-events-misc.h qapi/qapi-events-misc.c > @@ -581,6 +585,7 @@ qapi-modules = $(SRC_PATH)/qapi/qapi-schema.json $(SRC_PATH)/qapi/common.json \ > $(SRC_PATH)/qapi/block.json $(SRC_PATH)/qapi/block-core.json \ > $(SRC_PATH)/qapi/char.json \ > $(SRC_PATH)/qapi/crypto.json \ > + $(SRC_PATH)/qapi/firmware.json \ > $(SRC_PATH)/qapi/introspect.json \ > $(SRC_PATH)/qapi/migration.json \ > $(SRC_PATH)/qapi/misc.json \ > @@ -600,6 +605,7 @@ qapi/qapi-types-block.c qapi/qapi-types-block.h \ > qapi/qapi-types-char.c qapi/qapi-types-char.h \ > qapi/qapi-types-common.c qapi/qapi-types-common.h \ > qapi/qapi-types-crypto.c qapi/qapi-types-crypto.h \ > +qapi/qapi-types-firmware.c qapi/qapi-types-firmware.h \ > qapi/qapi-types-introspect.c qapi/qapi-types-introspect.h \ > qapi/qapi-types-migration.c qapi/qapi-types-migration.h \ > qapi/qapi-types-misc.c qapi/qapi-types-misc.h \ > @@ -618,6 +624,7 @@ qapi/qapi-visit-block.c qapi/qapi-visit-block.h \ > qapi/qapi-visit-char.c qapi/qapi-visit-char.h \ > qapi/qapi-visit-common.c qapi/qapi-visit-common.h \ > qapi/qapi-visit-crypto.c qapi/qapi-visit-crypto.h \ > +qapi/qapi-visit-firmware.c qapi/qapi-visit-firmware.h \ > qapi/qapi-visit-introspect.c qapi/qapi-visit-introspect.h \ > qapi/qapi-visit-migration.c qapi/qapi-visit-migration.h \ > qapi/qapi-visit-misc.c qapi/qapi-visit-misc.h \ > @@ -635,6 +642,7 @@ qapi/qapi-commands-block.c qapi/qapi-commands-block.h \ > qapi/qapi-commands-char.c qapi/qapi-commands-char.h \ > qapi/qapi-commands-common.c qapi/qapi-commands-common.h \ > qapi/qapi-commands-crypto.c qapi/qapi-commands-crypto.h \ > +qapi/qapi-commands-firmware.c qapi/qapi-commands-firmware.h \ > qapi/qapi-commands-introspect.c qapi/qapi-commands-introspect.h \ > qapi/qapi-commands-migration.c qapi/qapi-commands-migration.h \ > qapi/qapi-commands-misc.c qapi/qapi-commands-misc.h \ > @@ -652,6 +660,7 @@ qapi/qapi-events-block.c qapi/qapi-events-block.h \ > qapi/qapi-events-char.c qapi/qapi-events-char.h \ > qapi/qapi-events-common.c qapi/qapi-events-common.h \ > qapi/qapi-events-crypto.c qapi/qapi-events-crypto.h \ > +qapi/qapi-events-firmware.c qapi/qapi-events-firmware.h \ > qapi/qapi-events-introspect.c qapi/qapi-events-introspect.h \ > qapi/qapi-events-migration.c qapi/qapi-events-migration.h \ > qapi/qapi-events-misc.c qapi/qapi-events-misc.h \ > diff --git a/Makefile.objs b/Makefile.objs > index c6c9b8fc2177..6ed4e0010b10 100644 > --- a/Makefile.objs > +++ b/Makefile.objs > @@ -9,6 +9,7 @@ util-obj-y += qapi/qapi-types-block.o > util-obj-y += qapi/qapi-types-char.o > util-obj-y += qapi/qapi-types-common.o > util-obj-y += qapi/qapi-types-crypto.o > +util-obj-y += qapi/qapi-types-firmware.o > util-obj-y += qapi/qapi-types-introspect.o > util-obj-y += qapi/qapi-types-migration.o > util-obj-y += qapi/qapi-types-misc.o > @@ -27,6 +28,7 @@ util-obj-y += qapi/qapi-visit-block.o > util-obj-y += qapi/qapi-visit-char.o > util-obj-y += qapi/qapi-visit-common.o > util-obj-y += qapi/qapi-visit-crypto.o > +util-obj-y += qapi/qapi-visit-firmware.o > util-obj-y += qapi/qapi-visit-introspect.o > util-obj-y += qapi/qapi-visit-migration.o > util-obj-y += qapi/qapi-visit-misc.o > @@ -44,6 +46,7 @@ util-obj-y += qapi/qapi-events-block.o > util-obj-y += qapi/qapi-events-char.o > util-obj-y += qapi/qapi-events-common.o > util-obj-y += qapi/qapi-events-crypto.o > +util-obj-y += qapi/qapi-events-firmware.o > util-obj-y += qapi/qapi-events-introspect.o > util-obj-y += qapi/qapi-events-migration.o > util-obj-y += qapi/qapi-events-misc.o > @@ -139,6 +142,7 @@ common-obj-y += qapi/qapi-commands-block.o > common-obj-y += qapi/qapi-commands-char.o > common-obj-y += qapi/qapi-commands-common.o > common-obj-y += qapi/qapi-commands-crypto.o > +common-obj-y += qapi/qapi-commands-firmware.o > common-obj-y += qapi/qapi-commands-introspect.o > common-obj-y += qapi/qapi-commands-migration.o > common-obj-y += qapi/qapi-commands-misc.o > diff --git a/qapi/firmware.json b/qapi/firmware.json > new file mode 100644 > index 000000000000..2add6fd8afe7 > --- /dev/null > +++ b/qapi/firmware.json > @@ -0,0 +1,554 @@ > +# -*- Mode: Python -*- > +# > +# Copyright (C) 2018 Red Hat, Inc. > +# > +# Authors: > +# Daniel P. Berrange <berrange@xxxxxxxxxx> > +# Laszlo Ersek <lersek@xxxxxxxxxx> > +# > +# This work is licensed under the terms of the GNU GPL, version 2 or > +# later. See the COPYING file in the top-level directory. > + > +## > +# = Firmware > +## > + > +{ 'include' : 'common.json' } > +{ 'include' : 'block-core.json' } > + > +## > +# @FirmwareOSInterface: > +# > +# 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. > +# > +# @openfirmware: The interface is defined by the (historical) IEEE > +# 1275-1994 standard. Examples for firmware projects that > +# provide this interface are: OpenBIOS, OpenHackWare, > +# 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. > +# > +# Since: 2.13 > +## > +{ 'enum' : 'FirmwareOSInterface', > + 'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] } > + > +## > +# @FirmwareDevice: > +# > +# 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. > +# > +# @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. > +# > +# Since: 2.13 > +## > +{ 'enum' : 'FirmwareDevice', > + 'data' : [ 'flash', 'kernel', 'memory' ] } > + > +## > +# @FirmwareTarget: > +# > +# Defines the machine types that firmware may execute on. > +# > +# @architecture: Determines the emulation target (the QEMU system > +# 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). > +# > +# Since: 2.13 > +## > +{ 'struct' : 'FirmwareTarget', > + 'data' : { 'architecture' : 'SysEmuTarget', > + 'machines' : [ 'str' ] } } > + > +## > +# @FirmwareFeature: > +# > +# 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-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". > +# > +# @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/amd-memory-encryption.txt". > +# > +# @enrolled-keys: The variable store (NVRAM) template associated with > +# 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".) 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. > +# > +# @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. > +# > +# @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. > +# > +# Since: 2.13 > +## > +{ 'enum' : 'FirmwareFeature', > + 'data' : [ 'acpi-s3', 'acpi-s4', 'amd-sev', 'enrolled-keys', > + 'requires-smm', 'secure-boot', 'verbose-dynamic', > + 'verbose-static' ] } > + > +## > +# @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 > +# 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. > +# > +# @format: Specifies the block format of the file pointed-to by > +# @filename, such as @raw or @qcow2. > +# > +# Since: 2.13 > +## > +{ 'struct' : 'FirmwareFlashFile', > + 'data' : { 'filename' : 'str', > + 'format' : 'BlockdevDriver' } } > + > +## > +# @FirmwareMappingFlash: > +# > +# Describes loading and mapping properties for the firmware executable > +# and its accompanying NVRAM file, when @FirmwareDevice is @flash. > +# > +# @executable: Identifies the firmware executable. The firmware > +# executable may be shared by multiple virtual machine > +# definitions. The corresponding QEMU command line option > +# is "-drive > +# if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format". > +# > +# @nvram-template: Identifies the NVRAM template compatible with > +# @executable. 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 corresponding QEMU command line > +# option is "-drive > +# if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format". > +# > +# Since: 2.13 > +## > +{ 'struct' : 'FirmwareMappingFlash', > + 'data' : { 'executable' : 'FirmwareFlashFile', > + 'nvram-template' : 'FirmwareFlashFile' } } > + > +## > +# @FirmwareMappingKernel: > +# > +# 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". > +# > +# Since: 2.13 > +## > +{ 'struct' : 'FirmwareMappingKernel', > + 'data' : { 'filename' : 'str' } } > + > +## > +# @FirmwareMappingMemory: > +# > +# 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". > +# > +# Since: 2.13 > +## > +{ 'struct' : 'FirmwareMappingMemory', > + 'data' : { 'filename' : 'str' } } > + > +## > +# @FirmwareMapping: > +# > +# Provides a discriminated structure for firmware to describe its > +# loading / mapping properties. > +# > +# @device: Selects the device type that the firmware must be mapped > +# into. > +# > +# Since: 2.13 > +## > +{ 'union' : 'FirmwareMapping', > + 'base' : { 'device' : 'FirmwareDevice' }, > + 'discriminator' : 'device', > + 'data' : { 'flash' : 'FirmwareMappingFlash', > + 'kernel' : 'FirmwareMappingKernel', > + 'memory' : 'FirmwareMappingMemory' } } > + > +## > +# @Firmware: > +# > +# 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. > +# > +# 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: > +# > +# - /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, > +# > +# - $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. > +# > +# For example, if a distro ships > +# > +# - /usr/share/qemu/firmware/50-ovmf.json > +# > +# - /usr/share/qemu/firmware/50-seabios-256k.json > +# > +# then the sysadmin can prevent the default OVMF being used at all with > +# > +# $ touch /etc/qemu/firmware/50-ovmf.json > +# > +# The sysadmin can replace/alter the distro default OVMF with > +# > +# $ vim /etc/qemu/firmware/50-ovmf.json > +# > +# or they can provide a parallel OVMF with higher priority > +# > +# $ vim /etc/qemu/firmware/10-ovmf.json > +# > +# or they can provide a parallel OVMF with lower priority > +# > +# $ vim /etc/qemu/firmware/99-ovmf.json > +# > +# @description: Provides a human-readable description of the firmware. > +# 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. > +# > +# @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. > +# > +# @features: Lists the features that the firmware supports, and the > +# 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. > +# > +# Since: 2.13 > +# > +# Examples: > +# > +# { > +# "description": "SeaBIOS", > +# "interface-types": [ > +# "bios" > +# ], > +# "mapping": { > +# "device": "memory", > +# "filename": "/usr/share/seabios/bios-256k.bin" > +# }, > +# "targets": [ > +# { > +# "architecture": "i386", > +# "machines": [ > +# "pc-i440fx-*", > +# "pc-q35-*" > +# ] > +# }, > +# { > +# "architecture": "x86_64", > +# "machines": [ > +# "pc-i440fx-*", > +# "pc-q35-*" > +# ] > +# } > +# ], > +# "features": [ > +# "acpi-s3", > +# "acpi-s4" > +# ], > +# "tags": [ > +# "CONFIG_BOOTSPLASH=n", > +# "CONFIG_ROM_SIZE=256", > +# "CONFIG_USE_SMM=n" > +# ] > +# } > +# > +# { > +# "description": "OVMF with SB+SMM, empty varstore", > +# "interface-types": [ > +# "uefi" > +# ], > +# "mapping": { > +# "device": "flash", > +# "executable": { > +# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", > +# "format": "raw" > +# }, > +# "nvram-template": { > +# "filename": "/usr/share/OVMF/OVMF_VARS.fd", > +# "format": "raw" > +# } > +# }, > +# "targets": [ > +# { > +# "architecture": "x86_64", > +# "machines": [ > +# "pc-q35-*" > +# ] > +# } > +# ], > +# "features": [ > +# "acpi-s3", > +# "amd-sev", > +# "requires-smm", > +# "secure-boot", > +# "verbose-dynamic" > +# ], > +# "tags": [ > +# "-a IA32", > +# "-a X64", > +# "-p OvmfPkg/OvmfPkgIa32X64.dsc", > +# "-t GCC48", > +# "-b DEBUG", > +# "-D SMM_REQUIRE", > +# "-D SECURE_BOOT_ENABLE", > +# "-D FD_SIZE_4MB" > +# ] > +# } > +# > +# { > +# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled", > +# "interface-types": [ > +# "uefi" > +# ], > +# "mapping": { > +# "device": "flash", > +# "executable": { > +# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", > +# "format": "raw" > +# }, > +# "nvram-template": { > +# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd", > +# "format": "raw" > +# } > +# }, > +# "targets": [ > +# { > +# "architecture": "x86_64", > +# "machines": [ > +# "pc-q35-*" > +# ] > +# } > +# ], > +# "features": [ > +# "acpi-s3", > +# "amd-sev", > +# "enrolled-keys", > +# "requires-smm", > +# "secure-boot", > +# "verbose-dynamic" > +# ], > +# "tags": [ > +# "-a IA32", > +# "-a X64", > +# "-p OvmfPkg/OvmfPkgIa32X64.dsc", > +# "-t GCC48", > +# "-b DEBUG", > +# "-D SMM_REQUIRE", > +# "-D SECURE_BOOT_ENABLE", > +# "-D FD_SIZE_4MB" > +# ] > +# } > +# > +# { > +# "description": "UEFI firmware for ARM64 virtual machines", > +# "interface-types": [ > +# "uefi" > +# ], > +# "mapping": { > +# "device": "flash", > +# "executable": { > +# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd", > +# "format": "raw" > +# }, > +# "nvram-template": { > +# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd", > +# "format": "raw" > +# } > +# }, > +# "targets": [ > +# { > +# "architecture": "aarch64", > +# "machines": [ > +# "virt-*" > +# ] > +# } > +# ], > +# "features": [ > +# > +# ], > +# "tags": [ > +# "-a AARCH64", > +# "-p ArmVirtPkg/ArmVirtQemu.dsc", > +# "-t GCC48", > +# "-b DEBUG", > +# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" > +# ] > +# } > +## > +{ 'struct' : 'Firmware', > + 'data' : { 'description' : 'str', > + 'interface-types' : [ 'FirmwareOSInterface' ], > + 'mapping' : 'FirmwareMapping', > + 'targets' : [ 'FirmwareTarget' ], > + 'features' : [ 'FirmwareFeature' ], > + 'tags' : [ 'str' ] } } > + > +## > +# @x-check-firmware: > +# > +# Accept a @Firmware object and do nothing, successfully. This command > +# can be used in the QMP shell to validate @Firmware JSON against the > +# schema. > +# > +# @fw: ignored > +# > +# Since: 2.13 > +## > +{ 'command' : 'x-check-firmware', > + 'data' : { 'fw' : 'Firmware' } } > diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json > index 25bce78352b8..2d6339ca8c99 100644 > --- a/qapi/qapi-schema.json > +++ b/qapi/qapi-schema.json > @@ -92,4 +92,5 @@ > { 'include': 'transaction.json' } > { 'include': 'trace.json' } > { 'include': 'introspect.json' } > +{ 'include': 'firmware.json' } > { 'include': 'misc.json' } > diff --git a/qmp.c b/qmp.c > index f72261667f92..2141ebe6f027 100644 > --- a/qmp.c > +++ b/qmp.c > @@ -34,6 +34,7 @@ > #include "qapi/qapi-commands-block-core.h" > #include "qapi/qapi-commands-misc.h" > #include "qapi/qapi-commands-ui.h" > +#include "qapi/qapi-commands-firmware.h" > #include "qapi/qmp/qdict.h" > #include "qapi/qmp/qerror.h" > #include "qapi/qobject-input-visitor.h" > @@ -781,3 +782,7 @@ void qmp_x_oob_test(bool lock, Error **errp) > qemu_sem_post(&x_oob_test_sem); > } > } > + > +void qmp_x_check_firmware(Firmware *fw, Error **errp) > +{ > +} > diff --git a/.gitignore b/.gitignore > index 4055e12ee85d..1d8d1066d3d1 100644 > --- a/.gitignore > +++ b/.gitignore > @@ -35,6 +35,7 @@ > /qapi/qapi-commands-char.[ch] > /qapi/qapi-commands-common.[ch] > /qapi/qapi-commands-crypto.[ch] > +/qapi/qapi-commands-firmware.[ch] > /qapi/qapi-commands-introspect.[ch] > /qapi/qapi-commands-migration.[ch] > /qapi/qapi-commands-misc.[ch] > @@ -52,6 +53,7 @@ > /qapi/qapi-events-char.[ch] > /qapi/qapi-events-common.[ch] > /qapi/qapi-events-crypto.[ch] > +/qapi/qapi-events-firmware.[ch] > /qapi/qapi-events-introspect.[ch] > /qapi/qapi-events-migration.[ch] > /qapi/qapi-events-misc.[ch] > @@ -70,6 +72,7 @@ > /qapi/qapi-types-char.[ch] > /qapi/qapi-types-common.[ch] > /qapi/qapi-types-crypto.[ch] > +/qapi/qapi-types-firmware.[ch] > /qapi/qapi-types-introspect.[ch] > /qapi/qapi-types-migration.[ch] > /qapi/qapi-types-misc.[ch] > @@ -87,6 +90,7 @@ > /qapi/qapi-visit-char.[ch] > /qapi/qapi-visit-common.[ch] > /qapi/qapi-visit-crypto.[ch] > +/qapi/qapi-visit-firmware.[ch] > /qapi/qapi-visit-introspect.[ch] > /qapi/qapi-visit-migration.[ch] > /qapi/qapi-visit-misc.[ch] > -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
