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

[Julien Grall <julien@xxxxxxx>]

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 
invalid. This seems to contradict the Assumption of Use. Can you explain 
the difference?
> +
> +Rationale:
This seems to be a bit odd to have an empty section. Can you explain why?

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