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