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