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# ******** 15# Firmware 16# ******** 17## 18 19{ 'pragma': { 20 'member-name-exceptions': [ 21 'FirmwareArchitecture' # x86_64 22 ] } } 23 24## 25# @FirmwareOSInterface: 26# 27# Lists the firmware-OS interface types provided by various firmware 28# that is commonly used with QEMU virtual machines. 29# 30# @bios: Traditional x86 BIOS interface. For example, firmware built 31# from the SeaBIOS project usually provides this interface. 32# 33# @openfirmware: The interface is defined by the (historical) IEEE 34# 1275-1994 standard. Examples for firmware projects that 35# provide this interface are: OpenBIOS and SLOF. 36# 37# @uboot: Firmware interface defined by the U-Boot project. 38# 39# @uefi: Firmware interface defined by the UEFI specification. For 40# example, firmware built from the edk2 (EFI Development Kit II) 41# project usually provides this interface. 42# 43# Since: 3.0 44## 45{ 'enum' : 'FirmwareOSInterface', 46 'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] } 47 48## 49# @FirmwareDevice: 50# 51# Defines the device types that firmware can be mapped into. 52# 53# @flash: The firmware executable and its accompanying NVRAM file are to 54# be mapped into a pflash chip each. 55# 56# @kernel: The firmware is to be loaded like a Linux kernel. This is 57# similar to @memory but may imply additional processing that 58# is specific to the target architecture and machine type. 59# 60# @memory: The firmware is to be mapped into memory. 61# 62# @igvm: The firmware is defined by a file conforming to the IGVM 63# specification and mapped into memory according to directives 64# defined in the file. This is similar to @memory but may 65# include additional processing defined by the IGVM file 66# including initial CPU state or population of metadata into 67# the guest address space. Since: 10.1 68# 69# Since: 3.0 70## 71{ 'enum' : 'FirmwareDevice', 72 'data' : [ 'flash', 'kernel', 'memory', 'igvm' ] } 73 74## 75# @FirmwareArchitecture: 76# 77# Enumeration of architectures for which Qemu uses additional 78# firmware files. 79# 80# @aarch64: 64-bit Arm. 81# 82# @arm: 32-bit Arm. 83# 84# @i386: 32-bit x86. 85# 86# @loongarch64: 64-bit LoongArch. (since: 7.1) 87# 88# @riscv64: 64-bit RISC-V. 89# 90# @x86_64: 64-bit x86. 91# 92# Since: 3.0 93## 94{ 'enum' : 'FirmwareArchitecture', 95 'data' : [ 'aarch64', 'arm', 'i386', 'loongarch64', 'riscv64', 'x86_64' ] } 96 97## 98# @FirmwareTarget: 99# 100# Defines the machine types that firmware may execute on. 101# 102# @architecture: Determines the emulation target (the QEMU system 103# emulator) that can execute the firmware. 104# 105# @machines: Lists the machine types (known by the emulator that is 106# specified through @architecture) that can execute the 107# firmware. Elements of @machines are supposed to be concrete 108# machine types, not aliases. Glob patterns are understood, 109# which is especially useful for versioned machine types. 110# (For example, the glob pattern "pc-i440fx-*" matches 111# "pc-i440fx-2.12".) On the QEMU command line, "-machine 112# type=..." specifies the requested machine type (but that 113# option does not accept glob patterns). 114# 115# Since: 3.0 116## 117{ 'struct' : 'FirmwareTarget', 118 'data' : { 'architecture' : 'FirmwareArchitecture', 119 'machines' : [ 'str' ] } } 120 121## 122# @FirmwareFeature: 123# 124# Defines the features that firmware may support, and the platform 125# requirements that firmware may present. 126# 127# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined 128# in the ACPI specification. On the "pc-i440fx-*" machine 129# types of the @i386 and @x86_64 emulation targets, S3 can be 130# enabled with "-global PIIX4_PM.disable_s3=0" and disabled 131# with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*" 132# machine types of the @i386 and @x86_64 emulation targets, S3 133# can be enabled with "-global ICH9-LPC.disable_s3=0" and 134# disabled with "-global ICH9-LPC.disable_s3=1". 135# 136# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as 137# defined in the ACPI specification. On the "pc-i440fx-*" 138# machine types of the @i386 and @x86_64 emulation targets, S4 139# can be enabled with "-global PIIX4_PM.disable_s4=0" and 140# disabled with "-global PIIX4_PM.disable_s4=1". On the 141# "pc-q35-*" machine types of the @i386 and @x86_64 emulation 142# targets, S4 can be enabled with "-global 143# ICH9-LPC.disable_s4=0" and disabled with "-global 144# ICH9-LPC.disable_s4=1". 145# 146# @amd-sev: The firmware supports running under AMD Secure Encrypted 147# Virtualization, as specified in the AMD64 Architecture 148# Programmer's Manual. QEMU command line options related to 149# this feature are documented in 150# "docs/system/i386/amd-memory-encryption.rst". 151# 152# @amd-sev-es: The firmware supports running under AMD Secure Encrypted 153# Virtualization - Encrypted State, as specified in the AMD64 154# Architecture Programmer's Manual. QEMU command line options 155# related to this feature are documented in 156# "docs/system/i386/amd-memory-encryption.rst". 157# 158# @amd-sev-snp: The firmware supports running under AMD Secure Encrypted 159# Virtualization - Secure Nested Paging, as specified in the 160# AMD64 Architecture Programmer's Manual. QEMU command line 161# options related to this feature are documented in 162# "docs/system/i386/amd-memory-encryption.rst". 163# 164# @intel-tdx: The firmware supports running under Intel Trust Domain 165# Extensions (TDX). 166# 167# @enrolled-keys: The variable store (NVRAM) template associated with 168# the firmware binary has the UEFI Secure Boot 169# operational mode turned on, with certificates 170# enrolled. 171# 172# @requires-smm: The firmware requires the platform to emulate SMM 173# (System Management Mode), as defined in the AMD64 174# Architecture Programmer's Manual, and in the Intel(R)64 175# and IA-32 Architectures Software Developer's Manual. On 176# the "pc-q35-*" machine types of the @i386 and @x86_64 177# emulation targets, SMM emulation can be enabled with 178# "-machine smm=on". (On the "pc-q35-*" machine types of 179# the @i386 emulation target, @requires-smm presents 180# further CPU requirements; one combination known to work 181# is "-cpu coreduo,nx=off".) If the firmware is marked as 182# both @secure-boot and @requires-smm, then write 183# accesses to the pflash chip (NVRAM) that holds the UEFI 184# variable store must be restricted to code that executes 185# in SMM, using the additional option "-global 186# driver=cfi.pflash01,property=secure,value=on". 187# Furthermore, a large guest-physical address space 188# (comprising guest RAM, memory hotplug range, and 64-bit 189# PCI MMIO aperture), and/or a high VCPU count, may 190# present high SMRAM requirements from the firmware. On 191# the "pc-q35-*" machine types of the @i386 and @x86_64 192# emulation targets, the SMRAM size may be increased 193# above the default 16MB with the "-global 194# mch.extended-tseg-mbytes=uint16" option. As a rule of 195# thumb, the default 16MB size suffices for 1TB of 196# guest-phys address space and a few tens of VCPUs; for 197# every further TB of guest-phys address space, add 8MB 198# of SMRAM. 48MB should suffice for 4TB of guest-phys 199# address space and 2-3 hundred VCPUs. 200# 201# @secure-boot: The firmware implements the software interfaces for UEFI 202# Secure Boot, as defined in the UEFI specification. Note 203# that without @requires-smm, guest code running with 204# kernel privileges can undermine the security of Secure 205# Boot. 206# 207# @verbose-dynamic: When firmware log capture is enabled, the firmware 208# logs a large amount of debug messages, which may 209# impact boot performance. With log capture disabled, 210# there is no boot performance impact. On the 211# "pc-i440fx-*" and "pc-q35-*" machine types of the 212# @i386 and @x86_64 emulation targets, firmware log 213# capture can be enabled with the QEMU command line 214# options "-chardev file,id=fwdebug,path=LOGFILEPATH 215# -device isa-debugcon,iobase=0x402,chardev=fwdebug". 216# @verbose-dynamic is mutually exclusive with 217# @verbose-static. 218# 219# @verbose-static: The firmware unconditionally produces a large amount 220# of debug messages, which may impact boot performance. 221# This feature may typically be carried by certain UEFI 222# firmware for the "virt-*" machine types of the @arm 223# and @aarch64 emulation targets, where the debug 224# messages are written to the first (always present) 225# PL011 UART. @verbose-static is mutually exclusive 226# with @verbose-dynamic. 227# 228# @host-uefi-vars: The firmware expects the host to provide an uefi 229# variable store. qemu supports that via 230# "uefi-vars-sysbus" (aarch64, riscv64, loongarch64) 231# or "uefi-vars-x64" (x86_64) devices. The firmware 232# will not use flash for nvram. When loading the 233# firmware into flash the 'stateless' setup should be 234# used. It is recommened to load the firmware into 235# memory though. 236# 237# Since: 3.0 238## 239{ 'enum' : 'FirmwareFeature', 240 'data' : [ 'acpi-s3', 'acpi-s4', 241 'amd-sev', 'amd-sev-es', 'amd-sev-snp', 242 'intel-tdx', 243 'enrolled-keys', 'requires-smm', 244 'secure-boot', 'host-uefi-vars', 245 'verbose-dynamic', 'verbose-static' ] } 246 247## 248# @FirmwareFormat: 249# 250# Formats that are supported for firmware images. 251# 252# @raw: Raw disk image format. 253# 254# @qcow2: The QCOW2 image format. 255# 256# Since: 3.0 257## 258{ 'enum': 'FirmwareFormat', 259 'data': [ 'raw', 'qcow2' ] } 260 261## 262# @FirmwareFlashFile: 263# 264# Defines common properties that are necessary for loading a firmware 265# file into a pflash chip. The corresponding QEMU command line option is 266# "-drive file=@filename,format=@format". Note however that the 267# option-argument shown here is incomplete; it is completed under 268# @FirmwareMappingFlash. 269# 270# @filename: Specifies the filename on the host filesystem where the 271# firmware file can be found. 272# 273# @format: Specifies the block format of the file pointed-to by 274# @filename, such as @raw or @qcow2. 275# 276# Since: 3.0 277## 278{ 'struct' : 'FirmwareFlashFile', 279 'data' : { 'filename' : 'str', 280 'format' : 'FirmwareFormat' } } 281 282 283## 284# @FirmwareFlashMode: 285# 286# Describes how the firmware build handles code versus variable 287# persistence. 288# 289# @split: the executable file contains code while the NVRAM 290# template provides variable storage. The executable 291# must be configured read-only and can be shared between 292# multiple guests. The NVRAM template must be cloned 293# for each new guest and configured read-write. 294# 295# @combined: the executable file contains both code and 296# variable storage. The executable must be cloned 297# for each new guest and configured read-write. 298# No NVRAM template will be specified. 299# 300# @stateless: the executable file contains code and variable 301# storage is not persisted. The executable must 302# be configured read-only and can be shared 303# between multiple guests. No NVRAM template 304# will be specified. 305# 306# Since: 7.0.0 307## 308{ 'enum': 'FirmwareFlashMode', 309 'data': [ 'split', 'combined', 'stateless' ] } 310 311## 312# @FirmwareMappingFlash: 313# 314# Describes loading and mapping properties for the firmware executable 315# and its accompanying NVRAM file, when @FirmwareDevice is @flash. 316# 317# @mode: Describes how the firmware build handles code versus variable 318# storage. If not present, it must be treated as if it was 319# configured with value @split. Since: 7.0.0 320# 321# @executable: Identifies the firmware executable. The @mode 322# indicates whether there will be an associated 323# NVRAM template present. The preferred 324# corresponding QEMU command line options are 325# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format 326# -machine pflash0=pflash0 327# or equivalent -blockdev instead of -drive. When 328# @mode is @combined the executable must be 329# cloned before use and configured with readonly=off. 330# With QEMU versions older than 4.0, you have to use 331# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format 332# 333# @nvram-template: Identifies the NVRAM template compatible with 334# @executable, when @mode is set to @split, 335# otherwise it should not be present. 336# Management software instantiates an 337# individual copy -- a specific NVRAM file -- from 338# @nvram-template.@filename for each new virtual 339# machine definition created. @nvram-template.@filename 340# itself is never mapped into virtual machines, only 341# individual copies of it are. An NVRAM file is 342# typically used for persistently storing the 343# non-volatile UEFI variables of a virtual machine 344# definition. The preferred corresponding QEMU 345# command line options are 346# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 347# -machine pflash1=pflash1 348# or equivalent -blockdev instead of -drive. 349# With QEMU versions older than 4.0, you have to use 350# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format 351# 352# Since: 3.0 353## 354{ 'struct' : 'FirmwareMappingFlash', 355 'data' : { '*mode': 'FirmwareFlashMode', 356 'executable' : 'FirmwareFlashFile', 357 '*nvram-template' : 'FirmwareFlashFile' } } 358 359## 360# @FirmwareMappingKernel: 361# 362# Describes loading and mapping properties for the firmware executable, 363# when @FirmwareDevice is @kernel. 364# 365# @filename: Identifies the firmware executable. The firmware executable 366# may be shared by multiple virtual machine definitions. The 367# corresponding QEMU command line option is "-kernel 368# @filename". 369# 370# Since: 3.0 371## 372{ 'struct' : 'FirmwareMappingKernel', 373 'data' : { 'filename' : 'str' } } 374 375## 376# @FirmwareMappingMemory: 377# 378# Describes loading and mapping properties for the firmware executable, 379# when @FirmwareDevice is @memory. 380# 381# @filename: Identifies the firmware executable. The firmware executable 382# may be shared by multiple virtual machine definitions. The 383# corresponding QEMU command line option is "-bios 384# @filename". 385# 386# Since: 3.0 387## 388{ 'struct' : 'FirmwareMappingMemory', 389 'data' : { 'filename' : 'str' } } 390 391## 392# @FirmwareMappingIgvm: 393# 394# Describes loading and mapping properties for the firmware executable, 395# when @FirmwareDevice is @igvm. 396# 397# @filename: Identifies the IGVM file containing the firmware executable 398# along with other information used to configure the initial 399# state of the guest. The IGVM file may be shared by multiple 400# virtual machine definitions. This corresponds to creating 401# an object on the command line with "-object igvm-cfg, 402# file=@filename". 403# 404# Since: 10.1 405## 406{ 'struct' : 'FirmwareMappingIgvm', 407 'data' : { 'filename' : 'str' } } 408 409## 410# @FirmwareMapping: 411# 412# Provides a discriminated structure for firmware to describe its 413# loading / mapping properties. 414# 415# @device: Selects the device type that the firmware must be mapped 416# into. 417# 418# Since: 3.0 419## 420{ 'union' : 'FirmwareMapping', 421 'base' : { 'device' : 'FirmwareDevice' }, 422 'discriminator' : 'device', 423 'data' : { 'flash' : 'FirmwareMappingFlash', 424 'kernel' : 'FirmwareMappingKernel', 425 'memory' : 'FirmwareMappingMemory', 426 'igvm' : 'FirmwareMappingIgvm' } } 427 428## 429# @Firmware: 430# 431# Describes a firmware (or a firmware use case) to management software. 432# 433# It is possible for multiple @Firmware elements to match the search 434# criteria of management software. Applications thus need rules to pick 435# one of the many matches, and users need the ability to override distro 436# defaults. 437# 438# It is recommended to create firmware JSON files (each containing a 439# single @Firmware root element) with a double-digit prefix, for example 440# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in 441# predictable order. The firmware JSON files should be searched for in 442# three directories: 443# 444# - /usr/share/qemu/firmware -- populated by distro-provided firmware 445# packages (XDG_DATA_DIRS covers 446# /usr/share by default), 447# 448# - /etc/qemu/firmware -- exclusively for sysadmins' local additions, 449# 450# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local 451# additions (XDG_CONFIG_HOME 452# defaults to $HOME/.config). 453# 454# Top-down, the list of directories goes from general to specific. 455# 456# Management software should build a list of files from all three 457# locations, then sort the list by filename (i.e., last pathname 458# component). Management software should choose the first JSON file on 459# the sorted list that matches the search criteria. If a more specific 460# directory has a file with same name as a less specific directory, then 461# the file in the more specific directory takes effect. If the more 462# specific file is zero length, it hides the less specific one. 463# 464# For example, if a distro ships 465# 466# - /usr/share/qemu/firmware/50-ovmf.json 467# 468# - /usr/share/qemu/firmware/50-seabios-256k.json 469# 470# then the sysadmin can prevent the default OVMF being used at all with 471# 472# $ touch /etc/qemu/firmware/50-ovmf.json 473# 474# The sysadmin can replace/alter the distro default OVMF with 475# 476# $ vim /etc/qemu/firmware/50-ovmf.json 477# 478# or they can provide a parallel OVMF with higher priority 479# 480# $ vim /etc/qemu/firmware/10-ovmf.json 481# 482# or they can provide a parallel OVMF with lower priority 483# 484# $ vim /etc/qemu/firmware/99-ovmf.json 485# 486# @description: Provides a human-readable description of the firmware. 487# Management software may or may not display @description. 488# 489# @interface-types: Lists the types of interfaces that the firmware can 490# expose to the guest OS. This is a non-empty, ordered 491# list; entries near the beginning of @interface-types 492# are considered more native to the firmware, and/or 493# to have a higher quality implementation in the 494# firmware, than entries near the end of 495# @interface-types. 496# 497# @mapping: Describes the loading / mapping properties of the firmware. 498# 499# @targets: Collects the target architectures (QEMU system emulators) 500# and their machine types that may execute the firmware. 501# 502# @features: Lists the features that the firmware supports, and the 503# platform requirements it presents. 504# 505# @tags: A list of auxiliary strings associated with the firmware for 506# which @description is not appropriate, due to the latter's 507# possible exposure to the end-user. @tags serves development and 508# debugging purposes only, and management software shall 509# explicitly ignore it. 510# 511# Since: 3.0 512# 513# .. qmp-example:: 514# 515# { 516# "description": "SeaBIOS", 517# "interface-types": [ 518# "bios" 519# ], 520# "mapping": { 521# "device": "memory", 522# "filename": "/usr/share/seabios/bios-256k.bin" 523# }, 524# "targets": [ 525# { 526# "architecture": "i386", 527# "machines": [ 528# "pc-i440fx-*", 529# "pc-q35-*" 530# ] 531# }, 532# { 533# "architecture": "x86_64", 534# "machines": [ 535# "pc-i440fx-*", 536# "pc-q35-*" 537# ] 538# } 539# ], 540# "features": [ 541# "acpi-s3", 542# "acpi-s4" 543# ], 544# "tags": [ 545# "CONFIG_BOOTSPLASH=n", 546# "CONFIG_ROM_SIZE=256", 547# "CONFIG_USE_SMM=n" 548# ] 549# } 550# 551# { 552# "description": "OVMF with SB+SMM, empty varstore", 553# "interface-types": [ 554# "uefi" 555# ], 556# "mapping": { 557# "device": "flash", 558# "executable": { 559# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 560# "format": "raw" 561# }, 562# "nvram-template": { 563# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 564# "format": "raw" 565# } 566# }, 567# "targets": [ 568# { 569# "architecture": "x86_64", 570# "machines": [ 571# "pc-q35-*" 572# ] 573# } 574# ], 575# "features": [ 576# "acpi-s3", 577# "amd-sev", 578# "requires-smm", 579# "secure-boot", 580# "verbose-dynamic" 581# ], 582# "tags": [ 583# "-a IA32", 584# "-a X64", 585# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 586# "-t GCC48", 587# "-b DEBUG", 588# "-D SMM_REQUIRE", 589# "-D SECURE_BOOT_ENABLE", 590# "-D FD_SIZE_4MB" 591# ] 592# } 593# 594# { 595# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled", 596# "interface-types": [ 597# "uefi" 598# ], 599# "mapping": { 600# "device": "flash", 601# "executable": { 602# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd", 603# "format": "raw" 604# }, 605# "nvram-template": { 606# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd", 607# "format": "raw" 608# } 609# }, 610# "targets": [ 611# { 612# "architecture": "x86_64", 613# "machines": [ 614# "pc-q35-*" 615# ] 616# } 617# ], 618# "features": [ 619# "acpi-s3", 620# "amd-sev", 621# "enrolled-keys", 622# "requires-smm", 623# "secure-boot", 624# "verbose-dynamic" 625# ], 626# "tags": [ 627# "-a IA32", 628# "-a X64", 629# "-p OvmfPkg/OvmfPkgIa32X64.dsc", 630# "-t GCC48", 631# "-b DEBUG", 632# "-D SMM_REQUIRE", 633# "-D SECURE_BOOT_ENABLE", 634# "-D FD_SIZE_4MB" 635# ] 636# } 637# 638# { 639# "description": "OVMF with SEV-ES support", 640# "interface-types": [ 641# "uefi" 642# ], 643# "mapping": { 644# "device": "flash", 645# "executable": { 646# "filename": "/usr/share/OVMF/OVMF_CODE.fd", 647# "format": "raw" 648# }, 649# "nvram-template": { 650# "filename": "/usr/share/OVMF/OVMF_VARS.fd", 651# "format": "raw" 652# } 653# }, 654# "targets": [ 655# { 656# "architecture": "x86_64", 657# "machines": [ 658# "pc-q35-*" 659# ] 660# } 661# ], 662# "features": [ 663# "acpi-s3", 664# "amd-sev", 665# "amd-sev-es", 666# "verbose-dynamic" 667# ], 668# "tags": [ 669# "-a X64", 670# "-p OvmfPkg/OvmfPkgX64.dsc", 671# "-t GCC48", 672# "-b DEBUG", 673# "-D FD_SIZE_4MB" 674# ] 675# } 676# 677# { 678# "description": "UEFI firmware for ARM64 virtual machines", 679# "interface-types": [ 680# "uefi" 681# ], 682# "mapping": { 683# "device": "flash", 684# "executable": { 685# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd", 686# "format": "raw" 687# }, 688# "nvram-template": { 689# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd", 690# "format": "raw" 691# } 692# }, 693# "targets": [ 694# { 695# "architecture": "aarch64", 696# "machines": [ 697# "virt-*" 698# ] 699# } 700# ], 701# "features": [ 702# 703# ], 704# "tags": [ 705# "-a AARCH64", 706# "-p ArmVirtPkg/ArmVirtQemu.dsc", 707# "-t GCC48", 708# "-b DEBUG", 709# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" 710# ] 711# } 712## 713{ 'struct' : 'Firmware', 714 'data' : { 'description' : 'str', 715 'interface-types' : [ 'FirmwareOSInterface' ], 716 'mapping' : 'FirmwareMapping', 717 'targets' : [ 'FirmwareTarget' ], 718 'features' : [ 'FirmwareFeature' ], 719 'tags' : [ 'str' ] } } 720