.../reqs/design-reqs/arm64/generic-timer.rst | 24 ++++++++++++++++++- docs/fusa/reqs/intro.rst | 10 ++++++++ 2 files changed, 33 insertions(+), 1 deletion(-)
From: Michal Orzel <michal.orzel@amd.com>
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@amd.com>
Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@amd.com>
---
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.
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
--
2.25.1Hi, On 11/09/2024 10:44, Ayan Kumar Halder wrote: > From: Michal Orzel <michal.orzel@amd.com> > > 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@amd.com> > Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@amd.com> > --- > 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
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@amd.com> >> >> 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@amd.com> >> Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@amd.com> >> --- >> 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
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@amd.com> >>> >>> 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@amd.com> >>> Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@amd.com> >>> --- >>> 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@amazon.com> Cheers, -- Julien Grall
© 2016 - 2025 Red Hat, Inc.