5. Software Requirements Engineering

Software engineering standards for critical software such as ECSS-E-ST-40C demand that software requirements for a software product are collected in a software requirements specification (technical specification in ECSS-E-ST-40C terms). They are usually derived from system requirements (requirements baseline in ECSS-E-ST-40C 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 [Mot88] and later the ORKID [VIT90] 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 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 from FreeBSD to use its network stack, USB stack, SD/MMC card stack and device drivers resulted in another set of requirements. The addition of 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.

Guidance

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.

5.1. Requirements for Requirements

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

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 name or a number. The parts are divided by an optional separator. The prefix is determined by the document.

The UID scheme for RTEMS requirements is the concatenation of RTEMS, one or more component names, and a name. Each part is separated by a “-” character. For example, the UID RTEMS-CLASSIC-TASK-CREATERRINVADDR may specify that the rtems_task_create() directive shall return a status of RTEMS_INVALID_ADDRESS if the id parameter is NULL.

Doorstop

Doorstop uses documents to create namespaces (named a prefix in Doorstop). For the example above, you can create the documents like this:

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:

  • RTEMS

    • BUILD (building RTEMS BSPs and libraries)

    • CONFIG (application configuration)

    • CLASSIC

      • TASK

        • CREAT* (requirements for rtems_task_create())

        • DELT* (requirements for rtems_task_delete())

        • EXIT* (requirements for rtems_task_exit())

        • GETAFF* (requirements for rtems_task_get_affinity())

        • GETPRI* (requirements for rtems_task_get_priority())

        • GETSHD* (requirements for rtems_task_get_scheduler())

        • IDNT* (requirements for rtems_task_ident())

        • ISSUSP* (requirements for rtems_task_is_suspended())

        • ITER* (requirements for rtems_task_iterate())

        • MODE* (requirements for rtems_task_mode())

        • RESTRT* (requirements for rtems_task_restart())

        • RESUME* (requirements for rtems_task_resume())

        • SELF* (requirements for rtems_task_self())

        • SETAFF* (requirements for rtems_task_set_affinity())

        • SETPRI* (requirements for rtems_task_set_priority())

        • SETSHD* (requirements for rtems_task_set_scheduler())

        • START* (requirements for rtems_task_start())

        • SUSP* (requirements for rtems_task_suspend())

        • WKAFT* (requirements for rtems_task_wake_after())

        • WKWHN* (requirements for rtems_task_wake_when())

      • Semaphore

    • POSIX

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 clear scheme for all Classic API managers may help to keep the UIDs short and descriptive.

The specification of the validation of requirements should be maintained also by Doorstop. For each requirement document there should be a validation child Doorstop document with a TEST component name, e.g. RTEMS-CLASSIC-TASK-TEST. A test document may contain also validations by analysis, by inspection, and by design, see Requirement Validation.

5.1.2. 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 [Bra97] and ECSS-E-ST-10-06C [ECS09].

5.1.2.1. Absolute Requirements

Absolute requirements shall be expressed with the verbal form shall and no other terms.

5.1.2.2. Absolute Prohibitions

Absolute prohibitions shall be expressed with the verbal form shall not and no other terms.

Warning

Absolute prohibitions may be difficult to validate. They should not be used.

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

5.1.2.4. 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.)

5.1.2.5. Possibilities and Capabilities

Possibilities and capabilities shall be expressed with the verbal form can and no other terms.

5.1.3. Syntax

Use the Easy Approach to Requirements Syntax (EARS) to formulate requirements. A recommended reading list to get familiar with this approach is [MWHN09], [MW10], and [MWGU16]. Please also have a look at the EARS quick reference sheet [Uus12]. 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 the enabled-by attribute 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).

5.1.4. Wording Restrictions

To prevent the expression of imprecise requirements, the following terms shall 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”

  • “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 [WB13]. There should be some means to enforce that these terms are not used, e.g. through a client-side pre-commit Git hook, a server-side pre-receive Git hook, or some scripts run by special build commands.

5.1.5. Separate Requirements

Requirements shall be stated separately. A bad example is:

RTEMS-CLASSIC-TASK-CRAT

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-CLASSIC-TASK-CRAT

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 an initialized task object to the id parameter and return the RTEMS_SUCCESSFUL status.

RTEMS-CLASSIC-TASK-CRATERRTOOMANY

