eng: Add generated documentation of spec items

The documentation of the specification items is generated by an RTEMS
qualification tool from a specification of specification items.

Move non-generated content to "req-for-req.rst".

Update #3715.

eng/glossary.rst

@@ -9,9 +9,6 @@ Glossary
 .. glossary::
     :sorted:
 
-    ABI
-        An acronym for Application Binary Interface.
-
     API
         An acronym for Application Programming Interface.
 
@@ -103,9 +100,6 @@ Glossary
         linker) such as jump tables, linker trampolines, exception frame information,
         etc.
 
-    software item
-        This term has the same meaning as :term:`software product`.
-
     software product
         The *software product* is the :term:`RTEMS` real-time operating system.
 

eng/req/index.rst

@@ -86,7 +86,6 @@ All procedures should be based on a peer review principles.
 
     req-for-req
     items
-    validation
     traceability
     management
     tooling

eng/req/req-for-req.rst

@@ -346,4 +346,49 @@ Justification of Requirements
 
 Each requirement shall have a rationale or justification recorded in a
 dedicated section of the requirement file.  See *rationale* attribute for
-:ref:`ReqEngSpecItems`.
+:ref:`ReqEngSpecificationItems`.
+
+.. _ReqEngValidation:
+
+Requirement Validation
+----------------------
+
+The validation of each :ref:`SpecTypeRequirementItemType` item shall be
+accomplished by one or more specification items of the types
+:ref:`SpecTypeTestCaseItemType` or :ref:`SpecTypeRequirementValidationItemType`
+through a link from the validation item to the requirement item with the
+:ref:`SpecTypeRequirementValidationLinkRole`.
+
+Validation by test is strongly recommended.  The choice of any other validation
+method shall be strongly justified.  The requirements author is obligated to
+provide the means to validate the requirement with detailed instructions.
+
+.. _ReqEngResAndPerf:
+
+Resources and Performance
+-------------------------
+
+Normally, resource and performance requirements are formulated like this:
+
+* The resource U shall need less than V storage units.
+
+* The operation Y shall complete within X time units.
+
+Such statements are difficult to make for a software product like RTEMS which
+runs on many different target platforms in various configurations.  So, the
+performance requirements of RTEMS shall be stated in terms of benchmarks.  The
+benchmarks are run on the project-specific target platform and configuration.
+The results obtained by the benchmark runs are reported in a human readable
+presentation.  The application designer can then use the benchmark results to
+determine if its system performance requirements are met.  The benchmarks shall
+be executed under different environment conditions, e.g. varying cache states
+(dirty, empty, valid) and system bus load generated by other processors.  The
+application designer shall have the ability to add additional environment
+conditions, e.g. system bus load by DMA engines or different system bus
+arbitration schemes.
+
+To catch resource and performance regressions via test suite runs there shall be
+a means to specify threshold values for the measured quantities.  The threshold
+values should be provided for each validation platform.  How this can be done
+and if the threshold values are maintained by the RTEMS Project is subject to
+discussion.

eng/req/traceability.rst

@@ -57,20 +57,21 @@ Traceability between Software Requirements, Architecture and Design
 -------------------------------------------------------------------
 
 The software requirements are implemented in custom YAML files, see
-:ref:`ReqEngSpecItems`.  The software architecture and design is written in
+:ref:`ReqEngSpecificationItems`.  The software architecture and design is
-Doxygen markup.  Doxygen markup is used throughout all header and source files.
+written in Doxygen markup.  Doxygen markup is used throughout all header and
-A Doxygen filter program may be provided to place Doxygen markup in assembler
+source files.  A Doxygen filter program may be provided to place Doxygen markup
-files.  The software architecture is documented via Doxygen groups.  Each
+in assembler files.  The software architecture is documented via Doxygen
-Doxygen group name should have a project-specific name and the name should be
+groups.  Each Doxygen group name should have a project-specific name and the
-unique within the project, e.g.  RTEMSTopLevel\ MidLevel\ LowLevel.  The link
+name should be unique within the project, e.g.  RTEMSTopLevel\ MidLevel\
-from a Doxygen group to its parent group is realized through the ``@ingroup``
+LowLevel.  The link from a Doxygen group to its parent group is realized
-special command.  The link from a Doxygen group or :term:`software component`
+through the ``@ingroup`` special command.  The link from a Doxygen group or
-to the corresponding requirement is realized through a ``@satisfy{req}``
+:term:`software component` to the corresponding requirement is realized through
-`custom command <http://www.doxygen.nl/manual/custcmd.html>`_ which needs the
+a ``@satisfy{req}`` `custom command
-identifier of the requirement as its one and only parameter.  Only links to
+<http://www.doxygen.nl/manual/custcmd.html>`_ which needs the identifier of the
-parents are explicitly given in the Doxygen markup.  The links from a parent to
+requirement as its one and only parameter.  Only links to parents are
-its children are only implicitly specified via the link from a child to its
+explicitly given in the Doxygen markup.  The links from a parent to its
-parent.  So, a tool must process all files to get the complete hierarchy of
+children are only implicitly specified via the link from a child to its parent.
-software requirements, architecture and design. Links from a software component
+So, a tool must process all files to get the complete hierarchy of software
-to another software component are realized through automatic Doxygen references
+requirements, architecture and design. Links from a software component to
-or the ``@ref`` and ``@see`` special commands.
+another software component are realized through automatic Doxygen references or
+the ``@ref`` and ``@see`` special commands.

eng/req/validation.rst

@@ -1,46 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
-
-.. _ReqEngValidation:
-
-Requirement Validation
-======================
-
-The validation of each requirement shall be accomplished by one or more of
-the following methods and nothing else:
-
-* *By test*: A :ref:`ReqEngTestCase` specification item is provided to
-  demonstrate that the requirement is satisfied when the software product is
-  executed on the target platform.
-
-* *By analysis*: A statement is provided how the requirement is met, by
-  analysing static properties of the software product.
-
-* *By inspection*: A statement is provided how the requirement is met, by
-  inspection of the :term:`source code`.
-
-* *By review of design*: A rationale is provided to demonstrate how the
-  qualification requirement is satisfied implicitly by the software design.
-
-Validation by test is strongly recommended.  The choice of any other validation
-method shall be strongly justified.  The requirements author is obligated to
-provide the means to validate the requirement with detailed instructions.
-
-For a specification item in a parent directory it could be checked that at
-least one item in a subdirectory has a link to it.  For example a subdirectory
-could contain validation items.  With this feature you could check that all
-requirements are covered by at least one validation item.
-
-The requirement validation by analysis, by inspection, and by design
-specification items shall have the following attribute specializations:
-
-type
-    The type attribute value shall be *validation-by-analysis*,
-    *validation-by-inspection*, or *validation-by-review-of-design*.
-
-link
-    There shall be exactly one link to the validated requirement.
-
-text
-    The statement or rational of the requirement validation.