0001 What: /sys/firmware/qemu_fw_cfg/
0002 Date: August 2015
0003 Contact: Gabriel Somlo <somlo@cmu.edu>
0004 Description:
0005 Several different architectures supported by QEMU (x86, arm,
0006 sun4*, ppc/mac) are provisioned with a firmware configuration
0007 (fw_cfg) device, originally intended as a way for the host to
0008 provide configuration data to the guest firmware. Starting
0009 with QEMU v2.4, arbitrary fw_cfg file entries may be specified
0010 by the user on the command line, which makes fw_cfg additionally
0011 useful as an out-of-band, asynchronous mechanism for providing
0012 configuration data to the guest userspace.
0013
0014 The authoritative guest-side hardware interface documentation
0015 to the fw_cfg device can be found in "docs/specs/fw_cfg.rst"
0016 in the QEMU source tree, or online at:
0017 https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html
0018
0019 **SysFS fw_cfg Interface**
0020
0021 The fw_cfg sysfs interface described in this document is only
0022 intended to display discoverable blobs (i.e., those registered
0023 with the file directory), as there is no way to determine the
0024 presence or size of "legacy" blobs (with selector keys between
0025 0x0002 and 0x0018) programmatically.
0026
0027 All fw_cfg information is shown under:
0028
0029 /sys/firmware/qemu_fw_cfg/
0030
0031 The only legacy blob displayed is the fw_cfg device revision:
0032
0033 /sys/firmware/qemu_fw_cfg/rev
0034
0035 **Discoverable fw_cfg blobs by selector key**
0036
0037 All discoverable blobs listed in the fw_cfg file directory are
0038 displayed as entries named after their unique selector key
0039 value, e.g.:
0040
0041 /sys/firmware/qemu_fw_cfg/by_key/32
0042 /sys/firmware/qemu_fw_cfg/by_key/33
0043 /sys/firmware/qemu_fw_cfg/by_key/34
0044 ...
0045
0046 Each such fw_cfg sysfs entry has the following values exported
0047 as attributes:
0048
0049 ==== ====================================================
0050 name The 56-byte nul-terminated ASCII string used as the
0051 blob's 'file name' in the fw_cfg directory.
0052 size The length of the blob, as given in the fw_cfg
0053 directory.
0054 key The value of the blob's selector key as given in the
0055 fw_cfg directory. This value is the same as used in
0056 the parent directory name.
0057 raw The raw bytes of the blob, obtained by selecting the
0058 entry via the control register, and reading a number
0059 of bytes equal to the blob size from the data
0060 register.
0061 ==== ====================================================
0062
0063 **Listing fw_cfg blobs by file name**
0064
0065 While the fw_cfg device does not impose any specific naming
0066 convention on the blobs registered in the file directory,
0067 QEMU developers have traditionally used path name semantics
0068 to give each blob a descriptive name. For example::
0069
0070 "bootorder"
0071 "genroms/kvmvapic.bin"
0072 "etc/e820"
0073 "etc/boot-fail-wait"
0074 "etc/system-states"
0075 "etc/table-loader"
0076 "etc/acpi/rsdp"
0077 "etc/acpi/tables"
0078 "etc/smbios/smbios-tables"
0079 "etc/smbios/smbios-anchor"
0080 ...
0081
0082 In addition to the listing by unique selector key described
0083 above, the fw_cfg sysfs driver also attempts to build a tree
0084 of directories matching the path name components of fw_cfg
0085 blob names, ending in symlinks to the by_key entry for each
0086 "basename", as illustrated below (assume current directory is
0087 /sys/firmware)::
0088
0089 qemu_fw_cfg/by_name/bootorder -> ../by_key/38
0090 qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35
0091 qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41
0092 ...
0093
0094 Construction of the directory tree and symlinks is done on a
0095 "best-effort" basis, as there is no guarantee that components
0096 of fw_cfg blob names are always "well behaved". I.e., there is
0097 the possibility that a symlink (basename) will conflict with
0098 a dirname component of another fw_cfg blob, in which case the
0099 creation of the offending /sys/firmware/qemu_fw_cfg/by_name
0100 entry will be skipped.
0101
0102 The authoritative list of entries will continue to be found
0103 under the /sys/firmware/qemu_fw_cfg/by_key directory.
