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

[PATCH v2] docs: fusa: Add requirements for generic timer


  • To: <xen-devel@xxxxxxxxxxxxxxxxxxxx>
  • From: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
  • Date: Thu, 29 Aug 2024 12:31:20 +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=Gm2POMBECsGV7z8vdKZQvlwhA36fQr6aLBAeMcMvOw8=; b=atGIA5w3+z3PvRd8Oau1FSqjg1Z+ahCzOjJ3czvhMzA/GmuB/0jvg+KXdoLwikA+Nf4bhStyYS5CtMoJsmaV/J/33Fo/RaMftH8gXIsm0j2NS6v8Sj2ypvFuS4vnh/e/QaRsVSAWlJv2dDtqaccJ1vGS81Q+sMQDKp2JprGWrebQzCQvj+hZBeygLTVpSK9GlkJcRAqjIFF8wtc6MPQC67GI7SkqDBDAY7j/yfhrJvXHvP9Yu1AL4aulG6VanvkR3hO34OSQuHSt4kQ4f02jEcAVnjjHroCGWa6mPOLPB4mRU34grRwKR1nqnyIsp0mxg/kqxYRHqQGvYuD+NW97vw==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector10001; d=microsoft.com; cv=none; b=Kwou0QZukpW9/yeY/Nsv7JHn/yRwdHhOdDjruPmrEaAhKDytHil4H2+3yi9Mmx+S7a9mb1p72b9gALLG6B1u5EBTztxrOTxhYGNfO1bLihjFN4t+DTgcZNZF996GfIjUhsvI6A9NGOcV8m9hk1kLuD4K36y1VhKrE6J6vGiC4h2yKdAySGS22X58W+bMAWqlxZ2vtnDHHW/6KYWwdo1iJUWaD6S48peV443fcUR3zaMQRgrTzRRecuB6pRFgdkvtlC4CdT7lzkStljt6OtbSl/Jv008w4af0eMOq0GOsuFG3fyT0SjxDWtFBMJbVlNqUSVWIu0IkgPnmUemAmkyWrA==
  • Cc: Michal Orzel <michal.orzel@xxxxxxx>, Stefano Stabellini <sstabellini@xxxxxxxxxx>, Bertrand Marquis <bertrand.marquis@xxxxxxx>, "Ayan Kumar Halder" <ayan.kumar.halder@xxxxxxx>, Artem Mygaiev <artem_mygaiev@xxxxxxxx>, Hisao Munakata <hisao.munakata.vt@xxxxxxxxxxx>
  • Delivery-date: Thu, 29 Aug 2024 11:31:44 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>

From: Michal Orzel <michal.orzel@xxxxxxx>

Add the requirements for the use of generic timer by a domain

Signed-off-by: Michal Orzel <michal.orzel@xxxxxxx>
Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
---
Changes from -

v1 - 1. Fixed some wordings as suggested in v1.
2. Removed the comments which mentions Domain specific usage details.

 .../reqs/design-reqs/arm64/generic-timer.rst  | 123 ++++++++++++++++++
 docs/fusa/reqs/index.rst                      |   3 +
 docs/fusa/reqs/intro.rst                      |   3 +-
 docs/fusa/reqs/market-reqs/reqs.rst           |  34 +++++
 docs/fusa/reqs/product-reqs/arm64/reqs.rst    |  23 ++++
 5 files changed, 185 insertions(+), 1 deletion(-)
 create mode 100644 docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
 create mode 100644 docs/fusa/reqs/market-reqs/reqs.rst
 create mode 100644 docs/fusa/reqs/product-reqs/arm64/reqs.rst

