RTEMS Software Engineering (7.491f6c8)#
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.
RTEMS Online Resources
Documentation https://docs.rtems.org
Mailing Lists https://lists.rtems.org
Bug Reporting https://gitlab.rtems.org
Git Repositories https://gitlab.rtems.org
Developers https://gitlab.rtems.org
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 RTEMS User Manual.
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 to. 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 stakeholders to invest on an ongoing basis to ensure that any investment they make is maintained and viable in the long-term. 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.
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], [MWGU16], and Alisair Mavin’s web site. The patterns are:
Ubiquitous
The <system name> shall <system response>.
Event-driven
When <trigger>, the <system name> shall <system response>.
State-driven
While <pre-condition>, the <system name> shall <system response>.
Unwanted behaviour
If <trigger>, then the <system name> shall <system response>.
Optional
Where <feature is included>, the <system name> shall <system response>.
Complex
Where <feature 0 is included>, where <feature 1 is included>, …, where <feature n is included>, while <pre-condition 0>, while <pre-condition 1>, …, while <pre-condition m>, when <trigger>, the <system name> shall <system response>.
Where <feature 0 is included>, where <feature 1 is included>, …, where <feature n is included>, while <pre-condition 0>, while <pre-condition 1>, …, while <pre-condition m>, if <trigger>, then the <system name> shall <system response>.
The optional pattern 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
idparameter and return theRTEMS_SUCCESSFULstatus.- spec:/classic/task/create-err-toomany
If no free task objects exists, the task create directive shall return the
RTEMS_TOO_MANYstatus.- spec:/classic/task/create-err-invaddr
If the
idparameter isNULL, the task create directive shall return theRTEMS_INVALID_ADDRESSstatus.- spec:/classic/task/create-err-invname
If the
nameparameter is invalid, the task create directive shall return theRTEMS_INVALID_NAMEstatus.…
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.1. Specification Item Hierarchy#
The specification item types have the following hierarchy:
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 through the type attribute if the value is build. This set of attributes specifies a build item. Only the build-type attribute is mandatory. The explicit attributes for this type are:
- build-type
The attribute value shall be a Name. It shall be the build item type.
- extra-files
The attribute value shall be a list of strings. If the value is present, it shall be the list of extra files associated with the item.
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 through 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 (
-Doption value forgnatmake).- 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.
- 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.
- 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. Each list element shall be a Build Link Static Library Directive.
- 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 & Co. KG
cppflags: []
cxxflags: []
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 through 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 & Co. KG
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 through 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 is 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 & Co. KG
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 through 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 through 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:
- 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.
- 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
cflags: []
copyrights:
- Copyright (C) 2020 embedded brains GmbH & Co. KG
cppflags: []
cxxflags: []
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 through 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.
zforlibz.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 & Co. KG
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 through 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. Objects Items must not be included on multiple paths through the build dependency graph with identical build options. Violating this can cause race conditions in the build system due to duplicate installs and multiple instances of build tasks. 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 & Co. KG
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 through the build-type attribute if the value is option. This set of attributes specifies a build option. The following explicit attributes are mandatory:
actionsdefaultdescription
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 list. Each list element shall be a Build Option Value. It shall be the list of default values of the option. When a default value is needed, the first value on the list which is enabled according to the enabled set is chosen. If no value is enabled, then the default value is
null.- 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, 2022 embedded brains GmbH & Co. KG
default:
- enabled-by:
- bsps/powerpc/motorola_powerpc
- m68k/m5484FireEngine
- powerpc/hsc_cm01
value: 9600
- enabled-by: m68k/COBRA5475
value: 19200
- enabled-by: true
value: 115200
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 through 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-builddo-configureprepare-buildprepare-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 thedo_build()method of thewscript. A local variablebldis available with thewafbuild context. A local variablebicis 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 thedo_configure()method of thewscript. A local variableconfis available with thewafconfiguration context. A local variablecicis 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 theprepare_build()method of thewscript. A local variablebldis available with thewafbuild context. A local variablebicis 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 theprepare_configure()method of thewscript. A local variableconfis available with thewafconfiguration context. A local variablecicis available with the configuration item context.- stlib
The attribute value shall be a list. Each list element shall be a Build Link Static Library Directive.
- 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: script
copyrights:
- Copyright (C) 2020 embedded brains GmbH & Co. KG
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 through 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 & Co. KG
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 through 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
wafbuild 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. Each list element shall be a Build Link Static Library Directive.
- 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 & Co. KG
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 through 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.
- 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 through 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 through 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 through 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 through 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:
- index-entries
The attribute value shall be a list of strings. It shall be a list of additional document index entries. A document index entry derived from the interface name is added automatically.
- 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 through 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 through 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.
- name
The attribute value shall be an Application Configuration Option Name.
- notes
The attribute value shall be an Interface Notes.
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 through 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 through 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:
Application Configuration Option Item Type through the
appl-config-option-typeattribute if the value isinitializerApplication Configuration Option Item Type through the
appl-config-option-typeattribute if the value isinteger
This set of attributes specifies application configuration initializer or integer option. All explicit attributes shall be specified. The explicit attributes for this type are:
- default-value
The attribute value shall be an Integer or String. It shall describe the default value of the application configuration option.
5.2.2.24. Interface Compound Item Type#
This type refines the following types:
Interface Item Type through the
interface-typeattribute if the value isstructInterface Item Type through the
interface-typeattribute if the value isunion
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 Define Item Type#
This type refines the Interface Item Type through 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.26. Interface Domain Item Type#
This type refines the Interface Item Type through the interface-type attribute if the value is domain. This set of attributes specifies an interface domain. Interface items 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.27. Interface Enum Item Type#
This type refines the Interface Item Type through 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.28. Interface Enumerator Item Type#
This type refines the Interface Item Type through 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.29. Interface Forward Declaration Item Type#
This type refines the Interface Item Type through 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.30. Interface Function or Macro Item Type#
This type refines the following types:
Interface Item Type through the
interface-typeattribute if the value isfunctionInterface Item Type through the
interface-typeattribute if the value ismacro
This set of attributes specifies a function or 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 Function or Macro 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 or 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.31. Interface Group Item Type#
This type refines the Interface Item Type through 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.
- text
The attribute value shall be a Requirement Text. It shall state the requirement for the interface group.
5.2.2.32. Interface Header File Item Type#
This type refines the Interface Item Type through 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:
- brief
The attribute value shall be an Interface Brief Description.
- 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.33. Interface Typedef Item Type#
This type refines the Interface Item Type through 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.
- 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.34. Interface Unspecified Header File Item Type#
This type refines the Interface Item Type through the interface-type attribute if the value is unspecified-header-file. This set of attributes specifies an unspecified 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.- references
The attribute value shall be a list. Each list element shall be an External Reference.
5.2.2.35. Interface Unspecified Item Type#
This type refines the following types:
Interface Item Type through the
interface-typeattribute if the value isunspecified-defineInterface Item Type through the
interface-typeattribute if the value isunspecified-enumInterface Item Type through the
interface-typeattribute if the value isunspecified-enumeratorInterface Item Type through the
interface-typeattribute if the value isunspecified-functionInterface Item Type through the
interface-typeattribute if the value isunspecified-groupInterface Item Type through the
interface-typeattribute if the value isunspecified-macroInterface Item Type through the
interface-typeattribute if the value isunspecified-objectInterface Item Type through the
interface-typeattribute if the value isunspecified-structInterface Item Type through the
interface-typeattribute if the value isunspecified-typedefInterface Item Type through the
interface-typeattribute if the value isunspecified-union
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.
- references
The attribute value shall be a list. Each list element shall be an External Reference.
5.2.2.36. Interface Variable Item Type#
This type refines the Interface Item Type through 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.37. Register Block Item Type#
This type refines the Interface Item Type through the interface-type attribute if the value is register-block. This set of attributes specifies a register block. A register block may be used to specify the interface of devices. Register blocks consist of register block members specified by the definition attribute. Register block members are either instances of registers specified by the registers attribute or instances of other register blocks specified by links with the Register Block Include Role. Registers consists of bit fields (see Register Bits Definition. The register block members are placed into the address space of the device relative to the base address of the register block. Register member offsets and the register block size are specified in units of the address space granule. 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 a Register Block Member Definition Directive.
- 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 name of the register block.
- notes
The attribute value shall be an Interface Notes.
- register-block-group
The attribute value shall be a string. It shall be the name of the interface group defined for the register block. For the group identifier see the
identifierattribute.- register-block-size
The attribute value shall be an Optional Integer. If the value is present, then it shall be the size of the register block in units of the address space granule.
- register-prefix
The attribute value shall be an optional string. If the value is present, then it will be used to prefix register bit field names, otherwise the value of the
nameattribute will be used.- registers
The attribute value shall be a list. Each list element shall be a Register Definition.
5.2.2.38. Proxy Item Types#
This type refines the Root Item Type through the type attribute if the value is proxy. Items of similar characteristics may link to a proxy item through links with the Proxy Member Link Role. A proxy item resolves to the first member item which is enabled. Proxies may be used to provide an interface with a common name and implementations which depend on configuration options. For example, in one configuration a constant could be a compile time constant and in another configuration it could be a read-only object.
5.2.2.39. Requirement Item Type#
This type refines the Root Item Type through 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 an External 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 & Co. KG
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.40. Functional Requirement Item Type#
This type refines the Requirement Item Type through 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.41. Action Requirement Item Type#
This type refines the Functional Requirement Item Type through 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.
- skip-reasons
The attribute value shall be an Action Requirement Skip Reasons.
- 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-cleanup
The attribute value shall be an optional string. If the value is present, then it shall be the test cleanup code. The code is placed in the test action loop body after the test post-condition checks.
- test-context
The attribute value shall be a list. Each list element shall be a Test Context Member.
- test-context-support
The attribute value shall be an optional string. If the value is present, then it shall be the test context support code. The context support code is placed at file scope before the test context definition.
- 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 a 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-prepare
The attribute value shall be an optional string. If the value is present, then it shall be the early test preparation code. The code is placed in the test action loop body before the test pre-condition preparations.
- test-setup
The attribute value shall be a Test Support Method.
- test-stop
The attribute value shall be a Test Support 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 a Test Support 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 & Co. KG
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: