[PATCH] eng: Add Software Requirements Engineering chapter

Gedare Bloom gedare at rtems.org
Mon Jul 29 22:16:42 UTC 2019


Seems to make sense to me. I noted just a few very small grammatical errors.

On Wed, Jul 24, 2019 at 7:45 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> ---
>  eng/index.rst             |   1 +
>  eng/req-eng.rst           | 813 ++++++++++++++++++++++++++++++++++++++++++++++
>  images/eng/req-add.pdf    | Bin 0 -> 81320 bytes
>  images/eng/req-add.png    | Bin 0 -> 50516 bytes
>  images/eng/req-add.uml    |  40 +++
>  images/eng/req-modify.pdf | Bin 0 -> 68500 bytes
>  images/eng/req-modify.png | Bin 0 -> 37776 bytes
>  images/eng/req-modify.uml |  34 ++
>  8 files changed, 888 insertions(+)
>  create mode 100644 eng/req-eng.rst
>  create mode 100644 images/eng/req-add.pdf
>  create mode 100644 images/eng/req-add.png
>  create mode 100644 images/eng/req-add.uml
>  create mode 100644 images/eng/req-modify.pdf
>  create mode 100644 images/eng/req-modify.png
>  create mode 100644 images/eng/req-modify.uml
>
> diff --git a/eng/index.rst b/eng/index.rst
> index cfc831b..802eec9 100644
> --- a/eng/index.rst
> +++ b/eng/index.rst
> @@ -26,6 +26,7 @@ RTEMS Software Engineering (|version|)
>      preface
>      prequalification
>      stakeholders
> +    req-eng
>      management
>      test-plan
>      test-framework
> diff --git a/eng/req-eng.rst b/eng/req-eng.rst
> new file mode 100644
> index 0000000..6b63c7b
> --- /dev/null
> +++ b/eng/req-eng.rst
> @@ -0,0 +1,813 @@
> +.. SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. Copyright (C) 2019 embedded brains GmbH
> +
> +.. |E40| replace:: ECSS-E-ST-40C
> +
> +.. |E10-06| replace:: ECSS-E-ST-10-06C
> +
> +Software Requirements Engineering
> +*********************************
> +
> +Software engineering standards for critical software such as |E40| demand that
> +software requirements for a software product are collected in a software
> +requirements specification (technical specification in |E40| terms).  They are
> +usually derived from system requirements (requirements baseline in |E40|
> +terms).  RTEMS is designed as a reusable software product which can be utilized
> +by application designers to ease the development of their applications.  The
> +requirements of the end system (system requirements) using RTEMS are only known
> +to the application designer.  RTEMS itself is developed by the RTEMS
> +maintainers and they do not know the requirements of a particular end system in
> +general.  RTEMS is designed as a real-time operating system to meet typical
> +system requirements for a wide range of applications.  Its suitability for a
> +particular application must be determined by the application designer based on
> +the technical specification provided by RTEMS accompanied with performance data
> +for a particular target platform.
> +
> +Currently, no technical specification of RTEMS exists in the form of a
> +dedicated document.  Since the beginning of the RTEMS evolution in the late
> +1980s it was developed iteratively.  It was never developed in a waterfall
> +model.  During initial development the RTEID :cite:`Motorola:1988:RTEID` and
> +later the ORKID :cite:`VITA:1990:ORKID` draft specifications were used as
> +requirements.  These were evolving during the development and an iterative
> +approach was followed often using simple algorithms and coming back to
> +optimise.  In 1993 and 1994 a subset of pthreads sufficient to support
> +:term:`GNAT` was added as requirements.  At this time the Ada tasking was
> +defined, however, not implemented in GNAT, so this involved guessing during the
> +development. Later some adjustments were made when Ada tasking was actually
> +implemented.  So, it was consciously iterative with the specifications evolving
> +and feedback from performance analysis.  Benchmarks published from other real
> +time operating systems were used for comparison.  Optimizations were carried
> +out until the results were comparable.  Development was done with distinct
> +contractual phases and tasks for development, optimization, and the addition of
> +priority inheritance and rate monotonic scheduling.  The pthreads requirement
> +has grown to be as much POSIX as possible.  Portability to FreeBSD to use the
> +network stack, USB stack, SD/MMC card stack and device drivers resulted in
> +another set of requirements.  The support for symmetric multiprocessing (SMP)
> +was a huge driver for change.  It was developed step by step and sponsored by
> +several independent users with completely different applications and target
> +platforms in mind.  The high performance OpenMP support introduced the Futex as
> +a new synchronization primitive.  A key success element of RTEMS is the ability
> +to accept changes driven by user needs and still keep the operating system
> +stable enough for production systems.  Procedures that place a high burden on
> +changes are doomed to be discarded by the RTEMS project.  We have to keep this
> +in mind when we introduce a requirements management work flow which should be
> +followed by RTEMS community members and new contributors.
> +
> +We have to put in some effort first into the reconstruction of software
> +requirements through reverse engineering using the RTEMS documentation, test
> +cases, sources, standard references, mailing list archives, etc. as input.
> +Writing a technical specification for the complete RTEMS code base is probably
> +a job of several person-years.  We have to get started with a moderate feature
> +set (e.g. subset of the Classic API) and extend it based on user demands step
> +by step.
> +
> +The development of the technical specification will take place in two phases.
> +The first phase tries to establish an initial technical specification for an
> +initial feature set.  This technical specification will be integrated into
> +RTEMS as a big chunk.  In the second phase the technical specification is
> +modified through arranged procedures.  There will be procedures
> +
> +* to modify existing requirements,
> +
> +* add new requirements, and
> +
> +* mark requirements as obsolete.
> +
> +All procedures should be based on a peer review principles.
> +
> +Requirements for Requirements
> +=============================
> +
> +Identification
> +--------------
> +
> +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
> +a best effort approach, the name *RTEMS* shall be used as a part in all
> +requirement identifiers. This should ensure that the RTEMS requirements can be
> +referenced easily in larger systems.  The standard ECSS-E-ST-10-06C recommends
> +in section 8.2.6 that the identifier should reflect the type of the requirement
> +and the life profile situation.  Other standards may have other
> +recommendations.  To avoid a bias of RTEMS in the direction of ECSS, this
> +recommendation will not be followed.
> +
> +.. topic:: Doorstop
> +
> +    The UID of an item (requirement) is defined by its file name without the
> +    extension. An UID consists of two parts, the prefix and a number. The parts
> +    are divided by an optional separator. The prefix is determined by the
> +
> +The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or
> +more component names, and a 3-digit number.  Each part is separated by a "-"
> +character.  For example UIDs from RTEMS-Classic-Task-Create-001 to
> +RTEMS-Classic-Task-Create-999 are task create requirements, UIDs from
> +RTEMS-Classic-Semaphore-Delete-001 to RTEMS-Classic-Semaphore-Delete-999 are
> +semaphore delete requirements, etc.
> +
> +.. topic:: Doorstop
> +
> +    Doorstop uses documents to create namespaces (named a prefix in Doorstop).
> +    For the example above, you can create the documents like this:
> +
> +    .. code-block:: none
> +
> +        doorstop create -d 3 RTEMS-Classic -p RTEMS reqs/classic
> +        doorstop create -d 3 RTEMS-Classic-Task -p RTEMS-Classic reqs/classic/task
> +        doorstop create -d 3 RTEMS-Classic-Task-Create -p RTEMS-Classic-Task-Create reqs/classic/task/create
> +        doorstop create -d 3 RTEMS-Classic-Semaphore -p RTEMS-Classic reqs/classic/semaphore
> +        doorstop create -d 3 RTEMS-Classic-Semaphore-Delete -p RTEMS-Classic-Semaphore-Delete reqs/classic/semaphore/delete
> +
> +    The requirement files are organized in directories.
> +
> +A initial requirement hierarchy could be this:
> +
> +* RTEMS
> +
> +  * Build (Building RTEMS BSPs and Libraries)
> +
> +  * Config (Application Configuration)
> +
> +  * Classic
> +
> +    * Task
> +
> +      * Create
> +      * Delete
> +      * Exit
> +      * GetAffinity
> +      * GetPriority
> +      * GetScheduler
> +      * Ident
> +      * IsSuspended
> +      * Iterate
> +      * Mode
> +      * Restart
> +      * Resume
> +      * Self
> +      * SetAffinity
> +      * SetPriority
> +      * SetScheduler
> +      * Start
> +      * Suspend
> +      * WakeAfter
> +      * WakeWhen
> +
> +    * Semaphore
> +
> +      * ...
> +
> +  * POSIX
> +
> +  * ...
> +
> +The specification of the validation of requirements should be maintained also
> +by Doorstop.  For each requirement document there should be a validation child
> +document with a *Test* component name, e.g. RTEMS-Classic-Task-Create-Test.  A
> +Test component may contain also justifications by design and by analysis, unit
> +tests, and integration tests.
> +
> +Level of Requirements
> +---------------------
> +
> +The level of a requirement shall be expressed with one of the verbal forms
> +listed below and nothing else.  The level of requirements are derived from RFC
> +2119 :cite:`RFC2119` and |E10-06| :cite:`ECSS_E_ST_10_06C`.
> +
> +Absolute Requirements
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Absolute requirements shall be expressed with the verbal form *shall* and no
> +other terms.
> +
> +Absolute Prohibitions
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Absolute prohibitions shall be expressed with the verbal form *shall not* and
> +no other terms.
> +
> +.. warning::
> +
> +    Absolute prohibitions may be difficult to verify.  They should not be used.
> +
> +Recommendations
> +~~~~~~~~~~~~~~~
> +
> +Recommendations shall be expressed with the verbal forms *should* and
> +*should not* and no other terms with guidance from RFC 2119:
> +
> +    SHOULD   This word, or the adjective "RECOMMENDED", mean that there
> +    may exist valid reasons in particular circumstances to ignore a
> +    particular item, but the full implications must be understood and
> +    carefully weighed before choosing a different course.
> +
> +    SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean that
> +    there may exist valid reasons in particular circumstances when the
> +    particular behavior is acceptable or even useful, but the full
> +    implications should be understood and the case carefully weighed
> +    before implementing any behavior described with this label.
> +
> +Permissions
> +~~~~~~~~~~~
> +
> +Permissions shall be expressed with the verbal form *may* and no other terms
> +with guidance from RFC 2119:
> +
> +    MAY   This word, or the adjective "OPTIONAL", mean that an item is
> +    truly optional.  One vendor may choose to include the item because a
> +    particular marketplace requires it or because the vendor feels that
> +    it enhances the product while another vendor may omit the same item.
> +    An implementation which does not include a particular option MUST be
> +    prepared to interoperate with another implementation which does
> +    include the option, though perhaps with reduced functionality. In the
> +    same vein an implementation which does include a particular option
> +    MUST be prepared to interoperate with another implementation which
> +    does not include the option (except, of course, for the feature the
> +    option provides.)
> +
> +Possibilities and Capabilities
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Possibilities and capabilities shall be expressed with the verbal form *can*
> +and no other terms.
> +
> +Syntax
> +------
> +
> +Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate
> +requirements.  A recommended reading list to get familiar with this approach is
> +:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and
> +:cite:`Mavin:2016:LLEARS`.  Please also have a look at the EARS quick reference
> +sheet :cite:`Uusitalo:2012:EARS`.  The sentence types are:
> +
> +* Ubiquitous
> +
> +    The <system name> shall <system response>.
> +
> +* Event-driven
> +
> +    *When* <optional preconditions> <trigger>, the <system name> shall <system response>.
> +
> +* State-driven
> +
> +    *While* <in state>, the <system name> shall <system response>.
> +
> +* Unwanted behaviour
> +
> +    *If* <optional preconditions> <trigger>, *then* the <system name> shall <system response>.
> +
> +* Optional
> +
> +    *Where* <feature>, the <system name> shall <system response>.
> +
> +The optional sentence type should be only used for application configuration
> +options.  The goal is to use *enabled-by* and *disabled-by* attributes to
> +enable or disable requirements based on configuration parameters that define
> +the RTEMS artefacts used to build an application executable (header files,
> +libraries, linker command files).  Such configuration parameters are for
> +example the architecture, the platform, CPU port options, and build
> +configuration options (e.g. uniprocessor vs. SMP).
> +
> +Wording Restrictions
> +--------------------
> +
> +The prevent the expression of imprecise requirements, the following terms shall
"To prevent"

