#3715 closed task (fixed)

Add Requirements Engineering chapter to RTEMS Software Engineering Handbook

Reported by: Sebastian Huber Owned by: Sebastian Huber
Priority: normal Milestone: 6.1
Component: doc Version: 6
Severity: normal Keywords: qualification
Cc: Blocked By:
Blocking: #3703


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

Change History (90)

comment:1 Changed on 03/04/19 at 13:10:43 by Sebastian Huber

Status: assignedaccepted
Summary: Add Requirements Engineering chaper to RTEMS Software Engineering HandbookAdd Requirements Engineering chapter to RTEMS Software Engineering Handbook

comment:2 Changed on 03/04/19 at 23:02:03 by 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?

comment:3 Changed on 03/04/19 at 23:06:15 by 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
  • ...

comment:4 Changed on 03/07/19 at 07:34:38 by 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?

comment:5 in reply to:  4 Changed on 03/07/19 at 21:00:27 by 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.

comment:6 Changed on 01/07/20 at 09:14:04 by Sebastian Huber <sebastian.huber@…>

In d412c5b/rtems-docs:

eng: Add Software Requirements Engineering chapter

Update #3715.

comment:7 Changed on 04/02/20 at 07:47:16 by 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


  • task

Update #3715.

comment:8 Changed on 05/05/20 at 05:37:31 by 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.

comment:9 Changed on 06/01/20 at 11:02:31 by 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.

comment:10 Changed on 06/01/20 at 11:02:33 by 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.

comment:11 Changed on 06/01/20 at 11:02:35 by Sebastian Huber <sebastian.huber@…>

In 459326c/rtems-docs:

eng: Update requirements tooling section

Update #3715.

comment:12 Changed on 06/01/20 at 11:02:37 by Sebastian Huber <sebastian.huber@…>

In 9b269ad/rtems-docs:

eng: Add interface specification how-to

Update #3715.

comment:13 Changed on 06/08/20 at 07:05:29 by Sebastian Huber <sebastian.huber@…>

In f547988/rtems-docs:

eng: Simplify wording for specification items

Update #3715.

comment:14 Changed on 06/08/20 at 07:05:31 by Sebastian Huber <sebastian.huber@…>

In 0c43c52/rtems-docs:

eng: Add generic attribute key types

Update #3715.

comment:15 Changed on 06/08/20 at 07:05:33 by 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.

comment:16 Changed on 06/08/20 at 07:05:35 by Sebastian Huber <sebastian.huber@…>

In ca2f5e6/rtems-docs:

eng: Update specification how-to section

Update #3715.

comment:17 Changed on 06/10/20 at 08:12:37 by Sebastian Huber <sebastian.huber@…>

In db3892b/rtems-docs:

eng: Update action requirement specification

Update #3715.

comment:18 Changed on 06/17/20 at 07:11:35 by Sebastian Huber <sebastian.huber@…>

In 87a9478/rtems-docs:

eng: Clarify action requirement specification

Update #3715.

comment:19 Changed on 07/03/20 at 08:34:03 by Sebastian Huber <sebastian.huber@…>

In 1bd14cd/rtems-docs:

eng: Reformat to maximize the text width

Remove extra "X" character in some labels.

Update #3715.

comment:20 Changed on 07/03/20 at 08:34:05 by Sebastian Huber <sebastian.huber@…>

In 0c13e94/rtems-docs:

eng: Fix typo

Update #3715.

comment:21 Changed on 07/28/20 at 05:33:52 by 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.

comment:22 Changed on 07/28/20 at 05:33:54 by Sebastian Huber <sebastian.huber@…>

In f12cae1/rtems-docs:

eng: Add brief description to header file items

Update #3715.

comment:23 Changed on 07/28/20 at 05:33:56 by 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.

comment:24 Changed on 07/28/20 at 05:33:58 by 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

Update #3715.

comment:25 Changed on 07/28/20 at 05:34:01 by Sebastian Huber <sebastian.huber@…>

In 1bb6947/rtems-docs:

