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