> +not be used in requirement formulations:
> +
> +* "acceptable"
> +* "adequate"
> +* "almost always"
> +* "and/or"
> +* "appropriate"
> +* "approximately"
> +* "as far as possible"
> +* "as much as practicable"
> +* "best"
> +* "best possible"
> +* "easy"
> +* "easy"
> +* "efficient"
> +* "e.g."
> +* "enable"
> +* "enough"
> +* "etc."
> +* "few"
> +* "first rate"
> +* "flexible"
> +* "generally"
> +* "goal"
> +* "graceful"
> +* "great"
> +* "greatest"
> +* "ideally"
> +* "i.e."
> +* "if possible"
> +* "in most cases"
> +* "large"
> +* "many"
> +* "maximize"
> +* "minimize"
> +* "most"
> +* "multiple"
> +* "necessary"
> +* "numerous"
> +* "optimize"
> +* "ought to"
> +* "probably"
> +* "quick"
> +* "rapid"
> +* "reasonably"
> +* "relevant"
> +* "robust"
> +* "satisfactory"
> +* "several"
> +* "shall be included but not limited to"
> +* "simple"
> +* "small"
> +* "some"
> +* "state-of-the-art".
> +* "sufficient"
> +* "suitable"
> +* "support"
> +* "systematically"
> +* "transparent"
> +* "typical"
> +* "user-friendly"
> +* "usually"
> +* "versatile"
> +* "when necessary"
> +
> +For guidelines to avoid these terms see Table 11-2, "Some ambiguous terms to
> +avoid in requirements" in :cite:`Wiegers:2013:SR`.
> +
> +Separate Requirements
> +---------------------
> +
> +Requirements shall be stated separately.  A bad example is:
> +
> +    RTEMS-001: The task create directive shall evaluate the parameters,
> +    allocate a task object and initialize it.
> +
> +To make this a better example, it should be split into separate requirements:
> +
> +    RTEMS-001: When the task create directive is called with valid parameters
> +    and a free task object exists, the task create directive shall return the
> +    identifier of an initialized task object and the RTEMS_SUCCESSFUL status.
> +
> +    RTEMS-002: If no free task objects exists, the task create directive shall
> +    return the RTEMS_TOO_MANY status.
> +
> +    RTEMS-003: If the id parameter is NULL, the task create directive shall
> +    return the RTEMS_INVALID_ADDRESS status.
> +
> +    RTEMS-004: If the name parameter is not valid, the task create directive
> +    shall return the RTEMS_INVALID_NAME status.
> +
> +    ...
> +
> +Conflict Free Requirements
> +--------------------------
> +
> +Requirements shall not be in conflict with each other inside a specification.
> +A bad example is:
> +
> +    RTEMS-013: If a mutex is not available, the mutex obtain directive shall
> +    enqueue the calling thread on the wait queue of the mutex.
> +
> +    RTEMS-042: If a mutex is not available, the mutex obtain directive shall
> +    return the RTEMS_UNSATISFIED status.
> +
> +To resolve this conflict, a condition may be added:
> +
> +    RTEMS-013: If a mutex is not available, when the RTEMS_WAIT option is set,
> +    the mutex obtain directive shall enqueue the calling thread on the wait
> +    queue of the mutex.
> +
> +    RTEMS-042: If a mutex is not available, when the RTEMS_WAIT option is not
> +    set, the mutex obtain directive shall return the RTEMS_UNSATISFIED status.
> +
> +Use of Project-Specific Terms and Abbreviations
> +-----------------------------------------------
> +
> +All project-specific terms and abbreviations used to formulate requirements
> +shall be defined in the project glossary.
> +
> +Justification of Requirements
> +-----------------------------
> +
> +The requirements shall have a justification recorded in a dedicated section of
> +the requirements file.
> +
> +Specification Items
> +===================
> +
> +The technical specification of RTEMS will contain requirements, specializations
> +of requirements, test procedures, test suites, test cases, and justifications
> +by design and by analysis.  These things will be called *specification items*
> +or just *items* if it is clear from the context.
> +
> +.. topic:: Doorstop
> +
> +    Doorstop maintains *items* which are included in *documents*.  The normal
> +    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 justifications by design and by analysis.  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
> +        A boolean value which indicates if the requirement is active or not.
> +        The value is included in the fingerprint via a document configuration
> +        option.
> +
> +    derived
> +        A boolean value which indicates if the requirement derived or not.  For
"is derived"

