RTEMS Software Engineering (5.3)

Copyrights and License

© 2018, 2019 embedded brains GmbH
© 2018, 2019 Sebastian Huber
© 1988, 2015 On-Line Applications Research Corporation (OAR)

This document is available under the Creative Commons Attribution-ShareAlike 4.0 International Public License.

The authors have used their best efforts in preparing this material. These efforts include the development, research, and testing of the theories and programs to determine their effectiveness. No warranty of any kind, expressed or implied, with regard to the software or the material contained in this document is provided. No liability arising out of the application or use of any product described in this document is assumed. The authors reserve the right to revise this material and to make changes from time to time in the content hereof without obligation to notify anyone of such revision or changes.

The RTEMS Project is hosted at https://www.rtems.org. Any inquiries concerning RTEMS, its related support components, or its documentation should be directed to the RTEMS Project community.

1. Preface

This manual aims to guide the development of RTEMS itself. You should read this document if you want to participate in the development of RTEMS. Users of RTEMS may find background information in this manual. Please refer to the RTEMS User Manual and RTEMS Classic API Guide if you want to know how the RTEMS development environment is set up and how you can develop applications using RTEMS.

2. RTEMS Project Mission Statement

RTEMS development done under the umbrella of the RTEMS Project aims to provide a free and open real-time operating system targeted towards deeply embedded systems which is competitive with proprietary products. The RTEMS Project encourages the support and use of standard APIs in order to promote application portability and ease porting other packages to the RTEMS environment.

The RTEMS development effort uses an open development environment in which all users collaborate to improve RTEMS. The RTEMS cross development tool suite is based upon the free GNU tools and the open source standard C library newlib. RTEMS supports many host platforms and target architectures.

2.1. Free Software Project

The free software goals of the project are:

  • RTEMS and supporting components are available under various free licenses with copyrights being held by individual authors.

  • All software which executes on the target will not place undue restrictions on embedded applications. See also Licensing Requirements.

  • Patches must be legally acceptable for inclusion into the RTEMS Project or the specific project being used.

2.2. Design and Development Goals

  • Source based development with all users building from source

  • Any suitable host should be supported

  • Open testing, tests and test results

  • Ports to new architectures and CPU models

  • Addition of Board Support Packages for available hardware

  • Improved runtime libraries

  • Faster debug cycle

  • Various other infrastructure improvements

2.3. Open Development Environment

  • Encourage cooperation and communication between developers

  • Work more closely with “consumers”

  • Code available to everyone at any time, and everyone is welcome to participate in development

  • Patches will be considered equally based on their technical merits

  • All individuals and companies are welcome to contribute as long as they accept the ground rules

  • Open mailing lists

  • Developer friendly tools and procedures with a focus on keeping them current

  • Conflicts of interest exist for many RTEMS developers. The developers contributing to the RTEMS Project must put the interests of the RTEMS Project first.

3. RTEMS Stakeholders

You are a potential RTEMS stakeholder. RTEMS is a community based free and open source project. All users are treated as stakeholders. It is hoped that as stakeholders, users will contribute to the project, sponsor core developers, and help fund the infrastructure required to host and manage the project. Please have a look at the Support and Contributing chapter of the ERROR: :r:url:`user`.

4. Introduction to Pre-Qualification

RTEMS has a long history of being used to support critical applications. In some of these application domains, there are standards (e.g., DO-178C, NPR 7150.2) which define the expectations for the processes used to develop software and the associated artifacts. These standards typically do not specify software functionality but address topics like requirements definition, traceability, having a documented change process, coding style, testing requirements, and a user’s manual. During system test, these standards call for a review - usually by an independent entity - that the standard has been adhered too. These reviews cover a broad variety of topics and activities, but the process is generally referred to as qualification, verification, or auditing against the specific standard in use. The RTEMS Project will use the term “qualification” independent of the standard.

The goal of the RTEMS Qualification Project is to make RTEMS easier to review regardless of the standard chosen. Quite specifically, the RTEMS Qualification effort will NOT produce a directly qualified product or artifacts in the format dictated by a specific organization or standard. The goal is to make RTEMS itself, documentation, testing infrastructure, etc. more closely align with the information requirements of these high integrity qualification standards. In addition to improving the items that a mature, high quality open source project will have, there are additional artifacts needed for a qualification effort that no known open source project possesses. Specifically, requirements and the associated traceability to source code, tests, and documentation are needed.

The RTEMS Qualification Project is technically “pre-qualification.” True qualification must be performed on the project’s target hardware in a system context. The FAA has provided guidance for Reusable Software Components (FAA-AC20-148) and this effort should follow that guidance. The open RTEMS Project, with the assistance of domain experts, will possess and maintain the master technical information needed in a qualification effort. Consultants will provide the services required to tailor the master information, perform testing on specific system hardware, and to guide end users in using the master technical data in the context of a particular standard.

The RTEMS Qualification Project will broadly address two areas. The first area is suggesting areas of improvement for automated project infrastructure and the master technical data that has traditionally been provided by the RTEMS Project. For example, the RTEMS Qualification could suggest specific improvements to code coverage reports. The teams focused on qualification should be able to provide resources for improving the automated project infrastructure and master technical data for RTEMS. The term “resources” is often used by open source projects to refer to volunteer code contributions or funding. Although code contributions in this area are important and always welcome, funding is also important. At a minimum, ongoing funding is needed for maintenance and upgrades of the RTEMS Project server infrastructure, addition of services to those servers, and core contributors to review submissions

The second area is the creation and maintenance of master technical data that has traditionally not been owned or maintained by the RTEMS Project. The most obvious example of this is a requirements set with proper infrastructure for tracing requirements through code to test and documentation. It is expected that these will be maintained by the RTEMS Qualification Project. They will be evaluated for adoption by the main RTEMS Project but the additional maintenance burden imposed will be a strong factor in this consideration. It behooves the RTEMS Qualification Project to limit dependence on manual checks and ensure that automation and ongoing support for that automation is contributed to the RTEMS Project.

It is expected that the RTEMS Qualification Project will create and maintain maps from the RTEMS master technical data to the various qualification standards. It will maintain “scorecards” which identify how the RTEMS Project is currently doing when reviewed per each standard. These will be maintained in the open as community resources which will guide the community in improving its infrastructure.

4.1. Stakeholder Involvement

Qualification of RTEMS is a specialized activity and only specific users of RTEMS will complete a formal qualification activity. The RTEMS Project cannot self-fund this entire activity and requires stakeholder to invest in an ongoing basis to ensure that any investment they make is maintained and viable in an ongoing basis. The RTEMS core developers view steady support of the qualification effort as necessary to continue to lower the overall costs of qualifying RTEMS.

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. Therefore all UIDs used to link one specification item to another should use relative UIDs. This ensures that the RTEMS requirements can be referenced easily in larger systems though a system-specific prefix. 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.

The absolute UID of a specification item (for example a requirement) is defined by a leading / and the path of directories from the specification base directory to the file of the item separated by / characters and the file name without the .yml extension. For example, a specification item contained in the file build/cpukit/librtemscpu.yml inside a spec directory has the absolute UID of /build/cpukit/librtemscpu.

The relative UID to a specification item is defined by the path of directories from the file containing the source specification item to the file of the destination item separated by / characters and the file name of the destination item without the .yml extension. For example the relative UID from /build/bsps/sparc/leon3/grp to /build/bsps/bspopts is ../../bspopts.

Basically, the valid characters of an UID are determined by the file system storing the item files. By convention, UID characters shall be restricted to the following set defined by the regular expression [a-zA-Z0-9_-]+. Use - as a separator inside an UID part.

In documents the URL-like prefix spec: shall be used to indicated specification item UIDs.

The UID scheme for RTEMS requirements shall be component based. For example, the UID spec:/classic/task/create-err-invaddr may specify that the rtems_task_create() directive shall return a status of RTEMS_INVALID_ADDRESS if the id parameter is NULL.

A initial requirement item hierarchy could be this:

  • build (building RTEMS BSPs and libraries)

  • acfg (application configuration groups)

    • opt (application configuration options)

  • classic

    • task

      • create-* (requirements for rtems_task_create())

      • delete-* (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())

      • getsched-* (requirements for rtems_task_get_scheduler())

      • ident-* (requirements for rtems_task_ident())

      • issusp-* (requirements for rtems_task_is_suspended())

      • iter-* (requirements for rtems_task_iterate())

      • mode-* (requirements for rtems_task_mode())

      • restart-* (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())

      • setsched* (requirements for rtems_task_set_scheduler())

      • start-* (requirements for rtems_task_start())

      • susp-* (requirements for rtems_task_suspend())

      • wkafter-* (requirements for rtems_task_wake_after())

      • wkwhen-* (requirements for rtems_task_wake_when())

    • sema

  • 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 specification items. For each requirement directory there should be a validation subdirectory named test, e.g. spec/classic/task/test. A test specification directory 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:

spec:/classic/task/create

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:

spec:/classic/task/create

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.

spec:/classic/task/create-err-toomany

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

spec:/classic/task/create-err-invaddr

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

spec:/classic/task/create-err-invname

If the name parameter is invalid, 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:

spec:/classic/sema/mtx-obtain-wait

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

spec:/classic/sema/mtx-obtain-err-unsat

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:

spec:/classic/sema/mtx-obtain-wait

When a mutex is not available and the RTEMS_WAIT option is set, the mutex obtain directive shall enqueue the calling thread on the wait queue of the mutex.

spec:/classic/sema/mtx-obtain-err-unsat

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. See rationale attribute for Specification Items.

5.1.9. Requirement Validation

The validation of each Requirement Item Type item shall be accomplished by one or more specification items of the types Test Case Item Type or Requirement Validation Item Type through a link from the validation item to the requirement item with the Requirement Validation Link Role.

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.

5.1.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.2. Specification Items

5.2.2. Specification Item Types

5.2.2.1. Root Item Type

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

The specification items are stored in files in YAML format with a defined set of key-value pairs called attributes. Each attribute key name shall be a Name. In particular, key names which begin with an underscore (_) are reserved for internal use in tools.

This is the root specification item type. All explicit attributes shall be specified. The explicit attributes for this type are:

SPDX-License-Identifier

The attribute value shall be a SPDX License Identifier. It shall be the license of the item.

copyrights

The attribute value shall be a list. Each list element shall be a Copyright. It shall be the list of copyright statements of the item.

enabled-by

The attribute value shall be an Enabled-By Expression. It shall define the conditions under which the item is enabled.

links

The attribute value shall be a list. Each list element shall be a Link.

type

The attribute value shall be a Name. It shall be the item type. 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. The item type may be refined further with additional type-specific subtypes.

This type is refined by the following types:

5.2.2.2. Build Item Type

This type refines the Root Item Type though the type attribute if the value is build. This set of attributes specifies a build item. All explicit attributes shall be specified. The explicit attributes for this type are:

build-type

The attribute value shall be a Name. It shall be the build item type.

This type is refined by the following types:

5.2.2.3. Build Ada Test Program Item Type

This type refines the Build Item Type though the build-type attribute if the value is ada-test-program. This set of attributes specifies an Ada test program executable to build. Test programs may use additional objects provided by Build Objects Item Type items. Test programs have an implicit enabled-by attribute value which is controlled by the option action set-test-state. If the test state is set to exclude, then the test program is not built. All explicit attributes shall be specified. The explicit attributes for this type are:

ada-main

The attribute value shall be a string. It shall be the path to the Ada main body file.

ada-object-directory

The attribute value shall be a string. It shall be the path to the Ada object directory (-D option value for gnatmake).

adaflags

The attribute value shall be a list of strings. It shall be a list of options for the Ada compiler.

adaincludes

The attribute value shall be a list of strings. It shall be a list of Ada include paths.

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

ldflags

The attribute value shall be a list. Each list element shall be a Build Linker Option.

source

The attribute value shall be a list. Each list element shall be a Build Source.

stlib

The attribute value shall be a list of strings. It shall be a list of external static library identifiers used to link this test program, e.g. m for libm.a.

target

The attribute value shall be a Build Target.

use-after

The attribute value shall be a list. Each list element shall be a Build Use After Directive.

use-before

The attribute value shall be a list. Each list element shall be a Build Use Before Directive.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
ada-main: testsuites/ada/samples/hello/hello.adb
ada-object-directory: testsuites/ada/samples/hello
adaflags: []
adaincludes:
- cpukit/include/adainclude
- testsuites/ada/support
build-type: ada-test-program
cflags: []
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
cppflags: []
enabled-by: true
includes: []
ldflags: []
links: []
source:
- testsuites/ada/samples/hello/init.c
stlib: []
target: testsuites/ada/ada_hello.exe
type: build
use-after: []
use-before: []
5.2.2.4. Build BSP Item Type

This type refines the Build Item Type though the build-type attribute if the value is bsp. This set of attributes specifies a base BSP variant to build. All explicit attributes shall be specified. The explicit attributes for this type are:

arch

The attribute value shall be a string. It shall be the target architecture of the BSP.

bsp

The attribute value shall be a string. It shall be the base BSP variant name.

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

family

The attribute value shall be a string. It shall be the BSP family name. The name shall be the last directory of the path to the BSP sources.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

install

The attribute value shall be a list. Each list element shall be a Build Install Directive.

source

