Requirement Document generator tool

[Jose Valdez]

Hello Chris,

Thank you for your reply.

Please find below my answers.

José

-----Original Message-----
From: Chris Johns [mailto:chrisj at rtems.org] 
Sent: sexta-feira, 13 de dezembro de 2019 19:09
To: Jose Valdez; devel at rtems.org
Subject: Re: Requirement Document generator tool

On 14/12/19 3:09 am, Jose Valdez wrote:
> In the scope of ESA's RTEMS SMP project, we are developing a tool which will
> allow to generate RTEMS software documentation 

I assume this is the pre-qual effort.

JV: That's correct.

> (Requirements, Design, Test Specification and other software documents).

How do these documents relate to the project's current documentation? It may
help to explain the purpose of each of these documents and the target user.

JV: The idea of the project is to allow an user to pre-qualify RTEMS for space applications. In that sense, the goal of the tool is to save the pre-qualification effort, by creating automatically the parts of the necessary documentation, which may be automatized. Generically parts which may be automatized are:
-> Traceabilities (ex: Requirements against Architecture)
-> Requirement coverage (Tests against requirements)
-> Test results verification
-> Creation of document templates
-> source code metrics collection
-> etc.

The current scope is to create the documentation in accordance with ESA standard (ECSS), which defines the following necessary documents (and also the template) for a software product (note: the description text of each document was taken from ECSS, for helping you to understand the goal of each document):

------------------------------------------------------------------------------------------------
Software Development Plan (SDP) - Its purpose is to describe the established management and development approach for the software items to be defined by a software supplier to set up a software project in accordance with the customer requirements.

Software Product Assurance Plan (SPAP) - The purpose of the software product assurance plan is to provide information on the organizational aspects and the technical approach to the execution of the software product assurance programme

Software Configuration Management Plan (SCMP) - The objective of the configuration management plan is to provide in a single document all elements necessary to ensure that the implementation of configuration management meets customer requirements and is commensurate with the programme or project, organization, and management structure.

Software Configuration File (SCF) - The objective of the software configuration file is to provide the configuration status of the software configuration item. It controls its evolution during the programme or project life cycle.

Software Reuse File (SRF) - Its purpose is to document the analysis to be performed on existing software intended to be reused.
The global objectives of the software reuse file are to document all the information used to decide about the reuse (or not) of existing software and to plan the specific actions undertaken to ensure that the reused software meets the project requirements.
The SRF is also used to document software developed for intended reuse, such that it is ready when the software is actually reused.

Software User Manual (SUM) - Its purpose is to provide instructions for the users of the software.
For flight software, the relevant parts of the SUM are a contribution to the flight operation manual (FOM).

Software Validation Specification (SVS) - The purpose of this DRD is to describe the testing, analysis, inspection and
review of design specifications, and is used to document:
-> the software validation specification with respect to the technical specification (TS), and
-> the software validation specification with respect to the requirements baseline (RB).
It provides a unique template for the software validation specification document, to be instantiated for, either the technical specification, or the
requirement baseline. The acronym SVS w.r.t. TS is used to designate the software validation specification with respect to the technical specification whilst SVS w.r.t. RB is used to designate the software validation specification with respect to the requirement baseline.

Software Design Document (SDD) - It provides description of the software architectural design and the software detailed design. Internal interfaces design is also included in this document.

Software Release Document (SRelD) - Its purpose is to describe a given software version in terms of known problems, limitations or restrictions with respect to its approved baseline.

Interface Control Document (ICD) - It describes all the (preliminary and update) external interfaces.

Software Product Assurance Milestone Report (SPAMR) - The main purpose of the software product assurance milestone report is to collect and present at project milestones the reporting on the software product assurance activities performed during the past project phases.

Software Review Plan (SRevP) - This document provides means for identifying and structuring all of the activities and information required in a project review. It identifies the information outputs and activities necessary to complete the process. It also provides a check-list of activities and information required for each of the project reviews identified in the ECSS Management Standards.

Software Verification Report (SVR) - Its purpose is to present gathered results of all the software verification activities that have to be executed along the software development life cycle according to the SVerP. It is organized per process, with the exception of the timing and sizing issues which are gathered in a separate section. Each process verification report can be placed into a separate document.

Software Validation Plan (SVP) - Its purpose is to provide the definition of organizational aspects and management approach to the implementation of the validation tasks. The objective of the software validation plan is to describe the approach to the implementation of the validation process for a software product.

