rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-06-05 04:05:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

eng: Update requirements engineering chapter

Browse Source 
Update requirements engineering chapter due to the removal of Doorstop
as the requirements management tool.

Update the application configuration related specification items.

Update #3715.
This commit is contained in:
Sebastian Huber 2020-04-22 13:43:25 +02:00
parent 2d22d7453d
commit d4ba908e42
7 changed files with 415 additions and 309 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

689
eng/req-eng.rst
View File

@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0 .. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2019 embedded brains GmbH .. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
.. |E40| replace:: ECSS-E-ST-40C .. |E40| replace:: ECSS-E-ST-40C
@ -93,92 +93,93 @@ Identification
-------------- --------------
Each requirement shall have a unique identifier (UID). The question is in Each requirement shall have a unique identifier (UID). The question is in
which scope should it be unique? Ideally, it should be universally unique. As which scope should it be unique? Ideally, it should be universally unique.
a best effort approach, the name *RTEMS* shall be used as a part in all Therefore all UIDs used to link one specification item to another should use
requirement identifiers. This should ensure that the RTEMS requirements can be relative UIDs. This ensures that the RTEMS requirements can be referenced
referenced easily in larger systems. The standard ECSS-E-ST-10-06C recommends easily in larger systems though a system-specific prefix. The standard
in section 8.2.6 that the identifier should reflect the type of the requirement ECSS-E-ST-10-06C recommends in section 8.2.6 that the identifier should reflect
and the life profile situation. Other standards may have other the type of the requirement and the life profile situation. Other standards
recommendations. To avoid a bias of RTEMS in the direction of ECSS, this may have other recommendations. To avoid a bias of RTEMS in the direction of
recommendation will not be followed. ECSS, this recommendation will not be followed.
.. topic:: Doorstop The *absolute UID* of a specification item (for example a requirement) is
defined by a leading ``/`` and the path of directories from the specification
base directory to the file of the item separated by ``/`` characters and the
file name without the ``.yml`` extension. For example, a specification item
contained in the file :file:`build/cpukit/librtemscpu.yml` inside a
:file:`spec` directory has the absolute UID of ``/build/cpukit/librtemscpu``.
The UID of an item (requirement) is defined by its file name without the The *relative UID* to a specification item is defined by the path of
extension. An UID consists of two parts, the prefix and a name or a number. directories from the file containing the source specification item to the file
The parts are divided by an optional separator. The prefix is determined by of the destination item separated by ``/`` characters and the file name of the
the document. destination item without the ``.yml`` extension. For example the relative UID
from ``/build/bsps/sparc/leon3/grp`` to ``/build/bsps/bspopts`` is
``../../bspopts``.
The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or Basically, the valid characters of an UID are determined by the file system
more component names, and a name. Each part is separated by a "-" storing the item files. By convention, UID characters shall be restricted to
character. For example, the UID RTEMS-CLASSIC-TASK-CREATERRINVADDR may specify the following set defined by the regular expression ``[a-zA-Z0-9_-]+``. Use
that the `rtems_task_create()` directive shall return a status of ``-`` as a separator inside an UID part.
`RTEMS_INVALID_ADDRESS` if the `id` parameter is `NULL`.
.. topic:: Doorstop In documents the URL-like prefix ``spec:`` shall be used to indicated
specification item UIDs.
Doorstop uses documents to create namespaces (named a prefix in Doorstop). The UID scheme for RTEMS requirements shall be component based. For example,
For the example above, you can create the documents like this: the UID ``spec:/classic/task/create-err-invaddr`` may specify that the
:c:func:`rtems_task_create` directive shall return a status of
.. code-block:: none ``RTEMS_INVALID_ADDRESS`` if the ``id`` parameter is ``NULL``.
doorstop create -s - RTEMS-CLASSIC -p RTEMS spec/classic
doorstop create -s - RTEMS-CLASSIC-TASK -p RTEMS-CLASSIC spec/classic/task
doorstop create -s - RTEMS-CLASSIC-SEMAPHORE -p RTEMS-CLASSIC spec/classic/semaphore
The requirement files are organized in directories.
A initial requirement item hierarchy could be this: A initial requirement item hierarchy could be this:
* RTEMS * build (building RTEMS BSPs and libraries)
* BUILD (building RTEMS BSPs and libraries) * acfg (application configuration groups)
* CONFIG (application configuration) * opt (application configuration options)
* CLASSIC * classic
* TASK * task
* CREAT* (requirements for `rtems_task_create()`) * create-* (requirements for :c:func:`rtems_task_create`)
* DELT* (requirements for `rtems_task_delete()`) * delete-* (requirements for :c:func:`rtems_task_delete`)
* EXIT* (requirements for `rtems_task_exit()`) * exit-* (requirements for :c:func:`rtems_task_exit`)
* GETAFF* (requirements for `rtems_task_get_affinity()`) * getaff-* (requirements for :c:func:`rtems_task_get_affinity`)
* GETPRI* (requirements for `rtems_task_get_priority()`) * getpri-* (requirements for :c:func:`rtems_task_get_priority`)
* GETSHD* (requirements for `rtems_task_get_scheduler()`) * getsched-* (requirements for :c:func:`rtems_task_get_scheduler`)
* IDNT* (requirements for `rtems_task_ident()`) * ident-* (requirements for :c:func:`rtems_task_ident`)
* ISSUSP* (requirements for `rtems_task_is_suspended()`) * issusp-* (requirements for :c:func:`rtems_task_is_suspended`)
* ITER* (requirements for `rtems_task_iterate()`) * iter-* (requirements for :c:func:`rtems_task_iterate`)
* MODE* (requirements for `rtems_task_mode()`) * mode-* (requirements for :c:func:`rtems_task_mode`)
* RESTRT* (requirements for `rtems_task_restart()`) * restart-* (requirements for :c:func:`rtems_task_restart`)
* RESUME* (requirements for `rtems_task_resume()`) * resume* (requirements for :c:func:`rtems_task_resume`)
* SELF* (requirements for `rtems_task_self()`) * self* (requirements for :c:func:`rtems_task_self`)
* SETAFF* (requirements for `rtems_task_set_affinity()`) * setaff-* (requirements for :c:func:`rtems_task_set_affinity`)
* SETPRI* (requirements for `rtems_task_set_priority()`) * setpri-* (requirements for :c:func:`rtems_task_set_priority`)
* SETSHD* (requirements for `rtems_task_set_scheduler()`) * setsched* (requirements for :c:func:`rtems_task_set_scheduler`)
* START* (requirements for `rtems_task_start()`) * start-* (requirements for :c:func:`rtems_task_start`)
* SUSP* (requirements for `rtems_task_suspend()`) * susp-* (requirements for :c:func:`rtems_task_suspend`)
* WKAFT* (requirements for `rtems_task_wake_after()`) * wkafter-* (requirements for :c:func:`rtems_task_wake_after`)
* WKWHN* (requirements for `rtems_task_wake_when()`) * wkwhen-* (requirements for :c:func:`rtems_task_wake_when`)
* Semaphore * sema
* ... * ...
* POSIX * posix
* ... * ...
A more detailed naming scheme and guidelines should be established. We have to A more detailed naming scheme and guidelines should be established. We have to
find the right balance between the length of UIDs and self-descriptive UIDs. A find the right balance between the length of UIDs and self-descriptive UIDs. A
clear scheme for all Classic API managers may help to keep the UIDs short and clear scheme for all Classic API managers may help to keep the UIDs short and
descriptive. descriptive.
The specification of the validation of requirements should be maintained also by The specification of the validation of requirements should be maintained also
Doorstop. For each requirement document there should be a validation child by specification items. For each requirement directory there should be a
Doorstop document with a *TEST* component name, e.g. RTEMS-CLASSIC-TASK-TEST. A validation subdirectory named *test*, e.g. :file:`spec/classic/task/test`. A
test document may contain also validations by analysis, by inspection, and by test specification directory may contain also validations by analysis, by
design, see :ref:`ReqEngValidation`. inspection, and by design, see :ref:`ReqEngValidation`.
Level of Requirements Level of Requirements
--------------------- ---------------------
@ -363,29 +364,29 @@ Separate Requirements
Requirements shall be stated separately. A bad example is: Requirements shall be stated separately. A bad example is:
RTEMS-CLASSIC-TASK-CRAT spec:/classic/task/create
The task create directive shall evaluate the parameters, allocate a task The task create directive shall evaluate the parameters, allocate a task
object and initialize it. object and initialize it.
To make this a better example, it should be split into separate requirements: To make this a better example, it should be split into separate requirements:
RTEMS-CLASSIC-TASK-CRAT spec:/classic/task/create
When the task create directive is called with valid parameters and a free When the task create directive is called with valid parameters and a free
task object exists, the task create directive shall assign the identifier of task object exists, the task create directive shall assign the identifier of
an initialized task object to the id parameter and return the an initialized task object to the ``id`` parameter and return the
RTEMS_SUCCESSFUL status. ``RTEMS_SUCCESSFUL`` status.
RTEMS-CLASSIC-TASK-CRATERRTOOMANY spec:/classic/task/create-err-toomany
If no free task objects exists, the task create directive shall return the If no free task objects exists, the task create directive shall return the
RTEMS_TOO_MANY status. ``RTEMS_TOO_MANY`` status.
RTEMS-CLASSIC-TASK-CRATERRINVADDR spec:/classic/task/create-err-invaddr
If the id parameter is NULL, the task create directive shall return the If the ``id`` parameter is ``NULL``, the task create directive shall return the
RTEMS_INVALID_ADDRESS status. ``RTEMS_INVALID_ADDRESS`` status.
RTEMS-CLASSIC-TASK-CRATERRINVNAME spec:/classic/task/create-err-invname
If the name parameter is not valid, the task create directive shall return If the ``name`` parameter is invalid, the task create directive shall
the RTEMS_INVALID_NAME status. return the ``RTEMS_INVALID_NAME`` status.
... ...
@ -395,22 +396,22 @@ Conflict Free Requirements
Requirements shall not be in conflict with each other inside a specification. Requirements shall not be in conflict with each other inside a specification.
A bad example is: A bad example is:
RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT spec:/classic/sema/mtx-obtain-wait
If a mutex is not available, the mutex obtain directive shall enqueue the When a mutex is not available, the mutex obtain directive shall enqueue the
calling thread on the wait queue of the mutex. calling thread on the wait queue of the mutex.
RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT spec:/classic/sema/mtx-obtain-err-unsat
If a mutex is not available, the mutex obtain directive shall return the If a mutex is not available, the mutex obtain directive shall return the
RTEMS_UNSATISFIED status. RTEMS_UNSATISFIED status.
To resolve this conflict, a condition may be added: To resolve this conflict, a condition may be added:
RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT spec:/classic/sema/mtx-obtain-wait
If a mutex is not available, when the RTEMS_WAIT option is set, the mutex When a mutex is not available and the RTEMS_WAIT option is set, the mutex
obtain directive shall enqueue the calling thread on the wait queue of the obtain directive shall enqueue the calling thread on the wait queue of the
mutex. mutex.
RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT spec:/classic/sema/mtx-obtain-err-unsat
If a mutex is not available, when the RTEMS_WAIT option is not set, the If a mutex is not available, when the RTEMS_WAIT option is not set, the
mutex obtain directive shall return the RTEMS_UNSATISFIED status. mutex obtain directive shall return the RTEMS_UNSATISFIED status.
@ -426,11 +427,8 @@ Justification of Requirements
----------------------------- -----------------------------
Each requirement shall have a rationale or justification recorded in a Each requirement shall have a rationale or justification recorded in a
dedicated section of the requirement file. dedicated section of the requirement file. See *rationale* attribute for
:ref:`ReqEngSpecItems`.
.. topic:: Doorstop
See *rationale* attribute for :ref:`ReqEngSpecItems`.
.. _ReqEngSpecItems: .. _ReqEngSpecItems:
@ -443,107 +441,99 @@ of requirements, :ref:`test procedures <ReqEngTestProcedure>`,
:ref:`requirement validations <ReqEngValidation>`. These things will be called :ref:`requirement validations <ReqEngValidation>`. These things will be called
*specification items* or just *items* if it is clear from the context. *specification items* or just *items* if it is clear from the context.
.. topic:: Doorstop 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.
Doorstop maintains *items* which are included in *documents*. The normal Each specification item shall have the following attributes:
use case is to store a requirement with meta-data in an item. However,
items can be also used to store other things like test procedures, test
suites, test cases, and requirement validations. Items contain key-value
pairs called attributes. Specializations of requirements may contain extra
attributes, e.g. interface, build, configuration requirements. All items
have the following standard Doorstop attributes:
active enabled-by
A boolean value which indicates if the requirement is active or not. The value shall be a list of expressions. An expression is an operator
The value is included in the fingerprint via a document configuration or an option. An option evaluates to true if it is included the set of
option. enabled options of the configuration. An operator is a dictionary with
exactly one key and a value. Valid keys are *and*, *or*, and *not*:
derived * The value of the *and* operator shall be a list of expressions. It
A boolean value which indicates if the requirement is derived or not. evaluates to the *logical and* of all outcomes of the expressions in
For the the list.
`definition of derived <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#derived>`_.
see the Doorstop documentation. For RTEMS, this value shall be false
for all requirements. The value is not included in the fingerprint.
normative * The value of the *or* operator shall be a list of expressions. It
A boolean value which indicates if the requirement is normative or not. evaluates to the *logical or* of all outcomes of the expressions in
For the the list.
`definition of normative <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#normative>`_.
see the Doorstop documentation. For RTEMS, this value shall be true
for all requirements. The value is not included in the fingerprint.
level * The value of the *not* operator shall be an expression. It negates
Indicates the presentation order within a document. For RTEMS, this the outcome of its expression.
value shall be unused. The value is not included in the fingerprint.
header The outcome of a list of expressions without an operator is the
A header for an item. For RTEMS, this value shall be the empty string. *logical or* of all outcomes of the expressions in the list. An empty
The value is not included in the fingerprint. list evaluates to true. Examples:
reviewed .. code-block:: none
The fingerprint of the item. Maintain this attribute with the
`doorstop clear` command.
links enabled-by:
The links from this item to parent items. Maintain this attribute with - RTEMS_SMP
the `doorstop link` command. The value is included in the fingerprint.
ref .. code-block:: none
References to files and directories. See
`#365 <https://github.com/jacebrowning/doorstop/issues/365>`_,
The value is included in the fingerprint.
text enabled-by:
The item text. The value is included in the fingerprint. - and:
- RTEMS_NETWORKING
- not: RTEMS_SMP
All specification items shall have the following extended attributes: .. code-block:: none
type: enabled-by:
A list of :ref:`item types <ReqEngItemTypes>`. The value is not - and:
included in the fingerprint. - not: TEST_DEBUGGER01_EXCLUDE
- or:
- arm
- i386
enabled-by: links
The value is a list of expressions. The value is included in the The value shall be a list of key-value pairs defining links to other
fingerprint. An expression is an operator or an option. An option specification items. The list is ordered and defines the order in
evaluates to true if it is included the set of enabled options of the which links are processed. There shall be a key *role* with an
configuration. An operator is a dictionary with exactly one key and a unspecified value. There shall be a key *uid* with a relative UID to
value. Valid keys are `and`, `or`, and `not`: the item referenced by this link. Other keys are type-specific.
Example:
* The value of the `and` operator shall be a list of expressions. It .. code-block:: yaml
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 links:
evaluates to the `logical or` of all outcomes of the expressions in - role: build-dependency
the list. uid: optpwrdwnhlt
- role: build-dependency
uid: ../../bspopts
- role: build-dependency
uid: ../start
* The value of the `not` operator shall be an expression. It negates type
the outcome of its expression. The value shall be the specification :ref:`item type <ReqEngItemTypes>`.
The outcome of a list of expressions without an operator is the The following attributes are used in specification items of various types:
`logical or` of all outcomes of the expressions in the list. An empty
list evaluates to true. Examples:
.. code-block:: none .. _ReqEngItemAttrLicense:
enabled-by: SPDX-License-Identifier
- RTEMS_SMP 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.
.. code-block:: none .. _ReqEngItemAttrCopyrights:
enabled-by: copyrights
- and: The value shall be a list of copyright statements of the following formats:
- RTEMS_NETWORKING
- not: RTEMS_SMP
.. code-block:: none * ``Copyright (C) <YEAR> <COPYRIGHT HOLDER>``
enabled-by: * ``Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER>``
- and:
- not: TEST_DEBUGGER01_EXCLUDE See also :ref:`FileHeaderCopyright`.
- or:
- arm
- i386
.. _ReqEngItemTypes: .. _ReqEngItemTypes:
@ -626,14 +616,10 @@ their definition is work in progress. A list of types follows:
Requirements Requirements
------------ ------------
.. topic:: Doorstop All requirement specification items shall have the following attribute:
All requirement specification items shall have the following extended rationale:
attribute: The rationale or justification of the specification item.
rationale:
The rationale or justification of the specification item. The value is
**not** included in the fingerprint.
Build Configuration Build Configuration
------------------- -------------------
@ -657,6 +643,10 @@ The item type shall be *interface-requirement*.
Interface Interface
--------- ---------
.. warning::
This is work in progress.
Interface items shall specify the interface of the software product to other Interface items shall specify the interface of the software product to other
software products and the hardware. The item type shall be *interface*. The software products and the hardware. The item type shall be *interface*. The
interface items shall have an *interface-category* which is one of the interface items shall have an *interface-category* which is one of the
@ -711,56 +701,145 @@ following and nothing else:
* *variable* * *variable*
.. _ReqEngInterfaceApplicationConfig: .. _ReqEngInterfaceApplicationConfigGroups:
Interface - Application Configuration Interface - Application Configuration Groups
------------------------------------- --------------------------------------------
.. topic:: Doorstop The application configuration group items shall have the following attribute
specializations:
The application configuration items shall have the following attribute SPDX-License-Identifier
specializations: See :ref:`SPDX-License-Identifier <ReqEngItemAttrLicense>`.
type appl-config-group-description:
The type value shall be *interface*. The value shall be the description of this application configuration group.
interface-category appl-config-group-name:
The interface category value shall be *application-configuration*. The value shall be the name of this application configuration group.
interface-type copyrights
The interface type value shall be *configuration-option*. See :ref:`copyrights <ReqEngItemAttrCopyrights>`.
link interface-type
There shall be a link to a higher level requirement. The interface type value shall be *appl-config-group*.
text link
The application configuration requirement. There shall be a link to a higher level requirement.
configuration-category: text
A category to which this application configuration option belongs. The application configuration group requirement.
define: type
The name of the configuration define. The type value shall be *interface*.
data-type: .. _ReqEngInterfaceApplicationConfigOptions:
The data type of the configuration define.
value-range: Interface - Application Configuration Options
The range of valid values. ---------------------------------------------
default-value: The application configuration option items shall have the following attribute
The default value. specializations:
description: SPDX-License-Identifier
The description of the application configuration. The description See :ref:`SPDX-License-Identifier <ReqEngItemAttrLicense>`.
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.
note: appl-config-option-constraint
Notes for this application configuration. The notes should explain This attribute shall be present only for *initializer* and *integer*
everything which was omitted from the description. It should cover all type options. The value shall be a dictionary of the following optional
the details. 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: .. _ReqEngTestProcedure:
@ -769,24 +848,22 @@ Test Procedure
Test procedures shall be executed by the Qualification Toolchain. Test procedures shall be executed by the Qualification Toolchain.
.. topic:: Doorstop The test procedure items shall have the following attribute
specializations:
The test procedure items shall have the following attribute type
specializations: The type value shall be *test-procedure*.
type text
The type value shall be *test-procedure*. The purpose of this test procedure.
text platform
The purpose of this test procedure. There shall be links to validation platform requirements.
platform steps
There shall be links to validation platform requirements. 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
steps performed in this step.
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: .. _ReqEngTestSuite:
@ -795,15 +872,13 @@ Test Suite
Test suites shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`. Test suites shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.
.. topic:: Doorstop The test suite items shall have the following attribute specializations:
The test suite items shall have the following attribute specializations: type
The type value shall be *test-suite*.
type text
The type value shall be *test-suite*. The test suite description.
text
The test suite description.
.. _ReqEngTestCase: .. _ReqEngTestCase:
@ -812,37 +887,35 @@ Test Case
Test cases shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`. Test cases shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.
.. topic:: Doorstop The test case items shall have the following attribute specializations:
The test case items shall have the following attribute specializations: type
The type value shall be *test-case*.
type link
The type value shall be *test-case*. The link to the requirement validated by this test case or no links if
this is a unit or integration test case.
link ref
The link to the requirement validated by this test case or no links if If this is a unit test case, then a reference to the :term:`software
this is a unit or integration test case. 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.
ref text
If this is a unit test case, then a reference to the :term:`software A short description of the test case.
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 inputs
A short description of the test case. The inputs to execute the test case.
inputs outputs
The inputs to execute the test case. The expected outputs.
outputs The test case code may be also contained in the test case specification
The expected outputs. item in a *code* attribute. This is subject to discussion on the RTEMS
mailing list. Alternatively, the test code could be placed directly in
The test case code may be also contained in the test case specification source files. A method is required to find the test case specification of
item in a *code* attribute. This is subject to discussion on the RTEMS a test case code and vice versa.
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: .. _ReqEngResAndPerf:
@ -898,7 +971,7 @@ indicate an agreed statement (similar to the
`Linux kernel patch submission guidelines <https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_). `Linux kernel patch submission guidelines <https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_).
Git commit procedures may be ensured through a server-side pre-receive hook. Git commit procedures may be ensured through a server-side pre-receive hook.
The history of requirements may be also added to the specification items The history of requirements may be also added to the specification items
directly in a ``revision`` attribute. This would make it possible to generate directly in a *revision* attribute. This would make it possible to generate
the history information for documents without having the Git repository the history information for documents without having the Git repository
available, e.g. from an RTEMS source release archive. available, e.g. from an RTEMS source release archive.
@ -909,7 +982,7 @@ Backward Traceability of Specification Items
Providing backward traceability of specification items means that we must be Providing backward traceability of specification items means that we must be
able to find the corresponding higher level specification item for each refined able to find the corresponding higher level specification item for each refined
specification item. This is a standard Doorstop feature. specification item. A custom tool needs to verify this.
.. _ReqEngTraceForward: .. _ReqEngTraceForward:
@ -918,7 +991,7 @@ Forward Traceability of Specification Items
Providing forward traceability of specification items means that we must be Providing forward traceability of specification items means that we must be
able to find all the refined specification items for each higher level able to find all the refined specification items for each higher level
specification item. This is a standard Doorstop feature. The links from specification item. A custom tool needs to verify this. The links from
parent to child specification items are implicitly defined by links from a parent to child specification items are implicitly defined by links from a
child item to a parent item. child item to a parent item.
@ -927,24 +1000,24 @@ child item to a parent item.
Traceability between Software Requirements, Architecture and Design Traceability between Software Requirements, Architecture and Design
------------------------------------------------------------------- -------------------------------------------------------------------
The software requirements are implemented in Doorstop compatible YAML files. The software requirements are implemented in custom YAML files, see
The software architecture and design is written in Doxygen markup. Doxygen :ref:`ReqEngSpecItems`. The software architecture and design is written in
markup is used throughout all header and source files. A Doxygen filter Doxygen markup. Doxygen markup is used throughout all header and source files.
program may be provided to place Doxygen markup in assembler files. The A Doxygen filter program may be provided to place Doxygen markup in assembler
software architecture is documented via Doxygen groups. Each Doxygen group files. The software architecture is documented via Doxygen groups. Each
name should have a project-specific name and the name should be unique within Doxygen group name should have a project-specific name and the name should be
the project, e.g. RTEMSTopLevel\ MidLevel\ LowLevel. The link from a Doxygen unique within the project, e.g. RTEMSTopLevel\ MidLevel\ LowLevel. The link
group to its parent group is realized through the ``@ingroup`` special command. from a Doxygen group to its parent group is realized through the ``@ingroup``
The link from a Doxygen group or :term:`software component` to the special command. The link from a Doxygen group or :term:`software component`
corresponding requirement is realized through a ``@satisfy{req}`` to the corresponding requirement is realized through a ``@satisfy{req}``
`custom command <http://www.doxygen.nl/manual/custcmd.html>`_ `custom command <http://www.doxygen.nl/manual/custcmd.html>`_ which needs the
which needs the identifier of the requirement as its one and only parameter. identifier of the requirement as its one and only parameter. Only links to
Only links to parents are explicitly given in the Doxygen markup. The links parents are explicitly given in the Doxygen markup. The links from a parent to
from a parent to its children are only implicitly specified via the link from a its children are only implicitly specified via the link from a child to its
child to its parent. So, a tool must process all files to get the complete parent. So, a tool must process all files to get the complete hierarchy of
hierarchy of software requirements, architecture and design. Links from a software requirements, architecture and design. Links from a software component
software component to another software component are realized through automatic to another software component are realized through automatic Doxygen references
Doxygen references or the ``@ref`` and ``@see`` special commands. or the ``@ref`` and ``@see`` special commands.
.. _ReqEngValidation: .. _ReqEngValidation:
@ -971,25 +1044,23 @@ Validation by test is strongly recommended. The choice of any other validation
method shall be strongly justified. The requirements author is obligated to method shall be strongly justified. The requirements author is obligated to
provide the means to validate the requirement with detailed instructions. provide the means to validate the requirement with detailed instructions.
.. topic:: Doorstop 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.
For an item in a parent document it is checked that at least one item in a The requirement validation by analysis, by inspection, and by design
child document has a link to it. For example a child document could specification items shall have the following attribute specializations:
contain validation items. With this feature you can check that all
requirements are covered by at least one validation item.
The requirement validation by analysis, by inspection, and by design type
specification items shall have the following attribute specializations: The type attribute value shall be *validation-by-analysis*,
*validation-by-inspection*, or *validation-by-review-of-design*.
type link
The type attribute value shall be *validation-by-analysis*, There shall be exactly one link to the validated requirement.
*validation-by-inspection*, or *validation-by-review-of-design*.
link text
There shall be exactly one link to the validated requirement. The statement or rational of the requirement validation.
text
The statement or rational of the requirement validation.
Requirement Management Requirement Management
====================== ======================
@ -1121,8 +1192,8 @@ user.
.. _ReqEngDoorstop: .. _ReqEngDoorstop:
Selected Tool - Doorstop Best Available Tool - Doorstop
------------------------ ------------------------------
:term:`Doorstop` is a requirements management tool. It has a modern, :term:`Doorstop` is a requirements management tool. It has a modern,
object-oriented and well-structured implementation in Python 3.6 under the object-oriented and well-structured implementation in Python 3.6 under the
@ -1145,8 +1216,8 @@ Doorstop consists of three main parts
For RTEMS, its scope will be extended to manage specifications in general. The For RTEMS, its scope will be extended to manage specifications in general. The
primary reason for selecting Doorstop as the requirements management tool for primary reason for selecting Doorstop as the requirements management tool for
the RTEMS Project is its data format which allows a high degree of the RTEMS Project is its data format which allows a high degree of
customization. Doorstop uses a directed, acyclic graph of items. The items are customization. Doorstop uses a directed, acyclic graph (DAG) of items. The
files in YAML format. Each item has a set of items are files in YAML format. Each item has a set of
`standard attributes <https://doorstop.readthedocs.io/en/latest/reference/item/>`_ `standard attributes <https://doorstop.readthedocs.io/en/latest/reference/item/>`_
(key-value pairs). (key-value pairs).
@ -1175,3 +1246,37 @@ specification items. This can be done with a table which contains columns for
Given the source code of RTEMS (which includes the specification items) and this Given the source code of RTEMS (which includes the specification items) and this
table, it can be determined which items are unchanged and which have another table, it can be determined which items are unchanged and which have another
status (e.g. unknown, changed, etc.). status (e.g. unknown, changed, etc.).
After some initial work with Doorstop some issues surfaced
(`#471 <https://github.com/doorstop-dev/doorstop/issues/471>`_)
It turned out that Doorstop is not designed as a library and contains to much
policy. This results in a lack of flexibility required for the RTEMS Project.
1. Its primary use case is requirements management. So, it has some standard
attributes useful in this domain, like derived, header, level, normative,
ref, reviewed, and text. However, we want to use it more generally for
specification items and these attributes make not always sense. Having them
in every item is just overhead and may cause confusion.
2. The links cannot have custom attributes, e.g. role, enabled-by. With
link-specific attributes you could have multiple DAGs formed up by the same
set of items.
3. Inside a document (directory) items are supposed to have a common type (set
of attributes). We would like to store at a hierarchy level also distinct
specializations.
4. The verification of the items is quite limited. We need verification with
type-based rules.
5. The UIDs in combination with the document hierarchy lead to duplication,
e.g. a/b/c/a-b-c-d.yml. You have the path (a/b/c) also in the file name
(a-b-c). You cannot have relative UIDs in links (e.g. ../parent-req) . The
specification items may contain multiple requirements, e.g. min/max
attributes. There is no way to identify them.
6. The links are ordered by Doorstop alphabetically by UID. For some
applications, it would be better to use the order specified by the user. For
example, we want to use specification items for a new build system. Here it
is handy if you can express things like this: A is composed of B and C.
Build B before C.

