Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg

   1 What:           /sys/firmware/qemu_fw_cfg/
   2 Date:           August 2015
   3 Contact:        Gabriel Somlo <somlo@cmu.edu>
   4 Description:
   5                 Several different architectures supported by QEMU (x86, arm,
   6                 sun4*, ppc/mac) are provisioned with a firmware configuration
   7                 (fw_cfg) device, originally intended as a way for the host to
   8                 provide configuration data to the guest firmware. Starting
   9                 with QEMU v2.4, arbitrary fw_cfg file entries may be specified
  10                 by the user on the command line, which makes fw_cfg additionally
  11                 useful as an out-of-band, asynchronous mechanism for providing
  12                 configuration data to the guest userspace.
  13
  14                 The authoritative guest-side hardware interface documentation
  15                 to the fw_cfg device can be found in "docs/specs/fw_cfg.rst"
  16                 in the QEMU source tree, or online at:
  17                 https://qemu-project.gitlab.io/qemu/specs/fw_cfg.html
  18
  19                 **SysFS fw_cfg Interface**
  20
  21                 The fw_cfg sysfs interface described in this document is only
  22                 intended to display discoverable blobs (i.e., those registered
  23                 with the file directory), as there is no way to determine the
  24                 presence or size of "legacy" blobs (with selector keys between
  25                 0x0002 and 0x0018) programmatically.
  26
  27                 All fw_cfg information is shown under:
  28
  29                         /sys/firmware/qemu_fw_cfg/
  30
  31                 The only legacy blob displayed is the fw_cfg device revision:
  32
  33                         /sys/firmware/qemu_fw_cfg/rev
  34
  35                 **Discoverable fw_cfg blobs by selector key**
  36
  37                 All discoverable blobs listed in the fw_cfg file directory are
  38                 displayed as entries named after their unique selector key
  39                 value, e.g.:
  40
  41                         /sys/firmware/qemu_fw_cfg/by_key/32
  42                         /sys/firmware/qemu_fw_cfg/by_key/33
  43                         /sys/firmware/qemu_fw_cfg/by_key/34
  44                         ...
  45
  46                 Each such fw_cfg sysfs entry has the following values exported
  47                 as attributes:
  48
  49                 ====      ====================================================
  50                 name      The 56-byte nul-terminated ASCII string used as the
  51                           blob's 'file name' in the fw_cfg directory.
  52                 size      The length of the blob, as given in the fw_cfg
  53                           directory.
  54                 key       The value of the blob's selector key as given in the
  55                           fw_cfg directory. This value is the same as used in
  56                           the parent directory name.
  57                 raw       The raw bytes of the blob, obtained by selecting the
  58                           entry via the control register, and reading a number
  59                           of bytes equal to the blob size from the data
  60                           register.
  61                 ====      ====================================================
  62
  63                 **Listing fw_cfg blobs by file name**
  64
  65                 While the fw_cfg device does not impose any specific naming
  66                 convention on the blobs registered in the file directory,
  67                 QEMU developers have traditionally used path name semantics
  68                 to give each blob a descriptive name. For example::
  69
  70                         "bootorder"
  71                         "genroms/kvmvapic.bin"
  72                         "etc/e820"
  73                         "etc/boot-fail-wait"
  74                         "etc/system-states"
  75                         "etc/table-loader"
  76                         "etc/acpi/rsdp"
  77                         "etc/acpi/tables"
  78                         "etc/smbios/smbios-tables"
  79                         "etc/smbios/smbios-anchor"
  80                         ...
  81
  82                 In addition to the listing by unique selector key described
  83                 above, the fw_cfg sysfs driver also attempts to build a tree
  84                 of directories matching the path name components of fw_cfg
  85                 blob names, ending in symlinks to the by_key entry for each
  86                 "basename", as illustrated below (assume current directory is
  87                 /sys/firmware)::
  88
  89                     qemu_fw_cfg/by_name/bootorder -> ../by_key/38
  90                     qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35
  91                     qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41
  92                     ...
  93
  94                 Construction of the directory tree and symlinks is done on a
  95                 "best-effort" basis, as there is no guarantee that components
  96                 of fw_cfg blob names are always "well behaved". I.e., there is
  97                 the possibility that a symlink (basename) will conflict with
  98                 a dirname component of another fw_cfg blob, in which case the
  99                 creation of the offending /sys/firmware/qemu_fw_cfg/by_name
 100                 entry will be skipped.
 101
 102                 The authoritative list of entries will continue to be found
 103                 under the /sys/firmware/qemu_fw_cfg/by_key directory.