1. Patchew
  2. Xen
  3. View series

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

Ayan Kumar Halder posted 1 patch 2 months, 3 weeks ago
Patches applied successfully (tree, apply log)
git fetch https://gitlab.com/xen-project/patchew/xen tags/patchew/20240829113120.3980270-1-ayan.kumar.halder@amd.com
.../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
[PATCH v2] docs: fusa: Add requirements for generic timer
Posted by Ayan Kumar Halder 2 months, 3 weeks ago 
From: Michal Orzel <michal.orzel@amd.com>

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

Signed-off-by: Michal Orzel <michal.orzel@amd.com>
Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@amd.com>
Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>
---
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
Re: [PATCH v2] docs: fusa: Add requirements for generic timer
Posted by Bertrand Marquis 2 months, 3 weeks ago 
Hi Ayan,


> On 29 Aug 2024, at 13:31, Ayan Kumar Halder <ayan.kumar.halder@amd.com> wrote:
> 
> From: Michal Orzel <michal.orzel@amd.com>
> 
> Add the requirements for the use of generic timer by a domain
> 
> Signed-off-by: Michal Orzel <michal.orzel@amd.com>
> Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@amd.com>
> Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>

Reviewed-by: Bertrand Marquis <bertrand.marquis@arm.com>

Cheers
Bertrand

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

Patchew 2.1-devel-b67e4c2

© 2016 - 2024 Red Hat, Inc.