docs: fusa: Add requirements for generic timer
PATCH v2 1/1 docs: fusa: Add requirements for generic timer
From: Michal Orzel <[email protected]>
Add the requirements for the use of generic timer by a domain
Signed-off-by Michal Orzel <[email protected]>
Signed-off-by Ayan Kumar Halder <[email protected]>
Reviewed-by Stefano Stabellini <[email protected]>
---
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
docs/fusa/reqs/design-reqs/arm64/generic-timer.rst new file +123 -0
@@ -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
docs/fusa/reqs/index.rst +3 -0
@@ -7,3 +7,6 @@ Requirements documentation :maxdepth: 2 intro + market-reqs + product-reqs + design-reqs/arm64
docs/fusa/reqs/intro.rst +2 -1
@@ -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.
docs/fusa/reqs/market-reqs/reqs.rst new file +34 -0
@@ -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
docs/fusa/reqs/product-reqs/arm64/reqs.rst new file +23 -0
@@ -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
Signature · 1 line
2.25.1
Hi Ayan,
Quoted 9 lines · Ayan Kumar Halder
From: Michal Orzel <[email protected]>
Add the requirements for the use of generic timer by a domain
Signed-off-by Michal Orzel <[email protected]>Signed-off-by Ayan Kumar Halder <[email protected]>Reviewed-by Stefano Stabellini <[email protected]>
Reviewed-by Bertrand Marquis <[email protected]>
Cheers
Bertrand
Quoted 242 lines
---
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.rstcreate mode 100644docs/fusa/reqs/market-reqs/reqs.rstcreate mode 100644docs/fusa/reqs/product-reqs/arm64/reqs.rstdocs/fusa/reqs/design-reqs/arm64/generic-timer.rst new file +123
-0@@ -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.yamldocs/fusa/reqs/index.rst +3
-0@@ -7,3 +7,6 @@ Requirements documentation :maxdepth: 2 intro + market-reqs + product-reqs + design-reqs/arm64docs/fusa/reqs/intro.rst +2
-1@@ -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.docs/fusa/reqs/market-reqs/reqs.rst new file +34
-0@@ -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: + - XenProddocs/fusa/reqs/product-reqs/arm64/reqs.rst new file +23
-0@@ -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: + - XenSwdgnSignature · 1 line
2.25.1