aboutsummaryrefslogtreecommitdiff
path: root/docs/interop/firmware.json
blob: 9d94ccafa9e0b410d058449b3a2ddf80cb0e34c3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
# -*- Mode: Python -*-
# vim: filetype=python
#
# Copyright (C) 2018 Red Hat, Inc.
#
# Authors:
#  Daniel P. Berrange <berrange@redhat.com>
#  Laszlo Ersek <lersek@redhat.com>
#
# This work is licensed under the terms of the GNU GPL, version 2 or
# later. See the COPYING file in the top-level directory.

##
# = Firmware
##

{ 'include' : 'machine.json' }
{ 'include' : 'block-core.json' }

##
# @FirmwareOSInterface:
#
# Lists the firmware-OS interface types provided by various firmware
# that is commonly used with QEMU virtual machines.
#
# @bios: Traditional x86 BIOS interface. For example, firmware built
#        from the SeaBIOS project usually provides this interface.
#
# @openfirmware: The interface is defined by the (historical) IEEE
#                1275-1994 standard. Examples for firmware projects that
#                provide this interface are: OpenBIOS and SLOF.
#
# @uboot: Firmware interface defined by the U-Boot project.
#
# @uefi: Firmware interface defined by the UEFI specification. For
#        example, firmware built from the edk2 (EFI Development Kit II)
#        project usually provides this interface.
#
# Since: 3.0
##
{ 'enum' : 'FirmwareOSInterface',
  'data' : [ 'bios', 'openfirmware', 'uboot', 'uefi' ] }

##
# @FirmwareDevice:
#
# Defines the device types that firmware can be mapped into.
#
# @flash: The firmware executable and its accompanying NVRAM file are to
#         be mapped into a pflash chip each.
#
# @kernel: The firmware is to be loaded like a Linux kernel. This is
#          similar to @memory but may imply additional processing that
#          is specific to the target architecture and machine type.
#
# @memory: The firmware is to be mapped into memory.
#
# Since: 3.0
##
{ 'enum' : 'FirmwareDevice',
  'data' : [ 'flash', 'kernel', 'memory' ] }

##
# @FirmwareTarget:
#
# Defines the machine types that firmware may execute on.
#
# @architecture: Determines the emulation target (the QEMU system
#                emulator) that can execute the firmware.
#
# @machines: Lists the machine types (known by the emulator that is
#            specified through @architecture) that can execute the
#            firmware. Elements of @machines are supposed to be concrete
#            machine types, not aliases. Glob patterns are understood,
#            which is especially useful for versioned machine types.
#            (For example, the glob pattern "pc-i440fx-*" matches
#            "pc-i440fx-2.12".) On the QEMU command line, "-machine
#            type=..." specifies the requested machine type (but that
#            option does not accept glob patterns).
#
# Since: 3.0
##
{ 'struct' : 'FirmwareTarget',
  'data'   : { 'architecture' : 'SysEmuTarget',
               'machines'     : [ 'str' ] } }

