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