docs/specs/fw_cfg.txt

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