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