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

[Ayan Kumar Halder <ayankuma@xxxxxxx>]

On 11/09/2024 10:55, Julien Grall wrote:
> Hi,
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.
Yes, I will explain this in the commit message. Does the following sound 
fine ?
```

docs: fusa: Add Assumption of Use (AoU)

AoU are the assumptions that 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.

Also, fixed a requirement to denote that Xen shall **not** expose the 
system counter frequency via the "clock-frequency" device tree property. 
The reason being the device tree documentation strongly discourages the 
use of this peoperty. Further if the "clock-frequency" is exposed, then 
it overrides the value programmed in the CNTFRQ_EL0 register.
So, the frequency shall be exposed via the CNTFRQ_EL0 register only and 
consequently there is an assumption on the platform to program the 
register correctly.
```

- Ayan