Skip to contentSkip to conversation

Introduce functional safety related documents

PATCH In review Ayan Kumar Halder 2 participants 5 messages Aug 6, 2024 – Sep 2, 2024

lore
Share & tools
lore
#0 lore raw

v3 cover Introduce functional safety related documents

Hi,

In the Xen summit, we presented an update on Xen Functional Safety. For details, please refer to
https://youtu.be/eFRTHSGDMfQ?si=sYOdYfDI7qsgkcjE ("Xen Functional Safety - an Update - Ayan Kumar Halder & Michal Orzel, AMD")

We wish to start with upstreaming the requirements.

This patches illustrate how we are writing the requirements and provides some examples.
The support level is experimental and it will be maintained on a best effort basis.

Changes from v1 :-
1. Added "docs: fusa: reqs: Added a requirements writing style guide" in this patch serie.

v2 :-
1. Reordered patches 2 and 3.
2. Changes mentioned in individual files.

Ayan Kumar Halder (3):
docs: Introduce Fusa Requirement and define maintainers
docs: fusa: reqs: Added a requirements writing style guide
docs: fusa : reqs: Added a sample of requirements [DO_NOT_MERGE]

 MAINTAINERS                                   |   9 +
 docs/fusa/index.rst                           |   9 +
 docs/fusa/reqs/REQUIREMENTS-STYLE             |  34 +++
 .../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/index.rst                      |   9 +
 docs/fusa/reqs/intro.rst                      |  86 +++++++
 docs/fusa/reqs/market-reqs/reqs.rst           |  77 ++++++
 docs/fusa/reqs/product-reqs/reqs.rst          |  64 +++++
 10 files changed, 881 insertions(+)
 create mode 100644 docs/fusa/index.rst
 create mode 100644 docs/fusa/reqs/REQUIREMENTS-STYLE
 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/index.rst
 create mode 100644 docs/fusa/reqs/intro.rst
 create mode 100644 docs/fusa/reqs/market-reqs/reqs.rst
 create mode 100644 docs/fusa/reqs/product-reqs/reqs.rst
Signature · 1 line
2.25.1
#1 lore raw

PATCH v3 1/3 docs: Introduce Fusa Requirement and define maintainers

The FUSA folder is expected to contain requirements and other documents to enable safety certification of Xen hypervisor.
Added a intro to explain how the requirements are categorized, written and their supported status.
Also, added index.rst for inclusion in build docs.

Added maintainers for the same.

---
Changes from :-

v1 - 1. Added a comment from Stefano.
2. Added Ack.

v2 - 1. Renamed README to intro and changed the format from MD to RST (as the majority of files are in RST format and it gets picked during building of the docs).
However, the actual contents hasn't changed so I am keeping the acks.

2. Added SPDX license identifier to the intro file.

 MAINTAINERS              |  9 +++++
 docs/fusa/index.rst      |  9 +++++
 docs/fusa/reqs/index.rst |  9 +++++
 docs/fusa/reqs/intro.rst | 86 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 113 insertions(+)
 create mode 100644 docs/fusa/index.rst
 create mode 100644 docs/fusa/reqs/index.rst
 create mode 100644 docs/fusa/reqs/intro.rst
MAINTAINERS +9 -0
index 7c524a8a93..0d328e065c 100644
@@ -314,6 +314,15 @@ F:	xen/arch/x86/include/asm/x86_*/efi*.h
 F:	xen/common/efi/
 F:	xen/include/efi/
 
+FUSA
+M:	Stefano Stabellini <[email protected]>
+M:	Bertrand Marquis <[email protected]>
+M:	Michal Orzel <[email protected]>
+M:	Ayan Kumar Halder <[email protected]>
+M:	Artem Mygaiev <[email protected]>
+S:	Supported
+F:	docs/fusa/
+
 GDBSX DEBUGGER
 M:	Elena Ufimtseva <[email protected]>
 S:	Supported
docs/fusa/index.rst new file +9 -0
new file mode 100644
index 0000000000..13bf4e8e23
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Functional Safety documentation
+===============================
+
+.. toctree::
+   :maxdepth: 2
+
+   reqs
docs/fusa/reqs/index.rst new file +9 -0
new file mode 100644
index 0000000000..78c02b1d9b
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Requirements documentation
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
docs/fusa/reqs/intro.rst new file +86 -0

86 lines not on this page · raw message

Signature · 1 line
2.25.1
Acked-by Acked-by Bertrand Marquis Acked-by Michal Orzel Reviewed-by Stefano Stabellini on v3 1/3
#2 lore raw

Re: [PATCH v3 1/3] docs: Introduce Fusa Requirement and define maintainers

Hi Ayan
Sorry for delay - I was ill and then off for the whole August

Just for the record:

Best regards,
-- Artem Mygaiev

________________________________________
From: Ayan Kumar Halder <[email protected]>
Sent: Tuesday, August 6, 2024 19:31
To: [email protected] <[email protected]>; [email protected] <[email protected]>; [email protected] <[email protected]>; [email protected] <[email protected]>; Artem Mygaiev <[email protected]>; [email protected] <[email protected]> Cc: [email protected] <[email protected]>
Subject: [PATCH v3 1/3] docs: Introduce Fusa Requirement and define maintainers

