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