# -*- Mode: Python -*-
# vim: filetype=python
#
# Copyright (C) 2018 Red Hat, Inc.
#
# Authors:
# Daniel P. Berrange <berrange@redhat.com>
# Laszlo Ersek <lersek@redhat.com>
#
# 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' : 'machine.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 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.
#
# Since: 3.0
##
{ '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: 3.0
##
{ '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: 3.0
##
{ '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: 3.0
##
{ '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: 3.0
##
{ '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 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.
# 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. 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
##
{ '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: 3.0
##
{ '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: 3.0
##
{ '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: 3.0
##
{ '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: 3.0
#
# 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' ] } }
