From 878974a33f9b4ae2686364ce2375239fccd7b063 Mon Sep 17 00:00:00 2001 From: Ayan Kumar Halder Date: Tue, 6 Aug 2024 17:31:55 +0100 Subject: [PATCH] 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. Signed-off-by: Ayan Kumar Halder Acked-by: Bertrand Marquis Acked-by: Michal Orzel Reviewed-by: Stefano Stabellini --- 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 diff --git a/MAINTAINERS b/MAINTAINERS index 89be48fdf9..fb0ebf0939 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -315,6 +315,15 @@ F: xen/arch/x86/include/asm/x86_*/efi*.h F: xen/common/efi/ F: xen/include/efi/ +FUSA +M: Stefano Stabellini +M: Bertrand Marquis +M: Michal Orzel +M: Ayan Kumar Halder +M: Artem Mygaiev +S: Supported +F: docs/fusa/ + GDBSX DEBUGGER M: Elena Ufimtseva S: Supported diff --git a/docs/fusa/index.rst b/docs/fusa/index.rst new file mode 100644 index 0000000000..13bf4e8e23 --- /dev/null +++ b/docs/fusa/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Functional Safety documentation +=============================== + +.. toctree:: + :maxdepth: 2 + + reqs diff --git a/docs/fusa/reqs/index.rst b/docs/fusa/reqs/index.rst new file mode 100644 index 0000000000..78c02b1d9b --- /dev/null +++ b/docs/fusa/reqs/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +Requirements documentation +========================== + +.. toctree:: + :maxdepth: 2 + + intro diff --git a/docs/fusa/reqs/intro.rst b/docs/fusa/reqs/intro.rst new file mode 100644 index 0000000000..d67b18dd9f --- /dev/null +++ b/docs/fusa/reqs/intro.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: CC-BY-4.0 + +################################## +Requirements Introduction Document +################################## + +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 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.