Re: [PATCH v3 3/4] docs: sbsa: document platform version changes

[Peter Maydell]

On Wed, 24 May 2023 at 12:33, Marcin Juszkiewicz
<marcin.juszkiewicz@linaro.org> wrote:
>
> We plan to start adding more system information in DT so firmware does
> not have to use hardcoded values.
>
> Signed-off-by: Marcin Juszkiewicz <marcin.juszkiewicz@linaro.org>
> ---
>  docs/system/arm/sbsa.rst | 31 +++++++++++++++++++++++++------
>  1 file changed, 25 insertions(+), 6 deletions(-)
>
> diff --git a/docs/system/arm/sbsa.rst b/docs/system/arm/sbsa.rst
> index 016776aed8..922a29700d 100644
> --- a/docs/system/arm/sbsa.rst
> +++ b/docs/system/arm/sbsa.rst
> @@ -6,16 +6,35 @@ 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.

> +Platform versions
> +"""""""""""""""""

All this stuff about the DTB format isn't interesting to most
users, so we should put it at the bottom of the doc, below
the 'supported devices' part. Also, the subsection title should
be something like "Board-to-firmware interface", and it should
lead off with the text that clarifies that although the data
blob provided by the board is in DT format it is not intended
to be a complete compliant DT but is just a mechanism for
providing the firmware with specific information about the
non-discoverable components in the system.

> +
> +QEMU 7.1 brought support for "platform version major/minor" fields in
> +DeviceTree.

We don't generally document things in terms of which QEMU versions
they appeared in. The docs just say what the current status is.

> +
> +Version 0.0
> +'''''''''''
> +
> +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).
> +
> +Version 0.1
> +'''''''''''
> +
> +Additional data are provided in DT to the firmware:
> +  - address and size of GIC Distributor
> +  - address and size of GIC Redistributor
> +
> +Simple "/intc/reg" field is used.
> +
>  Supported devices
>  """""""""""""""""

thanks
-- PMM