| blob | 240f565397ae0e754e85976f2d4b5e3873ae8211 |
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' : 'machine.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 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' ] }
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' ] }
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' ] } }
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' ] }
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' } }
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' } }
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' } }
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' } }
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' } }
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' ] } }