[PATCH 2/2] docs: fusa : reqs: Added a sample of requirements [DO_NOT_MERGE]

[Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>]

Added a sample of market, product and design requirements. This is to
help explain how we are writing the requirements and understand the
context of the first patch.
We will be sending these requirements for review in the subsequent
patches.

Please do not merge this patch.

Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
---
 .../reqs/design_reqs/arm64/emulated_uart.rst  | 240 ++++++++++++++++++
 .../reqs/design_reqs/arm64/generic_timer.rst  | 146 +++++++++++
 docs/fusa/reqs/design_reqs/xen_version.rst    | 207 +++++++++++++++
 docs/fusa/reqs/market_reqs/reqs.rst           |  77 ++++++
 docs/fusa/reqs/product_reqs/reqs.rst          |  64 +++++
 5 files changed, 734 insertions(+)
 create mode 100644 docs/fusa/reqs/design_reqs/arm64/emulated_uart.rst
 create mode 100644 docs/fusa/reqs/design_reqs/arm64/generic_timer.rst
 create mode 100644 docs/fusa/reqs/design_reqs/xen_version.rst
 create mode 100644 docs/fusa/reqs/market_reqs/reqs.rst
 create mode 100644 docs/fusa/reqs/product_reqs/reqs.rst

diff --git a/docs/fusa/reqs/design_reqs/arm64/emulated_uart.rst 
b/docs/fusa/reqs/design_reqs/arm64/emulated_uart.rst
new file mode 100644
index 0000000000..483db92fa8
--- /dev/null
+++ b/docs/fusa/reqs/design_reqs/arm64/emulated_uart.rst
@@ -0,0 +1,240 @@
+UART
+====
+
+The following are the requirements related to SBSA UART [1] emulated and
+exposed by Xen to Arm64 domains.
+
+Probe the UART device tree node
+-------------------------------
+
+`XenSwdgn~arm64_uart_probe_dt_node~1`
+
+Description:
+Xen shall generate a device tree node for the SBSA UART (in accordance to Arm
+SBSA UART device tree binding [2]) to allow domains to probe it.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Transmit data in software polling mode
+--------------------------------------
+
+`XenSwdgn~arm64_uart_transmit_data_poll_mode~1`
+
+Description:
+Domain shall transmit data in polling mode (i.e. without involving interrupts).
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Transmit data in interrupt driven mode
+--------------------------------------
+
+`XenSwdgn~arm64_uart_transmit_data_irq_mode~1`
+
+Description:
+Domain shall transmit data in interrupt driven mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Receive data in software polling mode
+-------------------------------------
+
+`XenSwdgn~arm64_uart_receive_data_polling_mode~1`
+
+Description:
+Domain shall receive data in polling mode (i.e. without involving interrupts).
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Receive data in interrupt driven mode
+-------------------------------------
+
+`XenSwdgn~arm64_uart_receive_data_interrupt_driven_mode~1`
+
+Description:
+Domain shall receive data in interrupt driven mode.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART data register
+-------------------------
+
+`XenSwdgn~arm64_uart_access_data_register~1`
+
+Description:
+Domain shall access (read/write) UART data register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART receive status register
+-----------------------------------
+
+`XenSwdgn~arm64_uart_access_receive_status_register~1`
+
+Description:
+Domain shall access (read/write) UART receive status register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART flag register
+-------------------------
+
+`XenSwdgn~arm64_uart_access_flag_register~1`
+
+Description:
+Domain shall access (read only) UART flag register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART mask set/clear register
+-----------------------------------
+
+`XenSwdgn~arm64_uart_access_mask_register~1`
+
+Description:
+Domain shall access (read/write) UART mask set/clear register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART raw interrupt status register
+-----------------------------------------
+
+`XenSwdgn~arm64_uart_access_raw_interrupt_status_register~1`
+
+Description:
+Domain shall access (read only) UART raw interrupt status register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART masked interrupt status register
+--------------------------------------------
+
+`XenSwdgn~arm64_uart_access_mask_irq_status_register~1`
+
+Description:
+Domain shall access (read only) UART masked interrupt status register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Access UART interrupt clear register
+------------------------------------
+
+`XenSwdgn~arm64_uart_access_irq_clear_register~1`
+
+Description:
+Domain shall access (write only) UART interrupt clear register.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Receive UART TX interrupt
+-------------------------
+
+`XenSwdgn~arm64_uart_receive_tx_irq~1`
+
+Description:
+Domain shall receive UART TX interrupt
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Receive UART RX interrupt reception
+-----------------------------------
+
+`XenSwdgn~arm64_uart_receive_rx_irq~1`
+
+Description:
+Domain shall receive UART RX interrupt
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+Initial State
+=============
+
+Access UART in an initial (reset) state
+---------------------------------------
+
+`XenSwdgn~arm64_uart_access_reset_state~1`
+
+Description:
+Domain shall be given the access to the UART in a state, where all registers
+hold the reset value according to the specification [3] (only for registers
+implemented as part of SBSA UART).
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_uart~1`
+
+| [1] Arm Base System Architecture, chapter B
+| [2] 
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/serial/arm_sbsa_uart.txt
+| [3] PrimeCell UART (PL011)
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..00228448a3
--- /dev/null
+++ b/docs/fusa/reqs/design_reqs/arm64/generic_timer.rst
@@ -0,0 +1,146 @@
+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_probe_generic_timer_dt~1`
+
+Description:
+Xen shall generate a device tree node for the Generic Timer (in accordance to
+ARM architected timer device tree binding [2]) to allow domains to probe it.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Read system counter frequency
+-----------------------------
+
+`XenSwdgn~arm64_read_system_counter_freq~1`
+
+Description:
+Domain shall read the frequency of the system counter (either via CNTFRQ_EL0
+register or "clock-frequency" device tree property if present).
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Access CNTKCTL_EL1 system register from a domain
+------------------------------------------------
+
+`XenSwdgn~arm64_access_cntkctl_el1_system_register~1`
+
+Description:
+Domain shall access the counter-timer kernel control register to allow
+controlling the access to the timer from userspace (EL0).
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Access virtual timer from a domain
+----------------------------------
+
+`XenSwdgn~arm64_access_virtual_timer~1`
+
+Description:
+Domain shall access and make use of the virtual timer by accessing the 
following
+system registers:
+CNTVCT_EL0,
+CNTV_CTL_EL0,
+CNTV_CVAL_EL0,
+CNTV_TVAL_EL0.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Access physical timer from a domain
+-----------------------------------
+
+`XenSwdgn~arm64_access_physical_timer~1`
+
+Description:
+Domain shall access and make use of the physical timer by accessing the
+following system registers:
+CNTPCT_EL0,
+CNTP_CTL_EL0,
+CNTP_CVAL_EL0,
+CNTP_TVAL_EL0.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Trigger the virtual timer interrupt from a domain
+-------------------------------------------------
+
+`XenSwdgn~arm64_trigger_virtual_timer_interrupt~1`
+
+Description:
+Domain shall program the virtual timer to generate the interrupt when the
+asserted condition is met.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Trigger the physical timer interrupt from a domain
+--------------------------------------------------
+
+`XenSwdgn~arm64_trigger_physical_timer_interrupt~1`
+
+Description:
+Domain shall program the physical timer to generate the interrupt when the
+asserted condition is met.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
+
+Assumption of Use on the Firmware
+=================================
+
+Expose system timer frequency
+-----------------------------
+
+`XenSwdgn~arm64_program_cntfrq_el0_or_dt_prop_system_timer_freq~1`
+
+Description:
+Underlying firmware shall program CNTFRQ_EL0 with the system timer frequency.
+As an alternative, "clock-frequency" dt property (in the host device tree) can
+also be used to specify the system timer frequency. This helps in case of buggy
+firmware when CNTFRQ_EL0 is programmed incorrectly or not programmed at all.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~emulated_timer~1`
diff --git a/docs/fusa/reqs/design_reqs/xen_version.rst 
b/docs/fusa/reqs/design_reqs/xen_version.rst
new file mode 100644
index 0000000000..c5c58bb2df
--- /dev/null
+++ b/docs/fusa/reqs/design_reqs/xen_version.rst
@@ -0,0 +1,207 @@
+Hypercall xen_version
+=====================
+
+The following are the requirements related to __HYPERVISOR_xen_version 
hypercall
+[1] exposed by Xen to Arm64 and AMD64 PVH domains.
+
+Access hypercall __HYPERVISOR_xen_version for getting xen version
+-----------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_read_ver~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_version
+as a command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Validate the xen version returned by the XENVER_version command
+---------------------------------------------------------------
+
+`XenSwdgn~validate_version_hyp_xen_version~1`
+
+Description:
+The xen version returned should correspond to 4.18.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting xen extraversion
+----------------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_extraversion~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_extraversion as a
+command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting compile information
+-------------------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_compile_info~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_compile_info as a
+command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting capabilities
+------------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_capabilities~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_capabilities as a
+command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Validate the capabilities returned by XENVER_capabilities command
+-----------------------------------------------------------------
+
+`XenSwdgn~validate_cap_return_xenver_capabilities~1`
+
+Description:
+For Arm64, the capabilities returned should be xen-*-aarch64 string.
+For AMD64 PVH, the capabilities returned should be hvm-*-x86_64 string.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting changeset
+---------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_changeset~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_changeset
+as a command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting features
+--------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_features~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_get_features as a
+command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Check supported features returned by the XENVER_get_features command when the 
submap index passed is 0
+------------------------------------------------------------------------------------------------------
+
+`XenSwdgn~check_supported_features_xenver_get_features~1`
+
+Description:
+For Arm64, the bit position corresponding to the supported features should be 
1.
+Examples of Arm64 supported features:
+
+ * XENFEAT_ARM_SMCCC_supported
+
+For AMD64 PVH, the bit positions corresponding to the supported features should
+be 1.
+Examples of AMD64 PVH supported features:
+
+ * XENFEAT_memory_op_vnode_supported
+ * XENFEAT_vcpu_time_phys_area
+ * XENFEAT_runstate_phys_area
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting guest handle
+------------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_guest_handle~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_guest_handle as a
+command.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Access hypercall __HYPERVISOR_xen_version for getting xen pagesize
+------------------------------------------------------------------
+
+`XenSwdgn~access_hyp_xen_version_get_xen_pagesize~1`
+
+Description:
+Domain shall access __HYPERVISOR_xen_version passing XENVER_pagesize
+as a command and NULL as the guest handle.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+Validate the page size returned by XENVER_pagesize command
+----------------------------------------------------------
+
+`XenSwdgn~validate_page_size_xenver_pagesize_cmd~1`
+
+Description:
+The returned page size should be 4KB.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenProd~version_hypercall~1`
+
+| [1] 
https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=xen/include/public/version.h;hb=HEAD
diff --git a/docs/fusa/reqs/market_reqs/reqs.rst 
b/docs/fusa/reqs/market_reqs/reqs.rst
new file mode 100644
index 0000000000..a3f84cd503
--- /dev/null
+++ b/docs/fusa/reqs/market_reqs/reqs.rst
@@ -0,0 +1,77 @@
+Functional Requirements
+=======================
+
+Run Arm64 VMs
+-------------
+
+`XenMkt~run_arm64_vms~1`
+
+Description:
+Xen shall run Arm64 VMs.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
+
+Run AMD-x86 VMs
+---------------
+
+`XenMkt~run_x86_vms~1`
+
+Description:
+Xen shall run AMD-x86 VMs.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
+
+Support non paravirtualised VMs
+-------------------------------
+
+`XenMkt~non_pv_vms_support~1`
+
+Description:
+Xen shall support running guests which are not virtualisation aware.
+
+Rationale:
+
+Comments:
+
+Needs:
+ - XenProd
+
+Provide console to the VMs
+--------------------------
+
+`XenMkt~provide_console_vms~1`
+
+Description:
+Xen shall provide a console to a VM.
+
+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/reqs.rst 
b/docs/fusa/reqs/product_reqs/reqs.rst
new file mode 100644
index 0000000000..9954b7532a
--- /dev/null
+++ b/docs/fusa/reqs/product_reqs/reqs.rst
@@ -0,0 +1,64 @@
+Domain Creation And Runtime
+===========================
+
+Emulated UART
+-------------
+
+`XenProd~emulated_uart~1`
+
+Description:
+Xen shall emulate Arm SBSA UART on behalf of the domains.
+
+Rationale:
+
+Comments:
+The domains can use it to write/read to/from the console.
+
+Covers:
+ - `XenMkt~run_arm64_vms~1`
+ - `XenMkt~non_pv_vms_support~1`
+ - `XenMkt~provide_console_vms~1`
+
+Needs:
+ - XenSwdgn
+
+Emulated Timer
+--------------
+
+`XenProd~emulated_timer~1`
+
+Description:
+Xen shall emulate Arm Generic Timer timer on behalf of domains.
+
+Rationale:
+
+Comments:
+The domains can use it for e.g. scheduling.
+
+Covers:
+ - `XenMkt~run_arm64_vms~1`
+ - `XenMkt~non_pv_vms_support~1`
+ - `XenMkt~provide_timer_vms~1`
+
+Needs:
+ - XenSwdgn
+
+Version Hypercall
+-----------------
+
+`XenProd~version_hypercall~1`
+
+Description:
+Xen shall provide an interface to expose Xen version, type and compile
+information.
+
+Rationale:
+
+Comments:
+
+Covers:
+ - `XenMkt~run_arm64_vms~1`
+ - `XenMkt~run_x86_vms~1`
+
+Needs:
+ - XenSwdgn
-- 
2.25.1