The FUSA folder is expected to contain requirements and other documents
to enable safety certification of Xen hypervisor.
Added a intro to explain how the requirements are categorized, written
and their supported status.
Also, added index.rst for inclusion in build docs.

Added maintainers for the same.

---
Changes from :-

v1 - 1. Added a comment from Stefano.
2. Added Ack.

v2 - 1. Renamed README to intro and changed the format from MD to RST (as the majority of files are in RST format and it gets picked during building of the docs).
However, the actual contents hasn't changed so I am keeping the acks.

2. Added SPDX license identifier to the intro file.

 MAINTAINERS              |  9 +++++
 docs/fusa/index.rst      |  9 +++++ docs/fusa/reqs/index.rst |  9 +++++ docs/fusa/reqs/intro.rst | 86 ++++++++++++++++++++++++++++++++++++++++

 4 files changed, 113 insertions(+)

 create mode 100644 docs/fusa/index.rst
 create mode 100644 docs/fusa/reqs/index.rst
 create mode 100644 docs/fusa/reqs/intro.rst

MAINTAINERS +0 -0
index 7c524a8a93..0d328e065c 100644
@@ -314,6 +314,15 @@ F: xen/arch/x86/include/asm/x86_*/efi*.h

 F:      xen/common/efi/
 F:      xen/include/efi/

+FUSA
+M:     Stefano Stabellini <[email protected]> +M:     Bertrand Marquis <[email protected]> +M:     Michal Orzel <[email protected]> +M:     Ayan Kumar Halder <[email protected]> +M:     Artem Mygaiev <[email protected]> +S:     Supported
+F:     docs/fusa/
+
 GDBSX DEBUGGER
 M:      Elena Ufimtseva <[email protected]> S:      Supported

docs/fusa/index.rst new file +9 -0
new file mode 100644
index 0000000000..13bf4e8e23
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Functional Safety documentation
+===============================
+
+.. toctree::
+   :maxdepth: 2
+
+   reqs
docs/fusa/reqs/index.rst new file +9 -0
new file mode 100644
index 0000000000..78c02b1d9b
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: CC-BY-4.0
+
+Requirements documentation
+==========================
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
docs/fusa/reqs/intro.rst new file +86 -0

86 lines not on this page · raw message

--
2.25.1

#3 lore raw

PATCH v3 2/3 docs: fusa: reqs: Added a requirements writing style guide

In reply to Ayan Kumar Halder

Added a guide to help write and review requirements. The requirements are written to enable safety certification of Xen hypervisor.

---
Changes from -

v1, v2 - No changes.

 docs/fusa/reqs/REQUIREMENTS-STYLE | 34 +++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 docs/fusa/reqs/REQUIREMENTS-STYLE
docs/fusa/reqs/REQUIREMENTS-STYLE new file +34 -0
new file mode 100644
index 0000000000..cd2408b9f2
@@ -0,0 +1,34 @@
+Requirements writing style for the Xen Hypervisor
+=================================================
+
+The requirements writing style described below is the style used for writing the
+requirements of the Xen hypervisor to enable functional safety certification.
+
+The requirements writing style is inspired from the ANSI/IEEE guide to Software
+Requirements Standard. Specifically, the requirements should satisfy the
+following validation checklist.
+(Source - https://www.nasa.gov/reference/appendix-c-how-to-write-a-good-requirement)
+
+Clarity -
+The requirements should be clear, unambiguous, consise and simple. Each
+requirement should express a single thought. Each requirement stated should have
+a single interpretation.
+
+Consistency -
+Any requirement shouldn't contradict with any other requirement. The requirements
+should be categorized correctly (the categories have been explained in the
+README). The tone of each requirement should be definitive (ie "Xen shall ..."
+should be present in each requirement).
+
+Traceability -
+Any market requirement should be linked to the product requirement/s and
+vice versa. Any product requirement should be linked to the design requirement/s
+and vice versa. Full bi-directional traceability should be maintained between
+market, product and design requirements.
+
+Correctness -
+The requirements should be feasible and technically correct (at the time of
+writing). However, it is not expected that the requirements will be kept upto
+date with the code.
+
+The requirements follow the same license and line length as the code.
Signature · 1 line
2.25.1
#4 lore raw

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

In reply to Ayan Kumar Halder

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.

---
Changes from :-

v1, v2 - No changes.

 .../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
docs/fusa/reqs/design-reqs/arm64/emulated-uart.rst new file +240 -0
new file mode 100644
index 0000000000..483db92fa8
@@ -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)
docs/fusa/reqs/design-reqs/arm64/generic-timer.rst new file +146 -0

146 lines not on this page · raw message

docs/fusa/reqs/design-reqs/xen-version.rst new file +207 -0

207 lines not on this page · raw message

docs/fusa/reqs/market-reqs/reqs.rst new file +77 -0

77 lines not on this page · raw message

docs/fusa/reqs/product-reqs/reqs.rst new file +64 -0

64 lines not on this page · raw message

Signature · 1 line
2.25.1