Introduce functional safety related documents
PATCH v2 2/3 docs: fusa : reqs: Added a sample of requirements [DO_NOT_MERGE]
In reply to Ayan Kumar HalderAdded 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 - 1. Filenames contain '-' instead of '_'.
.../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
@@ -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
v2 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.
Ayan Kumar Halder (3):
docs: Introduce Fusa Requirement and define maintainers
docs: fusa : reqs: Added a sample of requirements [DO_NOT_MERGE]
docs: fusa: reqs: Added a requirements writing style guide
MAINTAINERS | 9 + docs/fusa/reqs/README.md | 78 ++++++ 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/market-reqs/reqs.rst | 77 ++++++ docs/fusa/reqs/product-reqs/reqs.rst | 64 +++++ 8 files changed, 855 insertions(+) create mode 100644 docs/fusa/reqs/README.md 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/market-reqs/reqs.rst create mode 100644 docs/fusa/reqs/product-reqs/reqs.rst
Signature · 1 line
2.25.1
PATCH v2 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 README to explain how the requirements are categorized, written and their supported status.
Added maintainers for the same.
---
Changes from :-
v1 - 1. Added a comment from Stefano.
2. Added Ack.
MAINTAINERS | 9 +++++ docs/fusa/reqs/README.md | 78 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 docs/fusa/reqs/README.md
MAINTAINERS +9 -0
@@ -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/reqs/README.md new file +78 -0
78 lines not on this page · raw message
Signature · 1 line
2.25.1
PATCH v2 3/3 docs: fusa: reqs: Added a requirements writing style guide
In reply to Ayan Kumar HalderAdded a guide to help write and review requirements. The requirements are written to enable safety certification of Xen hypervisor.
---
Changes from :-
v1 - 1. No change.
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
@@ -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
Re: [PATCH v2 3/3] docs: fusa: reqs: Added a requirements writing style guide
Hi Ayan,
Quoted 5 lines · Ayan Kumar Halder
Added a guide to help write and review requirements. The requirements are written to enable safety certification of Xen hypervisor.
Just a reminder if someone commits this serie:
PATCH 2 MUST NO BE COMMITED !!
Would have been a good idea to have it at the end of the serie and this one before.
In any case:
Quoted 1 line
Signed-off-by Ayan Kumar Halder <[email protected]>
Cheers
Bertrand
Quoted 52 lines
---
Changes from :-v1 - 1. No change.
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@@ -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
Re: [PATCH v2 1/3] docs: Introduce Fusa Requirement and define maintainers
In reply to Ayan Kumar HalderQuoted 9 lines · Ayan Kumar Halder
The FUSA folder is expected to contain requirements and other documents to enable safety certification of Xen hypervisor.
Added a README to explain how the requirements are categorized, written and their supported status.Added maintainers for the same.
Signed-off-by Ayan Kumar Halder <[email protected]>Acked-by Bertrand Marquis <[email protected]>
Quoted 118 lines
---
Changes from :-v1 - 1. Added a comment from Stefano.
2. Added Ack.MAINTAINERS | 9 +++++ docs/fusa/reqs/README.md | 78 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 docs/fusa/reqs/README.mdMAINTAINERS +9
-0@@ -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: Supporteddocs/fusa/reqs/README.md new file +78
-0@@ -0,0 +1,78 @@ +This folder contains a set of requirements describing Xen and its implementation +in a form suitable for a safety certification process. + +The status is experimental and it is maintained on a best effort basis. The +requirements may get slightly out of sync with the code. We are actively working +on a process to keep them updated, more details to follow. + +The requirements writing style is inspired from the ANSI/IEEE guide to Software +Requirements Standard 830-1984. + +The requirements are categorized as follows :- + +1. Market requirements - They define the high level functionalities of the +hypervisor without going into concepts specific to Xen. Those should allow a +system architect to understand wether Xen is providing the functionalities it +needs for its system. This is the top level of the requirements. + +2. Product requirements - They define the Xen specific concepts and interfaces +provided by Xen without going into implementation details. One or several of +those requirements are linked to each market requirement. An Architect can use +them understand how Xen fulfils a market need and design how Xen should be used +in his system. + +3. Design requirements - They describe what the software implementation is doing +from a technical point of view. One or several design requirement together +define how product requirements are fulfilled technically and are linked to +them. An implementer can use them to know how to write or understand the Xen +code. + +The requirements are linked using OpenFastTrace +(https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md). +OpenFastTrace parses through the requirements and generates a traceability +report. + +The following is the skeleton for a requirement. + +Title /* Title of the requirement */ +----- + +`unique_tag` +/* + * Each requirement needs to have a unique tag associated. The format is + * req_type~name~revision. + * + * Thus, it consists of three components :- + * requirement type - This denotes the category of requirement. Thus, it shall + * 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). + * revision number - This gets incremented each time the requirement is modified. + */ + +Description: +This shall describe the requirement in a definitive tone. In other words, +the requirement begins with 'Xen shall ...'. Further, the description is +expected to be unambiguous and consistent. + +Rationale: +This describes a rationale explaining the reason of the presence of the +requirement when this can help the reader. This field can be left blank. + +Comments: +This describes the use cases for the requirement when this can help the +reader. This field can be left blank as well. + +Covers: +This denotes the unique_tag of the parent. This field is non existent for the +market requirement as it is the top level. + +Needs: +This denotes the requirement type of its children. This field is non existent +for the design requirements as there are no subsequent requirements linked to +them. + + +The requirements are expected to the technically correct and follow the above +guidelines.Signature · 1 line
2.25.1
Re: [PATCH v2 1/3] docs: Introduce Fusa Requirement and define maintainers
In reply to Ayan Kumar HalderHi Ayan,
Quoted 9 lines · Ayan Kumar Halder
The FUSA folder is expected to contain requirements and other documents to enable safety certification of Xen hypervisor.
Added a README to explain how the requirements are categorized, written and their supported status.Added maintainers for the same.
Signed-off-by Ayan Kumar Halder <[email protected]>Acked-by Bertrand Marquis <[email protected]>
Quoted 8 lines
---
Changes from :-v1 - 1. Added a comment from Stefano.
2. Added Ack.MAINTAINERS | 9 +++++ docs/fusa/reqs/README.md | 78 ++++++++++++++++++++++++++++++++++++++++
I have 2 questions:
1) Most of our docs are written in RST, same will be true for requirements docs. Any specific reason for using markdown?
2) In the current form of this patch, docs/fusa won't be part of the generated Xen docs. Is this intended? Don't we want to include it?
Apart from that:
~Michal
Re: [PATCH v2 1/3] docs: Introduce Fusa Requirement and define maintainers
Quoted 1 line · Michal Orzel
Hi Ayan,
Hi Michal,
Quoted 14 lines · Ayan Kumar Halder
Quoted 12 lines
The FUSA folder is expected to contain requirements and other documents to enable safety certification of Xen hypervisor.
Added a README to explain how the requirements are categorized, written and their supported status.Added maintainers for the same.
Signed-off-by Ayan Kumar Halder <[email protected]>Acked-by Bertrand Marquis <[email protected]>---
Changes from :-
Quoted 7 lines
Quoted 5 lines
v1 - 1. Added a comment from Stefano.
2. Added Ack.MAINTAINERS | 9 +++++ docs/fusa/reqs/README.md | 78 ++++++++++++++++++++++++++++++++++++++++I have 2 questions:
1) Most of our docs are written in RST, same will be true for requirements docs. Any specific reason for using markdown?
No specific reason as such. I am happy for this filename to be renamed on commit.
Quoted 2 lines
2) In the current form of this patch, docs/fusa won't be part of the generated Xen docs. Is this intended? Don't we want to include it?
docs/fusa will become a part of the generated Xen docs when the requirements (see patch 2) are added.
Quoted 3 lines
Apart from that:
Acked-by Michal Orzel <[email protected]>
- Ayan
Quoted 2 lines
~Michal
Re: [PATCH v2 1/3] docs: Introduce Fusa Requirement and define maintainers
Quoted 21 lines · Ayan Kumar Halder
Quoted 1 line · Michal Orzel
Hi Ayan,
Hi Michal,
Quoted 17 lines · Ayan Kumar Halder
Quoted 15 lines
The FUSA folder is expected to contain requirements and other documents to enable safety certification of Xen hypervisor.
Added a README to explain how the requirements are categorized, written and their supported status.Added maintainers for the same.
Signed-off-by Ayan Kumar Halder <[email protected]>Acked-by Bertrand Marquis <[email protected]>---
Changes from :-v1 - 1. Added a comment from Stefano.
2. Added Ack.
Quoted 6 lines
Quoted 4 lines
Quoted 2 lines
MAINTAINERS | 9 +++++ docs/fusa/reqs/README.md | 78 ++++++++++++++++++++++++++++++++++++++++I have 2 questions:
1) Most of our docs are written in RST, same will be true for requirements docs. Any specific reason for using markdown?No specific reason as such. I am happy for this filename to be renamed on commit.
If we want RST, I'm afraid it would involve more changes than it can be done on commit (rstcheck reports quite a few). Also, renaming to RST would result in this file being picked up by sphinx build and it would report a warning too.
Quoted 4 lines
Quoted 2 lines
2) In the current form of this patch, docs/fusa won't be part of the generated Xen docs. Is this intended? Don't we want to include it?
docs/fusa will become a part of the generated Xen docs when the requirements (see patch 2) are added.
If you want docs/fusa to be included, why not doing this right away?
~Michal