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

[Julien Grall <julien@xxxxxxx>]

On 11/09/2024 12:24, Ayan Kumar Halder wrote:
> 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.
> ```
LGTM

Reviewed-by: Julien Grall <jgrall@xxxxxxxxxx>

Cheers,

--
Julien Grall