qemu/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
  80 == Firmware Configuration Items ==
  81
  82 === Signature (Key 0x0000, FW_CFG_SIGNATURE) ===
  83
  84 The presence of the fw_cfg selector and data registers can be verified
  85 by selecting the "signature" item using key 0x0000 (FW_CFG_SIGNATURE),
  86 and reading four bytes from the data register. If the fw_cfg device is
  87 present, the four bytes read will contain the characters "QEMU".
  88
  89 === Revision (Key 0x0001, FW_CFG_ID) ===
  90
  91 A 32-bit little-endian unsigned int, this item is used as an interface
  92 revision number, and is currently set to 1 by QEMU when fw_cfg is
  93 initialized.
  94
  95 === File Directory (Key 0x0019, FW_CFG_FILE_DIR) ===
  96
  97 Firmware configuration items stored at selector keys 0x0020 or higher
  98 (FW_CFG_FILE_FIRST or higher) have an associated entry in a directory
  99 structure, which makes it easier for guest-side firmware to identify
 100 and retrieve them. The format of this file directory (from fw_cfg.h in
 101 the QEMU source tree) is shown here, slightly annotated for clarity:
 102
 103 struct 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
 108 struct 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
 117 Please consult the QEMU source for the most up-to-date and authoritative
 118 list of selector keys and their respective items' purpose and format.
 119
 120 === Ranges ===
 121
 122 Theoretically, there may be up to 0x4000 generic firmware configuration
 123 items, and up to 0x4000 architecturally specific ones.
 124
 125 Selector Reg.    Range Usage
 126 ---------------  -----------
 127 0x0000 - 0x3fff  Generic (0x0000 - 0x3fff, RO)
 128 0x4000 - 0x7fff  Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+)
 129 0x8000 - 0xbfff  Arch. Specific (0x0000 - 0x3fff, RO)
 130 0xc000 - 0xffff  Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+)
 131
 132 In practice, the number of allowed firmware configuration items is given
 133 by the value of FW_CFG_MAX_ENTRY (see fw_cfg.h).
 134
 135 = Host-side API =
 136
 137 The following functions are available to the QEMU programmer for adding
 138 data to a fw_cfg device during guest initialization (see fw_cfg.h for
 139 each function's complete prototype):
 140
 141 == fw_cfg_add_bytes() ==
 142
 143 Given a selector key value, starting pointer, and size, create an item
 144 as a raw "blob" of the given size, available by selecting the given key.
 145 The data referenced by the starting pointer is only linked, NOT copied,
 146 into the data structure of the fw_cfg device.
 147
 148 == fw_cfg_add_string() ==
 149
 150 Instead of a starting pointer and size, this function accepts a pointer
 151 to a NUL-terminated ascii string, and inserts a newly allocated copy of
 152 the string (including the NUL terminator) into the fw_cfg device data
 153 structure.
 154
 155 == fw_cfg_add_iXX() ==
 156
 157 Insert an XX-bit item, where XX may be 16, 32, or 64. These functions
 158 will convert a 16-, 32-, or 64-bit integer to little-endian, then add
 159 a dynamically allocated copy of the appropriately sized item to fw_cfg
 160 under the given selector key value.
 161
 162 == fw_cfg_add_file() ==
 163
 164 Given a filename (i.e., fw_cfg item name), starting pointer, and size,
 165 create an item as a raw "blob" of the given size. Unlike fw_cfg_add_bytes()
 166 above, the next available selector key (above 0x0020, FW_CFG_FILE_FIRST)
 167 will 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
 169 assigned selector key value. The data referenced by the starting pointer
 170 is only linked, NOT copied, into the fw_cfg data structure.
 171
 172 == fw_cfg_add_file_callback() ==
 173
 174 Like fw_cfg_add_file(), but additionally sets pointers to a callback
 175 function (and opaque argument), which will be executed host-side by
 176 QEMU each time a byte is read by the guest from this particular item.
 177
 178 NOTE: The callback function is given the opaque argument set by
 179 fw_cfg_add_file_callback(), but also the current data offset,
 180 allowing it the option of only acting upon specific offset values
 181 (e.g., 0, before the first data byte of the selected item is
 182 returned to the guest).
 183
 184 == fw_cfg_modify_file() ==
 185
 186 Given a filename (i.e., fw_cfg item name), starting pointer, and size,
 187 completely replace the configuration item referenced by the given item
 188 name with the new given blob. If an existing blob is found, its
 189 callback information is removed, and a pointer to the old data is
 190 returned to allow the caller to free it, helping avoid memory leaks.
 191 If a configuration item does not already exist under the given item
 192 name, a new item will be created as with fw_cfg_add_file(), and NULL
 193 is returned to the caller. In any case, the data referenced by the
 194 starting pointer is only linked, NOT copied, into the fw_cfg data
 195 structure.
 196
 197 == fw_cfg_add_callback() ==
 198
 199 Like fw_cfg_add_bytes(), but additionally sets pointers to a callback
 200 function (and opaque argument), which will be executed host-side by
 201 QEMU each time a guest-side write operation to this particular item
 202 completes fully overwriting the item's data.
 203
 204 NOTE: This function is deprecated, and will be completely removed
 205 starting with QEMU v2.4.
 206
 207 == Externally Provided Items ==
 208
 209 As of v2.4, "file" fw_cfg items (i.e., items with selector keys above
 210 FW_CFG_FILE_FIRST, and with a corresponding entry in the fw_cfg file
 211 directory structure) may be inserted via the QEMU command line, using
 212 the following syntax:
 213
 214     -fw_cfg [name=]<item_name>,file=<path>
 215
 216 where <item_name> is the fw_cfg item name, and <path> is the location
 217 on the host file system of a file containing the data to be inserted.
 218
 219 NOTE: Users *SHOULD* choose item names beginning with the prefix "opt/"
 220 when using the "-fw_cfg" command line option, to avoid conflicting with
 221 item names used internally by QEMU. For instance:
 222
 223     -fw_cfg name=opt/my_item_name,file=./my_blob.bin
 224
 225 Similarly, QEMU developers *SHOULD NOT* use item names prefixed with
 226 "opt/" when inserting items programmatically, e.g. via fw_cfg_add_file().