If no free task objects exists, the task create directive shall return the RTEMS_TOO_MANY status.

RTEMS-CLASSIC-TASK-CRATERRINVADDR

If the id parameter is NULL, the task create directive shall return the RTEMS_INVALID_ADDRESS status.

RTEMS-CLASSIC-TASK-CRATERRINVNAME

If the name parameter is not valid, the task create directive shall return the RTEMS_INVALID_NAME status.

5.1.6. Conflict Free Requirements

Requirements shall not be in conflict with each other inside a specification. A bad example is:

RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT

If a mutex is not available, the mutex obtain directive shall enqueue the calling thread on the wait queue of the mutex.

RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT

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-CLASSIC-SEMAPHORE-MTXOBWAIT

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-CLASSIC-SEMAPHORE-MTXOBERRUNSAT

If a mutex is not available, when the RTEMS_WAIT option is not set, the mutex obtain directive shall return the RTEMS_UNSATISFIED status.

5.1.7. Use of Project-Specific Terms and Abbreviations

All project-specific terms and abbreviations used to formulate requirements shall be defined in the project glossary.

5.1.8. Justification of Requirements

Each requirement shall have a rationale or justification recorded in a dedicated section of the requirement file.

Doorstop

See rationale attribute for Specification Items.

5.2. Specification Items

The technical specification of RTEMS will contain requirements, specializations of requirements, test procedures, test suites, test cases, and requirement validations. These things will be called specification items or just items if it is clear from the context.

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

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 is derived or not. For 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 is normative or not. For 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, The value is included in the fingerprint.

text

The item text. The value is included in the fingerprint.

All specification items shall have the following extended attributes:

type:

A list of item types. The value is not included in the fingerprint.

enabled-by:

The value is a list of expressions. The value is included in the fingerprint. 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:

enabled-by:
- RTEMS_SMP
enabled-by:
- and:
  - RTEMS_NETWORKING
  - not: RTEMS_SMP
enabled-by:
- and:
  - not: TEST_DEBUGGER01_EXCLUDE
  - or:
    - arm
    - i386

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

_images/req-spec-items.png

5.2.2. Requirements

Doorstop

All requirement specification items shall have the following extended attribute:

rationale:

The rationale or justification of the specification item. The value is not included in the fingerprint.

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

5.2.4. Interface Requirement

Interface requirements shall describe the high level aspects of interfaces. The item type shall be interface-requirement.

5.2.5. Interface

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

5.2.6. Interface - Application Configuration

Doorstop

The application configuration items shall have the following attribute specializations:

type

The type value shall be interface.

interface-category

The interface category value shall be application-configuration.

interface-type

The interface type value shall be configuration-option.

link

There shall be a link to a higher level requirement.

text

The application configuration requirement.

configuration-category:

A category to which this application configuration option belongs.

define:

The name of the configuration define.

data-type:

The data type of the configuration define.

value-range:

The range of valid values.

default-value:

The default value.

description:

The description of the application configuration. 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.

note:

Notes for this application configuration. The notes should explain everything which was omitted from the description. It should cover all the details.

5.2.7. Test Procedure

Test procedures shall be executed by the Qualification Toolchain.

Doorstop

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.

5.2.8. Test Suite

Test suites shall use the RTEMS Test Framework.

Doorstop

The test suite items shall have the following attribute specializations:

type

The type value shall be test-suite.

text

The test suite description.

5.2.9. Test Case

Test cases shall use the RTEMS Test Framework.

Doorstop

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

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

5.3. Traceability of Specification Items

The standard ECSS-E-ST-10-06C demands that requirements shall be under configuration management, backwards-traceable and forward-traceable. Requirements are a specialization of specification items in RTEMS.

5.3.1. History of Specification Items

The RTEMS specification items should placed in the RTEMS sources using Git for version control. The history of specification items can be traced with Git. Special commit procedures for changes in specification item files should be established. For example, it should be allowed to change only one specification item 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). 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 directly in a revision attribute. This would make it possible to generate the history information for documents without having the Git repository available, e.g. from an RTEMS source release archive.

5.3.2. Backward Traceability of Specification Items

Providing backward traceability of specification items means that we must be able to find the corresponding higher level specification item for each refined specification item. This is a standard Doorstop feature.

