# -*- Mode: Python -*- # # Copyright (C) 2018 Red Hat, Inc. # # Authors: # Daniel P. Berrange # Laszlo Ersek # # 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, OpenHackWare, # 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".) 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' ] } }