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# @amd-sev-es: The firmware supports running under AMD Secure Encrypted 119# Virtualization - Encrypted State, as specified in the AMD64 120# Architecture Programmer's Manual. QEMU command line options 121# related to this feature are documented in 122# "docs/amd-memory-encryption.txt". 123# 124# @enrolled-keys: The variable store (NVRAM) template associated with 125# the firmware binary has the UEFI Secure Boot 126# operational mode turned on, with certificates 127# enrolled. 128# 129# @requires-smm: The firmware requires the platform to emulate SMM 130# (System Management Mode), as defined in the AMD64 131# Architecture Programmer's Manual, and in the Intel(R)64 132# and IA-32 Architectures Software Developer's Manual. On 133# the "pc-q35-*" machine types of the @i386 and @x86_64 134# emulation targets, SMM emulation can be enabled with 135# "-machine smm=on". (On the "pc-q35-*" machine types of 136# the @i386 emulation target, @requires-smm presents 137# further CPU requirements; one combination known to work 138# is "-cpu coreduo,nx=off".) If the firmware is marked as 139# both @secure-boot and @requires-smm, then write 140# accesses to the pflash chip (NVRAM) that holds the UEFI 141# variable store must be restricted to code that executes 142# in SMM, using the additional option "-global 143# driver=cfi.pflash01,property=secure,value=on". 144# Furthermore, a large guest-physical address space 145# (comprising guest RAM, memory hotplug range, and 64-bit 146# PCI MMIO aperture), and/or a high VCPU count, may 147# present high SMRAM requirements from the firmware. On 148# the "pc-q35-*" machine types of the @i386 and @x86_64 149# emulation targets, the SMRAM size may be increased 150# above the default 16MB with the "-global 151# mch.extended-tseg-mbytes=uint16" option. As a rule of 152# thumb, the default 16MB size suffices for 1TB of 153# guest-phys address space and a few tens of VCPUs; for 154# every further TB of guest-phys address space, add 8MB 155# of SMRAM. 48MB should suffice for 4TB of guest-phys 156# address space and 2-3 hundred VCPUs. 157# 158# @secure-boot: The firmware implements the software interfaces for UEFI 159# Secure Boot, as defined in the UEFI specification. Note 160# that without @requires-smm, guest code running with 161# kernel privileges can undermine the security of Secure 162# Boot. 163# 164# @verbose-dynamic: When firmware log capture is enabled, the firmware 165# logs a large amount of debug messages, which may 166# impact boot performance. With log capture disabled, 167# there is no boot performance impact. On the 168# "pc-i440fx-*" and "pc-q35-*" machine types of the 169# @i386 and @x86_64 emulation targets, firmware log 170# capture can be enabled with the QEMU command line 171# options "-chardev file,id=fwdebug,path=LOGFILEPATH 172# -device isa-debugcon,iobase=0x402,chardev=fwdebug". 173# @verbose-dynamic is mutually exclusive with 174# @verbose-static. 175# 176# @verbose-static: The firmware unconditionally produces a large amount 177# of debug messages, which may impact boot performance. 178# This feature may typically be carried by certain UEFI 179# firmware for the "virt-*" machine types of the @arm 180# and @aarch64 emulation targets, where the debug 181# messages are written to the first (always present) 182# PL011 UART. @verbose-static is mutually exclusive 183# with @verbose-dynamic. 184# 185# Since: 3.0 186## 187{ 'enum' : 'FirmwareFeature', 188 'data' : [ 'acpi-s3', 'acpi-s4', 'amd-sev', 'amd-sev-es', 'enrolled-keys', 189 'requires-smm', 'secure-boot', 'verbose-dynamic', 190 'verbose-static' ] } 191 192## 193# @FirmwareFlashFile: 194# 195# Defines common properties that are necessary for loading a firmware 196# file into a pflash chip. The corresponding QEMU command line option is 197# "-drive file=@filename,format=@format". Note however that the 198# option-argument shown here is incomplete; it is completed under 199# @FirmwareMappingFlash. 200# 201# @filename: Specifies the filename on the host filesystem where the 202# firmware file can be found. 203# 204# @format: Specifies the block format of the file pointed-to by 205# @filename, such as @raw or @qcow2. 206# 207# Since: 3.0 208## 209{ 'struct' : 'FirmwareFlashFile', 210 'data' : { 'filename' : 'str', 211 'format' : 'BlockdevDriver' } } 212 213## 214# @FirmwareMappingFlash: 215# 216# Describes loading and mapping properties for the firmware executable 217# and its accompanying NVRAM file, when @FirmwareDevice is @flash. 218# 219# @executable: Identifies the firmware executable. The firmware 220# executable may be shared by multiple virtual machine 221# definitions. The preferred corresponding QEMU command 222# line options are 223# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format 224# -machine pflash0=pflash0 225# or equivalent -blockdev instead of -drive. 226# With QEMU versions older than 4.0, you have to use 227# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format 228# 229# @nvram-template: Identifies the NVRAM template compatible with 230# @executable. Management software instantiates an 231# individual copy -- a specific NVRAM file -- from 232# @nvram-template.@filename for each new virtual 233# machine definition created. @nvram-template.@filename 234# itself is never mapped into virtual machines, only 235# individual copies of it are. An NVRAM file is 236# typically used for persistently storing the 237# non-volatile UEFI variables of a virtual machine 238# definition. The preferred corresponding QEMU 239# command line options are 240# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 241# -machine pflash1=pflash1 242# or equivalent -blockdev instead of -drive. 243# With QEMU versions older than 4.0, you have to use 244# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 245# 246# Since: 3.0 247## 248{ 'struct' : 'FirmwareMappingFlash', 249 'data' : { 'executable' : 'FirmwareFlashFile', 250 'nvram-template' : 'FirmwareFlashFile' } } 251 252## 253# @FirmwareMappingKernel: 254# 255# Describes loading and mapping properties for the firmware executable, 256# when @FirmwareDevice is @kernel. 257# 258# @filename: Identifies the firmware executable. The firmware executable 259# may be shared by multiple virtual machine definitions. The 260# corresponding QEMU command line option is "-kernel 261# @filename". 262# 263# Since: 3.0 264## 265{ 'struct' : 'FirmwareMappingKernel', 266 'data' : { 'filename' : 'str' } } 267 268## 269# @FirmwareMappingMemory: 270# 271# Describes loading and mapping properties for the firmware executable, 272# when @FirmwareDevice is @memory. 273# 274# @filename: Identifies the firmware executable. The firmware executable 275# may be shared by multiple virtual machine definitions. The 276# corresponding QEMU command line option is "-bios 277# @filename". 278# 279# Since: 3.0 280## 281{ 'struct' : 'FirmwareMappingMemory', 282 'data' : { 'filename' : 'str' } } 283 284## 285# @FirmwareMapping: 286# 287# Provides a discriminated structure for firmware to describe its 288# loading / mapping properties. 289# 290# @device: Selects the device type that the firmware must be mapped 291# into. 292# 293# Since: 3.0 294## 295{ 'union' : 'FirmwareMapping', 296 'base' : { 'device' : 'FirmwareDevice' }, 297 'discriminator' : 'device', 298 'data' : { 'flash' : 'FirmwareMappingFlash', 299 'kernel' : 'FirmwareMappingKernel', 300 'memory' : 'FirmwareMappingMemory' } } 301 302## 303# @Firmware: 304# 305# Describes a firmware (or a firmware use case) to management software. 306# 307# It is possible for multiple @Firmware elements to match the search 308# criteria of management software. Applications thus need rules to pick 309# one of the many matches, and users need the ability to override distro 310# defaults. 311# 312# It is recommended to create firmware JSON files (each containing a 313# single @Firmware root element) with a double-digit prefix, for example 314# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in 315# predictable order. The firmware JSON files should be searched for in 316# three directories: 317# 318# - /usr/share/qemu/firmware -- populated by distro-provided firmware 319# packages (XDG_DATA_DIRS covers 320# /usr/share by default), 321# 322# - /etc/qemu/firmware -- exclusively for sysadmins' local additions, 323# 324# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local 325# additions (XDG_CONFIG_HOME 326# defaults to $HOME/.config). 327# 328# Top-down, the list of directories goes from general to specific. 329# 330# Management software should build a list of files from all three 331# locations, then sort the list by filename (i.e., last pathname 332# component). Management software should choose the first JSON file on 333# the sorted list that matches the search criteria. If a more specific 334# directory has a file with same name as a less specific directory, then 335# the file in the more specific directory takes effect. If the more 336# specific file is zero length, it hides the less specific one. 337# 338# For example, if a distro ships 339# 340# - /usr/share/qemu/firmware/50-ovmf.json 341# 342# - /usr/share/qemu/firmware/50-seabios-256k.json 343# 344# then the sysadmin can prevent the default OVMF being used at all with 345# 346# $ touch /etc/qemu/firmware/50-ovmf.json 347# 348# The sysadmin can replace/alter the distro default OVMF with 349# 350# $ vim /etc/qemu/firmware/50-ovmf.json 351# 352# or they can provide a parallel OVMF with higher priority 353# 354# $ vim /etc/qemu/firmware/10-ovmf.json 355# 356# or they can provide a parallel OVMF with lower priority 357# 358# $ vim /etc/qemu/firmware/99-ovmf.json 359# 360# @description: Provides a human-readable description of the firmware. 361# Management software may or may not display @description. 362# 363# @interface-types: Lists the types of interfaces that the firmware can 364# expose to the guest OS. This is a non-empty, ordered 365# list; entries near the beginning of @interface-types 366# are considered more native to the firmware, and/or 367# to have a higher quality implementation in the 368# firmware, than entries near the end of 369# @interface-types. 370# 371# @mapping: Describes the loading / mapping properties of the firmware. 372# 373# @targets: Collects the target architectures (QEMU system emulators) 374# and their machine types that may execute the firmware. 375# 376# @features: Lists the features that the firmware supports, and the 377# platform requirements it presents. 378# 379# @tags: A list of auxiliary strings associated with the firmware for 380# which @description is not appropriate, due to the latter's 381# possible exposure to the end-user. @tags serves development and 382# debugging purposes only, and management software shall 383# explicitly ignore it. 384# 385# Since: 3.0 386# 387# Examples: 388# 389# { 390# "description": "SeaBIOS", 391# "interface-types": [ 392# "bios" 393# ], 394# "mapping": { 395# "device": "memory", 396# "filename": "/usr/share/seabios/bios-256k.bin" 397# }, 398# "targets": [ 399# { 400# "architecture": "i386", 401# "machines": [ 402# "pc-i440fx-*", 403# "pc-q35-*" 404# ] 405# }, 406# { 407# "architecture": "x86_64", 408# "machines": [ 409# "pc-i440fx-*", 410# "pc-q35-*" 411# ] 412# } 413# ], 414# "features": [ 415# "acpi-s3", 416# "acpi-s4" 417# ], 418# "tags": [ 419# "CONFIG_BOOTSPLASH=n", 420# "CONFIG_ROM_SIZE=256", 421# "CONFIG_USE_SMM=n" 422# ] 423# } 424# 425# { 426# "description": "OVMF with SB+SMM, empty varstore", 427# "interface-types": [ 428# "uefi" 429# ], 430# "mapping": { 431# "device": "flash", 432# "executable": { 433# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 434# "format": "raw" 435# }, 436# "nvram-template": { 437# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 438# "format": "raw" 439# } 440# }, 441# "targets": [ 442# { 443# "architecture": "x86_64", 444# "machines": [ 445# "pc-q35-*" 446# ] 447# } 448# ], 449# "features": [ 450# "acpi-s3", 451# "amd-sev", 452# "requires-smm", 453# "secure-boot", 454# "verbose-dynamic" 455# ], 456# "tags": [ 457# "-a IA32", 458# "-a X64", 459# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 460# "-t GCC48", 461# "-b DEBUG", 462# "-D SMM_REQUIRE", 463# "-D SECURE_BOOT_ENABLE", 464# "-D FD_SIZE_4MB" 465# ] 466# } 467# 468# { 469# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled", 470# "interface-types": [ 471# "uefi" 472# ], 473# "mapping": { 474# "device": "flash", 475# "executable": { 476# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 477# "format": "raw" 478# }, 479# "nvram-template": { 480# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd", 481# "format": "raw" 482# } 483# }, 484# "targets": [ 485# { 486# "architecture": "x86_64", 487# "machines": [ 488# "pc-q35-*" 489# ] 490# } 491# ], 492# "features": [ 493# "acpi-s3", 494# "amd-sev", 495# "enrolled-keys", 496# "requires-smm", 497# "secure-boot", 498# "verbose-dynamic" 499# ], 500# "tags": [ 501# "-a IA32", 502# "-a X64", 503# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 504# "-t GCC48", 505# "-b DEBUG", 506# "-D SMM_REQUIRE", 507# "-D SECURE_BOOT_ENABLE", 508# "-D FD_SIZE_4MB" 509# ] 510# } 511# 512# { 513# "description": "OVMF with SEV-ES support", 514# "interface-types": [ 515# "uefi" 516# ], 517# "mapping": { 518# "device": "flash", 519# "executable": { 520# "filename": "/usr/share/OVMF/OVMF_CODE.fd", 521# "format": "raw" 522# }, 523# "nvram-template": { 524# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 525# "format": "raw" 526# } 527# }, 528# "targets": [ 529# { 530# "architecture": "x86_64", 531# "machines": [ 532# "pc-q35-*" 533# ] 534# } 535# ], 536# "features": [ 537# "acpi-s3", 538# "amd-sev", 539# "amd-sev-es", 540# "verbose-dynamic" 541# ], 542# "tags": [ 543# "-a X64", 544# "-p OvmfPkg/OvmfPkgX64.dsc", 545# "-t GCC48", 546# "-b DEBUG", 547# "-D FD_SIZE_4MB" 548# ] 549# } 550# 551# { 552# "description": "UEFI firmware for ARM64 virtual machines", 553# "interface-types": [ 554# "uefi" 555# ], 556# "mapping": { 557# "device": "flash", 558# "executable": { 559# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd", 560# "format": "raw" 561# }, 562# "nvram-template": { 563# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd", 564# "format": "raw" 565# } 566# }, 567# "targets": [ 568# { 569# "architecture": "aarch64", 570# "machines": [ 571# "virt-*" 572# ] 573# } 574# ], 575# "features": [ 576# 577# ], 578# "tags": [ 579# "-a AARCH64", 580# "-p ArmVirtPkg/ArmVirtQemu.dsc", 581# "-t GCC48", 582# "-b DEBUG", 583# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" 584# ] 585# } 586## 587{ 'struct' : 'Firmware', 588 'data' : { 'description' : 'str', 589 'interface-types' : [ 'FirmwareOSInterface' ], 590 'mapping' : 'FirmwareMapping', 591 'targets' : [ 'FirmwareTarget' ], 592 'features' : [ 'FirmwareFeature' ], 593 'tags' : [ 'str' ] } } 594