| Message ID | 20240802094614.1114227-2-ayan.kumar.halder@amd.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Introduce functional safety related documents | expand |
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 >
Hi 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
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.