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

[Peter Maydell]

On Tue, 26 Mar 2024 at 09:58, Marcin Juszkiewicz
<marcin.juszkiewicz@linaro.org> 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>
> ---
>  docs/system/arm/sbsa.rst | 37 ++++++++++++++++++++++++++++---------
>  1 file changed, 28 insertions(+), 9 deletions(-)
>
> diff --git a/docs/system/arm/sbsa.rst b/docs/system/arm/sbsa.rst
> index bca61608ff..d4d1f2efe3 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,31 @@ 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 us with minimal information about hardware platform using

s/us/the guest EL3 firmware/  (or whatever other term you want to
use to describe the guest software that reads the dt).

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


Might want to say also
 Guest EL3 firmware does not pass this devicetree on to later
 components of the software stack.
?

> +
> +Ultimately this devicetree will be replaced by IPC calls to an emulated SCP.
> +And when we do that, we won't then have to rewrite Normal world firmware to
> +cope.

I would drop the last sentence here, and use "may" instead of "will".

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

Otherwise looks good to me, and the updates to the spec URLs
are particularly helpful. As a docs change I'd be happy
to take it into 9.0 (at least before rc2) if some other
sbsa-ref-knowledgeable person wants to either review or ack it.
(But it's also OK if it misses 9.0 and goes into 9.1.)

thanks
-- PMM