linux-user: arm: Remove ARM_cpsr and similar #defines
[qemu.git] / 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 DMA Address IOport:       0x514
80
81 === ARM Register Locations ===
82
83 Selector Register address: Base + 8 (2 bytes)
84 Data Register address:     Base + 0 (8 bytes)
85 DMA Address address:       Base + 16 (8 bytes)
86
87 == ACPI Interface ==
88
89 The fw_cfg device is defined with ACPI ID "QEMU0002". Since we expect
90 ACPI tables to be passed into the guest through the fw_cfg device itself,
91 the guest-side firmware can not use ACPI to find fw_cfg. However, once the
92 firmware is finished setting up ACPI tables and hands control over to the
93 guest kernel, the latter can use the fw_cfg ACPI node for a more accurate
94 inventory of in-use IOport or MMIO regions.
95
96 == Firmware Configuration Items ==
97
98 === Signature (Key 0x0000, FW_CFG_SIGNATURE) ===
99
100 The presence of the fw_cfg selector and data registers can be verified
101 by selecting the "signature" item using key 0x0000 (FW_CFG_SIGNATURE),
102 and reading four bytes from the data register. If the fw_cfg device is
103 present, the four bytes read will contain the characters "QEMU".
104
105 If the DMA interface is available, then reading the DMA Address
106 Register returns 0x51454d5520434647 ("QEMU CFG" in big-endian format).
107
108 === Revision / feature bitmap (Key 0x0001, FW_CFG_ID) ===
109
110 A 32-bit little-endian unsigned int, this item is used to check for enabled
111 features.
112  - Bit 0: traditional interface. Always set.
113  - Bit 1: DMA interface.
114
115 === File Directory (Key 0x0019, FW_CFG_FILE_DIR) ===
116
117 Firmware configuration items stored at selector keys 0x0020 or higher
118 (FW_CFG_FILE_FIRST or higher) have an associated entry in a directory
119 structure, which makes it easier for guest-side firmware to identify
120 and retrieve them. The format of this file directory (from fw_cfg.h in
121 the QEMU source tree) is shown here, slightly annotated for clarity:
122
123 struct FWCfgFiles {             /* the entire file directory fw_cfg item */
124     uint32_t count;             /* number of entries, in big-endian format */
125     struct FWCfgFile f[];       /* array of file entries, see below */
126 };
127
128 struct FWCfgFile {              /* an individual file entry, 64 bytes total */
129     uint32_t size;              /* size of referenced fw_cfg item, big-endian */
130     uint16_t select;            /* selector key of fw_cfg item, big-endian */
131     uint16_t reserved;
132     char name[56];              /* fw_cfg item name, NUL-terminated ascii */
133 };
134
135 === All Other Data Items ===
136
137 Please consult the QEMU source for the most up-to-date and authoritative
138 list of selector keys and their respective items' purpose and format.
139
140 === Ranges ===
141
142 Theoretically, there may be up to 0x4000 generic firmware configuration
143 items, and up to 0x4000 architecturally specific ones.
144
145 Selector Reg.    Range Usage
146 ---------------  -----------
147 0x0000 - 0x3fff  Generic (0x0000 - 0x3fff, RO)
148 0x4000 - 0x7fff  Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+)
149 0x8000 - 0xbfff  Arch. Specific (0x0000 - 0x3fff, RO)
150 0xc000 - 0xffff  Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+)
151
152 In practice, the number of allowed firmware configuration items is given
153 by the value of FW_CFG_MAX_ENTRY (see fw_cfg.h).
154
155 = Guest-side DMA Interface =
156
157 If bit 1 of the feature bitmap is set, the DMA interface is present. This does
158 not replace the existing fw_cfg interface, it is an add-on. This interface
159 can be used through the 64-bit wide address register.
160
161 The address register is in big-endian format. The value for the register is 0
162 at startup and after an operation. A write to the least significant half (at
163 offset 4) triggers an operation. This means that operations with 32-bit
164 addresses can be triggered with just one write, whereas operations with
165 64-bit addresses can be triggered with one 64-bit write or two 32-bit writes,
166 starting with the most significant half (at offset 0).
167
168 In this register, the physical address of a FWCfgDmaAccess structure in RAM
169 should be written. This is the format of the FWCfgDmaAccess structure:
170
171 typedef struct FWCfgDmaAccess {
172     uint32_t control;
173     uint32_t length;
174     uint64_t address;
175 } FWCfgDmaAccess;
176
177 The fields of the structure are in big endian mode, and the field at the lowest
178 address is the "control" field.
179
180 The "control" field has the following bits:
181  - Bit 0: Error
182  - Bit 1: Read
183  - Bit 2: Skip
184  - Bit 3: Select. The upper 16 bits are the selected index.
185
186 When an operation is triggered, if the "control" field has bit 3 set, the
187 upper 16 bits are interpreted as an index of a firmware configuration item.
188 This has the same effect as writing the selector register.
189
190 If the "control" field has bit 1 set, a read operation will be performed.
191 "length" bytes for the current selector and offset will be copied into the
192 physical RAM address specified by the "address" field.
193
194 If the "control" field has bit 2 set (and not bit 1), a skip operation will be
195 performed. The offset for the current selector will be advanced "length" bytes.
196
197 To check the result, read the "control" field:
198    error bit set        ->  something went wrong.
199    all bits cleared     ->  transfer finished successfully.
200    otherwise            ->  transfer still in progress (doesn't happen
201                             today due to implementation not being async,
202                             but may in the future).
203
204 = Externally Provided Items =
205
206 As of v2.4, "file" fw_cfg items (i.e., items with selector keys above
207 FW_CFG_FILE_FIRST, and with a corresponding entry in the fw_cfg file
208 directory structure) may be inserted via the QEMU command line, using
209 the following syntax:
210
211     -fw_cfg [name=]<item_name>,file=<path>
212
213 Or
214
215     -fw_cfg [name=]<item_name>,string=<string>
216
217 See QEMU man page for more documentation.
218
219 Using item_name with plain ASCII characters only is recommended.
220
221 Item names beginning with "opt/" are reserved for users.  QEMU will
222 never create entries with such names unless explicitly ordered by the
223 user.
224
225 To avoid clashes among different users, it is strongly recommended
226 that you use names beginning with opt/RFQDN/, where RFQDN is a reverse
227 fully qualified domain name you control.  For instance, if SeaBIOS
228 wanted to define additional names, the prefix "opt/org.seabios/" would
229 be appropriate.
230
231 For historical reasons, "opt/ovmf/" is reserved for OVMF firmware.
232
233 Prefix "opt/org.qemu/" is reserved for QEMU itself.
234
235 Use of names not beginning with "opt/" is potentially dangerous and
236 entirely unsupported.  QEMU will warn if you try.