The attribute value shall be a list. Each list element shall be a Build Source.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
arch: myarch
bsp: mybsp
build-type: bsp
cflags: []
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
cppflags: []
enabled-by: true
family: mybsp
includes: []
install:
- destination: ${BSP_INCLUDEDIR}
  source:
  - bsps/myarch/mybsp/include/bsp.h
  - bsps/myarch/mybsp/include/tm27.h
- destination: ${BSP_INCLUDEDIR}/bsp
  source:
  - bsps/myarch/mybsp/include/bsp/irq.h
- destination: ${BSP_LIBDIR}
  source:
  - bsps/myarch/mybsp/start/linkcmds
links:
- role: build-dependency
  uid: ../../obj
- role: build-dependency
  uid: ../../opto2
- role: build-dependency
  uid: abi
- role: build-dependency
  uid: obj
- role: build-dependency
  uid: ../start
- role: build-dependency
  uid: ../../bspopts
source:
- bsps/myarch/mybsp/start/bspstart.c
type: build
5.2.2.5. Build Configuration File Item Type

This type refines the Build Item Type though the build-type attribute if the value is config-file. This set of attributes specifies a configuration file placed in the build tree. The configuration file is generated during the configure command execution and are placed in the build tree. All explicit attributes shall be specified. The explicit attributes for this type are:

content

The attribute value shall be a string. It shall be the content of the configuration file. A ${VARIABLE} substitution is performed during the configure command execution using the variables of the configuration set. Use $$ for a plain $ character. To have all variables from sibling items available for substitution it is recommended to link them in the proper order.

install-path

The attribute value shall be a Build Install Path.

target

The attribute value shall be a Build Target.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
build-type: config-file
content: |
  # ...
  Name: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME}
  # ...
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
install-path: ${PREFIX}/lib/pkgconfig
links: []
target: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME}.pc
type: build
5.2.2.6. Build Configuration Header Item Type

This type refines the Build Item Type though the build-type attribute if the value is config-header. This set of attributes specifies configuration header file. The configuration header file is generated during configure command execution and is placed in the build tree. All collected configuration defines are written to the configuration header file during the configure command execution. To have all configuration defines from sibling items available it is recommended to link them in the proper order. All explicit attributes shall be specified. The explicit attributes for this type are:

guard

The attribute value shall be a string. It shall be the header guard define.

include-headers

The attribute value shall be a list of strings. It shall be a list of header files to include via #include <...>.

install-path

The attribute value shall be a Build Install Path.

target

The attribute value shall be a Build Target.

5.2.2.7. Build Group Item Type

This type refines the Build Item Type though the build-type attribute if the value is group. This set of attributes provides a means to aggregate other build items and modify the build item context which is used by referenced build items. The includes, ldflags, objects, and use variables of the build item context are updated by the corresponding attributes of the build group. All explicit attributes shall be specified. The explicit attributes for this type are:

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

install

The attribute value shall be a list. Each list element shall be a Build Install Directive.

ldflags

The attribute value shall be a list of strings. It shall be a list of options for the linker. They are used to link executables referenced by this item.

use-after

The attribute value shall be a list. Each list element shall be a Build Use After Directive.

use-before

The attribute value shall be a list. Each list element shall be a Build Use Before Directive.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
build-type: group
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by:
- BUILD_TESTS
- BUILD_SAMPLES
includes:
- testsuites/support/include
install: []
ldflags:
- -Wl,--wrap=printf
- -Wl,--wrap=puts
links:
- role: build-dependency
  uid: ticker
type: build
use-after: []
use-before:
- rtemstest
5.2.2.8. Build Library Item Type

This type refines the Build Item Type though the build-type attribute if the value is library. This set of attributes specifies a static library. Library items may use additional objects provided by Build Objects Item Type items through the build dependency links of the item. All explicit attributes shall be specified. The explicit attributes for this type are:

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

cxxflags

The attribute value shall be a list. Each list element shall be a Build C++ Compiler Option.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

install

The attribute value shall be a list. Each list element shall be a Build Install Directive.

install-path

The attribute value shall be a Build Install Path.

source

The attribute value shall be a list. Each list element shall be a Build Source.

target

The attribute value shall be a Build Target. It shall be the name of the static library, e.g. z for libz.a.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
build-type: library
cflags:
- -Wno-pointer-sign
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
cppflags: []
cxxflags: []
enabled-by: true
includes:
- cpukit/libfs/src/jffs2/include
install:
- destination: ${BSP_INCLUDEDIR}/rtems
  source:
  - cpukit/include/rtems/jffs2.h
install-path: ${BSP_LIBDIR}
links: []
source:
- cpukit/libfs/src/jffs2/src/build.c
target: jffs2
type: build
5.2.2.9. Build Objects Item Type

This type refines the Build Item Type though the build-type attribute if the value is objects. This set of attributes specifies a set of object files used to build static libraries or test programs. All explicit attributes shall be specified. The explicit attributes for this type are:

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

cxxflags

The attribute value shall be a list. Each list element shall be a Build C++ Compiler Option.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

install

The attribute value shall be a list. Each list element shall be a Build Install Directive.

source

The attribute value shall be a list. Each list element shall be a Build Source.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
build-type: objects
cflags: []
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
cppflags: []
cxxflags: []
enabled-by: true
includes: []
install:
- destination: ${BSP_INCLUDEDIR}/bsp
  source:
  - bsps/include/bsp/bootcard.h
  - bsps/include/bsp/default-initial-extension.h
  - bsps/include/bsp/fatal.h
links: []
source:
- bsps/shared/start/bootcard.c
- bsps/shared/rtems-version.c
type: build
5.2.2.10. Build Option Item Type

This type refines the Build Item Type though the build-type attribute if the value is option. This set of attributes specifies a build option. The following explicit attributes are mandatory:

  • actions

  • default

  • default-by-variant

  • description

The explicit attributes for this type are:

actions

The attribute value shall be a list. Each list element shall be a Build Option Action. Each action operates on the action value handed over by a previous action and action-specific attribute values. The actions pass the processed action value to the next action in the list. The first action starts with an action value of None. The actions are carried out during the configure command execution.

default

The attribute value shall be a Build Option Value. It shall be the default value of the option if no variant-specific default value is specified. Use null to specify that no default value exits. The variant-specific default values may be specified by the default-by-variant attribute.

default-by-variant

The attribute value shall be a list. Each list element shall be a Build Option Default by Variant. The list is processed from top to bottom. If a matching variant is found, then the processing stops.

description

The attribute value shall be an optional string. It shall be the description of the option.

format

The attribute value shall be an optional string. It shall be a Python format string, for example '{}' or '{:#010x}'.

name

The attribute value shall be a Build Option Name.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
actions:
- get-integer: null
- define: null
build-type: option
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
default: 115200
default-by-variant:
- value: 9600
  variants:
  - m68k/m5484FireEngine
  - powerpc/hsc_cm01
- value: 19200
  variants:
  - m68k/COBRA5475
description: |
  Default baud for console and other serial devices.
enabled-by: true
format: '{}'
links: []
name: BSP_CONSOLE_BAUD
type: build
5.2.2.11. Build Script Item Type

This type refines the Build Item Type though the build-type attribute if the value is script. This set of attributes specifies a build script. The optional attributes may be required by commands executed through the scripts. The following explicit attributes are mandatory:

  • do-build

  • do-configure

  • prepare-build

  • prepare-configure

The explicit attributes for this type are:

asflags

The attribute value shall be a list. Each list element shall be a Build Assembler Option.

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

cxxflags

The attribute value shall be a list. Each list element shall be a Build C++ Compiler Option.

do-build

The attribute value shall be an optional string. If this script shall execute, then it shall be Python code which is executed via exec() in the context of the do_build() method of the wscript. A local variable bld is available with the waf build context. A local variable bic is available with the build item context.

do-configure

The attribute value shall be an optional string. If this script shall execute, then it shall be Python code which is executed via exec() in the context of the do_configure() method of the wscript. A local variable conf is available with the waf configuration context. A local variable cic is available with the configuration item context.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

ldflags

The attribute value shall be a list. Each list element shall be a Build Linker Option.

prepare-build

The attribute value shall be an optional string. If this script shall execute, then it shall be Python code which is executed via exec() in the context of the prepare_build() method of the wscript. A local variable bld is available with the waf build context. A local variable bic is available with the build item context.

prepare-configure

The attribute value shall be an optional string. If this script shall execute, then it shall be Python code which is executed via exec() in the context of the prepare_configure() method of the wscript. A local variable conf is available with the waf configuration context. A local variable cic is available with the configuration item context.

stlib

The attribute value shall be a list of strings. It shall be a list of external static library identifiers used to link this test program, e.g. m for libm.a.

use-after

The attribute value shall be a list. Each list element shall be a Build Use After Directive.

use-before

The attribute value shall be a list. Each list element shall be a Build Use Before Directive.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
build-type: script
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
default: null
default-by-variant: []
do-build: |
  bld.install_as(
      "${BSP_LIBDIR}/linkcmds",
      "bsps/" + bld.env.ARCH + "/" + bld.env.BSP_FAMILY +
      "/start/linkcmds." + bld.env.BSP_BASE
  )
do-configure: |
  conf.env.append_value(
      "LINKFLAGS",
      ["-qnolinkcmds", "-T", "linkcmds." + conf.env.BSP_BASE]
  )
enabled-by: true
links: []
prepare-build: null
prepare-configure: null
type: build
5.2.2.12. Build Start File Item Type

This type refines the Build Item Type though the build-type attribute if the value is start-file. This set of attributes specifies a start file to build. A start file is used to link an executable. All explicit attributes shall be specified. The explicit attributes for this type are:

asflags

The attribute value shall be a list. Each list element shall be a Build Assembler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

install-path

The attribute value shall be a Build Install Path.

source

The attribute value shall be a list. Each list element shall be a Build Source.

target

The attribute value shall be a Build Target.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
asflags: []
build-type: start-file
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
cppflags: []
enabled-by: true
includes: []
install-path: ${BSP_LIBDIR}
links: []
source:
- bsps/sparc/shared/start/start.S
target: start.o
type: build
5.2.2.13. Build Test Program Item Type

This type refines the Build Item Type though the build-type attribute if the value is test-program. This set of attributes specifies a test program executable to build. Test programs may use additional objects provided by Build Objects Item Type items. Test programs have an implicit enabled-by attribute value which is controlled by the option action set-test-state. If the test state is set to exclude, then the test program is not built. All explicit attributes shall be specified. The explicit attributes for this type are:

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

cppflags

The attribute value shall be a list. Each list element shall be a Build C Preprocessor Option.

cxxflags

The attribute value shall be a list. Each list element shall be a Build C++ Compiler Option.

features

The attribute value shall be a string. It shall be the waf build features for this test program.

includes

The attribute value shall be a list. Each list element shall be a Build Include Path.

ldflags

The attribute value shall be a list. Each list element shall be a Build Linker Option.

source

The attribute value shall be a list. Each list element shall be a Build Source.

stlib

The attribute value shall be a list of strings. It shall be a list of external static library identifiers used to link this test program, e.g. m for libm.a.

target

The attribute value shall be a Build Target.

use-after

The attribute value shall be a list. Each list element shall be a Build Use After Directive.

use-before

The attribute value shall be a list. Each list element shall be a Build Use Before Directive.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
build-type: test-program
cflags: []
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
cppflags: []
cxxflags: []
enabled-by: true
features: c cprogram
includes: []
ldflags: []
links: []
source:
- testsuites/samples/ticker/init.c
- testsuites/samples/ticker/tasks.c
stlib: []
target: testsuites/samples/ticker.exe
type: build
use-after: []
use-before: []
5.2.2.14. Constraint Item Type

This type refines the Root Item Type though the type attribute if the value is constraint. This set of attributes specifies a constraint. All explicit attributes shall be specified. The explicit attributes for this type are:

rationale

The attribute value shall be an optional string. If the value is present, then it shall state the rationale or justification of the constraint.

scope

The attribute value shall be a string. It shall be the scope of the constraint.

text

The attribute value shall be a Requirement Text. It shall state the constraint.

5.2.2.15. Glossary Item Type

This type refines the Root Item Type though the type attribute if the value is glossary. This set of attributes specifies a glossary item. All explicit attributes shall be specified. The explicit attributes for this type are:

glossary-type

The attribute value shall be a Name. It shall be the glossary item type.

This type is refined by the following types:

5.2.2.16. Glossary Group Item Type

This type refines the Glossary Item Type though the glossary-type attribute if the value is group. This set of attributes specifies a glossary group. All explicit attributes shall be specified. The explicit attributes for this type are:

name

The attribute value shall be a string. It shall be the human readable name of the glossary group.

text

The attribute value shall be a string. It shall state the requirement for the glossary group.

5.2.2.17. Glossary Term Item Type

This type refines the Glossary Item Type though the glossary-type attribute if the value is term. This set of attributes specifies a glossary term. All explicit attributes shall be specified. The explicit attributes for this type are:

term

The attribute value shall be a string. It shall be the glossary term.

text

The attribute value shall be a string. It shall be the definition of the glossary term.

5.2.2.18. Interface Item Type

This type refines the Root Item Type though the type attribute if the value is interface. This set of attributes specifies an interface specification item. Interface items shall specify the interface of the software product to other software products and the hardware. Use Interface Domain Item Type items to specify interface domains, for example the API, C language, compiler, interfaces to the implementation, and the hardware. All explicit attributes shall be specified. The explicit attributes for this type are:

