aboutsummaryrefslogtreecommitdiff
path: root/docs/interop
diff options
context:
space:
mode:
Diffstat (limited to 'docs/interop')
-rw-r--r--docs/interop/firmware.json540
1 files changed, 540 insertions, 0 deletions
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
new file mode 100644
index 0000000000..28f9bc1591
--- /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' ] } }