diff --git a/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst 
b/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
new file mode 100644
index 0000000000..f2a0cd7fb8
--- /dev/null
+++ b/docs/fusa/reqs/design-reqs/arm64/generic-timer.rst
@@ -0,0 +1,123 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Generic Timer
+=============
+
+The following are the requirements related to ARM Generic Timer [1] interface
+exposed by Xen to Arm64 domains.
+
+Probe the Generic Timer device tree node from a domain
+------------------------------------------------------
+
+`XenSwdgn~arm64_generic_timer_probe_dt~1`
+
+Description:
+Xen shall generate a device tree node for the Generic Timer (in accordance to
+ARM architected timer device tree binding [2]) in the domain device tree.
+
+Rationale:
+
+Comments:
+Domains can detect the presence of the Generic Timer device tree node.
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Read system counter frequency
+-----------------------------
+
+`XenSwdgn~arm64_generic_timer_read_freq~1`
+
+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.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Access CNTKCTL_EL1 system register from a domain
+------------------------------------------------
+
+`XenSwdgn~arm64_generic_timer_access_cntkctlel1~1`
+
+Description:
+Xen shall expose Counter-timer Kernel Control register (CNTKCTL_EL1) to the
+domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Access virtual timer from a domain
+----------------------------------
+
+`XenSwdgn~arm64_generic_timer_access_virtual_timer~1`
+
+Description:
+Xen shall expose the virtual timer registers (CNTVCT_EL0, CNTV_CTL_EL0,
+CNTV_CVAL_EL0, CNTV_TVAL_EL0) to the domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Access physical timer from a domain
+-----------------------------------
+
+`XenSwdgn~arm64_generic_timer_access_physical_timer~1`
+
+Description:
+Xen shall expose physical timer registers (CNTPCT_EL0, CNTP_CTL_EL0,
+CNTP_CVAL_EL0, CNTP_TVAL_EL0) to the domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Trigger the virtual timer interrupt from a domain
+-------------------------------------------------
+
+`XenSwdgn~arm64_generic_timer_trigger_virtual_interrupt~1`
+
+Description:
+Xen shall generate virtual timer interrupts to domains when the virtual timer
+condition is met.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Trigger the physical timer interrupt from a domain
+--------------------------------------------------
+
+`XenSwdgn~arm64_generic_timer_trigger_physical_interrupt~1`
+
+Description:
+Xen shall generate physical timer interrupts to domains when the physical timer
+condition is met.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+[1] Arm Architecture Reference Manual for A-profile architecture, Chapter 11
+[2] 
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml
diff --git a/docs/fusa/reqs/index.rst b/docs/fusa/reqs/index.rst
index 78c02b1d9b..183f183b1f 100644
--- a/docs/fusa/reqs/index.rst
+++ b/docs/fusa/reqs/index.rst
@@ -7,3 +7,6 @@ Requirements documentation
    :maxdepth: 2
 
    intro
+   market-reqs
+   product-reqs
+   design-reqs/arm64
diff --git a/docs/fusa/reqs/intro.rst b/docs/fusa/reqs/intro.rst
index d67b18dd9f..245a219ff2 100644
--- a/docs/fusa/reqs/intro.rst
+++ b/docs/fusa/reqs/intro.rst
@@ -55,7 +55,8 @@ Title of the requirement
   be 'XenMkt', 'XenProd' or 'XenSwdgn' to denote market, product or design
   requirement.
   name - This denotes name of the requirement. In case of architecture specific
-  requirements, this starts with the architecture type (ie x86_64, arm64).
+  requirements, this starts with the architecture type (eg x86_64, arm64)
+  followed by component name (eg generic_timer) and action (eg read_xxx).
   revision number - This gets incremented each time the requirement is 
modified.
 
 
diff --git a/docs/fusa/reqs/market-reqs/reqs.rst 
b/docs/fusa/reqs/market-reqs/reqs.rst
new file mode 100644
index 0000000000..9c98c84a9a
--- /dev/null
+++ b/docs/fusa/reqs/market-reqs/reqs.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Functional Requirements
+=======================
+
+Run Arm64 VMs
+-------------
+
+`XenMkt~run_arm64_vms~1`
+
+Description:
+Xen shall run Arm64 VMs.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
+
+Provide timer to the VMs
+------------------------
+
+`XenMkt~provide_timer_vms~1`
+
+Description:
+Xen shall provide a timer to a VM.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
diff --git a/docs/fusa/reqs/product-reqs/arm64/reqs.rst 
b/docs/fusa/reqs/product-reqs/arm64/reqs.rst
new file mode 100644
index 0000000000..7aa3eeab6a
--- /dev/null
+++ b/docs/fusa/reqs/product-reqs/arm64/reqs.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Domain Creation And Runtime
+===========================
+
+Emulated Timer
+--------------
+
+`XenProd~emulated_timer~1`
+
+Description:
+Xen shall grant access to "Arm Generic Timer" for the domains.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_vms~1`
+ - `XenMkt~provide_timer_vms~1`
+
+Needs:
+ - XenSwdgn
-- 
2.25.1




 


Rackspace

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