| blob | ff8c2ce5f2217a0bf33c8d44359279531969ac49 |
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 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
222 #
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
239 #
240 # Since: 3.0
241 ##
242 { 'struct' : 'FirmwareMappingFlash',
243 'data' : { 'executable' : 'FirmwareFlashFile',
244 'nvram-template' : 'FirmwareFlashFile' } }
246 ##
247 # @FirmwareMappingKernel:
248 #
249 # Describes loading and mapping properties for the firmware executable,
250 # when @FirmwareDevice is @kernel.
251 #
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".
256 #
257 # Since: 3.0
258 ##
259 { 'struct' : 'FirmwareMappingKernel',
260 'data' : { 'filename' : 'str' } }
262 ##
263 # @FirmwareMappingMemory:
264 #
265 # Describes loading and mapping properties for the firmware executable,
266 # when @FirmwareDevice is @memory.
267 #
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".
272 #
273 # Since: 3.0
274 ##
275 { 'struct' : 'FirmwareMappingMemory',
276 'data' : { 'filename' : 'str' } }
278 ##
279 # @FirmwareMapping:
280 #
281 # Provides a discriminated structure for firmware to describe its
282 # loading / mapping properties.
283 #
284 # @device: Selects the device type that the firmware must be mapped
285 # into.
286 #
287 # Since: 3.0
288 ##
289 { 'union' : 'FirmwareMapping',
290 'base' : { 'device' : 'FirmwareDevice' },
291 'discriminator' : 'device',
292 'data' : { 'flash' : 'FirmwareMappingFlash',
293 'kernel' : 'FirmwareMappingKernel',
294 'memory' : 'FirmwareMappingMemory' } }
296 ##
297 # @Firmware:
298 #
299 # Describes a firmware (or a firmware use case) to management software.
300 #
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.
305 #
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:
311 #
312 # - /usr/share/qemu/firmware -- populated by distro-provided firmware
313 # packages (XDG_DATA_DIRS covers
314 # /usr/share by default),
315 #
316 # - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
317 #
318 # - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
319 # additions (XDG_CONFIG_HOME
320 # defaults to $HOME/.config).
321 #
322 # Top-down, the list of directories goes from general to specific.
323 #
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.
331 #
332 # For example, if a distro ships
333 #
334 # - /usr/share/qemu/firmware/50-ovmf.json
335 #
336 # - /usr/share/qemu/firmware/50-seabios-256k.json
337 #
338 # then the sysadmin can prevent the default OVMF being used at all with
339 #
340 # $ touch /etc/qemu/firmware/50-ovmf.json
341 #
342 # The sysadmin can replace/alter the distro default OVMF with
343 #
344 # $ vim /etc/qemu/firmware/50-ovmf.json
345 #
346 # or they can provide a parallel OVMF with higher priority
347 #
348 # $ vim /etc/qemu/firmware/10-ovmf.json
349 #
350 # or they can provide a parallel OVMF with lower priority
351 #
352 # $ vim /etc/qemu/firmware/99-ovmf.json
353 #
354 # @description: Provides a human-readable description of the firmware.
355 # Management software may or may not display @description.
356 #
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.
364 #
365 # @mapping: Describes the loading / mapping properties of the firmware.
366 #
367 # @targets: Collects the target architectures (QEMU system emulators)
368 # and their machine types that may execute the firmware.
369 #
370 # @features: Lists the features that the firmware supports, and the
371 # platform requirements it presents.
372 #
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.
378 #
379 # Since: 3.0
380 #
381 # Examples:
382 #
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 # }
418 #
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 # }
461 #
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 # }
505 #
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": [
531 #
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 # }
541 ##
542 { 'struct' : 'Firmware',
543 'data' : { 'description' : 'str',
544 'interface-types' : [ 'FirmwareOSInterface' ],
545 'mapping' : 'FirmwareMapping',
546 'targets' : [ 'FirmwareTarget' ],
547 'features' : [ 'FirmwareFeature' ],
548 'tags' : [ 'str' ] } }