interface-type

The attribute value shall be a Name. It shall be the interface item type.

This type is refined by the following types:

5.2.2.19. Application Configuration Group Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is appl-config-group. This set of attributes specifies an application configuration group. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be a string. It shall be the description of the application configuration group.

name

The attribute value shall be a string. It shall be human readable name of the application configuration group.

text

The attribute value shall be a Requirement Text. It shall state the requirement for the application configuration group.

5.2.2.20. Application Configuration Option Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is appl-config-option. This set of attributes specifies an application configuration option. All explicit attributes shall be specified. The explicit attributes for this type are:

appl-config-option-type

The attribute value shall be a Name. It shall be the application configuration option type.

description

The attribute value shall be an Interface Description. The Application Configuration Value Option Item Type items have an attribute for constraints.

index-entries

The attribute value shall be a list of strings. It shall be a list of additional application configuration option document index entries. The application configuration option name is automatically added to the document index.

name

The attribute value shall be an Application Configuration Option Name.

notes

The attribute value shall be an Interface Notes.

text

The attribute value shall be a Requirement Text. It shall state the requirement for the application configuration option.

This type is refined by the following types:

5.2.2.21. Application Configuration Feature Enable Option Item Type

This type refines the Application Configuration Option Item Type though the appl-config-option-type attribute if the value is feature-enable. This set of attributes specifies an application configuration feature enable option.

5.2.2.22. Application Configuration Feature Option Item Type

This type refines the Application Configuration Option Item Type though the appl-config-option-type attribute if the value is feature. This set of attributes specifies an application configuration feature option. All explicit attributes shall be specified. The explicit attributes for this type are:

default

The attribute value shall be a string. It shall describe what happens if the configuration option is undefined.

5.2.2.23. Application Configuration Value Option Item Type

This type refines the following types:

This set of attributes specifies application configuration initializer or integer option. All explicit attributes shall be specified. The explicit attributes for this type are:

constraints

The attribute value shall be an Application Configuration Option Constraint Set.

default-value

The attribute value shall be an Integer or String. It shall shall describe the default value of the application configuration option.

5.2.2.24. Interface Compound Item Type

This type refines the following types:

This set of attributes specifies a compound (struct or union). All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be a list. Each list element shall be an Interface Compound Member Definition Directive.

definition-kind

The attribute value shall be an Interface Compound Definition Kind.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the compound (struct or union).

notes

The attribute value shall be an Interface Notes.

5.2.2.25. Interface Container Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is container. Items of this type specify an interface container. The item shall have exactly one link with the Interface Placement Link Role to an Interface Domain Item Type item. This link defines the interface domain of the container.

5.2.2.26. Interface Define Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is define. This set of attributes specifies a define. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be an Interface Definition Directive.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the define.

notes

The attribute value shall be an Interface Notes.

5.2.2.27. Interface Domain Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is domain. This set of attributes specifies an interface domain. Items of the types Interface Container Item Type and Interface Header File Item Type are placed into domains through links with the Interface Placement Link Role. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be a string. It shall be the description of the domain

name

The attribute value shall be a string. It shall be the human readable name of the domain.

5.2.2.28. Interface Enum Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is enum. This set of attributes specifies an enum. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition-kind

The attribute value shall be an Interface Enum Definition Kind.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the enum.

notes

The attribute value shall be an Interface Description.

5.2.2.29. Interface Enumerator Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is enumerator. This set of attributes specifies an enumerator. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be an Interface Definition Directive.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the enumerator.

notes

The attribute value shall be an Interface Notes.

5.2.2.30. Interface Forward Declaration Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is forward-declaration. Items of this type specify a forward declaration. The item shall have exactly one link with the Interface Target Link Role to an Interface Compound Item Type item. This link defines the type declared by the forward declaration.

5.2.2.31. Interface Function Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is function. This set of attributes specifies a function. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be an Interface Function Definition Directive.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the function.

notes

The attribute value shall be an Interface Notes.

params

The attribute value shall be a list. Each list element shall be an Interface Parameter.

return

The attribute value shall be an Interface Return Directive.

5.2.2.32. Interface Group Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is group. This set of attributes specifies an interface group. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

description

The attribute value shall be an Interface Description.

identifier

The attribute value shall be an Interface Group Identifier.

name

The attribute value shall be a string. It shall be the human readable name of the interface group.

5.2.2.33. Interface Header File Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is header-file. This set of attributes specifies a header file. The item shall have exactly one link with the Interface Placement Link Role to an Interface Domain Item Type item. This link defines the interface domain of the header file. All explicit attributes shall be specified. The explicit attributes for this type are:

path

The attribute value shall be a string. It shall be the path used to include the header file. For example rtems/confdefs.h.

prefix

The attribute value shall be a string. It shall be the prefix directory path to the header file in the interface domain. For example cpukit/include.

5.2.2.34. Interface Macro Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is macro. This set of attributes specifies a macro. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be an Interface Definition Directive.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the macro.

notes

The attribute value shall be an Interface Notes.

params

The attribute value shall be a list. Each list element shall be an Interface Parameter.

return

The attribute value shall be an Interface Return Directive.

5.2.2.35. Interface Typedef Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is typedef. This set of attributes specifies a typedef. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be an Interface Definition Directive.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the typedef.

notes

The attribute value shall be an Interface Notes.

5.2.2.36. Interface Unspecified Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is unspecified. This set of attributes specifies an unspecified interface. All explicit attributes shall be specified. The explicit attributes for this type are:

name

The attribute value shall be a string. It shall be the name of the unspecified interface.

5.2.2.37. Interface Variable Item Type

This type refines the Interface Item Type though the interface-type attribute if the value is variable. This set of attributes specifies a variable. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

definition

The attribute value shall be an Interface Definition Directive.

description

The attribute value shall be an Interface Description.

name

The attribute value shall be a string. It shall be the name of the variable.

notes

The attribute value shall be an Interface Notes.

5.2.2.38. Requirement Item Type

This type refines the Root Item Type though the type attribute if the value is requirement. This set of attributes specifies a requirement. All explicit attributes shall be specified. The explicit attributes for this type are:

rationale

The attribute value shall be an optional string. If the value is present, then it shall state the rationale or justification of the requirement.

references

The attribute value shall be a list. Each list element shall be a Requirement Reference.

requirement-type

The attribute value shall be a Name. It shall be the requirement item type.

text

The attribute value shall be a Requirement Text. It shall state the requirement.

This type is refined by the following types:

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de
enabled-by: true
functional-type: capability
links: []
rationale: |
  It keeps you busy.
requirement-type: functional
text: |
  The system shall do crazy things.
type: requirement
5.2.2.39. Functional Requirement Item Type

This type refines the Requirement Item Type though the requirement-type attribute if the value is functional. This set of attributes specifies a functional requirement. All explicit attributes shall be specified. The explicit attributes for this type are:

functional-type

The attribute value shall be a Name. It shall be the functional type of the requirement.

This type is refined by the following types:

5.2.2.40. Action Requirement Item Type

This type refines the Functional Requirement Item Type though the functional-type attribute if the value is action. This set of attributes specifies functional requirements and corresponding validation test code. The functional requirements of an action are specified. An action performs a step in a finite state machine. An action is implemented through a function or a macro. The action is performed through a call of the function or an execution of the code of a macro expansion by an actor. The actor is for example a task or an interrupt service routine.

For action requirements which specify the function of an interface, there shall be exactly one link with the Interface Function Link Role to the interface of the action.

The action requirements are specified by

  • a list of pre-conditions, each with a set of states,

  • a list of post-conditions, each with a set of states,

  • the transition of pre-condition states to post-condition states through the action.

Along with the requirements, the test code to generate a validation test is specified. For an action requirement it is verified that all variations of pre-condition states have a set of post-condition states specified in the transition map. All transitions are covered by the generated test code. All explicit attributes shall be specified. The explicit attributes for this type are:

post-conditions

The attribute value shall be a list. Each list element shall be an Action Requirement Condition.

pre-conditions

The attribute value shall be a list. Each list element shall be an Action Requirement Condition.

test-action

The attribute value shall be a string. It shall be the test action code.

test-brief

The attribute value shall be an optional string. If the value is present, then it shall be the test case brief description.

test-context

The attribute value shall be a list. Each list element shall be an Action Requirement Test Context Member.

test-description

The attribute value shall be an optional string. If the value is present, then it shall be the test case description.

test-header

The attribute value shall be an Action Requirement Test Header.

test-includes

The attribute value shall be a list of strings. It shall be a list of header files included via #include <...>.

test-local-includes

The attribute value shall be a list of strings. It shall be a list of header files included via #include "...".

test-name

The attribute value shall be a Test Name.

test-setup

The attribute value shall be an Action Requirement Test Fixture Method.

test-stop

The attribute value shall be an Action Requirement Test Fixture Method.

test-support

The attribute value shall be an optional string. If the value is present, then it shall be the test case support code. The support code is placed at file scope before the test case code.

test-target

The attribute value shall be a string. It shall be the path to the generated test case source file.

test-teardown

The attribute value shall be an Action Requirement Test Fixture Method.

transition-map

The attribute value shall be a list. Each list element shall be an Action Requirement Transition.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
functional-type: action
links: []
post-conditions:
- name: Status
  states:
  - name: Success
    test-code: |
      /* Check that the status is SUCCESS */
    text: |
      The status shall be SUCCESS.
  - name: Error
    test-code: |
      /* Check that the status is ERROR */
    text: |
      The status shall be ERROR.
  test-epilogue: null
  test-prologue: null
- name: Data
  states:
  - name: Unchanged
    test-code: |
      /* Check that the data is unchanged */
    text: |
      The data shall be unchanged by the action.
  - name: Red
    test-code: |
      /* Check that the data is red */
    text: |
      The data shall be red.
  - name: Green
    test-code: |
      /* Check that the data is green */
    text: |
      The data shall be green.
  test-epilogue: null
  test-prologue: null
pre-conditions:
- name: Data
  states:
  - name: NullPtr
    test-code: |
      /* Set data pointer to NULL */
    text: |
      The data pointer shall be NULL.
  - name: Valid
    test-code: |
      /* Set data pointer to reference a valid data buffer */
    text: |
      The data pointer shall reference a valid data buffer.
  test-epilogue: null
  test-prologue: null
- name: Option
  states:
  - name: Red
    test-code: |
      /* Set option to RED */
    text: |
      The option shall be RED.
  - name: Green
    test-code: |
      /* Set option to GREEN */
    text: |
      The option shall be GREEN.
  test-epilogue: null
  test-prologue: null
requirement-type: functional
test-action: |
  /* Call the function of the action */
test-brief: null
test-context:
- brief: null
  description: null
  member: void *data
- brief: null
  description: null
  member: option_type option
test-description: null
test-header: null
test-includes: []
test-local-includes: []
test-name: RedGreenData
test-setup: null
test-stop: null
test-support: null
test-target: tc-red-green-data.c
test-teardown: null
transition-map:
- enabled-by: true
  post-conditions:
    Status: Error
    Data: Unchanged
  pre-conditions:
    Data: NullPtr
    Option: all
- enabled-by: true
  post-conditions:
    Status: Success
    Data: Red
  pre-conditions:
    Data: Valid
    Option: Red
- enabled-by: true
  post-conditions:
    Status: Success
    Data: Green
  pre-conditions:
    Data: Valid
    Option: Green
rationale: null
references: []
text: |
  ${.:/text-template}
type: requirement
5.2.2.41. Generic Functional Requirement Item Type

This type refines the following types:

Items of this type state a functional requirement with the functional type defined by the specification type refinement.

5.2.2.42. Non-Functional Requirement Item Type

This type refines the Requirement Item Type though the requirement-type attribute if the value is non-functional. This set of attributes specifies a non-functional requirement. All explicit attributes shall be specified. The explicit attributes for this type are:

non-functional-type

The attribute value shall be a Requirement Non-Functional Type. It shall be the non-functional type of the requirement.

5.2.2.43. Requirement Validation Item Type

This type refines the Root Item Type though the type attribute if the value is validation. This set of attributes provides a requirement validation evidence. The item shall have exactly one link to the validated requirement with the Requirement Validation Link Role. All explicit attributes shall be specified. The explicit attributes for this type are:

method

The attribute value shall be a Requirement Validation Method. Validation by test is done through Test Case Item Type items.

text

The attribute value shall be a string. It shall provide the validation evidence depending on the validation method:

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

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

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

5.2.2.44. Specification Item Type

This type refines the Root Item Type though the type attribute if the value is spec. This set of attributes specifies specification types. All explicit attributes shall be specified. The explicit attributes for this type are:

spec-description

The attribute value shall be an optional string. It shall be the description of the specification type.

spec-example

The attribute value shall be an optional string. If the value is present, then it shall be an example of the specification type.

spec-info

The attribute value shall be a Specification Information.

spec-name

The attribute value shall be an optional string. It shall be the human readable name of the specification type.

spec-type

The attribute value shall be a Name. It shall the specification type.

Please have a look at the following example:

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
links:
- role: spec-member
  uid: root
- role: spec-refinement
  spec-key: type
  spec-value: example
  uid: root
spec-description: null
spec-example: null
spec-info:
  dict:
    attributes:
      an-example-attribute:
        description: |
          It shall be an example.
        spec-type: optional-str
      example-number:
        description: |
          It shall be the example number.
        spec-type: int
    description: |
      This set of attributes specifies an example.
    mandatory-attributes: all
