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