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

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

[Marcin Juszkiewicz]

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

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

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

[Marcin Juszkiewicz]

W dniu 28.03.2024 o 16:43, Peter Maydell pisze:
> 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

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

Thanks, fixed.

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

This is a matter of what firmware stack QEMU user will run. TF-A (our 
current "guest EL3 firmware") passed devicetree to later components of 
the software stack. We just stopped using it in EDK2. But if someone 
would like to run U-Boot or other firmware then both SMC and DT will 
wait for them.

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

Done.

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

OK.