| blob | 8d8b0be030e53278cc31b8e766c825e0884ffa31 |
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
4 # Copyright (C) 2018 Red Hat, Inc.
5 #
6 # Authors:
7 # Daniel P. Berrange <berrange@redhat.com>
8 # Laszlo Ersek <lersek@redhat.com>
9 #
10 # This work is licensed under the terms of the GNU GPL, version 2 or
11 # later. See the COPYING file in the top-level directory.
13 ##
14 # = Firmware
15 ##
17 { 'include' : 'machine.json' }
18 { 'include' : 'block-core.json' }
20 ##
21 # @FirmwareOSInterface:
22 #
23 # Lists the firmware-OS interface types provided by various firmware
24 # that is commonly used with QEMU virtual machines.
25 #
26 # @bios: Traditional x86 BIOS interface. For example, firmware built
27 # from the SeaBIOS project usually provides this interface.
28 #
29 # @openfirmware: The interface is defined by the (historical) IEEE
30 # 1275-1994 standard. Examples for firmware projects that
31 # provide this interface are: OpenBIOS and SLOF.
32 #
33 # @uboot: Firmware interface defined by the U-Boot project.
34 #
35 # @uefi: Firmware interface defined by the UEFI specification. For
36 # example, firmware built from the edk2 (EFI Development Kit II)
37 # project usually provides this interface.
38 #
39 # Since: 3.0
40 ##
41 { 'enum' : 'FirmwareOSInterface',
42 'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] }
44 ##
45 # @FirmwareDevice:
46 #
47 # Defines the device types that firmware can be mapped into.
48 #
49 # @flash: The firmware executable and its accompanying NVRAM file are to
50 # be mapped into a pflash chip each.
51 #
52 # @kernel: The firmware is to be loaded like a Linux kernel. This is
53 # similar to @memory but may imply additional processing that
54 # is specific to the target architecture and machine type.
55 #
56 # @memory: The firmware is to be mapped into memory.
57 #
58 # Since: 3.0
59 ##
60 { 'enum' : 'FirmwareDevice',
61 'data' : [ 'flash', 'kernel', 'memory' ] }
63 ##
64 # @FirmwareTarget:
65 #
66 # Defines the machine types that firmware may execute on.
67 #
68 # @architecture: Determines the emulation target (the QEMU system
69 # emulator) that can execute the firmware.
70 #
71 # @machines: Lists the machine types (known by the emulator that is
72 # specified through @architecture) that can execute the
73 # firmware. Elements of @machines are supposed to be concrete
74 # machine types, not aliases. Glob patterns are understood,
75 # which is especially useful for versioned machine types.
76 # (For example, the glob pattern "pc-i440fx-*" matches
77 # "pc-i440fx-2.12".) On the QEMU command line, "-machine
78 # type=..." specifies the requested machine type (but that
79 # option does not accept glob patterns).
80 #
81 # Since: 3.0
82 ##
83 { 'struct' : 'FirmwareTarget',
84 'data' : { 'architecture' : 'SysEmuTarget',
85 'machines' : [ 'str' ] } }
87 ##
88 # @FirmwareFeature:
89 #
90 # Defines the features that firmware may support, and the platform
91 # requirements that firmware may present.
92 #
93 # @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined
94 # in the ACPI specification. On the "pc-i440fx-*" machine
95 # types of the @i386 and @x86_64 emulation targets, S3 can be
96 # enabled with "-global PIIX4_PM.disable_s3=0" and disabled
97 # with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*"
98 # machine types of the @i386 and @x86_64 emulation targets, S3
99 # can be enabled with "-global ICH9-LPC.disable_s3=0" and
100 # disabled with "-global ICH9-LPC.disable_s3=1".
101 #
102 # @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as
103 # defined in the ACPI specification. On the "pc-i440fx-*"
104 # machine types of the @i386 and @x86_64 emulation targets, S4
105 # can be enabled with "-global PIIX4_PM.disable_s4=0" and
106 # disabled with "-global PIIX4_PM.disable_s4=1". On the
107 # "pc-q35-*" machine types of the @i386 and @x86_64 emulation
108 # targets, S4 can be enabled with "-global
109 # ICH9-LPC.disable_s4=0" and disabled with "-global
110 # ICH9-LPC.disable_s4=1".
111 #
112 # @amd-sev: The firmware supports running under AMD Secure Encrypted
113 # Virtualization, as specified in the AMD64 Architecture
114 # Programmer's Manual. QEMU command line options related to
115 # this feature are documented in
116 # "docs/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' ] }
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' } }
213 ##
214 # @FirmwareMappingFlash:
215 #
216 # Describes loading and mapping properties for the firmware executable
217 # and its accompanying NVRAM file, when @FirmwareDevice is @flash.
218 #
219 # @executable: Identifies the firmware executable. The firmware
220 # executable may be shared by multiple virtual machine
221 # definitions. The preferred corresponding QEMU command
222 # line options are
223 # -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
224 # -machine pflash0=pflash0
225 # or equivalent -blockdev instead of -drive.
226 # With QEMU versions older than 4.0, you have to use
227 # -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
228 #
229 # @nvram-template: Identifies the NVRAM template compatible with
230 # @executable. Management software instantiates an
231 # individual copy -- a specific NVRAM file -- from
232 # @nvram-template.@filename for each new virtual
233 # machine definition created. @nvram-template.@filename
234 # itself is never mapped into virtual machines, only
235 # individual copies of it are. An NVRAM file is
236 # typically used for persistently storing the
237 # non-volatile UEFI variables of a virtual machine
238 # definition. The preferred corresponding QEMU
239 # command line options are
240 # -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
241 # -machine pflash1=pflash1
242 # or equivalent -blockdev instead of -drive.
243 # With QEMU versions older than 4.0, you have to use
244 # -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
245 #
246 # Since: 3.0
247 ##
248 { 'struct' : 'FirmwareMappingFlash',
249 'data' : { 'executable' : 'FirmwareFlashFile',
250 'nvram-template' : 'FirmwareFlashFile' } }
252 ##
253 # @FirmwareMappingKernel:
254 #
255 # Describes loading and mapping properties for the firmware executable,
256 # when @FirmwareDevice is @kernel.
257 #
258 # @filename: Identifies the firmware executable. The firmware executable
259 # may be shared by multiple virtual machine definitions. The
260 # corresponding QEMU command line option is "-kernel
261 # @filename".
262 #
263 # Since: 3.0
264 ##
265 { 'struct' : 'FirmwareMappingKernel',
266 'data' : { 'filename' : 'str' } }
268 ##
269 # @FirmwareMappingMemory:
270 #
271 # Describes loading and mapping properties for the firmware executable,
272 # when @FirmwareDevice is @memory.
273 #
274 # @filename: Identifies the firmware executable. The firmware executable
275 # may be shared by multiple virtual machine definitions. The
276 # corresponding QEMU command line option is "-bios
277 # @filename".
278 #
279 # Since: 3.0
280 ##
281 { 'struct' : 'FirmwareMappingMemory',
282 'data' : { 'filename' : 'str' } }
284 ##
285 # @FirmwareMapping:
286 #
287 # Provides a discriminated structure for firmware to describe its
288 # loading / mapping properties.
289 #
290 # @device: Selects the device type that the firmware must be mapped
291 # into.
292 #
293 # Since: 3.0
294 ##
295 { 'union' : 'FirmwareMapping',
296 'base' : { 'device' : 'FirmwareDevice' },
297 'discriminator' : 'device',
298 'data' : { 'flash' : 'FirmwareMappingFlash',
299 'kernel' : 'FirmwareMappingKernel',
300 'memory' : 'FirmwareMappingMemory' } }
302 ##
303 # @Firmware:
304 #
305 # Describes a firmware (or a firmware use case) to management software.
306 #
307 # It is possible for multiple @Firmware elements to match the search
308 # criteria of management software. Applications thus need rules to pick
309 # one of the many matches, and users need the ability to override distro
310 # defaults.
311 #
312 # It is recommended to create firmware JSON files (each containing a
313 # single @Firmware root element) with a double-digit prefix, for example
314 # "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
315 # predictable order. The firmware JSON files should be searched for in
316 # three directories:
317 #
318 # - /usr/share/qemu/firmware -- populated by distro-provided firmware
319 # packages (XDG_DATA_DIRS covers
320 # /usr/share by default),
321 #
322 # - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
323 #
324 # - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
325 # additions (XDG_CONFIG_HOME
326 # defaults to $HOME/.config).
327 #
328 # Top-down, the list of directories goes from general to specific.
329 #
330 # Management software should build a list of files from all three
331 # locations, then sort the list by filename (i.e., last pathname
332 # component). Management software should choose the first JSON file on
333 # the sorted list that matches the search criteria. If a more specific
334 # directory has a file with same name as a less specific directory, then
335 # the file in the more specific directory takes effect. If the more
336 # specific file is zero length, it hides the less specific one.
337 #
338 # For example, if a distro ships
339 #
340 # - /usr/share/qemu/firmware/50-ovmf.json
341 #
342 # - /usr/share/qemu/firmware/50-seabios-256k.json
343 #
344 # then the sysadmin can prevent the default OVMF being used at all with
345 #
346 # $ touch /etc/qemu/firmware/50-ovmf.json
347 #
348 # The sysadmin can replace/alter the distro default OVMF with
349 #
350 # $ vim /etc/qemu/firmware/50-ovmf.json
351 #
352 # or they can provide a parallel OVMF with higher priority
353 #
354 # $ vim /etc/qemu/firmware/10-ovmf.json
355 #
356 # or they can provide a parallel OVMF with lower priority
357 #
358 # $ vim /etc/qemu/firmware/99-ovmf.json
359 #
360 # @description: Provides a human-readable description of the firmware.
361 # Management software may or may not display @description.
362 #
363 # @interface-types: Lists the types of interfaces that the firmware can
364 # expose to the guest OS. This is a non-empty, ordered
365 # list; entries near the beginning of @interface-types
366 # are considered more native to the firmware, and/or
367 # to have a higher quality implementation in the
368 # firmware, than entries near the end of
369 # @interface-types.
370 #
371 # @mapping: Describes the loading / mapping properties of the firmware.
372 #
373 # @targets: Collects the target architectures (QEMU system emulators)
374 # and their machine types that may execute the firmware.
375 #
376 # @features: Lists the features that the firmware supports, and the
377 # platform requirements it presents.
378 #
379 # @tags: A list of auxiliary strings associated with the firmware for
380 # which @description is not appropriate, due to the latter's
381 # possible exposure to the end-user. @tags serves development and
382 # debugging purposes only, and management software shall
383 # explicitly ignore it.
384 #
385 # Since: 3.0
386 #
387 # Examples:
388 #
389 # {
390 # "description": "SeaBIOS",
391 # "interface-types": [
392 # "bios"
393 # ],
394 # "mapping": {
395 # "device": "memory",
396 # "filename": "/usr/share/seabios/bios-256k.bin"
397 # },
398 # "targets": [
399 # {
400 # "architecture": "i386",
401 # "machines": [
402 # "pc-i440fx-*",
403 # "pc-q35-*"
404 # ]
405 # },
406 # {
407 # "architecture": "x86_64",
408 # "machines": [
409 # "pc-i440fx-*",
410 # "pc-q35-*"
411 # ]
412 # }
413 # ],
414 # "features": [
415 # "acpi-s3",
416 # "acpi-s4"
417 # ],
418 # "tags": [
419 # "CONFIG_BOOTSPLASH=n",
420 # "CONFIG_ROM_SIZE=256",
421 # "CONFIG_USE_SMM=n"
422 # ]
423 # }
424 #
425 # {
426 # "description": "OVMF with SB+SMM, empty varstore",
427 # "interface-types": [
428 # "uefi"
429 # ],
430 # "mapping": {
431 # "device": "flash",
432 # "executable": {
433 # "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
434 # "format": "raw"
435 # },
436 # "nvram-template": {
437 # "filename": "/usr/share/OVMF/OVMF_VARS.fd",
438 # "format": "raw"
439 # }
440 # },
441 # "targets": [
442 # {
443 # "architecture": "x86_64",
444 # "machines": [
445 # "pc-q35-*"
446 # ]
447 # }
448 # ],
449 # "features": [
450 # "acpi-s3",
451 # "amd-sev",
452 # "requires-smm",
453 # "secure-boot",
454 # "verbose-dynamic"
455 # ],
456 # "tags": [
457 # "-a IA32",
458 # "-a X64",
459 # "-p OvmfPkg/OvmfPkgIa32X64.dsc",
460 # "-t GCC48",
461 # "-b DEBUG",
462 # "-D SMM_REQUIRE",
463 # "-D SECURE_BOOT_ENABLE",
464 # "-D FD_SIZE_4MB"
465 # ]
466 # }
467 #
468 # {
469 # "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled",
470 # "interface-types": [
471 # "uefi"
472 # ],
473 # "mapping": {
474 # "device": "flash",
475 # "executable": {
476 # "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
477 # "format": "raw"
478 # },
479 # "nvram-template": {
480 # "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd",
481 # "format": "raw"
482 # }
483 # },
484 # "targets": [
485 # {
486 # "architecture": "x86_64",
487 # "machines": [
488 # "pc-q35-*"
489 # ]
490 # }
491 # ],
492 # "features": [
493 # "acpi-s3",
494 # "amd-sev",
495 # "enrolled-keys",
496 # "requires-smm",
497 # "secure-boot",
498 # "verbose-dynamic"
499 # ],
500 # "tags": [
501 # "-a IA32",
502 # "-a X64",
503 # "-p OvmfPkg/OvmfPkgIa32X64.dsc",
504 # "-t GCC48",
505 # "-b DEBUG",
506 # "-D SMM_REQUIRE",
507 # "-D SECURE_BOOT_ENABLE",
508 # "-D FD_SIZE_4MB"
509 # ]
510 # }
511 #
512 # {
513 # "description": "OVMF with SEV-ES support",
514 # "interface-types": [
515 # "uefi"
516 # ],
517 # "mapping": {
518 # "device": "flash",
519 # "executable": {
520 # "filename": "/usr/share/OVMF/OVMF_CODE.fd",
521 # "format": "raw"
522 # },
523 # "nvram-template": {
524 # "filename": "/usr/share/OVMF/OVMF_VARS.fd",
525 # "format": "raw"
526 # }
527 # },
528 # "targets": [
529 # {
530 # "architecture": "x86_64",
531 # "machines": [
532 # "pc-q35-*"
533 # ]
534 # }
535 # ],
536 # "features": [
537 # "acpi-s3",
538 # "amd-sev",
539 # "amd-sev-es",
540 # "verbose-dynamic"
541 # ],
542 # "tags": [
543 # "-a X64",
544 # "-p OvmfPkg/OvmfPkgX64.dsc",
545 # "-t GCC48",
546 # "-b DEBUG",
547 # "-D FD_SIZE_4MB"
548 # ]
549 # }
550 #
551 # {
552 # "description": "UEFI firmware for ARM64 virtual machines",
553 # "interface-types": [
554 # "uefi"
555 # ],
556 # "mapping": {
557 # "device": "flash",
558 # "executable": {
559 # "filename": "/usr/share/AAVMF/AAVMF_CODE.fd",
560 # "format": "raw"
561 # },
562 # "nvram-template": {
563 # "filename": "/usr/share/AAVMF/AAVMF_VARS.fd",
564 # "format": "raw"
565 # }
566 # },
567 # "targets": [
568 # {
569 # "architecture": "aarch64",
570 # "machines": [
571 # "virt-*"
572 # ]
573 # }
574 # ],
575 # "features": [
576 #
577 # ],
578 # "tags": [
579 # "-a AARCH64",
580 # "-p ArmVirtPkg/ArmVirtQemu.dsc",
581 # "-t GCC48",
582 # "-b DEBUG",
583 # "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
584 # ]
585 # }
586 ##
587 { 'struct' : 'Firmware',
588 'data' : { 'description' : 'str',
589 'interface-types' : [ 'FirmwareOSInterface' ],
590 'mapping' : 'FirmwareMapping',
591 'targets' : [ 'FirmwareTarget' ],
592 'features' : [ 'FirmwareFeature' ],
593 'tags' : [ 'str' ] } }