blob: da0362a2c0e8291c039e344780b47ff868c9f92a [file] [log] [blame]
# -*- 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
# ********
##
{ 'pragma': {
'member-name-exceptions': [
'FirmwareArchitecture' # x86_64
] } }
##
# @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.
#
# @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
#
# Since: 3.0
##
{ 'enum' : 'FirmwareDevice',
'data' : [ 'flash', 'kernel', 'memory', 'igvm' ] }
##
# @FirmwareArchitecture:
#
# Enumeration of architectures for which Qemu uses additional firmware
# files.
#
# @aarch64: 64-bit Arm.
#
# @arm: 32-bit Arm.
#
# @i386: 32-bit x86.
#
# @loongarch64: 64-bit LoongArch. (since: 7.1)
#
# @riscv64: 64-bit RISC-V.
#
# @x86_64: 64-bit x86.
#
# Since: 3.0
##
{ 'enum' : 'FirmwareArchitecture',
'data' : [ 'aarch64', 'arm', 'i386', 'loongarch64', 'riscv64', 'x86_64' ] }
##
# @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' : 'FirmwareArchitecture',
'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/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".
#
# @intel-tdx: The firmware supports running under Intel Trust Domain
# 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.
#
# @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.
#
# @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.
#
# @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.
#
# Since: 3.0
##
{ 'enum' : 'FirmwareFeature',
'data' : [ 'acpi-s3', 'acpi-s4',
'amd-sev', 'amd-sev-es', 'amd-sev-snp',
'intel-tdx',
'enrolled-keys', 'requires-smm',
'secure-boot', 'host-uefi-vars',
'verbose-dynamic', 'verbose-static' ] }
##
# @FirmwareFormat:
#
# Formats that are supported for firmware images.
#
# @raw: Raw disk image format.
#
# @qcow2: The QCOW2 image format.
#
# Since: 3.0
##
{ 'enum': 'FirmwareFormat',
'data': [ 'raw', 'qcow2' ] }
##
# @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' : 'FirmwareFormat' } }
##
# @FirmwareFlashMode:
#
# 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.
#
# @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.
#
# Since: 7.0.0
##
{ 'enum': 'FirmwareFlashMode',
'data': [ 'split', 'combined', 'stateless' ] }
##
# @FirmwareMappingFlash:
#
# Describes loading and mapping properties for the firmware executable
# 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
#
# @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
#
# Since: 3.0
##
{ 'struct' : 'FirmwareMappingFlash',
'data' : { '*mode': 'FirmwareFlashMode',
'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' } }
##
# @FirmwareMappingIgvm:
#
# 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".
#
# Since: 10.1
##
{ 'struct' : 'FirmwareMappingIgvm',
'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',
'igvm' : 'FirmwareMappingIgvm' } }
##
# @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
#
# .. qmp-example::
#
# {
# "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": "OVMF with SEV-ES support",
# "interface-types": [
# "uefi"
# ],
# "mapping": {
# "device": "flash",
# "executable": {
# "filename": "/usr/share/OVMF/OVMF_CODE.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",
# "amd-sev-es",
# "verbose-dynamic"
# ],
# "tags": [
# "-a X64",
# "-p OvmfPkg/OvmfPkgX64.dsc",
# "-t GCC48",
# "-b DEBUG",
# "-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' ] } }