##
# @FirmwareFeature:
#
# Defines the features that firmware may support, and the platform
# requirements that firmware may present.
#
# @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as defined
#           in the ACPI specification. On the "pc-i440fx-*" machine
#           types of the @i386 and @x86_64 emulation targets, S3 can be
#           enabled with "-global PIIX4_PM.disable_s3=0" and disabled
#           with "-global PIIX4_PM.disable_s3=1". On the "pc-q35-*"
#           machine types of the @i386 and @x86_64 emulation targets, S3
#           can be enabled with "-global ICH9-LPC.disable_s3=0" and
#           disabled with "-global ICH9-LPC.disable_s3=1".
#
# @acpi-s4: The firmware supports S4 hibernation (suspend to disk), as
#           defined in the ACPI specification. On the "pc-i440fx-*"
#           machine types of the @i386 and @x86_64 emulation targets, S4
#           can be enabled with "-global PIIX4_PM.disable_s4=0" and
#           disabled with "-global PIIX4_PM.disable_s4=1". On the
#           "pc-q35-*" machine types of the @i386 and @x86_64 emulation
#           targets, S4 can be enabled with "-global
#           ICH9-LPC.disable_s4=0" and disabled with "-global
#           ICH9-LPC.disable_s4=1".
#
# @amd-sev: The firmware supports running under AMD Secure Encrypted
#           Virtualization, as specified in the AMD64 Architecture
#           Programmer's Manual. QEMU command line options related to
#           this feature are documented in
#           "docs/amd-memory-encryption.txt".
#
# @enrolled-keys: The variable store (NVRAM) template associated with
#                 the firmware binary has the UEFI Secure Boot
#                 operational mode turned on, with certificates
#                 enrolled.
#
# @requires-smm: The firmware requires the platform to emulate SMM
#                (System Management Mode), as defined in the AMD64
#                Architecture Programmer's Manual, and in the Intel(R)64
#                and IA-32 Architectures Software Developer's Manual. On
#                the "pc-q35-*" machine types of the @i386 and @x86_64
#                emulation targets, SMM emulation can be enabled with
#                "-machine smm=on". (On the "pc-q35-*" machine types of
#                the @i386 emulation target, @requires-smm presents
#                further CPU requirements; one combination known to work
#                is "-cpu coreduo,nx=off".) If the firmware is marked as
#                both @secure-boot and @requires-smm, then write
#                accesses to the pflash chip (NVRAM) that holds the UEFI
#                variable store must be restricted to code that executes
#                in SMM, using the additional option "-global
#                driver=cfi.pflash01,property=secure,value=on".
#                Furthermore, a large guest-physical address space
#                (comprising guest RAM, memory hotplug range, and 64-bit
#                PCI MMIO aperture), and/or a high VCPU count, may
#                present high SMRAM requirements from the firmware. On
#                the "pc-q35-*" machine types of the @i386 and @x86_64
#                emulation targets, the SMRAM size may be increased
#                above the default 16MB with the "-global
#                mch.extended-tseg-mbytes=uint16" option. As a rule of
#                thumb, the default 16MB size suffices for 1TB of
#                guest-phys address space and a few tens of VCPUs; for
#                every further TB of guest-phys address space, add 8MB
#                of SMRAM. 48MB should suffice for 4TB of guest-phys
#                address space and 2-3 hundred VCPUs.
#
# @secure-boot: The firmware implements the software interfaces for UEFI
#               Secure Boot, as defined in the UEFI specification. Note
#               that without @requires-smm, guest code running with
#               kernel privileges can undermine the security of Secure
#               Boot.
#
# @verbose-dynamic: When firmware log capture is enabled, the firmware
#                   logs a large amount of debug messages, which may
#                   impact boot performance. With log capture disabled,
#                   there is no boot performance impact. On the
#                   "pc-i440fx-*" and "pc-q35-*" machine types of the
#                   @i386 and @x86_64 emulation targets, firmware log
#                   capture can be enabled with the QEMU command line
#                   options "-chardev file,id=fwdebug,path=LOGFILEPATH
#                   -device isa-debugcon,iobase=0x402,chardev=fwdebug".
#                   @verbose-dynamic is mutually exclusive with
#                   @verbose-static.
#
# @verbose-static: The firmware unconditionally produces a large amount
#                  of debug messages, which may impact boot performance.
#                  This feature may typically be carried by certain UEFI
#                  firmware for the "virt-*" machine types of the @arm
#                  and @aarch64 emulation targets, where the debug
#                  messages are written to the first (always present)
#                  PL011 UART. @verbose-static is mutually exclusive
#                  with @verbose-dynamic.
#
# Since: 3.0
##
{ 'enum' : 'FirmwareFeature',
  'data' : [ 'acpi-s3', 'acpi-s4', 'amd-sev', 'enrolled-keys',
             'requires-smm', 'secure-boot', 'verbose-dynamic',
             'verbose-static' ] }

##
# @FirmwareFlashFile:
#
# Defines common properties that are necessary for loading a firmware
# file into a pflash chip. The corresponding QEMU command line option is
# "-drive file=@filename,format=@format". Note however that the
# option-argument shown here is incomplete; it is completed under
# @FirmwareMappingFlash.
#
# @filename: Specifies the filename on the host filesystem where the
#            firmware file can be found.
#
# @format: Specifies the block format of the file pointed-to by
#          @filename, such as @raw or @qcow2.
#
# Since: 3.0
##
{ 'struct' : 'FirmwareFlashFile',
  'data'   : { 'filename' : 'str',
               'format'   : 'BlockdevDriver' } }

##
# @FirmwareMappingFlash:
#
# Describes loading and mapping properties for the firmware executable
# and its accompanying NVRAM file, when @FirmwareDevice is @flash.
#
# @executable: Identifies the firmware executable. The firmware
#              executable may be shared by multiple virtual machine
#              definitions. The preferred corresponding QEMU command
#              line options are
#                  -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executable.@format
#                  -machine pflash0=pflash0
#              or equivalent -blockdev instead of -drive.
#              With QEMU versions older than 4.0, you have to use
#                  -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executable.@format
#
# @nvram-template: Identifies the NVRAM template compatible with
#                  @executable. Management software instantiates an
#                  individual copy -- a specific NVRAM file -- from
#                  @nvram-template.@filename for each new virtual
#                  machine definition created. @nvram-template.@filename
#                  itself is never mapped into virtual machines, only
#                  individual copies of it are. An NVRAM file is
#                  typically used for persistently storing the
#                  non-volatile UEFI variables of a virtual machine
#                  definition. The preferred corresponding QEMU
#                  command line options are
#                      -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
#                      -machine pflash1=pflash1
#                  or equivalent -blockdev instead of -drive.
#                  With QEMU versions older than 4.0, you have to use
#                      -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,format=@nvram-template.@format
#
# Since: 3.0
##
{ 'struct' : 'FirmwareMappingFlash',
  'data'   : { 'executable'     : 'FirmwareFlashFile',
               'nvram-template' : 'FirmwareFlashFile' } }

