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## 215# @FirmwareFlashType: 216# 217# Describes how the firmware build handles code versus variable 218# persistence. 219# 220# @split: the executable file contains code while the NVRAM 221# template provides variable storage. The executable 222# must be configured read-only and can be shared between 223# multiple guests. The NVRAM template must be cloned 224# for each new guest and configured read-write. 225# 226# @combined: the executable file contains both code and 227# variable storage. The executable must be cloned 228# for each new guest and configured read-write. 229# No NVRAM template will be specified. 230# 231# @stateless: the executable file contains code and variable 232# storage is not persisted. The executable must 233# be configured read-only and can be shared 234# between multiple guests. No NVRAM template 235# will be specified. 236# 237# Since: 7.0.0 238## 239{ 'enum': 'FirmwareFlashMode', 240 'data': [ 'split', 'combined', 'stateless' ] } 241 242## 243# @FirmwareMappingFlash: 244# 245# Describes loading and mapping properties for the firmware executable 246# and its accompanying NVRAM file, when @FirmwareDevice is @flash. 247# 248# @mode: Describes how the firmware build handles code versus variable 249# storage. If not present, it must be treated as if it was 250# configured with value ``split``. Since: 7.0.0 251# 252# @executable: Identifies the firmware executable. The @mode 253# indicates whether there will be an associated 254# NVRAM template present. The preferred 255# corresponding QEMU command line options are 256# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format 257# -machine pflash0=pflash0 258# or equivalent -blockdev instead of -drive. When 259# @mode is ``combined`` the executable must be 260# cloned before use and configured with readonly=off. 261# With QEMU versions older than 4.0, you have to use 262# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format 263# 264# @nvram-template: Identifies the NVRAM template compatible with 265# @executable, when @mode is set to ``split``, 266# otherwise it should not be present. 267# Management software instantiates an 268# individual copy -- a specific NVRAM file -- from 269# @nvram-template.@filename for each new virtual 270# machine definition created. @nvram-template.@filename 271# itself is never mapped into virtual machines, only 272# individual copies of it are. An NVRAM file is 273# typically used for persistently storing the 274# non-volatile UEFI variables of a virtual machine 275# definition. The preferred corresponding QEMU 276# command line options are 277# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 278# -machine pflash1=pflash1 279# or equivalent -blockdev instead of -drive. 280# With QEMU versions older than 4.0, you have to use 281# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 282# 283# Since: 3.0 284## 285{ 'struct' : 'FirmwareMappingFlash', 286 'data' : { '*mode': 'FirmwareFlashMode', 287 'executable' : 'FirmwareFlashFile', 288 '*nvram-template' : 'FirmwareFlashFile' } } 289 290## 291# @FirmwareMappingKernel: 292# 293# Describes loading and mapping properties for the firmware executable, 294# when @FirmwareDevice is @kernel. 295# 296# @filename: Identifies the firmware executable. The firmware executable 297# may be shared by multiple virtual machine definitions. The 298# corresponding QEMU command line option is "-kernel 299# @filename". 300# 301# Since: 3.0 302## 303{ 'struct' : 'FirmwareMappingKernel', 304 'data' : { 'filename' : 'str' } } 305 306## 307# @FirmwareMappingMemory: 308# 309# Describes loading and mapping properties for the firmware executable, 310# when @FirmwareDevice is @memory. 311# 312# @filename: Identifies the firmware executable. The firmware executable 313# may be shared by multiple virtual machine definitions. The 314# corresponding QEMU command line option is "-bios 315# @filename". 316# 317# Since: 3.0 318## 319{ 'struct' : 'FirmwareMappingMemory', 320 'data' : { 'filename' : 'str' } } 321 322## 323# @FirmwareMapping: 324# 325# Provides a discriminated structure for firmware to describe its 326# loading / mapping properties. 327# 328# @device: Selects the device type that the firmware must be mapped 329# into. 330# 331# Since: 3.0 332## 333{ 'union' : 'FirmwareMapping', 334 'base' : { 'device' : 'FirmwareDevice' }, 335 'discriminator' : 'device', 336 'data' : { 'flash' : 'FirmwareMappingFlash', 337 'kernel' : 'FirmwareMappingKernel', 338 'memory' : 'FirmwareMappingMemory' } } 339 340## 341# @Firmware: 342# 343# Describes a firmware (or a firmware use case) to management software. 344# 345# It is possible for multiple @Firmware elements to match the search 346# criteria of management software. Applications thus need rules to pick 347# one of the many matches, and users need the ability to override distro 348# defaults. 349# 350# It is recommended to create firmware JSON files (each containing a 351# single @Firmware root element) with a double-digit prefix, for example 352# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in 353# predictable order. The firmware JSON files should be searched for in 354# three directories: 355# 356# - /usr/share/qemu/firmware -- populated by distro-provided firmware 357# packages (XDG_DATA_DIRS covers 358# /usr/share by default), 359# 360# - /etc/qemu/firmware -- exclusively for sysadmins' local additions, 361# 362# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local 363# additions (XDG_CONFIG_HOME 364# defaults to $HOME/.config). 365# 366# Top-down, the list of directories goes from general to specific. 367# 368# Management software should build a list of files from all three 369# locations, then sort the list by filename (i.e., last pathname 370# component). Management software should choose the first JSON file on 371# the sorted list that matches the search criteria. If a more specific 372# directory has a file with same name as a less specific directory, then 373# the file in the more specific directory takes effect. If the more 374# specific file is zero length, it hides the less specific one. 375# 376# For example, if a distro ships 377# 378# - /usr/share/qemu/firmware/50-ovmf.json 379# 380# - /usr/share/qemu/firmware/50-seabios-256k.json 381# 382# then the sysadmin can prevent the default OVMF being used at all with 383# 384# $ touch /etc/qemu/firmware/50-ovmf.json 385# 386# The sysadmin can replace/alter the distro default OVMF with 387# 388# $ vim /etc/qemu/firmware/50-ovmf.json 389# 390# or they can provide a parallel OVMF with higher priority 391# 392# $ vim /etc/qemu/firmware/10-ovmf.json 393# 394# or they can provide a parallel OVMF with lower priority 395# 396# $ vim /etc/qemu/firmware/99-ovmf.json 397# 398# @description: Provides a human-readable description of the firmware. 399# Management software may or may not display @description. 400# 401# @interface-types: Lists the types of interfaces that the firmware can 402# expose to the guest OS. This is a non-empty, ordered 403# list; entries near the beginning of @interface-types 404# are considered more native to the firmware, and/or 405# to have a higher quality implementation in the 406# firmware, than entries near the end of 407# @interface-types. 408# 409# @mapping: Describes the loading / mapping properties of the firmware. 410# 411# @targets: Collects the target architectures (QEMU system emulators) 412# and their machine types that may execute the firmware. 413# 414# @features: Lists the features that the firmware supports, and the 415# platform requirements it presents. 416# 417# @tags: A list of auxiliary strings associated with the firmware for 418# which @description is not appropriate, due to the latter's 419# possible exposure to the end-user. @tags serves development and 420# debugging purposes only, and management software shall 421# explicitly ignore it. 422# 423# Since: 3.0 424# 425# Examples: 426# 427# { 428# "description": "SeaBIOS", 429# "interface-types": [ 430# "bios" 431# ], 432# "mapping": { 433# "device": "memory", 434# "filename": "/usr/share/seabios/bios-256k.bin" 435# }, 436# "targets": [ 437# { 438# "architecture": "i386", 439# "machines": [ 440# "pc-i440fx-*", 441# "pc-q35-*" 442# ] 443# }, 444# { 445# "architecture": "x86_64", 446# "machines": [ 447# "pc-i440fx-*", 448# "pc-q35-*" 449# ] 450# } 451# ], 452# "features": [ 453# "acpi-s3", 454# "acpi-s4" 455# ], 456# "tags": [ 457# "CONFIG_BOOTSPLASH=n", 458# "CONFIG_ROM_SIZE=256", 459# "CONFIG_USE_SMM=n" 460# ] 461# } 462# 463# { 464# "description": "OVMF with SB+SMM, empty varstore", 465# "interface-types": [ 466# "uefi" 467# ], 468# "mapping": { 469# "device": "flash", 470# "executable": { 471# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 472# "format": "raw" 473# }, 474# "nvram-template": { 475# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 476# "format": "raw" 477# } 478# }, 479# "targets": [ 480# { 481# "architecture": "x86_64", 482# "machines": [ 483# "pc-q35-*" 484# ] 485# } 486# ], 487# "features": [ 488# "acpi-s3", 489# "amd-sev", 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": "OVMF with SB+SMM, SB enabled, MS certs enrolled", 508# "interface-types": [ 509# "uefi" 510# ], 511# "mapping": { 512# "device": "flash", 513# "executable": { 514# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 515# "format": "raw" 516# }, 517# "nvram-template": { 518# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd", 519# "format": "raw" 520# } 521# }, 522# "targets": [ 523# { 524# "architecture": "x86_64", 525# "machines": [ 526# "pc-q35-*" 527# ] 528# } 529# ], 530# "features": [ 531# "acpi-s3", 532# "amd-sev", 533# "enrolled-keys", 534# "requires-smm", 535# "secure-boot", 536# "verbose-dynamic" 537# ], 538# "tags": [ 539# "-a IA32", 540# "-a X64", 541# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 542# "-t GCC48", 543# "-b DEBUG", 544# "-D SMM_REQUIRE", 545# "-D SECURE_BOOT_ENABLE", 546# "-D FD_SIZE_4MB" 547# ] 548# } 549# 550# { 551# "description": "OVMF with SEV-ES support", 552# "interface-types": [ 553# "uefi" 554# ], 555# "mapping": { 556# "device": "flash", 557# "executable": { 558# "filename": "/usr/share/OVMF/OVMF_CODE.fd", 559# "format": "raw" 560# }, 561# "nvram-template": { 562# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 563# "format": "raw" 564# } 565# }, 566# "targets": [ 567# { 568# "architecture": "x86_64", 569# "machines": [ 570# "pc-q35-*" 571# ] 572# } 573# ], 574# "features": [ 575# "acpi-s3", 576# "amd-sev", 577# "amd-sev-es", 578# "verbose-dynamic" 579# ], 580# "tags": [ 581# "-a X64", 582# "-p OvmfPkg/OvmfPkgX64.dsc", 583# "-t GCC48", 584# "-b DEBUG", 585# "-D FD_SIZE_4MB" 586# ] 587# } 588# 589# { 590# "description": "UEFI firmware for ARM64 virtual machines", 591# "interface-types": [ 592# "uefi" 593# ], 594# "mapping": { 595# "device": "flash", 596# "executable": { 597# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd", 598# "format": "raw" 599# }, 600# "nvram-template": { 601# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd", 602# "format": "raw" 603# } 604# }, 605# "targets": [ 606# { 607# "architecture": "aarch64", 608# "machines": [ 609# "virt-*" 610# ] 611# } 612# ], 613# "features": [ 614# 615# ], 616# "tags": [ 617# "-a AARCH64", 618# "-p ArmVirtPkg/ArmVirtQemu.dsc", 619# "-t GCC48", 620# "-b DEBUG", 621# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" 622# ] 623# } 624## 625{ 'struct' : 'Firmware', 626 'data' : { 'description' : 'str', 627 'interface-types' : [ 'FirmwareOSInterface' ], 628 'mapping' : 'FirmwareMapping', 629 'targets' : [ 'FirmwareTarget' ], 630 'features' : [ 'FirmwareFeature' ], 631 'tags' : [ 'str' ] } } 632