spec-name: Example Item Type
spec-type: spec
type: spec
5.2.2.45. Test Case Item Type

This type refines the Root Item Type though the type attribute if the value is test-case. This set of attributes specifies a test case. All explicit attributes shall be specified. The explicit attributes for this type are:

actions

The attribute value shall be a list. Each list element shall be a Test Case Action.

brief

The attribute value shall be a string. It shall be the test case brief description.

description

The attribute value shall be an optional string. It shall be the test case description.

epilogue

The attribute value shall be an optional string. If the value is present, then it shall be the test case epilogue code. The epilogue code is placed in the test case body after the test case actions.

fixture

The attribute value shall be an optional string. If the value is present, then it shall be a pointer to the test case fixture. The test case fixture pointer declaration may be provided by the test case support code or via an included header file.

includes

The attribute value shall be a list of strings. It shall be a list of header files included via #include <...>.

local-includes

The attribute value shall be a list of strings. It shall be a list of header files included via #include "...".

name

The attribute value shall be a Test Name.

prologue

The attribute value shall be an optional string. If the value is present, then it shall be the test case prologue code. The prologue code is placed in the test case body before the test case actions. A use case is the declaration of local variables used by the test case actions.

support

The attribute value shall be an optional string. If the value is present, then it shall be the test case support code. The support code is placed at file scope before the test case code.

target

The attribute value shall be a string. It shall be the path to the generated target test case source file.

5.2.2.46. Test Platform Item Type

This type refines the Root Item Type though the type attribute if the value is test-platform. Please note:

Warning

This item type is work in progress.

This set of attributes specifies a test platform. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be a string. It shall be the description of the test platform.

name

The attribute value shall be a string. It shall be the human readable name of the test platform.

5.2.2.47. Test Procedure Item Type

This type refines the Root Item Type though the type attribute if the value is test-procedure. Please note:

Warning

This item type is work in progress.

This set of attributes specifies a test procedure. All explicit attributes shall be specified. The explicit attributes for this type are:

name

The attribute value shall be a string. It shall be the human readable name of the test procedure.

purpose

The attribute value shall be a string. It shall state the purpose of the test procedure.

steps

The attribute value shall be a string. It shall describe the steps of the test procedure execution.

5.2.2.48. Test Suite Item Type

This type refines the Root Item Type though the type attribute if the value is test-suite. This set of attributes specifies a test suite. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be a string. It shall be the test suite brief description.

code

The attribute value shall be a string. It shall be the test suite code. The test suite code is placed at file scope in the target source file.

description

The attribute value shall be an optional string. It shall be the test suite description.

includes

The attribute value shall be a list of strings. It shall be a list of header files included via #include <...>.

local-includes

The attribute value shall be a list of strings. It shall be a list of header files included via #include "...".

name

The attribute value shall be a Test Name.

target

The attribute value shall be a string. It shall be the path to the generated target test suite source file.

5.2.3. Specification Attribute Sets and Value Types

5.2.3.1. Action Requirement Condition

This set of attributes defines an action pre-condition or post-condition. All explicit attributes shall be specified. The explicit attributes for this type are:

name

The attribute value shall be an Action Requirement Name.

states

The attribute value shall be a list. Each list element shall be an Action Requirement State.

test-epilogue

The attribute value shall be an optional string. If the value is present, then it shall be the test epilogue code. The epilogue code is placed in the test condition preparation or check before the state-specific code. The code may use a local variable ctx which points to the test context, see Action Requirement Test Context Member.

test-prologue

The attribute value shall be an optional string. If the value is present, then it shall be the test prologue code. The prologue code is placed in the test condition preparation or check after the state-specific code. The code may use a local variable ctx which points to the test context, see Action Requirement Test Context Member.

This type is used by the following types:

5.2.3.2. Action Requirement Name

The value shall be a string. It shall be the name of a condition or a state of a condition used to define pre-conditions and post-conditions of an action requirement. It shall be formatted in CamelCase. It should be brief and abbreviated. The rationale for this is that the names are used in tables and the horizontal space is limited by the page width. The more conditions you have in an action requirement, the shorter the names should be. The value shall match with the regular expression “^[A-Z][a-zA-Z0-9]+$".

This type is used by the following types:

5.2.3.3. Action Requirement State

This set of attributes defines an action pre-condition or post-condition state. All explicit attributes shall be specified. The explicit attributes for this type are:

name

The attribute value shall be an Action Requirement Name.

test-code

The attribute value shall be a string. It shall be the test code to prepare or check the state of the condition. The code may use a local variable ctx which points to the test context, see Action Requirement Test Context Member.

text

The attribute value shall be a Requirement Text. It shall define the state of the condition.

This type is used by the following types:

5.2.3.4. Action Requirement Test Context Member

A value of this type shall be of one of the following variants:

  • The value may be a set of attributes. This set of attributes defines an action requirement test context member. All explicit attributes shall be specified. The explicit attributes for this type are:

    brief

    The attribute value shall be an optional string. It shall be the test context member brief description.

    description

    The attribute value shall be an optional string. It shall be the test context member description.

    member

    The attribute value shall be a string. It shall be the test context member definition. It shall be a valid C structure member definition without a trailing ;.

  • There may by be no value (null).

This type is used by the following types:

5.2.3.5. Action Requirement Test Fixture Method

A value of this type shall be of one of the following variants:

  • The value may be a set of attributes. This set of attributes defines an action requirement test fixture method. All explicit attributes shall be specified. The explicit attributes for this type are:

    brief

    The attribute value shall be an optional string. It shall be the test fixture method brief description.

    code

    The attribute value shall be a string. It shall be the test fixture method code. The code may use a local variable ctx which points to the test context, see Action Requirement Test Context Member.

    description

    The attribute value shall be an optional string. It shall be the test fixture method description.

  • There may by be no value (null).

This type is used by the following types:

5.2.3.6. Action Requirement Test Header

A value of this type shall be of one of the following variants:

  • The value may be a set of attributes. This set of attributes specifies an action requirement test header. In case a test header is specified, then instead of a test case a test run function will be generated. The test run function will be declared in the test header target file and defined in the test source target file. The test run function can be used to compose test cases. The test header file is not automatically included in the test source file. It should be added to the includes or local includes of the test. All explicit attributes shall be specified. The explicit attributes for this type are:

    code

    The attribute value shall be an optional string. If the value is present, then it shall be the test case header code. The header code is placed at file scope after the test enum declarations and before the test run function declaration.

    includes

    The attribute value shall be a list of strings. It shall be a list of header files included by the header file via #include <...>.

    local-includes

    The attribute value shall be a list of strings. It shall be a list of header files included by the header file via #include "...".

    run-params

    The attribute value shall be a list. Each list element shall be an Action Requirement Test Run Parameter.

    target

    The attribute value shall be a string. It shall be the path to the generated test header file.

  • There may by be no value (null).

This type is used by the following types:

5.2.3.7. Action Requirement Test Run Parameter

This set of attributes specifies a parameter for the test run function. The parameter is also added as a member to the test context, see Action Requirement Test Context Member. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be a string. It shall be the description of the parameter.

dir

The attribute value shall be an Interface Parameter Direction.

name

The attribute value shall be a string. It shall be the parameter name.

specifier

The attribute value shall be a string. It shall be the complete function parameter specifier. Use ${.:name} for the parameter name, for example "int ${.:name}".

This type is used by the following types:

5.2.3.8. Action Requirement Transition

This set of attributes defines the transition from multiple sets of states of pre-conditions to a set of states of post-conditions through an action in an action requirement. The ability to specify multiple sets of states of pre-conditions which result in a common set of post-conditions may allow a more compact specification of the transition map. For example, let us suppose you want to specify the action of a function with a pointer parameter. The function performs an early check that the pointer is NULL and in this case returns an error code. The pointer condition dominates the action outcome if the pointer is NULL. Other pre-condition states can be simply set to all for this transition. All explicit attributes shall be specified. The explicit attributes for this type are:

enabled-by

The attribute value shall be an Enabled-By Expression. The transition map may be customized to support configuration variants through this attribute. The default transitions (enabled-by: true) shall be specified before the customized variants in the list.

post-conditions

The attribute value shall be an Action Requirement Transition Post-Conditions.

pre-conditions

The attribute value shall be an Action Requirement Transition Pre-Conditions.

This type is used by the following types:

5.2.3.9. Action Requirement Transition Post-Conditions

This set of attributes defines for each post-condition the state after the action for a transition in an action requirement. Generic attributes may be specified. Each generic attribute key shall be an Action Requirement Name. Each generic attribute value shall be an Action Requirement Name. There shall be exactly one generic attribute key for each post-condition. The key name shall be the post-condition name. The value of each generic attribute shall be the state of the post-condition.

This type is used by the following types:

5.2.3.10. Action Requirement Transition Pre-Condition State Set

A value of this type shall be of one of the following variants:

  • The value may be a list. Each list element shall be an Action Requirement Name. The list defines the set of states of the pre-condition in the transition.

  • The value may be a string. The value represents all states of the pre-condition in the transition. The value shall be equal to “all”.

This type is used by the following types:

5.2.3.11. Action Requirement Transition Pre-Conditions

This set of attributes defines for each pre-condition the set of states before the action for a transition in an actin requirement. Generic attributes may be specified. Each generic attribute key shall be an Action Requirement Name. Each generic attribute value shall be an Action Requirement Transition Pre-Condition State Set. There shall be exactly one generic attribute key for each pre-condition. The key name shall be the pre-condition name. The value of each generic attribute shall be a set of states of the pre-condition.

This type is used by the following types:

5.2.3.13. Application Configuration Option Constraint Set

This set of attributes defines application configuration option constraints. Additional constraints can be added through the links of the item using the Constraint Link Role. None of the explicit attributes is mandatory, they are all are optional. The explicit attributes for this type are:

max

The attribute value shall be an Integer or String. It shall be the maximum value of the application configuration option.

min

The attribute value shall be an Integer or String. It shall be the minimum value of the application configuration option.

set

The attribute value shall be a list. Each list element shall be an Integer or String. It shall be the set of valid values for the application configuration option.

texts

The attribute value shall be a list. Each list element shall be a Requirement Text. It shall be a list of constraints specific to this application configuration option. For general constraints, use a link with the Constraint Link Role to a constraint item.

This type is used by the following types:

5.2.3.14. Application Configuration Option Name

The value shall be a string. It shall be the name of an application configuration option. The value shall match with the regular expression “^(CONFIGURE_|BSP_)[A-Z0-9_]+$".

This type is used by the following types:

5.2.3.15. Boolean or Integer or String

A value of this type shall be of one of the following variants:

  • The value may be a boolean.

  • The value may be an integer number.

  • The value may be a string.

This type is used by the following types:

5.2.3.16. Build Assembler Option

The value shall be a string. It shall be an option for the assembler. The options are used to assemble the sources of this item. The options defined by this attribute succeed the options presented to the item by the build item context.

This type is used by the following types:

5.2.3.17. Build C Compiler Option

The value shall be a string. It shall be an option for the C compiler. The options are used to compile the sources of this item. The options defined by this attribute succeed the options presented to the item by the build item context.

This type is used by the following types:

5.2.3.18. Build C Preprocessor Option

The value shall be a string. It shall be an option for the C preprocessor. The options are used to preprocess the sources of this item. The options defined by this attribute succeed the options presented to the item by the build item context.

This type is used by the following types:

5.2.3.19. Build C++ Compiler Option

The value shall be a string. It shall be an option for the C++ compiler. The options are used to compile the sources of this item. The options defined by this attribute succeed the options presented to the item by the build item context.

This type is used by the following types:

5.2.3.21. Build Include Path

The value shall be a string. It shall be a path to header files. The path is used by the C preprocessor to search for header files. It succeeds the includes presented to the item by the build item context. For an Build Group Item Type item the includes are visible to all items referenced by the group item. For Build BSP Item Type, Build Objects Item Type, Build Library Item Type, Build Start File Item Type, and Build Test Program Item Type items the includes are only visible to the sources specified by the item itself and they do not propagate to referenced items.

This type is used by the following types:

5.2.3.22. Build Install Directive

This set of attributes specifies files installed by a build item. All explicit attributes shall be specified. The explicit attributes for this type are:

destination

The attribute value shall be a string. It shall be the install destination directory.

source

The attribute value shall be a list of strings. It shall be the list of source files to be installed in the destination directory. The path to a source file shall be relative to the directory of the wscript.

This type is used by the following types:

5.2.3.23. Build Install Path

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string. It shall be the installation path of a Build Target.

This type is used by the following types:

5.2.3.24. Build Linker Option

The value shall be a string. It shall be an option for the linker. The options are used to link executables. The options defined by this attribute succeed the options presented to the item by the build item context.

This type is used by the following types:

5.2.3.25. Build Option Action

This set of attributes specifies a build option action. Exactly one of the explicit attributes shall be specified. The explicit attributes for this type are:

append-test-cppflags

The attribute value shall be a string. It shall be the name of a test program. The action appends the action value to the CPPFLAGS of the test program. The name shall correspond to the name of a Build Test Program Item Type item. Due to the processing order of items, there is no way to check if the name specified by the attribute value is valid.

assert-aligned

