1# -*- Mode: Python -*- 2# 3# Copyright (C) 2018 Red Hat, Inc. 4# 5# Authors: 6# Daniel P. Berrange <berrange@redhat.com> 7# Laszlo Ersek <lersek@redhat.com> 8# 9# This work is licensed under the terms of the GNU GPL, version 2 or 10# later. See the COPYING file in the top-level directory. 11 12## 13# = Firmware 14## 15 16{ 'include' : 'common.json' } 17{ 'include' : 'block-core.json' } 18 19## 20# @FirmwareOSInterface: 21# 22# Lists the firmware-OS interface types provided by various firmware 23# that is commonly used with QEMU virtual machines. 24# 25# @bios: Traditional x86 BIOS interface. For example, firmware built 26# from the SeaBIOS project usually provides this interface. 27# 28# @openfirmware: The interface is defined by the (historical) IEEE 29# 1275-1994 standard. Examples for firmware projects that 30# provide this interface are: OpenBIOS, OpenHackWare, 31# SLOF. 32# 33# @uboot: Firmware interface defined by the U-Boot project. 34# 35# @uefi: Firmware interface defined by the UEFI specification. For 36# example, firmware built from the edk2 (EFI Development Kit II) 37# project usually provides this interface. 38# 39# Since: 3.0 40## 41{ 'enum' : 'FirmwareOSInterface', 42 'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] } 43 44## 45# @FirmwareDevice: 46# 47# Defines the device types that firmware can be mapped into. 48# 49# @flash: The firmware executable and its accompanying NVRAM file are to 50# be mapped into a pflash chip each. 51# 52# @kernel: The firmware is to be loaded like a Linux kernel. This is 53# similar to @memory but may imply additional processing that 54# is specific to the target architecture and machine type. 55# 56# @memory: The firmware is to be mapped into memory. 57# 58# Since: 3.0 59## 60{ 'enum' : 'FirmwareDevice', 61 'data' : [ 'flash', 'kernel', 'memory' ] } 62 63## 64# @FirmwareTarget: 65# 66# Defines the machine types that firmware may execute on. 67# 68# @architecture: Determines the emulation target (the QEMU system 69# emulator) that can execute the firmware. 70# 71# @machines: Lists the machine types (known by the emulator that is 72# specified through @architecture) that can execute the 73# firmware. Elements of @machines are supposed to be concrete 74# machine types, not aliases. Glob patterns are understood, 75# which is especially useful for versioned machine types. 76# (For example, the glob pattern "pc-i440fx-*" matches 77# "pc-i440fx-2.12".) On the QEMU command line, "-machine 78# type=..." specifies the requested machine type (but that 79# option does not accept glob patterns). 80# 81# Since: 3.0 82## 83{ 'struct' : 'FirmwareTarget', 84 'data' : { 'architecture' : 'SysEmuTarget', 85 'machines' : [ 'str' ] } } 86 87## 88# @FirmwareFeature: 89# 90# Defines the features that firmware may support, and the platform 91# requirements that firmware may present. 92# 93# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined 94# in the ACPI specification. On the "pc-i440fx-*" machine 95# types of the @i386 and @x86_64 emulation targets, S3 can be 96# enabled with "-global PIIX4_PM.disable_s3=0" and disabled 97# with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*" 98# machine types of the @i386 and @x86_64 emulation targets, S3 99# can be enabled with "-global ICH9-LPC.disable_s3=0" and 100# disabled with "-global ICH9-LPC.disable_s3=1". 101# 102# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as 103# defined in the ACPI specification. On the "pc-i440fx-*" 104# machine types of the @i386 and @x86_64 emulation targets, S4 105# can be enabled with "-global PIIX4_PM.disable_s4=0" and 106# disabled with "-global PIIX4_PM.disable_s4=1". On the 107# "pc-q35-*" machine types of the @i386 and @x86_64 emulation 108# targets, S4 can be enabled with "-global 109# ICH9-LPC.disable_s4=0" and disabled with "-global 110# ICH9-LPC.disable_s4=1". 111# 112# @amd-sev: The firmware supports running under AMD Secure Encrypted 113# Virtualization, as specified in the AMD64 Architecture 114# Programmer's Manual. QEMU command line options related to 115# this feature are documented in 116# "docs/amd-memory-encryption.txt". 117# 118# @enrolled-keys: The variable store (NVRAM) template associated with 119# the firmware binary has the UEFI Secure Boot 120# operational mode turned on, with certificates 121# enrolled. 122# 123# @requires-smm: The firmware requires the platform to emulate SMM 124# (System Management Mode), as defined in the AMD64 125# Architecture Programmer's Manual, and in the Intel(R)64 126# and IA-32 Architectures Software Developer's Manual. On 127# the "pc-q35-*" machine types of the @i386 and @x86_64 128# emulation targets, SMM emulation can be enabled with 129# "-machine smm=on". (On the "pc-q35-*" machine types of 130# the @i386 emulation target, @requires-smm presents 131# further CPU requirements; one combination known to work 132# is "-cpu coreduo,-nx".) If the firmware is marked as 133# both @secure-boot and @requires-smm, then write 134# accesses to the pflash chip (NVRAM) that holds the UEFI 135# variable store must be restricted to code that executes 136# in SMM, using the additional option "-global 137# driver=cfi.pflash01,property=secure,value=on". 138# Furthermore, a large guest-physical address space 139# (comprising guest RAM, memory hotplug range, and 64-bit 140# PCI MMIO aperture), and/or a high VCPU count, may 141# present high SMRAM requirements from the firmware. On 142# the "pc-q35-*" machine types of the @i386 and @x86_64 143# emulation targets, the SMRAM size may be increased 144# above the default 16MB with the "-global 145# mch.extended-tseg-mbytes=uint16" option. As a rule of 146# thumb, the default 16MB size suffices for 1TB of 147# guest-phys address space and a few tens of VCPUs; for 148# every further TB of guest-phys address space, add 8MB 149# of SMRAM. 48MB should suffice for 4TB of guest-phys 150# address space and 2-3 hundred VCPUs. 151# 152# @secure-boot: The firmware implements the software interfaces for UEFI 153# Secure Boot, as defined in the UEFI specification. Note 154# that without @requires-smm, guest code running with 155# kernel privileges can undermine the security of Secure 156# Boot. 157# 158# @verbose-dynamic: When firmware log capture is enabled, the firmware 159# logs a large amount of debug messages, which may 160# impact boot performance. With log capture disabled, 161# there is no boot performance impact. On the 162# "pc-i440fx-*" and "pc-q35-*" machine types of the 163# @i386 and @x86_64 emulation targets, firmware log 164# capture can be enabled with the QEMU command line 165# options "-chardev file,id=fwdebug,path=LOGFILEPATH 166# -device isa-debugcon,iobase=0x402,chardev=fwdebug". 167# @verbose-dynamic is mutually exclusive with 168# @verbose-static. 169# 170# @verbose-static: The firmware unconditionally produces a large amount 171# of debug messages, which may impact boot performance. 172# This feature may typically be carried by certain UEFI 173# firmware for the "virt-*" machine types of the @arm 174# and @aarch64 emulation targets, where the debug 175# messages are written to the first (always present) 176# PL011 UART. @verbose-static is mutually exclusive 177# with @verbose-dynamic. 178# 179# Since: 3.0 180## 181{ 'enum' : 'FirmwareFeature', 182 'data' : [ 'acpi-s3', 'acpi-s4', 'amd-sev', 'enrolled-keys', 183 'requires-smm', 'secure-boot', 'verbose-dynamic', 184 'verbose-static' ] } 185 186## 187# @FirmwareFlashFile: 188# 189# Defines common properties that are necessary for loading a firmware 190# file into a pflash chip. The corresponding QEMU command line option is 191# "-drive file=@filename,format=@format". Note however that the 192# option-argument shown here is incomplete; it is completed under 193# @FirmwareMappingFlash. 194# 195# @filename: Specifies the filename on the host filesystem where the 196# firmware file can be found. 197# 198# @format: Specifies the block format of the file pointed-to by 199# @filename, such as @raw or @qcow2. 200# 201# Since: 3.0 202## 203{ 'struct' : 'FirmwareFlashFile', 204 'data' : { 'filename' : 'str', 205 'format' : 'BlockdevDriver' } } 206 207## 208# @FirmwareMappingFlash: 209# 210# Describes loading and mapping properties for the firmware executable 211# and its accompanying NVRAM file, when @FirmwareDevice is @flash. 212# 213# @executable: Identifies the firmware executable. The firmware 214# executable may be shared by multiple virtual machine 215# definitions. The corresponding QEMU command line option 216# is "-drive 217# if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format". 218# 219# @nvram-template: Identifies the NVRAM template compatible with 220# @executable. Management software instantiates an 221# individual copy -- a specific NVRAM file -- from 222# @nvram-template.@filename for each new virtual 223# machine definition created. @nvram-template.@filename 224# itself is never mapped into virtual machines, only 225# individual copies of it are. An NVRAM file is 226# typically used for persistently storing the 227# non-volatile UEFI variables of a virtual machine 228# definition. The corresponding QEMU command line 229# option is "-drive 230# if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format". 231# 232# Since: 3.0 233## 234{ 'struct' : 'FirmwareMappingFlash', 235 'data' : { 'executable' : 'FirmwareFlashFile', 236 'nvram-template' : 'FirmwareFlashFile' } } 237 238## 239# @FirmwareMappingKernel: 240# 241# Describes loading and mapping properties for the firmware executable, 242# when @FirmwareDevice is @kernel. 243# 244# @filename: Identifies the firmware executable. The firmware executable 245# may be shared by multiple virtual machine definitions. The 246# corresponding QEMU command line option is "-kernel 247# @filename". 248# 249# Since: 3.0 250## 251{ 'struct' : 'FirmwareMappingKernel', 252 'data' : { 'filename' : 'str' } } 253 254## 255# @FirmwareMappingMemory: 256# 257# Describes loading and mapping properties for the firmware executable, 258# when @FirmwareDevice is @memory. 259# 260# @filename: Identifies the firmware executable. The firmware executable 261# may be shared by multiple virtual machine definitions. The 262# corresponding QEMU command line option is "-bios 263# @filename". 264# 265# Since: 3.0 266## 267{ 'struct' : 'FirmwareMappingMemory', 268 'data' : { 'filename' : 'str' } } 269 270## 271# @FirmwareMapping: 272# 273# Provides a discriminated structure for firmware to describe its 274# loading / mapping properties. 275# 276# @device: Selects the device type that the firmware must be mapped 277# into. 278# 279# Since: 3.0 280## 281{ 'union' : 'FirmwareMapping', 282 'base' : { 'device' : 'FirmwareDevice' }, 283 'discriminator' : 'device', 284 'data' : { 'flash' : 'FirmwareMappingFlash', 285 'kernel' : 'FirmwareMappingKernel', 286 'memory' : 'FirmwareMappingMemory' } } 287 288## 289# @Firmware: 290# 291# Describes a firmware (or a firmware use case) to management software. 292# 293# It is possible for multiple @Firmware elements to match the search 294# criteria of management software. Applications thus need rules to pick 295# one of the many matches, and users need the ability to override distro 296# defaults. 297# 298# It is recommended to create firmware JSON files (each containing a 299# single @Firmware root element) with a double-digit prefix, for example 300# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in 301# predictable order. The firmware JSON files should be searched for in 302# three directories: 303# 304# - /usr/share/qemu/firmware -- populated by distro-provided firmware 305# packages (XDG_DATA_DIRS covers 306# /usr/share by default), 307# 308# - /etc/qemu/firmware -- exclusively for sysadmins' local additions, 309# 310# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local 311# additions (XDG_CONFIG_HOME 312# defaults to $HOME/.config). 313# 314# Top-down, the list of directories goes from general to specific. 315# 316# Management software should build a list of files from all three 317# locations, then sort the list by filename (i.e., last pathname 318# component). Management software should choose the first JSON file on 319# the sorted list that matches the search criteria. If a more specific 320# directory has a file with same name as a less specific directory, then 321# the file in the more specific directory takes effect. If the more 322# specific file is zero length, it hides the less specific one. 323# 324# For example, if a distro ships 325# 326# - /usr/share/qemu/firmware/50-ovmf.json 327# 328# - /usr/share/qemu/firmware/50-seabios-256k.json 329# 330# then the sysadmin can prevent the default OVMF being used at all with 331# 332# $ touch /etc/qemu/firmware/50-ovmf.json 333# 334# The sysadmin can replace/alter the distro default OVMF with 335# 336# $ vim /etc/qemu/firmware/50-ovmf.json 337# 338# or they can provide a parallel OVMF with higher priority 339# 340# $ vim /etc/qemu/firmware/10-ovmf.json 341# 342# or they can provide a parallel OVMF with lower priority 343# 344# $ vim /etc/qemu/firmware/99-ovmf.json 345# 346# @description: Provides a human-readable description of the firmware. 347# Management software may or may not display @description. 348# 349# @interface-types: Lists the types of interfaces that the firmware can 350# expose to the guest OS. This is a non-empty, ordered 351# list; entries near the beginning of @interface-types 352# are considered more native to the firmware, and/or 353# to have a higher quality implementation in the 354# firmware, than entries near the end of 355# @interface-types. 356# 357# @mapping: Describes the loading / mapping properties of the firmware. 358# 359# @targets: Collects the target architectures (QEMU system emulators) 360# and their machine types that may execute the firmware. 361# 362# @features: Lists the features that the firmware supports, and the 363# platform requirements it presents. 364# 365# @tags: A list of auxiliary strings associated with the firmware for 366# which @description is not appropriate, due to the latter's 367# possible exposure to the end-user. @tags serves development and 368# debugging purposes only, and management software shall 369# explicitly ignore it. 370# 371# Since: 3.0 372# 373# Examples: 374# 375# { 376# "description": "SeaBIOS", 377# "interface-types": [ 378# "bios" 379# ], 380# "mapping": { 381# "device": "memory", 382# "filename": "/usr/share/seabios/bios-256k.bin" 383# }, 384# "targets": [ 385# { 386# "architecture": "i386", 387# "machines": [ 388# "pc-i440fx-*", 389# "pc-q35-*" 390# ] 391# }, 392# { 393# "architecture": "x86_64", 394# "machines": [ 395# "pc-i440fx-*", 396# "pc-q35-*" 397# ] 398# } 399# ], 400# "features": [ 401# "acpi-s3", 402# "acpi-s4" 403# ], 404# "tags": [ 405# "CONFIG_BOOTSPLASH=n", 406# "CONFIG_ROM_SIZE=256", 407# "CONFIG_USE_SMM=n" 408# ] 409# } 410# 411# { 412# "description": "OVMF with SB+SMM, empty varstore", 413# "interface-types": [ 414# "uefi" 415# ], 416# "mapping": { 417# "device": "flash", 418# "executable": { 419# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 420# "format": "raw" 421# }, 422# "nvram-template": { 423# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 424# "format": "raw" 425# } 426# }, 427# "targets": [ 428# { 429# "architecture": "x86_64", 430# "machines": [ 431# "pc-q35-*" 432# ] 433# } 434# ], 435# "features": [ 436# "acpi-s3", 437# "amd-sev", 438# "requires-smm", 439# "secure-boot", 440# "verbose-dynamic" 441# ], 442# "tags": [ 443# "-a IA32", 444# "-a X64", 445# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 446# "-t GCC48", 447# "-b DEBUG", 448# "-D SMM_REQUIRE", 449# "-D SECURE_BOOT_ENABLE", 450# "-D FD_SIZE_4MB" 451# ] 452# } 453# 454# { 455# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled", 456# "interface-types": [ 457# "uefi" 458# ], 459# "mapping": { 460# "device": "flash", 461# "executable": { 462# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 463# "format": "raw" 464# }, 465# "nvram-template": { 466# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd", 467# "format": "raw" 468# } 469# }, 470# "targets": [ 471# { 472# "architecture": "x86_64", 473# "machines": [ 474# "pc-q35-*" 475# ] 476# } 477# ], 478# "features": [ 479# "acpi-s3", 480# "amd-sev", 481# "enrolled-keys", 482# "requires-smm", 483# "secure-boot", 484# "verbose-dynamic" 485# ], 486# "tags": [ 487# "-a IA32", 488# "-a X64", 489# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 490# "-t GCC48", 491# "-b DEBUG", 492# "-D SMM_REQUIRE", 493# "-D SECURE_BOOT_ENABLE", 494# "-D FD_SIZE_4MB" 495# ] 496# } 497# 498# { 499# "description": "UEFI firmware for ARM64 virtual machines", 500# "interface-types": [ 501# "uefi" 502# ], 503# "mapping": { 504# "device": "flash", 505# "executable": { 506# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd", 507# "format": "raw" 508# }, 509# "nvram-template": { 510# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd", 511# "format": "raw" 512# } 513# }, 514# "targets": [ 515# { 516# "architecture": "aarch64", 517# "machines": [ 518# "virt-*" 519# ] 520# } 521# ], 522# "features": [ 523# 524# ], 525# "tags": [ 526# "-a AARCH64", 527# "-p ArmVirtPkg/ArmVirtQemu.dsc", 528# "-t GCC48", 529# "-b DEBUG", 530# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" 531# ] 532# } 533## 534{ 'struct' : 'Firmware', 535 'data' : { 'description' : 'str', 536 'interface-types' : [ 'FirmwareOSInterface' ], 537 'mapping' : 'FirmwareMapping', 538 'targets' : [ 'FirmwareTarget' ], 539 'features' : [ 'FirmwareFeature' ], 540 'tags' : [ 'str' ] } } 541