Re: [RFC PATCH] docs: add some notes on the sbsa-ref machine

[Leif Lindholm <leif@nuviainc.com>]

On Tue, Nov 03, 2020 at 10:47:10 +0000, Alex Bennée wrote:
> We should at least document what this machine is about.

Thanks!
(comments below)

> Cc: Graeme Gregory <graeme@nuviainc.com>
> Cc: Leif Lindholm <leif@nuviainc.com>
> Cc: Hongbo Zhang <hongbo.zhang@linaro.org>
> Cc: Shashi Mallela <shashi.mallela@linaro.org>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/system/arm/sbsa.rst   | 30 ++++++++++++++++++++++++++++++
>  docs/system/target-arm.rst |  1 +
>  2 files changed, 31 insertions(+)
>  create mode 100644 docs/system/arm/sbsa.rst
> 
> diff --git a/docs/system/arm/sbsa.rst b/docs/system/arm/sbsa.rst
> new file mode 100644
> index 0000000000..a47c9360de
> --- /dev/null
> +++ b/docs/system/arm/sbsa.rst
> @@ -0,0 +1,30 @@
> +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. It is a static system that
> +reports a very minimal DT to the firmware for command line input to
> +the firmware.

I think you mean the right thing, but ...
"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).
> +
> +It is intended to be a machine for developing firmware and testing
> +standards compliance with operating systems.
> +
> +Supported devices
> +"""""""""""""""""
> +
> +The sbsa-ref board supports:
> +
> +  - A configurable number of Cortex-A57 cpus
> +  - GIC version 3

The intent was always for sbsa-ref to be tracking SBSA development, so
I wonder whether we should be documenting specific versions of cpu and
gic (and then keep remembering to update the docs).
My short-term plan was to swap the a57 for "max", but
documentation-wise, could we just say "number of aarch64 cpus"?
Could we refer to the gic as "latest supported emulated"?

/
    Leif

> +  - System bus AHCI controller.
> +  - System bus EHCI controller.
> +  - CDROM and hard disc on AHCI bus.
> +  - E1000E ethernet card on PCIE bus.
> +  - VGA display adaptor on PCIE bus.
> +  - A generic SBSA watchdog device
> +
> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
> index fdcf25c237..9636f3fd00 100644
> --- a/docs/system/target-arm.rst
> +++ b/docs/system/target-arm.rst
> @@ -79,6 +79,7 @@ undocumented; you can get a complete list by running
>     arm/mps2
>     arm/musca
>     arm/realview
> +   arm/sbsa-ref
>     arm/versatile
>     arm/vexpress
>     arm/aspeed
> -- 
> 2.20.1
>