The attribute value shall be an integer number. The action asserts that the action value is aligned according to the attribute value.

assert-eq

The attribute value shall be a Boolean or Integer or String. The action asserts that the action value is equal to the attribute value.

assert-ge

The attribute value shall be an Integer or String. The action asserts that the action value is greater than or equal to the attribute value.

assert-gt

The attribute value shall be an Integer or String. The action asserts that the action value is greater than the attribute value.

assert-int16

The attribute shall have no value. The action asserts that the action value is a valid signed 16-bit integer.

assert-int32

The attribute shall have no value. The action asserts that the action value is a valid signed 32-bit integer.

assert-int64

The attribute shall have no value. The action asserts that the action value is a valid signed 64-bit integer.

assert-int8

The attribute shall have no value. The action asserts that the action value is a valid signed 8-bit integer.

assert-le

The attribute value shall be an Integer or String. The action asserts that the action value is less than or equal to the attribute value.

assert-lt

The attribute value shall be an Integer or String. The action asserts that the action value is less than the attribute value.

assert-ne

The attribute value shall be a Boolean or Integer or String. The action asserts that the action value is not equal to the attribute value.

assert-power-of-two

The attribute shall have no value. The action asserts that the action value is a power of two.

assert-uint16

The attribute shall have no value. The action asserts that the action value is a valid unsigned 16-bit integer.

assert-uint32

The attribute shall have no value. The action asserts that the action value is a valid unsigned 32-bit integer.

assert-uint64

The attribute shall have no value. The action asserts that the action value is a valid unsigned 64-bit integer.

assert-uint8

The attribute shall have no value. The action asserts that the action value is a valid unsigned 8-bit integer.

check-cc

The attribute value shall be a Build Option C Compiler Check Action.

check-cxx

The attribute value shall be a Build Option C++ Compiler Check Action.

define

The attribute value shall be an optional string. The action adds a define to the configuration set. If the attribute value is present, then it is used as the name of the define, otherwise the name of the item is used. The value of the define is the action value. If the action value is a string, then it is quoted.

define-condition

The attribute value shall be an optional string. The action adds a conditional define to the configuration set. If the attribute value is present, then it is used as the name of the define, otherwise the name of the item is used. The value of the define is the action value.

define-unquoted

The attribute value shall be an optional string. The action adds a define to the configuration set. If the attribute value is present, then it is used as the name of the define, otherwise the name of the item is used. The value of the define is the action value. If the action value is a string, then it is not quoted.

env-append

The attribute value shall be an optional string. The action appends the action value to an environment of the configuration set. If the attribute value is present, then it is used as the name of the environment variable, otherwise the name of the item is used.

env-assign

The attribute value shall be an optional string. The action assigns the action value to an environment of the configuration set. If the attribute value is present, then it is used as the name of the environment variable, otherwise the name of the item is used.

env-enable

The attribute value shall be an optional string. If the action value is true, then a name is appended to the ENABLE environment variable of the configuration set. If the attribute value is present, then it is used as the name, otherwise the name of the item is used.

find-program

The attribute shall have no value. The action tries to find the program specified by the action value. Uses the ${PATH} to find the program. Returns the result of the find operation, e.g. a path to the program.

find-tool

The attribute shall have no value. The action tries to find the tool specified by the action value. Uses the tool paths specified by the --rtems-tools command line option. Returns the result of the find operation, e.g. a path to the program.

format-and-define

The attribute value shall be an optional string. The action adds a define to the configuration set. If the attribute value is present, then it is used as the name of the define, otherwise the name of the item is used. The value of the define is the action value. The value is formatted according to the format attribute value.

get-boolean

The attribute shall have no value. The action gets the action value for subsequent actions from a configuration file variable named by the items name attribute. If no such variable exists in the configuration file, then the default value is used. The value is converted to a boolean.

get-env

The attribute value shall be a string. The action gets the action value for subsequent actions from the environment variable of the configuration set named by the attribute value.

get-integer

The attribute shall have no value. The action gets the action value for subsequent actions from a configuration file variable named by the items name attribute. If no such variable exists in the configuration file, then the default value is used. The value is converted to an integer.

get-string

The attribute shall have no value. The action gets the action value for subsequent actions from a configuration file variable named by the items name attribute. If no such variable exists in the configuration file, then the default value is used. The value is converted to a string.

script

The attribute value shall be a string. The action executes the attribute value with the Python eval() function in the context of the script action handler.

set-test-state

The attribute value shall be a Build Option Set Test State Action.

set-value

The attribute value shall be a Build Option Value. The action sets the action value for subsequent actions to the attribute value.

split

The attribute shall have no value. The action splits the action value.

substitute

The attribute shall have no value. The action Performs a ${VARIABLE} substitution on the action value. Use $$ for a plain $ character.

This type is used by the following types:

5.2.3.26. Build Option C Compiler Check Action

This set of attributes specifies a check done using the C compiler. All explicit attributes shall be specified. The explicit attributes for this type are:

cflags

The attribute value shall be a list. Each list element shall be a Build C Compiler Option.

fragment

The attribute value shall be a string. It shall be a code fragment used to check the availability of a certain feature through compilation with the C compiler. The resulting object is not linked to an executable.

message

The attribute value shall be a string. It shall be a description of the feature to check.

This type is used by the following types:

5.2.3.27. Build Option C++ Compiler Check Action

This set of attributes specifies a check done using the C++ compiler. All explicit attributes shall be specified. The explicit attributes for this type are:

cxxflags

The attribute value shall be a list. Each list element shall be a Build C++ Compiler Option.

fragment

The attribute value shall be a string. It shall be a code fragment used to check the availability of a certain feature through compilation with the C++ compiler. The resulting object is not linked to an executable.

message

The attribute value shall be a string. It shall be a description of the feature to check.

This type is used by the following types:

5.2.3.28. Build Option Default by Variant

This set of attributes specifies build option default values by variant. All explicit attributes shall be specified. The explicit attributes for this type are:

value

The attribute value shall be a Build Option Value. It value shall be the default value for the matching variants.

variants

The attribute value shall be a list of strings. It shall be a list of Python regular expression matching with the desired variants.

This type is used by the following types:

5.2.3.29. Build Option Name

The value shall be a string. It shall be the name of the build option. The value shall match with the regular expression “^[a-zA-Z_][a-zA-Z0-9_]*$".

This type is used by the following types:

5.2.3.30. Build Option Set Test State Action

This set of attributes specifies test states for a set of test programs. Generic attributes may be specified. Each generic attribute key shall be a Name. Each generic attribute value shall be a Build Test State. The keys shall be test program names. The names shall correspond to the name of a Build Test Program Item Type or Build Ada Test Program Item Type item. Due to the processing order of items, there is no way to check if the name specified by the attribute key is valid.

This type is used by the following types:

5.2.3.31. Build Option Value

A value of this type shall be of one of the following variants:

  • The value may be a boolean.

  • The value may be an integer number.

  • The value may be a list. Each list element shall be a string.

  • There may by be no value (null).

  • The value may be a string.

This type is used by the following types:

5.2.3.32. Build Source

The value shall be a string. It shall be a source file. The path to a source file shall be relative to the directory of the wscript.

This type is used by the following types:

5.2.3.33. Build Target

The value shall be a string. It shall be the target file path. The path to the target file shall be relative to the directory of the wscript. The target file is located in the build tree.

This type is used by the following types:

5.2.3.34. Build Test State

The value shall be a string. This string defines a test state. The value shall be an element of

  • benchmark”,

  • exclude”,

  • expected-fail”,

  • indeterminate”, and

  • user-input”.

This type is used by the following types:

5.2.3.35. Build Use After Directive

The value shall be a string. It shall be an internal static library identifier. They are used to link programs referenced by this item, e.g. z for libz.a. They are placed after the use items of the build item context.

This type is used by the following types:

5.2.3.36. Build Use Before Directive

The value shall be a string. It shall be an internal static library identifier. They are used to link programs referenced by this item, e.g. z for libz.a. They are placed before the use items of the build item context.

This type is used by the following types:

5.2.3.39. Enabled-By Expression

A value of this type shall be an expression which defines under which conditions the specification item or parts of it are enabled. The expression is evaluated with the use of an enabled set. This is a set of strings which indicate enabled features.

A value of this type shall be of one of the following variants:

  • The value may be a boolean. This expression evaluates directly to the boolean value.

  • The value may be a set of attributes. Each attribute defines an operator. Exactly one of the explicit attributes shall be specified. The explicit attributes for this type are:

    and

    The attribute value shall be a list. Each list element shall be an Enabled-By Expression. The and operator evaluates to the logical and of the evaluation results of the expressions in the list.

    not

    The attribute value shall be an Enabled-By Expression. The not operator evaluates to the logical not of the evaluation results of the expression.

    or

    The attribute value shall be a list. Each list element shall be an Enabled-By Expression. The or operator evaluates to the logical or of the evaluation results of the expressions in the list.

  • The value may be a list. Each list element shall be an Enabled-By Expression. This list of expressions evaluates to the logical or of the evaluation results of the expressions in the list.

  • The value may be a string. If the value is in the enabled set, this expression evaluates to true, otherwise to false.

This type is used by the following types:

Please have a look at the following example:

enabled-by:
  and:
  - RTEMS_NETWORKING
  - not: RTEMS_SMP
5.2.3.41. Integer or String

A value of this type shall be of one of the following variants:

  • The value may be an integer number.

  • The value may be a string.

This type is used by the following types:

5.2.3.42. Interface Brief Description

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string. It shall be the brief description of the interface.

This type is used by the following types:

5.2.3.43. Interface Compound Definition Kind

The value shall be a string. It specifies how the interface compound is defined. It may be a typedef only, the struct or union only, or a typedef with a struct or union definition. The value shall be an element of

  • struct-only”,

  • typedef-and-struct”,

  • typedef-and-union”,

  • typedef-only”, and

  • union-only”.

This type is used by the following types:

5.2.3.44. Interface Compound Member Compound

This type refines the following types:

This set of attributes specifies an interface compound member compound. All explicit attributes shall be specified. The explicit attributes for this type are:

definition

The attribute value shall be a list. Each list element shall be an Interface Compound Member Definition Directive.

5.2.3.45. Interface Compound Member Declaration

This type refines the Interface Compound Member Definition though the kind attribute if the value is member. This set of attributes specifies an interface compound member declaration. All explicit attributes shall be specified. The explicit attributes for this type are:

definition

The attribute value shall be a string. It shall be the interface compound member declaration. On the declaration a context-sensitive substitution of item variables is performed.

5.2.3.46. Interface Compound Member Definition

This set of attributes specifies an interface compound member definition. All explicit attributes shall be specified. The explicit attributes for this type are:

brief

The attribute value shall be an Interface Brief Description.

description

The attribute value shall be an Interface Description.

kind

The attribute value shall be a string. It shall be the interface compound member kind.

name

The attribute value shall be a string. It shall be the interface compound member name.

This type is refined by the following types:

This type is used by the following types:

5.2.3.47. Interface Compound Member Definition Directive

This set of attributes specifies an interface compound member definition directive. All explicit attributes shall be specified. The explicit attributes for this type are:

default

The attribute value shall be an Interface Compound Member Definition. The default definition will be used if no variant-specific definition is enabled.

variants

The attribute value shall be a list. Each list element shall be an Interface Compound Member Definition Variant.

This type is used by the following types:

5.2.3.48. Interface Compound Member Definition Variant

This set of attributes specifies an interface compound member definition variant. All explicit attributes shall be specified. The explicit attributes for this type are:

definition

The attribute value shall be an Interface Compound Member Definition. The definition will be used if the expression defined by the enabled-by attribute evaluates to true. In generated header files, the expression is evaluated by the C preprocessor.

enabled-by

The attribute value shall be an Interface Enabled-By Expression.

This type is used by the following types:

5.2.3.49. Interface Definition

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string. It shall be the definition. On the definition a context-sensitive substitution of item variables is performed.

This type is used by the following types:

5.2.3.50. Interface Definition Directive

This set of attributes specifies an interface definition directive. All explicit attributes shall be specified. The explicit attributes for this type are:

default

The attribute value shall be an Interface Definition. The default definition will be used if no variant-specific definition is enabled.

variants

The attribute value shall be a list. Each list element shall be an Interface Definition Variant.

This type is used by the following types:

5.2.3.51. Interface Definition Variant

This set of attributes specifies an interface definition variant. All explicit attributes shall be specified. The explicit attributes for this type are:

definition

The attribute value shall be an Interface Definition. The definition will be used if the expression defined by the enabled-by attribute evaluates to true. In generated header files, the expression is evaluated by the C preprocessor.

enabled-by

The attribute value shall be an Interface Enabled-By Expression.

This type is used by the following types:

5.2.3.52. Interface Description

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string. It shall be the description of the interface. The description should be short and concentrate on the average case. All special cases, usage notes, constraints, error conditions, configuration dependencies, references, etc. should be described in the Interface Notes.

This type is used by the following types:

5.2.3.53. Interface Enabled-By Expression

A value of this type shall be an expression which defines under which conditions an interface definition is enabled. In generated header files, the expression is evaluated by the C preprocessor.

