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