| blob | 57f55f6c54555c6dae307e7cc2622bc272b4b527 |
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.
13 ##
14 # = Firmware
15 ##
17 { 'pragma': {
18 'member-name-exceptions': [
19 'FirmwareArchitecture' # x86_64
20 ] } }
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' ] }
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' ] }
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' ] }
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' ] } }
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' ] }
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' ] }
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' } }
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' ] }
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' } }
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' } }
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' } }
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' } }
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' ] } }