> +        the definition of *derived* see the Doorstop documentation.  For RTEMS,
> +        this value shall be false for all requirements.  The value is not
> +        included in the fingerprint.
> +
> +    normative
> +        A boolean value which indicates if the requirement derived or not.  For
is "derived"? or "is normative"?

> +        the definition of *normative* see the Doorstop documentation.  For
> +        RTEMS, this value shall be true for all requirements.  The value is not
> +        included in the fingerprint.
> +
> +    level
> +        Indicates the presentation order within a document.  For RTEMS, this
> +        value shall be unused.  The value is not included in the fingerprint.
> +
> +    header
> +        A header for an item.  For RTEMS, this value shall be the empty string.
> +        The value is not included in the fingerprint.
> +
> +    reviewed
> +        The fingerprint of the item.  Maintain this attribute with the
> +        `doorstop clear` command.
> +
> +    links
> +        The links from this item to parent items.  Maintain this attribute with
> +        the `doorstop link` command.  The value is included in the fingerprint.
> +
> +    ref
> +        References to files and directories. See
> +        `#365 <https://github.com/jacebrowning/doorstop/issues/365>`_,
> +        The value is included in the fingerprint.
> +
> +    text
> +        The item text.  The value is included in the fingerprint.
> +
> +    All items shall have the following extended attributes:
> +
> +    type:
> +        A list of :ref:`item types <ReqEngItemTypes>`.  The value is not
> +        included in the fingerprint.
> +
> +    enabled-by:
> +        A list of strings which enable the item if a matching configuration
> +        option is present.  An empty list means the item is unconditionally
> +        enabled.  The *enabled-by* attribute has a lower priority than the
> +        *disabled-by* attribute.  The value is included in the fingerprint.
> +
> +    disabled-by:
> +        A list of strings which disables the item if a matching configuration
> +        option is present.  An empty list means the item is unconditionally
> +        disabled.  The *disabled-by* attribute has a higher priority than the
> +        *enabled-by* attribute.  The value is included in the fingerprint.
> +
> +.. _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 be in line with ECSS-E-ST-10-06 and possible future
"to be"

