4
# Copyright (C) 2018 Red Hat, Inc.
7
# Daniel P. Berrange <berrange@redhat.com>
8
# Laszlo Ersek <lersek@redhat.com>
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.
18
'member-name-exceptions': [
19
'FirmwareArchitecture' # x86_64
23
# @FirmwareOSInterface:
25
# Lists the firmware-OS interface types provided by various firmware
26
# that is commonly used with QEMU virtual machines.
28
# @bios: Traditional x86 BIOS interface. For example, firmware built
29
# from the SeaBIOS project usually provides this interface.
31
# @openfirmware: The interface is defined by the (historical) IEEE
32
# 1275-1994 standard. Examples for firmware projects that
33
# provide this interface are: OpenBIOS and SLOF.
35
# @uboot: Firmware interface defined by the U-Boot project.
37
# @uefi: Firmware interface defined by the UEFI specification. For
38
# example, firmware built from the edk2 (EFI Development Kit II)
39
# project usually provides this interface.
43
{ 'enum' : 'FirmwareOSInterface',44
'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] }
49
# Defines the device types that firmware can be mapped into.
51
# @flash: The firmware executable and its accompanying NVRAM file are to
52
# be mapped into a pflash chip each.
54
# @kernel: The firmware is to be loaded like a Linux kernel. This is
55
# similar to @memory but may imply additional processing that
56
# is specific to the target architecture and machine type.
58
# @memory: The firmware is to be mapped into memory.
62
{ 'enum' : 'FirmwareDevice',63
'data' : [ 'flash', 'kernel', 'memory' ] }
66
# @FirmwareArchitecture:
68
# Enumeration of architectures for which Qemu uses additional
71
# @aarch64: 64-bit Arm.
77
# @loongarch64: 64-bit LoongArch. (since: 7.1)
83
{ 'enum' : 'FirmwareArchitecture',84
'data' : [ 'aarch64', 'arm', 'i386', 'loongarch64', 'x86_64' ] }
89
# Defines the machine types that firmware may execute on.
91
# @architecture: Determines the emulation target (the QEMU system
92
# emulator) that can execute the firmware.
94
# @machines: Lists the machine types (known by the emulator that is
95
# specified through @architecture) that can execute the
96
# firmware. Elements of @machines are supposed to be concrete
97
# machine types, not aliases. Glob patterns are understood,
98
# which is especially useful for versioned machine types.
99
# (For example, the glob pattern "pc-i440fx-*" matches
100
# "pc-i440fx-2.12".) On the QEMU command line, "-machine
101
# type=..." specifies the requested machine type (but that
102
# option does not accept glob patterns).
106
{ 'struct' : 'FirmwareTarget',107
'data' : { 'architecture' : 'FirmwareArchitecture',108
'machines' : [ 'str' ] } }
113
# Defines the features that firmware may support, and the platform
114
# requirements that firmware may present.
116
# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined
117
# in the ACPI specification. On the "pc-i440fx-*" machine
118
# types of the @i386 and @x86_64 emulation targets, S3 can be
119
# enabled with "-global PIIX4_PM.disable_s3=0" and disabled
120
# with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*"
121
# machine types of the @i386 and @x86_64 emulation targets, S3
122
# can be enabled with "-global ICH9-LPC.disable_s3=0" and
123
# disabled with "-global ICH9-LPC.disable_s3=1".
125
# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as
126
# defined in the ACPI specification. On the "pc-i440fx-*"
127
# machine types of the @i386 and @x86_64 emulation targets, S4
128
# can be enabled with "-global PIIX4_PM.disable_s4=0" and
129
# disabled with "-global PIIX4_PM.disable_s4=1". On the
130
# "pc-q35-*" machine types of the @i386 and @x86_64 emulation
131
# targets, S4 can be enabled with "-global
132
# ICH9-LPC.disable_s4=0" and disabled with "-global
133
# ICH9-LPC.disable_s4=1".
135
# @amd-sev: The firmware supports running under AMD Secure Encrypted
136
# Virtualization, as specified in the AMD64 Architecture
137
# Programmer's Manual. QEMU command line options related to
138
# this feature are documented in
139
# "docs/system/i386/amd-memory-encryption.rst".
141
# @amd-sev-es: The firmware supports running under AMD Secure Encrypted
142
# Virtualization - Encrypted State, as specified in the AMD64
143
# Architecture Programmer's Manual. QEMU command line options
144
# related to this feature are documented in
145
# "docs/system/i386/amd-memory-encryption.rst".
147
# @amd-sev-snp: The firmware supports running under AMD Secure Encrypted
148
# Virtualization - Secure Nested Paging, as specified in the
149
# AMD64 Architecture Programmer's Manual. QEMU command line
150
# options related to this feature are documented in
151
# "docs/system/i386/amd-memory-encryption.rst".
153
# @intel-tdx: The firmware supports running under Intel Trust Domain
156
# @enrolled-keys: The variable store (NVRAM) template associated with
157
# the firmware binary has the UEFI Secure Boot
158
# operational mode turned on, with certificates
161
# @requires-smm: The firmware requires the platform to emulate SMM
162
# (System Management Mode), as defined in the AMD64
163
# Architecture Programmer's Manual, and in the Intel(R)64
164
# and IA-32 Architectures Software Developer's Manual. On
165
# the "pc-q35-*" machine types of the @i386 and @x86_64
166
# emulation targets, SMM emulation can be enabled with
167
# "-machine smm=on". (On the "pc-q35-*" machine types of
168
# the @i386 emulation target, @requires-smm presents
169
# further CPU requirements; one combination known to work
170
# is "-cpu coreduo,nx=off".) If the firmware is marked as
171
# both @secure-boot and @requires-smm, then write
172
# accesses to the pflash chip (NVRAM) that holds the UEFI
173
# variable store must be restricted to code that executes
174
# in SMM, using the additional option "-global
175
# driver=cfi.pflash01,property=secure,value=on".
176
# Furthermore, a large guest-physical address space
177
# (comprising guest RAM, memory hotplug range, and 64-bit
178
# PCI MMIO aperture), and/or a high VCPU count, may
179
# present high SMRAM requirements from the firmware. On
180
# the "pc-q35-*" machine types of the @i386 and @x86_64
181
# emulation targets, the SMRAM size may be increased
182
# above the default 16MB with the "-global
183
# mch.extended-tseg-mbytes=uint16" option. As a rule of
184
# thumb, the default 16MB size suffices for 1TB of
185
# guest-phys address space and a few tens of VCPUs; for
186
# every further TB of guest-phys address space, add 8MB
187
# of SMRAM. 48MB should suffice for 4TB of guest-phys
188
# address space and 2-3 hundred VCPUs.
190
# @secure-boot: The firmware implements the software interfaces for UEFI
191
# Secure Boot, as defined in the UEFI specification. Note
192
# that without @requires-smm, guest code running with
193
# kernel privileges can undermine the security of Secure
196
# @verbose-dynamic: When firmware log capture is enabled, the firmware
197
# logs a large amount of debug messages, which may
198
# impact boot performance. With log capture disabled,
199
# there is no boot performance impact. On the
200
# "pc-i440fx-*" and "pc-q35-*" machine types of the
201
# @i386 and @x86_64 emulation targets, firmware log
202
# capture can be enabled with the QEMU command line
203
# options "-chardev file,id=fwdebug,path=LOGFILEPATH
204
# -device isa-debugcon,iobase=0x402,chardev=fwdebug".
205
# @verbose-dynamic is mutually exclusive with
208
# @verbose-static: The firmware unconditionally produces a large amount
209
# of debug messages, which may impact boot performance.
210
# This feature may typically be carried by certain UEFI
211
# firmware for the "virt-*" machine types of the @arm
212
# and @aarch64 emulation targets, where the debug
213
# messages are written to the first (always present)
214
# PL011 UART. @verbose-static is mutually exclusive
215
# with @verbose-dynamic.
219
{ 'enum' : 'FirmwareFeature',220
'data' : [ 'acpi-s3', 'acpi-s4',
221
'amd-sev', 'amd-sev-es', 'amd-sev-snp',
223
'enrolled-keys', 'requires-smm', 'secure-boot',
224
'verbose-dynamic', 'verbose-static' ] }
229
# Formats that are supported for firmware images.
231
# @raw: Raw disk image format.
233
# @qcow2: The QCOW2 image format.
237
{ 'enum': 'FirmwareFormat',238
'data': [ 'raw', 'qcow2' ] }
243
# Defines common properties that are necessary for loading a firmware
244
# file into a pflash chip. The corresponding QEMU command line option is
245
# "-drive file=@filename,format=@format". Note however that the
246
# option-argument shown here is incomplete; it is completed under
247
# @FirmwareMappingFlash.
249
# @filename: Specifies the filename on the host filesystem where the
250
# firmware file can be found.
252
# @format: Specifies the block format of the file pointed-to by
253
# @filename, such as @raw or @qcow2.
257
{ 'struct' : 'FirmwareFlashFile',258
'data' : { 'filename' : 'str',259
'format' : 'FirmwareFormat' } }
265
# Describes how the firmware build handles code versus variable
268
# @split: the executable file contains code while the NVRAM
269
# template provides variable storage. The executable
270
# must be configured read-only and can be shared between
271
# multiple guests. The NVRAM template must be cloned
272
# for each new guest and configured read-write.
274
# @combined: the executable file contains both code and
275
# variable storage. The executable must be cloned
276
# for each new guest and configured read-write.
277
# No NVRAM template will be specified.
279
# @stateless: the executable file contains code and variable
280
# storage is not persisted. The executable must
281
# be configured read-only and can be shared
282
# between multiple guests. No NVRAM template
287
{ 'enum': 'FirmwareFlashMode',288
'data': [ 'split', 'combined', 'stateless' ] }
291
# @FirmwareMappingFlash:
293
# Describes loading and mapping properties for the firmware executable
294
# and its accompanying NVRAM file, when @FirmwareDevice is @flash.
296
# @mode: Describes how the firmware build handles code versus variable
297
# storage. If not present, it must be treated as if it was
298
# configured with value @split. Since: 7.0.0
300
# @executable: Identifies the firmware executable. The @mode
301
# indicates whether there will be an associated
302
# NVRAM template present. The preferred
303
# corresponding QEMU command line options are
304
# -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
305
# -machine pflash0=pflash0
306
# or equivalent -blockdev instead of -drive. When
307
# @mode is @combined the executable must be
308
# cloned before use and configured with readonly=off.
309
# With QEMU versions older than 4.0, you have to use
310
# -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
312
# @nvram-template: Identifies the NVRAM template compatible with
313
# @executable, when @mode is set to @split,
314
# otherwise it should not be present.
315
# Management software instantiates an
316
# individual copy -- a specific NVRAM file -- from
317
# @nvram-template.@filename for each new virtual
318
# machine definition created. @nvram-template.@filename
319
# itself is never mapped into virtual machines, only
320
# individual copies of it are. An NVRAM file is
321
# typically used for persistently storing the
322
# non-volatile UEFI variables of a virtual machine
323
# definition. The preferred corresponding QEMU
324
# command line options are
325
# -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
326
# -machine pflash1=pflash1
327
# or equivalent -blockdev instead of -drive.
328
# With QEMU versions older than 4.0, you have to use
329
# -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
333
{ 'struct' : 'FirmwareMappingFlash',334
'data' : { '*mode': 'FirmwareFlashMode',335
'executable' : 'FirmwareFlashFile',
336
'*nvram-template' : 'FirmwareFlashFile' } }
339
# @FirmwareMappingKernel:
341
# Describes loading and mapping properties for the firmware executable,
342
# when @FirmwareDevice is @kernel.
344
# @filename: Identifies the firmware executable. The firmware executable
345
# may be shared by multiple virtual machine definitions. The
346
# corresponding QEMU command line option is "-kernel
351
{ 'struct' : 'FirmwareMappingKernel',352
'data' : { 'filename' : 'str' } }355
# @FirmwareMappingMemory:
357
# Describes loading and mapping properties for the firmware executable,
358
# when @FirmwareDevice is @memory.
360
# @filename: Identifies the firmware executable. The firmware executable
361
# may be shared by multiple virtual machine definitions. The
362
# corresponding QEMU command line option is "-bios
367
{ 'struct' : 'FirmwareMappingMemory',368
'data' : { 'filename' : 'str' } }373
# Provides a discriminated structure for firmware to describe its
374
# loading / mapping properties.
376
# @device: Selects the device type that the firmware must be mapped
381
{ 'union' : 'FirmwareMapping',382
'base' : { 'device' : 'FirmwareDevice' },383
'discriminator' : 'device',
384
'data' : { 'flash' : 'FirmwareMappingFlash',385
'kernel' : 'FirmwareMappingKernel',
386
'memory' : 'FirmwareMappingMemory' } }
391
# Describes a firmware (or a firmware use case) to management software.
393
# It is possible for multiple @Firmware elements to match the search
394
# criteria of management software. Applications thus need rules to pick
395
# one of the many matches, and users need the ability to override distro
398
# It is recommended to create firmware JSON files (each containing a
399
# single @Firmware root element) with a double-digit prefix, for example
400
# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
401
# predictable order. The firmware JSON files should be searched for in
404
# - /usr/share/qemu/firmware -- populated by distro-provided firmware
405
# packages (XDG_DATA_DIRS covers
406
# /usr/share by default),
408
# - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
410
# - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
411
# additions (XDG_CONFIG_HOME
412
# defaults to $HOME/.config).
414
# Top-down, the list of directories goes from general to specific.
416
# Management software should build a list of files from all three
417
# locations, then sort the list by filename (i.e., last pathname
418
# component). Management software should choose the first JSON file on
419
# the sorted list that matches the search criteria. If a more specific
420
# directory has a file with same name as a less specific directory, then
421
# the file in the more specific directory takes effect. If the more
422
# specific file is zero length, it hides the less specific one.
424
# For example, if a distro ships
426
# - /usr/share/qemu/firmware/50-ovmf.json
428
# - /usr/share/qemu/firmware/50-seabios-256k.json
430
# then the sysadmin can prevent the default OVMF being used at all with
432
# $ touch /etc/qemu/firmware/50-ovmf.json
434
# The sysadmin can replace/alter the distro default OVMF with
436
# $ vim /etc/qemu/firmware/50-ovmf.json
438
# or they can provide a parallel OVMF with higher priority
440
# $ vim /etc/qemu/firmware/10-ovmf.json
442
# or they can provide a parallel OVMF with lower priority
444
# $ vim /etc/qemu/firmware/99-ovmf.json
446
# @description: Provides a human-readable description of the firmware.
447
# Management software may or may not display @description.
449
# @interface-types: Lists the types of interfaces that the firmware can
450
# expose to the guest OS. This is a non-empty, ordered
451
# list; entries near the beginning of @interface-types
452
# are considered more native to the firmware, and/or
453
# to have a higher quality implementation in the
454
# firmware, than entries near the end of
457
# @mapping: Describes the loading / mapping properties of the firmware.
459
# @targets: Collects the target architectures (QEMU system emulators)
460
# and their machine types that may execute the firmware.
462
# @features: Lists the features that the firmware supports, and the
463
# platform requirements it presents.
465
# @tags: A list of auxiliary strings associated with the firmware for
466
# which @description is not appropriate, due to the latter's
467
# possible exposure to the end-user. @tags serves development and
468
# debugging purposes only, and management software shall
469
# explicitly ignore it.
476
# "description": "SeaBIOS",
477
# "interface-types": [
482
# "filename": "/usr/share/seabios/bios-256k.bin"
486
# "architecture": "i386",
493
# "architecture": "x86_64",
505
# "CONFIG_BOOTSPLASH=n",
506
# "CONFIG_ROM_SIZE=256",
512
# "description": "OVMF with SB+SMM, empty varstore",
513
# "interface-types": [
519
# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
523
# "filename": "/usr/share/OVMF/OVMF_VARS.fd",
529
# "architecture": "x86_64",
545
# "-p OvmfPkg/OvmfPkgIa32X64.dsc",
549
# "-D SECURE_BOOT_ENABLE",
555
# "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled",
556
# "interface-types": [
562
# "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
566
# "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd",
572
# "architecture": "x86_64",
589
# "-p OvmfPkg/OvmfPkgIa32X64.dsc",
593
# "-D SECURE_BOOT_ENABLE",
599
# "description": "OVMF with SEV-ES support",
600
# "interface-types": [
606
# "filename": "/usr/share/OVMF/OVMF_CODE.fd",
610
# "filename": "/usr/share/OVMF/OVMF_VARS.fd",
616
# "architecture": "x86_64",
630
# "-p OvmfPkg/OvmfPkgX64.dsc",
638
# "description": "UEFI firmware for ARM64 virtual machines",
639
# "interface-types": [
645
# "filename": "/usr/share/AAVMF/AAVMF_CODE.fd",
649
# "filename": "/usr/share/AAVMF/AAVMF_VARS.fd",
655
# "architecture": "aarch64",
666
# "-p ArmVirtPkg/ArmVirtQemu.dsc",
669
# "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
673
{ 'struct' : 'Firmware',674
'data' : { 'description' : 'str',675
'interface-types' : [ 'FirmwareOSInterface' ],
676
'mapping' : 'FirmwareMapping',
677
'targets' : [ 'FirmwareTarget' ],
678
'features' : [ 'FirmwareFeature' ],
679
'tags' : [ 'str' ] } }