eng: Fix format of regular expressions

Update #3715.

comment:26 Changed on 08/06/20 at 07:12:00 by Sebastian Huber <sebastian.huber@…>

In bac4398/rtems-docs:

eng: Fix typo

Update #3715.

comment:27 Changed on 08/06/20 at 07:18:47 by 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

Update #3715.

comment:28 Changed on 08/07/20 at 04:44:14 by Sebastian Huber <sebastian.huber@…>

In 83e13b7/rtems-docs:

eng: Add application config options how-to

Update #3715.

comment:29 Changed on 08/07/20 at 05:15:28 by Sebastian Huber <sebastian.huber@…>

In 3e8e301/rtems-docs:

eng: Add more variants of unspecified interfaces

Update #3715.

comment:30 Changed on 08/07/20 at 05:15:31 by Sebastian Huber <sebastian.huber@…>

In 5cb493e/rtems-docs:

eng: Add reference to unspecified interfaces

Update #3715.

comment:31 Changed on 08/20/20 at 07:01:23 by Sebastian Huber <sebastian.huber@…>

In 9633e98/rtems-docs:

eng: Add test case attributes

Update #3715.

comment:32 Changed on 08/20/20 at 07:01:25 by Sebastian Huber <sebastian.huber@…>

In 1a48655/rtems-docs:

eng: Remove test name attribute

Derive the test name from the item UID.

Update #3715.

comment:33 Changed on 08/20/20 at 07:01:27 by Sebastian Huber <sebastian.huber@…>

In 83a3522/rtems-docs:

eng: Add test header to test case

Update #3715.

comment:34 Changed on 08/20/20 at 07:01:29 by Sebastian Huber <sebastian.huber@…>

In 93938c7/rtems-docs:

eng: Unify test attribute keys

Update #3715.

comment:35 Changed on 08/20/20 at 07:01:32 by Sebastian Huber <sebastian.huber@…>

In 57fb30d/rtems-docs:

eng: Add automatically generated warning

Update #3715.

comment:36 Changed on 10/11/20 at 13:20:43 by Sebastian Huber <sebastian.huber@…>

In c18215c/rtems-docs:

eng: Move index-entries to all interfaces

Update #3715.

comment:37 Changed on 10/11/20 at 13:20:45 by Sebastian Huber <sebastian.huber@…>

In bcf4a95/rtems-docs:

eng: Add placement link role

Update #3715.

comment:38 Changed on 10/24/20 at 10:15:38 by Sebastian Huber <sebastian.huber@…>

In abc9c44/rtems-docs:

eng: Replace spec2doc.py with spec2modules.py

Update #3715.

comment:39 Changed on 11/09/20 at 14:05:33 by Sebastian Huber <sebastian.huber@…>

In f610291/rtems-docs:

eng: Add function attributes

Update #3715.

comment:40 Changed on 11/19/20 at 10:24:36 by Sebastian Huber <sebastian.huber@…>

In bbd8d4a/rtems-docs:

eng: Fix typo

Update #3715.

comment:41 Changed on 11/27/20 at 08:17:00 by Sebastian Huber <sebastian.huber@…>

In 4b03ff7/rtems-docs:

eng: Add performance specification items

Add items to specify runtime performance requirements.

Update #3715.

comment:42 Changed on 01/15/21 at 05:40:59 by Sebastian Huber <sebastian.huber@…>

In a08e672/rtems-docs:

eng: Add design group requirement item type

Update #3715.

comment:43 Changed on 02/08/21 at 14:02:53 by Sebastian Huber <sebastian.huber@…>

In 174444f/rtems-docs:

eng: Update test case item

Update #3715.

comment:44 Changed on 03/02/21 at 07:29:25 by Sebastian Huber <sebastian.huber@…>

In fcac22e/rtems-docs:

eng: Fix typo

Update #3715.

comment:45 Changed on 03/08/21 at 07:29:24 by Sebastian Huber <sebastian.huber@…>

In a4b3019/rtems-docs:

eng: Add how-to for action requirements

