Re: [PATCH] docs: fusa: Add Assumption of Use (AOU)

[Michal Orzel <michal.orzel@xxxxxxx>]

Hi Julien,

On 08/09/2024 23:05, Julien Grall wrote:
> 
> 
> Hi Ayan,
> 
> On 06/09/2024 11:13, Ayan Kumar Halder wrote:
>> From: Michal Orzel <michal.orzel@xxxxxxx>
>>
>> AOU are the assumptions Xen relies on other components (eg platform, domains)
> 
> Searching online, I think the abbrevition is AoU rather than AOU. This
> would also match how we abbreviate in Xen (IOW if we use a lower case
> letter from the expanded name, then the letter in the acronym is also
> lower case).
> 
>> to fulfill its requirements. In our case, platform means a combination of
>> hardware, firmware and bootloader.
>>
>> We have defined AOU in the intro.rst and added AOU for the generic timer.
>>
>> Signed-off-by: Michal Orzel <michal.orzel@xxxxxxx>
>> Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
>> ---
>>   .../reqs/design-reqs/arm64/generic-timer.rst  | 19 +++++++++++++++++++
>>   docs/fusa/reqs/intro.rst                      | 10 ++++++++++
>>   2 files changed, 29 insertions(+)
>>
>> diff --git a/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst 
>> b/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
>> index f2a0cd7fb8..9df87cf4e0 100644
>> --- a/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
>> +++ b/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
>> @@ -116,6 +116,25 @@ Rationale:
>>
>>   Comments:
>>
>> +Covers:
>> + - `XenProd~emulated_timer~1`
>> +
>> +Assumption of Use on the Platform
>> +=================================
>> +
>> +Expose system timer frequency via register
>> +------------------------------------------
>> +
>> +`XenSwdgn~arm64_generic_timer_pf_program_cntfrq_el0~1`
>> +
>> +Description:
>> +Underlying platform shall ensure that CNTFRQ_EL0 register contains the 
>> system
>> +timer frequency.
> 
> The wording in [1] (not yet merged) implies that CNTFRQ_EL0 may be
It is merged:
https://xenbits.xen.org/gitweb/?p=xen.git;a=commit;h=51ad2c57a2d21b583a5944a0dc21c709af022f3c

> invalid. This seems to contradict the Assumption of Use. Can you explain
> the difference?
The requirement you refer to is written from a domain perspective and is about 
Xen exposing the frequency
to domains via CNTFRQ and/or dt property. In case of a presence of dt property 
in the host dtb, Xen could for instance decide
to emulate CNTFRQ instead of relying on the domain to parse the dt at runtime.

The AoU on the platform (hw/firmware/bootloader) is written from Xen 
perspective and is about the platform
exposing the correct frequency via register. This is Xen expected behavior on 
the platform. In other words, the platform should
expose the correct frequency via register.

However, even if the frequency in the register is correct, the host dtb might 
still contain the "clock-frequency" property.
Even though it is stated in the bindings that this property is about overriding 
broken firmware (which in our case is not),
in real life scenarios, the property can still be there and can match the 
register. This is because the host dtb is created by the user, not platform.
Even in Linux dts base, you will find lots of examples of device trees with 
this property. How can Linux know if the firmware
has been fixed already or not? This is why we want to give possibility for a 
user *not* platform to provide a dt property.



> 
>> +
>> +Rationale:
> 
> This seems to be a bit odd to have an empty section. Can you explain why?
That's the format we decided to go with. It's been documented in 
docs/fusa/reqs/intro.rst.
While AFAICT it is not strictly required for OFT, in the future we can decide 
to write our own parser to
present the requirements in a nicer form that OFT exporter. Then, it will be 
easier for use if each
requirement defines the same fields (I agree it's a matter of opinion but 
that's what we decided to use).

> 
>> +
>> +Comments:
>> +
>>   Covers:
>>    - `XenProd~emulated_timer~1`
>>
>> diff --git a/docs/fusa/reqs/intro.rst b/docs/fusa/reqs/intro.rst
>> index 245a219ff2..aa85ff821c 100644
>> --- a/docs/fusa/reqs/intro.rst
>> +++ b/docs/fusa/reqs/intro.rst
>> @@ -38,6 +38,16 @@ The requirements are linked using OpenFastTrace
>>   OpenFastTrace parses through the requirements and generates a traceability
>>   report.
>>
>> +Assumption of Use
>> +=================
>> +
>> +To fulfill one or more design requirements, there may be underlying 
>> assumptions
>> +on one or more components that Xen interacts with directly or indirectly. 
>> For
>> +eg, there may be assumptions on the underlying platform (hardware + 
>> firmware +
>> +bootloader) to set certain registers, etc. The important thing here is that
>> +anyone who validates these requirements, need to consider the assumption on 
>> the
>> +other components.
>> +
>>   The following is the skeleton for a requirement.
>>
>>   Title of the requirement
> 
> Cheers,
> 
> [1]
> https://lore.kernel.org/all/20240829113120.3980270-1-ayan.kumar.halder@xxxxxxx/
> 
> --
> Julien Grall

~Michal