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