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

[Artem Mygaiev <Artem_Mygaiev@xxxxxxxx>]

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

Just for the record:
Acked-by: Artem Mygaiev <artem_mygaiev@xxxxxxxx>

Best regards,
-- Artem Mygaiev

________________________________________
From: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
Sent: Tuesday, August 6, 2024 19:31
To: sstabellini@xxxxxxxxxx <sstabellini@xxxxxxxxxx>; bertrand.marquis@xxxxxxx 
<bertrand.marquis@xxxxxxx>; michal.orzel@xxxxxxx <michal.orzel@xxxxxxx>; 
ayan.kumar.halder@xxxxxxx <ayan.kumar.halder@xxxxxxx>; Artem Mygaiev 
<artem_mygaiev@xxxxxxxx>; julien@xxxxxxx <julien@xxxxxxx>
Cc: xen-devel@xxxxxxxxxxxxxxxxxxxx <xen-devel@xxxxxxxxxxxxxxxxxxxx>
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.

Signed-off-by: Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
Acked-by: Bertrand Marquis <bertrand.marquis@xxxxxxx>
Acked-by: Michal Orzel <michal.orzel@xxxxxxx>
Reviewed-by: Stefano Stabellini <sstabellini@xxxxxxxxxx>
---
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

diff --git a/MAINTAINERS b/MAINTAINERS
index 7c524a8a93..0d328e065c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -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 <sstabellini@xxxxxxxxxx>
+M:     Bertrand Marquis <bertrand.marquis@xxxxxxx>
+M:     Michal Orzel <michal.orzel@xxxxxxx>
+M:     Ayan Kumar Halder <ayan.kumar.halder@xxxxxxx>
+M:     Artem Mygaiev <artem_mygaiev@xxxxxxxx>
+S:     Supported
+F:     docs/fusa/
+
 GDBSX DEBUGGER
 M:      Elena Ufimtseva <elena.ufimtseva@xxxxxxxxxx>
 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://urldefense.com/v3/__https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md__;!!GF_29dbcQIUBPA!3MNZCxyEF3Nx0ElHxeOSL8GQue43wrSJ410vOujPqaM4D7gWoONkKa85oOiyDfxDy9iQ7xY4oyYT0DQ9nIPopGcKGbkI$
 [github[.]com]).
+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.
--
2.25.1