| blob | 28f9bc15914aade5422ee6c2020a91cb2472b0ff |
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.
12 ##
13 # = Firmware
14 ##
16 { 'include' : 'common.json' }
17 { 'include' : 'block-core.json' }
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, OpenHackWare,
31 # 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 # @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.
122 #
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.
151 #
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.
157 #
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.
169 #
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.
178 #
179 # Since: 3.0
180 ##
181 { 'enum' : 'FirmwareFeature',
182 'data' : [ 'acpi-s3', 'acpi-s4', 'amd-sev', 'enrolled-keys',
183 'requires-smm', 'secure-boot', 'verbose-dynamic',
184 'verbose-static' ] }
186 ##
187 # @FirmwareFlashFile:
188 #
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.
194 #
195 # @filename: Specifies the filename on the host filesystem where the
196 # firmware file can be found.
197 #
198 # @format: Specifies the block format of the file pointed-to by
199 # @filename, such as @raw or @qcow2.
200 #
201 # Since: 3.0
202 ##
203 { 'struct' : 'FirmwareFlashFile',
204 'data' : { 'filename' : 'str',
205 'format' : 'BlockdevDriver' } }
207 ##
208 # @FirmwareMappingFlash:
209 #
210 # Describes loading and mapping properties for the firmware executable
211 # and its accompanying NVRAM file, when @FirmwareDevice is @flash.
212 #
213 # @executable: Identifies the firmware executable. The firmware
214 # executable may be shared by multiple virtual machine
215 # definitions. The corresponding QEMU command line option
216 # is "-drive
217 # if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format".
218 #
219 # @nvram-template: Identifies the NVRAM template compatible with
220 # @executable. Management software instantiates an
221 # individual copy -- a specific NVRAM file -- from
222 # @nvram-template.@filename for each new virtual
223 # machine definition created. @nvram-template.@filename
224 # itself is never mapped into virtual machines, only
225 # individual copies of it are. An NVRAM file is
226 # typically used for persistently storing the
227 # non-volatile UEFI variables of a virtual machine
228 # definition. The corresponding QEMU command line
229 # option is "-drive
230 # if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format".
231 #
232 # Since: 3.0
233 ##
234 { 'struct' : 'FirmwareMappingFlash',
235 'data' : { 'executable' : 'FirmwareFlashFile',
236 'nvram-template' : 'FirmwareFlashFile' } }
238 ##
239 # @FirmwareMappingKernel:
240 #
241 # Describes loading and mapping properties for the firmware executable,
242 # when @FirmwareDevice is @kernel.
243 #
244 # @filename: Identifies the firmware executable. The firmware executable
245 # may be shared by multiple virtual machine definitions. The
246 # corresponding QEMU command line option is "-kernel
247 # @filename".
248 #
249 # Since: 3.0
250 ##
251 { 'struct' : 'FirmwareMappingKernel',
252 'data' : { 'filename' : 'str' } }
254 ##
255 # @FirmwareMappingMemory:
256 #
257 # Describes loading and mapping properties for the firmware executable,
258 # when @FirmwareDevice is @memory.
259 #
260 # @filename: Identifies the firmware executable. The firmware executable
261 # may be shared by multiple virtual machine definitions. The
262 # corresponding QEMU command line option is "-bios
263 # @filename".
264 #
265 # Since: 3.0
266 ##
267 { 'struct' : 'FirmwareMappingMemory',
268 'data' : { 'filename' : 'str' } }
270 ##
271 # @FirmwareMapping:
272 #
273 # Provides a discriminated structure for firmware to describe its
274 # loading / mapping properties.
275 #
276 # @device: Selects the device type that the firmware must be mapped
277 # into.
278 #
279 # Since: 3.0
280 ##
281 { 'union' : 'FirmwareMapping',
282 'base' : { 'device' : 'FirmwareDevice' },
283 'discriminator' : 'device',
284 'data' : { 'flash' : 'FirmwareMappingFlash',
285 'kernel' : 'FirmwareMappingKernel',
286 'memory' : 'FirmwareMappingMemory' } }
288 ##
289 # @Firmware:
290 #
291 # Describes a firmware (or a firmware use case) to management software.
292 #
293 # It is possible for multiple @Firmware elements to match the search
294 # criteria of management software. Applications thus need rules to pick
295 # one of the many matches, and users need the ability to override distro
296 # defaults.
297 #
298 # It is recommended to create firmware JSON files (each containing a
299 # single @Firmware root element) with a double-digit prefix, for example
300 # "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
301 # predictable order. The firmware JSON files should be searched for in
302 # three directories:
303 #
304 # - /usr/share/qemu/firmware -- populated by distro-provided firmware
305 # packages (XDG_DATA_DIRS covers
306 # /usr/share by default),
307 #
308 # - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
309 #
310 # - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
311 # additions (XDG_CONFIG_HOME
312 # defaults to $HOME/.config).
313 #
314 # Top-down, the list of directories goes from general to specific.
315 #
316 # Management software should build a list of files from all three
317 # locations, then sort the list by filename (i.e., last pathname
318 # component). Management software should choose the first JSON file on
319 # the sorted list that matches the search criteria. If a more specific
320 # directory has a file with same name as a less specific directory, then
321 # the file in the more specific directory takes effect. If the more
322 # specific file is zero length, it hides the less specific one.
323 #
324 # For example, if a distro ships
325 #
326 # - /usr/share/qemu/firmware/50-ovmf.json
327 #
328 # - /usr/share/qemu/firmware/50-seabios-256k.json
329 #
330 # then the sysadmin can prevent the default OVMF being used at all with
331 #
332 # $ touch /etc/qemu/firmware/50-ovmf.json
333 #
334 # The sysadmin can replace/alter the distro default OVMF with
335 #
336 # $ vim /etc/qemu/firmware/50-ovmf.json
337 #
338 # or they can provide a parallel OVMF with higher priority
339 #
340 # $ vim /etc/qemu/firmware/10-ovmf.json
341 #
342 # or they can provide a parallel OVMF with lower priority
343 #
344 # $ vim /etc/qemu/firmware/99-ovmf.json
345 #
346 # @description: Provides a human-readable description of the firmware.
347 # Management software may or may not display @description.
348 #
349 # @interface-types: Lists the types of interfaces that the firmware can
350 # expose to the guest OS. This is a non-empty, ordered
351 # list; entries near the beginning of @interface-types
352 # are considered more native to the firmware, and/or
353 # to have a higher quality implementation in the
354 # firmware, than entries near the end of
355 # @interface-types.
356 #
357 # @mapping: Describes the loading / mapping properties of the firmware.
358 #
359 # @targets: Collects the target architectures (QEMU system emulators)
360 # and their machine types that may execute the firmware.
361 #
362 # @features: Lists the features that the firmware supports, and the
363 # platform requirements it presents.
364 #
365 # @tags: A list of auxiliary strings associated with the firmware for
366 # which @description is not appropriate, due to the latter's
367 # possible exposure to the end-user. @tags serves development and
368 # debugging purposes only, and management software shall
369 # explicitly ignore it.
370 #
371 # Since: 3.0
372 #
373 # Examples:
374 #
375 # {
376 # "description": "SeaBIOS",
377 # "interface-types": [
378 # "bios"
379 # ],
380 # "mapping": {
381 # "device": "memory",
382 # "filename": "/usr/share/seabios/bios-256k.bin"
383 # },
384 # "targets": [
385 # {
386 # "architecture": "i386",
387 # "machines": [
388 # "pc-i440fx-*",
389 # "pc-q35-*"
390 # ]
391 # },
392 # {
393 # "architecture": "x86_64",
394 # "machines": [
395 # "pc-i440fx-*",
396 # "pc-q35-*"
397 # ]
398 # }
399 # ],
400 # "features": [
401 # "acpi-s3",
402 # "acpi-s4"
403 # ],
404 # "tags": [
405 # "CONFIG_BOOTSPLASH=n",
406 # "CONFIG_ROM_SIZE=256",
407 # "CONFIG_USE_SMM=n"
408 # ]
409 # }
410 #
411 # {
412 # "description": "OVMF with SB+SMM, empty varstore",
413 # "interface-types": [
414 # "uefi"
415 # ],
416 # "mapping": {
417 # "device": "flash",
418 # "executable": {
419 # "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
420 # "format": "raw"
421 # },
422 # "nvram-template": {
423 # "filename": "/usr/share/OVMF/OVMF_VARS.fd",
424 # "format": "raw"
425 # }
426 # },
427 # "targets": [
428 # {
429 # "architecture": "x86_64",
430 # "machines": [
431 # "pc-q35-*"
432 # ]
433 # }
434 # ],
435 # "features": [
436 # "acpi-s3",
437 # "amd-sev",
438 # "requires-smm",
439 # "secure-boot",
440 # "verbose-dynamic"
441 # ],
442 # "tags": [
443 # "-a IA32",
444 # "-a X64",
445 # "-p OvmfPkg/OvmfPkgIa32X64.dsc",
446 # "-t GCC48",
447 # "-b DEBUG",
448 # "-D SMM_REQUIRE",
449 # "-D SECURE_BOOT_ENABLE",
450 # "-D FD_SIZE_4MB"
451 # ]
452 # }
453 #
454 # {
455 # "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled",
456 # "interface-types": [
457 # "uefi"
458 # ],
459 # "mapping": {
460 # "device": "flash",
461 # "executable": {
462 # "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
463 # "format": "raw"
464 # },
465 # "nvram-template": {
466 # "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd",
467 # "format": "raw"
468 # }
469 # },
470 # "targets": [
471 # {
472 # "architecture": "x86_64",
473 # "machines": [
474 # "pc-q35-*"
475 # ]
476 # }
477 # ],
478 # "features": [
479 # "acpi-s3",
480 # "amd-sev",
481 # "enrolled-keys",
482 # "requires-smm",
483 # "secure-boot",
484 # "verbose-dynamic"
485 # ],
486 # "tags": [
487 # "-a IA32",
488 # "-a X64",
489 # "-p OvmfPkg/OvmfPkgIa32X64.dsc",
490 # "-t GCC48",
491 # "-b DEBUG",
492 # "-D SMM_REQUIRE",
493 # "-D SECURE_BOOT_ENABLE",
494 # "-D FD_SIZE_4MB"
495 # ]
496 # }
497 #
498 # {
499 # "description": "UEFI firmware for ARM64 virtual machines",
500 # "interface-types": [
501 # "uefi"
502 # ],
503 # "mapping": {
504 # "device": "flash",
505 # "executable": {
506 # "filename": "/usr/share/AAVMF/AAVMF_CODE.fd",
507 # "format": "raw"
508 # },
509 # "nvram-template": {
510 # "filename": "/usr/share/AAVMF/AAVMF_VARS.fd",
511 # "format": "raw"
512 # }
513 # },
514 # "targets": [
515 # {
516 # "architecture": "aarch64",
517 # "machines": [
518 # "virt-*"
519 # ]
520 # }
521 # ],
522 # "features": [
523 #
524 # ],
525 # "tags": [
526 # "-a AARCH64",
527 # "-p ArmVirtPkg/ArmVirtQemu.dsc",
528 # "-t GCC48",
529 # "-b DEBUG",
530 # "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
531 # ]
532 # }
533 ##
534 { 'struct' : 'Firmware',
535 'data' : { 'description' : 'str',
536 'interface-types' : [ 'FirmwareOSInterface' ],
537 'mapping' : 'FirmwareMapping',
538 'targets' : [ 'FirmwareTarget' ],
539 'features' : [ 'FirmwareFeature' ],
540 'tags' : [ 'str' ] } }