##
# @FirmwareMappingKernel:
#
# Describes loading and mapping properties for the firmware executable,
# when @FirmwareDevice is @kernel.
#
# @filename: Identifies the firmware executable. The firmware executable
#            may be shared by multiple virtual machine definitions. The
#            corresponding QEMU command line option is "-kernel
#            @filename".
#
# Since: 3.0
##
{ 'struct' : 'FirmwareMappingKernel',
  'data'   : { 'filename' : 'str' } }

##
# @FirmwareMappingMemory:
#
# Describes loading and mapping properties for the firmware executable,
# when @FirmwareDevice is @memory.
#
# @filename: Identifies the firmware executable. The firmware executable
#            may be shared by multiple virtual machine definitions. The
#            corresponding QEMU command line option is "-bios
#            @filename".
#
# Since: 3.0
##
{ 'struct' : 'FirmwareMappingMemory',
  'data'   : { 'filename' : 'str' } }

##
# @FirmwareMapping:
#
# Provides a discriminated structure for firmware to describe its
# loading / mapping properties.
#
# @device: Selects the device type that the firmware must be mapped
#          into.
#
# Since: 3.0
##
{ 'union'         : 'FirmwareMapping',
  'base'          : { 'device' : 'FirmwareDevice' },
  'discriminator' : 'device',
  'data'          : { 'flash'  : 'FirmwareMappingFlash',
                      'kernel' : 'FirmwareMappingKernel',
                      'memory' : 'FirmwareMappingMemory' } }

