docs/specs/fw_cfg.rst

   1 ===========================================
   2 QEMU Firmware Configuration (fw_cfg) Device
   3 ===========================================
   4
   5 Guest-side Hardware Interface
   6 =============================
   7
   8 This hardware interface allows the guest to retrieve various data items
   9 (blobs) that can influence how the firmware configures itself, or may
  10 contain tables to be installed for the guest OS. Examples include device
  11 boot order, ACPI and SMBIOS tables, virtual machine UUID, SMP and NUMA
  12 information, kernel/initrd images for direct (Linux) kernel booting, etc.
  13
  14 Selector (Control) Register
  15 ---------------------------
  16
  17 * Write only
  18 * Location: platform dependent (IOport or MMIO)
  19 * Width: 16-bit
  20 * Endianness: little-endian (if IOport), or big-endian (if MMIO)
  21
  22 A write to this register sets the index of a firmware configuration
  23 item which can subsequently be accessed via the data register.
  24
  25 Setting the selector register will cause the data offset to be set
  26 to zero. The data offset impacts which data is accessed via the data
  27 register, and is explained below.
  28
  29 Bit14 of the selector register indicates whether the configuration
  30 setting is being written. A value of 0 means the item is only being
  31 read, and all write access to the data port will be ignored. A value
  32 of 1 means the item's data can be overwritten by writes to the data
  33 register. In other words, configuration write mode is enabled when
  34 the selector value is between 0x4000-0x7fff or 0xc000-0xffff.
  35
  36 .. NOTE::
  37       As of QEMU v2.4, writes to the fw_cfg data register are no
  38       longer supported, and will be ignored (treated as no-ops)!
  39
  40 .. NOTE::
  41       As of QEMU v2.9, writes are reinstated, but only through the DMA
  42       interface (see below). Furthermore, writeability of any specific item is
  43       governed independently of Bit14 in the selector key value.
  44
  45 Bit15 of the selector register indicates whether the configuration
  46 setting is architecture specific. A value of 0 means the item is a
  47 generic configuration item. A value of 1 means the item is specific
  48 to a particular architecture. In other words, generic configuration
  49 items are accessed with a selector value between 0x0000-0x7fff, and
  50 architecture specific configuration items are accessed with a selector
  51 value between 0x8000-0xffff.
  52
  53 Data Register
  54 -------------
  55
  56 * Read/Write (writes ignored as of QEMU v2.4, but see the DMA interface)
  57 * Location: platform dependent (IOport\ [#placement]_ or MMIO)
  58 * Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO)
  59 * Endianness: string-preserving
  60
  61 .. [#placement]
  62     On platforms where the data register is exposed as an IOport, its
  63     port number will always be one greater than the port number of the
  64     selector register. In other words, the two ports overlap, and can not
  65     be mapped separately.
  66
  67 The data register allows access to an array of bytes for each firmware
  68 configuration data item. The specific item is selected by writing to
  69 the selector register, as described above.
  70
  71 Initially following a write to the selector register, the data offset
  72 will be set to zero. Each successful access to the data register will
  73 increment the data offset by the appropriate access width.
  74
  75 Each firmware configuration item has a maximum length of data
  76 associated with the item. After the data offset has passed the
  77 end of this maximum data length, then any reads will return a data
  78 value of 0x00, and all writes will be ignored.
  79
  80 An N-byte wide read of the data register will return the next available
  81 N bytes of the selected firmware configuration item, as a substring, in
  82 increasing address order, similar to memcpy().
  83
  84 Register Locations
  85 ------------------
  86
  87 x86, x86_64
  88     * Selector Register IOport: 0x510
  89     * Data Register IOport:     0x511
  90     * DMA Address IOport:       0x514
  91
  92 Arm
  93     * Selector Register address: Base + 8 (2 bytes)
  94     * Data Register address:     Base + 0 (8 bytes)
  95     * DMA Address address:       Base + 16 (8 bytes)
  96
  97 ACPI Interface
  98 --------------
  99
 100 The fw_cfg device is defined with ACPI ID ``QEMU0002``. Since we expect
 101 ACPI tables to be passed into the guest through the fw_cfg device itself,
 102 the guest-side firmware can not use ACPI to find fw_cfg. However, once the
 103 firmware is finished setting up ACPI tables and hands control over to the
 104 guest kernel, the latter can use the fw_cfg ACPI node for a more accurate
 105 inventory of in-use IOport or MMIO regions.
 106
 107 Firmware Configuration Items
 108 ----------------------------
 109
 110 Signature (Key 0x0000, ``FW_CFG_SIGNATURE``)
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 The presence of the fw_cfg selector and data registers can be verified
 114 by selecting the "signature" item using key 0x0000 (``FW_CFG_SIGNATURE``),
 115 and reading four bytes from the data register. If the fw_cfg device is
 116 present, the four bytes read will contain the characters ``QEMU``.
 117
 118 If the DMA interface is available, then reading the DMA Address
 119 Register returns 0x51454d5520434647 (``QEMU CFG`` in big-endian format).
 120
 121 Revision / feature bitmap (Key 0x0001, ``FW_CFG_ID``)
 122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 A 32-bit little-endian unsigned int, this item is used to check for enabled
 125 features.
 126
 127 - Bit 0: traditional interface. Always set.
 128 - Bit 1: DMA interface.
 129
 130 File Directory (Key 0x0019, ``FW_CFG_FILE_DIR``)
 131 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 132
 133 .. highlight:: c
 134
 135 Firmware configuration items stored at selector keys 0x0020 or higher
 136 (``FW_CFG_FILE_FIRST`` or higher) have an associated entry in a directory
 137 structure, which makes it easier for guest-side firmware to identify
 138 and retrieve them. The format of this file directory (from ``fw_cfg.h`` in
 139 the QEMU source tree) is shown here, slightly annotated for clarity::
 140
 141     struct FWCfgFiles {         /* the entire file directory fw_cfg item */
 142         uint32_t count;         /* number of entries, in big-endian format */
 143         struct FWCfgFile f[];   /* array of file entries, see below */
 144     };
 145
 146     struct FWCfgFile {          /* an individual file entry, 64 bytes total */
 147         uint32_t size;          /* size of referenced fw_cfg item, big-endian */
 148         uint16_t select;        /* selector key of fw_cfg item, big-endian */
 149         uint16_t reserved;
 150         char name[56];          /* fw_cfg item name, NUL-terminated ascii */
 151     };
 152
 153 All Other Data Items
 154 ~~~~~~~~~~~~~~~~~~~~
 155
 156 Please consult the QEMU source for the most up-to-date and authoritative list
 157 of selector keys and their respective items' purpose, format and writeability.
 158
 159 Ranges
 160 ~~~~~~
 161
 162 Theoretically, there may be up to 0x4000 generic firmware configuration
 163 items, and up to 0x4000 architecturally specific ones.
 164
 165 ===============  ===========
 166 Selector Reg.    Range Usage
 167 ===============  ===========
 168 0x0000 - 0x3fff  Generic (0x0000 - 0x3fff, generally RO, possibly RW through
 169                  the DMA interface in QEMU v2.9+)
 170 0x4000 - 0x7fff  Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+)
 171 0x8000 - 0xbfff  Arch. Specific (0x0000 - 0x3fff, generally RO, possibly RW
 172                  through the DMA interface in QEMU v2.9+)
 173 0xc000 - 0xffff  Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+)
 174 ===============  ===========
 175
 176 In practice, the number of allowed firmware configuration items depends on the
 177 machine type/version.
 178
 179 Guest-side DMA Interface
 180 ========================
 181
 182 If bit 1 of the feature bitmap is set, the DMA interface is present. This does
 183 not replace the existing fw_cfg interface, it is an add-on. This interface
 184 can be used through the 64-bit wide address register.
 185
 186 The address register is in big-endian format. The value for the register is 0
 187 at startup and after an operation. A write to the least significant half (at
 188 offset 4) triggers an operation. This means that operations with 32-bit
 189 addresses can be triggered with just one write, whereas operations with
 190 64-bit addresses can be triggered with one 64-bit write or two 32-bit writes,
 191 starting with the most significant half (at offset 0).
 192
 193 In this register, the physical address of a ``FWCfgDmaAccess`` structure in RAM
 194 should be written. This is the format of the ``FWCfgDmaAccess`` structure::
 195
 196     typedef struct FWCfgDmaAccess {
 197         uint32_t control;
 198         uint32_t length;
 199         uint64_t address;
 200     } FWCfgDmaAccess;
 201
 202 The fields of the structure are in big endian mode, and the field at the lowest
 203 address is the ``control`` field.
 204
 205 The ``control`` field has the following bits:
 206
 207 - Bit 0: Error
 208 - Bit 1: Read
 209 - Bit 2: Skip
 210 - Bit 3: Select. The upper 16 bits are the selected index.
 211 - Bit 4: Write
 212
 213 When an operation is triggered, if the ``control`` field has bit 3 set, the
 214 upper 16 bits are interpreted as an index of a firmware configuration item.
 215 This has the same effect as writing the selector register.
 216
 217 If the ``control`` field has bit 1 set, a read operation will be performed.
 218 ``length`` bytes for the current selector and offset will be copied into the
 219 physical RAM address specified by the ``address`` field.
 220
 221 If the ``control`` field has bit 4 set (and not bit 1), a write operation will be
 222 performed. ``length`` bytes will be copied from the physical RAM address
 223 specified by the ``address`` field to the current selector and offset. QEMU
 224 prevents starting or finishing the write beyond the end of the item associated
 225 with the current selector (i.e., the item cannot be resized). Truncated writes
 226 are dropped entirely. Writes to read-only items are also rejected. All of these
 227 write errors set bit 0 (the error bit) in the ``control`` field.
 228
 229 If the ``control`` field has bit 2 set (and neither bit 1 nor bit 4), a skip
 230 operation will be performed. The offset for the current selector will be
 231 advanced ``length`` bytes.
 232
 233 To check the result, read the ``control`` field:
 234
 235 Error bit set
 236     Something went wrong.
 237 All bits cleared
 238     Transfer finished successfully.
 239 Otherwise
 240     Transfer still in progress
 241     (doesn't happen today due to implementation not being async,
 242     but may in the future).
 243
 244 Externally Provided Items
 245 =========================
 246
 247 Since v2.4, "file" fw_cfg items (i.e., items with selector keys above
 248 ``FW_CFG_FILE_FIRST``, and with a corresponding entry in the fw_cfg file
 249 directory structure) may be inserted via the QEMU command line, using
 250 the following syntax::
 251
 252     -fw_cfg [name=]<item_name>,file=<path>
 253
 254 Or::
 255
 256     -fw_cfg [name=]<item_name>,string=<string>
 257
 258 Since v5.1, QEMU allows some objects to generate fw_cfg-specific content,
 259 the content is then associated with a "file" item using the 'gen_id' option
 260 in the command line, using the following syntax::
 261
 262     -object <generator-type>,id=<generated_id>,[generator-specific-options] \
 263     -fw_cfg [name=]<item_name>,gen_id=<generated_id>
 264
 265 See QEMU man page for more documentation.
 266
 267 Using item_name with plain ASCII characters only is recommended.
 268
 269 Item names beginning with ``opt/`` are reserved for users.  QEMU will
 270 never create entries with such names unless explicitly ordered by the
 271 user.
 272
 273 To avoid clashes among different users, it is strongly recommended
 274 that you use names beginning with ``opt/RFQDN/``, where RFQDN is a reverse
 275 fully qualified domain name you control.  For instance, if SeaBIOS
 276 wanted to define additional names, the prefix ``opt/org.seabios/`` would
 277 be appropriate.
 278
 279 For historical reasons, ``opt/ovmf/`` is reserved for OVMF firmware.
 280
 281 Prefix ``opt/org.qemu/`` is reserved for QEMU itself.
 282
 283 Use of names not beginning with ``opt/`` is potentially dangerous and
 284 entirely unsupported.  QEMU will warn if you try.
 285
 286 Use of names not beginning with ``opt/`` is tolerated with 'gen_id' (that
 287 is, the warning is suppressed), but you must know exactly what you're
 288 doing.
 289
 290 All externally provided fw_cfg items are read-only to the guest.