Documentation/devicetree/bindings/arm/fw-cfg.txt

   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 };