Re: [PATCH 1/1] docs: sbsa: document board to firmware interface

[Peter Maydell]

On Wed, 31 May 2023 at 18:18, Marcin Juszkiewicz
<marcin.juszkiewicz@linaro.org> wrote:
>
> 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>

I'm going to apply this to target-arm.next with this squashed in
to fix a few grammar/format nits and add some text from the comment
in the source file about the platform version part.

diff --git a/docs/system/arm/sbsa.rst b/docs/system/arm/sbsa.rst
index c5b3342b52f..f571fe645e7 100644
--- a/docs/system/arm/sbsa.rst
+++ b/docs/system/arm/sbsa.rst
@@ -28,19 +28,29 @@ The ``sbsa-ref`` board supports:

 Board to firmware interface
 """""""""""""""""""""""""""
-``sbsa-ref`` is a static system that reports a very minimal DeviceTree to the
+
+``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
+(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
-'''''''''''''''''''''''
+''''''''''''''''''''''

-Provided DeviceTree is not intended to be a complete compliant DT. Only
-minimal subset is provided:
+The devicetree provided by the board model to the firmware is not intended
+to be a complete compliant DT. It currently reports:

-   - cpus
+   - 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.

thanks
-- PMM