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