> +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:
> +
> +* functional requirements - Functional requirements shall describe the behaviour of the
> +  software under specific conditions.
> +
> +    * *application configuration*
> +
> +    * *function*
> +
> +    * *operational* - Operational requirements shall
> +
> +        * define the operation modes (e.g. initialization, multitasking, termination),
> +
> +        * describe the operation modes, and
> +
> +        * describe the operation mode transitions.
> +
> +* non-functional requirements
> +
> +    * *application interface*
> +
> +    * *architecture interface*
> +
> +    * *build configuration*
> +
> +    * *constraint*
> +
> +    * *design*
> +
> +    * *hardware interface*
> +
> +    * *maintainability*
> +
> +    * *performance*
> +
> +    * *portability*
> +
> +    * *quality*
> +
> +    * *reliability*
> +
> +    * *resource*
> +
> +    * *tool chain interface*
> +
> +* *test procedure*
> +
> +* *test suite*
> +
> +* *test case*
> +
> +* *justification by analysis*
> +
> +* *justification by design*
> +
> +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.
> +
> +Application Configuration
> +-------------------------
> +
> +Application configuration requirements define the system parameters which can
> +be set by the user at link-time.  The goal is to generate user manual
> +documentation parts and test cases from the application configuration
> +requirements.  A YAML scheme needs to be defined for this purpose.
> +
> +Application Interface
> +---------------------
> +
> +Application interface requirements shall describe the interface between the
> +software and the application (:term:`API`).  The goal is to generate header
> +files with Doxygen markup and user manual documentation parts from the
> +application interface requirements.  A YAML scheme needs to be defined for this
> +purpose.
> +
> +Tool Chain Interface
> +--------------------
> +
> +Tool chain interface requirements shall describe the interface between the
> +software and the tool chain libraries (e.g. Newlib, GCC).
> +
> +Architecture Interface
> +----------------------
> +
> +Architecture interface requirements shall describe the interface between the
> +software and the processor architecture (:term:`ABI`).
> +
> +Hardware Interface
> +------------------
> +
> +Hardware interface requirements shall describe the interface between the
> +software and hardware components.
> +
> +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.
> +
> +Requirement Traceability
> +========================
> +
> +The standard |E10-06| demands that requirements shall be under configuration
> +management, backwards-traceable and forward-traceable.
> +
> +History of Requirements
> +-----------------------
> +
> +The RTEMS requirements should placed in the RTEMS sources using Git for version
> +control.  The history of requirements can be traced with Git.  Special commit
> +procedures for changes in requirement files should be established.  For
> +example, it should be allowed to change only one requirement per commit.  A
> +dedicated Git commit message format may be used as well, e.g. use of
> +``Approved-by:`` or ``Reviewed-by:`` lines which 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>`_).
> +
> +Backward Traceability of Requirements
> +-------------------------------------
> +
> +Providing backward traceability of requirements means that we must be able to
> +find the corresponding higher level requirement for each refined requirement.
> +This is a standard Doorstop feature.
> +
> +Forward Traceability of Requirements
> +------------------------------------
> +
> +For forward traceability we must find the implementation of each requirement.
> +This will be provided through special Doxygen markup.
> +
> +Requirement Verification
> +========================
> +
> +The verification of each requirement shall be accomplished by one or more of
> +the following methods and nothing else:
> +
> +* *By test*: A test specification is provided to demonstrate that the requirement
> +  is satisfied when the software is executed on the target platform.
> +
> +* *By design*: A rationale is provided to demonstrate how the qualification
> +  requirement is satisfied implicitly by the software design.
> +
> +* *By analysis*: A statement is provided how the requirement is met, by analysing
> +  static properties of the software.
> +
> +.. topic:: Doorstop
> +
> +    For an item in a parent document it is checked that at least one item in a
> +    child document has a link to it.  For example a child document could
> +    contain verification items.  With this feature you can check that all
> +    requirements are covered by at least one verification item.
> +
> +Requirement Management
> +======================
> +
> +Change Control Board
> +--------------------
> +
> +Working with requirements usually involves a Change Control Board
> +(:term:`CCB`).  The CCB of the RTEMS project is the
> +`RTEMS developer mailing list <https://lists.rtems.org/mailman/listinfo/devel>`_.
> +
> +There are the following actors involved:
> +
> +* *RTEMS users*: Everyone using the RTEMS real-time operating system to design,
> +  develop and build an application on top of it.
> +
> +* *RTEMS developers*: The persons developing and maintaining RTEMS.  They write
> +  patches to add or modify code, requirements, tests and documentation.
> +
> +* *RTEMS maintainers*: They are listed in the
> +  `MAINTAINERS <https://git.rtems.org/rtems/tree/MAINTAINERS>`_ file and have
> +  write access to the project repositories.
> +
> +.. TODO: Make a reference to the "normal patch review process".
> +
> +Adding and changing requirements follows the normal patch review process.
> +Reviews and comments may be submitted by anyone, but a maintainer review is
> +required to approve *significant* changes.  In addition for significant
> +changes, there should be at least one reviewer with a sufficient independence
> +from the author which proposes a new requirement or a change of an existing
> +requirement.  Working in another company on different projects is sufficiently
> +independent.  RTEMS maintainers do not know all the details, so they trust in
> +general people with experience on a certain platform.  Sometimes no review
> +comments may appear in a reasonable time frame, then an implicit agreement to
> +the proposed changes is assumed.  Patches can be sent at anytime, so
> +controlling changes in RTEMS requires a permanent involvement on the RTEMS
> +developer mailing list.
> +
> +For a qualification of RTEMS according to certain standards, the requirements
> +may be approved by an RTEMS user.  The approval by RTEMS users is not the
> +concern of the RTEMS project, however, the RTEMS project should enable RTEMS
> +users to manage the approval of requirements easily.  This information may be
> +also used by a independent authority which comes into play with an Independent
> +Software Verification and Validation (:term:`ISVV`).  It could be used to
> +select a subset of requirements, e.g. look only at the ones approved by a
> +certain user.  RTEMS users should be able to reference the determinative
> +content of requirements, test procedures, test cases and justification reports
> +in their own documentation.  Changes in the determinative content should
> +invalidate all references to previous versions.
> +
> +.. topic:: Doorstop
> +
> +    In Doorstop some values of an item (generalization of a requirement)
> +    contribute to a
> +    `fingerprint of the item <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/items.md#reviewed>`_.
> +    Changing a value, e.g. the text of a requirement, changes the fingerprint.
> +    The links from one item to another include the fingerprint, so the impact
> +    of changes is also visible to dependent items.  Currently, MD5 is used as
> +    the hash.  Since this hash is insecure, it is proposed to add a
> +    configuration option to Doorstop which enables SHA512 for hashes.
> +
> +Add a Requirement
> +-----------------
> +
> +.. image:: ../images/eng/req-add.*
> +    :scale: 70
> +    :align: center
> +
> +.. _ReqEngModifyRequirement:
> +
> +Modify a Requirement
> +--------------------
> +
> +.. image:: ../images/eng/req-modify.*
> +    :scale: 70
> +    :align: center
> +
> +Mark a Requirement as Obsolete
> +------------------------------
> +
> +Requirements shall be never removed.  They shall be marked as obsolete.  This
> +ensures that requirement identifiers are not reused.  The procedure to obsolete
> +a requirement is the same as the one to :ref:`modify a requirement
> +<ReqEngModifyRequirement>`.
> +
> +Tooling
> +=======
> +
> +Tool Requirements
> +-----------------
> +
> +To manage requirements some tool support is helpful.  Here is a list of requirements for the tool:
> +
> +* The tool shall be open source.
> +
> +* The tool should be actively maintained during the initial phase of the RTEMS
> +  requirements specification.
> +
> +* The tool shall use plain text storage (no binary formats, no database).
> +
> +* The tool shall support version control via Git.
> +
> +* The tool should export the requirements in a human readable form using the Sphinx documentation framework.
> +
> +* The tool shall support traceability of requirements to items external to the tool.
> +
> +* The tool shall support traceability between requirements.
> +
> +* The tool shall support custom requirement attributes.
> +
> +* The tool should ensure that there are no cyclic dependencies between requirements.
> +
> +* The tool should provide an export to :term:`ReqIF`.
> +
> +Tool Evaluation
> +---------------
> +
> +During an evaluation phase the following tools were considered:
> +
> +* `aNimble <https://sourceforge.net/projects/nimble/>`_
> +* :term:`Doorstop`
> +* `OSRMT <https://github.com/osrmt/osrmt>`_
> +* `Papyrus <https://www.eclipse.org/papyrus/>`_
> +* `ProR <https://www.eclipse.org/rmf/pror/>`_
> +* `ReqIF Studio <https://formalmind.com/tools/studio/>`_
> +* `Requirement Heap <https://sourceforge.net/projects/reqheap/>`_
> +* `rmToo <http://rmtoo.florath.net/>`_
> +
> +The tools aNimble, OSRMT and Requirement Heap were not selected since they use
> +a database.  The tools Papyrus, ProR and ReqIF are Eclipse based and use
> +complex XML files for data storage.  They were difficult to use and lack good
> +documentation/tutorials.  The tools rmToo and Doorstop turned out to be the
> +best candidates to manage requirements in the RTEMS project.  The Doorstop tool
> +was selected as the first candidate mainly due a recommendation by an RTEMS
> +user.
> +
> +Tool Candidate - Doorstop
> +-------------------------
> +
> +:term:`Doorstop` has a modern, object-oriented and well-structured
> +implementation in Python 3.5 under the LGPLv3 license.  It uses a continuous
> +integration build with style checkers, static analysis, documentation checks,
> +code coverage, unit test and integration tests.  In 2019, the project was
> +actively maintained.  Pull requests for minor improvements were reviewed and
> +integrated within days, e.g.
> +`#339 <https://github.com/jacebrowning/doorstop/pull/339>`_,
> +`#343 <https://github.com/jacebrowning/doorstop/pull/343>`_,
> +`#346 <https://github.com/jacebrowning/doorstop/pull/346>`_, and
> +`#347 <https://github.com/jacebrowning/doorstop/pull/347>`_.
> +Each requirement is contained in a single file in :term:`YAML` format.
> +Requirements are organized in documents and can be linked to each other
> +:cite:`Browning:2014:RequirementsManagement`.
> diff --git a/images/eng/req-add.uml b/images/eng/req-add.uml
> new file mode 100644
> index 0000000..52b01f0
> --- /dev/null
> +++ b/images/eng/req-add.uml
> @@ -0,0 +1,40 @@
> +' SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +' Copyright (C) 2019 embedded brains GmbH
> +
> + at startuml
> +
> +start
> +
> +:Invoke: ""doorstop add RTEMS"";
> +
> +note right
> +  This will create a new requirement.
> +  For this activity its UID shall be NEW.
> +  It is located in a file NEW.yml.
> +end note
> +
> +while (Needs a link to a parent requirement?) is (Yes)
> +  :Invoke: ""doorstop link NEW PARENT"";
> +endwhile (No)
> +
> +repeat
> +  :Invoke: ""doorstop edit NEW"";
> +
> +  :Edit the requirement according to your needs and save it;
> +
> +  :Commit NEW.yml with a proper message;
> +
> +  :Send the patch to the devel at rtems.org mailing list for review;
> +repeat while (Reviewers demand changes in the new requirement?) is (Yes)
> +->No;
> +
> +if (New requirement was accepted by reviewers?) then (Yes)
> +  :Push the commit to the project repository;
> +else (No)
> +  :Discard the NEW requirement;
> +endif
> +
> +stop
> +
> + at enduml
> diff --git a/images/eng/req-modify.uml b/images/eng/req-modify.uml
> new file mode 100644
> index 0000000..cb104a6
> --- /dev/null
> +++ b/images/eng/req-modify.uml
> @@ -0,0 +1,34 @@
> +' SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +' Copyright (C) 2019 embedded brains GmbH
> +
> + at startuml
> +
> +start
> +
> +repeat
> +  :Invoke: ""doorstop edit REQ"";
> +
> +  note right
> +    For this activity the UID
> +    of the requirement shall be REQ.
> +    It is located in a file REQ.yml.
> +  end note
> +
> +  :Edit the requirement according to your needs and save it;
> +
> +  :Commit REQ.yml with a proper message;
> +
> +  :Send the patch to the devel at rtems.org mailing list for review;
> +repeat while (Reviewers demand changes in the modified requirement?) is (Yes)
> +->No;
> +
> +if (Modified requirement was accepted by reviewers?) then (Yes)
> +  :Push the commit to the project repository;
> +else (No)
> +  :Keep the requirement as is;
> +endif
> +
> +stop
> +
> + at enduml
> --
> 2.16.4
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel



More information about the devel mailing list