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 36Bit15 of the selector register indicates whether the configuration 37setting is architecture specific. A value of 0 means the item is a 38generic configuration item. A value of 1 means the item is specific 39to a particular architecture. In other words, generic configuration 40items are accessed with a selector value between 0x0000-0x7fff, and 41architecture specific configuration items are accessed with a selector 42value 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 52port number will always be one greater than the port number of the 53selector register. In other words, the two ports overlap, and can not 54be mapped separately. 55 56The data register allows access to an array of bytes for each firmware 57configuration data item. The specific item is selected by writing to 58the selector register, as described above. 59 60Initially following a write to the selector register, the data offset 61will be set to zero. Each successful access to the data register will 62increment the data offset by the appropriate access width. 63 64Each firmware configuration item has a maximum length of data 65associated with the item. After the data offset has passed the 66end of this maximum data length, then any reads will return a data 67value of 0x00, and all writes will be ignored. 68 69An N-byte wide read of the data register will return the next available 70N bytes of the selected firmware configuration item, as a substring, in 71increasing address order, similar to memcpy(). 72 73== Register Locations == 74 75=== x86, x86_64 Register Locations === 76 77Selector Register IOport: 0x510 78Data Register IOport: 0x511 79 80== Firmware Configuration Items == 81 82=== Signature (Key 0x0000, FW_CFG_SIGNATURE) === 83 84The presence of the fw_cfg selector and data registers can be verified 85by selecting the "signature" item using key 0x0000 (FW_CFG_SIGNATURE), 86and reading four bytes from the data register. If the fw_cfg device is 87present, the four bytes read will contain the characters "QEMU". 88 89=== Revision (Key 0x0001, FW_CFG_ID) === 90 91A 32-bit little-endian unsigned int, this item is used as an interface 92revision number, and is currently set to 1 by QEMU when fw_cfg is 93initialized. 94 95=== File Directory (Key 0x0019, FW_CFG_FILE_DIR) === 96 97Firmware configuration items stored at selector keys 0x0020 or higher 98(FW_CFG_FILE_FIRST or higher) have an associated entry in a directory 99structure, which makes it easier for guest-side firmware to identify 100and retrieve them. The format of this file directory (from fw_cfg.h in 101the QEMU source tree) is shown here, slightly annotated for clarity: 102 103struct FWCfgFiles { /* the entire file directory fw_cfg item */ 104 uint32_t count; /* number of entries, in big-endian format */ 105 struct FWCfgFile f[]; /* array of file entries, see below */ 106}; 107 108struct FWCfgFile { /* an individual file entry, 64 bytes total */ 109 uint32_t size; /* size of referenced fw_cfg item, big-endian */ 110 uint16_t select; /* selector key of fw_cfg item, big-endian */ 111 uint16_t reserved; 112 char name[56]; /* fw_cfg item name, NUL-terminated ascii */ 113}; 114 115=== All Other Data Items === 116 117Please consult the QEMU source for the most up-to-date and authoritative 118list of selector keys and their respective items' purpose and format. 119 120=== Ranges === 121 122Theoretically, there may be up to 0x4000 generic firmware configuration 123items, and up to 0x4000 architecturally specific ones. 124 125Selector Reg. Range Usage 126--------------- ----------- 1270x0000 - 0x3fff Generic (0x0000 - 0x3fff, RO) 1280x4000 - 0x7fff Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+) 1290x8000 - 0xbfff Arch. Specific (0x0000 - 0x3fff, RO) 1300xc000 - 0xffff Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+) 131 132In practice, the number of allowed firmware configuration items is given 133by the value of FW_CFG_MAX_ENTRY (see fw_cfg.h). 134 135= Host-side API = 136 137The following functions are available to the QEMU programmer for adding 138data to a fw_cfg device during guest initialization (see fw_cfg.h for 139each function's complete prototype): 140 141== fw_cfg_add_bytes() == 142 143Given a selector key value, starting pointer, and size, create an item 144as a raw "blob" of the given size, available by selecting the given key. 145The data referenced by the starting pointer is only linked, NOT copied, 146into the data structure of the fw_cfg device. 147 148== fw_cfg_add_string() == 149 150Instead of a starting pointer and size, this function accepts a pointer 151to a NUL-terminated ascii string, and inserts a newly allocated copy of 152the string (including the NUL terminator) into the fw_cfg device data 153structure. 154 155== fw_cfg_add_iXX() == 156 157Insert an XX-bit item, where XX may be 16, 32, or 64. These functions 158will convert a 16-, 32-, or 64-bit integer to little-endian, then add 159a dynamically allocated copy of the appropriately sized item to fw_cfg 160under the given selector key value. 161 162== fw_cfg_add_file() == 163 164Given a filename (i.e., fw_cfg item name), starting pointer, and size, 165create an item as a raw "blob" of the given size. Unlike fw_cfg_add_bytes() 166above, the next available selector key (above 0x0020, FW_CFG_FILE_FIRST) 167will be used, and a new entry will be added to the file directory structure 168(at key 0x0019), containing the item name, blob size, and automatically 169assigned selector key value. The data referenced by the starting pointer 170is only linked, NOT copied, into the fw_cfg data structure. 171 172== fw_cfg_add_file_callback() == 173 174Like fw_cfg_add_file(), but additionally sets pointers to a callback 175function (and opaque argument), which will be executed host-side by 176QEMU each time a byte is read by the guest from this particular item. 177 178NOTE: The callback function is given the opaque argument set by 179fw_cfg_add_file_callback(), but also the current data offset, 180allowing it the option of only acting upon specific offset values 181(e.g., 0, before the first data byte of the selected item is 182returned to the guest). 183 184== fw_cfg_modify_file() == 185 186Given a filename (i.e., fw_cfg item name), starting pointer, and size, 187completely replace the configuration item referenced by the given item 188name with the new given blob. If an existing blob is found, its 189callback information is removed, and a pointer to the old data is 190returned to allow the caller to free it, helping avoid memory leaks. 191If a configuration item does not already exist under the given item 192name, a new item will be created as with fw_cfg_add_file(), and NULL 193is returned to the caller. In any case, the data referenced by the 194starting pointer is only linked, NOT copied, into the fw_cfg data 195structure. 196 197== fw_cfg_add_callback() == 198 199Like fw_cfg_add_bytes(), but additionally sets pointers to a callback 200function (and opaque argument), which will be executed host-side by 201QEMU each time a guest-side write operation to this particular item 202completes fully overwriting the item's data. 203 204NOTE: This function is deprecated, and will be completely removed 205starting with QEMU v2.4. 206