xref: /openbmc/qemu/docs/specs/fw_cfg.rst (revision ab1b2ba9)
1===========================================
2QEMU Firmware Configuration (fw_cfg) Device
3===========================================
4
5Guest-side Hardware Interface
6=============================
7
8This hardware interface allows the guest to retrieve various data items
9(blobs) that can influence how the firmware configures itself, or may
10contain tables to be installed for the guest OS. Examples include device
11boot order, ACPI and SMBIOS tables, virtual machine UUID, SMP and NUMA
12information, kernel/initrd images for direct (Linux) kernel booting, etc.
13
14Selector (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
22A write to this register sets the index of a firmware configuration
23item which can subsequently be accessed via the data register.
24
25Setting the selector register will cause the data offset to be set
26to zero. The data offset impacts which data is accessed via the data
27register, and is explained below.
28
29Bit14 of the selector register indicates whether the configuration
30setting is being written. A value of 0 means the item is only being
31read, and all write access to the data port will be ignored. A value
32of 1 means the item's data can be overwritten by writes to the data
33register. In other words, configuration write mode is enabled when
34the 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
45Bit15 of the selector register indicates whether the configuration
46setting is architecture specific. A value of 0 means the item is a
47generic configuration item. A value of 1 means the item is specific
48to a particular architecture. In other words, generic configuration
49items are accessed with a selector value between 0x0000-0x7fff, and
50architecture specific configuration items are accessed with a selector
51value between 0x8000-0xffff.
52
53Data Register
54-------------
55
56* Read/Write (writes ignored as of QEMU v2.4, but see the DMA interface)
57* Location: platform dependent (IOport [#]_ or MMIO)
58* Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO)
59* Endianness: string-preserving
60
61.. [#]
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
67The data register allows access to an array of bytes for each firmware
68configuration data item. The specific item is selected by writing to
69the selector register, as described above.
70
71Initially following a write to the selector register, the data offset
72will be set to zero. Each successful access to the data register will
73increment the data offset by the appropriate access width.
74
75Each firmware configuration item has a maximum length of data
76associated with the item. After the data offset has passed the
77end of this maximum data length, then any reads will return a data
78value of 0x00, and all writes will be ignored.
79
80An N-byte wide read of the data register will return the next available
81N bytes of the selected firmware configuration item, as a substring, in
82increasing address order, similar to memcpy().
83
84Register Locations
85------------------
86
87x86, x86_64
88    * Selector Register IOport: 0x510
89    * Data Register IOport:     0x511
90    * DMA Address IOport:       0x514
91
92Arm
93    * Selector Register address: Base + 8 (2 bytes)
94    * Data Register address:     Base + 0 (8 bytes)
95    * DMA Address address:       Base + 16 (8 bytes)
96
97ACPI Interface
98--------------
99
100The fw_cfg device is defined with ACPI ID ``QEMU0002``. Since we expect
101ACPI tables to be passed into the guest through the fw_cfg device itself,
102the guest-side firmware can not use ACPI to find fw_cfg. However, once the
103firmware is finished setting up ACPI tables and hands control over to the
104guest kernel, the latter can use the fw_cfg ACPI node for a more accurate
105inventory of in-use IOport or MMIO regions.
106
107Firmware Configuration Items
108----------------------------
109
110Signature (Key 0x0000, ``FW_CFG_SIGNATURE``)
111~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112
113The presence of the fw_cfg selector and data registers can be verified
114by selecting the "signature" item using key 0x0000 (``FW_CFG_SIGNATURE``),
115and reading four bytes from the data register. If the fw_cfg device is
116present, the four bytes read will contain the characters ``QEMU``.
117
118If the DMA interface is available, then reading the DMA Address
119Register returns 0x51454d5520434647 (``QEMU CFG`` in big-endian format).
120
121Revision / feature bitmap (Key 0x0001, ``FW_CFG_ID``)
122~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123
124A 32-bit little-endian unsigned int, this item is used to check for enabled
125features.
126
127- Bit 0: traditional interface. Always set.
128- Bit 1: DMA interface.
129
130File Directory (Key 0x0019, ``FW_CFG_FILE_DIR``)
131~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
132
133.. highlight:: c
134
135Firmware configuration items stored at selector keys 0x0020 or higher
136(``FW_CFG_FILE_FIRST`` or higher) have an associated entry in a directory
137structure, which makes it easier for guest-side firmware to identify
138and retrieve them. The format of this file directory (from ``fw_cfg.h`` in
139the QEMU source tree) is shown here, slightly annotated for clarity::
140
141    struct FWCfgFiles {		/* the entire file directory fw_cfg item */
142        uint32_t count;		/* number of entries, in big-endian format */
143        struct FWCfgFile f[];	/* array of file entries, see below */
144    };
145
146    struct FWCfgFile {		/* an individual file entry, 64 bytes total */
147        uint32_t size;		/* size of referenced fw_cfg item, big-endian */
148        uint16_t select;	/* selector key of fw_cfg item, big-endian */
149        uint16_t reserved;
150        char name[56];		/* fw_cfg item name, NUL-terminated ascii */
151    };
152
153All Other Data Items
154~~~~~~~~~~~~~~~~~~~~
155
156Please consult the QEMU source for the most up-to-date and authoritative list
157of selector keys and their respective items' purpose, format and writeability.
158
159Ranges
160~~~~~~
161
162Theoretically, there may be up to 0x4000 generic firmware configuration
163items, and up to 0x4000 architecturally specific ones.
164
165===============  ===========
166Selector Reg.    Range Usage
167===============  ===========
1680x0000 - 0x3fff  Generic (0x0000 - 0x3fff, generally RO, possibly RW through
169                 the DMA interface in QEMU v2.9+)
1700x4000 - 0x7fff  Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+)
1710x8000 - 0xbfff  Arch. Specific (0x0000 - 0x3fff, generally RO, possibly RW
172                 through the DMA interface in QEMU v2.9+)
1730xc000 - 0xffff  Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+)
174===============  ===========
175
176In practice, the number of allowed firmware configuration items depends on the
177machine type/version.
178
179Guest-side DMA Interface
180========================
181
182If bit 1 of the feature bitmap is set, the DMA interface is present. This does
183not replace the existing fw_cfg interface, it is an add-on. This interface
184can be used through the 64-bit wide address register.
185
186The address register is in big-endian format. The value for the register is 0
187at startup and after an operation. A write to the least significant half (at
188offset 4) triggers an operation. This means that operations with 32-bit
189addresses can be triggered with just one write, whereas operations with
19064-bit addresses can be triggered with one 64-bit write or two 32-bit writes,
191starting with the most significant half (at offset 0).
192
193In this register, the physical address of a ``FWCfgDmaAccess`` structure in RAM
194should be written. This is the format of the ``FWCfgDmaAccess`` structure::
195
196    typedef struct FWCfgDmaAccess {
197        uint32_t control;
198        uint32_t length;
199        uint64_t address;
200    } FWCfgDmaAccess;
201
202The fields of the structure are in big endian mode, and the field at the lowest
203address is the ``control`` field.
204
205The ``control`` field has the following bits:
206
207- Bit 0: Error
208- Bit 1: Read
209- Bit 2: Skip
210- Bit 3: Select. The upper 16 bits are the selected index.
211- Bit 4: Write
212
213When an operation is triggered, if the ``control`` field has bit 3 set, the
214upper 16 bits are interpreted as an index of a firmware configuration item.
215This has the same effect as writing the selector register.
216
217If the ``control`` field has bit 1 set, a read operation will be performed.
218``length`` bytes for the current selector and offset will be copied into the
219physical RAM address specified by the ``address`` field.
220
221If the ``control`` field has bit 4 set (and not bit 1), a write operation will be
222performed. ``length`` bytes will be copied from the physical RAM address
223specified by the ``address`` field to the current selector and offset. QEMU
224prevents starting or finishing the write beyond the end of the item associated
225with the current selector (i.e., the item cannot be resized). Truncated writes
226are dropped entirely. Writes to read-only items are also rejected. All of these
227write errors set bit 0 (the error bit) in the ``control`` field.
228
229If the ``control`` field has bit 2 set (and neither bit 1 nor bit 4), a skip
230operation will be performed. The offset for the current selector will be
231advanced ``length`` bytes.
232
233To check the result, read the ``control`` field:
234
235Error bit set
236    Something went wrong.
237All bits cleared
238    Transfer finished successfully.
239Otherwise
240    Transfer still in progress
241    (doesn't happen today due to implementation not being async,
242    but may in the future).
243
244Externally Provided Items
245=========================
246
247Since v2.4, "file" fw_cfg items (i.e., items with selector keys above
248``FW_CFG_FILE_FIRST``, and with a corresponding entry in the fw_cfg file
249directory structure) may be inserted via the QEMU command line, using
250the following syntax::
251
252    -fw_cfg [name=]<item_name>,file=<path>
253
254Or::
255
256    -fw_cfg [name=]<item_name>,string=<string>
257
258Since v5.1, QEMU allows some objects to generate fw_cfg-specific content,
259the content is then associated with a "file" item using the 'gen_id' option
260in the command line, using the following syntax::
261
262    -object <generator-type>,id=<generated_id>,[generator-specific-options] \
263    -fw_cfg [name=]<item_name>,gen_id=<generated_id>
264
265See QEMU man page for more documentation.
266
267Using item_name with plain ASCII characters only is recommended.
268
269Item names beginning with ``opt/`` are reserved for users.  QEMU will
270never create entries with such names unless explicitly ordered by the
271user.
272
273To avoid clashes among different users, it is strongly recommended
274that you use names beginning with ``opt/RFQDN/``, where RFQDN is a reverse
275fully qualified domain name you control.  For instance, if SeaBIOS
276wanted to define additional names, the prefix ``opt/org.seabios/`` would
277be appropriate.
278
279For historical reasons, ``opt/ovmf/`` is reserved for OVMF firmware.
280
281Prefix ``opt/org.qemu/`` is reserved for QEMU itself.
282
283Use of names not beginning with ``opt/`` is potentially dangerous and
284entirely unsupported.  QEMU will warn if you try.
285
286Use of names not beginning with ``opt/`` is tolerated with 'gen_id' (that
287is, the warning is suppressed), but you must know exactly what you're
288doing.
289
290All externally provided fw_cfg items are read-only to the guest.
291