BIN
images/eng/req-add.pdf
View File

Binary file not shown.

BIN
images/eng/req-add.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 49 KiB

After

Width:  |  Height:  |  Size: 49 KiB

21
images/eng/req-add.puml
View File

@ -1,29 +1,30 @@
' SPDX-License-Identifier: CC-BY-SA-4.0 ' SPDX-License-Identifier: CC-BY-SA-4.0
' Copyright (C) 2019 embedded brains GmbH ' Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
@startuml @startuml
start start
:Invoke: ""doorstop add RTEMS""; :Create file: ""spec/component/new.yml"";
note right note right
This will create a new requirement. Create a new file in the specification
For this activity its UID shall be NEW. directory. For this activity its UID
It is located in a file NEW.yml. shall be spec:/component/new. It is
located in the file spec/component/new.yml.
end note end note
while (Needs a link to a parent requirement?) is (Yes) while (Needs a link to a parent requirement?) is (Yes)
:Invoke: ""doorstop link NEW PARENT""; :Add link to links attribute of file: ""spec/component/new.yml"";
endwhile (No) endwhile (No)
repeat repeat
:Invoke: ""doorstop edit NEW""; :Edit file: ""spec/component/new.yml"";
:Edit the requirement according to your needs and save it; :Add attributes according to your needs and save the file;
:Commit NEW.yml with a proper message; :Commit the changes with a proper message;
:Send the patch to the devel@rtems.org mailing list for review; :Send the patch to the devel@rtems.org mailing list for review;
repeat while (Reviewers demand changes in the new requirement?) is (Yes) repeat while (Reviewers demand changes in the new requirement?) is (Yes)
@ -32,7 +33,7 @@ repeat while (Reviewers demand changes in the new requirement?) is (Yes)
if (New requirement was accepted by reviewers?) then (Yes) if (New requirement was accepted by reviewers?) then (Yes)
:Push the commit to the project repository; :Push the commit to the project repository;
else (No) else (No)
:Discard the NEW requirement; :Discard the new requirement;
endif endif
stop stop

BIN
images/eng/req-modify.pdf
View File

Binary file not shown.

BIN
images/eng/req-modify.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 37 KiB

14
images/eng/req-modify.puml
View File

@ -1,23 +1,23 @@
' SPDX-License-Identifier: CC-BY-SA-4.0 ' SPDX-License-Identifier: CC-BY-SA-4.0
' Copyright (C) 2019 embedded brains GmbH ' Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
@startuml @startuml
start start
repeat repeat
:Invoke: ""doorstop edit REQ""; :Edit: ""spec/component/req.yml"";
note right note right
For this activity the UID For this activity the UID of the
of the requirement shall be REQ. requirement shall be spec:/component/req.
It is located in a file REQ.yml. It is located in a file spec/component/req.yml.
end note end note
:Edit the requirement according to your needs and save it; :Edit the attributes according to your needs and save the file;
:Commit REQ.yml with a proper message; :Commit the changes with a proper message;
:Send the patch to the devel@rtems.org mailing list for review; :Send the patch to the devel@rtems.org mailing list for review;
repeat while (Reviewers demand changes in the modified requirement?) is (Yes) repeat while (Reviewers demand changes in the modified requirement?) is (Yes)