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 Bit15 of the selector register indicates whether the configuration
  37 setting is architecture specific. A value of 0 means the item is a
  38 generic configuration item. A value of 1 means the item is specific
  39 to a particular architecture. In other words, generic configuration
  40 items are accessed with a selector value between 0x0000-0x7fff, and
  41 architecture specific configuration items are accessed with a selector
  42 value between 0x8000-0xffff.
  43
  44 == Data Register ==
  45
  46 * Read/Write (writes ignored as of QEMU v2.4)
  47 * Location: platform dependent (IOport [*] or MMIO)
  48 * Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO)
  49 * Endianness: string-preserving
  50
  51 [*] On platforms where the data register is exposed as an IOport, its
  52 port number will always be one greater than the port number of the
  53 selector register. In other words, the two ports overlap, and can not
  54 be mapped separately.
  55
  56 The data register allows access to an array of bytes for each firmware
  57 configuration data item. The specific item is selected by writing to
  58 the selector register, as described above.
  59
  60 Initially following a write to the selector register, the data offset
  61 will be set to zero. Each successful access to the data register will
  62 increment the data offset by the appropriate access width.
  63
  64 Each firmware configuration item has a maximum length of data
  65 associated with the item. After the data offset has passed the
  66 end of this maximum data length, then any reads will return a data
  67 value of 0x00, and all writes will be ignored.
  68
  69 An N-byte wide read of the data register will return the next available
  70 N bytes of the selected firmware configuration item, as a substring, in
  71 increasing address order, similar to memcpy().
  72
  73 == Register Locations ==
  74
  75 === x86, x86_64 Register Locations ===
  76
  77 Selector Register IOport: 0x510
  78 Data Register IOport:     0x511
  79 DMA Address IOport:       0x514
  80
  81 === ARM Register Locations ===
  82
  83 Selector Register address: Base + 8 (2 bytes)
  84 Data Register address:     Base + 0 (8 bytes)
  85 DMA Address address:       Base + 16 (8 bytes)
  86
  87 == Firmware Configuration Items ==
  88
  89 === Signature (Key 0x0000, FW_CFG_SIGNATURE) ===
  90
  91 The presence of the fw_cfg selector and data registers can be verified
  92 by selecting the "signature" item using key 0x0000 (FW_CFG_SIGNATURE),
  93 and reading four bytes from the data register. If the fw_cfg device is
  94 present, the four bytes read will contain the characters "QEMU".
  95
  96 If the DMA interface is available, then reading the DMA Address
  97 Register returns 0x51454d5520434647 ("QEMU CFG" in big-endian format).
  98
  99 === Revision / feature bitmap (Key 0x0001, FW_CFG_ID) ===
 100
 101 A 32-bit little-endian unsigned int, this item is used to check for enabled
 102 features.
 103  - Bit 0: traditional interface. Always set.
 104  - Bit 1: DMA interface.
 105
 106 === File Directory (Key 0x0019, FW_CFG_FILE_DIR) ===
 107
 108 Firmware configuration items stored at selector keys 0x0020 or higher
 109 (FW_CFG_FILE_FIRST or higher) have an associated entry in a directory
 110 structure, which makes it easier for guest-side firmware to identify
 111 and retrieve them. The format of this file directory (from fw_cfg.h in
 112 the QEMU source tree) is shown here, slightly annotated for clarity:
 113
 114 struct FWCfgFiles {             /* the entire file directory fw_cfg item */
 115     uint32_t count;             /* number of entries, in big-endian format */
 116     struct FWCfgFile f[];       /* array of file entries, see below */
 117 };
 118
 119 struct FWCfgFile {              /* an individual file entry, 64 bytes total */
 120     uint32_t size;              /* size of referenced fw_cfg item, big-endian */
 121     uint16_t select;            /* selector key of fw_cfg item, big-endian */
 122     uint16_t reserved;
 123     char name[56];              /* fw_cfg item name, NUL-terminated ascii */
 124 };
 125
 126 === All Other Data Items ===
 127
 128 Please consult the QEMU source for the most up-to-date and authoritative
 129 list of selector keys and their respective items' purpose and format.
 130
 131 === Ranges ===
 132
 133 Theoretically, there may be up to 0x4000 generic firmware configuration
 134 items, and up to 0x4000 architecturally specific ones.
 135
 136 Selector Reg.    Range Usage
 137 ---------------  -----------
 138 0x0000 - 0x3fff  Generic (0x0000 - 0x3fff, RO)
 139 0x4000 - 0x7fff  Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+)
 140 0x8000 - 0xbfff  Arch. Specific (0x0000 - 0x3fff, RO)
 141 0xc000 - 0xffff  Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+)
 142
 143 In practice, the number of allowed firmware configuration items is given
 144 by the value of FW_CFG_MAX_ENTRY (see fw_cfg.h).
 145
 146 = Guest-side DMA Interface =
 147
 148 If bit 1 of the feature bitmap is set, the DMA interface is present. This does
 149 not replace the existing fw_cfg interface, it is an add-on. This interface
 150 can be used through the 64-bit wide address register.
 151
 152 The address register is in big-endian format. The value for the register is 0
 153 at startup and after an operation. A write to the least significant half (at
 154 offset 4) triggers an operation. This means that operations with 32-bit
 155 addresses can be triggered with just one write, whereas operations with
 156 64-bit addresses can be triggered with one 64-bit write or two 32-bit writes,
 157 starting with the most significant half (at offset 0).
 158
 159 In this register, the physical address of a FWCfgDmaAccess structure in RAM
 160 should be written. This is the format of the FWCfgDmaAccess structure:
 161
 162 typedef struct FWCfgDmaAccess {
 163     uint32_t control;
 164     uint32_t length;
 165     uint64_t address;
 166 } FWCfgDmaAccess;
 167
 168 The fields of the structure are in big endian mode, and the field at the lowest
 169 address is the "control" field.
 170
 171 The "control" field has the following bits:
 172  - Bit 0: Error
 173  - Bit 1: Read
 174  - Bit 2: Skip
 175  - Bit 3: Select. The upper 16 bits are the selected index.
 176
 177 When an operation is triggered, if the "control" field has bit 3 set, the
 178 upper 16 bits are interpreted as an index of a firmware configuration item.
 179 This has the same effect as writing the selector register.
 180
 181 If the "control" field has bit 1 set, a read operation will be performed.
 182 "length" bytes for the current selector and offset will be copied into the
 183 physical RAM address specified by the "address" field.
 184
 185 If the "control" field has bit 2 set (and not bit 1), a skip operation will be
 186 performed. The offset for the current selector will be advanced "length" bytes.
 187
 188 To check the result, read the "control" field:
 189    error bit set        ->  something went wrong.
 190    all bits cleared     ->  transfer finished successfully.
 191    otherwise            ->  transfer still in progress (doesn't happen
 192                             today due to implementation not being async,
 193                             but may in the future).
 194
 195 = Externally Provided Items =
 196
 197 As of v2.4, "file" fw_cfg items (i.e., items with selector keys above
 198 FW_CFG_FILE_FIRST, and with a corresponding entry in the fw_cfg file
 199 directory structure) may be inserted via the QEMU command line, using
 200 the following syntax:
 201
 202     -fw_cfg [name=]<item_name>,file=<path>
 203
 204 where <item_name> is the fw_cfg item name, and <path> is the location
 205 on the host file system of a file containing the data to be inserted.
 206
 207 Small enough items may be provided directly as strings on the command
 208 line, using the syntax:
 209
 210     -fw_cfg [name=]<item_name>,string=<string>
 211
 212 The terminating NUL character of the content <string> will NOT be
 213 included as part of the fw_cfg item data, which is consistent with
 214 the absence of a NUL terminator for items inserted via the file option.
 215
 216 Both <item_name> and, if applicable, the content <string> are passed
 217 through by QEMU without any interpretation, expansion, or further
 218 processing. Any such processing (potentially performed e.g., by the shell)
 219 is outside of QEMU's responsibility; as such, using plain ASCII characters
 220 is recommended.
 221
 222 NOTE: Users *SHOULD* choose item names beginning with the prefix "opt/"
 223 when using the "-fw_cfg" command line option, to avoid conflicting with
 224 item names used internally by QEMU. For instance:
 225
 226     -fw_cfg name=opt/my_item_name,file=./my_blob.bin
 227
 228 Similarly, QEMU developers *SHOULD NOT* use item names prefixed with
 229 "opt/" when inserting items programmatically, e.g. via fw_cfg_add_file().