eng: Split up requirements engineering chapter

This allows to more easily generate the specification item section with
a script using specification items.

Update #3715.

1 files changed, 520 insertions, 0 deletions

diff --git a/eng/req/items.rst b/eng/req/items.rst
new file mode 100644
index 0000000..0c13bb2
--- /dev/null
+++ b/eng/req/items.rst
@@ -0,0 +1,520 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. _ReqEngSpecItems:
+
+Specification Items
+===================
+
+The technical specification of RTEMS will contain requirements, specializations
+of requirements, :ref:`test procedures <ReqEngTestProcedure>`,
+:ref:`test suites <ReqEngTestSuite>`, :ref:`test cases <ReqEngTestCase>`, and
+:ref:`requirement validations <ReqEngValidation>`.  These things will be called
+*specification items* or just *items* if it is clear from the context.
+
+The specification items are stored in files in :term:`YAML` format with a
+defined set of key-value pairs called attributes.  The key name shall match
+with the pattern defined by the regular expression
+``[a-zA-Z0-9][a-zA-Z0-9-]+``.  In particular, key names which begin with an
+underscore (``_``) are reserved for internal use in tools.
+
+Each specification item shall have the following attributes:
+
+enabled-by
+    The value shall be a list of expressions.  An expression is an operator
+    or an option.  An option evaluates to true if it is included the set of
+    enabled options of the configuration.  An operator is a dictionary with
+    exactly one key and a value.  Valid keys are *and*, *or*, and *not*:
+
+    * The value of the *and* operator shall be a list of expressions.  It
+      evaluates to the *logical and* of all outcomes of the expressions in
+      the list.
+
+    * The value of the *or* operator shall be a list of expressions.  It
+      evaluates to the *logical or* of all outcomes of the expressions in
+      the list.
+
+    * The value of the *not* operator shall be an expression.  It negates
+      the outcome of its expression.
+
+    The outcome of a list of expressions without an operator is the
+    *logical or* of all outcomes of the expressions in the list.  An empty
+    list evaluates to true.  Examples:
+
+    .. code-block:: none
+
+        enabled-by:
+        - RTEMS_SMP
+
+    .. code-block:: none
+
+        enabled-by:
+        - and:
+          - RTEMS_NETWORKING
+          - not: RTEMS_SMP
+
+    .. code-block:: none
+
+        enabled-by:
+        - and:
+          - not: TEST_DEBUGGER01_EXCLUDE
+          - or:
+            - arm
+            - i386
+
+links
+    The value shall be a list of key-value pairs defining links to other
+    specification items.  The list is ordered and defines the order in
+    which links are processed.  There shall be a key *role* with an
+    unspecified value.  There shall be a key *uid* with a relative UID to
+    the item referenced by this link.  Other keys are type-specific.
+    Example:
+
+    .. code-block:: yaml
+
+        links:
+        - role: build-dependency
+          uid: optpwrdwnhlt
+        - role: build-dependency
+          uid: ../../bspopts
+        - role: build-dependency
+          uid: ../start
+
+type
+    The value shall be the specification :ref:`item type <ReqEngItemTypes>`.
+
+The following attributes are used in specification items of various types:
+
+.. _ReqEngItemAttrLicense:
+
+SPDX-License-Identifier
+    The value should be ``BSD-2-Clause OR CC-BY-SA-4.0``.  If content is
+    imported from external sources, then the corresponding license shall be
+    used.  Acceptable licenses are BSD-2-Clause and CC-BY-SA-4.0.  The
+    copyright holder of the external work should be asked to allow a
+    dual-licensing BSD-2-Clause or CC-BY-SA-4.0.  This allows generation of
+    BSD-2-Clause licensed source code and CC-BY-SA-4.0 licensed documentation.
+
+.. _ReqEngItemAttrCopyrights:
+
+copyrights
+    The value shall be a list of copyright statements of the following formats:
+
+    * ``Copyright (C) <YEAR> <COPYRIGHT HOLDER>``
+
+    * ``Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER>``
+
+    See also :ref:`FileHeaderCopyright`.
+
+.. _ReqEngItemTypes:
+
+Item Types
+----------
+
+Specification items can have all sorts of *types*.  The selection of types and
+the level of detail depends on a particular standard and product model.  We need
+enough flexibility to be in line with ECSS-E-ST-10-06 and possible future
+applications of other standards.  Each item may have a list of types.  Valid
+types are listed below.  This list may change over time.  If new types are
+added, then a mapping between types should be specified.  The item types and
+their definition is work in progress.  A list of types follows:
+
+* requirement
+
+    * functional - Functional requirements shall describe the behaviour of the
+      software product under specific conditions.
+
+        * *capability*
+
+        * *dependability-function*
+
+        * *function*
+
+        * *operational* - Operational requirements shall
+
+            * define the operation modes (e.g. initialization, multitasking, termination),
+
+            * describe the operation modes, and
+
+            * describe the operation mode transitions.
+
+        * *safety-function*
+
+    * non-functional
+
+        * *build-configuration*
+
+        * *constraint*
+
+        * *design*
+
+        * *interface*
+
+        * *interface-requirement*
+
+        * *maintainability*
+
+        * *performance*
+
+        * *portability*
+
+        * *quality*
+
+        * *reliability*
+
+        * *resource*
+
+        * *safety*
+
+* *test-procedure*
+
+* *test-suite*
+
+* *test-case*
+
+* *validation-by-analysis*
+
+* *validation-by-inspection*
+
+* *validation-by-review-of-design*
+
+* *validation-platform*
+
+.. image:: ../../images/eng/req-spec-items.*
+    :scale: 70
+    :align: center
+
+Requirements
+------------
+
+All requirement specification items shall have the following attribute:
+
+rationale:
+    The rationale or justification of the specification item.
+
+Build Configuration
+-------------------
+
+Build configuration requirements define what needs to be built (libraries,
+object files, test executables, etc.) and how (configuration option header
+files, compiler flags, linker flags, etc.).  The goal is to generate build
+files (Makefile or waf) and content for the Software Configuration File (SCF)
+from it.  A YAML scheme needs to be defined for this purpose.
+
+.. _ReqEngInterfaceReq:
+
+Interface Requirement
+---------------------
+
+Interface requirements shall describe the high level aspects of interfaces.
+The item type shall be *interface-requirement*.
+
+.. _ReqEngInterface:
+
+Interface
+---------
+
+.. warning::
+
+    This is work in progress.
+
+Interface items shall specify the interface of the software product to other
+software products and the hardware.  The item type shall be *interface*.  The
+interface items shall have an *interface-category* which is one of the
+following and nothing else:
+
+* *application*: Application interface items shall describe the interface
+  between the software product and the application (:term:`API`).  The goal is
+  to generate header files with Doxygen markup and user manual documentation
+  parts from the application interface specification.
+
+* *application-configuration*: Application configuration items shall define
+  parameters of the software product which can be set by the application at
+  link-time.  The goal is to generate user manual documentation parts and test
+  cases from the application configuration specification.
+
+* *architecture*: Architecture interface items shall define the
+  interface between the software product and the processor architecture
+  (:term:`ABI`).
+
+* *gcc*: GCC interface items shall define the interface between the software
+  product and GCC components such as libgcc.a, libatomic.a, libgomp.a,
+  libstdc++.a, etc.
+
+* *hardware*: Hardware interface items shall define the interface between the
+  software product and the hardware.
+
+* *newlib*: Newlib interface items shall define the interface between the
+  software product and the Newlib (libc.a).
+
+The interface items shall have an *interface-type* which is one of the
+following and nothing else:
+
+* *configuration-option*
+
+* *define*
+
+* *enum*
+
+* *function*
+
+* *header*
+
+* *macro*
+
+* *register-block*
+
+* *structure*
+
+* *typedef*
+
+* *union*
+
+* *variable*
+
+.. _ReqEngInterfaceApplicationConfigGroups:
+
+Interface - Application Configuration Groups
+--------------------------------------------
+
+The application configuration group items shall have the following attribute
+specializations:
+
+SPDX-License-Identifier
+    See :ref:`SPDX-License-Identifier <ReqEngItemAttrLicense>`.
+
+appl-config-group-description:
+    The value shall be the description of this application configuration group.
+
+appl-config-group-name:
+    The value shall be the name of this application configuration group.
+
+copyrights
+    See :ref:`copyrights <ReqEngItemAttrCopyrights>`.
+
+interface-type
+    The interface type value shall be *appl-config-group*.
+
+link
+    There shall be a link to a higher level requirement.
+
+text
+    The application configuration group requirement.
+
+type
+    The type value shall be *interface*.
+
+.. _ReqEngInterfaceApplicationConfigOptions:
+
+Interface - Application Configuration Options
+---------------------------------------------
+
+The application configuration option items shall have the following attribute
+specializations:
+
+SPDX-License-Identifier
+    See :ref:`SPDX-License-Identifier <ReqEngItemAttrLicense>`.
+
+appl-config-option-constraint
+    This attribute shall be present only for *initializer* and *integer*
+    type options.  The value shall be a dictionary of the following optional
+    key-value pairs.
+
+    custom
+        The value shall be a list of constraints in natural language.  Use the
+        following wording:
+
+            The value of this configuration option shall be ...
+
+    min
+        The value shall be the minimum value of the option.
+
+    max
+        The value shall be the maximum value of the option.
+
+    links
+        The value shall be a list of relative UIDs to constraints.
+
+    set
+        The value shall be the list of valid values of the option.
+
+appl-config-option-default
+    This attribute shall be present only for *feature* type options.  The value
+    shall be a description of the default configuration in case this boolean
+    feature define is undefined.  Use the following wording:
+
+        If this configuration option is undefined, then ...
+
+appl-config-option-default-value
+    This attribute shall be present only for *initializer* and *integer*
+    type options.  The value shall be an initializer, an integer, or a
+    descriptive text.
+
+appl-config-option-description
+    For *feature* and *feature-enable* type options, the value shall be a
+    description of the configuration in case this boolean feature define is
+    defined.  Use the following wording:
+
+        In case this configuration option is defined, then ...
+
+    For *initializer* and *integer* options, the value shall describe the
+    effect of the option value.  The description should focus on the average
+    use-case.  It should not cover potential problems, constraints, obscure
+    use-cases, corner cases and everything which makes matters complicated.
+    Add these things to *appl-config-option-constraint* and
+    *appl-config-option-notes*.  Use the following wording:
+
+        The value of this configuration option defines ...
+
+appl-config-option-index
+    The value shall be a list of entries for the document index.  By default,
+    the application configuration option name is added to the index.
+
+appl-config-option-name
+    The value shall be the name of the application configuration option.  Use a
+    pattern of ``CONFIGURE_[A-Z0-9_]+`` for the name.
+
+appl-config-option-notes
+    The value shall be the notes for this option.  The notes should explain
+    everything which was omitted from the description.  It should cover all the
+    details, special cases, usage notes, error conditions, configuration
+    dependencies, and references.
+
+appl-config-option-type
+    The value shall be one of the following and nothing else:
+
+    feature
+        Use this type for boolean feature opions which have a behaviour in the
+        default configuration which is not just that the feature is disabled.
+
+    feature-enable
+        Use this type for boolean feature opions which just enables a feature.
+
+    initializer
+        Use this type for options which initialize a data structure.
+
+    integer
+        Use this type for integer options.
+
+copyrights
+    See :ref:`copyrights <ReqEngItemAttrCopyrights>`.
+
+interface-type
+    The interface type value shall be *appl-config-option*.
+
+link
+    There shall be a link to the application configuration group to which this
+    option belongs.
+
+text
+    The application configuration option requirement.
+
+type
+    The type value shall be *interface*.
+
+.. _ReqEngTestProcedure:
+
+Test Procedure
+--------------
+
+Test procedures shall be executed by the Qualification Toolchain.
+
+The test procedure items shall have the following attribute
+specializations:
+
+type
+    The type value shall be *test-procedure*.
+
+text
+    The purpose of this test procedure.
+
+platform
+    There shall be links to validation platform requirements.
+
+steps
+    The test procedure steps.  Could be a list of key-value pairs.  The key
+    is the step name and the value is a description of the actions
+    performed in this step.
+
+.. _ReqEngTestSuite:
+
+Test Suite
+----------
+
+Test suites shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.
+
+The test suite items shall have the following attribute specializations:
+
+type
+    The type value shall be *test-suite*.
+
+text
+    The test suite description.
+
+.. _ReqEngTestCase:
+
+Test Case
+---------
+
+Test cases shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.
+
+The test case items shall have the following attribute specializations:
+
+type
+    The type value shall be *test-case*.
+
+link
+    The link to the requirement validated by this test case or no links if
+    this is a unit or integration test case.
+
+ref
+    If this is a unit test case, then a reference to the :term:`software
+    item` under test shall be provided.  If this is an integration test
+    case, then a reference to the integration under test shall be provided.
+    The integration is identified by its Doxygen group name.
+
+text
+    A short description of the test case.
+
+inputs
+    The inputs to execute the test case.
+
+outputs
+    The expected outputs.
+
+The test case code may be also contained in the test case specification
+item in a *code* attribute.  This is subject to discussion on the RTEMS
+mailing list.  Alternatively, the test code could be placed directly in
+source files.  A method is required to find the test case specification of
+a test case code and vice versa.
+
+.. _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.