<div dir="ltr"><div dir="ltr"><div dir="ltr">Overall, this is really good. I am sure we will polish details as<div>things progress. I marked a few places with notes. Mostly</div><div>grammar or minor points.</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Nov 7, 2019 at 3:24 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</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">---<br>
v2:<br>
<br>
* Updates due to Doorstop improvements, e.g. UID with names, use of SHA256<br>
for item fingerprints, adding custom attributes to the fingerprint.<br>
<br>
* More detailed specification item types.<br>
<br>
* The normal patch review process is now described in the RTEMS User Manual.<br>
<br>
I removed the binary files from the patch. For the generated document see:<br>
<br>
<a href="https://ftp.rtems.org/pub/rtems/people/sebh/eng.pdf" rel="noreferrer" target="_blank">https://ftp.rtems.org/pub/rtems/people/sebh/eng.pdf</a><br>
<br>
Unfortunately, on openSUSE 15.1 the RTEMS branding of the document no longer<br>
works.<br>
<br>
This is still work in progress. It is a good first step from my point of view<br>
from nothing to something. We have to work out the details throughout the next<br>
year.<br>
<br>
eng/index.rst | 1 +<br>
eng/req-eng.rst | 1127 +++++++++++++++++++++++++++++++++++++++++<br>
images/eng/req-add.pdf | Bin 0 -> 81320 bytes<br>
images/eng/req-add.png | Bin 0 -> 50516 bytes<br>
images/eng/req-add.uml | 40 ++<br>
images/eng/req-modify.pdf | Bin 0 -> 68500 bytes<br>
images/eng/req-modify.png | Bin 0 -> 37776 bytes<br>
images/eng/req-modify.uml | 34 ++<br>
images/eng/req-spec-items.pdf | Bin 0 -> 84896 bytes<br>
images/eng/req-spec-items.png | Bin 0 -> 86050 bytes<br>
images/eng/req-spec-items.uml | 60 +++<br>
11 files changed, 1262 insertions(+)<br>
create mode 100644 eng/req-eng.rst<br>
create mode 100644 images/eng/req-add.pdf<br>
create mode 100644 images/eng/req-add.png<br>
create mode 100644 images/eng/req-add.uml<br>
create mode 100644 images/eng/req-modify.pdf<br>
create mode 100644 images/eng/req-modify.png<br>
create mode 100644 images/eng/req-modify.uml<br>
create mode 100644 images/eng/req-spec-items.pdf<br>
create mode 100644 images/eng/req-spec-items.png<br>
create mode 100644 images/eng/req-spec-items.uml<br>
<br>
diff --git a/eng/index.rst b/eng/index.rst<br>
index cfc831b..802eec9 100644<br>
--- a/eng/index.rst<br>
+++ b/eng/index.rst<br>
@@ -26,6 +26,7 @@ RTEMS Software Engineering (|version|)<br>
preface<br>
prequalification<br>
stakeholders<br>
+ req-eng<br>
management<br>
test-plan<br>
test-framework<br>
diff --git a/eng/req-eng.rst b/eng/req-eng.rst<br>
new file mode 100644<br>
index 0000000..8d64f2b<br>
--- /dev/null<br>
+++ b/eng/req-eng.rst<br>
@@ -0,0 +1,1127 @@<br>
+.. SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+.. Copyright (C) 2019 embedded brains GmbH<br>
+<br>
+.. |E40| replace:: ECSS-E-ST-40C<br>
+<br>
+.. |E10-06| replace:: ECSS-E-ST-10-06C<br>
+<br>
+.. _ReqEng:<br>
+<br>
+Software Requirements Engineering<br>
+*********************************<br>
+<br>
+Software engineering standards for critical software such as |E40| demand that<br>
+software requirements for a software product are collected in a software<br>
+requirements specification (technical specification in |E40| terms). They are<br>
+usually derived from system requirements (requirements baseline in |E40|<br>
+terms). RTEMS is designed as a reusable software product which can be utilized<br>
+by application designers to ease the development of their applications. The<br>
+requirements of the end system (system requirements) using RTEMS are only known<br>
+to the application designer. RTEMS itself is developed by the RTEMS<br>
+maintainers and they do not know the requirements of a particular end system in<br>
+general. RTEMS is designed as a real-time operating system to meet typical<br>
+system requirements for a wide range of applications. Its suitability for a<br>
+particular application must be determined by the application designer based on<br>
+the technical specification provided by RTEMS accompanied with performance data<br>
+for a particular target platform.<br><br></blockquote><div>The paragraph below is quite long. I think starting "A key success..." could</div><div>start another paragraph. There is likely another break to be found. The SMP</div><div>could be another paragraph.</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">
+Currently, no technical specification of RTEMS exists in the form of a<br>
+dedicated document. Since the beginning of the RTEMS evolution in the late<br>
+1980s it was developed iteratively. It was never developed in a waterfall<br>
+model. During initial development the RTEID :cite:`Motorola:1988:RTEID` and<br>
+later the ORKID :cite:`VITA:1990:ORKID` draft specifications were used as<br>
+requirements. These were evolving during the development and an iterative<br>
+approach was followed often using simple algorithms and coming back to<br>
+optimise. In 1993 and 1994 a subset of pthreads sufficient to support<br>
+:term:`GNAT` was added as requirements. At this time the Ada tasking was<br>
+defined, however, not implemented in GNAT, so this involved guessing during the<br>
+development. Later some adjustments were made when Ada tasking was actually<br>
+implemented. So, it was consciously iterative with the specifications evolving<br>
+and feedback from performance analysis. Benchmarks published from other real<br>
+time operating systems were used for comparison. Optimizations were carried<br>
+out until the results were comparable. Development was done with distinct<br>
+contractual phases and tasks for development, optimization, and the addition of<br>
+priority inheritance and rate monotonic scheduling. The pthreads requirement<br>
+has grown to be as much POSIX as possible. Portability to FreeBSD to use the<br>
+network stack, USB stack, SD/MMC card stack and device drivers resulted in<br>
+another set of requirements. </blockquote><div><br></div><div>"Portability to FreeBSD" seems inverted from what I think of. We provided</div><div>a FreeBSD device driver kernel interface compatible implementation to </div><div>support hosting FreeBSD kernel code on RTEMS. We didn't port to FreeBSD.</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">The support for symmetric multiprocessing (SMP)<br>
+was a huge driver for change. It was developed step by step and sponsored by<br>
+several independent users with completely different applications and target<br>
+platforms in mind. The high performance OpenMP support introduced the Futex as<br>
+a new synchronization primitive. </blockquote><div><br></div><div>The addition of support for SMP...</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">A key success element of RTEMS is the ability<br>
+to accept changes driven by user needs and still keep the operating system<br>
+stable enough for production systems. Procedures that place a high burden on<br>
+changes are doomed to be discarded by the RTEMS project. We have to keep this<br>
+in mind when we introduce a requirements management work flow which should be<br>
+followed by RTEMS community members and new contributors.<br></blockquote><div><br></div><div>The middle sentence could be in an emphasis box. It is a critical point to this</div><div>entire process.</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 have to put in some effort first into the reconstruction of software<br>
+requirements through reverse engineering using the RTEMS documentation, test<br>
+cases, sources, standard references, mailing list archives, etc. as input.<br>
+Writing a technical specification for the complete RTEMS code base is probably<br>
+a job of several person-years. We have to get started with a moderate feature<br>
+set (e.g. subset of the Classic API) and extend it based on user demands step<br>
+by step.<br>
+<br>
+The development of the technical specification will take place in two phases.<br>
+The first phase tries to establish an initial technical specification for an<br>
+initial feature set. This technical specification will be integrated into<br>
+RTEMS as a big chunk. In the second phase the technical specification is<br>
+modified through arranged procedures. There will be procedures<br>
+<br>
+* to modify existing requirements,<br>
+<br>
+* add new requirements, and<br>
+<br>
+* mark requirements as obsolete.<br>
+<br>
+All procedures should be based on a peer review principles.<br>
+<br>
+Requirements for Requirements<br>
+=============================<br>
+<br>
+.. _ReqEngIdent:<br>
+<br>
+Identification<br>
+--------------<br>
+<br>
+Each requirement shall have a unique identifier (UID). The question is in<br>
+which scope should it be unique? Ideally, it should be universally unique. As<br>
+a best effort approach, the name *RTEMS* shall be used as a part in all<br>
+requirement identifiers. This should ensure that the RTEMS requirements can be<br>
+referenced easily in larger systems. The standard ECSS-E-ST-10-06C recommends<br>
+in section 8.2.6 that the identifier should reflect the type of the requirement<br>
+and the life profile situation. Other standards may have other<br>
+recommendations. To avoid a bias of RTEMS in the direction of ECSS, this<br>
+recommendation will not be followed.<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ The UID of an item (requirement) is defined by its file name without the<br>
+ extension. An UID consists of two parts, the prefix and a name or a number.<br>
+ The parts are divided by an optional separator. The prefix is determined by<br>
+ the document.<br>
+<br>
+The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or<br>
+more component names, and a name. Each part is separated by a "-"<br>
+character. For example, the UID RTEMS-CLASSIC-TASK-CRATERRINVADDR may specify<br>
+that the `rtems_task_create()` directive shall return a status of<br>
+`RTEMS_INVALID_ADDRESS` if the `id` parameter is `NULL`.<br></blockquote><div><br></div><div>The CRATERRINVADDR part is undecipherable to me. Can we have more than 4 letters </div><div>for the method name? :I couldn't figure out what RTEMS had to do with Crates. :)</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>
+.. topic:: Doorstop<br>
+<br>
+ Doorstop uses documents to create namespaces (named a prefix in Doorstop).<br>
+ For the example above, you can create the documents like this:<br>
+<br>
+ .. code-block:: none<br>
+<br>
+ doorstop create -s - RTEMS-CLASSIC -p RTEMS spec/classic<br>
+ doorstop create -s - RTEMS-CLASSIC-TASK -p RTEMS-CLASSIC spec/classic/task<br>
+ doorstop create -s - RTEMS-CLASSIC-SEMAPHORE -p RTEMS-CLASSIC spec/classic/semaphore<br>
+<br>
+ The requirement files are organized in directories.<br>
+<br>
+A initial requirement item hierarchy could be this:<br>
+<br>
+* RTEMS<br>
+<br>
+ * BUILD (building RTEMS BSPs and libraries)<br>
+<br>
+ * CONFIG (application configuration)<br>
+<br>
+ * CLASSIC<br>
+<br>
+ * TASK<br>
+<br>
+ * CRAT* (requirements for `rtems_task_create()`)<br>
+ * DELT* (requirements for `rtems_task_delete()`)<br>
+ * EXIT* (requirements for `rtems_task_exit()`)<br>
+ * GAFF* (requirements for `rtems_task_get_affinity()`)<br>
+ * GPRI* (requirements for `rtems_task_get_priority()`)<br>
+ * GSHD* (requirements for `rtems_task_get_scheduler()`)<br>
+ * IDNT* (requirements for `rtems_task_ident()`)<br>
+ * ISUS* (requirements for `rtems_task_is_suspended()`)<br>
+ * ITER* (requirements for `rtems_task_iterate()`)<br>
+ * MODE* (requirements for `rtems_task_mode()`)<br>
+ * RSRT* (requirements for `rtems_task_restart()`)<br>
+ * RSME* (requirements for `rtems_task_resume()`)<br>
+ * SELF* (requirements for `rtems_task_self()`)<br>
+ * SAFF* (requirements for `rtems_task_set_affinity()`)<br>
+ * SPRI* (requirements for `rtems_task_set_priority()`)<br>
+ * SSHD* (requirements for `rtems_task_set_scheduler()`)<br>
+ * STRT* (requirements for `rtems_task_start()`)<br>
+ * SUSP* (requirements for `rtems_task_suspend()`)<br>
+ * WAFT* (requirements for `rtems_task_wake_after()`)<br>
+ * WWHN* (requirements for `rtems_task_wake_when()`)<br><br></blockquote><div>Some are OK with 4 letters. Others are mysterious. Six letters may be better </div><div>if possible. Hmmm.. The RTEID names were 6 letters prefixed with one or</div><div>two letters for the manager and an underscore. It used to be t_create, etc.</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">
+ * Semaphore<br>
+<br>
+ * ...<br>
+<br>
+ * POSIX<br>
+<br>
+ * ...<br>
+<br>
+The specification of the validation of requirements should be maintained also by<br>
+Doorstop. For each requirement document there should be a validation child<br>
+Doorstop document with a *TEST* component name, e.g. RTEMS-CLASSIC-TASK-TEST. A<br>
+test document may contain also validations by analysis, by inspection, and by<br>
+design, see :ref:`ReqEngValidation`.<br>
+<br>
+Level of Requirements<br>
+---------------------<br>
+<br>
+The level of a requirement shall be expressed with one of the verbal forms<br>
+listed below and nothing else. The level of requirements are derived from RFC<br>
+2119 :cite:`RFC2119` and |E10-06| :cite:`ECSS_E_ST_10_06C`.<br>
+<br>
+Absolute Requirements<br>
+~~~~~~~~~~~~~~~~~~~~~<br>
+<br>
+Absolute requirements shall be expressed with the verbal form *shall* and no<br>
+other terms.<br>
+<br>
+Absolute Prohibitions<br>
+~~~~~~~~~~~~~~~~~~~~~<br>
+<br>
+Absolute prohibitions shall be expressed with the verbal form *shall not* and<br>
+no other terms.<br>
+<br>
+.. warning::<br>
+<br>
+ Absolute prohibitions may be difficult to validate. They should not be<br>
+ used.<br>
+<br>
+Recommendations<br>
+~~~~~~~~~~~~~~~<br>
+<br>
+Recommendations shall be expressed with the verbal forms *should* and<br>
+*should not* and no other terms with guidance from RFC 2119:<br>
+<br>
+ SHOULD This word, or the adjective "RECOMMENDED", mean that there<br>
+ may exist valid reasons in particular circumstances to ignore a<br>
+ particular item, but the full implications must be understood and<br>
+ carefully weighed before choosing a different course.<br>
+<br>
+ SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that<br>
+ there may exist valid reasons in particular circumstances when the<br>
+ particular behavior is acceptable or even useful, but the full<br>
+ implications should be understood and the case carefully weighed<br>
+ before implementing any behavior described with this label.<br>
+<br>
+Permissions<br>
+~~~~~~~~~~~<br>
+<br>
+Permissions shall be expressed with the verbal form *may* and no other terms<br>
+with guidance from RFC 2119:<br>
+<br>
+ MAY This word, or the adjective "OPTIONAL", mean that an item is<br>
+ truly optional. One vendor may choose to include the item because a<br>
+ particular marketplace requires it or because the vendor feels that<br>
+ it enhances the product while another vendor may omit the same item.<br>
+ An implementation which does not include a particular option MUST be<br>
+ prepared to interoperate with another implementation which does<br>
+ include the option, though perhaps with reduced functionality. In the<br>
+ same vein an implementation which does include a particular option<br>
+ MUST be prepared to interoperate with another implementation which<br>
+ does not include the option (except, of course, for the feature the<br>
+ option provides.)<br>
+<br>
+Possibilities and Capabilities<br>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~<br>
+<br>
+Possibilities and capabilities shall be expressed with the verbal form *can*<br>
+and no other terms.<br>
+<br>
+.. _ReqEngSyntax:<br>
+<br>
+Syntax<br>
+------<br>
+<br>
+Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate<br>
+requirements. A recommended reading list to get familiar with this approach is<br>
+:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and<br>
+:cite:`Mavin:2016:LLEARS`. Please also have a look at the EARS quick reference<br>
+sheet :cite:`Uusitalo:2012:EARS`. The sentence types are:<br>
+<br>
+* Ubiquitous<br>
+<br>
+ The <system name> shall <system response>.<br>
+<br>
+* Event-driven<br>
+<br>
+ *When* <optional preconditions> <trigger>, the <system name> shall <system response>.<br>
+<br>
+* State-driven<br>
+<br>
+ *While* <in state>, the <system name> shall <system response>.<br>
+<br>
+* Unwanted behaviour<br>
+<br>
+ *If* <optional preconditions> <trigger>, *then* the <system name> shall <system response>.<br>
+<br>
+* Optional<br>
+<br>
+ *Where* <feature>, the <system name> shall <system response>.<br>
+<br>
+The optional sentence type should be only used for application configuration<br>
+options. The goal is to use *enabled-by* and *disabled-by* attributes to<br>
+enable or disable requirements based on configuration parameters that define<br>
+the RTEMS artefacts used to build an application executable (header files,<br>
+libraries, linker command files). Such configuration parameters are for<br>
+example the architecture, the platform, CPU port options, and build<br>
+configuration options (e.g. uniprocessor vs. SMP).<br>
+<br>
+Wording Restrictions<br>
+--------------------<br>
+<br>
+To prevent the expression of imprecise requirements, the following terms shall<br>
+not be used in requirement formulations:<br>
+<br>
+* "acceptable"<br>
+* "adequate"<br>
+* "almost always"<br>
+* "and/or"<br>
+* "appropriate"<br>
+* "approximately"<br>
+* "as far as possible"<br>
+* "as much as practicable"<br>
+* "best"<br>
+* "best possible"<br>
+* "easy"<br>
+* "efficient"<br>
+* "e.g."<br>
+* "enable"<br>
+* "enough"<br>
+* "etc."<br>
+* "few"<br>
+* "first rate"<br>
+* "flexible"<br>
+* "generally"<br>
+* "goal"<br>
+* "graceful"<br>
+* "great"<br>
+* "greatest"<br>
+* "ideally"<br>
+* "i.e."<br>
+* "if possible"<br>
+* "in most cases"<br>
+* "large"<br>
+* "many"<br>
+* "maximize"<br>
+* "minimize"<br>
+* "most"<br>
+* "multiple"<br>
+* "necessary"<br>
+* "numerous"<br>
+* "optimize"<br>
+* "ought to"<br>
+* "probably"<br>
+* "quick"<br>
+* "rapid"<br>
+* "reasonably"<br>
+* "relevant"<br>
+* "robust"<br>
+* "satisfactory"<br>
+* "several"<br>
+* "shall be included but not limited to"<br>
+* "simple"<br>
+* "small"<br>
+* "some"<br>
+* "state-of-the-art".<br>
+* "sufficient"<br>
+* "suitable"<br>
+* "support"<br>
+* "systematically"<br>
+* "transparent"<br>
+* "typical"<br>
+* "user-friendly"<br>
+* "usually"<br>
+* "versatile"<br>
+* "when necessary"<br>
+<br>
+For guidelines to avoid these terms see Table 11-2, "Some ambiguous terms to<br>
+avoid in requirements" in :cite:`Wiegers:2013:SR`.<br><br></blockquote><div>Good stuff. Are we enforcing this somehow?</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">
+Separate Requirements<br>
+---------------------<br>
+<br>
+Requirements shall be stated separately. A bad example is:<br>
+<br>
+RTEMS-CLASSIC-TASK-CRAT<br>
+ The task create directive shall evaluate the parameters, allocate a task<br>
+ object and initialize it.<br>
+<br>
+To make this a better example, it should be split into separate requirements:<br>
+<br>
+RTEMS-CLASSIC-TASK-CRAT<br>
+ When the task create directive is called with valid parameters and a free<br>
+ task object exists, the task create directive shall assign the identifier of<br>
+ an initialized task object to the id parameter and return the<br>
+ RTEMS_SUCCESSFUL status.<br>
+<br>
+RTEMS-CLASSIC-TASK-CRATERRTOOMANY<br>
+ If no free task objects exists, the task create directive shall return the<br>
+ RTEMS_TOO_MANY status.<br>
+<br>
+RTEMS-CLASSIC-TASK-CRATERRINVADDR<br>
+ If the id parameter is NULL, the task create directive shall return the<br>
+ RTEMS_INVALID_ADDRESS status.<br>
+<br>
+RTEMS-CLASSIC-TASK-CRATERRINVNAME<br>
+ If the name parameter is not valid, the task create directive shall return<br>
+ the RTEMS_INVALID_NAME status.<br>
+<br>
+ ...<br>
+<br>
+Conflict Free Requirements<br>
+--------------------------<br>
+<br>
+Requirements shall not be in conflict with each other inside a specification.<br>
+A bad example is:<br>
+<br>
+RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT<br>
+ If a mutex is not available, the mutex obtain directive shall enqueue the<br>
+ calling thread on the wait queue of the mutex.<br>
+<br>
+RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT<br>
+ If a mutex is not available, the mutex obtain directive shall return the<br>
+ RTEMS_UNSATISFIED status.<br>
+<br>
+To resolve this conflict, a condition may be added:<br>
+<br>
+RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT<br>
+ If a mutex is not available, when the RTEMS_WAIT option is set, the mutex<br>
+ obtain directive shall enqueue the calling thread on the wait queue of the<br>
+ mutex.<br>
+<br>
+RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT<br>
+ If a mutex is not available, when the RTEMS_WAIT option is not set, the<br>
+ mutex obtain directive shall return the RTEMS_UNSATISFIED status.<br>
+<br>
+Use of Project-Specific Terms and Abbreviations<br>
+-----------------------------------------------<br>
+<br>
+All project-specific terms and abbreviations used to formulate requirements<br>
+shall be defined in the project glossary.<br>
+<br>
+.. _ReqEngJustReq:<br>
+<br>
+Justification of Requirements<br>
+-----------------------------<br>
+<br>
+Each requirement shall have a rationale or justification recorded in a<br>
+dedicated section of the requirement file.<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ See *rationale* attribute for :ref:`ReqEngSpecItems`.<br>
+<br>
+.. _ReqEngSpecItems:<br>
+<br>
+Specification Items<br>
+===================<br>
+<br>
+The technical specification of RTEMS will contain requirements, specializations<br>
+of requirements, :ref:`test procedures <ReqEngTestProcedure>`,<br>
+:ref:`test suites <ReqEngTestSuite>`, :ref:`test cases <ReqEngTestCase>`, and<br>
+:ref:`requirement validations <ReqEngValidation>`. These things will be called<br>
+*specification items* or just *items* if it is clear from the context.<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ Doorstop maintains *items* which are included in *documents*. The normal<br>
+ use case is to store a requirement with meta-data in an item. However,<br>
+ items can be also used to store other things like test procedures, test<br>
+ suites, test cases, and requirement validations. Items contain key-value<br>
+ pairs called attributes. Specializations of requirements may contain extra<br>
+ attributes, e.g. interface, build, configuration requirements. All items<br>
+ have the following standard Doorstop attributes:<br>
+<br>
+ active<br>
+ A boolean value which indicates if the requirement is active or not.<br>
+ The value is included in the fingerprint via a document configuration<br>
+ option.<br>
+<br>
+ derived<br>
+ A boolean value which indicates if the requirement is derived or not.<br>
+ For the<br>
+ `definition of derived <<a href="https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#derived" rel="noreferrer" target="_blank">https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#derived</a>>`_.<br>
+ see the Doorstop documentation. For RTEMS, this value shall be false<br>
+ for all requirements. The value is not included in the fingerprint.<br>
+<br>
+ normative<br>
+ A boolean value which indicates if the requirement is normative or not.<br>
+ For the<br>
+ `definition of normative <<a href="https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#normative" rel="noreferrer" target="_blank">https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#normative</a>>`_.<br>
+ see the Doorstop documentation. For RTEMS, this value shall be true<br>
+ for all requirements. The value is not included in the fingerprint.<br>
+<br>
+ level<br>
+ Indicates the presentation order within a document. For RTEMS, this<br>
+ value shall be unused. The value is not included in the fingerprint.<br>
+<br>
+ header<br>
+ A header for an item. For RTEMS, this value shall be the empty string.<br>
+ The value is not included in the fingerprint.<br>
+<br>
+ reviewed<br>
+ The fingerprint of the item. Maintain this attribute with the<br>
+ `doorstop clear` command.<br>
+<br>
+ links<br>
+ The links from this item to parent items. Maintain this attribute with<br>
+ the `doorstop link` command. The value is included in the fingerprint.<br>
+<br>
+ ref<br>
+ References to files and directories. See<br>
+ `#365 <<a href="https://github.com/jacebrowning/doorstop/issues/365" rel="noreferrer" target="_blank">https://github.com/jacebrowning/doorstop/issues/365</a>>`_,<br>
+ The value is included in the fingerprint.<br>
+<br>
+ text<br>
+ The item text. The value is included in the fingerprint.<br>
+<br>
+ All items shall have the following extended attributes:<br>
+<br>
+ type:<br>
+ A list of :ref:`item types <ReqEngItemTypes>`. The value is not<br>
+ included in the fingerprint.<br>
+<br>
+ enabled-by:<br>
+ The value is a list of expressions. The value is included in the<br>
+ fingerprint. An expression is an operator or an option. An option<br>
+ evaluates to true if it is set in the configuration. An operator is a<br>
+ dictionary with exactly one key and a value. The value of the `not`<br>
+ operator shall be an expression. It negates the outcome of its<br>
+ expression. The value of the `and` operator shall be a list of<br>
+ expressions. It evaluates to the logical and of all outcomes of the<br>
+ expressions in the list. The outcome of a list of expressions is the<br>
+ logical or of all outcomes of the expressions in the list. Example:<br>
+<br>
+ .. code-block:: none<br>
+<br>
+ enabled-by:<br>
+ - OPT1<br>
+ - OPT2<br>
+ - not: OPT3<br>
+ - and:<br>
+ - OPT4<br>
+ - OPT5<br>
+ - not:<br>
+ - OPT6<br>
+ - OPT7<br><br></blockquote><div>Do you have an example from RTEMS for this?</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">
+ rationale:<br>
+ The rationale or justification of the specification item. The value is<br>
+ **not** included in the fingerprint.<br>
+<br>
+.. _ReqEngItemTypes:<br>
+<br>
+Item Types<br>
+----------<br>
+<br>
+Specification items can have all sorts of *types*. The selection of types and the<br>
+level of detail depends on a particular standard and product model. We need<br>
+enough flexibility to be in line with ECSS-E-ST-10-06 and possible future<br>
+applications of other standards. Each item may have a list of types. Valid<br>
+types are listed below. This list may change over time. If new types are<br>
+added, then a mapping between types should be specified. The item types and<br>
+their definition is work in progress. A list of types follows:<br>
+<br>
+* functional requirements - Functional requirements shall describe the behaviour of the<br>
+ software product under specific conditions.<br>
+<br>
+ * *capability*<br>
+<br>
+ * *dependability-function*<br>
+<br>
+ * *function*<br>
+<br>
+ * *operational* - Operational requirements shall<br>
+<br>
+ * define the operation modes (e.g. initialization, multitasking, termination),<br>
+<br>
+ * describe the operation modes, and<br>
+<br>
+ * describe the operation mode transitions.<br>
+<br>
+ * *safety-function*<br>
+<br>
+* non-functional requirements<br>
+<br>
+ * *build-configuration*<br>
+<br>
+ * *constraint*<br>
+<br>
+ * *design*<br>
+<br>
+ * *interface*<br>
+<br>
+ * *interface-requirement*<br>
+<br>
+ * *maintainability*<br>
+<br>
+ * *performance*<br>
+<br>
+ * *portability*<br>
+<br>
+ * *quality*<br>
+<br>
+ * *reliability*<br>
+<br>
+ * *resource*<br>
+<br>
+ * *safety*<br>
+<br>
+* *test-procedure*<br>
+<br>
+* *test-suite*<br>
+<br>
+* *test-case*<br>
+<br>
+* *validation-by-analysis*<br>
+<br>
+* *validation-by-inspection*<br>
+<br>
+* *validation-by-review-of-design*<br>
+<br>
+* *validation-platform*<br>
+<br>
+.. image:: ../images/eng/req-spec-items.*<br>
+ :scale: 70<br>
+ :align: center<br>
+<br>
+Build Configuration<br>
+-------------------<br>
+<br>
+Build configuration requirements define what needs to be built (libraries,<br>
+object files, test executables, etc.) and how (configuration option header<br>
+files, compiler flags, linker flags, etc.). The goal is to generate build<br>
+files (Makefile or waf) and content for the Software Configuration File (SCF)<br>
+from it. A YAML scheme needs to be defined for this purpose.<br>
+<br>
+.. _ReqEngInterfaceReq:<br>
+<br>
+Interface Requirement<br>
+---------------------<br>
+<br>
+Interface requirements shall describe the high level aspects of interfaces.<br>
+The item type shall be *interface-requirement*.<br>
+<br>
+.. _ReqEngInterface:<br>
+<br>
+Interface<br>
+---------<br>
+<br>
+Interface items shall specify the interface of the software product to other<br>
+software products and the hardware. The item type shall be *interface*. The<br>
+interface items shall have an *interface-category* which is one of the<br>
+following and nothing else:<br>
+<br>
+* *application*: Application interface items shall describe the interface<br>
+ between the software product and the application (:term:`API`). The goal is<br>
+ to generate header files with Doxygen markup and user manual documentation<br>
+ parts from the application interface specification.<br>
+<br>
+* *application-configuration*: Application configuration items shall define<br>
+ parameters of the software product which can be set by the application at<br>
+ link-time. The goal is to generate user manual documentation parts and test<br>
+ cases from the application configuration specification.<br>
+<br>
+* *architecture*: Architecture interface items shall define the<br>
+ interface between the software product and the processor architecture<br>
+ (:term:`ABI`).<br>
+<br>
+* *gcc*: GCC interface items shall define the interface between the software<br>
+ product and GCC components such as libgcc.a, libatomic.a, libgomp.a,<br>
+ libstdc++.a, etc.<br>
+<br>
+* *hardware*: Hardware interface items shall define the interface between the<br>
+ software product and the hardware.<br>
+<br>
+* *newlib*: Newlib interface items shall define the interface between the<br>
+ software product and the Newlib (libc.a).<br>
+<br>
+The interface items shall have an *interface-type* which is one of the<br>
+following and nothing else:<br>
+<br>
+* *configuration-option*<br>
+<br>
+* *define*<br>
+<br>
+* *enum*<br>
+<br>
+* *function*<br>
+<br>
+* *header*<br>
+<br>
+* *macro*<br>
+<br>
+* *register-block*<br>
+<br>
+* *structure*<br>
+<br>
+* *typedef*<br>
+<br>
+* *union*<br>
+<br>
+* *variable*<br>
+<br>
+.. _ReqEngInterfaceApplicationConfig:<br>
+<br>
+Interface - Application Configuration<br>
+-------------------------------------<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ The application configuration items shall have the following attribute<br>
+ specializations:<br>
+<br>
+ type<br>
+ The type value shall be *interface*.<br>
+<br>
+ interface-category<br>
+ The interface category value shall be *application-configuration*.<br>
+<br>
+ interface-type<br>
+ The interface type value shall be *configuration-option*.<br>
+<br>
+ link<br>
+ There shall be a link to a higher level requirement.<br>
+<br>
+ text<br>
+ The application configuration requirement.<br>
+<br>
+ configuration-category:<br>
+ A category to which this application configuration option belongs.<br>
+<br>
+ define:<br>
+ The name of the configuration define.<br>
+<br>
+ data-type:<br>
+ The data type of the configuration define.<br>
+<br>
+ value-range:<br>
+ The range of valid values.<br>
+<br>
+ default-value:<br>
+ The default value.<br>
+<br>
+ description:<br>
+ The description of the application configuration. The description<br>
+ should focus on the average use-case. It should not cover potential<br>
+ problems, constraints, obscure use-cases, corner cases and everything<br>
+ which makes matters complicated.<br>
+<br>
+ note:<br>
+ Notes for this application configuration. The notes should explain<br>
+ everything which was omitted from the description. It should cover all<br>
+ the details.<br>
+<br>
+.. _ReqEngTestProcedure:<br>
+<br>
+Test Procedure<br>
+--------------<br>
+<br>
+Test procedures shall be executed by the Qualification Toolchain.<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ The test procedure items shall have the following attribute<br>
+ specializations:<br>
+<br>
+ type<br>
+ The type value shall be *test-procedure*.<br>
+<br>
+ text<br>
+ The purpose of this test procedure.<br>
+<br>
+ platform<br>
+ There shall be links to validation platform requirements.<br>
+<br>
+ steps<br>
+ The test procedure steps. Could be a list of key-value pairs. The key<br>
+ is the step name and the value is a description of the actions<br>
+ performed in this step.<br>
+<br>
+.. _ReqEngTestSuite:<br>
+<br>
+Test Suite<br>
+----------<br>
+<br>
+Test suites shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ The test suite items shall have the following attribute specializations:<br>
+<br>
+ type<br>
+ The type value shall be *test-suite*.<br>
+<br>
+ text<br>
+ The test suite description.<br>
+<br>
+.. _ReqEngTestCase:<br>
+<br>
+Test Case<br>
+---------<br>
+<br>
+Test cases shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.<br>
+<br>
+.. topic:: Doorstop<br>
+<br>
+ The test case items shall have the following attribute specializations:<br>
+<br>
+ type<br>
+ The type value shall be *test-case*.<br>
+<br>
+ link<br>
+ The link to the requirement validated by this test case or no links if<br>
+ this is a unit or integration test case.<br>
+<br>
+ ref<br>
+ If this is a unit test case, then a reference to the :term:`software<br>
+ item` under test shall be provided. If this is an integration test<br>
+ case, then a reference to the integration under test shall be provided.<br>
+ The integration is identified by its Doxygen group name.<br>
+<br>
+ text<br>
+ A short description of the test case.<br>
+<br>
+ inputs<br>
+ The inputs to execute the test case.<br>
+<br>
+ outputs<br>
+ The expected outputs.<br>
+<br>
+ The test case code may be also contained in the test case specification<br>
+ item in a *code* attribute. This is subject to discussion on the RTEMS<br>
+ mailing list. Alternatively, the test code could be placed directly in<br>
+ source files. A method is required to find the test case specification of<br>
+ a test case code and vice versa.<br>
+<br>
+.. _ReqEngResAndPerf:<br>
+<br>
+Resources and Performance<br>
+-------------------------<br>
+<br>
+Normally, resource and performance requirements are formulated like this:<br>
+<br>
+* The resource U shall need less than V storage units.<br>
+<br>
+* The operation Y shall complete within X time units.<br>
+<br>
+Such statements are difficult to make for a software product like RTEMS which<br>
+runs on many different target platforms in various configurations. So, the<br>
+performance requirements of RTEMS shall be stated in terms of benchmarks. The<br>
+benchmarks are run on the project-specific target platform and configuration.<br>
+The results obtained by the benchmark runs are reported in a human readable<br>
+presentation. The application designer can then use the benchmark results to<br>
+determine if its system performance requirements are met. The benchmarks shall<br>
+be executed under different environment conditions, e.g. varying cache states<br>
+(dirty, empty, valid) and system bus load generated by other processors. The<br>
+application designer shall have the ability to add additional environment<br>
+conditions, e.g. system bus load by DMA engines or different system bus<br>
+arbitration schemes.<br>
+<br>
+To catch resource and performance regressions via test suite runs there shall be<br>
+a means to specify threshold values for the measured quantities. The threshold<br>
+values should be provided for each validation platform. How this can be done<br>
+and if the threshold values are maintained by the RTEMS Project is subject to<br>
+discussion.<br><br></blockquote><div>We focused on big-O and whether methods were constant time, bounded, or O(n)</div><div>when designing. Perhaps the focus could be there. But this is a design goal for all</div><div>of RTEMS and something we would document. Nothing to do except a general</div><div>design goal.</div><div><br></div><div>This section also sounds like part of what is required by a systems integrator</div><div>when leveraging what the FAA calls a Reusable Software Component:</div><div><br></div><div><a href="https://www.faa.gov/regulations_policies/advisory_circulars/index.cfm/go/document.information/documentID/22207">https://www.faa.gov/regulations_policies/advisory_circulars/index.cfm/go/document.information/documentID/22207</a> </div><div><br></div><div>You get credit for what's common and have to fill in details for your system.</div><div> <br></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">
+.. _ReqEngTrace:<br>
+<br>
+Traceability of Specification Items<br>
+===================================<br>
+<br>
+The standard |E10-06| demands that requirements shall be under configuration<br>
+management, backwards-traceable and forward-traceable. Requirements are a<br>
+specialization of specification items in RTEMS.<br>
+<br>
+.. _ReqEngTraceHistory:<br>
+<br>
+History of Specification Items<br>
+------------------------------<br>
+<br>
+The RTEMS specification items should placed in the RTEMS sources using Git for<br>
+version control. The history of specification items can be traced with Git.<br>
+Special commit procedures for changes in specification item files should be<br>
+established. For example, it should be allowed to change only one<br>
+specification item per commit. A dedicated Git commit message format may be<br>
+used as well, e.g. use of ``Approved-by:`` or ``Reviewed-by:`` lines which<br>
+indicate an agreed statement (similar to the<br>
+`Linux kernel patch submission guidelines <<a href="https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes" rel="noreferrer" target="_blank">https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes</a>>`_).<br>
+Git commit procedures may be ensured through a server-side pre-receive hook.<br>
+The history of requirements may be also added to the specification items<br>
+directly in a ``revision`` attribute. This would make it possible to generate<br>
+the history information for documents without having the Git repository<br>
+available, e.g. from an RTEMS source release archive.<br>
+<br>
+.. _ReqEngTraceBackward:<br>
+<br>
+Backward Traceability of Specification Items<br>
+--------------------------------------------<br>
+<br>
+Providing backward traceability of specification items means that we must be<br>
+able to find the corresponding higher level specification item for each refined<br>
+specification item. This is a standard Doorstop feature.<br>
+<br>
+.. _ReqEngTraceForward:<br>
+<br>
+Forward Traceability of Specification Items<br>
+-------------------------------------------<br>
+<br>
+Providing forward traceability of specification items means that we must be<br>
+able to find all the refined specification items for each higher level<br>
+specification item. This is a standard Doorstop feature. The links from<br>
+parent to child specification items are implicitly defined by links from a<br>
+child item to a parent item.<br>
+<br>
+.. _ReqEngTraceReqArchDesign:<br>
+<br>
+Traceability between Software Requirements, Architecture and Design<br>
+-------------------------------------------------------------------<br>
+<br>
+The software requirements are implemented in Doorstop compatible YAML files.<br>
+The software architecture and design is written in Doxygen markup. Doxygen<br>
+markup is used throughout all header and source files. A Doxygen filter<br>
+program may be provided to place Doxygen markup in assembler files. The<br>
+software architecture is documented via Doxygen groups. Each Doxygen group<br>
+name should have a project-specific name and the name should be unique within<br>
+the project, e.g. RTEMSTopLevel\ MidLevel\ LowLevel. The link from a Doxygen<br>
+group to its parent group is realized through the `@ingroup` special command.<br>
+The link from a Doxygen group or software component to the corresponding<br>
+requirement is realized through a `@satisfy{req}`<br>
+`custom command <<a href="http://www.doxygen.nl/manual/custcmd.html" rel="noreferrer" target="_blank">http://www.doxygen.nl/manual/custcmd.html</a>>`_<br>
+which needs the identifier of the requirement as its one and only parameter.<br>
+Only links to parents are explicitly given in the Doxygen markup. The links<br>
+from a parent to its children are only implicitly specified via the link from a<br>
+child to its parent. So, a tool must process all files to get the complete<br>
+hierarchy of software requirements, architecture and design. Links from a<br>
+software component to another software component are realized through automatic<br>
+Doxygen references or the ``@ref`` and ``@see`` special commands.<br>
+<br>
+.. _ReqEngValidation:<br>
+<br>
+Requirement Validation<br>
+======================<br>
+<br>
+The validation of each requirement shall be accomplished by one or more of<br>
+the following methods and nothing else:<br>
+<br>
+* *By test*: A :ref:`ReqEngTestCase` specification item is provided to<br>
+ demonstrate that the requirement is satisfied when the software product is<br>
+ executed on the target platform.<br>
+<br>
+* *By analysis*: A statement is provided how the requirement is met, by<br>
+ analysing static properties of the software product.<br>
+<br>
+* *By inspection*: A statement is provided how the requirement is met, by<br>
+ inspection of the :term:`source code`.<br>
+<br>
+* *By review of design*: A rationale is provided to demonstrate how the<br>
+ qualification requirement is satisfied implicitly by the software design.<br>
+<br>
+Validation by test is strongly recommended. The choice of any other validation<br>
+method shall be justified.<br></blockquote><div><br></div><div>I would say that if it isn't by test, then the requirements author is obligated to</div><div>provide the means to verify the requirement and instructions. They provide the</div><div>design artifacts, etc. You can't throw us a verify by inspection without telling</div><div>us what to inspect, how to do it, and providing the artifact to inspect. This is</div><div>not a new project and each requirement added comes with an obligation.</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>
+.. topic:: Doorstop<br>
+<br>
+ For an item in a parent document it is checked that at least one item in a<br>
+ child document has a link to it. For example a child document could<br>
+ contain validation items. With this feature you can check that all<br>
+ requirements are covered by at least one validation item.<br>
+<br>
+ The requirement validation by analysis, by inspection, and by design<br>
+ specification items shall have the following attribute specializations:<br>
+<br>
+ type<br>
+ The type attribute value shall be *validation-by-analysis*,<br>
+ *validation-by-inspection*, or *validation-by-review-of-design*.<br>
+<br>
+ link<br>
+ There shall be exactly one link to the validated requirement.<br>
+<br>
+ text<br>
+ The statement or rational of the requirement validation.<br>
+<br>
+Requirement Management<br>
+======================<br>
+<br>
+Change Control Board<br>
+--------------------<br>
+<br>
+Working with requirements usually involves a Change Control Board<br>
+(:term:`CCB`). The CCB of the RTEMS project is the<br>
+`RTEMS developer mailing list <<a href="https://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">https://lists.rtems.org/mailman/listinfo/devel</a>>`_.<br>
+<br>
+There are the following actors involved:<br>
+<br>
+* *RTEMS users*: Everyone using the RTEMS real-time operating system to design,<br>
+ develop and build an application on top of it.<br>
+<br>
+* *RTEMS developers*: The persons developing and maintaining RTEMS. They write<br>
+ patches to add or modify code, requirements, tests and documentation.<br>
+<br>
+* *RTEMS maintainers*: They are listed in the<br>
+ `MAINTAINERS <<a href="https://git.rtems.org/rtems/tree/MAINTAINERS" rel="noreferrer" target="_blank">https://git.rtems.org/rtems/tree/MAINTAINERS</a>>`_ file and have<br>
+ write access to the project repositories.<br>
+<br>
+Adding and changing requirements follows the normal patch review process. The<br>
+normal patch review process is described in the<br>
+`RTEMS User Manual <<a href="https://docs.rtems.org/branches/master/user/support/contrib.html#patch-review-process" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/user/support/contrib.html#patch-review-process</a>>`_.<br>
+Reviews and comments may be submitted by anyone, but a maintainer review is<br>
+required to approve *significant* changes. In addition for significant<br>
+changes, there should be at least one reviewer with a sufficient independence<br>
+from the author which proposes a new requirement or a change of an existing<br>
+requirement. Working in another company on different projects is sufficiently<br>
+independent. RTEMS maintainers do not know all the details, so they trust in<br>
+general people with experience on a certain platform. Sometimes no review<br>
+comments may appear in a reasonable time frame, then an implicit agreement to<br>
+the proposed changes is assumed. Patches can be sent at anytime, so<br>
+controlling changes in RTEMS requires a permanent involvement on the RTEMS<br>
+developer mailing list.<br>
+<br>
+For a qualification of RTEMS according to certain standards, the requirements<br>
+may be approved by an RTEMS user. The approval by RTEMS users is not the<br>
+concern of the RTEMS project, however, the RTEMS project should enable RTEMS<br>
+users to manage the approval of requirements easily. This information may be<br>
+also used by a independent authority which comes into play with an Independent<br>
+Software Verification and Validation (:term:`ISVV`). It could be used to<br>
+select a subset of requirements, e.g. look only at the ones approved by a<br>
+certain user. RTEMS users should be able to reference the determinative<br>
+content of requirements, test procedures, test cases and justification reports<br>
+in their own documentation. Changes in the determinative content should<br>
+invalidate all references to previous versions.<br>
+<br>
+Add a Requirement<br>
+-----------------<br>
+<br>
+.. image:: ../images/eng/req-add.*<br>
+ :scale: 70<br>
+ :align: center<br>
+<br>
+.. _ReqEngModifyRequirement:<br>
+<br>
+Modify a Requirement<br>
+--------------------<br>
+<br>
+.. image:: ../images/eng/req-modify.*<br>
+ :scale: 70<br>
+ :align: center<br>
+<br>
+Mark a Requirement as Obsolete<br>
+------------------------------<br>
+<br>
+Requirements shall be never removed. They shall be marked as obsolete. This<br>
+ensures that requirement identifiers are not reused. The procedure to obsolete<br>
+a requirement is the same as the one to :ref:`modify a requirement<br>
+<ReqEngModifyRequirement>`.<br>
+<br>
+Tooling<br>
+=======<br>
+<br>
+Tool Requirements<br>
+-----------------<br>
+<br>
+To manage requirements some tool support is helpful. Here is a list of requirements for the tool:<br>
+<br>
+* The tool shall be open source.<br>
+<br>
+* The tool should be actively maintained during the initial phase of the RTEMS<br>
+ requirements specification.<br>
+<br>
+* The tool shall use plain text storage (no binary formats, no database).<br>
+<br>
+* The tool shall support version control via Git.<br>
+<br>
+* The tool should export the requirements in a human readable form using the Sphinx documentation framework.<br>
+<br>
+* The tool shall support traceability of requirements to items external to the tool.<br>
+<br>
+* The tool shall support traceability between requirements.<br>
+<br>
+* The tool shall support custom requirement attributes.<br>
+<br>
+* The tool should ensure that there are no cyclic dependencies between requirements.<br>
+<br>
+* The tool should provide an export to :term:`ReqIF`.<br>
+<br>
+<br>
+Tool Evaluation<br>
+---------------<br>
+<br>
+During an evaluation phase the following tools were considered:<br>
+<br>
+* `aNimble <<a href="https://sourceforge.net/projects/nimble/" rel="noreferrer" target="_blank">https://sourceforge.net/projects/nimble/</a>>`_<br>
+* :term:`Doorstop`<br>
+* `OSRMT <<a href="https://github.com/osrmt/osrmt" rel="noreferrer" target="_blank">https://github.com/osrmt/osrmt</a>>`_<br>
+* `Papyrus <<a href="https://www.eclipse.org/papyrus/" rel="noreferrer" target="_blank">https://www.eclipse.org/papyrus/</a>>`_<br>
+* `ProR <<a href="https://www.eclipse.org/rmf/pror/" rel="noreferrer" target="_blank">https://www.eclipse.org/rmf/pror/</a>>`_<br>
+* `ReqIF Studio <<a href="https://formalmind.com/tools/studio/" rel="noreferrer" target="_blank">https://formalmind.com/tools/studio/</a>>`_<br>
+* `Requirement Heap <<a href="https://sourceforge.net/projects/reqheap/" rel="noreferrer" target="_blank">https://sourceforge.net/projects/reqheap/</a>>`_<br>
+* `rmToo <<a href="http://rmtoo.florath.net/" rel="noreferrer" target="_blank">http://rmtoo.florath.net/</a>>`_<br>
+<br>
+The tools aNimble, OSRMT and Requirement Heap were not selected since they use<br>
+a database. The tools Papyrus, ProR and ReqIF are Eclipse based and use<br>
+complex XML files for data storage. They were difficult to use and lack good<br>
+documentation/tutorials. The tools rmToo and Doorstop turned out to be the<br>
+best candidates to manage requirements in the RTEMS project. The Doorstop tool<br>
+was selected as the first candidate mainly due a recommendation by an RTEMS<br>
+user.<br>
+<br>
+Selected Tool - Doorstop<br>
+------------------------<br>
+<br>
+:term:`Doorstop` is a requirements management tool. It has a modern,<br>
+object-oriented and well-structured implementation in Python 3.6 under the<br>
+LGPLv3 license. It uses a continuous integration build with style checkers,<br>
+static analysis, documentation checks, code coverage, unit test and integration<br>
+tests. In 2019, the project was actively maintained. Pull requests for minor<br>
+improvements and new features were reviewed and integrated within days. Each<br>
+requirement is contained in a single file in :term:`YAML` format. Requirements<br>
+are organized in documents and can be linked to each other<br>
+:cite:`Browning:2014:RequirementsManagement`.<br>
+<br>
+Doorstop consists of three main parts<br>
+<br>
+* a stateless command line tool `doorstop`,<br>
+<br>
+* a file format with a pre-defined set of attributes (YAML), and<br>
+<br>
+* a primitive GUI tool (not intended to be used).<br>
+<br>
+For RTEMS, its scope will be extended to manage specifications in general. The<br>
+primary reason for selecting Doorstop as the requirements management tool for<br>
+the RTEMS Project is its data format which allows a high degree of customization. Doorstop uses a directed, acyclic graph of<br>
+items. The items are files in YAML format. Each item has a set of<br>
+`standard attributes <<a href="https://doorstop.readthedocs.io/en/latest/reference/item/" rel="noreferrer" target="_blank">https://doorstop.readthedocs.io/en/latest/reference/item/</a>>`_<br>
+(key-value pairs).<br><br></blockquote><div><br></div><div>Paragraph has a line which seems too long</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">
+The use case for the standard attributes is requirements management. However,<br>
+Doorstop is capable to manage custom attributes as well. We will heavily use<br>
+custom attributes for the specification items. Enabling Doorstop to effectively<br>
+use custom attributes was done specifically for the RTEMS Project in several<br>
+patch sets.<br>
+<br>
+A key feature of Doorstop is the `fingerprint of items<br>
+<<a href="https://doorstop.readthedocs.io/en/latest/reference/item/#reviewed" rel="noreferrer" target="_blank">https://doorstop.readthedocs.io/en/latest/reference/item/#reviewed</a>>`_.<br>
+For the RTEMS Project, the fingerprint hash algorithm was changed from MD5 to<br>
+SHA256. In 2019, it can be considered cryptographically secure. The<br>
+fingerprint should cover the normative values of an item, e.g. comments etc. are<br>
+not included. The fingerprint helps RTEMS users to track the significant<br>
+changes in the requirements (in contrast to all the changes visible in Git). As<br>
+an example use case, a user may want to assign a project-specific status to<br>
+specification items. This can be done with a table which contains columns for <br>
+<br>
+1. the UID of the item,<br>
+<br>
+2. the fingerprint, and<br>
+<br>
+3. the project-specific status.<br>
+<br>
+Given the source code of RTEMS (which includes the specification items) and this<br>
+table, it can be determined which items are unchanged and which have another<br>
+status (e.g. unknown, changed, etc.).<br>
diff --git a/images/eng/req-add.uml b/images/eng/req-add.uml<br>
new file mode 100644<br>
index 0000000..52b01f0<br>
--- /dev/null<br>
+++ b/images/eng/req-add.uml<br>
@@ -0,0 +1,40 @@<br>
+' SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+' Copyright (C) 2019 embedded brains GmbH<br>
+<br>
+@startuml<br>
+<br>
+start<br>
+<br>
+:Invoke: ""doorstop add RTEMS"";<br>
+<br>
+note right<br>
+ This will create a new requirement.<br>
+ For this activity its UID shall be NEW.<br>
+ It is located in a file NEW.yml.<br>
+end note<br>
+<br>
+while (Needs a link to a parent requirement?) is (Yes)<br>
+ :Invoke: ""doorstop link NEW PARENT"";<br>
+endwhile (No)<br>
+<br>
+repeat<br>
+ :Invoke: ""doorstop edit NEW"";<br>
+<br>
+ :Edit the requirement according to your needs and save it;<br>
+<br>
+ :Commit NEW.yml with a proper message;<br>
+<br>
+ :Send the patch to the <a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a> mailing list for review;<br>
+repeat while (Reviewers demand changes in the new requirement?) is (Yes)<br>
+->No;<br>
+<br>
+if (New requirement was accepted by reviewers?) then (Yes)<br>
+ :Push the commit to the project repository;<br>
+else (No)<br>
+ :Discard the NEW requirement;<br>
+endif<br>
+<br>
+stop<br>
+<br>
+@enduml<br>
diff --git a/images/eng/req-modify.uml b/images/eng/req-modify.uml<br>
new file mode 100644<br>
index 0000000..cb104a6<br>
--- /dev/null<br>
+++ b/images/eng/req-modify.uml<br>
@@ -0,0 +1,34 @@<br>
+' SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+' Copyright (C) 2019 embedded brains GmbH<br>
+<br>
+@startuml<br>
+<br>
+start<br>
+<br>
+repeat<br>
+ :Invoke: ""doorstop edit REQ"";<br>
+<br>
+ note right<br>
+ For this activity the UID<br>
+ of the requirement shall be REQ.<br>
+ It is located in a file REQ.yml.<br>
+ end note<br>
+<br>
+ :Edit the requirement according to your needs and save it;<br>
+<br>
+ :Commit REQ.yml with a proper message;<br>
+<br>
+ :Send the patch to the <a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a> mailing list for review;<br>
+repeat while (Reviewers demand changes in the modified requirement?) is (Yes)<br>
+->No;<br>
+<br>
+if (Modified requirement was accepted by reviewers?) then (Yes)<br>
+ :Push the commit to the project repository;<br>
+else (No)<br>
+ :Keep the requirement as is;<br>
+endif<br>
+<br>
+stop<br>
+<br>
+@enduml<br>
diff --git a/images/eng/req-spec-items.uml b/images/eng/req-spec-items.uml<br>
new file mode 100644<br>
index 0000000..f837a85<br>
--- /dev/null<br>
+++ b/images/eng/req-spec-items.uml<br>
@@ -0,0 +1,60 @@<br>
+' SPDX-License-Identifier: CC-BY-SA-4.0<br>
+<br>
+' Copyright (C) 2019 embedded brains GmbH<br>
+<br>
+@startuml<br>
+<br>
+class SpecificationItem {<br>
+ active<br>
+ derived<br>
+ enabled-by<br>
+ header<br>
+ level<br>
+ links<br>
+ normative<br>
+ rationale<br>
+ ref<br>
+ reviewed<br>
+ text<br>
+ type<br>
+}<br>
+<br>
+class Interface {<br>
+ interface-category<br>
+ interface-type<br>
+}<br>
+<br>
+class TestProcedure {<br>
+ platform<br>
+ steps<br>
+}<br>
+<br>
+class TestCase {<br>
+ inputs<br>
+ outputs<br>
+}<br>
+<br>
+class TestCase<br>
+<br>
+note right: test cases not validating\na requirement are unit tests<br>
+<br>
+SpecificationItem <|-- Requirement<br>
+Requirement <|-- Functional<br>
+Requirement <|-- NonFunctional<br>
+NonFunctional <|-- Interface<br>
+SpecificationItem <|-- TestProcedure<br>
+SpecificationItem <|-- TestSuite<br>
+SpecificationItem <|-- TestCase<br>
+SpecificationItem <|-- Validation\nByAnalysis<br>
+SpecificationItem <|-- Validation\nByInspection<br>
+SpecificationItem <|-- Validation\nByReviewOfDesign<br>
+SpecificationItem <|-- ValidationPlatform<br>
+TestProcedure "1..n" -- TestSuite : "run by"<br>
+TestSuite "1..n" -- TestCase : "contained in"<br>
+ValidationPlatform "1..n" -- TestProcedure : "requires"<br>
+Requirement "0..1" -- TestCase : "validates"<br>
+Requirement "1" -- Validation\nByAnalysis : "validates"<br>
+Requirement "1" -- Validation\nByInspection : "validates"<br>
+Requirement "1" -- Validation\nByReviewOfDesign : "validates"<br>
+<br>
+@enduml<br>
-- <br>
2.16.4<br>
<br>
<br>
<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></div>