| 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 | For a memory-mapped fw_cfg device, the standard register layout is: |
| 88 | |
| 89 | * base address : Data Register (64 bit) |
| 90 | * base address + 8 : Selector Register (16 bit) |
| 91 | * base address + 16 : DMA Address Register (64 bit) |
| 92 | |
| 93 | Some architectures or machines have a different layout for historical reasons: |
| 94 | |
| 95 | x86, x86_64 |
| 96 | * Selector Register IOport: 0x510 |
| 97 | * Data Register IOport: 0x511 |
| 98 | * DMA Address IOport: 0x514 |
| 99 | |
| 100 | PA-RISC: |
| 101 | * base address : Selector Register (16 bit) |
| 102 | * base address + 4 : Data Register (8 bit) |
| 103 | |
| 104 | 32-bit SPARC, PPC ``g3beige``, ``mac99``, ``prep``: |
| 105 | * base address : Selector Register (16 bit) |
| 106 | * base address + 2 : Data Register (8 bit) |
| 107 | |
| 108 | 64-bit SPARC: |
| 109 | * base address : Selector Register (16 bit) |
| 110 | * base address + 1 : Data Register (8 bit) |
| 111 | |
| 112 | MIPS ``loongson3-virt`` machine: |
| 113 | * base address : Selector Register (16 bit) |
| 114 | * base address + 8 : Data Register (64 bit) |
| 115 | |
| 116 | |
| 117 | ACPI Interface |
| 118 | -------------- |
| 119 | |
| 120 | The fw_cfg device is defined with ACPI ID ``QEMU0002``. Since we expect |
| 121 | ACPI tables to be passed into the guest through the fw_cfg device itself, |
| 122 | the guest-side firmware can not use ACPI to find fw_cfg. However, once the |
| 123 | firmware is finished setting up ACPI tables and hands control over to the |
| 124 | guest kernel, the latter can use the fw_cfg ACPI node for a more accurate |
| 125 | inventory of in-use IOport or MMIO regions. |
| 126 | |
| 127 | Firmware Configuration Items |
| 128 | ---------------------------- |
| 129 | |
| 130 | Signature (Key 0x0000, ``FW_CFG_SIGNATURE``) |
| 131 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 132 | |
| 133 | The presence of the fw_cfg selector and data registers can be verified |
| 134 | by selecting the "signature" item using key 0x0000 (``FW_CFG_SIGNATURE``), |
| 135 | and reading four bytes from the data register. If the fw_cfg device is |
| 136 | present, the four bytes read will contain the characters ``QEMU``. |
| 137 | |
| 138 | If the DMA interface is available, then reading the DMA Address |
| 139 | Register returns 0x51454d5520434647 (``QEMU CFG`` in big-endian format). |
| 140 | |
| 141 | Revision / feature bitmap (Key 0x0001, ``FW_CFG_ID``) |
| 142 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 143 | |
| 144 | A 32-bit little-endian unsigned int, this item is used to check for enabled |
| 145 | features. |
| 146 | |
| 147 | - Bit 0: traditional interface. Always set. |
| 148 | - Bit 1: DMA interface. |
| 149 | |
| 150 | File Directory (Key 0x0019, ``FW_CFG_FILE_DIR``) |
| 151 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 152 | |
| 153 | .. highlight:: c |
| 154 | |
| 155 | Firmware configuration items stored at selector keys 0x0020 or higher |
| 156 | (``FW_CFG_FILE_FIRST`` or higher) have an associated entry in a directory |
| 157 | structure, which makes it easier for guest-side firmware to identify |
| 158 | and retrieve them. The format of this file directory (from ``fw_cfg.h`` in |
| 159 | the QEMU source tree) is shown here, slightly annotated for clarity:: |
| 160 | |
| 161 | struct FWCfgFiles { /* the entire file directory fw_cfg item */ |
| 162 | uint32_t count; /* number of entries, in big-endian format */ |
| 163 | struct FWCfgFile f[]; /* array of file entries, see below */ |
| 164 | }; |
| 165 | |
| 166 | struct FWCfgFile { /* an individual file entry, 64 bytes total */ |
| 167 | uint32_t size; /* size of referenced fw_cfg item, big-endian */ |
| 168 | uint16_t select; /* selector key of fw_cfg item, big-endian */ |
| 169 | uint16_t reserved; |
| 170 | char name[56]; /* fw_cfg item name, NUL-terminated ascii */ |
| 171 | }; |
| 172 | |
| 173 | All Other Data Items |
| 174 | ~~~~~~~~~~~~~~~~~~~~ |
| 175 | |
| 176 | Please consult the QEMU source for the most up-to-date and authoritative list |
| 177 | of selector keys and their respective items' purpose, format and writeability. |
| 178 | |
| 179 | Ranges |
| 180 | ~~~~~~ |
| 181 | |
| 182 | Theoretically, there may be up to 0x4000 generic firmware configuration |
| 183 | items, and up to 0x4000 architecturally specific ones. |
| 184 | |
| 185 | =============== =========== |
| 186 | Selector Reg. Range Usage |
| 187 | =============== =========== |
| 188 | 0x0000 - 0x3fff Generic (0x0000 - 0x3fff, generally RO, possibly RW through |
| 189 | the DMA interface in QEMU v2.9+) |
| 190 | 0x4000 - 0x7fff Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+) |
| 191 | 0x8000 - 0xbfff Arch. Specific (0x0000 - 0x3fff, generally RO, possibly RW |
| 192 | through the DMA interface in QEMU v2.9+) |
| 193 | 0xc000 - 0xffff Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+) |
| 194 | =============== =========== |
| 195 | |
| 196 | In practice, the number of allowed firmware configuration items depends on the |
| 197 | machine type/version. |
| 198 | |
| 199 | Guest-side DMA Interface |
| 200 | ======================== |
| 201 | |
| 202 | If bit 1 of the feature bitmap is set, the DMA interface is present. This does |
| 203 | not replace the existing fw_cfg interface, it is an add-on. This interface |
| 204 | can be used through the 64-bit wide address register. |
| 205 | |
| 206 | The address register is in big-endian format. The value for the register is 0 |
| 207 | at startup and after an operation. A write to the least significant half (at |
| 208 | offset 4) triggers an operation. This means that operations with 32-bit |
| 209 | addresses can be triggered with just one write, whereas operations with |
| 210 | 64-bit addresses can be triggered with one 64-bit write or two 32-bit writes, |
| 211 | starting with the most significant half (at offset 0). |
| 212 | |
| 213 | In this register, the physical address of a ``FWCfgDmaAccess`` structure in RAM |
| 214 | should be written. This is the format of the ``FWCfgDmaAccess`` structure:: |
| 215 | |
| 216 | typedef struct FWCfgDmaAccess { |
| 217 | uint32_t control; |
| 218 | uint32_t length; |
| 219 | uint64_t address; |
| 220 | } FWCfgDmaAccess; |
| 221 | |
| 222 | The fields of the structure are in big endian mode, and the field at the lowest |
| 223 | address is the ``control`` field. |
| 224 | |
| 225 | The ``control`` field has the following bits: |
| 226 | |
| 227 | - Bit 0: Error |
| 228 | - Bit 1: Read |
| 229 | - Bit 2: Skip |
| 230 | - Bit 3: Select. The upper 16 bits are the selected index. |
| 231 | - Bit 4: Write |
| 232 | |
| 233 | When an operation is triggered, if the ``control`` field has bit 3 set, the |
| 234 | upper 16 bits are interpreted as an index of a firmware configuration item. |
| 235 | This has the same effect as writing the selector register. |
| 236 | |
| 237 | If the ``control`` field has bit 1 set, a read operation will be performed. |
| 238 | ``length`` bytes for the current selector and offset will be copied into the |
| 239 | physical RAM address specified by the ``address`` field. |
| 240 | |
| 241 | If the ``control`` field has bit 4 set (and not bit 1), a write operation will be |
| 242 | performed. ``length`` bytes will be copied from the physical RAM address |
| 243 | specified by the ``address`` field to the current selector and offset. QEMU |
| 244 | prevents starting or finishing the write beyond the end of the item associated |
| 245 | with the current selector (i.e., the item cannot be resized). Truncated writes |
| 246 | are dropped entirely. Writes to read-only items are also rejected. All of these |
| 247 | write errors set bit 0 (the error bit) in the ``control`` field. |
| 248 | |
| 249 | If the ``control`` field has bit 2 set (and neither bit 1 nor bit 4), a skip |
| 250 | operation will be performed. The offset for the current selector will be |
| 251 | advanced ``length`` bytes. |
| 252 | |
| 253 | To check the result, read the ``control`` field: |
| 254 | |
| 255 | Error bit set |
| 256 | Something went wrong. |
| 257 | All bits cleared |
| 258 | Transfer finished successfully. |
| 259 | Otherwise |
| 260 | Transfer still in progress |
| 261 | (doesn't happen today due to implementation not being async, |
| 262 | but may in the future). |
| 263 | |
| 264 | Externally Provided Items |
| 265 | ========================= |
| 266 | |
| 267 | Since v2.4, "file" fw_cfg items (i.e., items with selector keys above |
| 268 | ``FW_CFG_FILE_FIRST``, and with a corresponding entry in the fw_cfg file |
| 269 | directory structure) may be inserted via the QEMU command line, using |
| 270 | the following syntax:: |
| 271 | |
| 272 | -fw_cfg [name=]<item_name>,file=<path> |
| 273 | |
| 274 | Or:: |
| 275 | |
| 276 | -fw_cfg [name=]<item_name>,string=<string> |
| 277 | |
| 278 | Since v5.1, QEMU allows some objects to generate fw_cfg-specific content, |
| 279 | the content is then associated with a "file" item using the 'gen_id' option |
| 280 | in the command line, using the following syntax:: |
| 281 | |
| 282 | -object <generator-type>,id=<generated_id>,[generator-specific-options] \ |
| 283 | -fw_cfg [name=]<item_name>,gen_id=<generated_id> |
| 284 | |
| 285 | See QEMU man page for more documentation. |
| 286 | |
| 287 | Using item_name with plain ASCII characters only is recommended. |
| 288 | |
| 289 | Item names beginning with ``opt/`` are reserved for users. QEMU will |
| 290 | never create entries with such names unless explicitly ordered by the |
| 291 | user. |
| 292 | |
| 293 | To avoid clashes among different users, it is strongly recommended |
| 294 | that you use names beginning with ``opt/RFQDN/``, where RFQDN is a reverse |
| 295 | fully qualified domain name you control. For instance, if SeaBIOS |
| 296 | wanted to define additional names, the prefix ``opt/org.seabios/`` would |
| 297 | be appropriate. |
| 298 | |
| 299 | For historical reasons, ``opt/ovmf/`` is reserved for OVMF firmware. |
| 300 | |
| 301 | Prefix ``opt/org.qemu/`` is reserved for QEMU itself. |
| 302 | |
| 303 | Use of names not beginning with ``opt/`` is potentially dangerous and |
| 304 | entirely unsupported. QEMU will warn if you try. |
| 305 | |
| 306 | Use of names not beginning with ``opt/`` is tolerated with 'gen_id' (that |
| 307 | is, the warning is suppressed), but you must know exactly what you're |
| 308 | doing. |
| 309 | |
| 310 | All externally provided fw_cfg items are read-only to the guest. |