##
# @Firmware:
#
# Describes a firmware (or a firmware use case) to management software.
#
# It is possible for multiple @Firmware elements to match the search
# criteria of management software. Applications thus need rules to pick
# one of the many matches, and users need the ability to override distro
# defaults.
#
# It is recommended to create firmware JSON files (each containing a
# single @Firmware root element) with a double-digit prefix, for example
# "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
# predictable order. The firmware JSON files should be searched for in
# three directories:
#
#   - /usr/share/qemu/firmware -- populated by distro-provided firmware
#                                 packages (XDG_DATA_DIRS covers
#                                 /usr/share by default),
#
#   - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
#
#   - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
#                                       additions (XDG_CONFIG_HOME
#                                       defaults to $HOME/.config).
#
# Top-down, the list of directories goes from general to specific.
#
# Management software should build a list of files from all three
# locations, then sort the list by filename (i.e., last pathname
# component). Management software should choose the first JSON file on
# the sorted list that matches the search criteria. If a more specific
# directory has a file with same name as a less specific directory, then
# the file in the more specific directory takes effect. If the more
# specific file is zero length, it hides the less specific one.
#
# For example, if a distro ships
#
#   - /usr/share/qemu/firmware/50-ovmf.json
#
#   - /usr/share/qemu/firmware/50-seabios-256k.json
#
# then the sysadmin can prevent the default OVMF being used at all with
#
#   $ touch /etc/qemu/firmware/50-ovmf.json
#
# The sysadmin can replace/alter the distro default OVMF with
#
#   $ vim /etc/qemu/firmware/50-ovmf.json
#
# or they can provide a parallel OVMF with higher priority
#
#   $ vim /etc/qemu/firmware/10-ovmf.json
#
# or they can provide a parallel OVMF with lower priority
#
#   $ vim /etc/qemu/firmware/99-ovmf.json
#
# @description: Provides a human-readable description of the firmware.
#               Management software may or may not display @description.
#
# @interface-types: Lists the types of interfaces that the firmware can
#                   expose to the guest OS. This is a non-empty, ordered
#                   list; entries near the beginning of @interface-types
#                   are considered more native to the firmware, and/or
#                   to have a higher quality implementation in the
#                   firmware, than entries near the end of
#                   @interface-types.
#
# @mapping: Describes the loading / mapping properties of the firmware.
#
# @targets: Collects the target architectures (QEMU system emulators)
#           and their machine types that may execute the firmware.
#
# @features: Lists the features that the firmware supports, and the
#            platform requirements it presents.
#
# @tags: A list of auxiliary strings associated with the firmware for
#        which @description is not appropriate, due to the latter's
#        possible exposure to the end-user. @tags serves development and
#        debugging purposes only, and management software shall
#        explicitly ignore it.
#
# Since: 3.0
#
# Examples:
#
# {
#     "description": "SeaBIOS",
#     "interface-types": [
#         "bios"
#     ],
#     "mapping": {
#         "device": "memory",
#         "filename": "/usr/share/seabios/bios-256k.bin"
#     },
#     "targets": [
#         {
#             "architecture": "i386",
#             "machines": [
#                 "pc-i440fx-*",
#                 "pc-q35-*"
#             ]
#         },
#         {
#             "architecture": "x86_64",
#             "machines": [
#                 "pc-i440fx-*",
#                 "pc-q35-*"
#             ]
#         }
#     ],
#     "features": [
#         "acpi-s3",
#         "acpi-s4"
#     ],
#     "tags": [
#         "CONFIG_BOOTSPLASH=n",
#         "CONFIG_ROM_SIZE=256",
#         "CONFIG_USE_SMM=n"
#     ]
# }
#
# {
#     "description": "OVMF with SB+SMM, empty varstore",
#     "interface-types": [
#         "uefi"
#     ],
#     "mapping": {
#         "device": "flash",
#         "executable": {
#             "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
#             "format": "raw"
#         },
#         "nvram-template": {
#             "filename": "/usr/share/OVMF/OVMF_VARS.fd",
#             "format": "raw"
#         }
#     },
#     "targets": [
#         {
#             "architecture": "x86_64",
#             "machines": [
#                 "pc-q35-*"
#             ]
#         }
#     ],
#     "features": [
#         "acpi-s3",
#         "amd-sev",
#         "requires-smm",
#         "secure-boot",
#         "verbose-dynamic"
#     ],
#     "tags": [
#         "-a IA32",
#         "-a X64",
#         "-p OvmfPkg/OvmfPkgIa32X64.dsc",
#         "-t GCC48",
#         "-b DEBUG",
#         "-D SMM_REQUIRE",
#         "-D SECURE_BOOT_ENABLE",
#         "-D FD_SIZE_4MB"
#     ]
# }
#
# {
#     "description": "OVMF with SB+SMM, SB enabled, MS certs enrolled",
#     "interface-types": [
#         "uefi"
#     ],
#     "mapping": {
#         "device": "flash",
#         "executable": {
#             "filename": "/usr/share/OVMF/OVMF_CODE.secboot.fd",
#             "format": "raw"
#         },
#         "nvram-template": {
#             "filename": "/usr/share/OVMF/OVMF_VARS.secboot.fd",
#             "format": "raw"
#         }
#     },
#     "targets": [
#         {
#             "architecture": "x86_64",
#             "machines": [
#                 "pc-q35-*"
#             ]
#         }
#     ],
#     "features": [
#         "acpi-s3",
#         "amd-sev",
#         "enrolled-keys",
#         "requires-smm",
#         "secure-boot",
#         "verbose-dynamic"
#     ],
#     "tags": [
#         "-a IA32",
#         "-a X64",
#         "-p OvmfPkg/OvmfPkgIa32X64.dsc",
#         "-t GCC48",
#         "-b DEBUG",
#         "-D SMM_REQUIRE",
#         "-D SECURE_BOOT_ENABLE",
#         "-D FD_SIZE_4MB"
#     ]
# }
#
# {
#     "description": "UEFI firmware for ARM64 virtual machines",
#     "interface-types": [
#         "uefi"
#     ],
#     "mapping": {
#         "device": "flash",
#         "executable": {
#             "filename": "/usr/share/AAVMF/AAVMF_CODE.fd",
#             "format": "raw"
#         },
#         "nvram-template": {
#             "filename": "/usr/share/AAVMF/AAVMF_VARS.fd",
#             "format": "raw"
#         }
#     },
#     "targets": [
#         {
#             "architecture": "aarch64",
#             "machines": [
#                 "virt-*"
#             ]
#         }
#     ],
#     "features": [
#
#     ],
#     "tags": [
#         "-a AARCH64",
#         "-p ArmVirtPkg/ArmVirtQemu.dsc",
#         "-t GCC48",
#         "-b DEBUG",
#         "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
#     ]
# }
##
{ 'struct' : 'Firmware',
  'data'   : { 'description'     : 'str',
               'interface-types' : [ 'FirmwareOSInterface' ],
               'mapping'         : 'FirmwareMapping',
               'targets'         : [ 'FirmwareTarget' ],
               'features'        : [ 'FirmwareFeature' ],
               'tags'            : [ 'str' ] } }