| blob | cc8f869186817ea5c33c534aa01acc314e5c235b |
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 { 'include' : 'machine.json' }
18 { 'include' : 'block-core.json' }
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' ] }
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' ] }
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' ] } }
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' ] }
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' } }
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' ] }
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' } }
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' } }
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' } }
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' } }
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' ] } }