Software Requirements Specification (SRS) - It describes the functional and non functional requirements applicable to the software item. 

Software Unit/Integration Test Plan (SUITP) - The purpose of this document is to describe the tests plans, and is utilized for the following documents:
-> the software unit test plan;
-> the software integration test plan.
It provides a unique template for unit and integration testing, to be instantiated for the software test plans specified in the document requirement list, either for a software unit test plan, or for a software integration test plan.
---------------------------------------------------------------------------------------

This documentation will re-direct to information already existent in the RTEMS current documentation (ex: the case of the RTEMS API User Manual). Repeating what was said above, the goal is to create ESA needed documentation to facilitate the RTEMS pre-qualification for space missions (according with ESA standard). However, the idea is not to close the tool for ESA space applications. We have performed a study, comparing the ECSS standard with other standards (DO, IEC and ISO) which aimed to assess the needed effort to adapt/extend the tool for other standards. The conclusion was that the tool could be indeed adapted for other standards, so this opens potential for the tool to be extended and used for other space agencies (ex: NASA) and also for other possible RTEMS markets (ex: automotive standards).

Note that this work includes also a Test Executor, which will allow to execute the tests in the space platforms. Although some development was already done, we are currently studying how we could integrate our tool with RTEMS tester or even if we need our Test Executor at all, since the RTEMS tester may be doing already all the intended functionality. 

> Our first task will be to develop and integrate the SRS Manager into RTEMS
> project. 

What does SRS mean? What is it managing?

JV: Software Requirement Specification (as explained above). The SRS Manager software will allow to collect the requirements written in doorstop format and create the SRS document according with ESA standard. It may manage the following information:
-> Creation of a Requirement document according with a certain template
-> Verification of requirements traceability against higher-level requirements
-> Certain checks in the requirements (ex: unique ID, if it has a verification method defined, if it is deprecated, etc)

Could you please explain in more detail how you are planing to do the
development? As an open source project we prefer to see things that end up in
RTEMS being developed publicly and on our devel@ list. It makes the process of
merging smoother.

JV: The tool development will be made in a module-by-module basis (that is first we start with SRS Manager, then TestManager and so on), this development will be approximately 1 month development cycle per manager, during the next year. We will have the RTEMS SMP qualification (done by Sebastian Huber) as our first user. My suggestion is that each manager could be integrated in the RTEMS project as long as it is finished and Sebastian gives us positive feedback of his tool user-experience..

> This SRS Manager reads requirements written in doorstop format (each
> topic is a doorstop document) and produces the SRS document according with ECSS
> format (the output of the tool are sphinx files, which then are compiled to pdf
> document).

I do not understand what is meant by "doorstop document"? A work flow may help
where we see the types of data used. I ask this because a document generator
needs to have the requirements data being held somewhere and I do not know where
that is.

JV: You may think as "doorstop document" a set of doorstop yaml files. Each set is a requirements' topic (ex: requirements for task manager, requirements for semaphore manager, etc). This is explained in our documentation, which probably we should provide to you.

Does the tool generate ReST format output?

JV: Yes

Is the ECSS format a template given to sphinx? We would need to be able to
support other formats.

JV: It is our tool which creates the ECSS format. I agree (other formats should be supported), and it is in line with I explained above. The scope of this project is to just create automatically the documentation for the ECSS format. But as a future continuation of this work other formats/standars could be included.

We typically require HTML _and_ PDF.

JV: We are generating PDF. HTML is not considered to be in the scope of this project. Although I would say that it would not be hard to generate html from what we have now, since sphinx has built-in capability to generate html.

> Could you indicate how I can integrate our tool into RTEMS git repository?

Commit access to the repositories is given to people who work with the project
and are active for a period of time. You will need to post changes and get the
support of a core development before the code can be merged.

> Should be in rtems-tools? If so, in which place?

I think this is the best place given the information I have. I would need to
have more detail before I could provide any specific direction here.

JV: I hope I was able to clarify your points. I predict the first integration/commit will be for the SRS Manager, after Sebastian positive user-experience.

I would like to clearly state I fully support the pre-qual effort and I thank
ESA for making this happen. It is exciting for RTEMS to have this activity.

JV: Thank you for your words. We hope this tool serves the RTEMS community as much as possible.

Chris