A value of this type shall be of one of the following variants:

  • The value may be a boolean. It is converted to 0 or 1. It defines a symbol in the expression.

  • The value may be a set of attributes. Each attribute defines an operator. Exactly one of the explicit attributes shall be specified. The explicit attributes for this type are:

    and

    The attribute value shall be a list. Each list element shall be an Interface Enabled-By Expression. The and operator defines a logical and of the expressions in the list.

    not

    The attribute value shall be an Interface Enabled-By Expression. The not operator defines a logical not of the expression.

    or

    The attribute value shall be a list. Each list element shall be an Interface Enabled-By Expression. The or operator defines a logical or of the expressions in the list.

  • The value may be a list. Each list element shall be an Interface Enabled-By Expression. It defines a logical or of the expressions in the list.

  • The value may be a string. It defines a symbol in the expression.

This type is used by the following types:

5.2.3.54. Interface Enum Definition Kind

The value shall be a string. It specifies how the enum is defined. It may be a typedef only, the enum only, or a typedef with an enum definition. The value shall be an element of

  • enum-only”,

  • typedef-and-enum”, and

  • typedef-only”.

This type is used by the following types:

5.2.3.56. Interface Function Definition

This set of attributes specifies a function definition. All explicit attributes shall be specified. The explicit attributes for this type are:

body

The attribute value shall be an optional string. If the value is present, then it shall be the definition of a static inline function. On the function definition a context-sensitive substitution of item variables is performed. If no value is present, then the function is declared as an external function.

params

The attribute value shall be a list of strings. It shall be the list of parameter declarations of the function. On the function parameter declarations a context-sensitive substitution of item variables is performed.

return

The attribute value shall be a string. It shall be the function return type. On the return type a context-sensitive substitution of item variables is performed.

This type is used by the following types:

5.2.3.57. Interface Function Definition Directive

This set of attributes specifies a function definition directive. All explicit attributes shall be specified. The explicit attributes for this type are:

default

The attribute value shall be an Interface Function Definition. The default definition will be used if no variant-specific definition is enabled.

variants

The attribute value shall be a list. Each list element shall be an Interface Function Definition Variant.

This type is used by the following types:

5.2.3.58. Interface Function Definition Variant

This set of attributes specifies a function definition variant. All explicit attributes shall be specified. The explicit attributes for this type are:

definition

The attribute value shall be an Interface Function Definition. The definition will be used if the expression defined by the enabled-by attribute evaluates to true. In generated header files, the expression is evaluated by the C preprocessor.

enabled-by

The attribute value shall be an Interface Enabled-By Expression.

This type is used by the following types:

5.2.3.60. Interface Group Identifier

The value shall be a string. It shall be the identifier of the interface group. The value shall match with the regular expression “^[A-Z][a-zA-Z0-9]*$".

This type is used by the following types:

5.2.3.63. Interface Notes

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string. It shall be the notes for the interface.

This type is used by the following types:

5.2.3.64. Interface Parameter

This set of attributes specifies an interface parameter. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be an Interface Description.

dir

The attribute value shall be an Interface Parameter Direction.

name

The attribute value shall be a string. It shall be the interface parameter name.

This type is used by the following types:

5.2.3.65. Interface Parameter Direction

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string. It specifies the interface parameter direction. The value shall be an element of

    • in”,

    • out”, and

    • inout”.

This type is used by the following types:

5.2.3.67. Interface Return Directive

This set of attributes specifies an interface return. All explicit attributes shall be specified. The explicit attributes for this type are:

return

The attribute value shall be an optional string. It shall describe the interface return for unspecified return values.

return-values

The attribute value shall be a list. Each list element shall be an Interface Return Value.

This type is used by the following types:

5.2.3.68. Interface Return Value

This set of attributes specifies an interface return value. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be an Interface Description.

value

The attribute value shall be a Boolean or Integer or String. It shall be the described interface return value.

This type is used by the following types:

5.2.3.72. Optional String

A value of this type shall be of one of the following variants:

  • There may by be no value (null).

  • The value may be a string.

5.2.3.73. Requirement Non-Functional Type

The value shall be a string. This type shall be used for non-functional requirement types. The value shall be an element of

  • build-configuration”,

  • constraint”,

  • design”,

  • documentation”,

  • interface”,

  • interface-requirement”,

  • maintainability”,

  • performance”,

  • portability”,

  • quality”,

  • reliability”,

  • resource”, and

  • safety”.

This type is used by the following types:

5.2.3.74. Requirement Reference

This set of attributes specifies a requirement reference. All explicit attributes shall be specified. The explicit attributes for this type are:

identifier

The attribute value shall be a string. It shall be the type-specific identifier of the reference target. For group references use the Doxygen group identifier.

type

The attribute value shall be a Requirement Reference Type.

This type is used by the following types:

5.2.3.75. Requirement Reference Type

The value shall be a string. It specifies the type of a requirement reference. The value shall be an element of

  • define”,

  • file”,

  • function”,

  • group”,

  • macro”, and

  • variable”.

This type is used by the following types:

5.2.3.77. Requirement Text

The value shall be a string. It shall state a requirement or constraint. The value shall not contain an element of

  • 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”, and

  • when necessary”.

This type is used by the following types:

5.2.3.79. Requirement Validation Method

The value shall be a string. This value type characterizes a requirement validation method (except validation by test). The value shall be an element of

  • by-analysis”,

  • by-inspection”, and

  • by-review-of-design”.

This type is used by the following types:

5.2.3.80. SPDX License Identifier

The value shall be a string. It defines the license of the item expressed though an SPDX License Identifier. The value

  • shall be equal to “CC-BY-SA-4.0 OR BSD-2-Clause”,

  • or, shall be equal to “BSD-2-Clause”,

  • or, shall be equal to “CC-BY-SA-4.0”.

This type is used by the following types:

5.2.3.81. Specification Attribute Set

This set of attributes specifies a set of attributes. The following explicit attributes are mandatory:

  • attributes

  • description

  • mandatory-attributes

The explicit attributes for this type are:

attributes

The attribute value shall be a Specification Explicit Attributes. It shall specify the explicit attributes of the attribute set.

description

The attribute value shall be an optional string. It shall be the description of the attribute set.

generic-attributes

The attribute value shall be a Specification Generic Attributes. It shall specify the generic attributes of the attribute set.

mandatory-attributes

The attribute value shall be a Specification Mandatory Attributes. It shall specify the mandatory attributes of the attribute set.

This type is used by the following types:

5.2.3.82. Specification Attribute Value

This set of attributes specifies an attribute value. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be an optional string. It shall be the description of the attribute value.

spec-type

The attribute value shall be a Name. It shall be the specification type of the attribute value.

This type is used by the following types:

5.2.3.83. Specification Boolean Value

This attribute set specifies a boolean value. Only the description attribute is mandatory. The explicit attributes for this type are:

assert

The attribute value shall be a boolean. This optional attribute defines the value constraint of the specified boolean value. If the value of the assert attribute is true, then the value of the specified boolean value shall be true. If the value of the assert attribute is false, then the value of the specified boolean value shall be false. In case the assert attribute is not present, then the value of the specified boolean value may be true or false.

description

The attribute value shall be an optional string. It shall be the description of the specified boolean value.

This type is used by the following types:

5.2.3.84. Specification Explicit Attributes

Generic attributes may be specified. Each generic attribute key shall be a Name. Each generic attribute value shall be a Specification Attribute Value. Each generic attribute specifies an explicit attribute of the attribute set. The key of the each generic attribute defines the attribute key of the explicit attribute.

This type is used by the following types:

5.2.3.85. Specification Floating-Point Assert

A value of this type shall be an expression which asserts that the floating-point value of the specified attribute satisfies the required constraints.

A value of this type shall be of one of the following variants:

  • The value may be a set of attributes. Each attribute defines an operator. Exactly one of the explicit attributes shall be specified. The explicit attributes for this type are:

    and

    The attribute value shall be a list. Each list element shall be a Specification Floating-Point Assert. The and operator evaluates to the logical and of the evaluation results of the expressions in the list.

    eq

    The attribute value shall be a floating-point number. The eq operator evaluates to true, if the value to check is equal to the value of this attribute, otherwise to false.

    ge

    The attribute value shall be a floating-point number. The ge operator evaluates to true, if the value to check is greater than or equal to the value of this attribute, otherwise to false.

    gt

    The attribute value shall be a floating-point number. The gt operator evaluates to true, if the value to check is greater than the value of this attribute, otherwise to false.

    le

    The attribute value shall be a floating-point number. The le operator evaluates to true, if the value to check is less than or equal to the value of this attribute, otherwise to false.

    lt

    The attribute value shall be a floating-point number. The lt operator evaluates to true, if the value to check is less than the value of this attribute, otherwise to false.

    ne

    The attribute value shall be a floating-point number. The ne operator evaluates to true, if the value to check is not equal to the value of this attribute, otherwise to false.

    not

    The attribute value shall be a Specification Floating-Point Assert. The not operator evaluates to the logical not of the evaluation results of the expression.

    or

    The attribute value shall be a list. Each list element shall be a Specification Floating-Point Assert. The or operator evaluates to the logical or of the evaluation results of the expressions in the list.

  • The value may be a list. Each list element shall be a Specification Floating-Point Assert. This list of expressions evaluates to the logical or of the evaluation results of the expressions in the list.

This type is used by the following types:

5.2.3.86. Specification Floating-Point Value

This set of attributes specifies a floating-point value. Only the description attribute is mandatory. The explicit attributes for this type are:

assert

The attribute value shall be a Specification Floating-Point Assert. This optional attribute defines the value constraints of the specified floating-point value. In case the assert attribute is not present, then the value of the specified floating-point value may be every valid floating-point number.

description

The attribute value shall be an optional string. It shall be the description of the specified floating-point value.

This type is used by the following types:

5.2.3.87. Specification Generic Attributes

This set of attributes specifies generic attributes. Generic attributes are attributes which are not explicitly specified by Specification Explicit Attributes. They are restricted to uniform attribute key and value types. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be an optional string. It shall be the description of the generic attributes.

key-spec-type

The attribute value shall be a Name. It shall be the specification type of the generic attribute keys.

value-spec-type

The attribute value shall be a Name. It shall be the specification type of the generic attribute values.

This type is used by the following types:

5.2.3.88. Specification Information

This set of attributes specifies attribute values. At least one of the explicit attributes shall be specified. The explicit attributes for this type are:

bool

The attribute value shall be a Specification Boolean Value. It shall specify a boolean value.

dict

The attribute value shall be a Specification Attribute Set. It shall specify a set of attributes.

float

The attribute value shall be a Specification Floating-Point Value. It shall specify a floating-point value.

int

The attribute value shall be a Specification Integer Value. It shall specify an integer value.

list

The attribute value shall be a Specification List. It shall specify a list of attributes or values.

none

The attribute shall have no value. It specifies that no value is required.

str

The attribute value shall be a Specification String Value. It shall specify a string.

This type is used by the following types:

5.2.3.89. Specification Integer Assert

A value of this type shall be an expression which asserts that the integer value of the specified attribute satisfies the required constraints.

A value of this type shall be of one of the following variants:

  • The value may be a set of attributes. Each attribute defines an operator. Exactly one of the explicit attributes shall be specified. The explicit attributes for this type are:

    and

    The attribute value shall be a list. Each list element shall be a Specification Integer Assert. The and operator evaluates to the logical and of the evaluation results of the expressions in the list.

    eq

    The attribute value shall be an integer number. The eq operator evaluates to true, if the value to check is equal to the value of this attribute, otherwise to false.

    ge

    The attribute value shall be an integer number. The ge operator evaluates to true, if the value to check is greater than or equal to the value of this attribute, otherwise to false.

    gt

    The attribute value shall be an integer number. The gt operator evaluates to true, if the value to check is greater than the value of this attribute, otherwise to false.

    le

    The attribute value shall be an integer number. The le operator evaluates to true, if the value to check is less than or equal to the value of this attribute, otherwise to false.

    lt

    The attribute value shall be an integer number. The lt operator evaluates to true, if the value to check is less than the value of this attribute, otherwise to false.

    ne

    The attribute value shall be an integer number. The ne operator evaluates to true, if the value to check is not equal to the value of this attribute, otherwise to false.

    not

    The attribute value shall be a Specification Integer Assert. The not operator evaluates to the logical not of the evaluation results of the expression.

    or

    The attribute value shall be a list. Each list element shall be a Specification Integer Assert. The or operator evaluates to the logical or of the evaluation results of the expressions in the list.

  • The value may be a list. Each list element shall be a Specification Integer Assert. This list of expressions evaluates to the logical or of the evaluation results of the expressions in the list.

This type is used by the following types:

5.2.3.90. Specification Integer Value

This set of attributes specifies an integer value. Only the description attribute is mandatory. The explicit attributes for this type are:

assert

The attribute value shall be a Specification Integer Assert. This optional attribute defines the value constraints of the specified integer value. In case the assert attribute is not present, then the value of the specified integer value may be every valid integer number.

description

The attribute value shall be an optional string. It shall be the description of the specified integer value.

This type is used by the following types:

5.2.3.91. Specification List

This set of attributes specifies a list of attributes or values. All explicit attributes shall be specified. The explicit attributes for this type are:

description

The attribute value shall be an optional string. It shall be the description of the list.

spec-type

The attribute value shall be a Name. It shall be the specification type of elements of the list.

This type is used by the following types:

5.2.3.92. Specification Mandatory Attributes

It defines which explicit attributes are mandatory.

