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