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

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Wed, 31 Jul 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@xxxxxxx>
> ---
>  MAINTAINERS              |  9 +++++
>  docs/fusa/reqs/README.md | 75 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 84 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@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/reqs/README.md b/docs/fusa/reqs/README.md
> new file mode 100644
> index 0000000000..69b8d3a5c8
> --- /dev/null
> +++ b/docs/fusa/reqs/README.md
> @@ -0,0 +1,75 @@
> +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 writing style is inspired from the ANSI/IEEE guide to 
> Software
> +Requirements Standard 830-1984.


I think it would be helpful to mention that they are currently
experimental and may be slightly out of sync with the code. We are
actively working on a process to keep them updated, more details to
follow.


> +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
>