A value of this type shall be of one of the following variants:

  • The value may be a list. Each list element shall be a Name. The list defines the mandatory attributes through their key names.

  • The value may be a string. It defines how many explicit attributes are mandatory. If none is used, then none of the explicit attributes is mandatory, they are all optional. The value shall be an element of

    • all”,

    • at-least-one”,

    • at-most-one”,

    • exactly-one”, and

    • none”.

This type is used by the following types:

5.2.3.95. Specification String Assert

A value of this type shall be an expression which asserts that the string of the specified attribute satisfies the required constraints.

A value of this type shall be of one of the following variants:

  • The value may be a set of attributes. Each attribute defines an operator. Exactly one of the explicit attributes shall be specified. The explicit attributes for this type are:

    and

    The attribute value shall be a list. Each list element shall be a Specification String Assert. The and operator evaluates to the logical and of the evaluation results of the expressions in the list.

    contains

    The attribute value shall be a list of strings. The contains operator evaluates to true, if the string to check converted to lower case with all white space characters converted to a single space character contains a string of the list of strings of this attribute, otherwise to false.

    eq

    The attribute value shall be a string. The eq operator evaluates to true, if the string to check is equal to the value of this attribute, otherwise to false.

    ge

    The attribute value shall be a string. The ge operator evaluates to true, if the string to check is greater than or equal to the value of this attribute, otherwise to false.

    gt

    The attribute value shall be a string. The gt operator evaluates to true, if the string to check is greater than the value of this attribute, otherwise to false.

    in

    The attribute value shall be a list of strings. The in operator evaluates to true, if the string to check is contained in the list of strings of this attribute, otherwise to false.

    le

    The attribute value shall be a string. The le operator evaluates to true, if the string to check is less than or equal to the value of this attribute, otherwise to false.

    lt

    The attribute value shall be a string. The lt operator evaluates to true, if the string to check is less than the value of this attribute, otherwise to false.

    ne

    The attribute value shall be a string. The ne operator evaluates to true, if the string to check is not equal to the value of this attribute, otherwise to false.

    not

    The attribute value shall be a Specification String Assert. The not operator evaluates to the logical not of the evaluation results of the expression.

    or

    The attribute value shall be a list. Each list element shall be a Specification String Assert. The or operator evaluates to the logical or of the evaluation results of the expressions in the list.

    re

    The attribute value shall be a string. The re operator evaluates to true, if the string to check matches with the regular expression of this attribute, otherwise to false.

    uid

    The attribute shall have no value. The uid operator evaluates to true, if the string is a valid UID, otherwise to false.

  • The value may be a list. Each list element shall be a Specification String Assert. This list of expressions evaluates to the logical or of the evaluation results of the expressions in the list.

This type is used by the following types:

5.2.3.96. Specification String Value

This set of attributes specifies a string. Only the description attribute is mandatory. The explicit attributes for this type are:

assert

The attribute value shall be a Specification String Assert. This optional attribute defines the constraints of the specified string. In case the assert attribute is not present, then the specified string may be every valid string.

description

The attribute value shall be an optional string. It shall be the description of the specified string attribute.

This type is used by the following types:

5.2.3.97. Test Case Action

This set of attributes specifies a test case action. All explicit attributes shall be specified. The explicit attributes for this type are:

action

The attribute value shall be a string. It shall be the test case action code.

checks

The attribute value shall be a list. Each list element shall be a Test Case Check.

description

The attribute value shall be an optional string. It shall be the test case action description.

links

The attribute value shall be a list. Each list element shall be a Link.

This type is used by the following types:

5.2.3.98. Test Case Check

This set of attributes specifies a test case check. All explicit attributes shall be specified. The explicit attributes for this type are:

check

The attribute value shall be a string. It shall be the test case check code.

description

The attribute value shall be an optional string. It shall be the test case check description.

links

The attribute value shall be a list. Each list element shall be a Link.

This type is used by the following types:

5.2.3.99. Test Name

The value shall be a string. It shall be the name of a test suite or test case. It shall be formatted in the style of a caption. If shall form a valid C designator after removal of all white space characters. The value shall match with the regular expression “^[A-Z][a-zA-Z0-9 _]+$".

This type is used by the following types:

5.2.3.100. UID

The value shall be a string. The string shall be a valid absolute or relative item UID.

This type is used by the following types:

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 [ECS09]. 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. A custom tool needs to verify this.

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. A custom tool needs to verify this. 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 custom YAML files, see Specification Items. 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 Management

5.4.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.4.2. Add a Requirement

_images/req-add.png

5.4.3. Modify a Requirement

_images/req-modify.png

5.4.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.5. Tooling

5.5.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.5.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.5.3. Best Available 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 could be extended to manage specifications in general. The primary reason for a close consideration of Doorstop as the requirements management tool for the RTEMS Project was its data format which allows a high degree of customization. Doorstop uses a directed, acyclic graph (DAG) 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 which in the end turned out to be not enough to use Doorstop for the RTEMS Project.

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 would help 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.).

