[xen staging] docs: fusa: Add Assumption of Use (AOU)

[patchbot@xxxxxxx]

commit f9ce66ea9d24aa8b26fcb2c18828caf314328ca3
Author:     Michal Orzel <michal.orzel@xxxxxxx>
AuthorDate: Tue Sep 24 09:29:23 2024 +0100
Commit:     Stefano Stabellini <stefano.stabellini@xxxxxxx>
CommitDate: Tue Oct 1 17:32:15 2024 -0700

    docs: fusa: Add Assumption of Use (AOU)
    
    AoU are the assumptions that Xen relies on other components (eg platform
    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.
    
    Signed-off-by: Michal Orzel <michal.orzel@xxxxxxx>
    Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
    Reviewed-by: Julien Grall <jgrall@xxxxxxxxxx>
    Reviewed-by: Bertrand Marquis <bertrand.marquis@xxxxxxx>
---
 docs/fusa/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..9d2a5a8085 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:
+CNTFRQ_EL0 register shall be programmed with the value of the system timer
+frequency.
+
+Rationale:
+Xen reads the CNTFRQ_EL0 register to get the value of system timer frequency.
+
+Comments:
+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.
+
 Covers:
  - `XenProd~emulated_timer~1`
 
diff --git a/docs/fusa/reqs/intro.rst b/docs/fusa/reqs/intro.rst
index 245a219ff2..d8b43f5785 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
+=================
+
+Xen is making several assumptions on the status of the platform or on some
+functions being present and operational. For example, Xen might assume that
+some registers are set.
+Anybody who wants to use Xen must validate that the platform it is used on
+(meaning the hardware and any software running before Xen like the firmware)
+fulfils all the AoU described by Xen.
+
 The following is the skeleton for a requirement.
 
 Title of the requirement
--
generated by git-patchbot for /home/xen/git/xen.git#staging