[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH v4] docs: fusa: Add Assumption of Use (AOU)


  • To: <xen-devel@xxxxxxxxxxxxxxxxxxxx>, <michal.orzel@xxxxxxx>, <ayan.kumar.halder@xxxxxxx>
  • From: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
  • Date: Tue, 24 Sep 2024 09:29:23 +0100
  • Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 165.204.84.17) smtp.rcpttodomain=lists.xenproject.org smtp.mailfrom=amd.com; dmarc=pass (p=quarantine sp=quarantine pct=100) action=none header.from=amd.com; dkim=none (message not signed); arc=none (0)
  • Arc-message-signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector10001; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=SpOLUaNzGFCTaVTTwD6i3Axw0ar9IW+hLBSqeIRCplo=; b=id9mlw+lSYvRAZrKy3G6YJzMhQdD/BizQ5o/tcoXlKPQeA5/2e80F5SMRC+X2e1V33XRZvYoIWswtQlIAYIVH+RKyPqsdA7ZC+Pj6R8vhs9drXpEaq+/tKRpZfyG7wXK1YA+OU853a2x3o/80aOqqmmUPlJJ3SQOcQMxJDqwiB1nb7sxBRO0kCTP+OdH9W+x56i9fHzx33A7MCIE3fuJl1ZyAUnfYOIo0fKAsqpXSPeIw6/8Q6Xc0XdlbDb+xWC8qX+baslvPJOQxH/ALganKJ9ArzzrZDbhIsSqbQ1bAZqKLn9FJn8tFE5p97J03RIdDJmgQSkZ4lgZozgOeMT3Uw==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=r9KJDMmmWGtgEqodCs2W03DXlAHWH393OGrELxZvVixDGdnwlyw04vEPDO9lpga/lhp4vptVNuIFD/1KtKeUY023rlLhlxcH0WvMiFc6Y1kH27Re0gwfsJbkQPMrr2fyeOFRAYx2/+yedR1pMZeGjrP77zFScgq490vY0sC6+evqO1gfp3pzZLI0rDxOwsa0T1yDRxa1+LQF3Kt1N8auI7+aWt6kcNG4b5ioolk7qtVFqxAS10g7qIMARqvGl/R37LIFmorAeM1I0XANUMUvMQKgh1JqSN9kUCA2RZYdjE+dpmcJz8nSMVABjZBkWy/Gdtd0qpOz8pLbOyXhHyTCjw==
  • Cc: Stefano Stabellini <sstabellini@xxxxxxxxxx>, Bertrand Marquis <bertrand.marquis@xxxxxxx>, Artem Mygaiev <artem_mygaiev@xxxxxxxx>, "Hisao Munakata" <hisao.munakata.vt@xxxxxxxxxxx>, Julien Grall <jgrall@xxxxxxxxxx>
  • Delivery-date: Tue, 24 Sep 2024 08:29:42 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

From: Michal Orzel <michal.orzel@xxxxxxx>

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>
---
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.

v2 - 1. Reworded the commit message. Added R-b.

v3 - 1. Fixed the definition of AoU.

2. Simplified the description of "Expose system timer frequency via register"
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..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..48f70edab5 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 functional. 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
-- 
2.25.1




 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.