docs: sbsa: document board to firmware interface

We plan to add more hardware information into DeviceTree to limit amount
of hardcoded values in firmware.

Signed-off-by: Marcin Juszkiewicz <marcin.juszkiewicz@linaro.org>
Message-id: 20230531171834.236569-1-marcin.juszkiewicz@linaro.org
[PMM: fix format nits, add text about platform version fields from
 a comment in the C source file]
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
This commit is contained in:
Marcin Juszkiewicz 2023-05-31 19:18:34 +02:00 committed by Peter Maydell
parent bd96e10071
commit ff49fb950d

View File

@ -6,12 +6,7 @@ any real hardware the ``sbsa-ref`` board intends to look like real
hardware. The `Server Base System Architecture
<https://developer.arm.com/documentation/den0029/latest>`_ defines a
minimum base line of hardware support and importantly how the firmware
reports that to any operating system. It is a static system that
reports a very minimal DT to the firmware for non-discoverable
information about components affected by the qemu command line (i.e.
cpus and memory). As a result it must have a firmware specifically
built to expect a certain hardware layout (as you would in a real
machine).
reports that to any operating system.
It is intended to be a machine for developing firmware and testing
standards compliance with operating systems.
@ -19,7 +14,7 @@ standards compliance with operating systems.
Supported devices
"""""""""""""""""
The sbsa-ref board supports:
The ``sbsa-ref`` board supports:
- A configurable number of AArch64 CPUs
- GIC version 3
@ -30,3 +25,32 @@ The sbsa-ref board supports:
- Bochs display adapter on PCIe bus
- A generic SBSA watchdog device
Board to firmware interface
"""""""""""""""""""""""""""
``sbsa-ref`` is a static system that reports a very minimal devicetree to the
firmware for non-discoverable information about system components. This
includes both internal hardware and parts affected by the qemu command line
(i.e. CPUs and memory). As a result it must have a firmware specifically built
to expect a certain hardware layout (as you would in a real machine).
DeviceTree information
''''''''''''''''''''''
The devicetree provided by the board model to the firmware is not intended
to be a complete compliant DT. It currently reports:
- CPUs
- memory
- platform version
- GIC addresses
The platform version is only for informing platform firmware about
what kind of ``sbsa-ref`` board it is running on. It is neither
a QEMU versioned machine type nor a reflection of the level of the
SBSA/SystemReady SR support provided.
The ``machine-version-major`` value is updated when changes breaking
fw compatibility are introduced. The ``machine-version-minor`` value
is updated when features are added that don't break fw compatibility.