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 <ayan.kumar.halder@amd.com>
Acked-by: Bertrand Marquis <bertrand.marquis@arm.com>
---
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
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@kernel.org>
+M: Bertrand Marquis <bertrand.marquis@arm.com>
+M: Michal Orzel <michal.orzel@amd.com>
+M: Ayan Kumar Halder <ayan.kumar.halder@amd.com>
+M: Artem Mygaiev <artem_mygaiev@epam.com>
+S: Supported
+F: docs/fusa/
+
GDBSX DEBUGGER
M: Elena Ufimtseva <elena.ufimtseva@oracle.com>
S: Supported
diff --git a/docs/fusa/reqs/README.md b/docs/fusa/reqs/README.md
new file mode 100644
index 0000000000..651f0a4e00
--- /dev/null
+++ b/docs/fusa/reqs/README.md
@@ -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.
--
2.25.1Hi Ayan, On 02/08/2024 11:46, Ayan Kumar Halder wrote: > 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 <ayan.kumar.halder@amd.com> > Acked-by: Bertrand Marquis <bertrand.marquis@arm.com> > --- > 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: Acked-by: Michal Orzel <michal.orzel@amd.com> ~Michal
On 05/08/2024 10:46, Michal Orzel wrote: > Hi Ayan, Hi Michal, > > On 02/08/2024 11:46, Ayan Kumar Halder wrote: >> 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 <ayan.kumar.halder@amd.com> >> Acked-by: Bertrand Marquis <bertrand.marquis@arm.com> >> --- >> 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? No specific reason as such. I am happy for this filename to be renamed on commit. > 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. > > Apart from that: > Acked-by: Michal Orzel <michal.orzel@amd.com> - Ayan > > ~Michal
On 05/08/2024 14:45, Ayan Kumar Halder wrote: > > On 05/08/2024 10:46, Michal Orzel wrote: >> Hi Ayan, > Hi Michal, >> >> On 02/08/2024 11:46, Ayan Kumar Halder wrote: >>> 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 <ayan.kumar.halder@amd.com> >>> Acked-by: Bertrand Marquis <bertrand.marquis@arm.com> >>> --- >>> 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? > 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. >> 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
On Fri, 2 Aug 2024, Ayan Kumar Halder wrote: > 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 <ayan.kumar.halder@amd.com> > Acked-by: Bertrand Marquis <bertrand.marquis@arm.com> Reviewed-by: Stefano Stabellini <sstabellini@kernel.org> > --- > 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 > > 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@kernel.org> > +M: Bertrand Marquis <bertrand.marquis@arm.com> > +M: Michal Orzel <michal.orzel@amd.com> > +M: Ayan Kumar Halder <ayan.kumar.halder@amd.com> > +M: Artem Mygaiev <artem_mygaiev@epam.com> > +S: Supported > +F: docs/fusa/ > + > GDBSX DEBUGGER > M: Elena Ufimtseva <elena.ufimtseva@oracle.com> > S: Supported > diff --git a/docs/fusa/reqs/README.md b/docs/fusa/reqs/README.md > new file mode 100644 > index 0000000000..651f0a4e00 > --- /dev/null > +++ b/docs/fusa/reqs/README.md > @@ -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. > -- > 2.25.1 >
© 2016 - 2024 Red Hat, Inc.