docs/interop/firmware.json

1 # -*- Mode: Python -*-
11 # later. See the COPYING file in the top-level directory.
18     'member-name-exceptions': [
25 # Lists the firmware-OS interface types provided by various firmware
32 #                1275-1994 standard. Examples for firmware projects that
35 # @uboot: Firmware interface defined by the U-Boot project.
54 # @kernel: The firmware is to be loaded like a Linux kernel. This is
71 # @aarch64: 64-bit Arm.
73 # @arm: 32-bit Arm.
75 # @i386: 32-bit x86.
77 # @loongarch64: 64-bit LoongArch. (since: 7.1)
79 # @x86_64: 64-bit x86.
84   'data' : [ 'aarch64', 'arm', 'i386', 'loongarch64', 'x86_64' ] }
99 #            (For example, the glob pattern "pc-i440fx-*" matches
100 #            "pc-i440fx-2.12".) On the QEMU command line, "-machine
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
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
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
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
161 # @requires-smm: The firmware requires the platform to emulate SMM
164 #                and IA-32 Architectures Software Developer's Manual. On
165 #                the "pc-q35-*" machine types of the @i386 and @x86_64
167 #                "-machine smm=on". (On the "pc-q35-*" machine types of
168 #                the @i386 emulation target, @requires-smm presents
170 #                is "-cpu coreduo,nx=off".) If the firmware is marked as
171 #                both @secure-boot and @requires-smm, then write
174 #                in SMM, using the additional option "-global
176 #                Furthermore, a large guest-physical address space
177 #                (comprising guest RAM, memory hotplug range, and 64-bit
180 #                the "pc-q35-*" machine types of the @i386 and @x86_64
182 #                above the default 16MB with the "-global
183 #                mch.extended-tseg-mbytes=uint16" option. As a rule 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
192 #               that without @requires-smm, guest code running with
196 # @verbose-dynamic: When firmware log capture is enabled, the firmware
200 #                   "pc-i440fx-*" and "pc-q35-*" machine types of the
201 #                   @i386 and @x86_64 emulation targets, firmware log
203 #                   options "-chardev file,id=fwdebug,path=LOGFILEPATH
204 #                   -device isa-debugcon,iobase=0x402,chardev=fwdebug".
205 #                   @verbose-dynamic is mutually exclusive with
206 #                   @verbose-static.
208 # @verbose-static: The firmware unconditionally produces a large amount
211 #                  firmware for the "virt-*" machine types of the @arm
214 #                  PL011 UART. @verbose-static is mutually exclusive
215 #                  with @verbose-dynamic.
217 # @host-uefi-vars: The firmware expects the host to provide an uefi
219 #                  "uefi-vars-sysbus" (aarch64, riscv64, loongarch64)
220 #                  or "uefi-vars-x64" (x86_64) devices.  The firmware
229   'data' : [ 'acpi-s3', 'acpi-s4',
230              'amd-sev', 'amd-sev-es', 'amd-sev-snp',
231              'intel-tdx',
232              'enrolled-keys', 'requires-smm',
233              'secure-boot', 'host-uefi-vars',
234              'verbose-dynamic', 'verbose-static' ] }
255 # "-drive file=@filename,format=@format". Note however that the
256 # option-argument shown here is incomplete; it is completed under
262 # @format: Specifies the block format of the file pointed-to by
280 #         must be configured read-only and can be shared between
282 #         for each new guest and configured read-write.
286 #            for each new guest and configured read-write.
291 #             be configured read-only and can be shared
314 #                  -drive if=none,id=pflash0,readonly=on,file=@executable.@filename,format=@executa…
315 #                  -machine pflash0=pflash0
316 #              or equivalent -blockdev instead of -drive. When
320 #                  -drive if=pflash,unit=0,readonly=on,file=@executable.@filename,format=@executabl…
322 # @nvram-template: Identifies the NVRAM template compatible with
326 #                  individual copy -- a specific NVRAM file -- from
327 #                  @nvram-template.@filename for each new virtual
328 #                  machine definition created. @nvram-template.@filename
332 #                  non-volatile UEFI variables of a virtual machine
335 #                      -drive if=none,id=pflash1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,f…
336 #                      -machine pflash1=pflash1
337 #                  or equivalent -blockdev instead of -drive.
339 #                      -drive if=pflash,unit=1,readonly=off,file=FILENAME_OF_PRIVATE_NVRAM_FILE,for…
346                '*nvram-template' : 'FirmwareFlashFile' } }
356 #            corresponding QEMU command line option is "-kernel
372 #            corresponding QEMU command line option is "-bios
409 # single @Firmware root element) with a double-digit prefix, for example
410 # "50-ovmf.json", "50-seabios-256k.json", etc, so they can be sorted in
414 #   - /usr/share/qemu/firmware -- populated by distro-provided firmware
418 #   - /etc/qemu/firmware -- exclusively for sysadmins' local additions,
420 #   - $XDG_CONFIG_HOME/qemu/firmware -- exclusively for per-user local
424 # Top-down, the list of directories goes from general to specific.
436 #   - /usr/share/qemu/firmware/50-ovmf.json
438 #   - /usr/share/qemu/firmware/50-seabios-256k.json
442 #   $ touch /etc/qemu/firmware/50-ovmf.json
446 #   $ vim /etc/qemu/firmware/50-ovmf.json
450 #   $ vim /etc/qemu/firmware/10-ovmf.json
454 #   $ vim /etc/qemu/firmware/99-ovmf.json
456 # @description: Provides a human-readable description of the firmware.
459 # @interface-types: Lists the types of interfaces that the firmware can
460 #                   expose to the guest OS. This is a non-empty, ordered
461 #                   list; entries near the beginning of @interface-types
465 #                   @interface-types.
477 #        possible exposure to the end-user. @tags serves development and
483 # .. qmp-example::
487 #         "interface-types": [
492 #             "filename": "/usr/share/seabios/bios-256k.bin"
496 #                 "architecture": "i386",
498 #                     "pc-i440fx-*",
499 #                     "pc-q35-*"
505 #                     "pc-i440fx-*",
506 #                     "pc-q35-*"
511 #             "acpi-s3",
512 #             "acpi-s4"
523 #         "interface-types": [
532 #             "nvram-template": {
541 #                     "pc-q35-*"
546 #             "acpi-s3",
547 #             "amd-sev",
548 #             "requires-smm",
549 #             "secure-boot",
550 #             "verbose-dynamic"
553 #             "-a IA32",
554 #             "-a X64",
555 #             "-p OvmfPkg/OvmfPkgIa32X64.dsc",
556 #             "-t GCC48",
557 #             "-b DEBUG",
558 #             "-D SMM_REQUIRE",
559 #             "-D SECURE_BOOT_ENABLE",
560 #             "-D FD_SIZE_4MB"
566 #         "interface-types": [
575 #             "nvram-template": {
584 #                     "pc-q35-*"
589 #             "acpi-s3",
590 #             "amd-sev",
591 #             "enrolled-keys",
592 #             "requires-smm",
593 #             "secure-boot",
594 #             "verbose-dynamic"
597 #             "-a IA32",
598 #             "-a X64",
599 #             "-p OvmfPkg/OvmfPkgIa32X64.dsc",
600 #             "-t GCC48",
601 #             "-b DEBUG",
602 #             "-D SMM_REQUIRE",
603 #             "-D SECURE_BOOT_ENABLE",
604 #             "-D FD_SIZE_4MB"
609 #         "description": "OVMF with SEV-ES support",
610 #         "interface-types": [
619 #             "nvram-template": {
628 #                     "pc-q35-*"
633 #             "acpi-s3",
634 #             "amd-sev",
635 #             "amd-sev-es",
636 #             "verbose-dynamic"
639 #             "-a X64",
640 #             "-p OvmfPkg/OvmfPkgX64.dsc",
641 #             "-t GCC48",
642 #             "-b DEBUG",
643 #             "-D FD_SIZE_4MB"
649 #         "interface-types": [
658 #             "nvram-template": {
667 #                     "virt-*"
675 #             "-a AARCH64",
676 #             "-p ArmVirtPkg/ArmVirtQemu.dsc",
677 #             "-t GCC48",
678 #             "-b DEBUG",
679 #             "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000"
685                'interface-types' : [ 'FirmwareOSInterface' ],