|
| 1 | +* QEMU Firmware Configuration bindings for ARM |
| 2 | + |
| 3 | +QEMU's arm-softmmu and aarch64-softmmu emulation / virtualization targets |
| 4 | +provide the following Firmware Configuration interface on the "virt" machine |
| 5 | +type: |
| 6 | + |
| 7 | +- A write-only, 16-bit wide selector (or control) register, |
| 8 | +- a read-write, 64-bit wide data register. |
| 9 | + |
| 10 | +QEMU exposes the control and data register to ARM guests as memory mapped |
| 11 | +registers; their location is communicated to the guest's UEFI firmware in the |
| 12 | +DTB that QEMU places at the bottom of the guest's DRAM. |
| 13 | + |
| 14 | +The guest writes a selector value (a key) to the selector register, and then |
| 15 | +can read the corresponding data (produced by QEMU) via the data register. If |
| 16 | +the selected entry is writable, the guest can rewrite it through the data |
| 17 | +register. |
| 18 | + |
| 19 | +The selector register takes keys in big endian byte order. |
| 20 | + |
| 21 | +The data register allows accesses with 8, 16, 32 and 64-bit width (only at |
| 22 | +offset 0 of the register). Accesses larger than a byte are interpreted as |
| 23 | +arrays, bundled together only for better performance. The bytes constituting |
| 24 | +such a word, in increasing address order, correspond to the bytes that would |
| 25 | +have been transferred by byte-wide accesses in chronological order. |
| 26 | + |
| 27 | +The interface allows guest firmware to download various parameters and blobs |
| 28 | +that affect how the firmware works and what tables it installs for the guest |
| 29 | +OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and |
| 30 | +initrd images for direct kernel booting, virtual machine UUID, SMP information, |
| 31 | +virtual NUMA topology, and so on. |
| 32 | + |
| 33 | +The authoritative registry of the valid selector values and their meanings is |
| 34 | +the QEMU source code; the structure of the data blobs corresponding to the |
| 35 | +individual key values is also defined in the QEMU source code. |
| 36 | + |
| 37 | +The presence of the registers can be verified by selecting the "signature" blob |
| 38 | +with key 0x0000, and reading four bytes from the data register. The returned |
| 39 | +signature is "QEMU". |
| 40 | + |
| 41 | +The outermost protocol (involving the write / read sequences of the control and |
| 42 | +data registers) is expected to be versioned, and/or described by feature bits. |
| 43 | +The interface revision / feature bitmap can be retrieved with key 0x0001. The |
| 44 | +blob to be read from the data register has size 4, and it is to be interpreted |
| 45 | +as a uint32_t value in little endian byte order. The current value |
| 46 | +(corresponding to the above outer protocol) is zero. |
| 47 | + |
| 48 | +The guest kernel is not expected to use these registers (although it is |
| 49 | +certainly allowed to); the device tree bindings are documented here because |
| 50 | +this is where device tree bindings reside in general. |
| 51 | + |
| 52 | +Required properties: |
| 53 | + |
| 54 | +- compatible: "qemu,fw-cfg-mmio". |
| 55 | + |
| 56 | +- reg: the MMIO region used by the device. |
| 57 | + * Bytes 0x0 to 0x7 cover the data register. |
| 58 | + * Bytes 0x8 to 0x9 cover the selector register. |
| 59 | + * Further registers may be appended to the region in case of future interface |
| 60 | + revisions / feature bits. |
| 61 | + |
| 62 | +Example: |
| 63 | + |
| 64 | +/ { |
| 65 | + #size-cells = <0x2>; |
| 66 | + #address-cells = <0x2>; |
| 67 | + |
| 68 | + fw-cfg@9020000 { |
| 69 | + compatible = "qemu,fw-cfg-mmio"; |
| 70 | + reg = <0x0 0x9020000 0x0 0xa>; |
| 71 | + }; |
| 72 | +}; |
0 commit comments