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