hw/arm/boot: Further improve initrd positioning code
[qemu/ar7.git] / docs / interop / firmware.json
blobff8c2ce5f2217a0bf33c8d44359279531969ac49
1 # -*- Mode: Python -*-
3 # Copyright (C) 2018 Red Hat, Inc.
5 # Authors:
6 #  Daniel P. Berrange <berrange@redhat.com>
7 #  Laszlo Ersek <lersek@redhat.com>
9 # This work is licensed under the terms of the GNU GPL, version 2 or
10 # later. See the COPYING file in the top-level directory.
13 # = Firmware
16 { 'include' : 'common.json' }
17 { 'include' : 'block-core.json' }
20 # @FirmwareOSInterface:
22 # Lists the firmware-OS interface types provided by various firmware
23 # that is commonly used with QEMU virtual machines.
25 # @bios: Traditional x86 BIOS interface. For example, firmware built
26 #        from the SeaBIOS project usually provides this interface.
28 # @openfirmware: The interface is defined by the (historical) IEEE
29 #                1275-1994 standard. Examples for firmware projects that
30 #                provide this interface are: OpenBIOS, OpenHackWare,
31 #                SLOF.
33 # @uboot: Firmware interface defined by the U-Boot project.
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.
39 # Since: 3.0
41 { 'enum' : 'FirmwareOSInterface',
42   'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] }
45 # @FirmwareDevice:
47 # Defines the device types that firmware can be mapped into.
49 # @flash: The firmware executable and its accompanying NVRAM file are to
50 #         be mapped into a pflash chip each.
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.
56 # @memory: The firmware is to be mapped into memory.
58 # Since: 3.0
60 { 'enum' : 'FirmwareDevice',
61   'data' : [ 'flash', 'kernel', 'memory' ] }
64 # @FirmwareTarget:
66 # Defines the machine types that firmware may execute on.
68 # @architecture: Determines the emulation target (the QEMU system
69 #                emulator) that can execute the firmware.
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).
81 # Since: 3.0
83 { 'struct' : 'FirmwareTarget',
84   'data'   : { 'architecture' : 'SysEmuTarget',
85                'machines'     : [ 'str' ] } }
88 # @FirmwareFeature:
90 # Defines the features that firmware may support, and the platform
91 # requirements that firmware may present.
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".
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".
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".
118 # @enrolled-keys: The variable store (NVRAM) template associated with
119 #                 the firmware binary has the UEFI Secure Boot
120 #                 operational mode turned on, with certificates
121 #                 enrolled.
123 # @requires-smm: The firmware requires the platform to emulate SMM
124 #                (System Management Mode), as defined in the AMD64
125 #                Architecture Programmer's Manual, and in the Intel(R)64
126 #                and IA-32 Architectures Software Developer's Manual. On
127 #                the "pc-q35-*" machine types of the @i386 and @x86_64
128 #                emulation targets, SMM emulation can be enabled with
129 #                "-machine smm=on". (On the "pc-q35-*" machine types of
130 #                the @i386 emulation target, @requires-smm presents
131 #                further CPU requirements; one combination known to work
132 #                is "-cpu coreduo,-nx".) If the firmware is marked as
133 #                both @secure-boot and @requires-smm, then write
134 #                accesses to the pflash chip (NVRAM) that holds the UEFI
135 #                variable store must be restricted to code that executes
136 #                in SMM, using the additional option "-global
137 #                driver=cfi.pflash01,property=secure,value=on".
138 #                Furthermore, a large guest-physical address space
139 #                (comprising guest RAM, memory hotplug range, and 64-bit
140 #                PCI MMIO aperture), and/or a high VCPU count, may
141 #                present high SMRAM requirements from the firmware. On
142 #                the "pc-q35-*" machine types of the @i386 and @x86_64
143 #                emulation targets, the SMRAM size may be increased
144 #                above the default 16MB with the "-global
145 #                mch.extended-tseg-mbytes=uint16" option. As a rule of
146 #                thumb, the default 16MB size suffices for 1TB of
147 #                guest-phys address space and a few tens of VCPUs; for
148 #                every further TB of guest-phys address space, add 8MB
149 #                of SMRAM. 48MB should suffice for 4TB of guest-phys
150 #                address space and 2-3 hundred VCPUs.
152 # @secure-boot: The firmware implements the software interfaces for UEFI
153 #               Secure Boot, as defined in the UEFI specification. Note
154 #               that without @requires-smm, guest code running with
155 #               kernel privileges can undermine the security of Secure
156 #               Boot.
158 # @verbose-dynamic: When firmware log capture is enabled, the firmware
159 #                   logs a large amount of debug messages, which may
160 #                   impact boot performance. With log capture disabled,
161 #                   there is no boot performance impact. On the
162 #                   "pc-i440fx-*" and "pc-q35-*" machine types of the
163 #                   @i386 and @x86_64 emulation targets, firmware log
164 #                   capture can be enabled with the QEMU command line
165 #                   options "-chardev file,id=fwdebug,path=LOGFILEPATH
166 #                   -device isa-debugcon,iobase=0x402,chardev=fwdebug".
167 #                   @verbose-dynamic is mutually exclusive with
168 #                   @verbose-static.
170 # @verbose-static: The firmware unconditionally produces a large amount
171 #                  of debug messages, which may impact boot performance.
172 #                  This feature may typically be carried by certain UEFI
173 #                  firmware for the "virt-*" machine types of the @arm
174 #                  and @aarch64 emulation targets, where the debug
175 #                  messages are written to the first (always present)
176 #                  PL011 UART. @verbose-static is mutually exclusive
177 #                  with @verbose-dynamic.
179 # Since: 3.0
181 { 'enum' : 'FirmwareFeature',
182   'data' : [ 'acpi-s3', 'acpi-s4', 'amd-sev', 'enrolled-keys',
183              'requires-smm', 'secure-boot', 'verbose-dynamic',
184              'verbose-static' ] }
187 # @FirmwareFlashFile:
189 # Defines common properties that are necessary for loading a firmware
190 # file into a pflash chip. The corresponding QEMU command line option is
191 # "-drive file=@filename,format=@format". Note however that the
192 # option-argument shown here is incomplete; it is completed under
193 # @FirmwareMappingFlash.
195 # @filename: Specifies the filename on the host filesystem where the
196 #            firmware file can be found.
198 # @format: Specifies the block format of the file pointed-to by
199 #          @filename, such as @raw or @qcow2.
201 # Since: 3.0
203 { 'struct' : 'FirmwareFlashFile',
204   'data'   : { 'filename' : 'str',
205                'format'   : 'BlockdevDriver' } }
208 # @FirmwareMappingFlash:
210 # Describes loading and mapping properties for the firmware executable
211 # and its accompanying NVRAM file, when @FirmwareDevice is @flash.
213 # @executable: Identifies the firmware executable. The firmware
214 #              executable may be shared by multiple virtual machine
215 #              definitions. The preferred corresponding QEMU command
216 #              line options are
217 #                  -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
218 #                  -machine pflash0=pflash0
219 #              or equivalent -blockdev instead of -drive.
220 #              With QEMU versions older than 4.0, you have to use
221 #                  -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
223 # @nvram-template: Identifies the NVRAM template compatible with
224 #                  @executable. Management software instantiates an
225 #                  individual copy -- a specific NVRAM file -- from
226 #                  @nvram-template.@filename for each new virtual
227 #                  machine definition created. @nvram-template.@filename
228 #                  itself is never mapped into virtual machines, only
229 #                  individual copies of it are. An NVRAM file is
230 #                  typically used for persistently storing the
231 #                  non-volatile UEFI variables of a virtual machine
232 #                  definition. The preferred corresponding QEMU
233 #                  command line options are
234 #                      -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
235 #                      -machine pflash1=pflash1
236 #                  or equivalent -blockdev instead of -drive.
237 #                  With QEMU versions older than 4.0, you have to use
238 #                      -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
240 # Since: 3.0
242 { 'struct' : 'FirmwareMappingFlash',
243   'data'   : { 'executable'     : 'FirmwareFlashFile',
244                'nvram-template' : 'FirmwareFlashFile' } }
247 # @FirmwareMappingKernel:
249 # Describes loading and mapping properties for the firmware executable,
250 # when @FirmwareDevice is @kernel.
252 # @filename: Identifies the firmware executable. The firmware executable
253 #            may be shared by multiple virtual machine definitions. The
254 #            corresponding QEMU command line option is "-kernel
255 #            @filename".
257 # Since: 3.0
259 { 'struct' : 'FirmwareMappingKernel',
260   'data'   : { 'filename' : 'str' } }
263 # @FirmwareMappingMemory:
265 # Describes loading and mapping properties for the firmware executable,
266 # when @FirmwareDevice is @memory.
268 # @filename: Identifies the firmware executable. The firmware executable
269 #            may be shared by multiple virtual machine definitions. The
270 #            corresponding QEMU command line option is "-bios
271 #            @filename".
273 # Since: 3.0
275 { 'struct' : 'FirmwareMappingMemory',
276   'data'   : { 'filename' : 'str' } }
279 # @FirmwareMapping:
281 # Provides a discriminated structure for firmware to describe its
282 # loading / mapping properties.
284 # @device: Selects the device type that the firmware must be mapped
285 #          into.
287 # Since: 3.0
289 { 'union'         : 'FirmwareMapping',
290   'base'          : { 'device' : 'FirmwareDevice' },
291   'discriminator' : 'device',
292   'data'          : { 'flash'  : 'FirmwareMappingFlash',
293                       'kernel' : 'FirmwareMappingKernel',
294                       'memory' : 'FirmwareMappingMemory' } }
297 # @Firmware:
299 # Describes a firmware (or a firmware use case) to management software.
301 # It is possible for multiple @Firmware elements to match the search
302 # criteria of management software. Applications thus need rules to pick
303 # one of the many matches, and users need the ability to override distro
304 # defaults.
306 # It is recommended to create firmware JSON files (each containing a
307 # single @Firmware root element) with a double-digit prefix, for example
308 # "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
309 # predictable order. The firmware JSON files should be searched for in
310 # three directories:
312 #   - /usr/share/qemu/firmware -- populated by distro-provided firmware
313 #                                 packages (XDG_DATA_DIRS covers
314 #                                 /usr/share by default),
316 #   - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
318 #   - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
319 #                                       additions (XDG_CONFIG_HOME
320 #                                       defaults to $HOME/.config).
322 # Top-down, the list of directories goes from general to specific.
324 # Management software should build a list of files from all three
325 # locations, then sort the list by filename (i.e., last pathname
326 # component). Management software should choose the first JSON file on
327 # the sorted list that matches the search criteria. If a more specific
328 # directory has a file with same name as a less specific directory, then
329 # the file in the more specific directory takes effect. If the more
330 # specific file is zero length, it hides the less specific one.
332 # For example, if a distro ships
334 #   - /usr/share/qemu/firmware/50-ovmf.json
336 #   - /usr/share/qemu/firmware/50-seabios-256k.json
338 # then the sysadmin can prevent the default OVMF being used at all with
340 #   $ touch /etc/qemu/firmware/50-ovmf.json
342 # The sysadmin can replace/alter the distro default OVMF with
344 #   $ vim /etc/qemu/firmware/50-ovmf.json
346 # or they can provide a parallel OVMF with higher priority
348 #   $ vim /etc/qemu/firmware/10-ovmf.json
350 # or they can provide a parallel OVMF with lower priority
352 #   $ vim /etc/qemu/firmware/99-ovmf.json
354 # @description: Provides a human-readable description of the firmware.
355 #               Management software may or may not display @description.
357 # @interface-types: Lists the types of interfaces that the firmware can
358 #                   expose to the guest OS. This is a non-empty, ordered
359 #                   list; entries near the beginning of @interface-types
360 #                   are considered more native to the firmware, and/or
361 #                   to have a higher quality implementation in the
362 #                   firmware, than entries near the end of
363 #                   @interface-types.
365 # @mapping: Describes the loading / mapping properties of the firmware.
367 # @targets: Collects the target architectures (QEMU system emulators)
368 #           and their machine types that may execute the firmware.
370 # @features: Lists the features that the firmware supports, and the
371 #            platform requirements it presents.
373 # @tags: A list of auxiliary strings associated with the firmware for
374 #        which @description is not appropriate, due to the latter's
375 #        possible exposure to the end-user. @tags serves development and
376 #        debugging purposes only, and management software shall
377 #        explicitly ignore it.
379 # Since: 3.0
381 # Examples:
383 # {
384 #     "description": "SeaBIOS",
385 #     "interface-types": [
386 #         "bios"
387 #     ],
388 #     "mapping": {
389 #         "device": "memory",
390 #         "filename": "/usr/share/seabios/bios-256k.bin"
391 #     },
392 #     "targets": [
393 #         {
394 #             "architecture": "i386",
395 #             "machines": [
396 #                 "pc-i440fx-*",
397 #                 "pc-q35-*"
398 #             ]
399 #         },
400 #         {
401 #             "architecture": "x86_64",
402 #             "machines": [
403 #                 "pc-i440fx-*",
404 #                 "pc-q35-*"
405 #             ]
406 #         }
407 #     ],
408 #     "features": [
409 #         "acpi-s3",
410 #         "acpi-s4"
411 #     ],
412 #     "tags": [
413 #         "CONFIG_BOOTSPLASH=n",
414 #         "CONFIG_ROM_SIZE=256",
415 #         "CONFIG_USE_SMM=n"
416 #     ]
417 # }
419 # {
420 #     "description": "OVMF with SB+SMM, empty varstore",
421 #     "interface-types": [
422 #         "uefi"
423 #     ],
424 #     "mapping": {
425 #         "device": "flash",
426 #         "executable": {
427 #             "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
428 #             "format": "raw"
429 #         },
430 #         "nvram-template": {
431 #             "filename": "/usr/share/OVMF/OVMF_VARS.fd",
432 #             "format": "raw"
433 #         }
434 #     },
435 #     "targets": [
436 #         {
437 #             "architecture": "x86_64",
438 #             "machines": [
439 #                 "pc-q35-*"
440 #             ]
441 #         }
442 #     ],
443 #     "features": [
444 #         "acpi-s3",
445 #         "amd-sev",
446 #         "requires-smm",
447 #         "secure-boot",
448 #         "verbose-dynamic"
449 #     ],
450 #     "tags": [
451 #         "-a IA32",
452 #         "-a X64",
453 #         "-p OvmfPkg/OvmfPkgIa32X64.dsc",
454 #         "-t GCC48",
455 #         "-b DEBUG",
456 #         "-D SMM_REQUIRE",
457 #         "-D SECURE_BOOT_ENABLE",
458 #         "-D FD_SIZE_4MB"
459 #     ]
460 # }
462 # {
463 #     "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled",
464 #     "interface-types": [
465 #         "uefi"
466 #     ],
467 #     "mapping": {
468 #         "device": "flash",
469 #         "executable": {
470 #             "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
471 #             "format": "raw"
472 #         },
473 #         "nvram-template": {
474 #             "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd",
475 #             "format": "raw"
476 #         }
477 #     },
478 #     "targets": [
479 #         {
480 #             "architecture": "x86_64",
481 #             "machines": [
482 #                 "pc-q35-*"
483 #             ]
484 #         }
485 #     ],
486 #     "features": [
487 #         "acpi-s3",
488 #         "amd-sev",
489 #         "enrolled-keys",
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 # }
506 # {
507 #     "description": "UEFI firmware for ARM64 virtual machines",
508 #     "interface-types": [
509 #         "uefi"
510 #     ],
511 #     "mapping": {
512 #         "device": "flash",
513 #         "executable": {
514 #             "filename": "/usr/share/AAVMF/AAVMF_CODE.fd",
515 #             "format": "raw"
516 #         },
517 #         "nvram-template": {
518 #             "filename": "/usr/share/AAVMF/AAVMF_VARS.fd",
519 #             "format": "raw"
520 #         }
521 #     },
522 #     "targets": [
523 #         {
524 #             "architecture": "aarch64",
525 #             "machines": [
526 #                 "virt-*"
527 #             ]
528 #         }
529 #     ],
530 #     "features": [
532 #     ],
533 #     "tags": [
534 #         "-a AARCH64",
535 #         "-p ArmVirtPkg/ArmVirtQemu.dsc",
536 #         "-t GCC48",
537 #         "-b DEBUG",
538 #         "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
539 #     ]
540 # }
542 { 'struct' : 'Firmware',
543   'data'   : { 'description'     : 'str',
544                'interface-types' : [ 'FirmwareOSInterface' ],
545                'mapping'         : 'FirmwareMapping',
546                'targets'         : [ 'FirmwareTarget' ],
547                'features'        : [ 'FirmwareFeature' ],
548                'tags'            : [ 'str' ] } }