Update #3715.

comment:46 Changed on 03/08/21 at 09:19:49 by Sebastian Huber <sebastian.huber@…>

In e05df28/rtems-docs:

eng: Clarify how-to for action requirements

Update #3715.

comment:47 Changed on 03/11/21 at 05:57:22 by Sebastian Huber <sebastian.huber@…>

In 0518d94/rtems-docs:

eng: Clarify how-to for action requirements

Update #3715.

comment:48 Changed on 03/11/21 at 06:54:01 by 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.

comment:49 Changed on 03/19/21 at 07:20:33 by 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.

comment:50 Changed on 03/19/21 at 07:20:35 by Sebastian Huber <sebastian.huber@…>

In b580a6d/rtems-docs:

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

Update #3715.

comment:51 Changed on 03/19/21 at 07:20:37 by Sebastian Huber <sebastian.huber@…>

In b40e043/rtems-docs:

eng: Document expressions in action requirements

Update #3715.

comment:52 Changed on 03/19/21 at 07:20:40 by Sebastian Huber <sebastian.huber@…>

In 4476290/rtems-docs:

eng: Add example to action requirements how-to

Update #3715.

comment:53 Changed on 04/27/21 at 07:46:36 by Sebastian Huber <sebastian.huber@…>

In 3fa9ed4/rtems-docs:

eng: Allow multiple interface references

Update #3715.

comment:54 Changed on 04/29/21 at 05:31:36 by Sebastian Huber <sebastian.huber@…>

In 889a5ff/rtems-docs:

eng: Remove embedded constraints

Update #3715.

comment:55 Changed on 04/29/21 at 05:31:39 by Sebastian Huber <sebastian.huber@…>

In e263e84/rtems-docs:

eng: Add unit test link role

Update #3715.

comment:56 Changed on 04/29/21 at 09:05:21 by Sebastian Huber <sebastian.huber@…>

In b6cb057/rtems-docs:

eng: Remove scope from constraints

Use links instead of this special purpose attributes.

Update #3715.

comment:57 Changed on 04/29/21 at 09:05:24 by Sebastian Huber <sebastian.huber@…>

In a95c968/rtems-docs:

eng: Add test suite name

Update #3715.

comment:58 Changed on 04/30/21 at 05:06:27 by Sebastian Huber <sebastian.huber@…>

In aa0c495/rtems-docs:

eng: Remove text attribute from acfg options

Update #3715.

comment:59 Changed on 05/08/21 at 08:27:49 by Sebastian Huber <sebastian.huber@…>

In b797009/rtems-docs:

eng: Add unspecified interface groups

Update #3715.

comment:60 Changed on 08/03/21 at 08:40:02 by Sebastian Huber <sebastian.huber@…>

In 76b5b81/rtems-docs:

eng: Add freestanding test cases

Update #3715.

comment:61 Changed on 09/10/21 at 14:26:52 by Sebastian Huber <sebastian.huber@…>

In 7b2b1b4/rtems-docs:

eng: Simplify interface return specification

Update #3715.

comment:62 Changed on 09/10/21 at 14:26:54 by Sebastian Huber <sebastian.huber@…>

In 9dd6135/rtems-docs:

eng: Add interface params/return to typedefs

Update #3715.

comment:63 Changed on 09/10/21 at 14:26:57 by Sebastian Huber <sebastian.huber@…>

In 60e08fd/rtems-docs:

eng: Make interface definitions optional

Update #3715.

comment:64 Changed on 09/10/21 at 14:26:59 by Sebastian Huber <sebastian.huber@…>

In 2df0d64/rtems-docs:

eng: Add hidden interface group membership

Update #3715.

comment:65 Changed on 01/24/22 at 14:28:03 by Sebastian Huber <sebastian.huber@…>

In dd60a4a/rtems-docs:

eng: Add script usage to how-to

Update #3715.

comment:66 Changed on 10/04/22 at 06:29:00 by Sebastian Huber <sebastian.huber@…>

In 889a498d/rtems-docs:

eng: Remove interface container item type

