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

[Julien Grall <julien@xxxxxxx>]

Hi,

On 11/09/2024 10:44, Ayan Kumar Halder wrote:
> From: Michal Orzel <michal.orzel@xxxxxxx>
>
> AoU are the assumptions Xen relies on other components (eg platform, domains)
> 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>
> ---
> Changes from :-
>
> v1 - 1. Removed the part of requirement which states that Xen exposes the
> frequency of the system timer by reading the "clock-frequency" property.
>
> 2. Added a rationale for AoU.
>
> 3. Reworded the AoU.
>
>   .../reqs/design-reqs/arm64/generic-timer.rst  | 24 ++++++++++++++++++-
>   docs/fusa/reqs/intro.rst                      | 10 ++++++++
>   2 files changed, 33 insertions(+), 1 deletion(-)
>
> diff --git a/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst 
> b/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
> index f2a0cd7fb8..86d84a3c40 100644
> --- a/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
> +++ b/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
> @@ -30,7 +30,7 @@ Read system counter frequency
>   
>   Description:
>   Xen shall expose the frequency of the system counter to the domains in
> -CNTFRQ_EL0 register and/or domain device tree's "clock-frequency" property.
> +CNTFRQ_EL0 register.
This either wants to be split or explained in the commit message.

>   
>   Rationale:
>   
> @@ -116,6 +116,28 @@ Rationale:
>   
>   Comments:
>   
> +Covers:
> + - `XenProd~emulated_timer~1`
> +
> +Assumption of Use on the Platform
> +=================================
> +
> +Expose system timer frequency via register
> +------------------------------------------
> +
> +`XenSwdgn~arm64_generic_timer_plat_program_cntfrq_el0~1`
> +
> +Description:
> +Underlying platform shall program CNTFRQ_EL0 register with the value of system
> +timer frequency.
> +
> +Rationale:
> +Xen reads the CNTFRQ_EL0 register to get the value of system timer frequency.
> +While there is a provision to get this value by reading the "clock-frequency"
> +dt property [2], the use of this property is strongly discouraged.
> +
> +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,

--
Julien Grall