Add Requirements Engineering chapter to RTEMS Software Engineering Handbook

[Sebastian Huber]

The chapter should cover the following topics:

• Overview and introduction
• Evaluation of tools for requirements management
• Selected tool for requirements management
• Evaluation of data models and formats for the requirements
• Definition of data model and format actually used for the project (may overlap with tool)
• Requirements management workflow used in the project
• Requirements on requirements, e.g. derived from standards such as ​ECSS-E-ST-10-06C
• Requirement identifiers used to ensure traceability

[Chris Johns]

How does the quality of RTEMS and it's requirements depend on the evaluation and selection of the tools for requirement management? I can understand the quality of the requirements effecting the quality of RTEMS but not the tools used to capture them? Why have the process, ie a sort of log book, in the engineering handbook? I would have expected this document to contain the out come of the discovery process and not the process itself.

I am concerned adding these things just creates a liability for the project. Can an email archive can perform this task?

[Joel Sherrill]

I agree with Chris. A trade study of requirements tools shouldn't end up in the handbook. Perhaps our requirements for a tool.

• open source
• supports format XXX for interchange
• supports links for requirement derivation
• ...

[Sebastian Huber]

Yes, maybe this is not the best place for the tool overview. I though it would be helpful in case someone asks in two years, why did you use this, have you considered that, etc.? Should I add a ticket for the tool selection instead?

[Chris Johns]

Replying to Sebastian Huber:

Yes, maybe this is not the best place for the tool overview. I though it would be helpful in case someone asks in two years, why did you use this, have you considered that, etc.?

A brief rational can be helpful, but the details can be distracting. I feel the simpler and more direct this document is the more effective it will be.

Should I add a ticket for the tool selection instead?

Yes, it can links to mailing lists discussions and attachments and it is easy to link too.

[Sebastian Huber <sebastian.huber@…>]

In d412c5b/rtems-docs:

eng: Add Software Requirements Engineering chapter

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 6f0bc56/rtems-docs:

eng: Add glossary terms

Define the following terms:

• assembler language
• C language
• ELF
• interrupt service
• software component
• software unit

Clarify:

• task

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In d4ba908/rtems-docs:

eng: Update requirements engineering chapter

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

Update the application configuration related specification items.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 59312aa/rtems-docs:

eng: Split up requirements engineering chapter

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

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 23ab40d/rtems-docs:

eng: Add generated documentation of spec items

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

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

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 459326c/rtems-docs:

eng: Update requirements tooling section

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 9b269ad/rtems-docs:

eng: Add interface specification how-to

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In f547988/rtems-docs:

eng: Simplify wording for specification items

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 0c43c52/rtems-docs:

eng: Add generic attribute key types

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 0213e8e/rtems-docs:

eng: Add a specification type for actions

Add support to specify functional requirements for actions (functions or
macros) via a transition map of pre-conditions to post-conditions. This
will be the work horse for functional requirements. Generation of
corresponding validation tests is supported.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In ca2f5e6/rtems-docs:

eng: Update specification how-to section

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In db3892b/rtems-docs:

eng: Update action requirement specification

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 87a9478/rtems-docs:

eng: Clarify action requirement specification

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 1bd14cd/rtems-docs:

eng: Reformat to maximize the text width

Remove extra "X" character in some labels.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 0c13e94/rtems-docs:

eng: Fix typo

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In fd2fc50/rtems-docs:

eng: Add requirement text to interface groups

This allows to state the requirement for an interface group directly in
the item.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In f12cae1/rtems-docs:

eng: Add brief description to header file items

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In c259563/rtems-docs:

eng: Support N/A in the action transitions

Sometimes the pre-conditions in an action requirement are not
independent and it is necessary to mark pre-conditions as not applicable
in a particular transition.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 3f9fa47/rtems-docs:

eng: Add ability to skip action transitions

Sometimes the pre-conditions in an action requirement are not
independent and it is necessary skip a certain set of pre-condition
states. This should be used with care since no test code is run in
these cases. There shall be a reason given why skipping a transition is
justified.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 1bb6947/rtems-docs:

eng: Fix format of regular expressions

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In bac4398/rtems-docs:

eng: Fix typo

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In e1e0408/rtems-docs:

eng: Partially revert previous commit

The previous commit contained more than just a typo fix. Remove this
part.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 83e13b7/rtems-docs:

eng: Add application config options how-to

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 3e8e301/rtems-docs:

eng: Add more variants of unspecified interfaces

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 5cb493e/rtems-docs:

eng: Add reference to unspecified interfaces

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 9633e98/rtems-docs:

eng: Add test case attributes

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 1a48655/rtems-docs:

eng: Remove test name attribute

Derive the test name from the item UID.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 83a3522/rtems-docs:

eng: Add test header to test case

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 93938c7/rtems-docs:

eng: Unify test attribute keys

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 57fb30d/rtems-docs:

eng: Add automatically generated warning

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In c18215c/rtems-docs:

eng: Move index-entries to all interfaces

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In bcf4a95/rtems-docs:

