[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [qemu RFC v3 3/3] qapi: add "firmware.json"
|
From: |
Laszlo Ersek |
|
Subject: |
Re: [Qemu-devel] [qemu RFC v3 3/3] qapi: add "firmware.json" |
|
Date: |
Thu, 3 May 2018 16:03:37 +0200 |
|
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 |
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" <address@hidden>
> Cc: David Gibson <address@hidden>
> Cc: Eric Blake <address@hidden>
> Cc: Gerd Hoffmann <address@hidden>
> Cc: Kashyap Chamarthy <address@hidden>
> Cc: Markus Armbruster <address@hidden>
> Cc: Paolo Bonzini <address@hidden>
> Cc: Thomas Huth <address@hidden>
> Signed-off-by: Laszlo Ersek <address@hidden>
> ---
>
> Notes:
> RFCv3:
>
> - Previous version (RFCv2) was posted at:
> <http://mid.mail-archive.com/address@hidden>
>
> - 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
> @address@hidden to @SysEmuTarget (now defined in
> "common.json"). [Dan, Gerd, Markus]
>
> - Switch elements of @address@hidden 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 "@address@hidden" 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/address@hidden>
>
> - v2 is basically a rewrite from scratch, starting out with Dan's
> definitions from
> <http://mid.mail-archive.com/address@hidden> and
> <http://mid.mail-archive.com/address@hidden>,
> 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 <address@hidden>
> +# Laszlo Ersek <address@hidden>
> +#
> +# 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 address@hidden,address@hidden". 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,address@hidden@filename,address@hidden@format".
> +#
> +# @nvram-template: Identifies the NVRAM template compatible with
> +# @executable. Management software instantiates an
> +# individual copy -- a specific NVRAM file -- from
> +# @address@hidden for each new virtual
> +# machine definition created. @address@hidden
> +# 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,address@hidden@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]
>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- Re: [Qemu-devel] [qemu RFC v3 3/3] qapi: add "firmware.json",
Laszlo Ersek <=