After some initial work with Doorstop some issues surfaced (#471). It turned out that Doorstop is not designed as a library and contains too much policy. This results in a lack of flexibility required for the RTEMS Project.

  1. Its primary use case is requirements management. So, it has some standard attributes useful in this domain, like derived, header, level, normative, ref, reviewed, and text. However, we want to use it more generally for specification items and these attributes make not always sense. Having them in every item is just overhead and may cause confusion.

  2. The links cannot have custom attributes, e.g. role, enabled-by. With link-specific attributes you could have multiple DAGs formed up by the same set of items.

  3. Inside a document (directory) items are supposed to have a common type (set of attributes). We would like to store at a hierarchy level also distinct specializations.

  4. The verification of the items is quite limited. We need verification with type-based rules.

  5. The UIDs in combination with the document hierarchy lead to duplication, e.g. a/b/c/a-b-c-d.yml. You have the path (a/b/c) also in the file name (a-b-c). You cannot have relative UIDs in links (e.g. ../parent-req) . The specification items may contain multiple requirements, e.g. min/max attributes. There is no way to identify them.

  6. The links are ordered by Doorstop alphabetically by UID. For some applications, it would be better to use the order specified by the user. For example, we want to use specification items for a new build system. Here it is handy if you can express things like this: A is composed of B and C. Build B before C.

5.5.4. Custom Requirements Management Tool

No requirements management tool was available that fits the need of the RTEMS Qualification Project. The decision was to develop a custom requirements management tool written in Python 3.6 or later. The design for it is heavily inspired by Doorstop.

5.6. How-To

5.6.1. Getting Started

The RTEMS specification items and qualification tools are work in progress and not fully integrated in the RTEMS Project. The first step to work with the RTEMS specification and the corresponding tools is a clone of the following repository:

git clone git://git.rtems.org/sebh/rtems-qual.git
git submodule init
git submodule update

The tools need a virtual Python 3 environment. To set it up use:

cd rtems-qual
make env

Each time you want to use one of the tools, you have to activate the environment in your shell:

cd rtems-qual
. env/bin/activate

5.6.2. Glossary Specification

The glossary of terms for the RTEMS Project is defined by Glossary Term Item Type items in the spec/glossary directory. For a new glossary term add a glossary item to this directory. As the file name use the term in lower case with all white space and special characters removed or replaced by alphanumeric characters, for example spec/glossary/magicpower.yml for the term magic power.

Use ${uid:/attribute} substitutions to reference other parts of the specification.

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
glossary-type: term
links:
- role: glossary-member
  uid: ../glossary-general
term: magic power
text: |
  Magic power enables a caller to create magic objects using a
  ${magicwand:/term}.
type: glossary

Define acronyms with the phrase This term is an acronym for *. in the text attribute:

...
term: MP
...
text: |
  This term is an acronym for Magic Power.
...

Once you are done with the glossary items, run the script spec2doc.py to generate the derived documentation content. Send patches for the generated documentation and the specification to the Developers Mailing List and follow the normal patch review process.

5.6.3. Interface Specification

5.6.3.1. Specify an API Header File

The RTEMS API header files are specified under spec:/if/rtems/*. Create a subdirectory with a corresponding name for the API, for example in spec/if/rtems/foo for the foo API. In this new subdirectory place an Interface Header File Item Type item named header.yml (spec/if/rtems/foo/header.yml) and populate it with the required attributes.

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
interface-type: header-file
links:
- role: interface-placement
  uid: /if/domains/api
path: rtems/rtems/foo.h
prefix: cpukit/include
type: interface
5.6.3.2. Specify an API Element

Figure out the corresponding header file item. If it does not exist, see Specify an API Header File. Place a specialization of an Interface Item Type item into the directory of the header file item, for example spec/if/rtems/foo/bar.yml for the bar() function. Add the required attributes for the new interface item. Do not hard code interface names which are used to define the new interface. Use ${uid-of-interface-item:/name} instead. If the referenced interface is specified in the same directory, then use a relative UID. Using interface references creates implicit dependencies and helps the header file generator to resolve the interface dependencies and header file includes for you. Use Interface Unspecified Item Type items for interface dependencies to other domains such as the C language, the compiler, the implementation, or user-provided defines. To avoid cyclic dependencies between types you may use an Interface Forward Declaration Item Type item.

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: Tries to create a magic object and returns it.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
  default:
    body: null
    params:
    - ${magic-wand:/name} ${.:/params[0]/name}
    return: ${magic-type:/name} *
  variants: []
description: |
  The magic object is created out of nothing with the help of a magic wand.
enabled-by: true
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: /groups/api/classic/foo
name: bar
notes: null
params:
- description: is the magic wand.
  dir: null
  name: magic_wand
return:
  return: Otherwise, the magic object is returned.
  return-values:
  - description: The caller did not have enough magic power.
    value: ${/if/c/null}
type: interface

6. Software Development Management

6.1. Software Development (Git Users)

6.1.1. Browse the Git Repository Online

You can browse all available repositories online by accessing https://git.rtems.org/.

6.1.2. Using the Git Repository

The following examples demonstrate how to use the RTEMS’ Git repos. These examples are provided for the main rtems module, but they are also valid for the other modules.

First, we need to obtain our own local copy of the RTEMS Git repository:

git clone git://git.rtems.org/rtems.git rtems

This command will create a folder named rtems in the current directory. This folder will contain a full-featured RTEMS’ Git repository and the current HEAD revision checked out. Since all the history is available we can check out any release of RTEMS. Major RTEMS releases are available as separate branches in the repo.

To see all available remote branches issue the following command:

git branch -r

We can check out one of those remote branches (e.g. rtems-4.10 branch) using the command:

git checkout -b rtems410 origin/4.10

This will create a local branch named “rtems410”, containing the rtems-4.10 release, that will track the remote branch “rtems-4-10-branch” in origin (git://git.rtems.org/rtems.git). The git branch command prints a list of the current local branches, indicating the one currently checked out.

If you want to switch between local branches:

git checkout <branch-name>

With time your local repository will diverge from the main RTEMS repository. To keep your local copy up to date you need to issue:

git pull origin

This command will update all your local branches with any new code revisions available on the central repository.

6.1.3. Making Changes

Git allows you to make changes in the RTEMS source tree and track those changes locally. We recommend you make all your changes in local branches. If you are working on a few different changes or a progression of changes it is best to use a local branch for each change.

A branch for each change lets your repo’s master branch track the upstream RTEMS’ master branch without interacting with any of the changes you are working on. A completed change is emailed to the developer’s list for review and this can take time. While this is happening the upstream’s master branch may be updated and you may need to rebase your work and test again if you are required to change or update your patch. A local branch isolates a specific change from others and helps you manage the process.

First, you need to clone the repository:

git clone git://git.rtems.org/rtems.git rtems

Or if you already cloned it before, then you might want to update to the latest version before making your changes:

cd rtems
git pull

Create a local branch to make your changes in, in this example, the change is faster-context-switch:

git checkout -b faster-context-switch

Next, make your changes to files. If you add, delete ormove/rename files you need to inform Git

git add /some/new/file
git rm /some/old/file
git mv /some/old/file /some/new/file

When you’re satisfied with the changes you made, commit them (locally)

git commit -a

The -a flag commits all the changes that were made, but you can also control which changes to commit by individually adding files as you modify them by using. You can also specify other options to commit, such as a message with the -m flag.

git add /some/changed/files
git commit

Create a patch from your branch, in this case, we have two commits we want to send for review:

 git format-patch -2

There are new changes pushed to the RTEMS' master branch and our local branch
needs to be updated:
git checkout master
git pull
git checkout faster-context-switch
git rebase master

6.1.4. Working with Branches

Branches facilitate trying out new code and creating patches.

The previous releases of RTEMS are available through remote branches. To check out a remote branch, first query the Git repository for the list of branches:

git branch -r

Then check out the desired remote branch, for example:

git checkout -b rtems410 origin/4.10

Or if you have previously checked out the remote branch then you should see it in your local branches:

git branch

You can change to an existing local branch easily:

git checkout rtems410

You can also create a new branch and switch to it:

git branch temporary
git checkout temporary

Or more concisely:

git checkout -b temporary

If you forget which branch you are on

git branch

shows you by placing a * next to the current one.

When a branch is no longer useful you can delete it.

git checkout master
git branch -d temporary

If you have unmerged changes in the old branch Git complains and you need to use -D instead of -d.

6.1.5. Viewing Changes

To view all changes since the last commit:

git diff HEAD

To view all changes between the current branch and another branch, say master:

git diff master..HEAD

To view descriptions of committed changes:

git log

Or view the changeset for some file (or directory):

git log /some/file

To view the changesets made between two branches:

git log master..HEAD

Or for a more brief description use shortlog:

git shortlog master..HEAD

6.1.6. Reverting Changes

To remove all (uncommitted) changes on a branch

git checkout -f

Or to selectively revert (uncommited) files, for example if you accidentally deleted ./some/file

git checkout -- ./some/file

or

git checkout HEAD ./some/file

To remove commits there are two useful options, reset and revert. git reset should only be used on local branches that no one else is accessing remotely. git revert is cleaner and is the right way to revert changes that have already been pushed/pulled remotely.

6.1.7. git reset

git reset is a powerful and tricky command that should only be used on local (un-pushed) branches): A good description of what it enables to do can be found here. The following are a few useful examples. Note that adding a ~ after HEAD refers to the most recent commit, and you can add a number after the ~ to refer to commits even further back; HEAD by itself refers to the current working directory (changes since the last commit).

git reset HEAD~

Will undo the last commit and unstage those changes. Your working directory will remain the same, therefore a git status will yield any changes you made plus the changes made in your last commit. This can be used to fix the last commit. You will need to add the files again.

git reset --soft HEAD~

Will just undo the last commit. The changes from the last commit will still be staged (just as if you finished git adding them). This can be used to amend the last commit (e.g. You forgot to add a file to the last commit).

git reset --hard HEAD~

Will revert everything, including the working directory, to the previous commit. This is dangerous and can lead to you losing all your changes; the --hard flag ignores errors.

git reset HEAD

Will unstage any change. This is used to revert a wrong git add. (e.g. You added a file that shouldn’t be there, but you haven’t ‘committed’)

Will revert your working directory to a HEAD state. You will lose any change you made to files after the last commit. This is used when you just want to destroy all changes you made since the last commit.

6.1.8. git revert

git revert does the same as reset but creates a new commit with the reverted changes instead of modifying the local repository directly.

git revert HEAD

This will create a new commit which undoes the change in HEAD. You will be given a chance to edit the commit message for the new commit.

6.1.9. Merging Changes

Suppose you commit changes in two different branches, branch1 and branch2, and want to create a new branch containing both sets of changes:

git checkout -b merged
git merge branch1
git merge branch2

Or you might want to bring the changes in one branch into the other:

git checkout branch1
git merge branch2

And now that branch2 is merged you might get rid of it:

git branch -d branch2

If you have done work on a branch, say branch1, and have gone out-of-sync with the remote repository, you can pull the changes from the remote repo and then merge them into your branch:

git checkout master
git pull
git checkout branch1
git merge master

If all goes well the new commits you pulled into your master branch will be merged into your branch1, which will now be up-to-date. However, if branch1 has not been pushed remotely then rebasing might be a good alternative to merging because the merge generates a commit.

6.1.10. Rebasing

An alternative to the merge command is rebase, which replays the changes (commits) on one branch onto another. git rebase finds the common ancestor of the two branches, stores each commit of the branch you are on to temporary files and applies each commit in order.

For example

git checkout branch1
git rebase master

or more concisely

git rebase master branch1

will bring the changes of master into branch1, and then you can fast-forward master to include branch1 quite easily

git checkout master
git merge branch1

Rebasing makes a cleaner history than merging; the log of a rebased branch looks like a linear history as if the work was done serially rather than in parallel. A primary reason to rebase is to ensure commits apply cleanly on a remote branch, e.g. when submitting patches to RTEMS that you create by working on a branch in a personal repository. Using rebase to merge your work with the remote branch eliminates most integration work for the committer/maintainer.

There is one caveat to using rebase: Do not rebase commits that you have pushed to a public repository. Rebase abandons existing commits and creates new ones that are similar but different. If you push commits that others pull down, and then you rewrite those commits with git rebase and push them up again, the others will have to re-merge their work and trying to integrate their work into yours can become messy.

6.1.11. Accessing a Developer’s Repository

RTEMS developers with Git commit access have personal repositories on https://git.rtems.org/ that can be cloned to view cutting-edge development work shared there.

6.1.12. Commit Message Guidance

The commit message associated with a change to any software project is of critical importance. It is the explanation of the change and the rationale for it. Future users looing back through the project history will rely on it. Even the author of the change will likely rely on it once they have forgotten the details of the change. It is important to make the message useful. Here are some guidelines followed by the RTEMS Project to help improve the quality of our commit messages.

  • When committing a change the first line is a summary. Please make it short while hinting at the nature of the change. You can discuses the change if you wish in a ticket that has a PR number which can be referenced in the commit message. After the first line, leave an empty line and add whatever required details you feel are needed.

  • Patches should be as single purpose as possible. This is reflected in the first line summary message. If you find yourself writing something like “Fixed X and Y”, “Updated A and B”, or similar, then evaluate whether the patch should really be a patch series rather than a single larger patch.

  • Format the commit message so it is readable and clear. If you have specific points related to the change make them with separate paragraphs and if you wish you can optionally uses a - marker with suitable indents and alignment to aid readability.

  • Limit the line length to less than 80 characters

  • Please use a real name with a valid email address. Please do not use pseudonyms or provide anonymous contributions.

  • Please do not use terms such as “Fix bug”, “With this change it works”, or “Bump hash”. If you fix a bug please state the nature of the bug and why this change fixes it. If a change makes something work then detail the reason. You do not need to explain the change line by line as the commits diff and associated ticket will.

  • If you change the formatting of source code in a repository please make that a separate patch and use “Formatting changes only” on the first line. Please indicate the reason or process. For example to “Conforming to code standing”, “Reverting to upstream format”, “Result of automatic formatting”.

  • Similarly, if addressing a spelling, grammar, or Doxygen issue, please put that in a commit by itself separate from technical changes.

An example commit message:

test/change: Test message on formatting of commits

- Shows a simple single first line

- Has an empty second line

- Shows the specifics of adding separate points in the commit message as
  separate paragraphs. It also shows a `-` separator and multilines
  that are less than the 80 character width

- Show a ticket update and close

Updates #9876
Closes #8765

The first line generally starts with a file or directory name which indicates the area in RTEMS to which the commit applies. For a patch series which impacts multiple BSPs, it is common to put each BSP into a separate patch. This improves the quality and specificity of the commit messages.

6.1.13. Creating a Patch

Before submitting a patch, please read Commit Message Guidance to become familiar with the commit message formatting we require.

The recommended way to create a patch is to branch the Git repository master and use one commit for each logical change. Then you can use git format-patch to turn your commits into patches and easily submit them.

git format-patch master

Creates a separate patch for each commit that has been made between the master branch and the current branch and writes them in the current directory. Use the -o flag to redirect the files to a different directory.

If you are re-submitting a patch that has previously been reviewed, you should specify a version number for your patch, for example, use

git format-patch -v2 ...

to indicate the second version of a patch, -v3 for a third, and so forth.

Patches created using git format-patch are formatted so they can be emailed and rely on having Git configured with your name and email address, for example

git config --global user.name "Your Name"
git config --global user.email name@domain.com

Please use a real name, we do not allow pseudonyms or anonymous contributions.

6.1.14. Submitting a Patch

Using git send-email you can easily contribute your patches. You will need to install git send-email first:

sudo yum install git-email

or

sudo dnf install git-email

or

sudo apt install git-email

Then you will need to configure an SMTP server. You could install one on your localhost, or you can connect to a mail server such as Gmail.

6.1.15. Configuring git send-email to use Gmail

Configure Git to use Gmail:

git config --global sendemail.smtpserver smtp.gmail.com
git config --global sendemail.smtpserverport 587
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpuser your_email@gmail.com

It will ask for your password each time you use git send-email. Optionally you can also put it in your git config:

git config --global sendemail.smtppass your_password

6.1.16. Sending Email

To send your patches just

git send-email /path/to/patch --to devel@rtems.org

To send multiple related patches (if you have more than one commit in your branch) specify a path to a directory containing all of the patches created by git format-patch. git send-email has some useful options such as:

  • --annotate to show/edit your patch

  • --cover-letter to prepend a summary

  • --cc=<address> to cc someone

You can configure the to address:

git config --global sendemail.to devel@rtems.org

So all you need is:

git send-email /path/to/patch

6.1.17. Troubleshooting

Some restrictive corporate firewalls block access through the Git protocol (git://). If you are unable to reach the server git://git.rtems.org/ you can try accessing through http. To clone the rtems repository using the http protocol use the following command:

git clone http://git.rtems.org/rtems/ rtems

This access through http is slower (way slower!) than through the git protocol, therefore, the Git protocol is preferred.

6.1.18. Manage Your Code

You may prefer to keep your application and development work in a Git repository for all the good reasons that come with version control. For public repositories, you may like to try GitHub or BitBucket. RTEMS maintains mirrors on GitHub which can make synchronizing with upstream changes relatively simple. If you need to keep your work private, you can use one of those services with private repositories or manage your own server. The details of setting up a server are outside the scope of this document, but if you have a server with SSH access you should be able to find instructions on how to set up Git access. Once you have git configured on the server, adding repositories is a snap.

6.1.19. Private Servers

In the following, replace @USER@ with your username on your server, @REPO@ with the name of your repository, and @SERVER@ with your server’s name or address.

To push a mirror to your private server, first create a bare repository on your server.

cd /home/@USER@
mkdir git
mkdir git/@REPO@.git
cd git/@REPO@.git
git --bare init

Now from your client machine (e.g. your work laptop/desktop), push a git, perhaps one you cloned from elsewhere, or one that you made locally with git init, by adding a remote and pushing:

git remote add @SERVER@ ssh://@SERVER@/home/@USER@/git/@REPO@.git
git push @SERVER@ master

You can replace the @SERVER@ with another name for your remote if you like. And now you can push other branches that you might have created. Now you can push and pull between your client and your server. Use SSH keys to authenticate with your server if you want to save on password typing; remember to put a passphrase on your SSH key if there is a risk the private key file might get compromised.

The following is an example scenario that might be useful for RTEMS users that uses a slightly different approach than the one just outlined:

ssh @SERVER@
mkdir git
git clone --mirror git://git.rtems.org/rtems.git
## Add your ssh key to ~/.ssh/authorized_keys
exit
git clone ssh://@SERVER@/home/@USER@/git/rtems.git
cd rtems
git remote add upstream git://git.rtems.org/rtems.git
git fetch upstream
git pull upstream master
git push
## If you want to track RTEMS on your personal master branch,
## you should only push changes to origin/master that you pull
## from upstream. The basic workflow should look something like:
git checkout master
git pull upstream master
git push
git checkout -b anewbranch
## Repeat: do work, git commit -a
git push origin anewbranch

## delete a remote branch
git push origin :anewbranch
## delete a local branch
git branch -d anewbranch

6.1.20. Learn more about Git

Links to the sites with good Git information:

6.2. Software Development (Git Writers)

6.2.1. SSH Access

Currently all committer’s should have an ssh account on the main git server, dispatch.rtems.org. If you have been granted commit access and do have an account on dispatch.rtems.org one should be requested on the devel@ list. SSH access for git uses key logins instead of passwords. The key should be at least 1024 bits in length.

The public repositories can by cloned with

git clone ssh://user@dispatch.rtems.org/data/git/rtems.git

Or replace rtems.git with another repo to clone another one.

6.2.2. Personal Repository

Personal repositories keep the clutter away from the master repository. A user with a personal repository can make commits, create and delete branches, plus more without interfering with the master repository. Commits to the master repository generate email to the vc@ list and development type commits by a developer would only add noise and lessen the effectiveness of the commit list

A committer should maintain a personal clone of the RTEMS repository through which all changes merged into the RTEMS head are sent. The personal repository is also a good place for committers to push branches that contain works in progress. The following instructions show how to setup a personal repositor that by default causes commits to go to your private local repository and pushes to go to your publicly visible personal repository. The RTEMS head is configured as a remote repository named ‘upstream’ to which you can push changes that have been approved for merging into RTEMS.

Branches aren’t automatically pushed until you tell git to do the initial push after which the branch is pushed automatically. In order to keep code private just put it on a branch in your local clone and do not push the branch.

6.2.3. Create a personal repository

Set up the server side repository. In the following substitute user with your username.

# ssh git.rtems.org
[user@git ~]$ ln -s /data/git/user git
[user@git ~]$ ls -l
lrwxrwxrwx 1 user rtems 16 Feb  1 11:52 git -> /data/git/user
[user@git ~]$ cd git
[user@git git]$ git clone --mirror /data/git/rtems.git

Provide a description for the repository, for example “Clone of master repository.”

[user@git git]$ echo "Clone of master repository." > rtems.git/description
[user@git git]$ logout

Clone the repository on your local machine

# git clone ssh://user@dispatch.rtems.org/home/user/git/rtems.git
# cd rtems

Add the RTEMS repository as a remote repository and get the remote tags and branches

# git remote add upstream ssh://user@dispatch.rtems.org/data/git/rtems.git
# git fetch upstream

After a little while you should be able to see your personal repo at https://git.rtems.org/@USER@/rtems.git/ and you can create other repositories in your git directory that will propagate to https://git.rtems.org/@USER@/ if you need. For example, joel’s personal repos appear at https://git.rtems.org/joel/.