eng: Add placement link role

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In abc9c44/rtems-docs:

eng: Replace spec2doc.py with spec2modules.py

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In f610291/rtems-docs:

eng: Add function attributes

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In bbd8d4a/rtems-docs:

eng: Fix typo

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 4b03ff7/rtems-docs:

eng: Add performance specification items

Add items to specify runtime performance requirements.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In a08e672/rtems-docs:

eng: Add design group requirement item type

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 174444f/rtems-docs:

eng: Update test case item

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In fcac22e/rtems-docs:

eng: Fix typo

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In a4b3019/rtems-docs:

eng: Add how-to for action requirements

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In e05df28/rtems-docs:

eng: Clarify how-to for action requirements

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 0518d94/rtems-docs:

eng: Clarify how-to for action requirements

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In bc0a857/rtems-docs:

eng: Clarify how-to for action requirements

Bring how-to in line with current action requirements.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 239644b/rtems-docs:

eng: Update EARS syntax

The document used the EARS syntax from 2009 which slightly changed in
2016, see "Listens Learned (8 Lessons Learned Applying EARS)". The
optional pre-conditions moved to the state-driven pattern. This refined
syntax fits better to the action requirements.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In b580a6d/rtems-docs:

eng: Add build/appl config clauses to how-to

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In b40e043/rtems-docs:

eng: Document expressions in action requirements

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 4476290/rtems-docs:

eng: Add example to action requirements how-to

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 3fa9ed4/rtems-docs:

eng: Allow multiple interface references

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 889a5ff/rtems-docs:

eng: Remove embedded constraints

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In e263e84/rtems-docs:

eng: Add unit test link role

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In b6cb057/rtems-docs:

eng: Remove scope from constraints

Use links instead of this special purpose attributes.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In a95c968/rtems-docs:

eng: Add test suite name

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In aa0c495/rtems-docs:

eng: Remove text attribute from acfg options

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In b797009/rtems-docs:

eng: Add unspecified interface groups

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 76b5b81/rtems-docs:

eng: Add freestanding test cases

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 7b2b1b4/rtems-docs:

eng: Simplify interface return specification

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 9dd6135/rtems-docs:

eng: Add interface params/return to typedefs

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 60e08fd/rtems-docs:

eng: Make interface definitions optional

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 2df0d64/rtems-docs:

eng: Add hidden interface group membership

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In dd60a4a/rtems-docs:

eng: Add script usage to how-to

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 889a498d/rtems-docs:

eng: Remove interface container item type

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In c812323/rtems-docs:

eng: Unify interface function and macro

This allows the documentation of parameter and return types for macros.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 1d9f9af/rtems-docs:

eng: Add function implementation link role

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In c909228/rtems-docs:

eng: Refine unspecified interfaces

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 4966ed0/rtems-docs:

eng: Remove appl config group member link role

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In b55c8bf/rtems-docs:

eng: Use type refinement for validation method

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 4fddb23/rtems-docs:

eng: Add memory benachmark type refinement

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 0b0dd79/rtems-docs:

eng: Use a recommendation for requirement texts

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 6dc190b/rtems-docs:

eng: Rework performance meansurement items

Use links to specify runtime performance limits in target-specific
items. Clarify wording.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 5928d04/rtems-docs:

eng: Generalize external references

Use a common subtype for external references of interfaces and
requirements. Add specializations for document and file references.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In c81a244/rtems-docs:

eng: Add conditional build dependencies

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 98172bc/rtems-docs:

eng: Use type refinement for validation method

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 77e8b56/rtems-docs:

eng: Add optional floating-point number type

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 7158449/rtems-docs:

eng: Update application configuration how-to

Change paths to be in line with the actual specification. Fix group
membership link role.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In c69046e/rtems-docs:

eng: Remove obsolete type listing

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 2a5e59d/rtems-docs:

eng: Add design target item type

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 8bc24e5/rtems-docs:

eng: Add proxy item type

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 9a5fb29/rtems-docs:

eng: Remove ambiguous interface types

Use an item proxy instead.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 63286a5/rtems-docs:

eng: Add an item type for not defined defines

This helps to deduce that a missing define in the software design is
intended.

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 2fecb7a/rtems-docs:

eng: Make design group identifiers optional

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 9c2498a/rtems-docs:

eng: Add unspecified header file item type

Update #3715.

[Sebastian Huber <sebastian.huber@…>]

In 2e939ff/rtems-docs:

eng: Add register block specification types

A register block may be used to specify the interface of devices which
contain registers associated with an integer address. Register blocks
consist of register block members specified by the definition
attribute. Register block members are either instances of registers
specified by the registers attribute or instances of other register
blocks specified by links with the "register-block-include" link role.
Registers consists of bit fields. The register block members are placed
into the address space of the device relative to the base address of the
register block. Register member offests and the register block size are
specified in units of the address space granule.

Update #3715.

[Sebastian Huber]

The initial work for this chapter is now done. The specification of the specification items in rtems-central is in line with the rtems-docs repository. Further work in this area should be done under a new ticket.