<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Dec 16, 2019 at 7:29 AM Jose Valdez <<a href="mailto:Jose.Valdez@edisoft.pt">Jose.Valdez@edisoft.pt</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello Chris,<br>
<br>
Thank you for your reply.<br>
<br>
Please find below my answers.<br>
<br>
José<br>
<br>
-----Original Message-----<br>
From: Chris Johns [mailto:<a href="mailto:chrisj@rtems.org" target="_blank">chrisj@rtems.org</a>] <br>
Sent: sexta-feira, 13 de dezembro de 2019 19:09<br>
To: Jose Valdez; <a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
Subject: Re: Requirement Document generator tool<br>
<br>
On 14/12/19 3:09 am, Jose Valdez wrote:<br>
> In the scope of ESA's RTEMS SMP project, we are developing a tool which will<br>
> allow to generate RTEMS software documentation <br>
<br>
I assume this is the pre-qual effort.<br>
<br>
JV: That's correct.<br>
<br>
> (Requirements, Design, Test Specification and other software documents).<br>
<br>
How do these documents relate to the project's current documentation? It may<br>
help to explain the purpose of each of these documents and the target user.<br></blockquote><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
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:<br>
-> Traceabilities (ex: Requirements against Architecture)<br>
-> Requirement coverage (Tests against requirements)<br>
-> Test results verification<br>
-> Creation of document templates<br>
-> source code metrics collection<br>
-> etc.<br>
<br>
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):<br></blockquote><div><br></div><div>This list of documents has some of which I would expect to</div><div>be hand-written, one-time documents. Others related to requirements, traceability,</div><div>and tests, I would expect to be generated. Can you clarify which documents</div><div>fall into which category?</div><div><br></div><div>And how these documents related to RTEMS Pre-Qualification. For example, I don't see the</div><div>need for a Software Reuse File for RTEMS. That would seem to be something a project adopting</div><div>RTEMS might need.</div><div><br></div><div>These documents also show an intentional bias to ECSS which is OK for you guys but </div><div>doesn't help in the RTEMS.org broader goal of having technical data for qualification which</div><div>fulfills the needs for multiple standards (NASA Quality, DO-178, automotive, etc.) Please</div><div>keep in mind that RTEMS is a world-wide project, independent of ESA and we would </div><div>like this effort to be able to address the multiple stakeholders.</div><div><br></div><div>Some of these have the same names as other quality standard, others don't.</div><div></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
------------------------------------------------------------------------------------------------<br>
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.<br>
<br>
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<br>
<br>
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.<br>
<br>
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.<br>
<br>
Software Reuse File (SRF) - Its purpose is to document the analysis to be performed on existing software intended to be reused.<br>
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.<br>
The SRF is also used to document software developed for intended reuse, such that it is ready when the software is actually reused.<br>
<br>
Software User Manual (SUM) - Its purpose is to provide instructions for the users of the software.<br>
For flight software, the relevant parts of the SUM are a contribution to the flight operation manual (FOM).<br>
<br>
Software Validation Specification (SVS) - The purpose of this DRD is to describe the testing, analysis, inspection and<br>
review of design specifications, and is used to document:<br>
-> the software validation specification with respect to the technical specification (TS), and<br>
-> the software validation specification with respect to the requirements baseline (RB).<br>
It provides a unique template for the software validation specification document, to be instantiated for, either the technical specification, or the<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
Interface Control Document (ICD) - It describes all the (preliminary and update) external interfaces.<br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
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.<br>
<br>
Software Requirements Specification (SRS) - It describes the functional and non functional requirements applicable to the software item. <br>
<br>
Software Unit/Integration Test Plan (SUITP) - The purpose of this document is to describe the tests plans, and is utilized for the following documents:<br>
-> the software unit test plan;<br>
-> the software integration test plan.<br>
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.<br>
---------------------------------------------------------------------------------------<br>
<br>
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).<br>
<br>
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. <br>
<br>
> Our first task will be to develop and integrate the SRS Manager into RTEMS<br>
> project. <br>
<br>
What does SRS mean? What is it managing?<br>
<br>
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:<br>
-> Creation of a Requirement document according with a certain template<br>
-> Verification of requirements traceability against higher-level requirements<br>
-> Certain checks in the requirements (ex: unique ID, if it has a verification method defined, if it is deprecated, etc)<br>
<br>
Could you please explain in more detail how you are planing to do the<br>
development? As an open source project we prefer to see things that end up in<br>
RTEMS being developed publicly and on our devel@ list. It makes the process of<br>
merging smoother.<br>
<br>
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..<br></blockquote><div><br></div><div>Existence is not a sufficient condition for any tool to be accepted by the RTEMS Project.</div><div><br></div><div>There are requirements on licensing, cross-platform support, dependencies to manage, </div><div>ease of integration into automated systems, etc. If these tools are to be supported, they</div><div>need to be made available for review from the initial decision points. By the time you have</div><div>code, you may already be too committed down a path to produce something the RTEMS</div><div>Project would find acceptable.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
> This SRS Manager reads requirements written in doorstop format (each<br>
> topic is a doorstop document) and produces the SRS document according with ECSS<br>
> format (the output of the tool are sphinx files, which then are compiled to pdf<br>
> document).<br>
<br>
I do not understand what is meant by "doorstop document"? A work flow may help<br>
where we see the types of data used. I ask this because a document generator<br>
needs to have the requirements data being held somewhere and I do not know where<br>
that is.</blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>
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.<br></blockquote><div><br></div><div>This is a requirement set then which is implemented as a collection of Doorstop YAML files.</div><div><br></div><div>Can this set be changed? Can multiple sets be managed? For example, the ESA SMP Profile</div><div>and another POSIX focused profile.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Does the tool generate ReST format output?<br>
<br>
JV: Yes<br>
<br>
Is the ECSS format a template given to sphinx? We would need to be able to<br>
support other formats.<br>
<br>
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.<br></blockquote><div><br></div><div>If I read this correctly, without this tool (which has issues mentioned earlier),</div><div>there are no requirements and traceability documents produced. The RTEMS<br>Project would just have a set of Doorstop files without much value.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
We typically require HTML _and_ PDF.<br>
<br>
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.<br></blockquote><div><br></div><div>Ironically, I know of a DO-178 Level A product that delivers requirements in browsable,</div><div>hyperlinked HTML. It is really a beauty in action.</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
> Could you indicate how I can integrate our tool into RTEMS git repository?<br>
<br>
Commit access to the repositories is given to people who work with the project<br>
and are active for a period of time. You will need to post changes and get the<br>
support of a core development before the code can be merged.<br></blockquote><div><br></div><div>Commit privileges are earned as Chris points out.</div><div><br></div><div>You will have to submit your work in manageable pieces under an acceptable license.</div><div>You will have to "socialize" it before dumping any code on the RTEMS Project. The</div><div>core developers will have to understand where the tools fit into the project, development</div><div>process, and that they have a chance to be technically acceptably.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
> Should be in rtems-tools? If so, in which place?<br>
<br>
I think this is the best place given the information I have. I would need to<br>
have more detail before I could provide any specific direction here.<br></blockquote><div><br></div><div>All host tools are in rtems-tools so at this point, there isn't another place.</div><div> </div><div>But I agree with Chris. We need more information.<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
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.<br>
<br>
I would like to clearly state I fully support the pre-qual effort and I thank<br>
ESA for making this happen. It is exciting for RTEMS to have this activity.<br></blockquote><div><br></div><div>I couldn't agree with this sentiment more. I am thrilled this is happening.</div><div>We just have to be careful to not "break the project". We have open source</div><div>principles to uphold along with the requirement not to make working with or</div><div>on RTEMS burdensome. We still want a college student to be able to make</div><div>meaningful contributions without being buried or terrified with flight safety.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
JV: Thank you for your words. We hope this tool serves the RTEMS community as much as possible.<br>
<br>
Chris<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div>