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