5.3.3. Forward Traceability of Specification Items

Providing forward traceability of specification items means that we must be able to find all the refined specification items for each higher level specification item. This is a standard Doorstop feature. The links from parent to child specification items are implicitly defined by links from a child item to a parent item.

5.3.4. Traceability between Software Requirements, Architecture and Design

The software requirements are implemented in Doorstop compatible YAML files. The software architecture and design is written in Doxygen markup. Doxygen markup is used throughout all header and source files. A Doxygen filter program may be provided to place Doxygen markup in assembler files. The software architecture is documented via Doxygen groups. Each Doxygen group name should have a project-specific name and the name should be unique within the project, e.g. RTEMSTopLevelMidLevelLowLevel. The link from a Doxygen group to its parent group is realized through the @ingroup special command. The link from a Doxygen group or software component to the corresponding requirement is realized through a @satisfy{req} custom command which needs the identifier of the requirement as its one and only parameter. Only links to parents are explicitly given in the Doxygen markup. The links from a parent to its children are only implicitly specified via the link from a child to its parent. So, a tool must process all files to get the complete hierarchy of software requirements, architecture and design. Links from a software component to another software component are realized through automatic Doxygen references or the @ref and @see special commands.

5.4. Requirement Validation

The validation of each requirement shall be accomplished by one or more of the following methods and nothing else:

  • By test: A Test Case specification item is provided to demonstrate that the requirement is satisfied when the software product is executed on the target platform.

  • By analysis: A statement is provided how the requirement is met, by analysing static properties of the software product.

  • By inspection: A statement is provided how the requirement is met, by inspection of the source code.

  • By review of design: A rationale is provided to demonstrate how the qualification requirement is satisfied implicitly by the software design.

Validation by test is strongly recommended. The choice of any other validation method shall be strongly justified. The requirements author is obligated to provide the means to validate the requirement with detailed instructions.

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 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 specification items shall have the following attribute specializations:

type

The type attribute value shall be validation-by-analysis, validation-by-inspection, or validation-by-review-of-design.

link

There shall be exactly one link to the validated requirement.

text

The statement or rational of the requirement validation.

5.5. Requirement Management

5.5.1. Change Control Board

Working with requirements usually involves a Change Control Board (CCB). The CCB of the RTEMS Project is the RTEMS developer mailing list.

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 file and have write access to the project repositories.

Adding and changing requirements follows the normal patch review process. The normal patch review process is described in the RTEMS User Manual. 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 (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.

5.5.2. Add a Requirement

_images/req-add.png

5.5.3. Modify a Requirement

_images/req-modify.png

5.5.4. 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 modify a requirement.

5.6. Tooling

5.6.1. 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 ReqIF.

5.6.2. Tool Evaluation

During an evaluation phase the following tools were considered:

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.

5.6.3. Selected Tool - Doorstop

Doorstop is a requirements management tool. It has a modern, object-oriented and well-structured implementation in Python 3.6 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 and new features were reviewed and integrated within days. Each requirement is contained in a single file in YAML format. Requirements are organized in documents and can be linked to each other [BA14].

Doorstop consists of three main parts

  • a stateless command line tool doorstop,

  • a file format with a pre-defined set of attributes (YAML), and

  • a primitive GUI tool (not intended to be used).

For RTEMS, its scope will be extended to manage specifications in general. The primary reason for selecting Doorstop as the requirements management tool for 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 files in YAML format. Each item has a set of standard attributes (key-value pairs).

The use case for the standard attributes is requirements management. However, Doorstop is capable to manage custom attributes as well. We will heavily use custom attributes for the specification items. Enabling Doorstop to effectively use custom attributes was done specifically for the RTEMS Project in several patch sets.

A key feature of Doorstop is the fingerprint of items. For the RTEMS Project, the fingerprint hash algorithm was changed from MD5 to SHA256. In 2019, it can be considered cryptographically secure. The fingerprint should cover the normative values of an item, e.g. comments etc. are not included. The fingerprint helps RTEMS users to track the significant changes in the requirements (in contrast to all the changes visible in Git). As an example use case, a user may want to assign a project-specific status to specification items. This can be done with a table which contains columns for

  1. the UID of the item,

  2. the fingerprint, and

  3. the project-specific status.

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 status (e.g. unknown, changed, etc.).