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

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

[Marcin Juszkiewicz]

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>
---
 docs/system/arm/sbsa.rst | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/docs/system/arm/sbsa.rst b/docs/system/arm/sbsa.rst
index 016776aed8..c5b3342b52 100644
--- a/docs/system/arm/sbsa.rst
+++ b/docs/system/arm/sbsa.rst
@@ -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,22 @@ 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
+'''''''''''''''''''''''
+
+Provided DeviceTree is not intended to be a complete compliant DT. Only
+minimal subset is provided:
+
+   - cpus
+   - memory
+   - platform version
+   - GIC addresses
-- 
2.40.1

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

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

[Marcin Juszkiewicz]

W dniu 19.06.2023 o 14:41, Peter Maydell pisze:
> 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.

Thanks.

My English grammar sucks so I am glad that you looked and improved that 
text.