diff options
Diffstat (limited to 'docs/interop/firmware.json')
| -rw-r--r-- | docs/interop/firmware.json | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json new file mode 100644 index 0000000..28f9bc1 --- /dev/null +++ b/docs/interop/firmware.json @@ -0,0 +1,540 @@ +# -*- Mode: 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' : '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: 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 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: 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' ] } } |