Re: [PATCH v2 1/1] docs: sbsa: update specs, add dt note

[Leif Lindholm]

On Thu, Mar 28, 2024 at 17:38:51 +0100, Marcin Juszkiewicz wrote:
> Hardware of sbsa-ref board is nowadays defined by both BSA and SBSA
> specifications. Then BBR defines firmware interface.
> 
> Added note about DeviceTree data passed from QEMU to firmware. It is
> very minimal and provides only data we use in firmware.
> 
> Added NUMA information to list of things reported by DeviceTree.
> 
> Signed-off-by: Marcin Juszkiewicz <marcin.juszkiewicz@linaro.org>

Reviewed-by: Leif Lindholm <quic_llindhol@quicinc.com>

Thanks!

/
     Leif

> ---
>  docs/system/arm/sbsa.rst | 35 ++++++++++++++++++++++++++---------
>  1 file changed, 26 insertions(+), 9 deletions(-)
> 
> diff --git a/docs/system/arm/sbsa.rst b/docs/system/arm/sbsa.rst
> index bca61608ff..2bf22a1d0b 100644
> --- a/docs/system/arm/sbsa.rst
> +++ b/docs/system/arm/sbsa.rst
> @@ -1,12 +1,16 @@
>  Arm Server Base System Architecture Reference board (``sbsa-ref``)
>  ==================================================================
>  
> -While the ``virt`` board is a generic board platform that doesn't match
> -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.
> +The ``sbsa-ref`` board intends to look like real hardware (while the ``virt``
> +board is a generic board platform that doesn't match any real hardware).
> +
> +The hardware part is defined by two specifications:
> +
> +  - `Base System Architecture 
> <https://developer.arm.com/documentation/den0094/>`__ (BSA)
> +  - `Server Base System Architecture 
> <https://developer.arm.com/documentation/den0029/>`__ (SBSA)
> +
> +The `Arm Base Boot Requirements 
> <https://developer.arm.com/documentation/den0044/>`__ (BBR)
> +specification defines how the firmware reports that to any operating system.
>  
>  It is intended to be a machine for developing firmware and testing
>  standards compliance with operating systems.
> @@ -35,16 +39,29 @@ 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).
>  
> +Note
> +''''
> +
> +QEMU provides the guest EL3 firmware with minimal information about hardware
> +platform using minimalistic devicetree. This is not a Linux devicetree. It is
> +not even a firmware devicetree.
> +
> +It is information passed from QEMU to describe the information a hardware
> +platform would have other mechanisms to discover at runtime, that are 
> affected
> +by the QEMU command line.
> +
> +Ultimately this devicetree may be replaced by IPC calls to an emulated SCP.
> +
>  DeviceTree information
>  ''''''''''''''''''''''
>  
> -The devicetree provided by the board model to the firmware is not intended
> -to be a complete compliant DT. It currently reports:
> +The devicetree reports:
>  
>     - CPUs
>     - memory
>     - platform version
>     - GIC addresses
> +   - NUMA node id for CPUs and memory
>  
>  Platform version
>  ''''''''''''''''
> @@ -70,4 +87,4 @@ Platform version changes:
>    GIC ITS information is present in devicetree.
>  
>  0.3
> -  The USB controller is an XHCI device, not EHCI
> +  The USB controller is an XHCI device, not EHCI.
> -- 
> 2.44.0
>