Re: [PATCH v2] docs: fusa: Add requirements for emulated uart

[Bertrand Marquis <Bertrand.Marquis@xxxxxxx>]

Hi Ayan,

> On 17 Sep 2024, at 15:13, Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx> wrote:
> 
> From: Michal Orzel <michal.orzel@xxxxxxx>
> 
> Add the requirements for emulated SBSA UART.
> 
> Signed-off-by: Michal Orzel <michal.orzel@xxxxxxx>
> Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>

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

Cheers
Bertrand

> ---
> Changes from :-
> 
> v1 - 1. Reworded the requirements to remove any ambiguity.
> 2. Dopped the "virtualization unaware VMs" requirement as it is not easy to
> define "virtualization unaware".
> 
> .../fusa/reqs/design-reqs/arm64/sbsa-uart.rst | 224 ++++++++++++++++++
> docs/fusa/reqs/market-reqs/reqs.rst           |  15 ++
> docs/fusa/reqs/product-reqs/arm64/reqs.rst    |  19 ++
> 3 files changed, 258 insertions(+)
> create mode 100644 docs/fusa/reqs/design-reqs/arm64/sbsa-uart.rst
> 
> diff --git a/docs/fusa/reqs/design-reqs/arm64/sbsa-uart.rst 
> b/docs/fusa/reqs/design-reqs/arm64/sbsa-uart.rst
> new file mode 100644
> index 0000000000..89598fa8a5
> --- /dev/null
> +++ b/docs/fusa/reqs/design-reqs/arm64/sbsa-uart.rst
> @@ -0,0 +1,224 @@
> +.. SPDX-License-Identifier: CC-BY-4.0
> +
> +SBSA 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 from a domain
> +---------------------------------------------
> +
> +`XenSwdgn~arm64_uart_probe_dt~1`
> +
> +Description:
> +Xen shall generate a device tree node for the SBSA UART (in accordance to Arm
> +SBSA UART device tree binding [2]) in the domain device tree.
> +
> +Rationale:
> +
> +Comments:
> +Domains can detect the presence of the SBSA UART device tree node.
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Transmit data in software polling mode
> +--------------------------------------
> +
> +`XenSwdgn~arm64_uart_transmit_data_poll_mode~1`
> +
> +Description:
> +Xen shall support transmission of data in polling mode.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Transmit data in interrupt driven mode
> +--------------------------------------
> +
> +`XenSwdgn~arm64_uart_transmit_data_interrupt_mode~1`
> +
> +Description:
> +Xen shall support transmission of 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:
> +Xen shall support reception of data in polling mode.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Receive data in interrupt driven mode
> +-------------------------------------
> +
> +`XenSwdgn~arm64_uart_receive_data_interrupt_mode~1`
> +
> +Description:
> +Xen shall support reception of data in interrupt driven mode.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART data register
> +-------------------------
> +
> +`XenSwdgn~arm64_uart_access_data_register~1`
> +
> +Description:
> +Xen shall emulate the UARTDR register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART receive status register
> +-----------------------------------
> +
> +`XenSwdgn~arm64_uart_access_receive_status_register~1`
> +
> +Description:
> +Xen shall emulate the UARTRSR register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART flag register
> +-------------------------
> +
> +`XenSwdgn~arm64_uart_access_flag_register~1`
> +
> +Description:
> +Xen shall emulate the UARTFR register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART mask set/clear register
> +-----------------------------------
> +
> +`XenSwdgn~arm64_uart_access_mask_register~1`
> +
> +Description:
> +Xen shall emulate the UARTIMSC register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART raw interrupt status register
> +-----------------------------------------
> +
> +`XenSwdgn~arm64_uart_access_raw_interrupt_status_register~1`
> +
> +Description:
> +Xen shall emulate the UARTRIS register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART masked interrupt status register
> +--------------------------------------------
> +
> +`XenSwdgn~arm64_uart_access_mask_irq_status_register~1`
> +
> +Description:
> +Xen shall emulate the UARTMIS register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Access UART interrupt clear register
> +------------------------------------
> +
> +`XenSwdgn~arm64_uart_access_irq_clear_register~1`
> +
> +Description:
> +Xen shall emulate the UARTICR register.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Receive UART TX interrupt
> +-------------------------
> +
> +`XenSwdgn~arm64_uart_receive_tx_irq~1`
> +
> +Description:
> +Xen shall generate UART interrupt when the UART transmit interrupt condition 
> is
> +met.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenProd~emulated_uart~1`
> +
> +Receive UART RX interrupt reception
> +-----------------------------------
> +
> +`XenSwdgn~arm64_uart_receive_rx_irq~1`
> +
> +Description:
> +Xen shall generate UART interrupt when the UART receive interrupt condition 
> is
> +met.
> +
> +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
> \ No newline at end of file
> diff --git a/docs/fusa/reqs/market-reqs/reqs.rst 
> b/docs/fusa/reqs/market-reqs/reqs.rst
> index 9c98c84a9a..e98f348cf4 100644
> --- a/docs/fusa/reqs/market-reqs/reqs.rst
> +++ b/docs/fusa/reqs/market-reqs/reqs.rst
> @@ -32,3 +32,18 @@ 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
> \ No newline at end of file
> diff --git a/docs/fusa/reqs/product-reqs/arm64/reqs.rst 
> b/docs/fusa/reqs/product-reqs/arm64/reqs.rst
> index 7aa3eeab6a..97e90813ec 100644
> --- a/docs/fusa/reqs/product-reqs/arm64/reqs.rst
> +++ b/docs/fusa/reqs/product-reqs/arm64/reqs.rst
> @@ -21,3 +21,22 @@ Covers:
> 
> Needs:
>  - XenSwdgn
> +
> +Emulated UART
> +-------------
> +
> +`XenProd~emulated_uart~1`
> +
> +Description:
> +Xen shall provide an "Arm SBSA UART" compliant device to the domains.
> +
> +Rationale:
> +
> +Comments:
> +
> +Covers:
> + - `XenMkt~run_arm64_vms~1`
> + - `XenMkt~provide_console_vms~1`
> +
> +Needs:
> + - XenSwdgn
> \ No newline at end of file
> -- 
> 2.25.1
>