Update #3715.

comment:67 Changed on 10/04/22 at 06:29:01 by 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.

comment:68 Changed on 10/04/22 at 06:29:02 by Sebastian Huber <sebastian.huber@…>

In 1d9f9af/rtems-docs:

eng: Add function implementation link role

Update #3715.

comment:69 Changed on 10/04/22 at 06:29:03 by Sebastian Huber <sebastian.huber@…>

In c909228/rtems-docs:

eng: Refine unspecified interfaces

Update #3715.

comment:70 Changed on 10/04/22 at 06:29:05 by Sebastian Huber <sebastian.huber@…>

In 4966ed0/rtems-docs:

eng: Remove appl config group member link role

Update #3715.

comment:71 Changed on 10/04/22 at 06:29:06 by Sebastian Huber <sebastian.huber@…>

In b55c8bf/rtems-docs:

eng: Use type refinement for validation method

Update #3715.

comment:72 Changed on 10/04/22 at 06:29:07 by Sebastian Huber <sebastian.huber@…>

In 4fddb23/rtems-docs:

eng: Add memory benachmark type refinement

Update #3715.

comment:73 Changed on 11/30/22 at 08:52:47 by Sebastian Huber

Milestone: 6.17.1

comment:74 Changed on 01/23/23 at 06:38:37 by Sebastian Huber <sebastian.huber@…>

In 0b0dd79/rtems-docs:

eng: Use a recommendation for requirement texts

Update #3715.

comment:75 Changed on 05/19/23 at 05:21:00 by Sebastian Huber

Milestone: 7.16.1

comment:76 Changed on 05/19/23 at 05:21:26 by 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.

comment:77 Changed on 05/19/23 at 05:21:27 by 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.

comment:78 Changed on 05/19/23 at 05:21:29 by Sebastian Huber <sebastian.huber@…>

In c81a244/rtems-docs:

eng: Add conditional build dependencies

Update #3715.

comment:79 Changed on 05/19/23 at 05:21:30 by Sebastian Huber <sebastian.huber@…>

In 98172bc/rtems-docs:

eng: Use type refinement for validation method

Update #3715.

comment:80 Changed on 05/19/23 at 05:21:31 by Sebastian Huber <sebastian.huber@…>

In 77e8b56/rtems-docs:

eng: Add optional floating-point number type

Update #3715.

comment:81 Changed on 05/19/23 at 05:21:32 by 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.

comment:82 Changed on 05/19/23 at 05:21:34 by Sebastian Huber <sebastian.huber@…>

In c69046e/rtems-docs:

eng: Remove obsolete type listing

Update #3715.

comment:83 Changed on 05/19/23 at 05:21:35 by Sebastian Huber <sebastian.huber@…>

In 2a5e59d/rtems-docs:

eng: Add design target item type

Update #3715.

comment:84 Changed on 05/19/23 at 05:21:36 by Sebastian Huber <sebastian.huber@…>

In 8bc24e5/rtems-docs:

eng: Add proxy item type

Update #3715.

comment:85 Changed on 05/19/23 at 05:21:37 by Sebastian Huber <sebastian.huber@…>

In 9a5fb29/rtems-docs:

eng: Remove ambiguous interface types

Use an item proxy instead.

Update #3715.

comment:86 Changed on 05/19/23 at 05:21:39 by 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

Update #3715.

comment:87 Changed on 05/19/23 at 05:21:40 by Sebastian Huber <sebastian.huber@…>

In 2fecb7a/rtems-docs:

eng: Make design group identifiers optional

Update #3715.

comment:88 Changed on 05/19/23 at 05:21:41 by Sebastian Huber <sebastian.huber@…>

In 9c2498a/rtems-docs:

eng: Add unspecified header file item type

Update #3715.

comment:89 Changed on 05/19/23 at 05:21:43 by 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.

comment:90 Changed on 05/19/23 at 05:25:41 by Sebastian Huber

Resolution: fixed
Status: acceptedclosed

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.

Note: See TracTickets for help on using tickets.