1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4# Copyright (C) 2018 Red Hat, Inc. 5# 6# Authors: 7# Daniel P. Berrange <berrange@redhat.com> 8# Laszlo Ersek <lersek@redhat.com> 9# 10# This work is licensed under the terms of the GNU GPL, version 2 or 11# later. See the COPYING file in the top-level directory. 12 13## 14# = Firmware 15## 16 17{ 'include' : 'machine.json' } 18{ 'include' : 'block-core.json' } 19 20## 21# @FirmwareOSInterface: 22# 23# Lists the firmware-OS interface types provided by various firmware 24# that is commonly used with QEMU virtual machines. 25# 26# @bios: Traditional x86 BIOS interface. For example, firmware built 27# from the SeaBIOS project usually provides this interface. 28# 29# @openfirmware: The interface is defined by the (historical) IEEE 30# 1275-1994 standard. Examples for firmware projects that 31# provide this interface are: OpenBIOS and 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 preferred corresponding QEMU command 216# line options are 217# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format 218# -machine pflash0=pflash0 219# or equivalent -blockdev instead of -drive. 220# With QEMU versions older than 4.0, you have to use 221# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format 222# 223# @nvram-template: Identifies the NVRAM template compatible with 224# @executable. Management software instantiates an 225# individual copy -- a specific NVRAM file -- from 226# @nvram-template.@filename for each new virtual 227# machine definition created. @nvram-template.@filename 228# itself is never mapped into virtual machines, only 229# individual copies of it are. An NVRAM file is 230# typically used for persistently storing the 231# non-volatile UEFI variables of a virtual machine 232# definition. The preferred corresponding QEMU 233# command line options are 234# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 235# -machine pflash1=pflash1 236# or equivalent -blockdev instead of -drive. 237# With QEMU versions older than 4.0, you have to use 238# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 239# 240# Since: 3.0 241## 242{ 'struct' : 'FirmwareMappingFlash', 243 'data' : { 'executable' : 'FirmwareFlashFile', 244 'nvram-template' : 'FirmwareFlashFile' } } 245 246## 247# @FirmwareMappingKernel: 248# 249# Describes loading and mapping properties for the firmware executable, 250# when @FirmwareDevice is @kernel. 251# 252# @filename: Identifies the firmware executable. The firmware executable 253# may be shared by multiple virtual machine definitions. The 254# corresponding QEMU command line option is "-kernel 255# @filename". 256# 257# Since: 3.0 258## 259{ 'struct' : 'FirmwareMappingKernel', 260 'data' : { 'filename' : 'str' } } 261 262## 263# @FirmwareMappingMemory: 264# 265# Describes loading and mapping properties for the firmware executable, 266# when @FirmwareDevice is @memory. 267# 268# @filename: Identifies the firmware executable. The firmware executable 269# may be shared by multiple virtual machine definitions. The 270# corresponding QEMU command line option is "-bios 271# @filename". 272# 273# Since: 3.0 274## 275{ 'struct' : 'FirmwareMappingMemory', 276 'data' : { 'filename' : 'str' } } 277 278## 279# @FirmwareMapping: 280# 281# Provides a discriminated structure for firmware to describe its 282# loading / mapping properties. 283# 284# @device: Selects the device type that the firmware must be mapped 285# into. 286# 287# Since: 3.0 288## 289{ 'union' : 'FirmwareMapping', 290 'base' : { 'device' : 'FirmwareDevice' }, 291 'discriminator' : 'device', 292 'data' : { 'flash' : 'FirmwareMappingFlash', 293 'kernel' : 'FirmwareMappingKernel', 294 'memory' : 'FirmwareMappingMemory' } } 295 296## 297# @Firmware: 298# 299# Describes a firmware (or a firmware use case) to management software. 300# 301# It is possible for multiple @Firmware elements to match the search 302# criteria of management software. Applications thus need rules to pick 303# one of the many matches, and users need the ability to override distro 304# defaults. 305# 306# It is recommended to create firmware JSON files (each containing a 307# single @Firmware root element) with a double-digit prefix, for example 308# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in 309# predictable order. The firmware JSON files should be searched for in 310# three directories: 311# 312# - /usr/share/qemu/firmware -- populated by distro-provided firmware 313# packages (XDG_DATA_DIRS covers 314# /usr/share by default), 315# 316# - /etc/qemu/firmware -- exclusively for sysadmins' local additions, 317# 318# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local 319# additions (XDG_CONFIG_HOME 320# defaults to $HOME/.config). 321# 322# Top-down, the list of directories goes from general to specific. 323# 324# Management software should build a list of files from all three 325# locations, then sort the list by filename (i.e., last pathname 326# component). Management software should choose the first JSON file on 327# the sorted list that matches the search criteria. If a more specific 328# directory has a file with same name as a less specific directory, then 329# the file in the more specific directory takes effect. If the more 330# specific file is zero length, it hides the less specific one. 331# 332# For example, if a distro ships 333# 334# - /usr/share/qemu/firmware/50-ovmf.json 335# 336# - /usr/share/qemu/firmware/50-seabios-256k.json 337# 338# then the sysadmin can prevent the default OVMF being used at all with 339# 340# $ touch /etc/qemu/firmware/50-ovmf.json 341# 342# The sysadmin can replace/alter the distro default OVMF with 343# 344# $ vim /etc/qemu/firmware/50-ovmf.json 345# 346# or they can provide a parallel OVMF with higher priority 347# 348# $ vim /etc/qemu/firmware/10-ovmf.json 349# 350# or they can provide a parallel OVMF with lower priority 351# 352# $ vim /etc/qemu/firmware/99-ovmf.json 353# 354# @description: Provides a human-readable description of the firmware. 355# Management software may or may not display @description. 356# 357# @interface-types: Lists the types of interfaces that the firmware can 358# expose to the guest OS. This is a non-empty, ordered 359# list; entries near the beginning of @interface-types 360# are considered more native to the firmware, and/or 361# to have a higher quality implementation in the 362# firmware, than entries near the end of 363# @interface-types. 364# 365# @mapping: Describes the loading / mapping properties of the firmware. 366# 367# @targets: Collects the target architectures (QEMU system emulators) 368# and their machine types that may execute the firmware. 369# 370# @features: Lists the features that the firmware supports, and the 371# platform requirements it presents. 372# 373# @tags: A list of auxiliary strings associated with the firmware for 374# which @description is not appropriate, due to the latter's 375# possible exposure to the end-user. @tags serves development and 376# debugging purposes only, and management software shall 377# explicitly ignore it. 378# 379# Since: 3.0 380# 381# Examples: 382# 383# { 384# "description": "SeaBIOS", 385# "interface-types": [ 386# "bios" 387# ], 388# "mapping": { 389# "device": "memory", 390# "filename": "/usr/share/seabios/bios-256k.bin" 391# }, 392# "targets": [ 393# { 394# "architecture": "i386", 395# "machines": [ 396# "pc-i440fx-*", 397# "pc-q35-*" 398# ] 399# }, 400# { 401# "architecture": "x86_64", 402# "machines": [ 403# "pc-i440fx-*", 404# "pc-q35-*" 405# ] 406# } 407# ], 408# "features": [ 409# "acpi-s3", 410# "acpi-s4" 411# ], 412# "tags": [ 413# "CONFIG_BOOTSPLASH=n", 414# "CONFIG_ROM_SIZE=256", 415# "CONFIG_USE_SMM=n" 416# ] 417# } 418# 419# { 420# "description": "OVMF with SB+SMM, empty varstore", 421# "interface-types": [ 422# "uefi" 423# ], 424# "mapping": { 425# "device": "flash", 426# "executable": { 427# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 428# "format": "raw" 429# }, 430# "nvram-template": { 431# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 432# "format": "raw" 433# } 434# }, 435# "targets": [ 436# { 437# "architecture": "x86_64", 438# "machines": [ 439# "pc-q35-*" 440# ] 441# } 442# ], 443# "features": [ 444# "acpi-s3", 445# "amd-sev", 446# "requires-smm", 447# "secure-boot", 448# "verbose-dynamic" 449# ], 450# "tags": [ 451# "-a IA32", 452# "-a X64", 453# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 454# "-t GCC48", 455# "-b DEBUG", 456# "-D SMM_REQUIRE", 457# "-D SECURE_BOOT_ENABLE", 458# "-D FD_SIZE_4MB" 459# ] 460# } 461# 462# { 463# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled", 464# "interface-types": [ 465# "uefi" 466# ], 467# "mapping": { 468# "device": "flash", 469# "executable": { 470# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 471# "format": "raw" 472# }, 473# "nvram-template": { 474# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd", 475# "format": "raw" 476# } 477# }, 478# "targets": [ 479# { 480# "architecture": "x86_64", 481# "machines": [ 482# "pc-q35-*" 483# ] 484# } 485# ], 486# "features": [ 487# "acpi-s3", 488# "amd-sev", 489# "enrolled-keys", 490# "requires-smm", 491# "secure-boot", 492# "verbose-dynamic" 493# ], 494# "tags": [ 495# "-a IA32", 496# "-a X64", 497# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 498# "-t GCC48", 499# "-b DEBUG", 500# "-D SMM_REQUIRE", 501# "-D SECURE_BOOT_ENABLE", 502# "-D FD_SIZE_4MB" 503# ] 504# } 505# 506# { 507# "description": "UEFI firmware for ARM64 virtual machines", 508# "interface-types": [ 509# "uefi" 510# ], 511# "mapping": { 512# "device": "flash", 513# "executable": { 514# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd", 515# "format": "raw" 516# }, 517# "nvram-template": { 518# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd", 519# "format": "raw" 520# } 521# }, 522# "targets": [ 523# { 524# "architecture": "aarch64", 525# "machines": [ 526# "virt-*" 527# ] 528# } 529# ], 530# "features": [ 531# 532# ], 533# "tags": [ 534# "-a AARCH64", 535# "-p ArmVirtPkg/ArmVirtQemu.dsc", 536# "-t GCC48", 537# "-b DEBUG", 538# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" 539# ] 540# } 541## 542{ 'struct' : 'Firmware', 543 'data' : { 'description' : 'str', 544 'interface-types' : [ 'FirmwareOSInterface' ], 545 'mapping' : 'FirmwareMapping', 546 'targets' : [ 'FirmwareTarget' ], 547 'features' : [ 'FirmwareFeature' ], 548 'tags' : [ 'str' ] } } 549