diff options
Diffstat (limited to 'eng')
42 files changed, 13986 insertions, 1651 deletions
diff --git a/eng/build-system.rst b/eng/build-system.rst new file mode 100644 index 0000000..11e8ba7 --- /dev/null +++ b/eng/build-system.rst @@ -0,0 +1,520 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +.. _BSPBuildSystem: + +BSP Build System +**************** + +The purpose of the build system is to produce and install artefacts from the +RTEMS sources such as static libraries, start files, linker command files, +configuration header files, header files, test programs, package description +files, and third-party build system support files for a specific BSP in a user +controlled configuration. + +Goals +===== + +The system should meet the following goals: + +* The install location of artefacts should be the same as in previous build + systems + +* Easy build configuration of BSPs through configuration options + +* Enable the BSP build configuration to be placed in a version control system + (e.g. no local paths) + +* Fast builds (also on Windows) + +* Easy to maintain, e.g. add/remove a BSP, add/change/remove configuration + options, add/remove a library, add/remove an object to/from a library, + add/remove tests + +* Reusable build specifications (e.g. generate documentation for BSP options for + the user manual) + +* Validation of built artefacts (e.g. ensure that the objects are built as + specified using the DWARF debug information) + +* Support building of BSPs external to the project + +* Customization of the build (e.g. build only a subset of the RTEMS functions) + +* Support alternative compilers such as clang instead of GCC + +* Ability to unit test the build system + +* Version control system friendly change sets (e.g. most changes are line based + in text files) + +Configurable things which depend on the host computer environment such as paths +to tools are intended to be passed as command line options to the ``waf`` +command line tool. Configurable things which define what is built and how the +artefacts are configured are intended to be placed in configuration files that +can be configuration controlled. The ``waf`` build script file called +``wscript`` should know nothing about the layout of the sources. What is built +and how it is built should be completely defined by the user configuration and +the build specification items. + +Overview +======== + +For an overview of the build system, see the *BSP Build System* chapter of the +`RTEMS User Manual <https://docs.rtems.org/branches/master/user/bld/>`_. + +Commands +======== + +This section explains how the :ref:`SpecTypeBuildItemType` items determine what +the following ``waf`` commands do. + +BSP List +-------- + +In the ``./waf bsplist`` command, the BSP list is generated from the +:ref:`SpecTypeBuildBSPItemType` items. + +BSP Defaults +------------ + +In the ``./waf bspdefaults`` command, the BSP defaults are generated from the +:ref:`SpecTypeBuildBSPItemType` and :ref:`SpecTypeBuildOptionItemType` items. +Build specification items contribute to the command through the +``do_defaults()`` method in the ``wscript``. + +Configure +--------- + +In the ``./waf configure`` command, the build specification items contribute to +the command through the ``prepare_configure()`` and ``do_configure()`` methods +in the ``wscript``. + +Build, Clean, and Install +------------------------- + +In the ``./waf``, ``./waf clean``, and ``./waf install`` commands, the build +specification items contribute to the commands through the ``prepare_build()`` +and ``do_build()`` methods in the ``wscript``. + +UID Naming Conventions +====================== + +Use the following patterns for :ref:`UID names <ReqEngIdent>`: + +abi + Use the name ``abi`` for the GCC-specific ABI flags item of a BSP family. + Each BSP family should have exactly one :ref:`SpecTypeBuildOptionItemType` + item which defines the GCC-specific ABI flags for all base BSPs of the + family. For an architecture named *arch* and a BSP family named *family*, + the file path is ``spec/build/bsps/arch/family/abi.yml``. + +abiclang + Use the name ``abiclang`` for the clang-specific ABI flags item of a BSP + family. Each BSP family may have at most one + :ref:`SpecTypeBuildOptionItemType` item which defines the clang-specific + ABI flags for all base BSPs of the family. For an architecture named + *arch* and a BSP family named *family*, the file path is + ``spec/build/bsps/arch/family/abiclang.yml``. + +bsp* + Use the prefix ``bsp`` for base BSPs. + +cfg* + Use the prefix ``cfg`` for ``config.h`` header options. + +grp* + Use the prefix ``grp`` for groups. + +lib* + Use the prefix ``lib`` for libraries. + +linkcmds* + Use the prefix ``linkcmds`` for linker command files. + +obj* + Use the prefix ``obj`` for objects. Use + + * ``objmpci`` for objects which are enabled by ``RTEMS_MULTIPROCESSING``, + + * ``objnet`` for objects which are enabled by ``RTEMS_NETWORKING``, + + * ``objnetnosmp`` for objects which are enabled by ``RTEMS_NETWORKING`` and + not ``RTEMS_SMP``, and + + * ``objsmp`` for objects which are enabled by ``RTEMS_SMP``. + +opt* + Use the prefix ``opt`` for options. Use + + * ``optclock*`` for options which have something to do with the clock + driver, + + * ``optconsole*`` for options which have something to do with the console + driver, + + * ``optirq*`` for options which have something to do with interrupt + processing, + + * ``optmem*`` for options which have something to do with the memory + configuration, map, settings, etc., and + + * ``optosc*`` for options which have something to do with oscillators. + +start + Use the name ``start`` for BSP start file items. Each architecture or BSP + family should have a :ref:`SpecTypeBuildStartFileItemType` item which + builds the start file of a BSP. For an architecture named *arch* and a BSP + family named *family*, the file path is ``spec/build/bsps/arch/start.yml`` + or ``spec/build/bsps/arch/family/start.yml``. It is preferable to have a + shared start file for the architecture instead of a start file for each BSP + family. + +tst* + Use the prefix ``tst`` for test states. + +.. _BuildSpecItems: + +Build Specification Items +========================= + +Specification items of refinements of the :ref:`SpecTypeBuildItemType` are used +by the ``wscript`` to determine what it should do. The ``wscript`` does not +provide default values. All values are defined by specification items. The +entry point to what is built are the :ref:`SpecTypeBuildBSPItemType` items and +the top-level :ref:`SpecTypeBuildGroupItemType` item. The user configuration +defines which BSPs are built. The top-level group defaults to ``/grp`` and can +be changed by the ``--rtems-top-level`` command line option given to the ``waf +configure`` command. + +The top-level group is a trade-off between the specification complexity and a +strict dependency definition. Dependencies are normally explicit though the +item links. However, using only explicit dependencies would make the +specification quite complex, see :numref:`BuildExplicitDeps`. The top-level +group and explicit :ref:`SpecTypeBuildBSPItemType` items reduce the +specification complexity since they use a priori knowledge of global build +dependencies, see :numref:`BuildOrderDeps` for an example. This approach makes +the build system easier, but less general. + +.. _BuildExplicitDeps: + +.. figure:: ../images/eng/bld-deps.* + :width: 100% + + Example with Explicit Item Links + + This example shows how build item dependencies are specified explicitly + by item links. In this example, a user wants to build a group of tests. + Each test program has a dependency on the standard RTEMS libraries. The + first issue is that the ``librtemsbsp.a`` needs dependencies to all base + BSP variants (more than 100). The dependencies are the values of the + ``links`` attribute in the library item files. External BSPs would have + to modify the library item files. This is quite undesirable. The + second issue is that the source files of the ``librtemscpu.a`` need a + dependency to the ABI compiler flags specified by each BSP. The third + issue is that each BSP has to define its own ``bspopts.h`` configuration + header item. + +.. _BuildOrderDeps: + +.. figure:: ../images/eng/bld-deps2.* + :width: 50% + + Example with Implicit Ordering Rules + + This example shows how build item dependencies are specified by dedicated + BSP items, a top-level group, and ordered item links. The BSP is + configured after the top-level group item and built before the top-level + group item (defined by ``wscript`` source code). The library group is + configured and built before the test group as specified by the item link + order in the top-level group. The BSP options are processed before the + results are written to the configuration header ``bspopts.h`` as defined by + the BSP item link order. + +.. _BuildHowTo: + +How-To +====== + +This section presents how to do common maintenance tasks in the build system. + +Find the Right Item +------------------- + +You find all build specification items in the RTEMS sources under the +``spec/build`` directory. You can use the ``grep`` command line tool to search +in the build specification items. + +Create a BSP Architecture +------------------------- + +Let *arch* be the name of the architecture. You can add the new BSP +architecture with: + +.. code-block:: none + + $ mkdir spec/build/bsps/arch + +For a new architecture try to use a shared start file which can be used by all +BSPs of the architecture. Add a :ref:`SpecTypeBuildStartFileItemType` item for +it: + +.. code-block:: none + + $ vi spec/build/bsps/arch/start.yml + +Create a BSP Family +------------------- + +Let *family* be the BSP family name and *arch* the name of the architecture. +You can add the new BSP family with: + +.. code-block:: none + + $ mkdir spec/build/bsps/arch/family + +Add a :ref:`SpecTypeBuildOptionItemType` item for the ABI flags of the BSP family: + +.. code-block:: none + + $ vi spec/build/bsps/arch/family/abi.yml + +Define the ABI flags for each base BSP of the family. The ``${ABI_FLAGS}`` are +used for the ``${ASFLAGS}``, ``${CFLAGS}``, ``${CXXFLAGS}``, and ``${LDFLAGS}`` +build environment variables. Please have a look at the following example which +shows the GCC-specific ABI flags item of the ``sparc/leon3`` BSP family: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + actions: + - get-string: null + - split: null + - env-append: null + build-type: option + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + default: + - -mcpu=leon3 + default-by-variant: + - value: + - -mcpu=leon3 + - -mfix-ut700 + variants: + - sparc/ut700 + - value: + - -mcpu=leon + - -mfix-ut699 + variants: + - sparc/ut699 + - value: + - -mcpu=leon3 + - -mfix-gr712rc + variants: + - sparc/gr712rc + description: | + ABI flags + enabled-by: gcc + links: [] + name: ABI_FLAGS + type: build + +If the architecture has no shared start file, then add a +:ref:`SpecTypeBuildStartFileItemType` item for the new BSP family: + +.. code-block:: none + + $ vi spec/build/bsps/arch/family/start.yml + +Add a Base BSP to a BSP Family +------------------------------ + +.. _BuildBSPFamilyOneBSP: + +.. figure:: ../images/eng/bld-bsp.* + :width: 40% + :figclass: align-center + + This example shows a BSP family named *family* in the architecture *arch* + which consists of only one base BSP named *xyz*. The BSP sources and + installation information is contained in the + ``spec:/build/bsps/arch/family/bspxyz`` BSP item. The items linked by the + BSP item are shown using relative UIDs. + +.. _BuildBSPFamilyManyBSPs: + +.. figure:: ../images/eng/bld-bsp2.* + :width: 50% + :figclass: align-center + + This example shows a BSP family named *family* in the architecture *arch* + which consists of three base BSPs named *rst*, *uvw*, and *xyz*. The BSP + sources and installation information is contained in the *obj* objects + item. The group *grp* defines the main BSP constituents. The base BSP + items ``spec:/build/bsps/arch/family/bsprst``, + ``spec:/build/bsps/arch/family/bspuvw``, and + ``spec:/build/bsps/arch/family/bspxyz`` just define the name of the base + BSP and set a link to the group item. The base BSP and BSP family names + can be used for example in the ``default-by-variant`` attribute of + :ref:`SpecTypeBuildOptionItemType` items. The items linked by the BSP + items are shown using relative UIDs. + +Let *family* be the BSP family name, *arch* the name of the architecture, and +*new* the name of the new base BSP. You can add the new base BSP with: + +.. code-block:: none + + $ vi spec/build/bsps/arch/family/bspnew.yml + +Define the attributes of your new base BSP according to +:ref:`SpecTypeBuildBSPItemType`. + +In case the BSP family has no group, then create a group if it is likely that +the BSP family will contain more than one base BSP (see +:ref:`BuildHowToBSPFamilyGroup`). + +If the BSP family has a group, then link the new base BSP to the group with: + +.. code-block:: none + + $ vi spec/build/bsps/arch/familiy/grp.yml + +Add a link using a relative UID to the new base BSP item: + +.. code-block:: yaml + + links: + - role: build-dependency + uid: bspnew + +Add a BSP Option +---------------- + +Let *family* be the BSP family name, *arch* the name of the architecture, and +*new* the name of the new BSP option. You can add the new BSP option with: + +.. code-block:: none + + $ vi spec/build/bsps/arch/family/optnew.yml + +Define the attributes of your new BSP option according to +:ref:`SpecTypeBuildOptionItemType`. Link the option item to the corresponding +group or BSP item using a relative UID: + +.. code-block:: yaml + + links: + - role: build-dependency + uid: optnew + +.. _BuildHowToBSPFamilyGroup: + +Extend a BSP Family with a Group +-------------------------------- + +Let *family* be the BSP family name and *arch* the name of the architecture. If +you want to have more than one base BSP in a BSP family, then you have to use a +group item (see :ref:`SpecTypeBuildGroupItemType`). Add the group item named *grp* to the +family with: + +.. code-block:: none + + $ vi spec/build/bsps/arch/family/grp.yml + +Define the attributes of your new group according to +:ref:`SpecTypeBuildGroupItemType` and move the links of the existing base BSP +item to the group item. Add a link to *obj*. + +Add an objects item named *obj* to the family with: + +.. code-block:: none + + $ vi spec/build/bsps/arch/family/obj.yml + +Define the attributes of your new objects item according to +:ref:`SpecTypeBuildObjectsItemType` and move the ``cflags``, ``cppflags``, +``includes``, ``install`` and ``source`` attribute values of the +existing base BSP item to the objects item. + +Add a Test Program +------------------ + +Let *collection* be the name of a test program collection and *new* the name of +the new test program. You can add the new test program with: + +.. code-block:: none + + $ vi spec/build/testsuites/collection/new.yml + +Define the attributes of your new test program according to +:ref:`SpecTypeBuildTestProgramItemType`. + +Edit corresponding group item of the test program collection: + +.. code-block:: none + + $ vi spec/build/testsuites/collection/grp.yml + +Add a link to the new test program item using a relative UID: + +.. code-block:: yaml + + links: + - role: build-dependency + uid: new + +Add a Library +------------- + +Let *new* be the name of the new library. You can add the new library with: + +.. code-block:: none + + $ vi spec/build/cpukit/libnew.yml + +Define the attributes of your new library according to +:ref:`SpecTypeBuildLibraryItemType`. + +Edit corresponding group item: + +.. code-block:: none + + $ vi spec/build/cpukit/grp.yml + +Add a link to the new library item using a relative UID: + +.. code-block:: yaml + + links: + - role: build-dependency + uid: libnew + +Add an Object +------------- + +Build objects logically separate relatively independent segments of +functionality (for example a device driver, an architecture-dependent feature, +etc.). Let *new* be the name of the new object. You can add the new object +with: + +.. code-block:: none + + $ vi spec/build/cpukit/objnew.yml + +Define the attributes of your new object according to +:ref:`SpecTypeBuildObjectsItemType`. + +Edit corresponding group item: + +.. code-block:: none + + $ vi spec/build/cpukit/grp.yml + +Add a link to the new objects item using a relative UID: + +.. code-block:: yaml + + links: + - role: build-dependency + uid: objnew diff --git a/eng/coding-80cols.rst b/eng/coding-80cols.rst deleted file mode 100644 index 85b838a..0000000 --- a/eng/coding-80cols.rst +++ /dev/null @@ -1,154 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Eighty Character Line Limit -*************************** - -.. COMMENT: TBD - Convert the following to Rest and insert into this file -.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line - - Code should look good for everyone under some standard width assumptions. - Where a line wraps should be the same for anyone reading the code. For - historical reasons, RTEMS uses 80 characters as the maximum width for each - line of code. - -If you find yourself with code longer than 80 characters, first ask yourself -whether the nesting level is too deep, names too long, compound expressions too -complicated, or if some other guideline for improving readability can help to -shrink the line length. Refactoring nested blocks into functions can help to -alleviate code width problems while improving code readability. Making names -descriptive yet terse can also improve readability. If absolutely necessary -to have a long line, follow the rules on this page to break the line up to adhere -to the 80 characters per line rule. - -Breaking long lines -------------------- - -``if``, ``while``, and ``for`` loops have their condition expressions aligned -and broken on separate lines. When the conditions have to be broken, none go on -the first line with the ``if``, ``while``, or ``for`` statement, and none go on -the last line with the closing parenthesis and (optional) curly brace. Long -statements are broken up and indented at operators, with an operator always -being the last token on a line. No blank spaces should be left at the end of -any line. Here is an example with a ``for`` loop. - -.. code-block:: c - - for ( initialization = statement; a + really + long + statement + that + evaluates + to < a + boolean; another + statement++ ) { - z = a + really + long + statement + that + needs + two + lines + gets + indented + four + more + spaces + on + the + second + and + subsequent + lines + and + broken + up + at + operators; - } - -Should be replaced with - -.. code-block:: c - - for ( - initialization = statement; - a + really + long + statement + that + evaluates + to < - a + boolean; - another + statement++ - ) { - z = a + really + long + statement + that + needs + - two + lines + gets + indented + four + more + - spaces + on + the + second + and + subsequent + - lines + and + broken + up + at + operators; - } - -Note that indentations should add 2 nesting levels (4 space characters, not tabs). - -Similarly, - -.. code-block:: c - - if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) { - -should be broken up like - -.. code-block:: c - - if ( - this + that < those && - this + these < that && - this + those < these && - this < those && - those < that - ) { - -Note that each expression that resolves to a boolean goes on its own line. -Where you place the boolean operator is a matter of choice. - -When a line is long because of a comment at the end, move the comment to -just before the line, for example - -.. code-block:: c - - #define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */ - -can be replaced with - -.. code-block:: c - - /* Plus + a + really + long + comment */ - #define A_LONG_MACRO_NAME (AND + EXPANSION) - -C Preprocessor macros need to be broken up with some care, because the -preprocessor does not understand that it should eat newline characters. So - -.. code-block:: c - - #define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED) - -would become - -.. code-block:: c - - #define A_LONG_MACRO_NAME ( \ - AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \ - DEFINED \ - ) - -Notice that each line is terminated by a backslash then the carriage return. -The backslash tells the preprocessor to eat the newline. Of course, if you have -such a long macro, you should consider not using a macro. - -Function declarations can be broken up at each argument, for example - -.. code-block:: c - - int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 ); - -would be broken up as - -.. code-block:: c - - int this_is_a_function( - int arg1, - int arg2, - int arg3, - int arg4, - int arg5, - int arg6, - int arg7, - int arg8, - int arg9 - ); - -Excessively long comments should be broken up at a word boundary or somewhere -that makes sense, for example - -.. code-block:: c - - /* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */ - -would be - -.. code-block:: c - - /* Excessively long comments should be broken up at a word boundary or - * somewhere that makes sense, for example */ - -Note that multiline comments have a single asterisk aligned with the asterisk -in the opening ``/*``. The closing ``*/`` should go at the end of the last -line. diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst index 488ee26..b56d3c2 100644 --- a/eng/coding-conventions.rst +++ b/eng/coding-conventions.rst @@ -9,119 +9,127 @@ Coding Conventions ****************** -The style of RTEMS is generally consistent in the core areas. -This page attempts to capture generally accepted practices. -When in doubt, consult the code around you or look in cpukit/rtems. -See the sister page `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_. -for examples that illustrate style rules and Doxygen usage. +The style of RTEMS is generally consistent in the core areas. This section +attempts to capture generally accepted practices. When in doubt, consult the +code around you, look in the RTEMS sources in the directories +:file:`cpukit/include/rtems/score` and :file:`cpukit/score`, or ask on the +:r:list:`devel`. Source Documentation -------------------- -* Use Doxygen according to our `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_.. -* Start each file with a brief description followed by a license. - See `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_.. -* Use /* */ comments. -* Use comments wisely within function bodies, to explain - or draw attention without being verbose. -* Use English prose and strive for good grammar, - spelling, and punctuation. -* Use TODO: with a comment to indicate code that needs improvement. - Make it clear what there is to do. -* Use XXX or FIXME to indicate an error/bug/broken code. +* Use Doxygen according to our :ref:`DoxygenGuidelines`. + +* Use the file templates, see :ref:`FileTemplates`. + +* Use ``/* */`` comments. + +* Do not use ``//`` comments. + +* Use comments wisely within function bodies, to explain or draw attention + without being verbose. + +* Use English prose and strive for good grammar, spelling, and punctuation. + +* Use ``TODO`` with a comment to indicate code that needs improvement. Make + it clear what there is to do. Add a ticket and add a link to it. + +* Use ``XXX`` or ``FIXME`` to indicate an error/bug/broken code. Add a ticket + and add a link to it. Licenses -------- -* The RTEMS `License <https://devel.rtems.org/wiki/TBR/Website/License>`_. is the typical - and preferred license. - * 2- and 3-clause BSD, MIT, and other OSI-approved non-copyleft licenses - that permit statically linking with the code of different licenses - are acceptable. - * GPL licensed code is NOT acceptable, neither is LGPL. - See `this blog post explanation <http://gedare-csphd.blogspot.com/2013/05/software-licenses-with-rtems.html>`_. - for more information. - * Advertising obligations are NOT acceptable, but restrictions are permissible. +The RTEMS Project has strict requirements on the types of software licenses +that apply to software it includes and distributes. Submissions will be +summarily rejected that do not follow the correct license or file header +requirements. + +* Refer to :ref:`LicensingRequirements` for a discussion of the acceptable + licenses and the rationale. + +* Refer to :ref:`FileHeaderCopyright` for example copyright/license comment + blocks for various languages. Language and Compiler --------------------- * Use C99. + * Treat warnings as errors: eliminate them. + * Favor C, but when assembly language is required use inline assembly if possible. + * Do not use compiler extensions. -* Use the RTEMS_macros defined in score/basedefs.h for abstracting - compiler-specific features. + +* Use the RTEMS macros defined in <rtems/score/basedefs.h> for abstracting + compiler-specific features. For using attributes see the + `GCC attribute syntax <https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html#Attribute-Syntax>`_. + Prefer to place attributes in front of the declarator. Try to be in line + with + `C++11 attributes <https://en.cppreference.com/w/cpp/language/attributes>`_ + and C11 keywords such as + `_Noreturn <https://en.cppreference.com/w/c/language/_Noreturn>`_. + * Use NULL for the null pointer, and prefer to use explicit checks against NULL, e.g., .. code-block:: c if ( ptr != NULL ) + instead of .. code-block:: c if ( !ptr ) + * Use explicit checks for bits in variables. + * Example 1: Use + .. code-block:: c if ( XBITS == (var & XBITS) ) + to check for a set of defined bits. + * Example 2: Use + .. code-block:: c if ( (var & X_FLAGS) != 0) ) + instead of + .. code-block:: c if ( !!(var & X_FLAGS) ) + to check for at least 1 defined bit in a set. -* Use '(void) unused;' to mark unused parameters and set-but-unused + +* Use ``(void) unused;`` to mark unused parameters and set-but-unused variables immediately after being set. + * Do not put function prototypes in C source files, any global functions should have a prototype in a header file and any private function should be declared static. + * Declare global variables in exactly one header file. Define global variables in at most one source file. Include the header file declaring the global variable as the first include file if possible to make sure that the compiler checks the declaration and definition and that the header file is self-contained. + * Do not cast arguments to any printf() or printk() variant. Use <inttypes.h> PRI constants for the types supported there. Use <rtems/inttypes.h> for the other POSIX and RTEMS types that have PRI constants defined there. This increases the portability of the printf() format. -* Do not use the register keyword. It is deprecated since C++14. -Formatting ------------ - -* Use spaces instead of tabs. -* Use two spaces for indentation, four spaces for - hanging indentation. -* Adhere to a limit of `80 characters per line <https://devel.rtems.org/wiki/Developer/Coding/80_characters_per_line>`_.. -* Put function return types and names on one line if they fit. -* Put function calls on one line if they fit. -* No space between a function name or function-like macro and - the opening parens. -* Put braces on the same line as and one space after the - conditional expression ends. -* Put the opening brace of a function definition one line after - the closing parenthesis of its prototype. -* Put a single space inside and outside of each parenthesis - of a conditional expression. - * Exception: never put a space before a closing semi-colon. -* Put a single space before and after ternary operators. -* Put a single space before and after binary operators. -* Put no space between unary operators (e.g. *, &, !, ~, ++, --) - and their operands. -* No spaces around dereferencing operators (-> and .). -* Do not use more than one blank line in a row. -* Do not use trailing whitespace at the end of a line. +* Do not use the register keyword. It is deprecated since C++14. Readability ------------ @@ -198,7 +206,7 @@ Portability Maintainability --------------- -* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_.. +* Minimize modifications to `third-party code <https://devel.rtems.org/wiki/Developer/Coding/ThirdPartyCode>`_. * Keep it simple! Simple code is easier to debug and easier to read than clever code. * Share code with other architectures, CPUs, and BSPs where possible. * Do not duplicate standard OS or C Library routines. @@ -211,8 +219,6 @@ Performance * Understand the constraints of `real-time programming <https://devel.rtems.org/wiki/TBR/Review/Real-Time_Resources>`_.. Limit execution times in interrupt contexts and critical sections, such as Interrupt and Timer Service Routines (TSRs). -* Functions used only through function pointers should be declared - 'static inline' (RTEMS_INLINE_ROUTINE) * Prefer to ++preincrement instead of postincrement++. * Avoid using floating point except where absolutely necessary. @@ -224,6 +230,43 @@ Miscellaneous * If adding code to ''cpukit'' be sure the filename is unique since all files under that directory get merged into a single library. +Header Files +------------ + +* Do not add top-level header files. Place the header files in a directory, + for example ``#include <rtems/*>``, ``#include <bsp/*>``, + ``#include <dev/*>``, etc. + +* Use the extension :file:`.h` for C header files. + +* Use the extension :file:`.hpp` for C++ header files. + +* Use the file template for header files, see :ref:`CCXXHeaderFileTemplate`. + +* Use separate header files for the API and the implementation. + +* Use :file:`foobar.h` for the header file of the ``foobar`` module which + defines API components. + +* Use :file:`foobardata.h` for the header file of the ``foobar`` module which + defines interfaces used by the application configuration. + +* Use :file:`foobarimpl.h` for the header file of the ``foobar`` module which + defines interfaces, macros, and inline functions used by the implementation. + +* Do not place inline functions which are only used in one implementation + source file into the implementation header file. Add these inline functions + directly to the corresponding source file. + +* Document all elements in header files with comments in Doxygen markup, see + :ref:`DoxygenGuidelines`. + +* Only place header files which should be directly included by the user with an + ``@file`` Doxygen directive into the API documentation group. Place internal + API header files with an ``@file`` Doxygen command into the implementation + documentation group even if they define API elements. The API documentation + group should only list public header files and no internal header files. + Layering -------- diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst index 2f7682d..efd543b 100644 --- a/eng/coding-doxygen.rst +++ b/eng/coding-doxygen.rst @@ -1,6 +1,8 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG + +.. _DoxygenGuidelines: Doxygen Guidelines ================== @@ -14,12 +16,13 @@ In the RTEMS source code, CamelCase is rarely used, so this makes it easier to search and replace Doxygen groups. It avoids ambiguous references to functions, types, defines, macros, and groups. All groups shall have an ``RTEMS`` prefix. This makes it possible to include the RTEMS files with -Doxygen comments in a larger project without name conflicts. +Doxygen comments in a larger project without name conflicts. The group name +shall use `Title Case <https://en.wikipedia.org/wiki/Letter_case#Title_Case>`_. .. code:: c /** - * @defgroup RTEMSScoreThread + * @defgroup RTEMSScoreThread Thread Handler * * @ingrop RTEMSScore * @@ -34,18 +37,28 @@ global variable declaration shall belong to at least one Doxygen group. Use ``@defgroup`` and ``@addtogroup`` with ``@{`` and ``@}`` brackets to add members to a group. A group shall be defined at most once. Each group shall be documented with an ``@brief`` description and an optional detailed -description. The ``@brief`` description shall use -`Title Case <https://en.wikipedia.org/wiki/Letter_case#Title_Case>`_. -Use grammatically correct sentences for the detailed descriptions. +description. Use grammatically correct sentences for the ``@brief`` and +detailed descriptions. + +For the ``@brief`` description use phrases like this: + +* This group contains ... and so on. + +* The XYZ Handler provides ... and so on. + +* The ABC Component contains ... and so on. .. code:: c /** - * @defgroup RTEMSScoreThread + * @defgroup RTEMSScoreThread Thread Handler * * @ingrop RTEMSScore * - * @brief Thread Handler + * @brief The Thread Handler provides functionality related to the + * management of threads. + * + * This includes the creation, deletion, and scheduling of threads. * * ... * @@ -71,24 +84,33 @@ Use grammatically correct sentences for the detailed descriptions. Files ----- -Each source or header file shall have an ``@file`` block at the top of the -file. The ``@file`` block should precede the license header separated by one -blank line. This placement reduces the chance of merge conflicts in imported -third-party code. The ``@file`` block shall be put into a group with -``@ingroup GroupName``. The ``@file`` block should have an ``@brief`` -description and a detailed description if it is considered helpful. Use -``@brief @copybrief GroupName`` as a default to copy the ``@brief`` description -from the corresponding group and omit the detailed description. +Each header and source file shall have an ``@file`` block at the top of the +file after the SPDX License Identifier. The ``@file`` block shall precede the +license header separated by one blank line, see :ref:`CCXXHeaderFileTemplate` +and :ref:`CCXXASMSourceFileTemplate`. The ``@file`` block shall be put into a +group with ``@ingroup GroupName``. The ``@file`` block shall have an +``@brief`` description and an optional detailed description. The detailed +description could give an explanation why a certain set of functions or data +structures is grouped in one file. Use grammatically correct sentences for the +``@brief`` and detailed descriptions. -.. code:: c +For the ``@brief`` description of header files use phrases like this: - /** - * @file - * - * @ingroup RTEMSScoreThread - * - * @brief @copybrief RTEMSScoreThread - */ +* This header file provides ... and so on. + +* This header file provides the API of the ABC Manager. + +* This header file provides interfaces and functions used to implement the XYZ + Handler. + +For the ``@brief`` description of source files use phrases like this: + +* This source file contains the implementation of some_function(). + +* This source file contains the definition of some_data_element. + +* This source file contains the implementation of XZY Hander functions related + to ABC processing. .. code:: c @@ -97,38 +119,69 @@ from the corresponding group and omit the detailed description. * * @ingroup RTEMSScoreThread * - * @brief Some helpful brief description. - * - * Some helpful detailed description. + * @brief This source file contains the implementation of + * _Thread_Initialize(). */ Type Definitions ---------------- -Each type defined in a header file shall be documented with an ``@brief`` -description and an optional detailed description. Each type member shall be +Each type (``typedef``, ``struct``, ``enum``) defined in a header file shall be documented with an ``@brief`` description and an optional detailed description. -Use grammatically correct sentences for the detailed descriptions. +Use grammatically correct sentences for the ``@brief`` and detailed +descriptions. + +For the ``@brief`` description of types use phrases like this: + +* This type represents ... and so on. + +* This structure represents ... and so on. + +* This structure provides ... and so on. + +* This enumeration represents ... and so on. + +* The XYZ represents ... and so on. + +Each type member shall be documented with an ``@brief`` description and an +optional detailed description. Use grammatically correct sentences for the +``@brief`` and detailed descriptions. + +For the ``@brief`` description of types members use phrases like this: + +* This member represents ... and so on. + +* This member contains ... and so on. + +* This member references ... and so on. + +* The XYZ lock protects ... and so on. + +For the ``@brief`` description of boolean type members use a phrase like this: +"This member is true, if some condition is satisfied, otherwise it is false.". .. code:: c /** - * @brief The information structure used to manage each API class of objects. + * @brief The object information structure maintains the objects of an + * object class. * - * If objects for the API class are configured, an instance of this structure - * is statically allocated and pre-initialized by OBJECTS_INFORMATION_DEFINE() - * through <rtems/confdefs.h>. The RTEMS library contains a statically - * allocated and pre-initialized instance for each API class providing zero - * objects, see OBJECTS_INFORMATION_DEFINE_ZERO(). + * If objects for the object class are configured, then an instance of this + * structure is statically allocated and pre-initialized by + * OBJECTS_INFORMATION_DEFINE() through <rtems/confdefs.h>. The RTEMS + * library contains a statically allocated and pre-initialized instance for + * each object class providing zero objects, see + * OBJECTS_INFORMATION_DEFINE_ZERO(). */ typedef struct { /** - * @brief This is the maximum valid ID of this object API class. + * @brief This member contains the object identifier maximum of this + * object class. * - * This member is statically initialized and provides also the object API, - * class and multiprocessing node information. + * It is statically initialized. The object identifier maximum provides + * also the object API, class, and multiprocessing node information. * - * It is used by _Objects_Get() to validate an object ID. + * It is used by _Objects_Get() to validate an object identifier. */ Objects_Id maximum_id; @@ -138,27 +191,58 @@ Use grammatically correct sentences for the detailed descriptions. Function Declarations --------------------- -Each function declaration or function-like macros in a header file shall be +Each function declaration or function-like macro in a header file shall be documented with an ``@brief`` description and an optional detailed description. -Use grammatically correct sentences for the brief and detailed descriptions. +Use grammatically correct sentences for the ``@brief`` and detailed +descriptions. Use the descriptive-style for ``@brief`` descriptions, for +example ``"Creates a task."``, ``"Sends the events to the task."``, or +``"Obtains the semaphore."``. Use "the" to refer to parameters of the +function. Do not use descriptions like ``"Returns this and that."``. Describe +the function return in ``@retval`` and ``@return`` paragraphs. + Each parameter shall be documented with an ``@param`` entry. List the ``@param`` entries in the order of the function parameters. For *non-const pointer* parameters -* use ``@param[out]``, if the referenced object is modified by the function, or +* use ``@param[out]``, if the function writes under some conditions to memory + locations referenced directly or indirectly by the non-``const`` pointer + parameter, or + +* use ``@param[in, out]``, if the function reads under some conditions from + memory locations referenced directly or indirectly by the non-``const`` + pointer parameter and the function writes under some conditions to memory + locations referenced directly or indirectly by the non-``const`` pointer + parameter. -* use ``@param[in, out]``, if the referenced object is read and modified by the - function. +If the function only reads from memory locations referenced directly or +indirectly by a non-``const`` pointer parameter, then the pointer parameter +should be made ``const``. For other parameters (e.g. *const pointer* and *scalar* parameters) do not use -the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers. Each return -value or return value range shall be documented with an ``@retval`` entry. -Document the most common return value first. Use a placeholder name for value -ranges, e.g. ``pointer`` in the ``_Workspace_Allocate()`` example below. In -case the function returns only one value, then use ``@return``, e.g. use -``@retval`` only if there are at least two return values or return value -ranges. Use grammatically correct sentences for the parameter and return value -descriptions. +the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers. + +For the ``@param`` descriptions use phrases like this: + +* is the ABC. + +* indicates what should be done. + +* defines the something. + +* references the object to deal with. + +The phrase shall form a grammatically correct sentence if "This parameter" +precedes the phrase, for example "This parameter is the size of the message in +bytes to send.". + +Distinctive return values shall be documented with an ``@retval`` entry. +Document the most common return value first. Use ``@return`` to describe the +return of non-distinctive values. Use grammatically correct sentences for the +descriptions. Use sentences in simple past tense to describe conditions which +resulted in the return of a status value. Place ``@retval`` descriptions +before the ``@return`` description. For functions returning a boolean value, +use ``@return`` and a phrase like this: "Returns true, if some condition is +satisfied, otherwise false.". .. code:: c @@ -229,12 +313,14 @@ descriptions. /** * @brief Allocates a memory block of the specified size from the workspace. * - * @param size The size of the memory block. + * @param size is the size in bytes of the memory block. * - * @retval pointer The pointer to the memory block. The pointer is at least - * aligned by CPU_HEAP_ALIGNMENT. - * @retval NULL No memory block with the requested size is available in the + * @retval NULL No memory block with the requested size was available in the * workspace. + * + * @return Returns the pointer to the allocated memory block, if enough + * memory to satisfy the allocation request was available. The pointer is at + * least aligned by #CPU_HEAP_ALIGNMENT. */ void *_Workspace_Allocate( size_t size ); @@ -243,8 +329,8 @@ descriptions. /** * @brief Rebalances the red-black tree after insertion of the node. * - * @param[in, out] the_rbtree The red-black tree control. - * @param[in, out] the_node The most recently inserted node. + * @param[in, out] the_rbtree references the red-black tree. + * @param[in, out] the_node references the most recently inserted node. */ void _RBTree_Insert_color( RBTree_Control *the_rbtree, @@ -256,12 +342,12 @@ descriptions. /** * @brief Builds an object ID from its components. * - * @param the_api The object API. - * @param the_class The object API class. - * @param node The object node. - * @param index The object index. + * @param the_api is the object API. + * @param the_class is the object class. + * @param node is the object node. + * @param index is the object index. * - * @return Returns the object ID constructed from the arguments. + * @return Returns the object ID built from the specified components. */ #define _Objects_Build_id( the_api, the_class, node, index ) diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index f67a199..4fc17fd 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -1,8 +1,10 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2018, 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2018, 2020 Sebastian Huber +.. _FileTemplates: + File Templates ============== @@ -72,6 +74,8 @@ Check the top-level :file:`COPYING` file of the repository. If you are a new copyright holder, then add yourself to the top of the list. If your last year of a substantial contribution changed, then please update your copyright line. +.. _CCXXHeaderFileTemplate: + C/C++ Header File Template -------------------------- @@ -92,11 +96,11 @@ Use the following guidelines and template for C and C++ header files (here * Separate the Doxygen comment block from the copyright and license, so that the copyright and license information is not included in the Doxygen output. -* For C++ header files discard the extern "C". +* For C++ header files discard the ``extern "C"`` start and end sections. .. code-block:: c - /* SPDX-License-Identifier: BSD-2-Clause + /* SPDX-License-Identifier: BSD-2-Clause */ /** * @file @@ -138,18 +142,22 @@ Use the following guidelines and template for C and C++ header files (here #include <foo/bar/xyz.h> + /* Remove for C++ code */ #ifdef __cplusplus extern "C" { #endif /* Declarations, defines, macros, inline functions, etc. */ + /* Remove for C++ code */ #ifdef __cplusplus } #endif #endif /* _FOO_BAR_BAZ_H */ +.. _CCXXASMSourceFileTemplate: + C/C++/Assembler Source File Template ------------------------------------ @@ -196,7 +204,7 @@ and <COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. * POSSIBILITY OF SUCH DAMAGE. */ - #if HAVE_CONFIG_H + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -207,13 +215,66 @@ and <COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. Python File Template -------------------- -Use the following template for Python source files and other files which accept -a ``#``-style comment block. For the <FIRST YEAR>, <LAST YEAR>, and -<COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. +Use the following template for Python source files. For the <FIRST YEAR>, +<LAST YEAR>, and <COPYRIGHT HOLDER> placeholders see +:ref:`FileHeaderCopyright`. + +The ``File documentation block`` is a `Python docstring (PEP 257) +<https://www.python.org/dev/peps/pep-0257/>`_ module documentation +block. RTEMS uses ``"""`` for Python docstrings. + +.. code-block:: python + + # SPDX-License-Identifier: BSD-2-Clause + """File documentation block""" + + # Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER> + # + # Redistribution and use in source and binary forms, with or without + # modification, are permitted provided that the following conditions + # are met: + # 1. Redistributions of source code must retain the above copyright + # notice, this list of conditions and the following disclaimer. + # 2. Redistributions in binary form must reproduce the above copyright + # notice, this list of conditions and the following disclaimer in the + # documentation and/or other materials provided with the distribution. + # + # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + # POSSIBILITY OF SUCH DAMAGE. + +If the Python source file is a command line command add the following as the +first line of the file: .. code-block:: python #!/usr/bin/env python + +A command line Python module does not need to have the ``.py`` file extension. + +Only specify ``python`` as the command to ``env``. A system that does not +provide the ``python`` command can install a virtual python environment or the +user can prepend the specific Python versioned command to the Python script on +the command line when invoking the command. + +Shell Scripts +------------- + +Use the following template for shell script source files and other files which +accept a ``#``-style comment block. For the <FIRST YEAR>, <LAST YEAR>, and +<COPYRIGHT HOLDER> placeholders see :ref:`FileHeaderCopyright`. + +.. code-block:: shell + + #!/bin/sh # SPDX-License-Identifier: BSD-2-Clause # File documentation block diff --git a/eng/coding-formatting.rst b/eng/coding-formatting.rst new file mode 100644 index 0000000..0053568 --- /dev/null +++ b/eng/coding-formatting.rst @@ -0,0 +1,196 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2018. +.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project + +Formatting +********** + +Rules +----- + +* Adhere to the :ref:`EightyCharacterLineLimit`. + +* Use spaces instead of tabs. + +* Use two spaces for one indentation level. + +* Put function return types and names on one line if they fit. + +* Put function calls on one line if they fit. + +* No space between a function name or function-like macro and + the opening parenthesis. + +* Put braces on the same line as and one space after the + conditional expression ends. + +* Put the opening brace of a function definition one line after the closing + parenthesis of its prototype. + +* Put a single space inside and outside of each parenthesis of a conditional + expression. Exception: never put a space before a closing semi-colon. + +* Put a single space before and after ternary operators. + +* Put a single space before and after binary operators. + +* Put no space between unary operators (e.g. ``*``, ``&``, ``!``, ``~``, ``++``, ``--``) + and their operands. + +* No spaces around dereferencing operators (``->`` and ``.``). + +* Do not use more than one blank line in a row. + +* Do not use trailing white space at the end of a line. + +.. _EightyCharacterLineLimit: + +Eighty Character Line Limit +--------------------------- + +Code should look good for everyone under some standard width assumptions. +Where a line wraps should be the same for anyone reading the code. For +historical reasons, RTEMS uses 80 characters as the maximum width for each line +of code. The newline (``\n``) character terminating the line does not count +for the 80 character limit. + +If you find yourself with code longer than 80 characters, first ask yourself +whether the nesting level is too deep, names too long, compound expressions too +complicated, or if some other guideline for improving readability can help to +shrink the line length. Refactoring nested blocks into functions can help to +alleviate code width problems while improving code readability. Making names +descriptive yet terse can also improve readability. If absolutely necessary to +have a long line, follow the rules on this page to break the line up to adhere +to the 80 characters per line rule. + +Breaking Long Lines +------------------- + +The ``if``, ``while``, and ``for`` control statements have their condition +expressions aligned and broken on separate lines. When the conditions have to +be broken, none go on the first line with the ``if``, ``while``, or ``for`` +statement, and none go on the last line with the closing parenthesis and the +curly brace. Long statements are broken up and indented at operators, with an +operator always being the last token on a line. No blank spaces should be left +at the end of any line. The continuation of a broken line is indented by one +level. Here is an example with a ``for`` loop. + +.. code-block:: c + + for ( initialization = statement; a + really + longish + statement + that + evaluates + to < a + boolean; another + statement ) { + some_variable = a + really + longish + statement + that + needs + two + lines + gets + indented + four + more + spaces + on + the + second + and + subsequent + lines + and + broken + up + at + operators; + } + +Should be replaced with + +.. code-block:: c + + for ( + initialization = statement; + a + really + longish + statement + that + evaluates + to < + a + boolean; + another + statement + ) { + some_variable = a + really + longish + statement + that + needs + + two + lines + gets + indented + four + more + + spaces + on + the + second + and + subsequent + + lines + and + broken + up + at + operators; + } + +Similarly, + +.. code-block:: c + + if ( this + that < those && this + these < that && this + those < these && this < those && those < that ) { + +should be broken up like + +.. code-block:: c + + if ( + this + that < those && + this + these < that && + this + those < these && + this < those && + those < that + ) { + +Note that each expression that resolves to a boolean goes on its own line. +Where you place the boolean operator is a matter of choice. + +When a line is long because of a comment at the end, move the comment to +just before the line, for example + +.. code-block:: c + + #define A_LONG_MACRO_NAME (AND + EXPANSION) /* Plus + a + really + long + comment */ + +can be replaced with + +.. code-block:: c + + /* Plus + a + really + long + comment */ + #define A_LONG_MACRO_NAME (AND + EXPANSION) + +C Preprocessor macros need to be broken up with some care, because the +preprocessor does not understand that it should eat newline characters. So + +.. code-block:: c + + #define A_LONG_MACRO_NAME (AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + DEFINED) + +would become + +.. code-block:: c + + #define A_LONG_MACRO_NAME ( \ + AND + EXCESSIVELY + LONG + EXPANSION + WITH + LOTS + OF + EXTRA + STUFF + \ + DEFINED \ + ) + +Notice that each line is terminated by a backslash. +The backslash tells the preprocessor to eat the newline. Of course, if you have +such a long macro, you should consider not using a macro. + +Function declarations can be broken up at each argument, for example + +.. code-block:: c + + int this_is_a_function( int arg1, int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8, int arg9 ); + +would be broken up as + +.. code-block:: c + + int this_is_a_function( + int arg1, + int arg2, + int arg3, + int arg4, + int arg5, + int arg6, + int arg7, + int arg8, + int arg9 + ); + +Excessively long comments should be broken up at a word boundary or somewhere +that makes sense, for example + +.. code-block:: c + + /* Excessively long comments should be broken up at a word boundary or somewhere that makes sense, for example */ + +would be + +.. code-block:: c + + /* + * Excessively long comments should be broken up at a word boundary or + * somewhere that makes sense, for example. + */ + +Note that multiline comments have a single asterisk aligned with the asterisk +in the opening ``/*``. The closing ``*/`` should appear on a line by itself at +the end. diff --git a/eng/coding-gen-patch.rst b/eng/coding-gen-patch.rst deleted file mode 100644 index 1781d89..0000000 --- a/eng/coding-gen-patch.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2018. -.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project - -Generating a Tools Patch -************************ - -.. COMMENT:TBD - Convert the following to Rest and insert into this file -.. COMMENT:TBD - https://devel.rtems.org/wiki/Developer/Coding/GenerateAPatch - -The RTEMS patches to the development tools are generated using a command like this - -.. code block:: shell - diff -N -P -r -c TOOL-original-image TOOL-with-changes >PATCHFILE - -where the options are: - -* -N and -P take care of adding and removing files (be careful not to -include junk files like file.mybackup) - -* -r tells diff to recurse through subdirectories -* -c is a context diff (easy to read for humans) -* -u is a unified diff (easy for patch to apply) - -Please look at the generated PATCHFILE and make sure it does not contain -anything you did not intend to send to the maintainers. It is easy to -accidentally leave a backup file in the modified source tree or have a -spurious change that should not be in the PATCHFILE. - -If you end up with the entire contents of a file in the patch and can't -figure out why, you may have different CR/LF scheme in the two source -files. The GNU open-source packages usually have UNIX style CR/LF. If -you edit on a Windows platform, the line terminators may have been -transformed by the editor into Windows style. diff --git a/eng/coding.rst b/eng/coding.rst index decadea..692f9aa 100644 --- a/eng/coding.rst +++ b/eng/coding.rst @@ -12,9 +12,8 @@ TBD - Write introduction, re-order, identify missing content .. toctree:: coding-conventions - coding-80cols + coding-formatting coding-deprecating coding-doxygen coding-file-hdr - coding-gen-patch coding-naming diff --git a/eng/doc-guide.rst b/eng/doc-guide.rst new file mode 100644 index 0000000..f0de23f --- /dev/null +++ b/eng/doc-guide.rst @@ -0,0 +1,79 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. _DocGuide: + +Documentation Guidelines +************************ + +Application Configuration Options +================================= + +Add at least an index entry and a label for the configuration option. Use a +pattern of ``CONFIGURE_[A-Z0-9_]+`` for the option name. Use the following +template for application configuration feature options: + +.. code-block:: rst + + .. index:: CONFIGURE_FEATURE + + .. _CONFIGURE_FEATURE: + + CONFIGURE_FEATURE + ----------------- + + CONSTANT: + ``CONFIGURE_FEATURE`` + + OPTION TYPE: + This configuration option is a boolean feature define. + + DEFAULT CONFIGURATION: + If this configuration option is undefined, then the described feature is not + enabled. + + DESCRIPTION: + In case this configuration option is defined, then feature happens. + + NOTES: + Keep the description short. Add all special cases, usage notes, error + conditions, configuration dependencies, references, etc. here to the notes. + +Use the following template for application configuration integer and +initializer options: + +.. code-block:: rst + + .. index:: CONFIGURE_VALUE + + .. _CONFIGURE_VALUE: + + CONFIGURE_VALUE + ----------------- + + CONSTANT: + ``CONFIGURE_VALUE`` + + OPTION TYPE: + This configuration option is an integer (or initializer) define. + + DEFAULT VALUE: + The default value is X. + + VALUE CONSTRAINTS: + The value of this configuration option shall satisfy all of the following + constraints: + + * It shall be greater than or equal to A. + + * It shall be less than or equal to B. + + * It shall meet C. + + DESCRIPTION: + The value of this configuration option defines the Y of Z in W. + + NOTES: + Keep the description short. Add all special cases, usage notes, error + conditions, configuration dependencies, references, etc. here to the notes. diff --git a/eng/fv/appendix-fv.rst b/eng/fv/appendix-fv.rst new file mode 100755 index 0000000..687679a --- /dev/null +++ b/eng/fv/appendix-fv.rst @@ -0,0 +1,1749 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +Appendix: RTEMS Formal Model Guide +********************************** + +This appendix covers the various formal models of RTEMS that are currently in +existence. It serves two purposes: +one is to provide detailed documentation of each model, +while the other is provide a guide into how to go about developing and deploying such models. + +The general approach followed here is to start by looking at the API documentation and identifying the key data-structures and function prototypes. +These are then modelled appropriately in Promela. +Then, general behavior patterns of interest are identified, +and the Promela model is extended to provide those patterns. +A key aspect here is exploiting the fact that Promela allows non-deterministic choices to be specified, which gives the effect of producing arbitrary orderings of model behavior. +All of this leads to a situation were the SPIN model-checker can effectively generate scenarios for all possible interleavings. +The final stage is mapping those scenarios to RTEMS C test code, +which has two parts: generating machine-readable output from SPIN, and developing the refinement mapping from that output to C test code. + +Some familiarity is assumed here with the Software Test Framework section in this document. + +The following models are included in the directory ``formal/promela/models/`` +at the top-level in ``rtems-central``: + +Chains API (``chains/``) + Models the unprotected chain append and get API calls in the Classic + Chains API Guide. This was an early model to develop the basic methodology. + +Events Manager (``events/``) + Models the behaviour of all the API calls in the Classic Events Manager API + Guide. This had to tackle real concurrency and deal with multiple CPUs and priority + issues. + +Barrier Manager (``barriers/``) + Models the behaviour of all the API calls in then Classic Barrier Manager API. + +Message Manager (``messages/``) + Models the create, send and receive API calls in the Classic Message Manager API. + +At the end of this guide is a section that discusses various issues that should be tackled in future work. + +Testing Chains +-------------- + +Documentation: Chains section in the RTEMS Classic API Guide. + +Model Directory: ``formal/promela/models/chains``. + +Model Name: ``chains-api-model``. + +The Chains API provides a doubly-linked list data-structure, optimised for fast +operations in an SMP setting. It was used as proof of concept exercise, +and focussed on just two API calls: ``rtems-chain-append-unprotected`` +and ``rtems-chain-get-unprotected`` (hereinafter just ``append`` and ``get``). + + +API Model +^^^^^^^^^ + +File: ``chains-api-model.pml`` + +While smart code optimization techniques are very important for RTEMS code, +the focus when constructing formal models is on functional correctness, +not performance. What is required is the simplest, most obviously correct model. + +The ``append`` operation adds new nodes on the end of the list, +while ``get`` removes and returns the node at the start of the list. +The Chains API has many other operations that can add/remove nodes at either end, or somewhere in the middle, but these are considered out of scope. + +Data Structures +~~~~~~~~~~~~~~~ + +There are no pointers in Promela, so we have to use arrays, +with array indices modelling pointers. +With just ``append`` and ``get``, an array can be used to implement a collection +of nodes in memory. +A ``Node`` type is defined that has next and previous indices, +plus an item payload. +Access to the node list is via a special control node with head and tail pointers. +In the model, an explicit size value is added to this control node, +to allow the writing of properties about chain length, +and to prevent array out-of-bound errors in the model itself. +We assume a single ``chain``, +with list node storage statically allocated in ``memory``. + +.. code:: c + + #define PTR_SIZE 3 + #define MEM_SIZE 8 + + typedef Node { + unsigned nxt : PTR_SIZE + ; unsigned prv : PTR_SIZE + ; byte itm + } + Node memory[MEM_SIZE] ; + + typedef Control { + unsigned head : PTR_SIZE; + unsigned tail : PTR_SIZE; + unsigned size : PTR_SIZE + } + Control chain ; + +While there are 8 memory elements, element 0 is inaccessible, +as the index 0 is treated like a ``NULL`` pointer. + +Function Calls +~~~~~~~~~~~~~~ + +The RTEMS prototype for ``append`` is: + +.. code:: c + + void rtems_chain_append_unprotected( + rtems_chain_control *the_chain, + rtems_chain_node *the_node + ); + +Its implementation starts by checking that the node to be appended is "off +chain", before performing the append. +The model is designed to satisfy this property so the check is not modelled. +Also, the Chains documentation is not clear about certain error cases. +As this is a proof of concept exercise, these details are not modelled. + +A Promela inline definition ``append`` models the desired behavior, +simulating C pointers with array addresses. Here ``ch`` is the chain argument, +while ``np`` is a node index. +The model starts by checking that the node pointer is not ``NULL``, +and that there is room in ``memory`` for another node. +These are to ensure that the model does not have any runtime errors. +Doing a standard model-check of this model finds no errors, +which indicates that those assertions are never false. + +.. code:: c + + inline append(ch,np) { + assert(np!=0); assert(ch.size < (MEM_SIZE-1)); + if + :: (ch.head == 0) -> ch.head = np; ch.tail = np; ch.size = 1; + memory[np].nxt = 0; memory[np].prv = 0; + :: (ch.head != 0) -> memory[ch.tail].nxt = np; memory[np].prv = ch.tail; + ch.tail = np; ch.size = ch.size + 1; + fi + } + +The RTEMS prototype for ``get`` is: + +.. code:: c + + rtems_chain_node *rtems_chain_get_unprotected( + rtems_chain_control *the_chain + ); + +It returns a pointer to the node, with ``NULL`` returned if the chain is empty. + +Promela inlines involve textual substitution, +so the concept of returning a value makes no sense. +For ``get``, the model is that of a statement that assigns the return value to +a variable. Both the function argument and return variable name are passed as parameters: + +.. code:: c + + /* np = get(ch); */ + inline get(ch,np) { + np = ch.head ; + if + :: (np != 0) -> + ch.head = memory[np].nxt; + ch.size = ch.size - 1; + // memory[np].nxt = 0 + :: (np == 0) -> skip + fi + if + :: (ch.head == 0) -> ch.tail = 0 + :: (ch.head != 0) -> skip + fi + } + +Behavior patterns +^^^^^^^^^^^^^^^^^ + +File: ``chains-api-model.pml`` + +A key feature of using a modelling language like Promela is that it has both +explicit and implicit non-determinism. This can be exploited so that SPIN will +find all possible interleavings of behavior. + +The Chains API model consists of six processes, three which perform ``append``, +and three that perform ``get``, waiting if the chain is empty. This model relies +on implicit non-determinism, in that the SPIN scheduler can choose and switch +between any unblocked process at any point. There is no explicit non-determinism +in this model. + +Promela process ``doAppend`` takes node index ``addr`` and a value ``val`` as +parameters. It puts ``val`` into the node indexed by ``addr``, +then calls ``append``, and terminates. +It is all made atomic to avoid unnecessary internal interleaving of operations because unprotected versions of API calls should only be used when interrupts +are disabled. + +.. code:: c + + proctype doAppend(int addr; int val) { + atomic{ memory[addr].itm = val; + append(chain,addr); } ; + } + +The ``doNonNullGet`` process waits for the chain to be non-empty before attempting to ``get`` an element. The first statement inside the atomic +construct is an expression, as a statements, that blocks while it evaluates to +zero. That only happens if ``head`` is in fact zero. The model also has an +assertion that checks that a non-null node is returned. + +.. code:: c + + proctype doNonNullGet() { + atomic{ + chain.head != 0; + get(chain,nptr); + assert(nptr != 0); + } ; + } + +All processes terminate after they have performed their (sole) action. + +The top-level of a Promela model is an initial process declared by the ``init`` construct. This initializes the chain as empty and then runs all six processes concurrently. It then uses the special ``_nr_pr`` variable to wait for all six +processes to terminate. A final assertion checks that the chain is empty. + +.. code:: c + + init { + pid nr; + chain.head = 0; chain.tail = 0; chain.size = 0 ; + nr = _nr_pr; // assignment, sets `nr` to current number of procs + run doAppend(6,21); + run doAppend(3,22); + run doAppend(4,23); + run doNonNullGet(); + run doNonNullGet(); + run doNonNullGet(); + nr == _nr_pr; // expression, waits until number of procs equals `nr` + assert (chain.size == 0); + } + +Simulation of this model will show some execution sequence in which the appends +happen in a random order, and the gets also occur in a random order, whenever +the chain is not empty. All assertions are always satisfied, including the last +one above. Model checking this model explores all possible interleavings and reports no errors of any kind. In particular, when the model reaches the last +assert statement, the chain size is always zero. + +SPIN uses the C pre-processor, and generates the model as a C program. This +model has a simple flow of control: basically execute each process once in an +almost arbitrary order, assert that the chain is empty, and terminate. Test +generation here just requires the negation of the final assertion to get all +possible interleavings. The special C pre-processor definition ``TEST_GEN`` is +used to switch between the two uses of the model. The last line above is +replaced by: + +.. code:: c + + #ifdef TEST_GEN + assert (chain.size != 0); + #else + assert (chain.size == 0); + #endif + +A test generation run can then be invoked by passing in ``-DTEST_GEN`` as a +command-line argument. + +Annotations +^^^^^^^^^^^ + +File: ``chains-api-model.pml`` + +The model needs to have ``printf`` statements added to generation the +annotations used to perform the test generation. + +This model wraps each of six API calls in its own process, so that model +checking can generate all feasible interleavings. However, the plan for the test code is that it will be just one RTEMS Task, that executes all the API +calls in the order determined by the scenario under consideration. All the +annotations in this model specify ``0`` as the Promela process identifier. + +Data Structures +~~~~~~~~~~~~~~~ + +Annotations have to be provided for any variable or datastructure declarations +that will need to have corresponding code in the test program. +These have to be printed out as the model starts to run. +For this model, the ``MAX_SIZE`` parameter is important, +as are the variables ``memory``, ``nptr``, and ``chain``: + +.. code:: c + + printf("@@@ 0 NAME Chain_AutoGen\n") + printf("@@@ 0 DEF MAX_SIZE 8\n"); + printf("@@@ 0 DCLARRAY Node memory MAX_SIZE\n"); + printf("@@@ 0 DECL unsigned nptr NULL\n") + printf("@@@ 0 DECL Control chain\n"); + +At this point, a parameter-free initialization annotation is issued. This should +be refined to C code that initializes the above variables. + +.. code:: c + + printf("@@@INIT\n"); + +Function Calls +~~~~~~~~~~~~~~ + +For ``append``, two forms of annotation are produced. One uses the ``CALL`` +format to report the function being called along with its arguments. The other +form reports the resulting contents of the chain. + +.. code:: c + + proctype doAppend(int addr; int val) { + atomic{ memory[addr].itm = val; append(chain,addr); + printf("@@@ 0 CALL append %d %d\n",val,addr); + show_chain(); + } ; + } + +The statement ``show_chain()`` is an inline function that prints the +contents of the chain after append returns. +The resulting output is multi-line, +starting with ``@@@ 0 SEQ chain``, +ending with ``@@@ 0 END chain``, +and with entries in between of the form ``@@@ 0 SCALAR _ val`` +displaying chain elements, line by line. + +Something similar is done for ``get``, with the addition of a third annotation +``show_node()`` that shows the node that was got: + +.. code:: c + + proctype doNonNullGet() { + atomic{ + chain.head != 0; + get(chain,nptr); + printf("@@@ 0 CALL getNonNull %d\n",nptr); + show_chain(); + assert(nptr != 0); + show_node(); + } ; + } + +The statement ``show_node()`` is defined as follows: + +.. code:: c + + inline show_node (){ + atomic{ + printf("@@@ 0 PTR nptr %d\n",nptr); + if + :: nptr -> printf("@@@ 0 STRUCT nptr\n"); + printf("@@@ 0 SCALAR itm %d\n", memory[nptr].itm); + printf("@@@ 0 END nptr\n") + :: else -> skip + fi + } + } + +It prints out the value of ``nptr``, which is an array index. If it is not zero, +it prints out some details of the indexed node structure. + +Annotations are also added to the ``init`` process to show the chain and node. + +.. code:: c + + chain.head = 0; chain.tail = 0; chain.size = 0; + show_chain(); + show_node(); + +Refinement +^^^^^^^^^^ + +Files: + + ``chains-api-model-rfn.yml`` + + ``chains-api-model-pre.h`` + + ``tr-chains-api-model.c`` + +Model annotations are converted to C test code using a YAML file that maps +single names to test code snippets into which parameters can be substituted. +Parameters are numbered from zero, and the ``n`` th parameter will be substituted +wherever ``{n}`` occurs in the snippet. + +Refinement is more than just the above mapping from annotations to code. Some of +this code will refer to C variables, structures, and functions that are needed +to support the test. Some of these are declared ``chains-api-model-pre.h`` and implemented in ``tr-chains-api-model.c``. + +Data Structures +~~~~~~~~~~~~~~~ + +The initialization generates one each of ``NAME``, ``DEF``, ``DCLARRAY``, and +``INIT`` annotations, and two ``DECL`` annotations. + +The ``DEF`` entry is currently not looked up as it is automatically converted to a ``#define``. + +The ``NAME`` annotation is used to declare the test case name, which is +stored in the global variable ``rtems_test_name``. The current +refinement entry is: + +.. code:: python + + NAME: | + const char rtems_test_name[] = "Model_Chain_API"; + +In this case, the name is fixed and ignores what is declared in the model. + +The ``DCLARRAY Node memory MAX_SIZE`` annotation looks up ``memory_DCL`` in the +refinement file, passing in ``memory`` and ``MAX_SIZE`` as arguments. The entry in the refinement file is: + +.. code:: python + + memory_DCL: item {0}[{1}]; + +Here ``item`` is the type of the chains nodes used in the test code. It is +declared in ``chains-api-model.pre.h`` as: + +.. code:: c + + typedef struct item + { + rtems_chain_node node; + int val; + } item; + +Substituting the arguments gives: + +.. code:: c + + item memory[MAX_SIZE]; + +The two ``DECL`` annotations have two or three parameters. The first is the +type, the second is the variable name, and the optional third is an initial +value. The lookup key is the variable name with ``_DCL`` added on. +In the refinement file, the entry only provides the C type, and the other parts of the declaration are added in. +The entries are: + +.. code:: python + + nptr_DCL: item * + chain_DCL: rtems_chain_control + +Annotation ``DECL unsigned nptr NULL`` results in: + +.. code:: c + + item * nptr = NULL ; + +Annotation ``DECL Control chain`` results in: + +.. code:: c + + rtems_chain_control chain ; + +The ``INIT`` annotation is looked up as ``INIT`` itself. It should be mapped to +code that does all necessary initialization. The refinement entry for chains is: + +.. code:: python + + INIT: rtems_chain_initialize_empty( &chain ); + +In addition to all the above dealing with declarations and initialization, +there are the annotations, already described above, that are used to display +composite values, such as structure contents, and chain contents. + +In the model, all accesses to individual chain nodes are via index ``nptr``, +which occurs in two types of annotations, ``PTR`` and ``STRUCT``. The ``PTR`` +annotation is refined by looking up ``nptr_PTR`` with the value of ``nptr`` as the sole argument. The refinement entry is: + +.. code:: python + + nptr_PTR: | + T_eq_ptr( nptr, NULL ); + T_eq_ptr( nptr, &memory[{0}] ); + +The first line is used if the value of ``nptr`` is zero, otherwise the second +line is used. + +The use of ``STRUCT`` requires three annotation lines in a row, *e.g.*: + +.. code:: c + + @@@ 0 STRUCT nptr + @@@ 0 SCALAR itm 21 + @@@ 0 END nptr + +The ``STRUCT`` and ``END`` annotations do not generate any code, but open and +close a scope in which ``nptr`` is noted as the "name" of the struct. The +``SCALAR`` annotation is used to observe simple values such as numbers or booleans. However, within a ``STRUCT`` it belongs to a C ``struct``, so the +relevant field needs to be used to access the value. +Within this scope, the scalar variable ``itm`` is looked up as a field name, +by searching for ``itm_FSCALAR`` with arguments``nptr`` and ``21``, which returns the entry: + +.. code:: python + + itm_FSCALAR: T_eq_int( {0}->val, {1} ); + +This gets turned into the following test: + +.. code:: c + + T_eq_int( nptr->val, 21 ); + +A similar idea is used to test the contents of a chain. The annotations produced +start with a ``SEQ`` annotation, followed by a ``SCALAR`` annotation for each +item in the chain, and then ending with an ``END`` annotation. Again, there is +a scope defined where the ``SEQ`` argument is the "name" of the sequence. +The ``SCALAR`` entries have no name here (indicated by ``_``), and their values +are accumulated in a string, separated by spaces. Test code generation is +triggered this time by the ``END`` annotation, that looks up the "name" with ``_SEQ`` appended, and the accumulated string as an argument. The corresponding entry for chain sequences is: + +.. code:: python + + chain_SEQ: | + show_chain( &chain, ctx->buffer ); + T_eq_str( ctx->buffer, "{0} 0" ); + +So, the following chain annotation sequence: + +.. code:: c + + @@@ 0 SEQ chain + @@@ 0 SCALAR _ 21 + @@@ 0 SCALAR _ 22 + @@@ 0 END chain + +becomes the following C code: + +.. code:: C + + show_chain( &chain, ctx->buffer ); + T_eq_str( ctx->buffer, " 21 22 0" ); + +C function ``show_chain()`` is defined in ``tr-chains-api-model.c`` and +generates a string with exactly the same format as that produced above. These +are then compared for equality. + +.. note:: + + The Promela/SPIN model checker's prime focus is modelling and verifying + concurrency related properties. It is not intended for verifying sequential + code or data transformations. This is why some of the ``STRUCT``/``SEQ`` + material here is so clumsy. It plays virtually no role in the other models. + +Function Calls +~~~~~~~~~~~~~~ + +For ``@@@ 0 CALL append 22 3`` lookup ``append`` to get + +.. code-block:: c + + memory[{1}].val = {0}; + rtems_chain_append_unprotected( &chain, (rtems_chain_node*)&memory[{1}] ); + +Substitute ``22`` and ``3`` in to produce + +.. code-block:: c + + memory[3].val = 22; + rtems_chain_append_unprotected( &chain, (rtems_chain_node*)&memory[3] ); + +For ``@@@ 0 CALL getNonNull 3`` lookup ``getNonNull`` to obtain + +.. code:: c + + nptr = get_item( &chain ); + T_eq_ptr( nptr, &memory[{0}] ); + +Function ``get_item()`` is defined in ``tc-chains-api-model.c`` and calls ``rtems_chain_get_unprotected()``. Substitute ``3`` to produce: + +.. code:: c + + nptr = get_item( &chain ); + T_eq_ptr( nptr, &memory[3] ); + +Testing Concurrent Managers +--------------------------- + +All the other models are of Managers that provide some form of communication +between multiple RTEMS Tasks. This introduces a number of issues regarding +the timing and control of tasks, particularly when developing *reproducible* +tests, where the sequencing of behavior is the same every time the test runs. +The tests are generated by following the schemes already in use for regular +RTEMS handwritten tests. +In particular the pre-existing tests for Send and Receive in the Event Manager +where used as a guide. + +Testing Strategy +^^^^^^^^^^^^^^^^ + +The tests are organized as follows: + +1. A designated Task, the Runner, is responsible for initializing, + coordinating and tearing down a test run. + Coordination involves starting other Worker Tasks that perform tests, + and waiting for them to complete. + It may also run some tests itself. + +1. One or more Worker Tasks are used to perform test actions. + +1. Each RTEMS Task (Runner/Worker) is modelled by one Promela process. + +1. Simple Binary Semaphores + are used to coordinate all the tasks to ensure + that the interleaving is always the same + (See Semaphore Manager section in Classic API Manual). + +1. Two other Promela processes are required: + One, called ``Clock()`` is used to model timing and timeouts; + The other, called ``System()`` models relevant behavior of the RTEMS scheduler. + +Model Structure +^^^^^^^^^^^^^^^ + +All the models developed so far are based on this framework. +The structure of these models takes the following form: + + Constant Declarations + Mainly ``#define``\ s that define important constants. + + Datastructure Definitions + Promela ``typedef``\ s that describe key forms of data. + In particular there is a type ``Task`` that models RTEMS Tasks. + The Simple Binary Semaphores are modelled as boolean variables. + + Global Variable Declarations + Typically these are arrays of data-structures, + representing objects such as tasks or semaphores. + + Supporting Models + These are ``inline`` definitions that capture common behavior. + In all models this includes ``Obtain()`` and ``Release()`` to model semaphores, + and ``waitUntilReady()`` that models a blocked task waiting to be unblocked. + Included here are other definitions specific to the particular Manager being + modelled. + + API Models + These are ``inline`` definitions that model the behavior of each API call. + All behavior must be modelled, including bad calls that (should) result in + an error code being returned. + The parameter lists used in the Promela models will differ from those + of the actual API calls. + Consider a hypothetical RTEMS API call: + + .. code:: c + + rc = rtems_some_api(arg1,arg2,...,argN); + + One reason, common to all calls, is that the ``inline`` construct has + no concept of returning a value, + so a variable parameter has to be added to represent it, + and it has to be ensured the appropriate return code is assigned to it. + + .. code:: promela + + inline some_api(arg1,arg2,...,argN,rc) { + ... + rc = RC_some_code + } + + Another reason is that some RTEMS types encode a number of different + concepts in a single machine word. + The most notable of these is the ``rtems_options`` type, + that specifies various options, usually for calls that may block. + In some models, some options are modelled individually, for clarity. + So the API model may have two or more parameters where the RTEMS call has one. + + .. code:: promela + + inline some_api(arg1,arg2feat1,arg2feat2,...,argN,rc) { + ... + rc = RC_some_code + } + + The refinement of this will pass the multiple feature arguments to + a C function that will assemble the single RTEMS argument. + + A third reason is that sometimes it is important to also provide + the process id of the *calling* task. This can be important where + priority and preemption are involved. + + Scenario Generation + A Testsuite that exercises *all* the API code is highly desirable. + This requires running tests that explore a wide range of scenarios, + normally devised by hand when writing a testsuite. + With Promela/SPIN, the model-checker can generate all of these simplify + as a result of its exhaustive search of the model. + In practice, scenarios fall into a number of high-level categories, + so the first step is make a random choice of such a category. + Within a category there may be further choices to be done. + A collection of global scenario variables are used to records the choices made. + This is all managed by inline ``chooseScenario()``. + + RTEMS Test Task Modelling + This is a series of Promela ``proctype``\ s, one for the Runner Task, + and one for each of the Worker Tasks. + Their behavior is controlled by the global scenario variables. + + System Modelling + These are Promela processes that model relevant underlying RTEMS behavior, + such as the scheduler (``System()``) and timers (``Clock()``). + + Model Main Process + Called ``init``, this initialises variables, invokes ``chooseScenario()``, + runs all the processes, waits for them to terminate, + and then terminates itself. + +The Promela models developed so far for these Managers always terminate. +The last few lines of each are of the form: + +.. code:: promela + + #ifdef TEST_GEN + assert(false); + #endif + +If these models are run in the usual way (simulation or verification), +then a correct verified model is observed. +If ``-DTEST_GEN`` is provided as the first command-line argument, +in verification mode configured to find *all* counterexamples, +then all the possible (correct) behaviours of the system will be generated. + +Transforming Model Behavior to C Code +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As described earlier, ``printf`` statements are used +to produce easy to parse output that makes +model events and outcomes easy to identify and process. +The YAML file used to define the refinement from model to code +provides a way of looking up an observation with arguments, +and then obtaining a C template that can be populated with those arguments. + +This refinement is a bridge between two distinct worlds: + + Model World: + where the key focus is on correctness and clarity. + + Code World: + where clarity is often sacrificed for efficiency. + +This means that the model-to-code relationship +need not be a simple one-to-one mapping. +This has already been alluded to above when the need for extra parameters +in API call models was discussed. +It can also be helpful when the model is better treating various attributes +separately, while the code handles those attributes packed into machine words. + +It is always reasonable to add test support code to the C test sources, +and this can include C functions that map distinct attribute values +down into some compact merged representation. + + +Testing the Event Manager +------------------------- + +Documentation: Event Manager section in the RTEMS Classic API Guide. + +Model Directory: ``formal/promela/models/events``. + +Model Name: ``event-mgr-model``. + +The Event Manager allows tasks to send events to, +and receive events from, other tasks. +From the perspective of the Event Manager, +events are just uninterpreted numbers in the range 0..31, +encoded as a 32-bit bitset. + +``rtems_event_send(id,event_in)`` + allows a task to send a bitset to a designated task + +``rtems_event_receive(event_in,option_set,ticks,event_out)`` + allows a task to specify a desired bitset + with options on what to do if it is not present. + +Most of the requirements are pretty straightforward, +but two were a little more complex, +and drove the more complex parts of the modelling. + +1. If a task was blocked waiting to receive events, + and a lower priority task then sent the events that would wake that + blocked task, + then the sending task would be immediately preempted by the receiver task. + +2. There was a requirement that explicitly discussed the situation + where the two tasks involved were running on different processors. + +A preliminary incomplete model of the Event Manager was originally developed +by the consortium early in the project. The model was then completed during +the rest of the activity by a Masters student: :cite:`Jennings:2021:FV`. +They also developed the first iteration of the ``testbuilder`` program. + +API Model +^^^^^^^^^ + +File: ``event-mgr-model.pml`` + +The RTEMS Event set contains 32 values, but in the model limits this to +just four, which is enough for test purposes. +Some inline definitions are provided to encode (``events``), display +(``printevents``), and subtract (``setminus``) events. + +The ``rtems_option_set`` is simplifiedto just two relevant bits: the timeout +setting (``Wait``, ``NoWait``), and how much of the desired event set will +satisfy the receiver (``All``, ``Any``). +These are passed in as two separate arguments to the model of the receive call. + +Event Send +~~~~~~~~~~ + +An RTEMS call ``rc = rtems_event_send(tid,evts)`` is modelled by an inline of +the form: + +.. code-block:: c + + event_send(self,tid,evts,rc) + +The four arguments are: + | ``self`` : id of process modelling the task/IDR making call. + | ``tid`` : id of process modelling the target task of the call. + | ``evts`` : event set being sent. + | ``rc`` : updated with the return code when the send completes. + +The main complication in the otherwise straightforward model is the requirement +to preempt under certain circumstances. + +.. code-block:: c + + inline event_send(self,tid,evts,rc) { + atomic{ + if + :: tid >= BAD_ID -> rc = RC_InvId + :: tid < BAD_ID -> + tasks[tid].pending = tasks[tid].pending | evts + // at this point, have we woken the target task? + unsigned got : NO_OF_EVENTS; + bool sat; + satisfied(tasks[tid],got,sat); + if + :: sat -> + tasks[tid].state = Ready; + printf("@@@ %d STATE %d Ready\n",_pid,tid) + preemptIfRequired(self,tid) ; + // tasks[self].state may now be OtherWait ! + waitUntilReady(self); + :: else -> skip + fi + rc = RC_OK; + fi + } + } + +Three inline abstractions are used: + +``satisfied(task,out,sat)`` + updates ``out`` with the wanted events received so far, and then checks if a receive has been satisfied. It + updates its ``sat`` argument to reflect the check outcome. + +``preemptIfRequired(self,tid)`` + forces the sending process to enter the ``OtherWait``, + if circumstances require it. + +``waitUntilReady(self)`` + basically waits for the process state to become ``Ready``. + +Event Receive +~~~~~~~~~~~~~ + +An RTEMS call ``rc = rtems_event_receive(evts,opts,interval,out)`` is modelled +by an inline of +the form: + +.. code-block:: c + + event_receive(self,evts,wait,wantall,interval,out,rc) + +The seven arguments are: + | ``self`` : id of process modelling the task making call + | ``evts`` : input event set + | ``wait`` : true if receive should wait + | ``what`` : all, or some? + | ``interval`` : wait interval (0 waits forever) + | ``out`` : pointer to location for satisfying events when the receive + completes. + | ``rc`` : updated with the return code when the receive completes. + + +There is a small complication, in that there are distinct variables in the model +for receiver options that are combined into a single RTEMS option set. The +actual calling sequence in C test code will be: + +.. code-block:: c + + opts = mergeopts(wait,wantall); + rc = rtems_event_receive(evts,opts,interval,out); + +Here ``mergeopts`` is a C function defined in the C Preamble. + +.. code-block:: c + + inline event_receive(self,evts,wait,wantall,interval,out,rc){ + atomic{ + printf("@@@ %d LOG pending[%d] = ",_pid,self); + printevents(tasks[self].pending); nl(); + tasks[self].wanted = evts; + tasks[self].all = wantall + if + :: out == 0 -> + printf("@@@ %d LOG Receive NULL out.\n",_pid); + rc = RC_InvAddr ; + :: evts == EVTS_PENDING -> + printf("@@@ %d LOG Receive Pending.\n",_pid); + recout[out] = tasks[self].pending; + rc = RC_OK + :: else -> + bool sat; + retry: satisfied(tasks[self],recout[out],sat); + if + :: sat -> + printf("@@@ %d LOG Receive Satisfied!\n",_pid); + setminus(tasks[self].pending,tasks[self].pending,recout[out]); + printf("@@@ %d LOG pending'[%d] = ",_pid,self); + printevents(tasks[self].pending); nl(); + rc = RC_OK; + :: !sat && !wait -> + printf("@@@ %d LOG Receive Not Satisfied (no wait)\n",_pid); + rc = RC_Unsat; + :: !sat && wait && interval > 0 -> + printf("@@@ %d LOG Receive Not Satisfied (timeout %d)\n",_pid,interval); + tasks[self].ticks = interval; + tasks[self].tout = false; + tasks[self].state = TimeWait; + printf("@@@ %d STATE %d TimeWait %d\n",_pid,self,interval) + waitUntilReady(self); + if + :: tasks[self].tout -> rc = RC_Timeout + :: else -> goto retry + fi + :: else -> // !sat && wait && interval <= 0 + printf("@@@ %d LOG Receive Not Satisfied (wait).\n",_pid); + tasks[self].state = EventWait; + printf("@@@ %d STATE %d EventWait\n",_pid,self) + if + :: sendTwice && !sentFirst -> Released(sendSema); + :: else + fi + waitUntilReady(self); + goto retry + fi + fi + printf("@@@ %d LOG pending'[%d] = ",_pid,self); + printevents(tasks[self].pending); nl(); + } + } + +Here ``satisfied()`` and ``waitUntilReady()`` are also used. + +Behaviour Patterns +^^^^^^^^^^^^^^^^^^ + +File: ``event-mgr-model.pml`` + +The Event Manager model consists of +five Promela processes: + +``init`` + The first top-level Promela process that performs initialisation, + starts the other processes, waits for them to terminate, and finishes. + +``System`` + A Promela process that models the behaviour of the operating system, + in particular that of the scheduler. + +``Clock`` + A Promela process used to facilitate modelling timeouts. + +``Receiver`` + The Promela process modelling the test Runner, + that also invokes the receive API call. + +``Sender`` + A Promela process modelling a singe test Worker + that invokes the send API call. + + +Two simple binary semaphores are used to synchronise the tasks. + +The Task model only looks at an abstracted version of RTEMS Task states: + +``Zombie`` + used to model a task that has just terminated. It can only be deleted. + +``Ready`` + same as the RTEMS notion of ``Ready``. + +``EventWait`` + is ``Blocked`` inside a call of ``event_receive()`` with no timeout. + +``TimeWait`` + is ``Blocked`` inside a call of ``event_receive()`` with a timeout. + +``OtherWait`` + is ``Blocked`` for some other reason, which arises in this model when a + sender gets pre-empted by a higher priority receiver it has just satisfied. + + +Tasks are represented using a datastructure array. +As array indices are proxies here for C pointers, +the zeroth array entry is always unused, +as index value 0 is used to model a NULL C pointer. + +.. code-block:: c + + typedef Task { + byte nodeid; // So we can spot remote calls + byte pmlid; // Promela process id + mtype state ; // {Ready,EventWait,TickWait,OtherWait} + bool preemptable ; + byte prio ; // lower number is higher priority + int ticks; // + bool tout; // true if woken by a timeout + unsigned wanted : NO_OF_EVENTS ; // EvtSet, those expected by receiver + unsigned pending : NO_OF_EVENTS ; // EvtSet, those already received + bool all; // Do we want All? + }; + Task tasks[TASK_MAX]; // tasks[0] models a NULL dereference + +.. code-block:: c + + byte sendrc; // Sender global variable + byte recrc; // Receiver global variable + byte recout[TASK_MAX] ; // models receive 'out' location. + +Task Scheduling +~~~~~~~~~~~~~~~ + +In order to produce a model that captures real RTEMS Task behaviour, +there need to be mechanisms that mimic the behaviour of the scheduler and other +activities that can modify the execution state of these Tasks. Given a scenario +generated by such a model, synchronisation needs to be added to the generated C +code to ensure test has the same execution patterns. + +Relevant scheduling behavior is modelled by two inlines that have already +been mentioned: ``waitUntilReady()`` and ``preemptIfRequired()``. + +For synchronisation, simple boolean semaphores are used, where True means +available, and False means the semaphore has been acquired. + +.. code-block:: c + + bool semaphore[SEMA_MAX]; // Semaphore + +The synchronisation mechanisms are: + + +``Obtain(sem_id)`` + call that waits to obtain semaphore ``sem_id``. + +``Release(sem_id)`` + call that releases semaphore ``sem_id`` + +``Released(sem_id)`` + simulates ecosystem behaviour that releases ``sem_id``. + +The difference between ``Release`` and ``Released`` is that the first issues +a ``SIGNAL`` annotation, while the second does not. + + +Scenarios +~~~~~~~~~ + +A number of different scenario schemes were defined +that cover various aspects of +Event Manager behaviour. Some schemes involve only one task, and are usually +used to test error-handling or abnormal situations. Other schemes involve two +tasks, with some mixture of event sending and receiving, with varying task +priorities. + +For example, an event send operation can involve a target identifier that +is invalid (``BAD_ID``), correctly identifies a receiver task (``RCV_ID``), or +is sending events to itself (``SEND_ID``). + +.. code-block:: c + + typedef SendInputs { + byte target_id ; + unsigned send_evts : NO_OF_EVENTS ; + } ; + SendInputs send_in[MAX_STEPS]; + +An event receive operation will be determined by values for desired events, +and the relevant to bits of the option-set parameter. + +.. code-block:: c + + typedef ReceiveInputs { + unsigned receive_evts : NO_OF_EVENTS ; + bool will_wait; + bool everything; + byte wait_length; + }; + ReceiveInputs receive_in[MAX_STEPS]; + +There is a range of global variables that define scenarios for both send and +receive. This defines a two-step process for choosing a scenario. +The first step is to select a scenario scheme. The possible schemes are +defined by the following ``mtype``: + +.. code-block:: c + + mtype = {Send,Receive,SndRcv,RcvSnd,SndRcvSnd,SndPre,MultiCore}; + mtype scenario; + +One of these is chosen by using a conditional where all alternatives are +executable, so behaving as a non-deterministic choice of one of them. + +.. code-block:: c + + if + :: scenario = Send; + :: scenario = Receive; + :: scenario = SndRcv; + :: scenario = SndPre; + :: scenario = SndRcvSnd; + :: scenario = MultiCore; + fi + + +Once the value of ``scenario`` is chosen, it is used in another conditional +to select a non-deterministic choice of the finer details of that scenario. + +.. code-block:: c + + if + :: scenario == Send -> + doReceive = false; + sendTarget = BAD_ID; + :: scenario == Receive -> + doSend = false + if + :: rcvWait = false + :: rcvWait = true; rcvInterval = 4 + :: rcvOut = 0; + fi + printf( "@@@ %d LOG sub-senario wait:%d interval:%d, out:%d\n", + _pid, rcvWait, rcvInterval, rcvOut ) + :: scenario == SndRcv -> + if + :: sendEvents = 14; // {1,1,1,0} + :: sendEvents = 11; // {1,0,1,1} + fi + printf( "@@@ %d LOG sub-senario send-receive events:%d\n", + _pid, sendEvents ) + :: scenario == SndPre -> + sendPrio = 3; + sendPreempt = true; + startSema = rcvSema; + printf( "@@@ %d LOG sub-senario send-preemptable events:%d\n", + _pid, sendEvents ) + :: scenario == SndRcvSnd -> + sendEvents1 = 2; // {0,0,1,0} + sendEvents2 = 8; // {1,0,0,0} + sendEvents = sendEvents1; + sendTwice = true; + printf( "@@@ %d LOG sub-senario send-receive-send events:%d\n", + _pid, sendEvents ) + :: scenario == MultiCore -> + multicore = true; + sendCore = 1; + printf( "@@@ %d LOG sub-senario multicore send-receive events:%d\n", + _pid, sendEvents ) + :: else // go with defaults + fi + +Ddefault values are defined for all the global scenario variables so that the +above code focusses on what differs. The default scenario is a receiver waiting +for a sender of the same priority which sends exactly what was requested. + +Sender Process (Worker Task) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sender process then uses the scenario configuration to determine its +behaviour. A key feature is the way it acquires its semaphore before doing a +send, and releases the receiver semaphore when it has just finished sending. +Both these semaphores are initialised in the unavailable state. + +.. code-block:: c + + proctype Sender (byte nid, taskid) { + + tasks[taskid].nodeid = nid; + tasks[taskid].pmlid = _pid; + tasks[taskid].prio = sendPrio; + tasks[taskid].preemptable = sendPreempt; + tasks[taskid].state = Ready; + printf("@@@ %d TASK Worker\n",_pid); + if + :: multicore -> + // printf("@@@ %d CALL OtherScheduler %d\n", _pid, sendCore); + printf("@@@ %d CALL SetProcessor %d\n", _pid, sendCore); + :: else + fi + if + :: sendPrio > rcvPrio -> printf("@@@ %d CALL LowerPriority\n", _pid); + :: sendPrio == rcvPrio -> printf("@@@ %d CALL EqualPriority\n", _pid); + :: sendPrio < rcvPrio -> printf("@@@ %d CALL HigherPriority\n", _pid); + :: else + fi + repeat: + Obtain(sendSema); + if + :: doSend -> + if + :: !sentFirst -> printf("@@@ %d CALL StartLog\n",_pid); + :: else + fi + printf("@@@ %d CALL event_send %d %d %d sendrc\n",_pid,taskid,sendTarget,sendEvents); + if + :: sendPreempt && !sentFirst -> printf("@@@ %d CALL CheckPreemption\n",_pid); + :: !sendPreempt && !sentFirst -> printf("@@@ %d CALL CheckNoPreemption\n",_pid); + :: else + fi + event_send(taskid,sendTarget,sendEvents,sendrc); + printf("@@@ %d SCALAR sendrc %d\n",_pid,sendrc); + :: else + fi + Release(rcvSema); + if + :: sendTwice && !sentFirst -> + sentFirst = true; + sendEvents = sendEvents2; + goto repeat; + :: else + fi + printf("@@@ %d LOG Sender %d finished\n",_pid,taskid); + tasks[taskid].state = Zombie; + printf("@@@ %d STATE %d Zombie\n",_pid,taskid) + } + +Receiver Process (Runner Task) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The receiver process uses the scenario configuration to determine its +behaviour. It has the responsibility to trigger the start semaphore to allow +either itself or the sender to start. The start semaphore corresponds to either +the send or receive semaphore, depending on the scenario. The receiver acquires +the receive semaphore before proceeding, and releases the send sempahore when +done. + +.. code-block:: c + + proctype Receiver (byte nid, taskid) { + + tasks[taskid].nodeid = nid; + tasks[taskid].pmlid = _pid; + tasks[taskid].prio = rcvPrio; + tasks[taskid].preemptable = false; + tasks[taskid].state = Ready; + printf("@@@ %d TASK Runner\n",_pid,taskid); + if + :: multicore -> + printf("@@@ %d CALL SetProcessor %d\n", _pid, rcvCore); + :: else + fi + Release(startSema); // make sure stuff starts */ + /* printf("@@@ %d LOG Receiver Task %d running on Node %d\n",_pid,taskid,nid); */ + Obtain(rcvSema); + + // If the receiver is higher priority then it will be running + // The sender is either blocked waiting for its semaphore + // or because it is lower priority. + // A high priority receiver needs to release the sender now, before it + // gets blocked on its own event receive. + if + :: rcvPrio < sendPrio -> Release(sendSema); // Release send semaphore for preemption + :: else + fi + if + :: doReceive -> + printf("@@@ %d SCALAR pending %d %d\n",_pid,taskid,tasks[taskid].pending); + if + :: sendTwice && !sentFirst -> Release(sendSema) + :: else + fi + printf("@@@ %d CALL event_receive %d %d %d %d %d recrc\n", + _pid,rcvEvents,rcvWait,rcvAll,rcvInterval,rcvOut); + /* (self, evts, when, what, ticks, out, rc) */ + event_receive(taskid,rcvEvents,rcvWait,rcvAll,rcvInterval,rcvOut,recrc); + printf("@@@ %d SCALAR recrc %d\n",_pid,recrc); + if + :: rcvOut > 0 -> + printf("@@@ %d SCALAR recout %d %d\n",_pid,rcvOut,recout[rcvOut]); + :: else + fi + printf("@@@ %d SCALAR pending %d %d\n",_pid,taskid,tasks[taskid].pending); + :: else + fi + Release(sendSema); + printf("@@@ %d LOG Receiver %d finished\n",_pid,taskid); + tasks[taskid].state = Zombie; + printf("@@@ %d STATE %d Zombie\n",_pid,taskid) + } + +System Process +~~~~~~~~~~~~~~ + + A process is needed that periodically wakes up blocked processes. + This is modelling background behaviour of the system, + such as ISRs and scheduling. + All tasks are visited in round-robin order (to prevent starvation) + and are made ready if waiting on other things. Tasks waiting for events or timeouts are not touched. This terminates when all tasks are zombies. + +.. code-block:: c + + proctype System () { + byte taskid ; + bool liveSeen; + printf("@@@ %d LOG System running...\n",_pid); + loop: + taskid = 1; + liveSeen = false; + printf("@@@ %d LOG Loop through tasks...\n",_pid); + atomic { + printf("@@@ %d LOG Scenario is ",_pid); + printm(scenario); nl(); + } + do // while taskid < TASK_MAX .... + :: taskid == TASK_MAX -> break; + :: else -> + atomic { + printf("@@@ %d LOG Task %d state is ",_pid,taskid); + printm(tasks[taskid].state); nl() + } + if + :: tasks[taskid].state == Zombie -> taskid++ + :: else -> + if + :: tasks[taskid].state == OtherWait + -> tasks[taskid].state = Ready + printf("@@@ %d STATE %d Ready\n",_pid,taskid) + :: else -> skip + fi + liveSeen = true; + taskid++ + fi + od + printf("@@@ %d LOG ...all visited, live:%d\n",_pid,liveSeen); + if + :: liveSeen -> goto loop + :: else + fi + printf("@@@ %d LOG All are Zombies, game over.\n",_pid); + stopclock = true; + } + +Clock Process +~~~~~~~~~~~~~ + +A process is needed that handles a clock tick, +by decrementing the tick count for tasks waiting on a timeout. +Such a task whose ticks become zero is then made ``Ready``, +and its timer status is flagged as a timeout. This terminates when all +tasks are zombies (as signalled by ``System()`` via ``stopclock``). + +.. code-block:: c + + proctype Clock () { + int tid, tix; + printf("@@@ %d LOG Clock Started\n",_pid) + do + :: stopclock -> goto stopped + :: !stopclock -> + printf(" (tick) \n"); + tid = 1; + do + :: tid == TASK_MAX -> break + :: else -> + atomic{ + printf("Clock: tid=%d, state=",tid); + printm(tasks[tid].state); nl() + }; + if + :: tasks[tid].state == TimeWait -> + tix = tasks[tid].ticks - 1; + if + :: tix == 0 + tasks[tid].tout = true + tasks[tid].state = Ready + printf("@@@ %d STATE %d Ready\n",_pid,tid) + :: else + tasks[tid].ticks = tix + fi + :: else // state != TimeWait + fi + tid = tid + 1 + od + od + stopped: + printf("@@@ %d LOG Clock Stopped\n",_pid); + } + + +init Process +~~~~~~~~~~~~ + +The initial process outputs annotations for defines and declarations, +generates a scenario non-deterministically and then starts the system, clock +and send and receive processes running. It then waits for those to complete, +and them, if test generation is underway, asserts ``false`` to trigger a +seach for counterexamples: + +.. code-block:: c + + init { + pid nr; + printf("@@@ %d NAME Event_Manager_TestGen\n",_pid) + outputDefines(); + outputDeclarations(); + printf("@@@ %d INIT\n",_pid); + chooseScenario(); + run System(); + run Clock(); + run Sender(THIS_NODE,SEND_ID); + run Receiver(THIS_NODE,RCV_ID); + _nr_pr == 1; + #ifdef TEST_GEN + assert(false); + #endif + } + +The information regarding when tasks should wait and/or restart +can be obtained by tracking the process identifiers, +and noting when they change. +The ``spin2test`` program does this, +and also produces separate test code segments for each Promela process. + +Annotations +^^^^^^^^^^^ + +File: ``event-mgr-model.pml`` + +Nothing more to say here. + +Refinement +^^^^^^^^^^ + +File: ``event-mgr-model-rfn.yml`` + + +The test-code generated here is based on the test-code generated from the +specification items used to describe the Event Manager in the main (non-formal) +part of the new qualification material. + +The relevant specification item is ``spec/rtems/event/req/send-receive.yml`` +found in ``rtems-central``. The corresponding C test code is +``tr-event-send-receive.c`` found in ``rtems`` at ``testsuites/validation``. +That automatically generated C code is a single file that uses a set of deeply +nested loops to iterate through the scenarios it generates. + +The approach here is to generate a stand-alone C code file for each scenario +(``tr-event-mgr-model-N.c`` for ``N`` in range 0..8.) + + +The ``TASK`` annotations issued by the ``Sender`` and ``Receiver`` processes +lookup the following refinement entries, to get code that tests that the C +code Task does correspond to what is being defined in the model. + +.. code-block:: yaml + + Runner: | + checkTaskIs( ctx->runner_id ); + + Worker: | + checkTaskIs( ctx->worker_id ); + +The ``WAIT`` and ``SIGNAL`` annotations produced by ``Obtain()`` and +``Release()`` respectively, are mapped to the corresponding operations on +RTEMS semaphores in the test code. + +.. code-block:: yaml + + code content + SIGNAL: | + Wakeup( semaphore[{}] ); + + WAIT: | + Wait( semaphore[{}] ); + +Some of the ``CALL`` annotations are used to do more complex test setup +involving priorities, or other processors and schedulers. For example: + +.. code-block:: yaml + + HigherPriority: | + SetSelfPriority( PRIO_HIGH ); + rtems_task_priority prio; + rtems_status_code sc; + sc = rtems_task_set_priority( RTEMS_SELF, RTEMS_CURRENT_PRIORITY, &prio ); + T_rsc_success( sc ); + T_eq_u32( prio, PRIO_HIGH ); + + SetProcessor: | + T_ge_u32( rtems_scheduler_get_processor_maximum(), 2 ); + uint32_t processor = {}; + cpu_set_t cpuset; + CPU_ZERO(&cpuset); + CPU_SET(processor, &cpuset); + +Some handle more complicated test outcomes, such as observing context-switches: + +.. code-block:: yaml + + CheckPreemption: | + log = &ctx->thread_switch_log; + T_eq_sz( log->header.recorded, 2 ); + T_eq_u32( log->events[ 0 ].heir, ctx->runner_id ); + T_eq_u32( log->events[ 1 ].heir, ctx->worker_id ); + +Most of the other refinement entries are similar to those described above for +the Chains API. + +Testing the Barrier Mananger +---------------------------- + +Documentation: Barrier Manager section in the RTEMS Classic API Guide. + +Model Directory: ``formal/promela/models/barriers``. + +Model Name: ``barrier-mgr-model``. + +The Barrier Manager is used to arrange for a number of tasks to wait on a +designated barrier object, until either another task releases them, or a +given number of tasks are waiting, at which point they are all released. + +All five directives were modelled: + +* ``rtems_barrier_create()`` + +* ``rtems_barrier_ident()`` + +* ``rtems_barrier_delete()`` + +* ``rtems_barrier_wait()`` + +* ``rtems_barrier_release()`` + +Barriers can be manual (released only by a call to ``..release()``), +or automatic (released by the call to ``..wait()`` that results in a wait count limit being reached.) +There is no notion of queuing in this manager, +only waiting for a barrier to be released. + +This model was developed by a Masters student :cite:`Jaskuc:2022:TESTGEN`, +using the Event Manager as a model. It was added into the QDP produced by +the follow-on IV&V activity. + +API Model +^^^^^^^^^ + +File: ``barrier-mgr-model.pml`` + +Modelling waiting is much easier than modelling queueing. +All that is required is an array of booleans (``waiters``), indexed by process id: + +.. code:: promela + + typedef Barrier { + byte b_name; // barrier name + bool isAutomatic; // true for automatic, false for manual barrier + int maxWaiters; // maximum count of waiters for automatic barrier + int waiterCount; // current amount of tasks waiting on the barrier + bool waiters[TASK_MAX]; // waiters on the barrier + bool isInitialised; // indicated whenever this barrier was created + } + +The name ``satisfied`` is currently used here for an inline that checks when +a barrier can be released. +Other helper inlines include ``waitAtBarrier()`` and ``barrierRelease()``. + +Behaviour Patterns +^^^^^^^^^^^^^^^^^^ + +File: ``barrier-mgr-model.pml`` + +The overall architecture in terms of Promela processes has processes ``init``, ``System``, ``Clock``, ``Runner``, +and two workers: ``Worker1`` and ``Worker2``. +The runner and workers each may perform one or more API calls, +in the following order: create, ident, wait, release, delete. +Scenarios mix and match which task does what. + +There are three top-level scenarios: + +.. code:: promela + + mtype = {ManAcqRel,AutoAcq,AutoToutDel}; + +In scenario ``ManAcqRel``, the runner will do create, release and delete, +with sub-scenarios to check error cases as well as good behaviour, +for manual barriers. +Good behaviour involves one or more workers doing a wait. +The ``AutoAcq`` and ``AutoToutDel`` +scenarios look at good and bad uses of automatic barriers. + +Annotations +^^^^^^^^^^^ + +File: ``barrier-mgr-model.pml`` + +Similiar to those used in the Event Manager. + +Refinement +^^^^^^^^^^ + +File: ``barrier-mgr-model-rfn.yml`` + +Similiar to those used in the Event Manager. + +Testing the Message Manager +--------------------------- + +Documentation: Message Manager section in the RTEMS Classic API Guide. + +Model Directory: ``formal/promela/models/messages``. + +Model Name: ``msg-mgr-model``. + +The Message Manager provides objects that act as message queues. Tasks can +interact with these by enqueuing and/or dequeuing message objects. + +There are 11 directives in total, but only the following were modelled: + + * ``rtems_message_queue_create()`` + + * ``rtems_message_queue_send()`` + + * ``rtems_message_queue_receive()`` + +The manager supports two queuing protocols, FIFO and priority-based. +Only the FIFO queueing was modelled. + +This model was developed by a Masters student :cite:`Lynch:2022:TESTGEN`, +using the Event Manager as a model. It was added into the QDP produced by +the follow-on IV&V activity. + +Below we focus on aspects of this model that differ from the Event Manager. + +API Model +^^^^^^^^^ + +File: ``msg-mgr-model.pml`` + +A key feature of this manager is that not only are messages in a queue, +but so are the tasks waiting for those messages. +Both task and message queues are modelled as circular buffers, +with inline definitions of enqueuing and dequeuing operations. + +While the Message Manager allows many queues to be created, +the model only uses one. + + +Behaviour Patterns +^^^^^^^^^^^^^^^^^^ + +File: ``msg-mgr-model.pml`` + +The overall architecture in terms of Promela processes has processes ``init``, ``System``, ``Clock``, ``Sender``, and two receivers: +``Receiver1`` and ``Receiver2``. +The ``Sender`` is the test runner, which performs the queue creation, +releases the start semaphore and then performs a send operation if needed. +The receivers are worker processes. + +There are four top level scenarios: + +.. code:: promela + + mtype = {Send,Receive,SndRcv, RcvSnd}; + +Scenarios ``Send`` and ``Receive`` are used for testing erroneous calls. +The ``SndRcv`` scenario fills up queues before the receivers run, +while the ``RcvSnd`` has the receivers waiting before messages are sent. + +Annotations +^^^^^^^^^^^ + +File: ``msg-mgr-model.pml`` + +Similiar to those used in the Event Manager. + +Refinement +^^^^^^^^^^ + +File: ``msg-mgr-model-rfn.yml`` + +Similiar to those used in the Event Manager. + +Current State of Play +--------------------- + +The models developed here are the result of +an ad-hoc incremental development process +and have a lot of overlapping material. + +Model State +^^^^^^^^^^^ + +The models were developed by first focusing on simple behavior +such as error handling, and then adding in simpler behaviors, +until sufficient coverage was acheived. +The basic philosophy at the time was not to fix anything not broken. + +This has led to the models being somewhat over-engineered, +particularly when it comes to scenario generation. +There is some conditional looping behaviour, +implemented using labels and ``goto``, +that should really be linearised, using conditionals to skip parts. +It is harder than it should be to understand what each scenario does. + +Also the API call models have perhaps a bit too much code devoted +to system behaviour. + +Model Refactoring +^^^^^^^^^^^^^^^^^ + +There is a case to be made to perform some model refactoring. +Some of this would address the model state issues above. +Other refactoring would extract the common model material out, +to be put into files that could be included. +This includes the binary semaphore models, +and the parts modelling preemption and waiting while blocked. + + +Test Code Refactoring +^^^^^^^^^^^^^^^^^^^^^ + +During the qualification activity, +a new file ``tx-support.c`` was added to the RTEMS validation testsuite codebase. +This gathers C test support functions used by most of the tests. +The contents of the ``tr-<modelname>.h`` and ``tr-<modelname>.c`` +files in particular should be brought in line with ``tx-support.c``. + +Suitable Promela models should also be produced +of relevant functions in ``tx-support.c``. + + + diff --git a/eng/fv/approaches.rst b/eng/fv/approaches.rst new file mode 100644 index 0000000..fe58a06 --- /dev/null +++ b/eng/fv/approaches.rst @@ -0,0 +1,178 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _FormalVerifApproaches: + +Formal Verification Approaches +============================== + +This is an overview of a range of formal methods and tools +that look feasible for use with RTEMS. + +A key criterion for any proposed tool is the ability to deploy it in a highly +automated manner. This amounts to the tool having a command-line interface that +covers all the required features. +One such feature is that the tool generates output that can be +easily transformed into the formats useful for qualification. +Tools with GUI interfaces can be very helpful while developing +and deploying formal models, as long as the models/tests/proofs +can be re-run automatically via the command-line. + +Other important criteria concerns the support available +for test generation support, +and how close the connection is between the formalism and actual C code. + +The final key criteria is whatever techniques are proposed should fit in +with the RTEMS Project Mission Statement, +in the Software Engineering manual. +This requires, among other things, +that any tool added to the tool-chain needs to be open-source. + +A more detailed report regarding this can be found in +:cite:`Butterfield:2021:FV1-200`. + + +Next is a general overview of formal methods and testing, +and discusses a number of formalisms and tools against the criteria above. + +Formal Methods Overview +----------------------- + +Formal specification languages can be divided into the following groups: + + Model-based: e.g., Z, VDM, B + + These have a language that describes a system in terms of having an abstract + state and how it is modified by operations. Reasoning is typically based + around the notions of pre- and post-conditions and state invariants. + The usual method of reasoning is by using theorem-proving. The resulting + models often have an unbounded number of possible states, and are capable + of describing unbounded numbers of operation steps. + + Finite State-based: e.g., finite-state machines (FSMs), SDL, Statecharts + + These are a variant of model-based specification, with the added constraint + that the number of states are bounded. Desired model properties are often + expressed using some form of temporal logic. The languages used to describe + these are often more constrained than in more general model-based + approaches. The finiteness allows reasoning by searching the model, + including doing exhaustive searches, a.k.a. model-checking. + + Process Algebras: e.g., CSP, CCS, pi-calculus, LOTOS + + These model systems in terms of the sequence of externally observable + events that they perform. There is no explicit definition of the abstract + states, but their underlying semantics is given as a state machine, + where the states are deduced from the overall behavior of the system, + and events denote transitions between these states. In general both the + number of such states and length of observed event sequences are unbounded. + While temporal logics can be used to express properties, many process + algebras use their own notation to express desired properties by simpler + systems. A technique called bisimulation is used to reason about the + relationships between these. + + Most of the methods above start with formal specifications/models. Also + needed is a way to bridge the gap to actual code. The relationship between + specification and code is often referred to as a :term:`refinement` + (some prefer the term :term:`reification`). Most model-based methods have refinement, + with the concept baked in as a key part of the methodology. + + Theorem Provers: e.g., CoQ, HOL4, PVS, Isabelle/HOL + + Many modern theorem provers are not only useful to help reason about the + formalisms mentioned above, but are often powerful enough to be used to + describe formal models in their own terms and then apply their proof + systems directly to those. + + Model Checkers: e.g., SPIN, FDR + + Model checkers are tools that do exhaustive searches over models with a + finite number of states. These are most commonly used with the finite-state + methods, as well as the process algebras where some bound is put on the + state-space. As model-checking is basically exhaustive testing, these are + often the easiest way to get test generation from formal techniques. + + Formal Development frameworks: e.g. TLA+, Frama-C, KeY + + There are also a number of frameworks that support a close connection + between a programming language, a formalism to specify desired behavior + for programs in that language, as well as tools to support the reasoning + (proof, simulation, test). + +Formal Methods actively considered +---------------------------------- + +Given the emphasis on verifying RTEMS C code, +the focus is on freely available tools that could easily connect to C. +These include: Frama-C, TLA+/PlusCal, Isabelle/HOL, and Promela/SPIN. +Further investigation ruled out TLA+/PlusCal because it is Java-based, +and requires installing a Java Runtime Environment. +Frama-C, Isabelle/HOL, and Promela/SPIN are discussed below in more detail, + +Frama-C +^^^^^^^ + +Frama-C (frama-c.com) is a platform supporting a range of tools for analysing C +code, including static analysers, support for functional specifications (ANSI-C +Specification Language – ACSL), and links to theorem provers. Some of its +analyses require code annotations, while others can extract useful information +from un-annotated code. It has a plug-in architecture, which makes it easy to +extend. It is used extensively by Airbus. + +Frama-C, and its plugins, are implemented in OCaml, +and it is installed using the ``opam`` package manager. +An issue here was that Frama-C has many quite large dependencies. +There was support for test generation, but it was not freely available. +Another issue was that Frama-C only supported C99, and not C11 +(the issue is how to handle C11 Atomics in terms of their semantics). + +Isabelle/HOL +^^^^^^^^^^^^ + +Isabelle/HOL is a wide-spectrum theorem-prover, implemented as an embedding of +Higher-Order Logic (HOL) into the Isabelle generic proof assistant +(isabelle.in.tum.de). It has a high degree of automation, including an ability +to link to third-party verification tools, and a very large library of verified +mathematical theorems, covering number and set theory, algebra, analysis. It is +based on the idea of a small trusted code kernel that defines an encapsulated +datatype representing a theorem, which can only be constructed using methods in +the kernel for that datatype, but which also scales effectively regardless of +how many theorems are so proven. +It is implemented using `polyml`, with the IDE implemented using Scala, +is open-source, and is easy to install. +However, like Frama-C, it is also a very large software suite. + +Formal Method actually used +--------------------------- + +A good survey of formal techniques and testing +is found in a 2009 ACM survey paper :cite:`Hierons:2009:FMT`. +Here they clearly state: + + "The most important role for formal verification in testing + is in the automated generation of test cases. + In this context, + model checking is the formal verification technology of choice; + this is due to the ability of model checkers + to produce counterexamples + in case a temporal property does not hold for a system model." + +Promela/SPIN +^^^^^^^^^^^^ + +The current use of formal methods in RTEMS is based on using the Promela +language to model key RTEMS features, +in such a way that tests can be generated using the SPIN model checker +(spinroot.com). +Promela is quite a low-level modelling language that makes it easy to get close +to code level, and is specifically targeted to modelling software. It is one of +the most widely used model-checkers, both in industry and education. It uses +assertions, and :term:`Linear Temporal Logic` (:term:`LTL`) to express properties of +interest. + +Given a Promela model that checks key properties successfully, +tests can be generated for a property *P* by asking +SPIN to check the negation of that property. +There are ways to get SPIN to generate multiple/all possible counterexamples, +as well as getting it to find the shortest. diff --git a/eng/fv/index.rst b/eng/fv/index.rst new file mode 100755 index 0000000..abeaa27 --- /dev/null +++ b/eng/fv/index.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _FormalVerif: + +Formal Verification +******************* + +.. toctree:: + + overview + approaches + methodology + promela-index + diff --git a/eng/fv/methodology.rst b/eng/fv/methodology.rst new file mode 100755 index 0000000..71430cd --- /dev/null +++ b/eng/fv/methodology.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _FormalVerifMethodology: + +Test Generation Methodology +=========================== + +The general approach to using any model-checking technology for test generation +has three major steps: + +Model desired behavior +---------------------- + +Construct a model that describes the desired properties (`P1`, ..., `PN`) +and use the model-checker to verify those properties. + +Promela can specify properties using the ``assert()`` statement, to be +true at the point where it gets executed, +and can use :term:`Linear Temporal Logic` +(LTL) to specify more complex properties over execution sequences. SPIN will +also check generic correctness properties such as deadlock and +livelock freedom. + +Make claims about undesired behavior +------------------------------------ + +Given a fully verified model, systematically negate each specified property. +Given that each property was verified as true, +then these negated properties will fail model-checking, +and counter-examples will be +generated. These counter-examples will in fact be scenarios describing correct +behavior of the system, demonstrating the truth of each property. + +.. warning:: + + It is very important that the negations only apply to stated properties, + and do not alter the possible behaviors of the model in any way. + The behaviours of the model are determined by the control-flow constructs, + so any boolean-valued expression statements used in these, + or used in sequential code to wait for some some condition, + should not be altered. + What can be altered are the expressions in ``assert()`` statements, + and any LTL properties. + +With Promela, there are a number of different ways to do systematic +negation. The precise approach adopted depends on the nature of the models, and +more details can be found +in the RTEMS Formal Models Guide Appendix in this document. + +Map good behavior scenarios to tests +------------------------------------ + +Define a mapping from counter-example output to test code, +and use this in the process of constructing a test program. + +A YAML file is used to define a mapping from SPIN output to +relevant fragments of RTEMS C test code, using the Test Framework section +in this document. +The process is automated by a python script called ``testbuilder``. + diff --git a/eng/fv/overview.rst b/eng/fv/overview.rst new file mode 100755 index 0000000..da981f2 --- /dev/null +++ b/eng/fv/overview.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _FormalVerifOverview: + +Formal Verification Overview +============================ + +Formal Verification is a technique based on writing key design artifacts using +notations that have a well-defined mathematical :term:`semantics`. This means +that these descriptions can be rigorously analyzed using logic and other +mathematical tools. The term :term:`formal model` is used to refer to any such +description. + +Having a formal model of a software engineering artifact (requirements, +specification, code) allows it to be analyzed to assess the behavior it +describes. This means checks can be done that the model has desired properties, +and that it lacks undesired ones. A key feature of having a formal description +is that tools can be developed that parse the notation and perform much, +if not most, of the analysis. An industrial-strength formalism is one that has +very good tool support. + +Having two formal models of the same software object at different levels +of abstraction (specification and code, say) allows their comparison. In +particular, a formal analysis can establish if a lower level artifact like +code satisfies the properties described by a higher level, +such as a specification. This relationship is commonly referred to as a +:term:`refinement`. + +Often it is quite difficult to get a useful formal model of real code. Some +formal modelling approaches are capable of generating machine-readable +:term:`scenarios <scenario>` that describe possible correct behaviors of the +system at the relevant level of abstraction. A refinement for these can be +defined by using them to generate test code. +This is the technique that is used in :ref:`FormalVerifMethodology` to +verify parts of RTEMS. Formal models are constructed based on requirements +documentation, and are used as a basis for test generation. diff --git a/eng/fv/promela-index.rst b/eng/fv/promela-index.rst new file mode 100644 index 0000000..6b32841 --- /dev/null +++ b/eng/fv/promela-index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. toctree:: + + tool-setup + promela + refinement diff --git a/eng/fv/promela.rst b/eng/fv/promela.rst new file mode 100755 index 0000000..6ebb3eb --- /dev/null +++ b/eng/fv/promela.rst @@ -0,0 +1,323 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _PromelaModelling: + +Modelling with Promela +====================== + +Promela is a large language with many features, +but only a subset is used here for test generation. +This is a short overview of that subset. +The definitive documentation can be found at +https://spinroot.com/spin/Man/promela.html. + +Promela Execution +----------------- + +Promela is a *modelling* language, not a programming language. It is designed +to describe the kind of runtime behaviors that make reasoning about low-level +concurrency so difficult: namely shared mutable state and effectively +non-deterministic interleaving of concurrent threads. This means that there are +control constructs that specify non-deterministic outcomes, +and an execution model that allows the specification of when threads should +block. + +The execution model is based on the following concepts: + +Interleaving Concurrency + A running Promela system consists of one or more concurrent processes. Each + process is described by a segment of code that defines a sequence of + atomic steps. The scheduler looks at all the available next-steps and makes + a **non-deterministic choice** of which one will run. The scheduler is + invoked after every atomic step. + +Executability + At any point in time, a Promela process is either able to perform a step, + and is considered executable, or is unable to do so, and is considered + blocked. Whether a statement is executable or blocked may depend on the + global state of the model. The scheduler will only select from among the + executable processes. + +The Promela language is based loosely on C, and the SPIN model-checking tool +converts a Promela model into a C program that has the specific model +hard-coded and optimized for whatever analysis has been invoked. It also +supports the use of the C pre-processor. + +Simulation vs. Verification +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPIN can run a model in several distinct modes: + +Simulation + SPIN simply makes random choices for the scheduler to produce a possible + execution sequence (a.k.a. scenario) allowed by the model. A readable + transcript is written to ``stdout`` as the simulation runs. + + The simplest SPIN invocation does simulation by default: + + .. code:: shell + + spin model.pml + +Verification + SPIN does an analysis of the whole model by exploring all the possible + choices that the scheduler can make. This will continue until either all + possible choices have been covered, or some form of error is uncovered. + If verification ends successfully, then this is simply reported as ok. + If an error occurs, verification stops, and the sequence of steps that led + to that failure are output to a so-called trail file. + + The simplest way to run a verification is to give the ``-run`` option: + + .. code:: shell + + spin -run model.pml + +Replaying + A trail file is an uninformative list of number-triples, but can be replayed + in simulation mode to produce human-readable output. + + .. code:: shell + + spin -t model.pml + +Promela Datatypes +----------------- + +Promela supports a subset of C scalar types (``short``, ``int``), but also +adds some of its own (``bit``, ``bool``, ``byte``, ``unsigned``). +It has support for one-dimensional arrays, +and its own variation of the C struct concept +(confusingly called a ``typedef``!). +It has a single enumeration type called ``mtype``. +There are no pointers in Promela, which means that modelling pointer +usage requires the use of arrays with their indices acting as proxies for +pointers. + +Promela Declarations +-------------------- + +Variables and one-dimensional arrays can be declared in Promela in much the +same way as they are done in C: + +.. code-block:: C + + int x, y[3] ; + +All global variables and arrays are initialized to zero. + +The identifier ``unsigned`` is the name of a type, rather than a modifier. +It is used to declare an unsigned number variable with a given bit-width: + +.. code-block:: C + + unsigned mask : 4 ; + + +Structure-like datatypes in Promela are defined using the ``typedef`` keyword +that associates a name with what is basically a C ``struct``: + +.. code-block:: C + + typedef CBuffer { + short count; + byte buffer[8] + } + + CBuffers cbuf[6]; + +Note that we can have arrays of ``typedef``\ s that themselves contain arrays. +This is the only way to get multi-dimensional arrays in Promela. + +There is only one enumeration type, which can be defined incrementally. +Consider the following sequence of four declarations that defines the values in +``mtype`` and declares two variables of that type: + +.. code-block:: C + + mtype = { up, down } ; + mtype dir1; + mtype = { left, right} ; + mtype dir2; + +This gives the same outcome with the following two declarations: + +.. code-block:: C + + mtype = { left, right, up, down } ; + mtype dir1, dir2; + +Special Identifiers +^^^^^^^^^^^^^^^^^^^ + +The are a number of variable identifiers that have a special meaning in Promela. +These all start with an underscore. We use the following: + +Process Id + ``_pid`` holds the process id of the currently active process + +Process Count + ``_nr_pr`` gives the number of currently active processes. + +Promela Atomic Statements +------------------------- + +Assignment + ``x = e`` where ``x`` is a variable and ``e`` is an expression. + + Expression ``e`` must have no side-effects. An assignment is always + executable. Its effect is to update the value of ``x`` with the current + value of ``e``. + +Condition Statement + ``e`` where ``e`` is an expression + + Expression ``e``, used standalone as a statement, is executable if its + value in the current state is non-zero. If its current value is zero, + then it is blocked. It behaves like a NO-OP when executed. + +Skip + ``skip``, a keyword + + ``skip`` is always executable, and behaves like a NO-OP when executed. + +Assertion + ``assert(e)`` where ``e`` is an expression + + An assertion is always executable. When executed, it evaluates its + expression. If the value is non-zero, then it behaves like a NO-OP. If the + value is zero, then it generates an assertion error and aborts further + simulation/verification of the model. + +Printing + ``printf(string,args)`` where ``string`` is a format-string and ``args`` + are values and expressions. + + A ``printf`` statement is completely ignored in verification mode. + In simulation mode, it is always executable, + and generates output to ``stdout`` in much the same way as in C. + This is is used in a structured way to assist with test generation. + +Goto + ``goto lbl`` where ``lbl`` is a statement label. + + Promela supports labels for statements, in the same manner as C. + The ``goto`` statement is always executable. + When executed, flow of control goes to the statement labelled by ``lbl:``. + +Break + ``break``, a keyword + + Can only occur within a loop (``do ... od``, see below). It is always + executable, and when executed performs a ``goto`` to the statement just + after the end of the innermost enclosing loop. + +Promela Composite Statements +---------------------------- + +Sequencing + ``{ <stmt> ; <stmt> ; ... ; <stmt> }`` where each ``<stmt>`` can be any + kind of statement, atomic or composite. The sub-statements execute in + sequence in the usual way. + +Selection + .. code-block:: none + + if + :: <stmt> + :: <stmt> + ... + :: <stmt> + fi + + A selection construct is blocked if all the ``<stmt>`` are blocked. It is + executable if at least one ``<stmt>`` is executable. The scheduler will make + a non-deterministic choice from all of those ``<stmt>`` that are executable. + The construct terminates when/if the chosen ``<stmt>`` does. + + Typically, a selection statement will be a sequence of the form + ``g ; s1 ; ... ; sN`` where ``g`` is an expression acting as a guard, + and the rest of the statements are intended to run if ``g`` is non-zero. + The symbol ``->`` plays the same syntactic role as ``;``, so this allows + for a more intuitive look and feel; ``g -> s1 ; ... ; sN``. + + If the last ``<stmt>`` has the form ``else -> ...``, then the ``else`` is + executable only when all the other selection statements are blocked. + +Repetition + .. code-block:: none + + do + :: <stmt> + :: <stmt> + ... + :: <stmt> + od + + The executability rules here are the same as for Selection above. The key + difference is that when/if a chosen ``<stmt>`` terminates, then the whole + construct is re-executed, making it basically an infinite loop. The only + way to exit this loop is for an active ``<stmt>`` to execute a ``break`` + or ``goto`` statement. + + A ``break`` statement only makes sense inside a Repetition, is always + executable, and its effect is to jump to the next statement after the + next ``od`` keyword in text order. + + +The selection and repetition syntax and semantics are based on Edsger +Djikstra's Guarded Command Language :cite:`Djikstra:1975:GCL` . + + +Atomic Composite + ``atomic{stmt}`` where ``stmt`` is usually a (sequential) composite. + + Wrapping the ``atomic`` keyword around a statement makes its entire + execution proceed without any interference from the scheduler. Once it is + executable, if the scheduler chooses it to run, then it runs to completion. + + There is one very important exception: if it should block internally because + some sub-statement is blocked, then the atomicity gets broken, and the + scheduler is free to find some other executable process to run. When/if the + sub-statement eventually becomes executable, once it gets chosen to run by + the scheduler then it continues to run atomically. + +Processes + ``proctype name (args) { sequence }`` where ``args`` is a list of zero + or more typed parameter declarations, + and ``sequence`` is a list of local declarations and statements. + + This defines a process type called ``name`` which takes parameters defined + by ``args`` and has the behavior defined by ``sequence``. When invoked, it + runs as a distinct concurrent process. Processes can be invoked explicitly + by an existing process using the ``run`` statement, + or can be setup to start automatically. + +Run + ``run name (exprs)`` where ``exprs`` is a list of expressions that match + the arguments defined the ``proctype`` declaration for ``name``. + + This is executable as long as the maximum process limit has not been reached, + and immediately starts the process running. + It is an atomic statement. + +Inlining + ``inline name (names) { sequence }`` where ``names`` is a list of zero or + more identifiers, and ``sequence`` is a list of declarations and statements. + + Inlining does textual substitution, and does not represent some kind of + function call. An invocation ``name(texts)`` gets replaced by + ``{ sequence }`` where each occurrence of an identifier in ``names`` is + replaced by the corresponding text in ``texts``. Such an invocation can + only appear in a context where a Promela statement can appear. + +Promela Top-Level +----------------- + +At the top-level, a Promela model is a list of declarations, much like a C +program. The Promela equivalent of ``main`` is a process called ``init`` that +has no arguments. There must be at least one Promela process setup to be running +at the start. This can be ``init``, or one or more ``proctype``\ s declared as +``active``. diff --git a/eng/fv/refinement.rst b/eng/fv/refinement.rst new file mode 100755 index 0000000..4cbad19 --- /dev/null +++ b/eng/fv/refinement.rst @@ -0,0 +1,559 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _Promela2CRefinement: + +Promela to C Refinement +======================= + +Promela models are more abstract than concrete C code. +A rigorous link, known as a :term:`refinement`, needs to be established +from Promela to C. +This is composed of two parts: +manual annotations in the Promela model to make its behavior easy +to identify and parse; +and a refinement defined as a YAML file that maps from +annotations to corresponding C code. +A single refinement YAML file is associated with each Promela model. + +Model Annotations +----------------- + +Promela ``printf`` statements are used in the models to output information that +is used by ``spin2test`` to generate test code. This information is used to +lookup keys in a YAML file that defines the mapping to C code. It uses a simple +format that makes it easy to parse and process, and is also designed to be +easily understood by a human reader. This is important because any V&V process +will require this information to be carefully assessed. + +Annotation Syntax +^^^^^^^^^^^^^^^^^ + +Format, where :math:`N \geq 0`: + + ``@@@ <pid> <KEYWORD> <parameter1> ... <parameterN>`` + +The leading ``@@@`` is a marker that makes it easy to filter out this +information from other SPIN output. + +Parameters take the following forms: + + ``<pid>`` Promela Process Id of ``proctype`` generating annotation + + ``<word>`` chunk of text containing no white space + + ``<name>`` Promela variable/structure/constant identifier + + ``<type>`` Promela type identifier + + ``<tid>`` OS Task/Thread/Process Id + + ``_`` unused argument (within containers) + +Each ``<KEYWORD>`` is associated with specific forms of parameters: + +.. code-block:: none + + LOG <word1> ... <wordN> + NAME <name> + INIT + DEF <name> <value> + DECL <type> <name> [<value>] + DCLARRAY <type> <name> <value> + TASK <name> + SIGNAL <name> <value> + WAIT <name> <value> + STATE tid <name> + SCALAR (<name>|_) [<index>] <value> + PTR <name> <value> + STRUCT <name> + SEQ <name> + END <name> + CALL <name> <value1> ... <valueN> + + +Annotation Lookup +----------------- + +The way that code is generated depends on the keyword in the annotation. +In particular, the keyword determines how, or if, +the YAML refinement file is looked up. + + Direct Output - no lookup + (``LOG``, ``DEF``) + + Keyword Refinement - lookup the ``<KEYWORD>`` + (``NAME``, ``INIT``, ``SIGNAL``, ``WAIT``) + + Name Refinement - lookup first parameter (considered as text) + (``TASK``, ``DECL``, ``DCLARRAY``, ``PTR``, ``CALL``, ``SCALAR``) + +The same name may appear in different contexts, +and the name can be extended with a suffix of the form +``_XXX`` to lookup less frequent uses: + + ``_DCL`` - A variable declaration + + ``_PTR`` - The pointer value itself + + ``_FSCALAR`` - A scalar that is a struct field + + ``_FPTR`` - A pointer that is a struct field + +Generally, the keyword, or name is used to lookup ``mymodel-rfn.yml`` to get a +string result. This string typically has substitution placeholders, as used by +the Python ``format()`` method for strings. The other parameters in the +annotation are then textually substituted in, to produce a segment of test code. + + +Specifying Refinement +--------------------- + +Using the terminology of the :ref:`RTEMSTestFramework` +each Promela model is converted into a set of Test Cases, +one for each complete scenario produced by test generation. +There are a number of template files, tailored for each model, +that are used to assemble the test code sources, +along with code segments for each Promela process, +based on the annotations output for any given scenario. + + +The refinement mapping from annotations to code is defined in a YAML file that +describes a Python dictionary that maps a name to some C code, with placeholders +that are used to allow for substituting in actual test values. + +The YAML file has entries of the following form: + +.. code:: yaml + + entity: | + C code line1{0} + ... + C code lineM{2} + +The entity is a reference to an annotation concept, which can refer to key +declarations, values, variables, types, API calls or model events. There can be +zero or more arguments in the annotations, and any occurrence of braces +enclosing a number in the C code means that the corresponding annotation +argument string is substituted in (using the python string object `format()` +method). + +The general pattern is working through all the annotations in order. The +code obtained by looking up the YAML file is collated into different +code-segments, one for each Promela process id (``<pid>``). + +In addition to the explicit annotations generated by the Promela models, there +are two implicit annotations produced by the python refinement code. These +occur when the ``<pid>`` part of a given explicit annotation is different to the +one belonging to the immediately preceding annotation. This indicates a point in +a test generation scenario where one task is suspended and another resumes. This +generates internal annotations with keywords ``SUSPEND`` and ``WAKEUP`` which +should have entries in the refinement file to provide code to ensure that the +corresponding RTEMS tasks in the test behave accordingly. + +The annotations can also be output as comments into the generated test-code, so +it is easy to check that parameters are correct, and the generated code is +correct. + +If a lookup fails, a C comment line is output stating the lookup failed. +The translation continues in any case. + +Lookup Example +^^^^^^^^^^^^^^ + +Consider the following annotation, from the Events Manager model: + + ``@@@ 1 CALL event_send 1 2 10 sendrc`` + +This uses Name refinement so a lookup with ``event_send`` as the key +and gets back the following text: + +.. code-block:: python3 + + T_log( T_NORMAL, "Calling Send(%d,%d)", mapid( ctx, {1}), {2} ); + {3} = ( *ctx->send )( mapid( ctx, {1} ), {2} ); + T_log( T_NORMAL, "Returned 0x%x from Send", {3} ); + +Arguments ``1``, ``2``, ``10``, and ``sendrc`` +are then substituted to get the code: + +.. code-block:: c + + T_log( T_NORMAL, "Calling Send(%d,%d)", mapid( ctx, 2), 10 ); + sendrc = ( *ctx->send )( mapid( ctx, 2 ), 10 ); + T_log( T_NORMAL, "Returned 0x%x from Send", sendrc ); + +Given a Promela process id of ``1``, this code is put into a code segment +for the corresponding RTEMS task. + + +Annotation Refinement Guide +--------------------------- + +This guide describes how each annotation is processed +by the test generation software. + +LOG +^^^ + +``LOG <word1> ... <wordN>`` (Direct Output) + Generate a call to ``T_log()`` with a message formed from the ``<word..>`` + parameters. + This message will appear in the test output for certain verbosity settings. + +NAME +^^^^ + +``NAME <name>`` (Keyword Refinement) + Looks up ``NAME`` (currently ignoring ``<name>``) and returns the resulting + text as is as part of the code. This code should define the name of the + testcase, if needed. + +INIT +^^^^ + +``INIT`` (Keyword Refinement) + Lookup ``INIT`` and expect to obtain test initialisation code. + +TASK +^^^^ + +``TASK <name>`` (Name Refinement) + Lookup ``<name>`` and return corresponding C code. + +SIGNAL +^^^^^^ + +``SIGNAL <value>`` (Keyword Refinement) + Lookup `SIGNAL` and return code with `<value>` substituted in. + +WAIT +^^^^ + +``WAIT <value>`` (Keyword Refinement) + Lookup `WAIT` and return code with `<value>` substituted in. + +DEF +^^^ + +``DEF <name> <value>`` (Direct Output) + Output ``#define <name> <value>``. + +DECL +^^^^ + +``DECL <type> <name> [<value>]`` (Name Refinement) + Lookup ``<name>_DCL`` and substitute ``<name>`` in. If ``<value>`` is + present, append ``=<value>``. Add a final semicolon. If the `<pid>` value + is zero, prepend ``static``. + +DCLARRAY +^^^^^^^^ + +``DCLARRAY <type> <name> <value>`` (Name Refinement) + Lookup ``<name>_DCL`` and substitute ``<name>`` and ``<value>`` in. If the + `<pid>` value is zero, prepend ``static``. + +CALL +^^^^ + +``CALL <name> <value0> .. <valueN>`` (Name refinement, ``N`` < 6) + Lookup ``<name>`` and substitute all ``<value..>`` in. + +STATE +^^^^^ + +``STATE <tid> <name>`` (Name Refinement) + Lookup ``<name>`` and substitute in ``<tid>``. + +STRUCT +^^^^^^ + +``STRUCT <name>`` + Declares the output of the contents of variable ``<name>`` + that is itself a structure. The ``<name>`` is noted, as is the fact + that a structured value is being processes. + Should not occur if already be processing a structure or a sequence. + +SEQ +^^^ + +``SEQ <name>`` + Declares the output of the contents of array variable ``<name>``. + The ``<name>`` is noted, as is the fact that an array is being processed. + Values are accumulated in a string now initialsed to empty. + Should not occur if already processing a structure or a sequence. + +PTR +^^^ + +``PTR <name> <value>`` (Name Refinement) + If not inside a ``STRUCT``, lookup ``<name>_PTR``. Two lines of code should + be returned. If the ``<value>`` is zero, use the first line, otherwise use + the second with ``<value>`` substituted in. This is required to handle NULL + pointers. + + If inside a ``STRUCT``, lookup ``<name>_FPTR``. Two lines of code should + be returned. If the ``<value>`` is zero, use the first line, otherwise use + the second with ``<value>`` substituted in. This is required to handle NULL + pointers. + +SCALAR +^^^^^^ + +There are quite a few variations here. + +``SCALAR _ <value>`` + Should only be used inside a ``SEQ``. A space and ``<value>`` is appended + to the string being accumulated by this ``SEQ``. + +``SCALAR <name> <value>`` (Name Refinement) + If not inside a ``STRUCT``, lookup ``<name>``, and substitute ``<value>`` + into the resulting code. + + If inside a ``STRUCT``, lookup ``<name>_FSCALAR`` and substitute the saved + ``STRUCT`` name and ``<value>`` into the resulting code. + + This should not be used inside a ``SEQ``. + +``SCALAR <name> <index> <value>`` (Name Refinement) + If not inside a ``STRUCT``, lookup ``<name>``, and substitute ``<index>`` + and ``<value>`` into the resulting code. + + If inside a ``STRUCT``, lookup ``<name>_FSCALAR`` and substitute the saved + ``STRUCT`` name and ``<value>`` into the resulting code. + + This should not be used inside a ``SEQ``. + +END +^^^ + +``END <name>`` + If inside a ``STRUCT``, terminates processing a + structured variable. + + If inside a ``SEQ``, lookup ``<name>_SEQ``. For each line of code obtained, + substitute in the saved sequence string. + Terminates processing a sequence/array variable. + + This should not be encountered outside of a ``STRUCT`` or ``SEQ``. + +SUSPEND and WAKEUP +^^^^^^^^^^^^^^^^^^ + +A change of Promela process id from ``oldid`` to ``newid`` has been found. +Increment a counter that tracks the number of such changes. + +``SUSPEND`` (Keyword Refinement) + + Lookup ``SUSPEND`` and substitute in the counter value, ``oldid`` and + ``newid``. + +``WAKEUP`` (Keyword Refinement) + + Lookup ``WAKEUP`` and substitute in the counter value, ``newid`` and + ``oldid``. + +Annotation Ordering +------------------- + +While most annotations occur in an order determined by any given test scenario, +there are some annotations that need to be issued first. These are, in order: +``NAME``, ``DEF``, ``DECL`` and ``DCLARRAY``, and finally, ``INIT``. + + +Test Code Assembly +------------------ + +The code snippets produced by refining annotations are not enough. +We also need boilerplate code to setup, coordinate and teardown the tests, +as well as providing useful C support functions. + +For a model called `mymodel` the following files are required: + +* ``mymodel.pml`` - the Promela model +* ``mymodel-rfn.yml`` - the model refinement to C test code +* ``tc-mymodel.c`` - the testcase setup C file +* ``tr-mymodel.h`` - the test-runner header file +* ``tr-mymodel.c`` - the test-runner setup C file + +The following files are templates used to assemble +a single test-runner C file +for each scenario generated by the Promela model: + +* ``mymodel-pre.h`` - preamble material at the start +* ``mymodel-run.h`` - test runner material +* ``mymodel-post.h`` - postamble material at the end. + +The process is entirely automated: + +.. code-block:: shell + + tbuild all mymodel + +The steps of the process are as follows: + +Scenario Generation +^^^^^^^^^^^^^^^^^^^ + +When SPIN is invoked to find all scenarios, +it will produce a number (N) of counterexample files +with a ``.trail`` extension. +These files hold numeric data that refer to SPIN internals. + +.. code-block:: none + + mymodel.pml1.trail + ... + mymodel.pmlN.trail + +SPIN is then used to take each trail file and produce a human-readable +text file, using the same format as the SPIN simulation output. +SPIN numbers files from 1 up, +whereas the RTEMS convention is to number things, +including filenames, from zero. +SPIN is used to produce readable output in text files with a ``.spn`` extension, +with 1 subtracted from the trail file number. +This results in the following files: + +.. code-block:: shell + + mymodel-0.spn + ... + mymodel-{N-1}.spn + +Test Code Generation +^^^^^^^^^^^^^^^^^^^^ + +Each SPIN output file ``mymodel-I.spn`` +is converted to a C test runner file ``tr-mymodel-I.c`` +by concatenating the following components: + +``mymodel-pre.h`` + This is a fairly standard first part of an RTEMS test C file. + It is used unchanged. + +refined test segments + The annotations in ``mymodel-I.spn`` are converted, in order, + into test code snippets using the refinement file ``mymodel-rfn.yml``. + Snippets are gathered into distinct code segments based on the Promela + process number reported in each annotation. + Each code segment is used to construct a C function called + ``TestSegmentP()``, where ``P`` is the relevant process number. + +``mymodel-post.h`` + This is static code that declares the top-level RTEMS Tasks + used in the test. + These are where the code segments above get invoked. + +``mymodel-run.h`` + This defines top-level C functions that implement a given test runner. The top-level function has a name like ``RtemsMyModel_Run`` + This is not valid C as it needs to produce a name parameterized by + the relevant scenario number. It contains Python string format substitution + placeholders that allow the relevant number to be added to end of the + function name. So the above run function actually appears in this file as ``RtemsMyModel_Run{0}``, so ``I`` will be substituted in for ``{0}`` to result in the name ``RtemsMyModel_RunI``. + In particular, it invokes ``TestSegment0()`` which contains code + generated from Promela process 0, which is the main model function. + This declares test variables, and initializes them. + +These will generate test-runner test files as follows: + +.. code-block:: none + + tr-mymodel-0.c + ... + tr-mymodel-{N-1}.c + +In addition, the test case file ``tc-mymodel.c`` needs to have entries added +manually of the form below, for ``I`` in the range 0 to N-1.: + +.. code-block:: c + + T_TEST_CASE( RtemsMyModelI ) + { + RtemsMyModel_RunI( + ... + ); + } + +These define the individual test cases in the model, each corresponding to precisely one SPIN scenario. + +Test Code Deployment +^^^^^^^^^^^^^^^^^^^^ + +All files starting with ``tc-`` or ``tr-`` are copied to the +relevant testsuite directory. +At present, this is ``testsuites/validation`` at the top level in +the ``rtems`` repository. +All the names of the above files with a ``.c`` extension are added +into a YAML file that +defines the Promela generated-test sources. +At present, this +is ``spec/build/testsuites/validation/model-0.yml`` +at the top-level in the ``rtems`` repository. +They appear in the YAML file under the ``source`` key: + +.. code-block:: yaml + + source: + - testsuites/validation/tc-mymodel.c + - testsuites/validation/tr-mymodel-0.c + ... + - testsuites/validation/tr-mymodel-{N-1}.c + - testsuites/validation/ts-model-0.c + +Performing Tests +^^^^^^^^^^^^^^^^ + +At this point build RTEMS as normal. e.g., with ``waf``, +and the tests will get built. +The executable will be found in the designated build directory, +*(e.g.):* + + ``rtems/build/sparc/gr740/testsuites/validation/ts-model-0.exe`` + + This can be run using the RTEMS Tester + (RTEMS User Manual, Host Tools, RTEMS Tester and Run). + + + Both building the code and running on the tester is also automated + (see :ref:`FormalToolSetup`). + +Traceability +------------ + +Traceability between requirements, specifications, designs, code, and tests, +is a key part of any qualification/certification effort. The test generation +methodology developed here supports this in two ways, when refining an +annotation: + +1. If the annotation is for a declaration of some sort, the annotation itself + is added as a comment to the output code, just before the refined declaration. + + .. code-block:: c + + // @@@ 0 NAME Chain_AutoGen + // @@@ 0 DEF MAX_SIZE 8 + #define MAX_SIZE 8 + // @@@ 0 DCLARRAY Node memory MAX_SIZE + static item memory[MAX_SIZE]; + // @@@ 0 DECL unsigned nptr NULL + static item * nptr = NULL; + // @@@ 0 DECL Control chain + static rtems_chain_control chain; + +2. If the annotation is for a test of some sort, a call to ``T_log()`` is + generated with the annotation as its text, just before the test code. + + .. code-block:: c + + T_log(T_NORMAL,"@@@ 0 INIT"); + rtems_chain_initialize_empty( &chain ); + T_log(T_NORMAL,"@@@ 0 SEQ chain"); + T_log(T_NORMAL,"@@@ 0 END chain"); + show_chain( &chain, ctx->buffer ); + T_eq_str( ctx->buffer, " 0" ); + +In addition to traceability, these also help when debugging models, refinement +files, and the resulting test code. diff --git a/eng/fv/tool-setup.rst b/eng/fv/tool-setup.rst new file mode 100755 index 0000000..f8cf046 --- /dev/null +++ b/eng/fv/tool-setup.rst @@ -0,0 +1,317 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Trinity College Dublin + +.. _FormalToolSetup: + +Formal Tools Setup +================== + +The required formal tools consist of +the model checking software (Promela/SPIN), +and the test generation software (spin2test/testbuilder). + +Installing Tools +---------------- + +Installing Promela/SPIN +^^^^^^^^^^^^^^^^^^^^^^^ + +Follow the installation instructions for Promela/Spin +at https://spinroot.com/spin/Man/README.html. + +There are references there to the Spin Distribution which is now on +Github (https://github.com/nimble-code/Spin). + +Installing Test Generation Tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The test generation tools are found in ``formal/promela/src``, written in +Python3, and installed using a virtual environment. +To build the tools, enter ``formal/promela/src`` and issue the +commands: + +.. code:: shell + + make env + . env/bin/activate + make py + +The test generation tools need to be used from within this Python virtual +environment. Use the ``deactivate`` command to exit from it. + +Test generation is managed at the top level by the script ``testbuilder.py`` +located in the top-level of ``formal/promela/src``. +To avoid using (long) absolute pathnames, +it helps to define an suitable alias +*(e.g.)*: + +.. code-block:: shell + + alias tbuild='python3 /..../formal/promela/src/testbuilder.py' + +This alias is used subsequently in this documentation. + +To check for a successful tool build, invoke the command without any +arguments, which should result in an extended help message being displayed: + +.. code-block:: shell + + (env) prompt % tbuild + USAGE: + help - more details about usage and commands below + all modelname - runs clean, spin, gentests, copy, compile and run + clean modelname - remove spin, test files + archive modelname - archives spin, test files + zero - remove all tesfiles from RTEMS + spin modelname - generate spin files + gentests modelname - generate test files + copy modelname - copy test files and configuration to RTEMS + compile - compiles RTEMS tests + run - runs RTEMS tests + +The tool is not yet ready for use, as it needs to be configured. + +Tool Configuration +------------------ + +Tool configuration involves setting up a new testsuite in RTEMS, and providing +information to ``tbuild`` that tells it where to find key locations, and some +command-line arguments for some of the tools. +A template file ``testbuilder-template.yml`` is included, +and contains the following entries: + +.. code-block:: python + + # This should be specialised for your setup, as testbuilder.yml, + # located in the same directory as testbuilder.py + # All pathnames should be absolute + + spin2test: <spin2test_directory>/spin2test.py + rtems: <path-to-main-rtems-directory> # rtems.git, or ..../modules/rtems/ + rsb: <rsb-build_directory>/rtems/6/bin/ + simulator: <path-to>/sparc-rtems6-sis + testyamldir: <rtems>/spec/build/testsuites/validation/ # directory containing <modelname>.yml + testcode: <rtems>/testsuites/validation/ + testexedir: <rtems>/build/.../testsuites/validation/ # directory containing ts-<modelname>.exe + testsuite: model-0 + simulatorargs: -leon3 -r s -m 2 # run command executes "<simulator> <simargs> <testexedir>/ts-<testsuite>.exe" + spinallscenarios: -DTEST_GEN -run -E -c0 -e # trail generation "spin <spinallscenarios> <model>.pml" + +This template should be copied/renamed to ``testbuilder.yml`` +and each entry updated as follows: + +* spin2test: + This should be the absolute path to ``spin2test.py`` + in the Promela sources directory. + + ``/.../formal/promela/src/spin2test.py`` + +* rtems: + This should be the absolute path to your RTEMS source directory, + with the terminating ``/``. + From ``rtems-central`` this would be: + + ``/.../rtems-central/modules/rtems/`` + + For a separate ``rtems`` installation + it would be where ``rtems.git`` was cloned. + + We refer to this path below as ``<rtems>``. + +* rsb: + This should be the absolute path + to your RTEMS source-builder binaries directory, + with the terminating ``/``. + From ``rtems-central`` this would be (assuming RTEMS 6): + + ``/.../rtems-central/modules/rsb/6/bin/`` + +* simulator: + This should be the absolute path to the RTEMS Tester + (See Host Tools in the RTEMS User Manual) + + It defaults at present to the ``sis`` simulator + + ``/.../rtems-central/modules/rsb/6/bin/sparc-rtems6-sis`` + +* testsuite: + This is the name for the testsuite : + + Default value: ``model-0`` + +* testyamldir: + This should be the absolute path to where validation tests are *specified*: + + ``<rtems>/spec/build/testsuites/validation/`` + +* testcode: + This should be the absolute path to where validation test sources + are found: + + ``<rtems>/testsuites/validation/`` + +* testexedir: + This should be the absolute path to where + the model-based validation test executable + will be found: + + ``<rtems>/build/.../testsuites/validation/`` + + This will contain ``ts-<testsuite>.exe`` (e.g. ``ts-model-0.exe``) + +* simulatorargs: + These are the command line arguments for the RTEMS Tester. + It defaults at present to those for the ``sis`` simulator. + + ``-<bsp> -r s -m <cpus>`` + + The first argument should be the BSP used when building RTEMS sources. + BSPs ``leon3``, ``gr712rc`` and ``gr740`` have been used. + The argument to the ``-m`` flag is the number of cores. + Possible values are: 1, 2 and 4 (BSP dependent) + + Default: ``-leon3 -r s -m 2`` + +* spinallscenarios: + These are command line arguments for SPIN, + that ensure that all counter-examples are generated. + + Default: ``-DTEST_GEN -run -E -c0 -e`` (recommended) + +Testsuite Setup +^^^^^^^^^^^^^^^ + +The C test code generated by these tools is installed into the main ``rtems`` +repository at ``testsuites/validation`` in the exact same way as other RTEMS +test code. +This means that whenever ``waf`` is used at the top level to build and/or run +tests, that the formally generated code is automatically included. +This requires adding and modifying some *Specification Items* +(See Software Requirements Engineering section in this document). + +To create a testsuite called ``model-0`` (say), do the following, in the +``spec/build/testsuites/validation`` directory: + +* Edit ``grp.yml`` and add the following two lines into the `links` entry: + + .. code-block:: YAML + + - role: build-dependency + uid: model-0 + +* Copy ``validation-0.yml`` (say) to ``model-0.yml``, and change the following + entries as shown: + + .. code-block:: YAML + + enabled-by: RTEMS_SMP + source: + - testsuites/validation/ts-model-0.c + target: testsuites/validation/ts-model-0.exe + +Then, go to the ``testsuites/validation`` directory, and copy +``ts-validation-0.c`` to ``ts-model-0.c``, and edit as follows: + + * Change all occurrences of ``Validation0`` in comments to ``Model0``. + + * Change ``rtems_test_name`` to ``Model0``. + +Running Test Generation +----------------------- + +The testbuilder takes a command as its first command-line argument. Some of +these commands require the model-name as a second argument: + + Usage: ``tbuild <command> [<modelname>]`` + +The commands provided are: + +``clean <model>`` + Removes generated files. + +``spin <model>`` + Runs SPIN to find all scenarios. The scenarios are found in numbered files + called ``<model>N.spn``. + +``gentests <model>`` + Convert SPIN scenarios to test sources. Each ``<model>N.spn`` produces a numbered + test source file. + +``copy <model>`` + Copies the generated test files to the relevant test source directory, and + updates the relevant test configuration files. + +``archive <model>`` + Copies generated spn, trail, source, and test log files to an archive + sub-directory of the model directory. + +``compile`` + Rebuilds the test executable. + +``run`` + Runs tests in a simulator. + +``all <model>`` + Does clean, spin, gentests, copy, compile, and run. + +``zero`` + Removes all generated test filenames from the test configuration files, but + does NOT remove the test sources from the test source directory. + +In order to generate test files the following input files are required: + ``<model>.pml``, + ``<model>-rfn.yml``, + ``<model>-pre.h``, + ``<model>-post.h``, and + ``<model>-run.h``. +In addition there may be other files +whose names have <model> embedded in them. These are included in what is +transfered to the test source directory by the copy command. + +The simplest way to check test generation is setup properly is to visit one of +the models, found under ``formal/promela/models`` and execute the following +command: + +.. code-block:: shell + + tbuild all mymodel + +This should end by generating a file `model-0-test.log`. The output is +identical to that generated by the regular RTEMS tests, using the +*Software Test Framework* described elsewhere in this document. + +Output for the Event Manager model, highly redacted: + +.. code-block:: + + SIS - SPARC/RISCV instruction simulator 2.29, copyright Jiri Gaisler 2020 + Bug-reports to jiri@gaisler.se + + GR740/LEON4 emulation enabled, 4 cpus online, delta 50 clocks + + Loaded ts-model-0.exe, entry 0x00000000 + + *** BEGIN OF TEST Model0 *** + *** TEST VERSION: 6.0.0.03337dab21e961585d323a9974c8eea6106c803d + *** TEST STATE: EXPECTED_PASS + *** TEST BUILD: RTEMS_SMP + *** TEST TOOLS: 10.3.1 20210409 (RTEMS 6, RSB 889cf95db0122bd1a6b21598569620c40ff2069d, Newlib eb03ac1) + A:Model0 + S:Platform:RTEMS + ... + B:RtemsModelSystemEventsMgr8 + ... + L:@@@ 3 CALL event_send 1 2 10 sendrc + L:Calling Send(167837697,10) + L:Returned 0x0 from Send + ... + E:RtemsModelEventsMgr0:N:21:F:0:D:0.005648 + Z:Model0:C:18:N:430:F:0:D:0.130464 + Y:ReportHash:SHA256:5EeLdWsRd25IE-ZsS6pduLDsrD_qzB59dMU-Mg2-BDA= + + *** END OF TEST Model0 *** + + cpu 0 in error mode (tt = 0x80) + 6927700 0000d580: 91d02000 ta 0x0 + diff --git a/eng/glossary.rst b/eng/glossary.rst new file mode 100644 index 0000000..a015eda --- /dev/null +++ b/eng/glossary.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022, 2023 Trinity College Dublin +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG +.. Copyright (C) 1988, 1998 On-Line Applications Research Corporation (OAR) + +Glossary +******** + +.. glossary:: + :sorted: + + API + This term is an acronym for Application Programming Interface. + + assembler language + The assembler language is a programming language which can be translated very + easily into machine code and data. For this project assembler languages are + restricted to languages accepted by the :term:`GNU` assembler + program for the target architectures. + + C language + The C language for this project is defined in terms of + :term:`C11`. + + C11 + The standard ISO/IEC 9899:2011. + + CCB + This term is an acronym for Change Control Board. + + Doorstop + `Doorstop <https://github.com/doorstop-dev/doorstop>`_ is a + requirements management tool. + + EARS + This term is an acronym for Easy Approach to Requirements Syntax. + + ELF + This term is an acronym for + `Executable and Linkable Format <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format>`_. + + formal model + A model of a computing component (hardware or software) that has a + mathematically based :term:`semantics`. + + GCC + This term is an acronym for `GNU Compiler Collection <https://gcc.gnu.org/>`_. + + GNAT + *GNAT* is the :term:`GNU` compiler for Ada, integrated into the + :term:`GCC`. + + GNU + This term is an acronym for `GNU's Not Unix <https://www.gnu.org/>`_. + + interrupt service + An *interrupt service* consists of an + :term:`Interrupt Service Routine` which is called with a user + provided argument upon reception of an interrupt service request. The + routine is invoked in interrupt context. Interrupt service requests may have + a priority and an affinity to a set of processors. An *interrupt service* is + a :term:`software component`. + + Interrupt Service Routine + An ISR is invoked by the CPU to process a pending interrupt. + + ISVV + This term is an acronym for Independent Software Verification and Validation. + + Linear Temporal Logic + This is a logic that states properties about (possibly infinite) sequences of + states. + + LTL + This term is an acronym for :term:`Linear Temporal Logic`. + + refinement + A *refinement* is a relationship between a specification and its + implementation as code. + + reification + Another term used to denote :term:`refinement`. + + ReqIF + This term is an acronym for + `Requirements Interchange Format <https://www.omg.org/spec/ReqIF/About-ReqIF/>`_. + + RTEMS + This term is an acronym for Real-Time Executive for Multiprocessor Systems. + + scenario + In the context of formal verification, in a setting that involves many + concurrent tasks that interleave in arbitrary ways, a scenario describes a + single specific possible interleaving. One interpretation of the behaviour + of a concurrent system is the set of all its scenarios. + + semantics + This term refers to the meaning of text or utterances in some language. In a + software engineering context these will be programming, modelling or + specification languages. + + software component + This term is defined by ECSS-E-ST-40C 3.2.28 as a "part of a software + system". For this project a *software component* shall be any of the + following items and nothing else: + + * :term:`software unit` + + * explicitly defined :term:`ELF` symbol in a + :term:`source code` file + + * :term:`assembler language` data in a source code file + + * :term:`C language` object with static storage duration + + * C language object with thread-local storage duration + + * :term:`thread` + + * :term:`interrupt service` + + * collection of *software components* (this is a software architecture + element) + + Please note that explicitly defined ELF symbols and assembler language + data are considered a software component only if they are defined in a + :term:`source code` file. For example, this rules out symbols + and data generated as side-effects by the toolchain (compiler, assembler, + linker) such as jump tables, linker trampolines, exception frame information, + etc. + + software product + The *software product* is the :term:`RTEMS` real-time operating system. + + software unit + This term is defined by ECSS-E-ST-40C 3.2.24 as a "separately compilable + piece of source code". For this project a *software unit* shall be any of + the following items and nothing else: + + * :term:`assembler language` function in a + :term:`source code` file + + * :term:`C language` function (external and internal linkage) + + A *software unit* is a :term:`software component`. + + source code + This project uses the *source code* definition of the + `Linux Information Project <http://www.linfo.org/source_code.html>`_: + "Source code (also referred to as source or code) is the version of + software as it is originally written (i.e., typed into a computer) by a + human in plain text (i.e., human readable alphanumeric characters)." + + target + The system on which the application will ultimately execute. + + task + This project uses the + `thread definition of Wikipedia <https://en.wikipedia.org/wiki/Thread_(computing)>`_: + "a thread of execution is the smallest sequence of programmed + instructions that can be managed independently by a scheduler, which is + typically a part of the operating system." + + It consists normally of a set of registers and a stack. The scheduler + assigns processors to a subset of the ready tasks. The terms task and + :term:`thread` are synonym in RTEMS. The term task is used + throughout the Classic API, however, internally in the operating system + implementation and the POSIX API the term thread is used. + + A *task* is a :term:`software component`. + + thread + This term has the same meaning as :term:`task`. + + YAML + This term is an acronym for `YAML Ain't Markup Language <https://yaml.org/>`_. diff --git a/eng/index.rst b/eng/index.rst index ed314a9..e4712ae 100644 --- a/eng/index.rst +++ b/eng/index.rst @@ -11,8 +11,9 @@ RTEMS Software Engineering (|version|) .. topic:: Copyrights and License - | |copy| 2018, 2019 embedded brains GmbH - | |copy| 2018, 2019 Sebastian Huber + | |copy| 2022 Trinity College Dublin + | |copy| 2018, 2020 embedded brains GmbH & Co. KG + | |copy| 2018, 2020 Sebastian Huber | |copy| 1988, 2015 On-Line Applications Research Corporation (OAR) .. include:: ../common/license.rst @@ -27,14 +28,18 @@ RTEMS Software Engineering (|version|) mission stakeholders prequalification - req-eng + req/index management test-plan test-framework + fv/index + build-system release-mgmt users-manuals license-requirements appendix-a + fv/appendix-fv function_and_variable concept + glossary zreferences diff --git a/eng/issue-tracking.rst b/eng/issue-tracking.rst index 1039b41..790ae83 100644 --- a/eng/issue-tracking.rst +++ b/eng/issue-tracking.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2018 Joel Sherill diff --git a/eng/license-requirements.rst b/eng/license-requirements.rst index 44814b1..537b45e 100644 --- a/eng/license-requirements.rst +++ b/eng/license-requirements.rst @@ -9,8 +9,10 @@ Licensing Requirements ********************** All artifacts shall adhere to RTEMS Project licensing -requirements. Currently, the preferred licenses are CC-BY-SA-4.0 license -for documentation and "Two Paragraph BSD" for source code. +requirements. Currently, the preferred licenses are: + +* "Two Clause BSD" (BSD-2-Clause) for source code, and +* CC-BY-SA-4.0 license for documentation Historically, RTEMS has been licensed under the GPL v2 with linking exception (https://www.rtems.org/license). It is preferred that new @@ -19,7 +21,110 @@ previously submitted code to RTEMS under a historical license, please grant the project permission to relicense. See https://devel.rtems.org/ticket/3053 for details. -TBD - Convert the following to Rest and insert into this file -TBD - https://devel.rtems.org/wiki/Developer/Coding/Conventions#Licenses +For example templates for what to include in source code and +documentation, see :ref:`FileHeaderCopyright`. + + +Rationale +--------- +.. COMMENT: Thanks to Gedare Bloom for his 2013 blog which +.. COMMENT: discussed the rationale for RTEMS License section. +.. COMMENT: http://gedare-csphd.blogspot.com/2013/05/software-licenses-with-rtems.html + +RTEMS is intended for use in real-time embedded systems in which the +application is statically linked with the operating system and all +support libraries. Given this use case, the RTEMS development team +evaluated a variety of licenses with with the goal of promoting use +while protecting both users and the developers. + +Using the GNU General Public License Version 2 (GPLv2) unmodified +was considered but discarded because the GPL can only be linked statically +with other GPL code. Put simply, linking your application code statically +with GPL code would cause your code to become GPL code. This would force +both licensing and redistribution requirements onto RTEMS users. This +was completely unacceptable. + +The GNU Lesser General Public License Version 2 (LGPLv2) was also +considered and deemed to not be a suitable license for RTEMS. This is +because it either requires use of a shared library that can be re-linked, +or release of the linked (application) code. This would require an +RTEMS-based embedded system to provide a "relinking kit." Again, this +license would force an unacceptable requirement on RTEMS users and deemed +unacceptable. + +Newer versions of the GPL (i.e. version 3) are completely unsuitable +for embedded systems due to the additions which add further restrictions +on end user applications. + +The historical RTEMS `License <https://www.rtems.org/license>`_ is a +modified version of the GPL version 2 that includes an exception to permit +including headers and linking against RTEMS object files statically. This +was based on the license used by GCC language runtime libraries at that +time. This license allows the static linking of RTEMS with applications +without forcing obligations and restrictions on users. + +A problem for RTEMS is there are no copyleft licenses that are compatible +with the deployment model of RTEMS. Thus, RTEMS Project has to reject any +code that uses the GPL or LGPL, even though RTEMS has historically appeared +to use the GPL itself -- but with the exception for static linking, and also +because an upstream GPL version 2 project could at any time switch to +GPL version 3 and become totally unusable. In practice, RTEMS can only +accept original code contributed under the RTEMS License and code that +has a permissive license. + +As stated above, the RTEMS Project has defined its preferred licenses. +These allow generation of documentation and software from specification +as well as allow end users to statically link with RTEMS and not incur +obligations. + +In some cases, RTEMS includes software from third-party projects. In those +cases, the license is carefully evaluated to meet the project licensing +goals. The RTEMS Project can only include software under licenses which follow +these guidelines: + +* 2- and 3-clause BSD, MIT, and other OSI-approved non-copyleft licenses + that permit statically linking with the code of different licenses + are acceptable. + +* The historical RTEMS `License <https://www.rtems.org/license>`_ is + acceptable for software already in the tree. This software is being + relicensed to BSD-2-Clause, rewritten, or removed. + +* GPL licensed code is NOT acceptable, neither is LGPL. + +* Software which is dual-licensed in a manner which prevents free use + in commercial applications is not acceptable. + +* Advertising obligations are not acceptable. + +* Some license restrictions may be permissible. These will be considered + on a case-by-case basis. See below for a list of such restrictions. + +In practice, these guidelines are not hard to follow. Critically, +they protect the freedom of the RTEMS source code and that of end users +to select the license and distribution terms they prefer for their +RTEMS-based application. + +License restrictions +-------------------- + +* Apache License 2.0 in section 4 (b) requires modified files to carry + prominent notice about performed modification. In case you modify such + file and the notice is not there yet you are required to put notice + below at the top of the modified file. If the notice is already + there you don't need to add it second time. + The notice should look: + + .. code-block:: c + + /* + * The file was modified by RTEMS contributors. + */ -TBD - Review and make sure this includes info on BSD variants + .. warning:: Do not import any project or files covered by the Apache + License 2.0 into the RTEMS project source tree without + discussing first with developers on the mailing list! + Handling of Apache License 2.0 projects is a bit + sensitive manner and RTEMS project is not prepared to + handle one kind of those projects yet. E.g. the projects + with NOTICE file present in the source tree. diff --git a/eng/management.rst b/eng/management.rst index 064559c..6a8e057 100644 --- a/eng/management.rst +++ b/eng/management.rst @@ -16,5 +16,7 @@ Software Development Management vc-users vc-authors coding + doc-guide + python-devel change-management issue-tracking diff --git a/eng/mission.rst b/eng/mission.rst index e1b0ec5..2c6aef1 100644 --- a/eng/mission.rst +++ b/eng/mission.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2015 Chris Johns .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) diff --git a/eng/preface.rst b/eng/preface.rst index f6fda0c..68c84fb 100644 --- a/eng/preface.rst +++ b/eng/preface.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH +.. Copyright (C) 2020 embedded brains GmbH & Co. KG Preface ******* diff --git a/eng/prequalification.rst b/eng/prequalification.rst index ba1840a..0d4561b 100644 --- a/eng/prequalification.rst +++ b/eng/prequalification.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2016, 2018 RTEMS Foundation, The RTEMS Documentation Project .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) @@ -15,7 +15,7 @@ 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 +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 @@ -83,8 +83,8 @@ 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 +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. diff --git a/eng/python-devel.rst b/eng/python-devel.rst new file mode 100644 index 0000000..f1502e4 --- /dev/null +++ b/eng/python-devel.rst @@ -0,0 +1,163 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. _PythonDevelGuide: + +Python Development Guidelines +***************************** + +Python is the preferred programming language for the RTEMS Tools. The RTEMS +Tools run on the host computer of an RTEMS user or maintainer. These +guidelines cover the Python language version, the source code formatting, use +of static analysis tools, type annotations, testing, code coverage, and +documentation. There are exceptions for existing code and third-party code. +It is recommended to read the +`PEP 8 - Style Guide for Python Code <https://www.python.org/dev/peps/pep-0008/>`_ +and the +`Google Python Style Guide <http://google.github.io/styleguide/pyguide.html>`_. + +Python Language Versions +======================== + +Although the official end-of-life of Python 2.7 was on January 1, 2020, the +RTEMS Project still cares about Python 2.7 compatibility for some tools. Every +tool provided by the RTEMS Project which an RTEMS user may use to develop +applications with RTEMS should be Python 2.7 compatible. Examples are the +build system, the RTEMS Source Builder, and the RTEMS Tester. The rationale is +that there are still some maintained Linux distributions in the wild which ship +only Python 2.7 by default. An example is CentOS 7 which gets maintenance +updates until June 2024. Everything an RTEMS maintainer uses should be written +in Python 3.6. + +Python Code Formatting +====================== + +Good looking code is important. Unfortunately, what looks good is a bit +subjective and varies from developer to developer. Arguing about the code +format is not productive. Code reviews should focus on more important topics, +for example functionality, testability, and performance. Fortunately, for +Python there are some good automatic code formatters available. All new code +specifically developed for the RTEMS Tools should be piped through the +`yapf <https://github.com/google/yapf>`_ Python code formatter before it is +committed or sent for review. Use the default settings of the tool +(`PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ coding style). + +You can disable the automatic formatting by the tool in a region starting with +the ``#yapf: disable`` comment until the next ``# yapf: enable`` comment, for +example + +.. code-block:: python + + # yapf: disable + FOO = { + # ... some very large, complex data literal. + } + + BAR = [ + # ... another large data literal. + ] + # yapf: enable + +For a single literal, you can disable the formatting like this: + +.. code-block:: python + + BAZ = { + (1, 2, 3, 4), + (5, 6, 7, 8), + (9, 10, 11, 12), + } # yapf: disable + +Static Analysis Tools +===================== + +Use the ``flake8`` and ``pylint`` static analysis tools for Python. Do not +commit your code or send it for review if the tools find some rule +violations. Run the tools with the default configuration. If you have +problems to silence the tools, then please ask for help on the :r:list:`devel`. +Consult the tool documentation to silence false positives. + +Type Annotations +================ + +For Python 3.6 or later code use type annotations. All public functions of +your modules should have `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ +type annotations. Check for type issues with the +`mypy <http://mypy-lang.org/>`_ static type checker. + +Testing +======= + +Write tests for your code with the +`pytest <https://docs.pytest.org/en/latest/contents.html>`_ framework. Use the +`monkeypatch <https://docs.pytest.org/en/latest/monkeypatch.html>`_ mocking +module. Do not use the standard Python ``unittest`` and ``unittest.mock`` +modules. Use ``coverage run -m pytest`` to run the tests with code coverage +support. If you modify existing code or contribute new code to a subproject +which uses tests and the code coverage metric, then do not make the code +coverage worse. + +Test Organization +----------------- + +Do not use test classes to group tests. Use separate files instead. Avoid +deep test directory hierarchies. For example, place tests for +:file:`mymodule.py` in :file:`tests/test_mymodule.py`. For class-specific +tests use: + +* ``mymodule.py:class First`` :math:`\rightarrow` + :file:`tests/test_mymodule_first.py` + +* ``mymodule.py:class Second`` :math:`\rightarrow` + :file:`tests/test_mymodule_second.py` + +* ``mymodule.py:class Third`` :math:`\rightarrow` + :file:`tests/test_mymodule_third.py` + +You can also group tests in other ways, for example: + +* :file:`mymodule.py` :math:`\rightarrow` :file:`tests/test_mymodule_input.py` + +* :file:`mymodule.py` :math:`\rightarrow` :file:`tests/test_mymodule_output.py` + +Documentation +============= + +Document your code using the +`PEP 257 - Docstring Conventions <https://www.python.org/dev/peps/pep-0257/>`_. +Contrary to PEP 257, use the descriptive-style +(``"""Fetches rows from a Bigtable."""``) instead of imperative-style +(``"""Fetch rows from a Bigtable."""``) as recommended by +`Comments and Docstrings - Functions and Methods <http://google.github.io/styleguide/pyguide.html#383-functions-and-methods>`_. +Use the +`Sphinx <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_ +format. The +`sphinx-autodoc-typehints <https://pypi.org/project/sphinx-autodoc-typehints/>`_ +helps to reuse the type annotations for the documentation. Test code does not +need docstrings in general. + +Existing Code +============= + +Existing code in the RTEMS Tools may not follow the preceding guidelines. The +RTEMS Project welcomes contributions which bring existing code in line with the +guidelines. Firstly, run the ``yapf`` code formatter through the existing code +of interest. Add ``# yapf: disable`` comments to avoid reformatting in some +areas if it makes sense. If the existing code has no unit tests, then add unit +tests before you modify existing code by hand. With the new unit tests aim at +a good code coverage especially in the areas you intend to modify. While you +review the code add docstrings. Run the static analysers and fix the rule +violations. Please keep in mind that also trivial modifications can break +working code. Make sure you have some unit tests. Add type annotations unless +the code should be Python 2.7 compatible. Concentrate on the public +interfaces. + +Third-Party Code +================ + +Try to not modify imported third-party code. In case there are issues with +third-party code, then at least write a bug report or otherwise contact the +upstream project. Reimport the third-party code after the issue is fixed in +the upstream project. Only temporarily modify imported third-party code until +a solution integrated in the upstream is available. diff --git a/eng/release-mgmt.rst b/eng/release-mgmt.rst index 6706d62..ff97d19 100644 --- a/eng/release-mgmt.rst +++ b/eng/release-mgmt.rst @@ -7,11 +7,9 @@ Software Release Management *************************** -TBD write content - - .. COMMENT: Subsections .. toctree:: + release-process change-reports vdd-generation diff --git a/eng/release-process.rst b/eng/release-process.rst new file mode 100644 index 0000000..7c250ea --- /dev/null +++ b/eng/release-process.rst @@ -0,0 +1,455 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Contemporary Software +.. Copyright (C) 2020 Chris Johns + +.. _Release_Process: + +Release Process +*************** + +The release process creates an RTEMS release. The process has a number of +stages that happen before a release can be made, during the creation of the +release and after the release has been made. + +Releases +======== + +RTEMS is released as a collection of ready to use source code and built +documentation. Releases are publicly available on the RTEMS servers under +https://ftp.rtems.org/pub/rtems/releases. + +Releases are group under the major version number as a collection of +directories consisting of the version number. This is termed a release +series. A release may also contain release snapshots. + +All releases must have a three digit version number and this can be optionally +followed by a dash character (``-``) and an identifier, e.g. ``5.1.0-acme-1``. + +The RTEMS Project reserves releases with only the three digit version number, +e.g. ``5.1.0``. This identifies an RTEMS Project release. + +Release Layout +-------------- + +* All released source archives are XZ compressed tar files. + +* Top level contains: + +:file:`README.txt`: + A set of brief release instructions. + +:file:`contrib`: + Contributed sources. For example the release scripts used to create the + release. + +:file:`docs`: + Compressed documentation build in HTML, Single page HTML and PDF + formats. Provide compressed files for each document and a single archive + of all the documentation. Provide an SHA512 check sum file. + +:file:`rtems-<VERSION>-release-notes.pdf`: + RTEMS Release notes document the changes in a release. This is a capture + of the Trac report for the release's milestone in PDF format. + +:file:`sha512sum.txt`: + SHA512 checksum of all files in this directory. + +:file:`sources`: + All source code referenced by the release. + +Release Version Numbering +------------------------- + +The release numbering scheme changed with RTEMS 5. + +The master branch has the version N.0.0 with N being the next major release +number. The release branch in a repository will be just the major number. + +The first release of this series will have the version number N.1.0. The first +bugfix release (minor release) of this series will have the version number +N.2.0. + +The release branch will have the version number N.M.1 with M being the last +minor release of this series. Tools will use N as the version number and must +be compatible with all releases and the release branch of the N series. + +Examples: + + - ``5.0.0`` is the version number of the development master for the 5 series + + - ``5.1.0`` is the first release of the 5 series + + - ``5.1.1`` is the version number of the 5 series release branch right after + the 5.1.0 release until 5.2.0 is released + + - ``5.2.0`` is the first bugfix release of the 5 series + + - ``5.2.1`` is the version number of the 5 series release branch right after + the 5.2.0 release until 5.3.0 is released + + - ``6.0.0`` is the version number of the development master for the 6 series + +Release Scripts +---------------- + +* The release scripts are held in the top level repository + https://git.rtems.org/rtems-release.git. + +* The scripts are written for FreeBSD and can run on FreeBSD 10 through + FreeBSD 12. No other host operating system is supported for the release + scripts. Updates are welcome if the changes do not affect the operation on + FreeBSD. + +* A Python ``virutalenv`` environment is required for a working Sphinx + documentation building environment. Follow the procedure in the + ``rtems-docs.git`` top level ``README`` file. + +* Building a standard release requires you provide the release major number + and the release's remaining version string including any additional + identifiers: + + .. code-block:: none + + ./rtems-release 5 1.0 + + To create a release snapshot: + + .. code-block:: none + + ./rtems-release 5 0.0-m2003 + +* A 3rd option of a release URL can be provided to create a test or deployable + release. The URL is a base path the RSB uses to download the release source + files from: + + .. code-block:: none + + ./rtems-release \ + -u https://ftp.rtems.org/pub/rtems/people/chrisj/releases \ + 5 0.0-m2003-2 + +* Building the release notes requires the Web Toolkit HTML to PDF converter be + installed. The FreeBSD package is ``wkhtmltopdf``. + +Release Snapshots +----------------- + +* Release snapshots are only created for the current development version of + RTEMS. For example RTEMS 5 snapshot path is :file:`5/5.0.0/5.0.0-m2003`. + +* Release snapshots are based on the development sources and may be unstable or + not suitable for use in production. + +* A release snapshot is created each month and is named as + ``<major>/<version>/<version>-<YYMM>`` where ``YY`` is the last two digits of + the current year and ``MM`` is the month as a two digit number. + +* In the lead up to a release more than one snapshot can be created by + appending ``-<count>`` to the snapshot version string where ``<count>`` is + incremented starting from ``1``. The first snapshot without a count is + considered number ``0``. + +* Release snapshots maybe removed from the RTEMS servers at the discretion of + the RTEMS project + +Release Repositories +==================== + +The following are the repositories that a release effects. Any repository +action is to be performed in the following repositories: + +* ``rtems.git`` + +* ``rtems-central.git`` + +* ``rtems-docs.git`` + +* ``rtems-examples.git`` + +* ``rtems-libbsd.git`` + +* ``rtems-release.git`` + +* ``rtems-source-builder.git`` + +* ``rtems-tools.git`` + +* ``rtems_waf.git`` + +Pre-Release Procedure +===================== + +* All tickets must be resolved, closed or moved to a later + milestone. Tickets can exist that are specific to the branch and are + to be resolved before the first release is made. + +* Create release snapshots and post suitable build and test results. + +Release Branching +================= + +A release has a release branch in each of the release repositories. A +release is a created from a release branch. The release branch label +is the RTEMS major version number. + +LibBSD Release Branch +--------------------- + +The ``rtems-libbsd.git`` is an exception as it has two active release +branches. The repository has a release branch based on the ``master`` +like all the release repositories and it can have a FreeBSD version +specific release branch that is used in the release. + +LibBSD runs two branches during it's development cycle. The ``master`` +branch tracks the FreeBSD ``master`` branch. This means LibBSD tracks +FreeBSD's development. LibBSD also tracks a FreeBSD branch for the +RTEMS release. For example RTEMS 5 tracks FreeBSD 12 as it's release +base. This provides functionaly stability to the RTEMS 5 release by +allowing a control process to track bug fixes in FreeBSD 12. + +Pre-Branch Procedure +-------------------- + +* All tickets assigned to the release's first milestone must be + resolved. Tickets can exist that are specific to the branch and are + to be resolved before the first release is made. + +* The following BSP must build using the RSB: + + - ``arm/beagleboneblack`` + +* Check and make sure the RSB kernel, libbsd and tools configurations + reference the ``master`` when the branch is made. + + The RSB Git builds reference a specific commit so it is important + the relevant configurations are valid. + +Branch Procedure +---------------- + +* Branch labels are the major number as branch releases increment the minor + number. A branch is only created when the first major release is made. + + The commands to set a remote branch for a release in a repository are: + + .. code-block:: none + + git clone <URL>/<REPO> <REPO> + cd <REPO> + git checkout -b <VERSION> origin/master + git push origin <VERSION> + + Example: + + .. code-block:: none + + git clone ssh://chrisj@dispatch.rtems.org/data/git/rtems.git rtems.git + cd rtems.git + git checkout -b 5 origin/master + git push origin 5 + +* Check and make sure the RSB kernel, libbsd and tools reference the + branch commit. + +Post-Branch Procedure +--------------------- + +#. Create a release page for the next RTEMS release in Trac. + +#. Update the releases table. The page link is: + + https://devel.rtems.org/wiki/Release + + Update the table adding the new development release to the top + moving down the previous releases. + + Label the new release branch as "Releasing". The documentation link + is left pointing to ``master`` until the release is made and the + documentation is installed on the RTEMS Documentation web site. + +#. Update the release table in the front page of the Trac Wiki. The + page link is: + + https://devel.rtems.org/wiki/ + +#. Add the milestones for the new development branch. The Trac page + is: + + .. code-block:: none + + = 6.1 (open) + + == Statistics + + || '''Total'''||[[TicketQuery(milestone=6.1,count)]] || + || Fixed||[[TicketQuery(status=closed&milestone=6.1,resolution=fixed,count,)]] || + || Invalid||[[TicketQuery(status=closed&milestone=6.1,resolution=invalid,count,)]] || + || Works for me||[[TicketQuery(status=closed&milestone=6.1,resolution=worksforme,count,)]] || + || Duplicate||[[TicketQuery(status=closed&milestone=6.1,resolution=duplicate,count,)]] || + || Won't fix||[[TicketQuery(status=closed&milestone=6.1,resolution=wontfix,count,)]] || + + == Distribution + [[TicketQuery(milestone=6.1&group=type,format=progress)]] + + == Summary + [[TicketQuery(milestone=6.1)]] + + == Details + [[TicketQuery(col=id|time|resolution|component|reporter|owner|changetime,status=closed&milestone=6.1,rows=summary|description,table)]] + + Replace ``6.1`` with the required milestone. + +#. Create the RC1 release candidate with the source as close the + branch point as possible. + +#. Create a ticket to the clean the RSB for the release. The RSB's + ``master`` branch carries a number of older configurations and new + release configurations. These can be confusing to a new user and + add no value to a released RSB. For example leaving RTEMS 6 tool + building configurations in the RTEMS 5 release. + +#. Check out the release branch of ``rtems-central.git``. Change all Git + submodules to reference commits of the corresponding release branch. Run + ``./spec2modules.py``. Inspect all Git submodules for changes. If there + are locally modified files, then there are two options. Firstly, integrate + the changes in the release branches. Afterwards update the Git submodule + commit. Secondly, change the specification so that a particular change is + not made. Make sure that there are no changes after this procedure. + +Post-Branch Version Number Updates +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After the release repositored have been branched the ``master`` branch +has to have the major version number updated. The follow is a list of +the needed changes. + +#. RTEMS requires the following files be changed: + + * :file:`Doxyfile`: Update ``PROJECT_NUMBER``. + + * :file:`rtems-bsps`: Update ``rtems_version``. + + * :file:`spec/build/cpukit/optvermaj.yml`: Update ``set-value``. + + * :file:`spec/build/cpukit/optvermin.yml`: Update ``set-value``. + + * :file:`spec/build/cpukit/optverrev.yml`: Update ``set-value``. + + * :file:`wscript`: Update ``default_prefix``. + +#. RTEMS Documentation the following files be changed: + + * :file:`wscript`: Update ``rtems_major_version``. + +#. RSB requires the following files be changed: + + * :file:`source-builder/sb/version.py`: Update ``_version``. + +#. RTEMS Tools requires the following files be changed: + + * :file:`config/rtems-version.ini`: Update ``revision``. + + * :file:`tester/rtems/version.cfg`: Update ``rtems_version``. + +#. ``rtems-libbsd`` requires the following files and branches be changed: + + * :file:`README.md`: Update ``Branches`` section. + + * :file:`wscript`: Update ``rtems_version``. + + * Create a new branch for tracking the FreeBSD stable version, for example + ``6-freebsd-12``. + +#. ``rtems-examples`` requires the following files be changed: + + * :file:`wscript`: Update ``rtems_version``. + +Release Procedure +================= + +The release procedure can be performed on any FreeBSD machine and uploaded to +the RTEMS FTP server. You will need ssh access to the RTEMS server +``dispatch.rtems.org`` and suitable permissions to write into the FTP release +path on the RTEMS server. + +#. The release process starts by branching the repositories. To branch + run the script: + + .. code-block:: none + + ./rtems-release-branch [-p] <USER> <VERSION> <REVISION> + + Example: + + .. code-block:: none + + cd + mkdir -p development/rtems/releases + cd development/rtems/releases + git clone git://git.rtems.org/rtems-release.git rtems-release.git + cd rtems-release.git + ./rtems-release-branch -p chrisj 5 + + You need to have suitable commit access to the repositories. + +#. To create the RTEMS release run the release script: + + .. code-block:: none + + ./rtems-release <VERSION> <REVISION> + + Example: + + .. code-block:: none + + ./rtems-release 5 1.0 + +#. Copy the release to the RTEMS FTP server: + + .. code-block:: none + + ssh <user>@dispatch.rtems.org mkdir -p /data/ftp/pub/rtems/releases/<VERSION> + scp -r <VERSION>.<REVISION> <user>@dispatch.rtems.org:/data/ftp/pub/rtems/releases/<VERSION>/. + + Example: + + .. code-block:: none + + ssh chrisj@dispatch.rtems.org mkdir -p /data/ftp/pub/rtems/releases/5 + scp -r 5.1.0 chrisj@dispatch.rtems.org:/data/ftp/pub/rtems/releases/5/. + +#. Verify the release has been uploaded by checking the link: + + https://ftp.rtems.org/pub/rtems/releases/<VERSION>/<VERSION>.<REVISION> + +#. Tag the release repositories with the following command: + + .. code-block:: none + + git checkout -b origin/<VERSION> + git tag <TAG> + git push origin <TAG> + + Example: + + .. code-block:: none + + git clone ssh://chrisj@dispatch.rtems.org/data/git/rtems.git rtems.git + cd rtems.git + git checkout -b origin/5 + git tag 5.1.0 + git push origin 5.1.0 + +Post-Release Procedure +====================== + +The following procedures are performed after a release has been created. + +#. Update the release to the RTEMS servers: + + .. code-block:: none + + rsync --rsh=ssh -arv 5.1.0 chrisj@dispatch.rtems.org:/data/ftp/pub/rtems/releases/5/. + +#. Test a build of the ``beagleboneblack`` BSP. diff --git a/eng/req-eng.rst b/eng/req-eng.rst deleted file mode 100644 index 61b82be..0000000 --- a/eng/req-eng.rst +++ /dev/null @@ -1,1177 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019 embedded brains GmbH - -.. |E40| replace:: ECSS-E-ST-40C - -.. |E10-06| replace:: ECSS-E-ST-10-06C - -.. _ReqEng: - -Software Requirements Engineering -********************************* - -Software engineering standards for critical software such as |E40| demand that -software requirements for a software product are collected in a software -requirements specification (technical specification in |E40| terms). They are -usually derived from system requirements (requirements baseline in |E40| -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 :cite:`Motorola:1988:RTEID` and -later the ORKID :cite:`VITA:1990:ORKID` 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 -:term:`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. - -.. topic:: 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. - -Requirements for Requirements -============================= - -.. _ReqEngIdent: - -Identification --------------- - -Each requirement shall have a unique identifier (UID). The question is in -which scope should it be unique? Ideally, it should be universally unique. As -a best effort approach, the name *RTEMS* shall be used as a part in all -requirement identifiers. This should ensure that the RTEMS requirements can be -referenced easily in larger systems. The standard ECSS-E-ST-10-06C recommends -in section 8.2.6 that the identifier should reflect the type of the requirement -and the life profile situation. Other standards may have other -recommendations. To avoid a bias of RTEMS in the direction of ECSS, this -recommendation will not be followed. - -.. topic:: Doorstop - - The UID of an item (requirement) is defined by its file name without the - extension. An UID consists of two parts, the prefix and a name or a number. - The parts are divided by an optional separator. The prefix is determined by - the document. - -The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or -more component names, and a name. Each part is separated by a "-" -character. For example, the UID RTEMS-CLASSIC-TASK-CREATERRINVADDR may specify -that the `rtems_task_create()` directive shall return a status of -`RTEMS_INVALID_ADDRESS` if the `id` parameter is `NULL`. - -.. topic:: Doorstop - - Doorstop uses documents to create namespaces (named a prefix in Doorstop). - For the example above, you can create the documents like this: - - .. code-block:: none - - doorstop create -s - RTEMS-CLASSIC -p RTEMS spec/classic - doorstop create -s - RTEMS-CLASSIC-TASK -p RTEMS-CLASSIC spec/classic/task - doorstop create -s - RTEMS-CLASSIC-SEMAPHORE -p RTEMS-CLASSIC spec/classic/semaphore - - The requirement files are organized in directories. - -A initial requirement item hierarchy could be this: - -* RTEMS - - * BUILD (building RTEMS BSPs and libraries) - - * CONFIG (application configuration) - - * CLASSIC - - * TASK - - * CREAT* (requirements for `rtems_task_create()`) - * DELT* (requirements for `rtems_task_delete()`) - * EXIT* (requirements for `rtems_task_exit()`) - * GETAFF* (requirements for `rtems_task_get_affinity()`) - * GETPRI* (requirements for `rtems_task_get_priority()`) - * GETSHD* (requirements for `rtems_task_get_scheduler()`) - * IDNT* (requirements for `rtems_task_ident()`) - * ISSUSP* (requirements for `rtems_task_is_suspended()`) - * ITER* (requirements for `rtems_task_iterate()`) - * MODE* (requirements for `rtems_task_mode()`) - * RESTRT* (requirements for `rtems_task_restart()`) - * RESUME* (requirements for `rtems_task_resume()`) - * SELF* (requirements for `rtems_task_self()`) - * SETAFF* (requirements for `rtems_task_set_affinity()`) - * SETPRI* (requirements for `rtems_task_set_priority()`) - * SETSHD* (requirements for `rtems_task_set_scheduler()`) - * START* (requirements for `rtems_task_start()`) - * SUSP* (requirements for `rtems_task_suspend()`) - * WKAFT* (requirements for `rtems_task_wake_after()`) - * WKWHN* (requirements for `rtems_task_wake_when()`) - - * Semaphore - - * ... - - * POSIX - - * ... - -A more detailed naming scheme and guidelines should be established. We have to -find the right balance between the length of UIDs and self-descriptive UIDs. A -clear scheme for all Classic API managers may help to keep the UIDs short and -descriptive. - -The specification of the validation of requirements should be maintained also by -Doorstop. For each requirement document there should be a validation child -Doorstop document with a *TEST* component name, e.g. RTEMS-CLASSIC-TASK-TEST. A -test document may contain also validations by analysis, by inspection, and by -design, see :ref:`ReqEngValidation`. - -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 :cite:`RFC2119` and |E10-06| :cite:`ECSS_E_ST_10_06C`. - -Absolute Requirements -~~~~~~~~~~~~~~~~~~~~~ - -Absolute requirements shall be expressed with the verbal form *shall* and no -other terms. - -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. - -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. - -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.) - -Possibilities and Capabilities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Possibilities and capabilities shall be expressed with the verbal form *can* -and no other terms. - -.. _ReqEngSyntax: - -Syntax ------- - -Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate -requirements. A recommended reading list to get familiar with this approach is -:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and -:cite:`Mavin:2016:LLEARS`. Please also have a look at the EARS quick reference -sheet :cite:`Uusitalo:2012:EARS`. 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). - -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 :cite:`Wiegers:2013:SR`. 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. - -Separate Requirements ---------------------- - -Requirements shall be stated separately. A bad example is: - -RTEMS-CLASSIC-TASK-CRAT - The task create directive shall evaluate the parameters, allocate a task - object and initialize it. - -To make this a better example, it should be split into separate requirements: - -RTEMS-CLASSIC-TASK-CRAT - When the task create directive is called with valid parameters and a free - task object exists, the task create directive shall assign the identifier of - an initialized task object to the id parameter and return the - RTEMS_SUCCESSFUL status. - -RTEMS-CLASSIC-TASK-CRATERRTOOMANY - If no free task objects exists, the task create directive shall return the - RTEMS_TOO_MANY status. - -RTEMS-CLASSIC-TASK-CRATERRINVADDR - If the id parameter is NULL, the task create directive shall return the - RTEMS_INVALID_ADDRESS status. - -RTEMS-CLASSIC-TASK-CRATERRINVNAME - If the name parameter is not valid, the task create directive shall return - the RTEMS_INVALID_NAME status. - - ... - -Conflict Free Requirements --------------------------- - -Requirements shall not be in conflict with each other inside a specification. -A bad example is: - -RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT - If a mutex is not available, the mutex obtain directive shall enqueue the - calling thread on the wait queue of the mutex. - -RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT - If a mutex is not available, the mutex obtain directive shall return the - RTEMS_UNSATISFIED status. - -To resolve this conflict, a condition may be added: - -RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT - If a mutex is not available, when the RTEMS_WAIT option is set, the mutex - obtain directive shall enqueue the calling thread on the wait queue of the - mutex. - -RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT - If a mutex is not available, when the RTEMS_WAIT option is not set, the - mutex obtain directive shall return the RTEMS_UNSATISFIED status. - -Use of Project-Specific Terms and Abbreviations ------------------------------------------------ - -All project-specific terms and abbreviations used to formulate requirements -shall be defined in the project glossary. - -.. _ReqEngJustReq: - -Justification of Requirements ------------------------------ - -Each requirement shall have a rationale or justification recorded in a -dedicated section of the requirement file. - -.. topic:: Doorstop - - See *rationale* attribute for :ref:`ReqEngSpecItems`. - -.. _ReqEngSpecItems: - -Specification Items -=================== - -The technical specification of RTEMS will contain requirements, specializations -of requirements, :ref:`test procedures <ReqEngTestProcedure>`, -:ref:`test suites <ReqEngTestSuite>`, :ref:`test cases <ReqEngTestCase>`, and -:ref:`requirement validations <ReqEngValidation>`. These things will be called -*specification items* or just *items* if it is clear from the context. - -.. topic:: Doorstop - - Doorstop maintains *items* which are included in *documents*. The normal - use case is to store a requirement with meta-data in an item. However, - items can be also used to store other things like test procedures, test - suites, test cases, and requirement validations. Items contain key-value - pairs called attributes. Specializations of requirements may contain extra - attributes, e.g. interface, build, configuration requirements. All items - have the following standard Doorstop attributes: - - active - A boolean value which indicates if the requirement is active or not. - The value is included in the fingerprint via a document configuration - option. - - derived - A boolean value which indicates if the requirement is derived or not. - For the - `definition of derived <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#derived>`_. - see the Doorstop documentation. For RTEMS, this value shall be false - for all requirements. The value is not included in the fingerprint. - - normative - A boolean value which indicates if the requirement is normative or not. - For the - `definition of normative <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#normative>`_. - see the Doorstop documentation. For RTEMS, this value shall be true - for all requirements. The value is not included in the fingerprint. - - level - Indicates the presentation order within a document. For RTEMS, this - value shall be unused. The value is not included in the fingerprint. - - header - A header for an item. For RTEMS, this value shall be the empty string. - The value is not included in the fingerprint. - - reviewed - The fingerprint of the item. Maintain this attribute with the - `doorstop clear` command. - - links - The links from this item to parent items. Maintain this attribute with - the `doorstop link` command. The value is included in the fingerprint. - - ref - References to files and directories. See - `#365 <https://github.com/jacebrowning/doorstop/issues/365>`_, - The value is included in the fingerprint. - - text - The item text. The value is included in the fingerprint. - - All specification items shall have the following extended attributes: - - type: - A list of :ref:`item types <ReqEngItemTypes>`. The value is not - included in the fingerprint. - - enabled-by: - The value is a list of expressions. The value is included in the - fingerprint. An expression is an operator or an option. An option - evaluates to true if it is included the set of enabled options of the - configuration. An operator is a dictionary with exactly one key and a - value. Valid keys are `and`, `or`, and `not`: - - * The value of the `and` operator shall be a list of expressions. It - evaluates to the `logical and` of all outcomes of the expressions in - the list. - - * The value of the `or` operator shall be a list of expressions. It - evaluates to the `logical or` of all outcomes of the expressions in - the list. - - * The value of the `not` operator shall be an expression. It negates - the outcome of its expression. - - The outcome of a list of expressions without an operator is the - `logical or` of all outcomes of the expressions in the list. An empty - list evaluates to true. Examples: - - .. code-block:: none - - enabled-by: - - RTEMS_SMP - - .. code-block:: none - - enabled-by: - - and: - - RTEMS_NETWORKING - - not: RTEMS_SMP - - .. code-block:: none - - enabled-by: - - and: - - not: TEST_DEBUGGER01_EXCLUDE - - or: - - arm - - i386 - -.. _ReqEngItemTypes: - -Item Types ----------- - -Specification items can have all sorts of *types*. The selection of types and -the level of detail depends on a particular standard and product model. We need -enough flexibility to be in line with ECSS-E-ST-10-06 and possible future -applications of other standards. Each item may have a list of types. Valid -types are listed below. This list may change over time. If new types are -added, then a mapping between types should be specified. The item types and -their definition is work in progress. A list of types follows: - -* requirement - - * functional - Functional requirements shall describe the behaviour of the - software product under specific conditions. - - * *capability* - - * *dependability-function* - - * *function* - - * *operational* - Operational requirements shall - - * define the operation modes (e.g. initialization, multitasking, termination), - - * describe the operation modes, and - - * describe the operation mode transitions. - - * *safety-function* - - * non-functional - - * *build-configuration* - - * *constraint* - - * *design* - - * *interface* - - * *interface-requirement* - - * *maintainability* - - * *performance* - - * *portability* - - * *quality* - - * *reliability* - - * *resource* - - * *safety* - -* *test-procedure* - -* *test-suite* - -* *test-case* - -* *validation-by-analysis* - -* *validation-by-inspection* - -* *validation-by-review-of-design* - -* *validation-platform* - -.. image:: ../images/eng/req-spec-items.* - :scale: 70 - :align: center - -Requirements ------------- - -.. topic:: Doorstop - - All requirement specification items shall have the following extended - attribute: - - rationale: - The rationale or justification of the specification item. The value is - **not** included in the fingerprint. - -Build Configuration -------------------- - -Build configuration requirements define what needs to be built (libraries, -object files, test executables, etc.) and how (configuration option header -files, compiler flags, linker flags, etc.). The goal is to generate build -files (Makefile or waf) and content for the Software Configuration File (SCF) -from it. A YAML scheme needs to be defined for this purpose. - -.. _ReqEngInterfaceReq: - -Interface Requirement ---------------------- - -Interface requirements shall describe the high level aspects of interfaces. -The item type shall be *interface-requirement*. - -.. _ReqEngInterface: - -Interface ---------- - -Interface items shall specify the interface of the software product to other -software products and the hardware. The item type shall be *interface*. The -interface items shall have an *interface-category* which is one of the -following and nothing else: - -* *application*: Application interface items shall describe the interface - between the software product and the application (:term:`API`). The goal is - to generate header files with Doxygen markup and user manual documentation - parts from the application interface specification. - -* *application-configuration*: Application configuration items shall define - parameters of the software product which can be set by the application at - link-time. The goal is to generate user manual documentation parts and test - cases from the application configuration specification. - -* *architecture*: Architecture interface items shall define the - interface between the software product and the processor architecture - (:term:`ABI`). - -* *gcc*: GCC interface items shall define the interface between the software - product and GCC components such as libgcc.a, libatomic.a, libgomp.a, - libstdc++.a, etc. - -* *hardware*: Hardware interface items shall define the interface between the - software product and the hardware. - -* *newlib*: Newlib interface items shall define the interface between the - software product and the Newlib (libc.a). - -The interface items shall have an *interface-type* which is one of the -following and nothing else: - -* *configuration-option* - -* *define* - -* *enum* - -* *function* - -* *header* - -* *macro* - -* *register-block* - -* *structure* - -* *typedef* - -* *union* - -* *variable* - -.. _ReqEngInterfaceApplicationConfig: - -Interface - Application Configuration -------------------------------------- - -.. topic:: Doorstop - - The application configuration items shall have the following attribute - specializations: - - type - The type value shall be *interface*. - - interface-category - The interface category value shall be *application-configuration*. - - interface-type - The interface type value shall be *configuration-option*. - - link - There shall be a link to a higher level requirement. - - text - The application configuration requirement. - - configuration-category: - A category to which this application configuration option belongs. - - define: - The name of the configuration define. - - data-type: - The data type of the configuration define. - - value-range: - The range of valid values. - - default-value: - The default value. - - description: - The description of the application configuration. The description - should focus on the average use-case. It should not cover potential - problems, constraints, obscure use-cases, corner cases and everything - which makes matters complicated. - - note: - Notes for this application configuration. The notes should explain - everything which was omitted from the description. It should cover all - the details. - -.. _ReqEngTestProcedure: - -Test Procedure --------------- - -Test procedures shall be executed by the Qualification Toolchain. - -.. topic:: Doorstop - - The test procedure items shall have the following attribute - specializations: - - type - The type value shall be *test-procedure*. - - text - The purpose of this test procedure. - - platform - There shall be links to validation platform requirements. - - steps - The test procedure steps. Could be a list of key-value pairs. The key - is the step name and the value is a description of the actions - performed in this step. - -.. _ReqEngTestSuite: - -Test Suite ----------- - -Test suites shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`. - -.. topic:: Doorstop - - The test suite items shall have the following attribute specializations: - - type - The type value shall be *test-suite*. - - text - The test suite description. - -.. _ReqEngTestCase: - -Test Case ---------- - -Test cases shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`. - -.. topic:: Doorstop - - The test case items shall have the following attribute specializations: - - type - The type value shall be *test-case*. - - link - The link to the requirement validated by this test case or no links if - this is a unit or integration test case. - - ref - If this is a unit test case, then a reference to the :term:`software - item` under test shall be provided. If this is an integration test - case, then a reference to the integration under test shall be provided. - The integration is identified by its Doxygen group name. - - text - A short description of the test case. - - inputs - The inputs to execute the test case. - - outputs - The expected outputs. - - The test case code may be also contained in the test case specification - item in a *code* attribute. This is subject to discussion on the RTEMS - mailing list. Alternatively, the test code could be placed directly in - source files. A method is required to find the test case specification of - a test case code and vice versa. - -.. _ReqEngResAndPerf: - -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. - -.. _ReqEngTrace: - -Traceability of Specification Items -=================================== - -The standard |E10-06| demands that requirements shall be under configuration -management, backwards-traceable and forward-traceable. Requirements are a -specialization of specification items in RTEMS. - -.. _ReqEngTraceHistory: - -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 <https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_). -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. - -.. _ReqEngTraceBackward: - -Backward Traceability of Specification Items --------------------------------------------- - -Providing backward traceability of specification items means that we must be -able to find the corresponding higher level specification item for each refined -specification item. This is a standard Doorstop feature. - -.. _ReqEngTraceForward: - -Forward Traceability of Specification Items -------------------------------------------- - -Providing forward traceability of specification items means that we must be -able to find all the refined specification items for each higher level -specification item. This is a standard Doorstop feature. The links from -parent to child specification items are implicitly defined by links from a -child item to a parent item. - -.. _ReqEngTraceReqArchDesign: - -Traceability between Software Requirements, Architecture and Design -------------------------------------------------------------------- - -The software requirements are implemented in Doorstop compatible YAML files. -The software architecture and design is written in Doxygen markup. Doxygen -markup is used throughout all header and source files. A Doxygen filter -program may be provided to place Doxygen markup in assembler files. The -software architecture is documented via Doxygen groups. Each Doxygen group -name should have a project-specific name and the name should be unique within -the project, e.g. RTEMSTopLevel\ MidLevel\ LowLevel. 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 <http://www.doxygen.nl/manual/custcmd.html>`_ -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. - -.. _ReqEngValidation: - -Requirement Validation -====================== - -The validation of each requirement shall be accomplished by one or more of -the following methods and nothing else: - -* *By test*: A :ref:`ReqEngTestCase` specification item is provided to - demonstrate that the requirement is satisfied when the software product is - executed on the target platform. - -* *By analysis*: A statement is provided how the requirement is met, by - analysing static properties of the software product. - -* *By inspection*: A statement is provided how the requirement is met, by - inspection of the :term:`source code`. - -* *By review of design*: A rationale is provided to demonstrate how the - qualification requirement is satisfied implicitly by the software design. - -Validation by test is strongly recommended. The choice of any other validation -method shall be strongly justified. The requirements author is obligated to -provide the means to validate the requirement with detailed instructions. - -.. topic:: Doorstop - - For an item in a parent document it is checked that at least one item in a - child document has a link to it. For example a child document could - contain validation items. With this feature you can check that all - requirements are covered by at least one validation item. - - The requirement validation by analysis, by inspection, and by design - specification items shall have the following attribute specializations: - - type - The type attribute value shall be *validation-by-analysis*, - *validation-by-inspection*, or *validation-by-review-of-design*. - - link - There shall be exactly one link to the validated requirement. - - text - The statement or rational of the requirement validation. - -Requirement Management -====================== - -Change Control Board --------------------- - -Working with requirements usually involves a Change Control Board -(:term:`CCB`). The CCB of the RTEMS Project is the -`RTEMS developer mailing list <https://lists.rtems.org/mailman/listinfo/devel>`_. - -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 <https://git.rtems.org/rtems/tree/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 <https://docs.rtems.org/branches/master/user/support/contrib.html#patch-review-process>`_. -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 (:term:`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. - -Add a Requirement ------------------ - -.. image:: ../images/eng/req-add.* - :scale: 70 - :align: center - -.. _ReqEngModifyRequirement: - -Modify a Requirement --------------------- - -.. image:: ../images/eng/req-modify.* - :scale: 70 - :align: center - -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 :ref:`modify a requirement -<ReqEngModifyRequirement>`. - -Tooling -======= - -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 :term:`ReqIF`. - -Tool Evaluation ---------------- - -During an evaluation phase the following tools were considered: - -* `aNimble <https://sourceforge.net/projects/nimble/>`_ -* :term:`Doorstop` -* `OSRMT <https://github.com/osrmt/osrmt>`_ -* `Papyrus <https://www.eclipse.org/papyrus/>`_ -* `ProR <https://www.eclipse.org/rmf/pror/>`_ -* `ReqIF Studio <https://formalmind.com/tools/studio/>`_ -* `Requirement Heap <https://sourceforge.net/projects/reqheap/>`_ -* `rmToo <http://rmtoo.florath.net/>`_ - -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. - -.. _ReqEngDoorstop: - -Selected Tool - Doorstop ------------------------- - -:term:`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 :term:`YAML` format. Requirements -are organized in documents and can be linked to each other -:cite:`Browning:2014:RequirementsManagement`. - -Doorstop consists of three main parts - -* a stateless command line tool `doorstop`, - -* a file format with a pre-defined set of attributes (YAML), and - -* a primitive GUI tool (not intended to be used). - -For RTEMS, its scope will be extended to manage specifications in general. The -primary reason for selecting Doorstop as the requirements management tool for -the RTEMS Project is its data format which allows a high degree of -customization. Doorstop uses a directed, acyclic graph of items. The items are -files in YAML format. Each item has a set of -`standard attributes <https://doorstop.readthedocs.io/en/latest/reference/item/>`_ -(key-value pairs). - -The use case for the standard attributes is requirements management. However, -Doorstop is capable to manage custom attributes as well. We will heavily use -custom attributes for the specification items. Enabling Doorstop to effectively -use custom attributes was done specifically for the RTEMS Project in several -patch sets. - -A key feature of Doorstop is the `fingerprint of items -<https://doorstop.readthedocs.io/en/latest/reference/item/#reviewed>`_. -For the RTEMS Project, the fingerprint hash algorithm was changed from MD5 to -SHA256. In 2019, it can be considered cryptographically secure. The -fingerprint should cover the normative values of an item, e.g. comments etc. are -not included. The fingerprint helps RTEMS users to track the significant -changes in the requirements (in contrast to all the changes visible in Git). As -an example use case, a user may want to assign a project-specific status to -specification items. This can be done with a table which contains columns for - -1. the UID of the item, - -2. the fingerprint, and - -3. the project-specific status. - -Given the source code of RTEMS (which includes the specification items) and this -table, it can be determined which items are unchanged and which have another -status (e.g. unknown, changed, etc.). diff --git a/eng/req/howto.rst b/eng/req/howto.rst new file mode 100644 index 0000000..325c443 --- /dev/null +++ b/eng/req/howto.rst @@ -0,0 +1,1213 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG + +How-To +====== + +Getting Started +--------------- + +The RTEMS specification items and qualification tools are work in progress. The +first step to work with the RTEMS specification and the corresponding tools is a +clone of the following repository: + +.. code-block:: none + + git clone git://git.rtems.org/rtems-central.git + git submodule init + git submodule update + +The tools need a virtual Python 3 environment. To set it up use: + +.. code-block:: none + + cd rtems-central + make env + +Each time you want to use one of the tools, you have to activate the +environment in your shell: + +.. code-block:: none + + cd rtems-central + . env/bin/activate + +View the Specification Graph +---------------------------- + +The specification items form directed graphs through :ref:`SpecTypeLink` +attributes. Each link has a role. For a particular view only specific roles +may be of interest. For example, the requirements specification of RTEMS +starts with the ``spec:/req/root`` specification item. It should form a tree +(connected graph without cycles). A text representation of the tree can be +printed with the ``./specview.py`` script: + +.. code-block:: none + + cd rtems-central + . env/bin/activate + ./specview.py + +This gives the following example output (shortened): + +.. code-block:: none + + /req/root (type=requirement/non-functional/design) + /bsp/if/group (type=requirement/non-functional/design-group, role=requirement-refinement) + /bsp/if/acfg-idle-task-body (type=interface/unspecified-define, role=interface-ingroup) + /bsp/sparc/leon3/req/idle-task-body (type=requirement/functional/function, role=interface-function) + /bsp/sparc/leon3/req/idle-task-power-down (type=requirement/functional/function, role=requirement-refinement) + /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation) + /bsp/sparc/leon3/req/idle-task-power-down-errata (type=requirement/functional/function, role=requirement-refinement) + /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation) + +The actual specification graph depends on build configuration options which +enable or disable specification items. The ``--enabled`` command line option +may be used to specify the build configuration options, for example +``--enabled=sparc,bsps/sparc/leon3,sparc/gr740,RTEMS_SMP,RTEMS_QUAL``. + +The ``./specview.py`` script can display other views of the specification +through the ``--filter`` command line option. Transition maps of +:ref:`SpecTypeActionRequirementItemType` items can be printed using the +``--filter=action-table`` or ``--filter=action-list`` filters. For example, +``./specview.py --filter=action-table /rtems/timer/req/create`` prints +something like this: + +.. code-block:: none + + .. table:: + :class: longtable + + ===== ========== ======= ===== ==== ======= ======= ===== + Entry Descriptor Name Id Free Status Name IdVar + ===== ========== ======= ===== ==== ======= ======= ===== + 0 0 Valid Valid Yes Ok Valid Set + 1 0 Valid Valid No TooMany Invalid Nop + 2 0 Valid Null Yes InvAddr Invalid Nop + 3 0 Valid Null No InvAddr Invalid Nop + 4 0 Invalid Valid Yes InvName Invalid Nop + 5 0 Invalid Valid No InvName Invalid Nop + 6 0 Invalid Null Yes InvName Invalid Nop + 7 0 Invalid Null No InvName Invalid Nop + ===== ========== ======= ===== ==== ======= ======= ===== + +For example, ``./specview.py --filter=action-list /rtems/timer/req/create`` +prints something like this: + +.. code-block:: none + + Status = Ok, Name = Valid, IdVar = Set + + * Name = Valid, Id = Valid, Free = Yes + + Status = TooMany, Name = Invalid, IdVar = Nop + + * Name = Valid, Id = Valid, Free = No + + Status = InvAddr, Name = Invalid, IdVar = Nop + + * Name = Valid, Id = Null, Free = { Yes, No } + + Status = InvName, Name = Invalid, IdVar = Nop + + * Name = Invalid, Id = { Valid, Null }, Free = { Yes, No } + +The view above yields for each variation of post-condition states the list of +associated pre-condition state variations. + +Generate Files from Specification Items +--------------------------------------- + +The ``./spec2modules.py`` script generates program and documentation files in +:file:`modules/rtems` and :file:`modules/rtems-docs` using the specification +items as input. The script should be invoked whenever a specification item was +modified. After running the script, go into the subdirectories and create +corresponding patch sets. For these patch sets, the normal patch review +process applies, see *Support and Contributing* chapter of the *RTEMS User +Manual*. + +Application Configuration Options +--------------------------------- + +The application configuration options and groups are maintained by +specification items in the directory :file:`spec/acfg/if`. Application +configuration options are grouped by +:ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be +stored in files using the :file:`spec/acfg/if/group-*.yml` pattern. Each +application configuration option shall link to exactly one group item with the +:ref:`SpecTypeInterfaceGroupMembershipLinkRole`. There are four +application option item types available which cover all existing options: + +* The *feature enable options* let the application enable a feature option. If + the option is not defined, then the feature is simply not available or + active. There should be no feature-specific code linked to the application + if the option is not defined. Examples are options which enable a device + driver like ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``. These options are + specified by + :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` items. + +* The *feature options* let the application enable a specific feature option. + If the option is not defined, then a default feature option is used. + Regardless whether the option is defined or not defined, feature-specific + code may be linked to the application. Examples are options which disable a + feature if the option is defined such as + ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` and options which provide a stub + implementation of a feature by default and a full implementation if the + option is defined such as ``CONFIGURE_IMFS_ENABLE_MKFIFO``. These options + are specified by :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` + items. + +* The *integer value options* let the application define a specific value for a + system parameter. If the option is not defined, then a default value is used + for the system parameter. Examples are options which define the maximum + count of objects available for application use such as + ``CONFIGURE_MAXIMUM_TASKS``. These options are specified by + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. + +* The *initializer options* let the application define a specific initializer + for a system parameter. If the option is not defined, then a default setting + is used for the system parameter. An example option of this type is + ``CONFIGURE_INITIAL_EXTENSIONS``. These options are specified by + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. + +Sphinx documentation sources and header files with Doxygen markup are generated +from the specification items. The descriptions in the items shall use a +restricted Sphinx formatting. Emphasis via one asterisk ("*"), strong emphasis +via two asterisk ("**"), code samples via blockquotes ("``"), code blocks (".. +code-block:: c") and lists are allowed. References to interface items are also +allowed, for example "${appl-needs-clock-driver:/name}" and +"${/rtems/task/if/create:/name}". References to other parts of the +documentation are possible, however, they have to be provided by +:file:`spec:/doc/if/*` items. + +Modify an Existing Group +^^^^^^^^^^^^^^^^^^^^^^^^ + +Search for the group by its section header and edit the specification item +file. For example: + +.. code-block:: none + + $ grep -rl "name: General System Configuration" spec/acfg/if + spec/acfg/if/group-general.yml + $ vi spec/acfg/if/group-general.yml + +Modify an Existing Option +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Search for the option by its C preprocessor define name and edit the +specification item file. For example: + +.. code-block:: none + + $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/acfg/if + spec/acfg/if/appl-needs-clock-driver.yml + $ vi spec/acfg/if/appl-needs-clock-driver.yml + +Add a New Group +^^^^^^^^^^^^^^^ + +Let ``new`` be the UID name part of the new group. Create the file +:file:`spec/acfg/if/group-new.yml` and provide all attributes for an +:ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example: + +.. code-block:: none + + $ vi spec/acfg/if/group-new.yml + +Add a New Option +^^^^^^^^^^^^^^^^ + +Let ``my-new-option`` be the UID name of the option. Create the file +:file:`if/acfg/my-new-option.yml` and provide all attributes for an appropriate +refinement of :ref:`SpecTypeApplicationConfigurationOptionItemType`. For +example: + +.. code-block:: none + + $ vi spec/acfg/if/my-new-option.yml + +Generate Content after Changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once you are done with the modifications of an existing item or the creation of +a new item, the changes need to be propagated to generated source files. This +is done by the :file:`spec2modules.py` script. Before you call this script, +make sure the Git submodules are up-to-date. + +.. code-block:: none + + $ ./spec2modules.py + +The script modifies or creates source files in :file:`modules/rtems` and +:file:`modules/rtems-docs`. Create patch sets for these changes just as if +these were work done by a human and follow the normal patch review process +described in the *RTEMS User Manual*. When the changes are integrated, update +the Git submodules and check in the changed items. + +Glossary Specification +---------------------- + +The glossary of terms for the RTEMS Project is defined by +:ref:`SpecTypeGlossaryTermItemType` items in the :file:`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 +:file:`spec/glossary/magicpower.yml` for the term `magic power`. + +Use ``${uid:/attribute}`` substitutions to reference other parts of the +specification. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + 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: + +.. code-block:: yaml + + ... + term: MP + ... + text: | + This term is an acronym for Magic Power. + ... + +Once you are done with the glossary items, run the script +:file:`spec2modules.py` to generate the derived documentation content. Send +patches for the generated documentation and the specification to the +:r:list:`devel` and follow the normal patch review process. + +Interface Specification +----------------------- + +.. _ReqEngAddAPIHeaderFile: + +Specify an API Header File +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The RTEMS :term:`API` header files are specified under ``spec:/rtems/*/if``. +Create a subdirectory with a corresponding name for the API, for example in +:file:`spec/rtems/foo/if` for the `foo` API. In this new subdirectory place an +:ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml` +(:file:`spec/rtems/foo/if/header.yml`) and populate it with the required +attributes. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + interface-type: header-file + links: + - role: interface-placement + uid: /if/domain + - role: interface-ingroup + uid: ../req/group + path: rtems/rtems/foo.h + prefix: cpukit/include + type: interface + +Specify an API Element +^^^^^^^^^^^^^^^^^^^^^^ + +Figure out the corresponding header file item. If it does not exist, see +:ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an +:ref:`SpecTypeInterfaceItemType` item into the directory of the header file +item, for example :file:`spec/rtems/foo/if/bar.yml` for the :c:func:`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 +:ref:`SpecTypeInterfaceUnspecifiedItemType` 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 :ref:`SpecTypeInterfaceForwardDeclarationItemType` item. + +.. code-block:: yaml + + 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 & Co. KG + 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: ${/c/if/null} + type: interface + +Requirements Depending on Build Configuration Options +----------------------------------------------------- + +Use the ``enabled-by`` attribute of items or parts of an item to make it +dependent on build configuration options such as :c:data:`RTEMS_SMP` or +architecture-specific options such as +:c:data:`CPU_ENABLE_ROBUST_THREAD_DISPATCH`, see +:ref:`SpecTypeEnabledByExpression`. With this attribute the specification can +be customized at the level of an item or parts of an item. If the +``enabled-by`` attribute evaluates to false for a particular configuration, +then the item or the associated part is disabled in the specification. The +``enabled-by`` attribute acts as a formalized *where* clause, see +:ref:`recommended requirements syntax <ReqEngSyntax>`. + +Please have a look at the following example which specifies the transition map +of :c:func:`rtems_signal_catch`: + +.. code-block:: yaml + + transition-map: + - enabled-by: true + post-conditions: + Status: Ok + ASRInfo: + - if: + pre-conditions: + Handler: Valid + then: New + - else: Inactive + pre-conditions: + Pending: all + Handler: all + Preempt: all + Timeslice: all + ASR: all + IntLvl: all + - enabled-by: CPU_ENABLE_ROBUST_THREAD_DISPATCH + post-conditions: + Status: NotImplIntLvl + ASRInfo: NopIntLvl + pre-conditions: + Pending: all + Handler: + - Valid + Preempt: all + Timeslice: all + ASR: all + IntLvl: + - Positive + - enabled-by: RTEMS_SMP + post-conditions: + Status: NotImplNoPreempt + ASRInfo: NopNoPreempt + pre-conditions: + Pending: all + Handler: + - Valid + Preempt: + - 'No' + Timeslice: all + ASR: all + IntLvl: all + +Requirements Depending on Application Configuration Options +----------------------------------------------------------- + +Requirements which depend on application configuration options such as +:c:data:`CONFIGURE_MAXIMUM_PROCESSORS` should be written in the following +:ref:`syntax <ReqEngSyntax>`: + + **Where** <feature is included>, the <system name> shall <system response>. + +Use these clauses with care. Make sure all feature combinations are covered. +Using a truth table may help. If a requirement depends on multiple features, +use: + + **Where** <feature 0>, **where** <feature 1>, **where** <feature ...>, the + <system name> shall <system response>. + +For application configuration options, use the clauses like this: + +:c:data:`CONFIGURE_MAXIMUM_PROCESSORS` equal to one + + **Where** the system was configured with a processor maximum of exactly + one, ... + +:c:data:`CONFIGURE_MAXIMUM_PROCESSORS` greater than one + + **Where** the system was configured with a processor maximum greater than + one, ... + +Please have a look at the following example used to specify +:c:func:`rtems_signal_catch`. The example is a post-condition state +specification of an action requirement, so there is an implicit set of +pre-conditions and the trigger: + + **While** <pre-condition(s)>, **when** rtems_signal_catch() is called, ... + +The *where* clauses should be mentally placed before the *while* clauses. + +.. code-block:: yaml + + post-conditions: + - name: ASRInfo + states: + - name: NopNoPreempt + test-code: | + if ( rtems_configuration_get_maximum_processors() > 1 ) { + CheckNoASRChange( ctx ); + } else { + CheckNewASRSettings( ctx ); + } + text: | + Where the scheduler does not support the no-preempt mode, the ASR + information of the caller of ${../if/catch:/name} shall not be + changed by the ${../if/catch:/name} call. + + Where the scheduler does support the no-preempt mode, the ASR + processing for the caller of ${../if/catch:/name} shall be done using + the handler specified by ${../if/catch:/params[0]/name} in the mode + specified by ${../if/catch:/params[1]/name}. + +Action Requirements +------------------- + +:ref:`SpecTypeActionRequirementItemType` items may be used to specify and +validate directive calls. They are a generator for event-driven requirements. +Event-driven requirements should be written in the following :ref:`syntax +<ReqEngSyntax>`: + + **While** <pre-condition 0>, **while** <pre-condition 1>, ..., **while** + <pre-condition *n*>, **when** <trigger>, the <system name> shall <system + response>. + +The list of *while* <pre-condition *i*> clauses for *i* from 1 to *n* in the +EARS notation is generated by *n* pre-condition states in the action +requirement item, see the ``pre-condition`` attribute in the +:ref:`SpecTypeActionRequirementItemType`. + +The <trigger> in the EARS notation is defined for an action requirement item by +the link to an :ref:`SpecTypeInterfaceFunctionItemType` or an +:ref:`SpecTypeInterfaceMacroItemType` item using the +:ref:`SpecTypeInterfaceFunctionLinkRole`. The code provided by the +``test-action`` attribute defines the action code which should invoke the +trigger directive in a particular set of pre-condition states. + +Each post-condition state of the action requirement item generates a <system +name> shall <system response> clause in the EARS notation, see the +``post-condition`` attribute in the :ref:`SpecTypeActionRequirementItemType`. + +Each entry in the transition map is an event-driven requirement composed of the +pre-condition states, the trigger defined by the link to a directive, and the +post-condition states. The transition map is defined by a list of +:ref:`SpecTypeActionRequirementTransition` descriptors. + +Use ``CamelCase`` for the pre-condition names, post-condition names, and state +names in action requirement items. The more conditions a directive has, the +shorter should be the names. The transition map may be documented as a table +and more conditions need more table columns. Use item attribute references in +the ``text`` attributes. This allows context-sensitive substitutions. + +Example +^^^^^^^ + +Lets have a look at an example of an action requirement item. We would like to +specify and validate the behaviour of the + +.. code-block:: c + + rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); + +directive which is particularly simple. For a more complex example see the +specification of :c:func:`rtems_signal_catch` or :c:func:`rtems_signal_send` in +``spec:/rtems/signal/req/catch`` or ``spec:/rtems/signal/send`` respectively. + +The event triggers are calls to :c:func:`rtems_timer_create`. Firstly, we need +the list of pre-conditions relevant to this directive. Good candidates are the +directive parameters, this gives us the ``Name`` and ``Id`` conditions. A +system condition is if an inactive timer object is available so that we can +create a timer, this gives us the ``Free`` condition. Secondly, we need the +list of post-conditions relevant to this directive. They are the return status +of the directive, ``Status``, the validity of a unique object name, ``Name``, +and the value of an object identifier variable, ``IdVar``. Each condition has +a set of states, see the YAML data below for the details. The specified +conditions and states yield the following transition map: + +.. table:: + :class: longtable + + ===== ========== ======= ===== ==== ======= ======= ===== + Entry Descriptor Name Id Free Status Name IdVar + ===== ========== ======= ===== ==== ======= ======= ===== + 0 0 Valid Valid Yes Ok Valid Set + 1 0 Valid Valid No TooMany Invalid Nop + 2 0 Valid Null Yes InvAddr Invalid Nop + 3 0 Valid Null No InvAddr Invalid Nop + 4 0 Invalid Valid Yes InvName Invalid Nop + 5 0 Invalid Valid No InvName Invalid Nop + 6 0 Invalid Null Yes InvName Invalid Nop + 7 0 Invalid Null No InvName Invalid Nop + ===== ========== ======= ===== ==== ======= ======= ===== + +Not all transition maps are that small, the transition map of +:c:func:`rtems_task_mode` has more than 8000 entries. We can construct +requirements from the clauses of the entries. For example, the three +requirements of entry 0 (Name=Valid, Id=Valid, and Free=Yes results in +Status=Ok, Name=Valid, and IdVar=Set) are: + + While the ``name`` parameter is valid, while the ``id`` parameter + references an object of type rtems_id, while the system has at least one + inactive timer object available, when rtems_timer_create() is called, the + return status of rtems_timer_create() shall be RTEMS_SUCCESSFUL. + + While the ``name`` parameter is valid, while the ``id`` parameter + references an object of type rtems_id, while the system has at least one + inactive timer object available, when rtems_timer_create() is called, the + unique object name shall identify the timer created by the + rtems_timer_create() call. + + While the ``name`` parameter is valid, while the ``id`` parameter + references an object of type rtems_id, while the system has at least one + inactive timer object available, when rtems_timer_create() is called, the + value of the object referenced by the ``id`` parameter shall be set to the + object identifier of the created timer after the return of the + rtems_timer_create() call. + +Now we will have a look at the specification item line by line. The top-level +attributes are normally in alphabetical order in an item file. For this +presentation we use a structured order. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2021 embedded brains GmbH & Co. KG + enabled-by: true + functional-type: action + rationale: null + references: [] + requirement-type: functional + +The specification items need a bit of boilerplate to tell you what they are, +who wrote them, and what their license is. + +.. code-block:: yaml + + text: ${.:text-template} + +Each requirement item needs a ``text`` attribute. For the action requirements, +we do not have a single requirement. There is just a template indicator and no +plain text. Several event-driven requirements are defined by the +pre-conditions, the trigger, and the post-conditions. + +.. code-block:: yaml + + pre-conditions: + - name: Name + states: + - name: Valid + test-code: | + ctx->name = NAME; + text: | + While the ${../if/create:/params[0]/name} parameter is valid. + - name: Invalid + test-code: | + ctx->name = 0; + text: | + While the ${../if/create:/params[0]/name} parameter is invalid. + test-epilogue: null + test-prologue: null + - name: Id + states: + - name: Valid + test-code: | + ctx->id = &ctx->id_value; + text: | + While the ${../if/create:/params[1]/name} parameter references an object + of type ${../../type/if/id:/name}. + - name: 'Null' + test-code: | + ctx->id = NULL; + text: | + While the ${../if/create:/params[1]/name} parameter is + ${/c/if/null:/name}. + test-epilogue: null + test-prologue: null + - name: Free + states: + - name: 'Yes' + test-code: | + /* Ensured by the test suite configuration */ + text: | + While the system has at least one inactive timer object available. + - name: 'No' + test-code: | + ctx->seized_objects = T_seize_objects( Create, NULL ); + text: | + While the system has no inactive timer object available. + test-epilogue: null + test-prologue: null + +This list defines the pre-conditions. Each pre-condition has a list of states +and corresponding validation test code. + +.. code-block:: yaml + + links: + - role: interface-function + uid: ../if/create + test-action: | + ctx->status = rtems_timer_create( ctx->name, ctx->id ); + +The link to the :c:func:`rtems_timer_create` interface specification item with +the ``interface-function`` link role defines the trigger. The ``test-action`` +defines the how the triggering directive is invoked for the validation test +depending on the pre-condition states. The code is not always as simple as in +this example. The validation test is defined in this item along with the +specification. + +.. code-block:: yaml + + post-conditions: + - name: Status + states: + - name: Ok + test-code: | + T_rsc_success( ctx->status ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/successful:/name}. + - name: InvName + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_NAME ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/invalid-name:/name}. + - name: InvAddr + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_ADDRESS ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/invalid-address:/name}. + - name: TooMany + test-code: | + T_rsc( ctx->status, RTEMS_TOO_MANY ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/too-many:/name}. + test-epilogue: null + test-prologue: null + - name: Name + states: + - name: Valid + test-code: | + id = 0; + sc = rtems_timer_ident( NAME, &id ); + T_rsc_success( sc ); + T_eq_u32( id, ctx->id_value ); + text: | + The unique object name shall identify the timer created by the + ${../if/create:/name} call. + - name: Invalid + test-code: | + sc = rtems_timer_ident( NAME, &id ); + T_rsc( sc, RTEMS_INVALID_NAME ); + text: | + The unique object name shall not identify a timer. + test-epilogue: null + test-prologue: | + rtems_status_code sc; + rtems_id id; + - name: IdVar + states: + - name: Set + test-code: | + T_eq_ptr( ctx->id, &ctx->id_value ); + T_ne_u32( ctx->id_value, INVALID_ID ); + text: | + The value of the object referenced by the ${../if/create:/params[1]/name} + parameter shall be set to the object identifier of the created timer + after the return of the ${../if/create:/name} call. + - name: Nop + test-code: | + T_eq_u32( ctx->id_value, INVALID_ID ); + text: | + Objects referenced by the ${../if/create:/params[1]/name} parameter in + past calls to ${../if/create:/name} shall not be accessed by the + ${../if/create:/name} call. + test-epilogue: null + test-prologue: null + +This list defines the post-conditions. Each post-condition has a list of +states and corresponding validation test code. + +.. code-block:: yaml + + skip-reasons: {} + transition-map: + - enabled-by: true + post-conditions: + Status: + - if: + pre-conditions: + Name: Invalid + then: InvName + - if: + pre-conditions: + Id: 'Null' + then: InvAddr + - if: + pre-conditions: + Free: 'No' + then: TooMany + - else: Ok + Name: + - if: + post-conditions: + Status: Ok + then: Valid + - else: Invalid + IdVar: + - if: + post-conditions: + Status: Ok + then: Set + - else: Nop + pre-conditions: + Name: all + Id: all + Free: all + type: requirement + +This list of transition descriptors defines the transition map. For the +post-conditions, you can use expressions to ease the specification, see +:ref:`SpecTypeActionRequirementTransitionPostConditionState`. The +``skip-reasons`` can be used to skip entire entries in the transition map, see +:ref:`SpecTypeActionRequirementSkipReasons`. + +.. code-block:: yaml + + test-brief: null + test-description: null + +The item contains the validation test code. The validation test in general can +be described by these two attributes. + +.. code-block:: yaml + + test-target: testsuites/validation/tc-timer-create.c + +This is the target file for the generated validation test code. Make sure this +file is included in the build specification, otherwise the test code generation +will fail. + +.. code-block:: yaml + + test-includes: + - rtems.h + - string.h + test-local-includes: [] + +You can specify a list of includes for the validation test. + +.. code-block:: yaml + + test-header: null + +A test header may be used to create a parameterized validation test, see +:ref:`SpecTypeTestHeader`. This is an advanced topic, see the specification of +:c:func:`rtems_task_ident` for an example. + +.. code-block:: yaml + + test-context-support: null + test-context: + - brief: | + This member is used by the T_seize_objects() and T_surrender_objects() + support functions. + description: null + member: | + void *seized_objects + - brief: | + This member may contain the object identifier returned by + rtems_timer_create(). + description: null + member: | + rtems_id id_value + - brief: | + This member specifies the ${../if/create:/params[0]/name} parameter for the + action. + description: null + member: | + rtems_name name + - brief: | + This member specifies the ${../if/create:/params[1]/name} parameter for the + action. + description: null + member: | + rtems_id *id + - brief: | + This member contains the return status of the action. + description: null + member: | + rtems_status_code status + +You can specify a list of validation test context members which can be used to +maintain the state of the validation test. The context is available through an +implicit ``ctx`` variable in all code blocks except the support blocks. The +context support code can be used to define test-specific types used by context +members. Do not use global variables. + +.. code-block:: yaml + + test-support: | + #define NAME rtems_build_name( 'T', 'E', 'S', 'T' ) + + #define INVALID_ID 0xffffffff + + static rtems_status_code Create( void *arg, uint32_t *id ) + { + return rtems_timer_create( rtems_build_name( 'S', 'I', 'Z', 'E' ), id ); + } + +The support code block can be used to provide functions, data structures, and +constants for the validation test. + +.. code-block:: yaml + + test-prepare: null + test-cleanup: | + if ( ctx->id_value != INVALID_ID ) { + rtems_status_code sc; + + sc = rtems_timer_delete( ctx->id_value ); + T_rsc_success( sc ); + + ctx->id_value = INVALID_ID; + } + + T_surrender_objects( &ctx->seized_objects, rtems_timer_delete ); + +The validation test basically executes a couple of nested for loops to iterate +over each pre-condition and each state of the pre-conditions. These two +optional code blocks can be used to prepare the pre-condition state +preparations and clean up after the post-condition checks in each loop +iteration. + +.. code-block:: yaml + + test-setup: + brief: null + code: | + memset( ctx, 0, sizeof( *ctx ) ); + ctx->id_value = INVALID_ID; + description: null + test-stop: null + test-teardown: null + +These optional code blocks correspond to test fixture methods, see +:ref:`RTEMSTestFrameworkFixture`. + +Pre-Condition Templates +^^^^^^^^^^^^^^^^^^^^^^^ + +Specify all directive parameters as separate pre-conditions. Use the following +syntax for directive object identifier parameters: + +.. code-block:: yaml + + - name: Id + states: + - name: NoObj + test-code: | + ctx->id = 0xffffffff; + text: | + While the ${../if/directive:/params[0]/name} parameter is not + associated with a thing. + - name: ClassA + test-code: | + ctx->id = ctx->class_a_id; + text: | + While the ${../if/directive:/params[0]/name} parameter is associated + with a class A thing. + - name: ClassB + test-code: | + ctx->id = ctx->class_b_id; + text: | + While the ${../if/directive:/params[0]/name} parameter is associated + with a class B thing. + test-epilogue: null + test-prologue: null + +Do not add specifications for invalid pointers. In general, there are a lot of +invalid pointers and the use of an invalid pointer is in almost all cases +undefined behaviour in RTEMS. There may be specifications for special cases +which deal with some very specific invalid pointers such as the :c:data:`NULL` +pointer or pointers which do not satisfy a range or boundary condition. Use +the following syntax for directive pointer parameters: + +.. code-block:: yaml + + - name: Id + states: + - name: Valid + test-code: | + ctx->id = &ctx->id_value; + text: | + While the ${../if/directive:/params[3]/name} parameter references an + object of type ${../../type/if/id:/name}. + - name: 'Null' + test-code: | + ctx->id = NULL; + text: | + While the ${../if/directive:/params[3]/name} parameter is + ${/c/if/null:/name}. + test-epilogue: null + test-prologue: null + +Use the following syntax for other directive parameters: + +.. code-block:: yaml + + - name: Name + states: + - name: Valid + test-code: | + ctx->name = NAME; + text: | + While the ${../if/directive:/params[0]/name} parameter is valid. + - name: Invalid + test-code: | + ctx->name = 0; + text: | + While the ${../if/directive:/params[0]/name} parameter is invalid. + test-epilogue: null + test-prologue: null + +Post-Condition Templates +^^^^^^^^^^^^^^^^^^^^^^^^ + +Do not mix different things into one post-condition. If you write multiple +sentences to describe what happened, then think about splitting up the +post-condition. Keep the post-condition simple and focus on one testable +aspect which may be changed by a directive call. + +For directives returning an :c:type:`rtems_status_code` use the following +post-condition states. Specify only status codes which may be returned by the +directive. Use it as the first post-condition. The first state shall be +``Ok``. The other states shall be listed in the order in which they can occur. + +.. code-block:: yaml + + - name: Status + states: + - name: Ok + test-code: | + T_rsc_success( ctx->status ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/successful:/name}. + - name: IncStat + test-code: | + T_rsc( ctx->status, RTEMS_INCORRECT_STATE ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/incorrect-state:/name}. + - name: InvAddr + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_ADDRESS ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-address:/name}. + - name: InvName + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_NAME ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-name:/name}. + - name: InvNum + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_NUMBER ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-number:/name}. + - name: InvSize + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_SIZE ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-size:/name}. + - name: InvPrio + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_PRIORITY ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-priority:/name}. + - name: NotConf + test-code: | + T_rsc( ctx->status, RTEMS_NOT_CONFIGURED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/not-configured:/name}. + - name: NotDef + test-code: | + T_rsc( ctx->status, RTEMS_NOT_DEFINED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/not-defined:/name}. + - name: NotImpl + test-code: | + T_rsc( ctx->status, RTEMS_NOT_IMPLEMENTED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/not-implemented:/name}. + - name: TooMany + test-code: | + T_rsc( ctx->status, RTEMS_TOO_MANY ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/too-many:/name}. + - name: Unsat + test-code: | + T_rsc( ctx->status, RTEMS_UNSATISFIED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/unsatisfied:/name}. + test-epilogue: null + test-prologue: null + +For values which are returned by reference through directive parameters, use +the following post-condition states. + +.. code-block:: yaml + + - name: SomeParamVar + states: + - name: Set + test-code: | + /* Add code to check that the object value was set to X */ + text: | + The value of the object referenced by the + ${../if/directive:/params[0]/name} parameter shall be set to X after + the return of the ${../if/directive:/name} call. + - name: Nop + test-code: | + /* Add code to check that the object was not modified */ + text: | + Objects referenced by the ${../if/directive:/params[0]/name} + parameter in past calls to ${../if/directive:/name} shall not be + accessed by the ${../if/directive:/name} call. + +Validation Test Guidelines +-------------------------- + +The validation test cases, test runners, and test suites are generated by the +``./spec2modules.py`` script from specification items. For the placement and +naming of the generated sources use the following rules: + +* Place architecture-specific validation test sources and programs into the + ``testsuites/validation/cpu`` directory. + +* Place BSP-specific validation test sources and programs into the + ``testsuites/validation/bsps`` directory. + +* Place all other validation test sources and programs into the + ``testsuites/validation`` directory. + +* Place architecture-specific unit test sources and programs into the + ``testsuites/unit/cpu`` directory. + +* Place BSP-specific unit test sources and programs into the + ``testsuites/unit/bsps`` directory. + +* Place all other unit test sources and programs into the + ``testsuites/unit`` directory. + +* Use dashes (``-``) to separate parts of a file name. Use only dashes, the + digits ``0`` to ``9``, and the lower case characters ``a`` to ``z`` for file + names. In particular, do not use underscores (``_``). + +* The parts of a file name shall be separated by dashes and ordered from most + general (left) to more specific (right), for example ``tc-task-construct.c``. + +* The file names associated with tests shall be unique within the system since + the test framework prints out only the base file names. + +* Use the prefix ``tc-`` for test case files. + +* Use the prefix ``tr-`` for test runner files. + +* Use the prefix ``ts-`` for test suite files. + +* Use the prefix ``tx-`` for test extension files (test support code). + +* Tests for fatal errors shall have ``fatal`` as the most general file part, + for example ``ts-fatal-too-large-tls-size.c``. + +* Validation test suites shall have ``validation`` as the most general file + part, for example ``ts-validation-no-clock-0.c``. + +* Unit test suites shall have ``unit`` as the most general file part, for + example ``ts-unit-no-clock-0.c``. + +* Architecture-specific files shall have the architecture name as a file part, + for example ``ts-fatal-sparc-leon3-clock-initialization.c``. + +* BSP-specific files shall have the BSP family or variant name as a file part, + for example ``tc-sparc-gr712rc.c``. + +* Architecture-specific or BSP-specific tests shall use the ``enabled-by`` + attribute of the associated specification item to make the build item + conditional, for example: + + .. code-block:: yaml + + ... + build-type: objects + enabled-by: arm + type: build + ... + + .. code-block:: yaml + + ... + build-type: test-program + enabled-by: bsps/sparc/leon3 + type: build + ... + +Verify the Specification Items +------------------------------ + +The ``./specverify.py`` script verifies that the specification items have the +format documented in :ref:`ReqEngSpecificationItems`. To some extent the +values of attributes are verified as well. diff --git a/eng/req/index.rst b/eng/req/index.rst new file mode 100644 index 0000000..524835d --- /dev/null +++ b/eng/req/index.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +.. |E40| replace:: ECSS-E-ST-40C + +.. _ReqEng: + +Software Requirements Engineering +********************************* + +Software engineering standards for critical software such as |E40| demand that +software requirements for a software product are collected in a software +requirements specification (technical specification in |E40| terms). They are +usually derived from system requirements (requirements baseline in |E40| +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 :cite:`Motorola:1988:RTEID` and +later the ORKID :cite:`VITA:1990:ORKID` 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 +:term:`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. + +.. topic:: 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. + +.. toctree:: + + req-for-req + items + traceability + management + tooling + howto diff --git a/eng/req/items.rst b/eng/req/items.rst new file mode 100644 index 0000000..286e998 --- /dev/null +++ b/eng/req/items.rst @@ -0,0 +1,6195 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2023 embedded brains GmbH & Co. KG + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ReqEngSpecificationItems: + +Specification Items +=================== + +.. _ReqEngSpecificationItemHierarchy: + +Specification Item Hierarchy +---------------------------- + +The specification item types have the following hierarchy: + +* :ref:`SpecTypeRootItemType` + + * :ref:`SpecTypeBuildItemType` + + * :ref:`SpecTypeBuildAdaTestProgramItemType` + + * :ref:`SpecTypeBuildBSPItemType` + + * :ref:`SpecTypeBuildConfigurationFileItemType` + + * :ref:`SpecTypeBuildConfigurationHeaderItemType` + + * :ref:`SpecTypeBuildGroupItemType` + + * :ref:`SpecTypeBuildLibraryItemType` + + * :ref:`SpecTypeBuildObjectsItemType` + + * :ref:`SpecTypeBuildOptionItemType` + + * :ref:`SpecTypeBuildScriptItemType` + + * :ref:`SpecTypeBuildStartFileItemType` + + * :ref:`SpecTypeBuildTestProgramItemType` + + * :ref:`SpecTypeConstraintItemType` + + * :ref:`SpecTypeGlossaryItemType` + + * :ref:`SpecTypeGlossaryGroupItemType` + + * :ref:`SpecTypeGlossaryTermItemType` + + * :ref:`SpecTypeInterfaceItemType` + + * :ref:`SpecTypeApplicationConfigurationGroupItemType` + + * :ref:`SpecTypeApplicationConfigurationOptionItemType` + + * :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` + + * :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` + + * :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + + * :ref:`SpecTypeInterfaceCompoundItemType` + + * :ref:`SpecTypeInterfaceDefineItemType` + + * :ref:`SpecTypeInterfaceDomainItemType` + + * :ref:`SpecTypeInterfaceEnumItemType` + + * :ref:`SpecTypeInterfaceEnumeratorItemType` + + * :ref:`SpecTypeInterfaceForwardDeclarationItemType` + + * :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + + * :ref:`SpecTypeInterfaceGroupItemType` + + * :ref:`SpecTypeInterfaceHeaderFileItemType` + + * :ref:`SpecTypeInterfaceTypedefItemType` + + * :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + + * :ref:`SpecTypeInterfaceUnspecifiedItemType` + + * :ref:`SpecTypeInterfaceVariableItemType` + + * :ref:`SpecTypeRegisterBlockItemType` + + * :ref:`SpecTypeProxyItemTypes` + + * :ref:`SpecTypeRequirementItemType` + + * :ref:`SpecTypeFunctionalRequirementItemType` + + * :ref:`SpecTypeActionRequirementItemType` + + * :ref:`SpecTypeGenericFunctionalRequirementItemType` + + * :ref:`SpecTypeNonFunctionalRequirementItemType` + + * :ref:`SpecTypeDesignGroupRequirementItemType` + + * :ref:`SpecTypeDesignTargetItemType` + + * :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + + * :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + + * :ref:`SpecTypeRuntimePerformanceRequirementItemType` + + * :ref:`SpecTypeRequirementValidationItemType` + + * :ref:`SpecTypeRequirementValidationMethod` + + * :ref:`SpecTypeRuntimeMeasurementTestItemType` + + * :ref:`SpecTypeSpecificationItemType` + + * :ref:`SpecTypeTestCaseItemType` + + * :ref:`SpecTypeTestPlatformItemType` + + * :ref:`SpecTypeTestProcedureItemType` + + * :ref:`SpecTypeTestSuiteItemType` + +.. _ReqEngSpecificationItemTypes: + +Specification Item Types +------------------------ + +.. _SpecTypeRootItemType: + +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 :term:`YAML` format with a +defined set of key-value pairs called attributes. Each attribute key name +shall be a :ref:`SpecTypeName`. 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 :ref:`SpecTypeSPDXLicenseIdentifier`. It + shall be the license of the item. + +copyrights + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeCopyright`. It shall be the list of copyright statements of + the item. + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. 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 + :ref:`SpecTypeLink`. + +type + The attribute value shall be a :ref:`SpecTypeName`. 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: + +* :ref:`SpecTypeBuildItemType` + +* :ref:`SpecTypeConstraintItemType` + +* :ref:`SpecTypeGlossaryItemType` + +* :ref:`SpecTypeInterfaceItemType` + +* :ref:`SpecTypeProxyItemTypes` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRequirementValidationItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeSpecificationItemType` + +* :ref:`SpecTypeTestCaseItemType` + +* :ref:`SpecTypeTestPlatformItemType` + +* :ref:`SpecTypeTestProcedureItemType` + +* :ref:`SpecTypeTestSuiteItemType` + +.. _SpecTypeBuildItemType: + +Build Item Type +^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through 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 :ref:`SpecTypeName`. It shall be the build + item type. + +This type is refined by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildConfigurationFileItemType` + +* :ref:`SpecTypeBuildConfigurationHeaderItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildAdaTestProgramItemType: + +Build Ada Test Program Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 :ref:`SpecTypeBuildObjectsItemType` items. Test +programs have an implicit ``enabled-by`` attribute value which is controlled by +the option action :ref:`set-test-state <SpecTypeBuildOptionItemType>`. 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 + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +stlib + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkStaticLibraryDirective`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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: [] + +.. _SpecTypeBuildBSPItemType: + +Build BSP Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +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 + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildConfigurationFileItemType: + +Build Configuration File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 :ref:`SpecTypeBuildInstallPath`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildConfigurationHeaderItemType: + +Build Configuration Header Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 :ref:`SpecTypeBuildInstallPath`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +.. _SpecTypeBuildGroupItemType: + +Build Group Item Type +^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +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 + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildLibraryItemType: + +Build Library Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 +:ref:`SpecTypeBuildObjectsItemType` 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 + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +install-path + The attribute value shall be a :ref:`SpecTypeBuildInstallPath`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. It shall be the + name of the static library, e.g. ``z`` for ``libz.a``. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildObjectsItemType: + +Build Objects Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildOptionItemType: + +Build Option Item Type +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through 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`` + +* ``description`` + +The explicit attributes for this type are: + +actions + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildOptionAction`. 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 + :ref:`SpecTypeBuildOptionDefaultValue`. 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 choosen. 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 + <https://docs.python.org/3/library/string.html#formatstrings>`_, for + example ``'{}'`` or ``'{:#010x}'``. + +name + The attribute value shall be a :ref:`SpecTypeBuildOptionName`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildScriptItemType: + +Build Script Item Type +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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-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 + :ref:`SpecTypeBuildAssemblerOption`. + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +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 :file:`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 :file:`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 + :ref:`SpecTypeBuildIncludePath`. + +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. + +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 :file:`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 :file:`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. Each list element shall be a + :ref:`SpecTypeBuildLinkStaticLibraryDirective`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildStartFileItemType: + +Build Start File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 + :ref:`SpecTypeBuildAssemblerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install-path + The attribute value shall be a :ref:`SpecTypeBuildInstallPath`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeBuildTestProgramItemType: + +Build Test Program Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` 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 :ref:`SpecTypeBuildObjectsItemType` items. Test programs have an +implicit ``enabled-by`` attribute value which is controlled by the option +action :ref:`set-test-state <SpecTypeBuildOptionItemType>`. 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 + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +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 + :ref:`SpecTypeBuildIncludePath`. + +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +stlib + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkStaticLibraryDirective`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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: [] + +.. _SpecTypeConstraintItemType: + +Constraint Item Type +^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` 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 :ref:`SpecTypeRequirementText`. It shall + state the constraint. + +.. _SpecTypeGlossaryItemType: + +Glossary Item Type +^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` 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 :ref:`SpecTypeName`. It shall be the + glossary item type. + +This type is refined by the following types: + +* :ref:`SpecTypeGlossaryGroupItemType` + +* :ref:`SpecTypeGlossaryTermItemType` + +.. _SpecTypeGlossaryGroupItemType: + +Glossary Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeGlossaryItemType` 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. + +.. _SpecTypeGlossaryTermItemType: + +Glossary Term Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeGlossaryItemType` 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. + +.. _SpecTypeInterfaceItemType: + +Interface Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` 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 +:ref:`SpecTypeInterfaceDomainItemType` items to specify interface domains, for +example the :term:`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 :ref:`SpecTypeName`. It shall be the + interface item type. + +This type is refined by the following types: + +* :ref:`SpecTypeApplicationConfigurationGroupItemType` + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceDomainItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceForwardDeclarationItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceHeaderFileItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + +* :ref:`SpecTypeInterfaceUnspecifiedItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeApplicationConfigurationGroupItemType: + +Application Configuration Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeRequirementText`. It shall + state the requirement for the application configuration group. + +.. _SpecTypeApplicationConfigurationOptionItemType: + +Application Configuration Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeName`. It shall be the + application configuration option type. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be an + :ref:`SpecTypeApplicationConfigurationOptionName`. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +This type is refined by the following types: + +* :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` + +* :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` + +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + +.. _SpecTypeApplicationConfigurationFeatureEnableOptionItemType: + +Application Configuration Feature Enable Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType` +through the ``appl-config-option-type`` attribute if the value is +``feature-enable``. This set of attributes specifies an application +configuration feature enable option. + +.. _SpecTypeApplicationConfigurationFeatureOptionItemType: + +Application Configuration Feature Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType` +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. + +.. _SpecTypeApplicationConfigurationValueOptionItemType: + +Application Configuration Value Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the + ``appl-config-option-type`` attribute if the value is ``initializer`` + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the + ``appl-config-option-type`` attribute if the value is ``integer`` + +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 :ref:`SpecTypeIntegerOrString`. It shall + describe the default value of the application configuration option. + +.. _SpecTypeInterfaceCompoundItemType: + +Interface Compound Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``struct`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``union`` + +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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`. + +definition-kind + The attribute value shall be an + :ref:`SpecTypeInterfaceCompoundDefinitionKind`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +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 :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeInterfaceDefineItemType: + +Interface Define Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the define. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeInterfaceDomainItemType: + +Interface Domain Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfacePlacementLinkRole`. 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. + +.. _SpecTypeInterfaceEnumItemType: + +Interface Enum Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition-kind + The attribute value shall be an :ref:`SpecTypeInterfaceEnumDefinitionKind`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the enum. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +.. _SpecTypeInterfaceEnumeratorItemType: + +Interface Enumerator Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the + enumerator. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeInterfaceForwardDeclarationItemType: + +Interface Forward Declaration Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceTargetLinkRole` to an +:ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the type +declared by the forward declaration. + +.. _SpecTypeInterfaceFunctionOrMacroItemType: + +Interface Function or Macro Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``function`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``macro`` + +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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +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 :ref:`SpecTypeInterfaceNotes`. + +params + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceParameter`. + +return + The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`. + +.. _SpecTypeInterfaceGroupItemType: + +Interface Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +identifier + The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`. + +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 :ref:`SpecTypeRequirementText`. It shall + state the requirement for the interface group. + +.. _SpecTypeInterfaceHeaderFileItemType: + +Interface Header File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfacePlacementLinkRole` to an +:ref:`SpecTypeInterfaceDomainItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +path + The attribute value shall be a string. It shall be the path used to include + the header file. For example :file:`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 + :file:`cpukit/include`. + +.. _SpecTypeInterfaceTypedefItemType: + +Interface Typedef Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the typedef. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +params + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceParameter`. + +return + The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`. + +.. _SpecTypeInterfaceUnspecifiedHeaderFileItemType: + +Interface Unspecified Header File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :file:`rtems/confdefs.h`. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + +.. _SpecTypeInterfaceUnspecifiedItemType: + +Interface Unspecified Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-define`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-enum`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-enumerator`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-function`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-group`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-macro`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-object`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-struct`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-typedef`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-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 + :ref:`SpecTypeExternalReference`. + +.. _SpecTypeInterfaceVariableItemType: + +Interface Variable Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the + variable. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeRegisterBlockItemType: + +Register Block Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` 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 +:ref:`SpecTypeRegisterBlockIncludeRole`. Registers consists of bit fields (see +:ref:`SpecTypeRegisterBitsDefinition`. 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 :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +identifier + The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`. + +name + The attribute value shall be a string. It shall be the name of the register + block. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +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 ``identifier`` attribute. + +register-block-size + The attribute value shall be an :ref:`SpecTypeOptionalInteger`. 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 ``name`` attribute will be used. + +registers + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterDefinition`. + +.. _SpecTypeProxyItemTypes: + +Proxy Item Types +^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``proxy``. Items of similar characteristics may link +to a proxy item through links with the :ref:`SpecTypeProxyMemberLinkRole`. 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. + +.. _SpecTypeRequirementItemType: + +Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` 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 + :ref:`SpecTypeExternalReference`. + +requirement-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + requirement item type. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeFunctionalRequirementItemType` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` + +Please have a look at the following example: + +.. code-block:: yaml + + 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 + +.. _SpecTypeFunctionalRequirementItemType: + +Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRequirementItemType` 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 :ref:`SpecTypeName`. It shall be the + functional type of the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeGenericFunctionalRequirementItemType` + +.. _SpecTypeActionRequirementItemType: + +Action Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeFunctionalRequirementItemType` 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 :ref:`SpecTypeInterfaceFunctionLinkRole` 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 + :ref:`SpecTypeActionRequirementCondition`. + +pre-conditions + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementCondition`. + +skip-reasons + The attribute value shall be an + :ref:`SpecTypeActionRequirementSkipReasons`. + +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 + :ref:`SpecTypeTestContextMember`. + +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 :ref:`SpecTypeTestHeader`. + +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 :ref:`SpecTypeTestSupportMethod`. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +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 :ref:`SpecTypeTestSupportMethod`. + +transition-map + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementTransition`. + +Please have a look at the following example: + +.. code-block:: yaml + + 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: + - 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 + skip-reasons: {} + test-action: | + /* Call the function of the action */ + test-brief: null + test-cleanup: null + test-context: + - brief: null + description: null + member: void *data + - brief: null + description: null + member: option_type option + test-context-support: null + test-description: null + test-header: null + test-includes: [] + test-local-includes: [] + test-prepare: null + 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 + +.. _SpecTypeGenericFunctionalRequirementItemType: + +Generic Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``capability`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``dependability-function`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``function`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``interface-define-not-defined`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``operational`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``safety-function`` + +Items of this type state a functional requirement with the functional type +defined by the specification type refinement. + +.. _SpecTypeNonFunctionalRequirementItemType: + +Non-Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRequirementItemType` through 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 :ref:`SpecTypeName`. It shall be the + non-functional type of the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeDesignGroupRequirementItemType` + +* :ref:`SpecTypeDesignTargetItemType` + +* :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +.. _SpecTypeDesignGroupRequirementItemType: + +Design Group Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``design-group``. This +set of attributes specifies a design group requirement. Design group +requirements have an explicit reference to the associated Doxygen group +specified by the ``identifier`` attribute. Design group requirements have an +implicit validation by inspection method. The qualification toolchain shall +perform the inspection and check that the specified Doxygen group exists in the +software source code. All explicit attributes shall be specified. The explicit +attributes for this type are: + +identifier + The attribute value shall be a + :ref:`SpecTypeRequirementDesignGroupIdentifier`. + +.. _SpecTypeDesignTargetItemType: + +Design Target Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``design-target``. This +set of attributes specifies a design :term:`target`. All explicit attributes +shall be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an optional string. If the value is present, + then it shall briefly describe the target. + +description + The attribute value shall be an optional string. If the value is present, + then it shall thoroughly describe the target. + +name + The attribute value shall be a string. It shall be the target name. + +.. _SpecTypeGenericNonFunctionalRequirementItemType: + +Generic Non-Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``build-configuration`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``constraint`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``design`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``documentation`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``interface`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``interface-requirement`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``maintainability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``performance`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is + ``performance-runtime-limits`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``portability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``quality`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``reliability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``resource`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``safety`` + +Items of this type state a non-functional requirement with the non-functional +type defined by the specification type refinement. + +.. _SpecTypeRuntimeMeasurementEnvironmentItemType: + +Runtime Measurement Environment Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is +``performance-runtime-environment``. This set of attributes specifies a runtime +measurement environment. 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 runtime measurement + environment name. See also + :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. + +.. _SpecTypeRuntimePerformanceRequirementItemType: + +Runtime Performance Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``performance-runtime``. +The item shall have exactly one link with the +:ref:`SpecTypeRuntimeMeasurementRequestLinkRole`. A requirement text processor +shall support a substitution of ${.:/limit-kind}: + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound`` or + ``min-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"minimum"``. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``mean-lower-bound`` or + ``mean-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"mean"``. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``max-lower-bound`` or + ``max-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"maximum"``. + +A requirement text processor shall support a substitution of +${.:/limit-condition}: + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound``, + ``mean-lower-bound``, or ``max-lower-bound``, the substitution of + ${.:/limit-condition} shall be ``"greater than or equal to <value>"`` with + <value> being the value of the corresponding entry in the + :ref:`SpecTypeRuntimeMeasurementValueTable`. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-upper-bound``, + ``mean-upper-bound``, or ``max-upper-bound``, the substitution of + ${.:/limit-condition} shall be ``"less than or equal to <value>"`` with + <value> being the value of the corresponding entry in the + :ref:`SpecTypeRuntimeMeasurementValueTable`. + +A requirement text processor shall support a substitution of ${.:/environment}. +The value of the substitution shall be ``"<environment> environment"`` with +<environment> being the environment of the corresponding entry in the +:ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. + +This set of attributes specifies a runtime performance requirement. Along with +the requirement, the validation test code to execute a measure runtime request +is specified. All explicit attributes shall be specified. The explicit +attributes for this type are: + +params + The attribute value shall be a + :ref:`SpecTypeRuntimePerformanceParameterSet`. + +test-body + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It shall + provide the code of the measure runtime body handler. In contrast to other + methods, this method is mandatory. + +test-cleanup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code to clean up the measure runtime request. This method is + called before the cleanup method of the corresponding + :ref:`SpecTypeRuntimeMeasurementTestItemType` item and after the request. + +test-prepare + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code to prepare the measure runtime request. This method is + called after the prepare method of the corresponding + :ref:`SpecTypeRuntimeMeasurementTestItemType` item and before the request. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code of the measure runtime setup handler. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code of the measure runtime teardown handler. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + links: + - role: runtime-measurement-request + uid: ../val/perf + params: {} + rationale: null + references: [] + test-body: + brief: | + Get a buffer. + code: | + ctx->status = rtems_partition_get_buffer( ctx->part_many, &ctx->buffer ); + description: null + test-cleanup: null + test-prepare: null + test-setup: null + test-teardown: + brief: | + Return the buffer. + code: | + rtems_status_code sc; + + T_quiet_rsc_success( ctx->status ); + + sc = rtems_partition_return_buffer( ctx->part_many, ctx->buffer ); + T_quiet_rsc_success( sc ); + + return tic == toc; + description: null + text: | + When a partition has exactly ${../val/perf:/params/buffer-count} free + buffers, the ${.:/limit-kind} runtime of exactly + ${../val/perf:/params/sample-count} successful calls to + ${../if/get-buffer:/name} in the ${.:/environment} shall be + ${.:/limit-condition}. + non-functional-type: performance-runtime + requirement-type: non-functional + type: requirement + +.. _SpecTypeRequirementValidationItemType: + +Requirement Validation Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through 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 :ref:`SpecTypeRequirementValidationLinkRole`. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +method + The attribute value shall be a :ref:`SpecTypeName`. It shall specify the + requirement validation method (except validation by test). Validation by + test is done through :ref:`SpecTypeTestCaseItemType` items. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + +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 :term:`software product`. + + * *By inspection*: A statement shall be provided how the requirement is + met, by inspection of the :term:`source code`. + + * *By review of design*: A rationale shall be provided to demonstrate how + the requirement is satisfied implicitly by the software design. + +This type is refined by the following types: + +* :ref:`SpecTypeRequirementValidationMethod` + +.. _SpecTypeRequirementValidationMethod: + +Requirement Validation Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute + if the value is ``by-analysis`` + +* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute + if the value is ``by-inspection`` + +* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute + if the value is ``by-review-of-design`` + +.. _SpecTypeRuntimeMeasurementTestItemType: + +Runtime Measurement Test Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``runtime-measurement-test``. This set of attributes +specifies a runtime measurement test case. All explicit attributes shall be +specified. The explicit attributes for this type are: + +params + The attribute value shall be a + :ref:`SpecTypeRuntimeMeasurementParameterSet`. + +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 a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the measure runtime request cleanup + method. The method is called after each measure runtime request. + +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. + +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-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 a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the measure runtime request prepare + method. The method is called before each measure runtime request. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case setup fixture method. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case stop 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 a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case teardown fixture method. + +.. _SpecTypeSpecificationItemType: + +Specification Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through 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 :ref:`SpecTypeSpecificationInformation`. + +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 :ref:`SpecTypeName`. It shall the + specification type. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + 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 + +.. _SpecTypeTestCaseItemType: + +Test Case Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through 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: + +test-actions + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestCaseAction`. + +test-brief + The attribute value shall be a string. It shall be the test case brief + description. + +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. + +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. It shall be the test case + description. + +test-header + The attribute value shall be a :ref:`SpecTypeTestHeader`. + +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-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +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 target test case source file. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +.. _SpecTypeTestPlatformItemType: + +Test Platform Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through 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. + +.. _SpecTypeTestProcedureItemType: + +Test Procedure Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through 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. + +.. _SpecTypeTestSuiteItemType: + +Test Suite Item Type +^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is + ``memory-benchmark`` + +* :ref:`SpecTypeRootItemType` through 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: + +test-brief + The attribute value shall be a string. It shall be the test suite brief + description. + +test-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. + +test-description + The attribute value shall be an optional string. It shall be the test suite + description. + +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-target + The attribute value shall be a string. It shall be the path to the + generated target test suite source file. + +.. _ReqEngSpecificationAttributeSetsAndValueTypes: + +Specification Attribute Sets and Value Types +-------------------------------------------- + +.. _SpecTypeActionRequirementBooleanExpression: + +Action Requirement Boolean Expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type is a boolean expression. + +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 an + :ref:`SpecTypeActionRequirementBooleanExpression`. 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 + :ref:`SpecTypeActionRequirementBooleanExpression`. 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 + :ref:`SpecTypeActionRequirementBooleanExpression`. The *or* operator + evaluates to the *logical or* of the evaluation results of the + expressions in the list. + + post-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionConditionSet`. The + *post-conditions* operator evaluates to true, if the post-condition + states of the associated transition are contained in the specified + post-condition set, otherwise to false. + + pre-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionConditionSet`. The + *pre-conditions* operator evaluates to true, if the pre-condition states + of the associated transition are contained in the specified pre-condition + set, otherwise to false. + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. 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: + +* :ref:`SpecTypeActionRequirementBooleanExpression` + +* :ref:`SpecTypeActionRequirementExpression` + +.. _SpecTypeActionRequirementCondition: + +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 :ref:`SpecTypeActionRequirementName`. + +states + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementState`. + +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 + :ref:`SpecTypeTestContextMember`. + +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 + :ref:`SpecTypeTestContextMember`. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +.. _SpecTypeActionRequirementExpression: + +Action Requirement Expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines an expression which may define the state of a +post-condition. The ``else`` and ``specified-by`` shall be used individually. +The ``if`` and ``then`` or ``then-specified-by`` expressions shall be used +together. At least one of the explicit attributes shall be specified. The +explicit attributes for this type are: + +else + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name + of the state of the post-condition. + +if + The attribute value shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. If the boolean + expression evaluates to true, then the state is defined according to the + ``then`` attribute value. + +specified-by + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It + shall be the name of a pre-condition. The name of the state of the + pre-condition in the associated transition defines the name of the state of + the post-condition. + +then + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name + of the state of the post-condition. + +then-specified-by + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It + shall be the name of a pre-condition. The name of the state of the + pre-condition in the associated transition defines the name of the state of + the post-condition. + +.. _SpecTypeActionRequirementExpressionConditionSet: + +Action Requirement Expression Condition Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines for the specified conditions a set of states. +Generic attributes may be specified. Each generic attribute key shall be an +:ref:`SpecTypeActionRequirementName`. Each generic attribute value shall be an +:ref:`SpecTypeActionRequirementExpressionStateSet`. There shall be at most one +generic attribute key for each condition. The key name shall be the condition +name. The value of each generic attribute shall be a set of states of the +condition. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementBooleanExpression` + +.. _SpecTypeActionRequirementExpressionStateName: + +Action Requirement Expression State Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the name of a state of the condition +or ``N/A`` if the condition is not applicable. The value + +* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + +* or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementExpression` + +.. _SpecTypeActionRequirementExpressionStateSet: + +Action Requirement Expression 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 + :ref:`SpecTypeActionRequirementExpressionStateName`. The list defines a set + of states of the condition. + +* The value may be a string. It shall be the name of a state of the condition + or ``N/A`` if the condition is not applicable. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + +.. _SpecTypeActionRequirementName: + +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 name +``NA`` is reserved and indicates that a condition is not applicable. The value + +* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + +* and, shall be not equal to "``NA``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementCondition` + +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + +* :ref:`SpecTypeActionRequirementExpression` + +* :ref:`SpecTypeActionRequirementSkipReasons` + +* :ref:`SpecTypeActionRequirementState` + +* :ref:`SpecTypeActionRequirementTransitionPostConditions` + +* :ref:`SpecTypeActionRequirementTransitionPreConditions` + +.. _SpecTypeActionRequirementSkipReasons: + +Action Requirement Skip Reasons +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies skip reasons used to justify why transitions +in the transition map are skipped. Generic attributes may be specified. Each +generic attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each +generic attribute value shall be a string. The key defines the name of a skip +reason. The name can be used in +:ref:`SpecTypeActionRequirementTransitionPostConditions` to skip the +corresponding transitions. The value shall give a reason why the transitions +are skipped. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +.. _SpecTypeActionRequirementState: + +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 :ref:`SpecTypeActionRequirementName`. + +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 + :ref:`SpecTypeTestContextMember`. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + define the state of the condition. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementCondition` + +.. _SpecTypeActionRequirementTransition: + +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 :ref:`SpecTypeEnabledByExpression`. 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 + :ref:`SpecTypeActionRequirementTransitionPostConditions`. + +pre-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementTransitionPreConditions`. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +.. _SpecTypeActionRequirementTransitionPostConditionState: + +Action Requirement Transition Post-Condition State +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 + :ref:`SpecTypeActionRequirementExpression`. The list contains expressions to + define the state of the corresponding post-condition. + +* The value may be a string. It shall be the name of a state of the + corresponding post-condition or ``N/A`` if the post-condition is not + applicable. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransitionPostConditions` + +.. _SpecTypeActionRequirementTransitionPostConditions: + +Action Requirement Transition Post-Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 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 :ref:`SpecTypeActionRequirementName`. Each generic attribute + value shall be an + :ref:`SpecTypeActionRequirementTransitionPostConditionState`. 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 or ``N/A`` if the post-condition is not + applicable. + +* The value may be a string. It shall be the name of a skip reason. If a skip + reason is given instead of a listing of post-condition states, then this + transition is skipped and no test code runs for this transition. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * and, shall be not equal to "``NA``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransition` + +.. _SpecTypeActionRequirementTransitionPreConditionStateSet: + +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 + :ref:`SpecTypeActionRequirementName`. The list defines the set of states of + the pre-condition in the transition. + +* The value may be a string. The value ``all`` represents all states of the + pre-condition in this transition. The value ``N/A`` marks the pre-condition + as not applicable in this transition. The value shall be an element of + + * "``all``", and + + * "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransitionPreConditions` + +.. _SpecTypeActionRequirementTransitionPreConditions: + +Action Requirement Transition Pre-Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 for each + pre-condition the set of states before the action for a transition in an + action requirement. Generic attributes may be specified. Each generic + attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each generic + attribute value shall be an + :ref:`SpecTypeActionRequirementTransitionPreConditionStateSet`. 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. + +* The value may be a string. If this name is specified instead of explicit + pre-condition states, then the post-condition states of this entry are used + to define all remaining transitions of the map. The value shall be equal to + "``default``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransition` + +.. _SpecTypeApplicationConfigurationOptionName: + +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: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +.. _SpecTypeBooleanOrIntegerOrString: + +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: + +* :ref:`SpecTypeBuildOptionAction` + +* :ref:`SpecTypeInterfaceReturnValue` + +.. _SpecTypeBuildAssemblerOption: + +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: + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +.. _SpecTypeBuildCCompilerOption: + +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: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionCCompilerCheckAction` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildCPreprocessorOption: + +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: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildCXXCompilerOption: + +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: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionCXXCompilerCheckAction` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildDependencyConditionalLinkRole: + +Build Dependency Conditional Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``build-dependency-conditional``. It defines the build dependency +conditional role of links. All explicit attributes shall be specified. The +explicit attributes for this type are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It + shall define under which conditions the build dependency is enabled. + +.. _SpecTypeBuildDependencyLinkRole: + +Build Dependency Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``build-dependency``. It defines the build dependency role of links. + +.. _SpecTypeBuildIncludePath: + +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 +:ref:`SpecTypeBuildGroupItemType` item the includes are visible to all items +referenced by the group item. For :ref:`SpecTypeBuildBSPItemType`, +:ref:`SpecTypeBuildObjectsItemType`, :ref:`SpecTypeBuildLibraryItemType`, +:ref:`SpecTypeBuildStartFileItemType`, and +:ref:`SpecTypeBuildTestProgramItemType` 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: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildInstallDirective: + +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 :file:`wscript`. + +This type is used by the following types: + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +.. _SpecTypeBuildInstallPath: + +Build Install Path +^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the installation path of a + :ref:`SpecTypeBuildTarget`. + +This type is used by the following types: + +* :ref:`SpecTypeBuildConfigurationFileItemType` + +* :ref:`SpecTypeBuildConfigurationHeaderItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +.. _SpecTypeBuildLinkStaticLibraryDirective: + +Build Link Static Library Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an external static library identifier. +The library is used to link programs referenced by this item, e.g. ``m`` for +``libm.a``. The library is added to the build command through the ``stlib`` +attribute. It shall not be used for internal static libraries. Internal static +libraries shall be specified through the ``use-after`` and ``use-before`` +attributes to enable a proper build dependency tracking. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildLinkerOption: + +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: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildOptionAction: + +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 + :ref:`SpecTypeBuildTestProgramItemType` 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 :ref:`SpecTypeBooleanOrIntegerOrString`. The + action asserts that the action value is equal to the attribute value. + +assert-ge + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is greater than or equal to the attribute + value. + +assert-gt + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. 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 :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is less than or equal to the attribute value. + +assert-lt + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is less than the attribute value. + +assert-ne + The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. 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 + :ref:`SpecTypeBuildOptionCCompilerCheckAction`. + +check-cxx + The attribute value shall be a + :ref:`SpecTypeBuildOptionCXXCompilerCheckAction`. + +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. + +get-string-command-line + The attribute value shall be a string. The action gets the action value for + subsequent actions from the value of a command line option named by the + items ``name`` attribute. If no such command line option is present, then + the attribute 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 + :ref:`SpecTypeBuildOptionSetTestStateAction`. + +set-value + The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. 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: + +* :ref:`SpecTypeBuildOptionItemType` + +.. _SpecTypeBuildOptionCCompilerCheckAction: + +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 + :ref:`SpecTypeBuildCCompilerOption`. + +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: + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeBuildOptionCXXCompilerCheckAction: + +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 + :ref:`SpecTypeBuildCXXCompilerOption`. + +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: + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeBuildOptionDefaultValue: + +Build Option Default Value +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a build option default value. All explicit +attributes shall be specified. The explicit attributes for this type are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. + +value + The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. Its value + shall be the default value for the associated enabled-by expression. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionItemType` + +.. _SpecTypeBuildOptionName: + +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: + +* :ref:`SpecTypeBuildOptionItemType` + +.. _SpecTypeBuildOptionSetTestStateAction: + +Build Option Set Test State Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies the test state for a set of test programs with +an optional reason. All explicit attributes shall be specified. The explicit +attributes for this type are: + +reason + The attribute value shall be an optional string. If the value is present, + then it shall be the reason for the test state definition. + +state + The attribute value shall be a :ref:`SpecTypeBuildTestState`. It shall be + the test state for the associated list of tests. + +tests + The attribute value shall be a list of strings. It shall be the list of + test program names associated with the test state. The names shall + correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType` or + :ref:`SpecTypeBuildAdaTestProgramItemType` item. Due to the processing + order of items, there is no way to check if a specified test program name + is valid. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeBuildOptionValue: + +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 be no value (null). + +* The value may be a string. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +* :ref:`SpecTypeBuildOptionDefaultValue` + +.. _SpecTypeBuildSource: + +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 :file:`wscript`. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildTarget: + +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 :file:`wscript`. The +target file is located in the build tree. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildConfigurationFileItemType` + +* :ref:`SpecTypeBuildConfigurationHeaderItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildTestState: + +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: + +* :ref:`SpecTypeBuildOptionSetTestStateAction` + +.. _SpecTypeBuildUseAfterDirective: + +Build Use After Directive +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an internal static library identifier. +The library is used to link programs referenced by this item, e.g. ``z`` for +``libz.a``. The library is placed after the use items of the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildUseBeforeDirective: + +Build Use Before Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an internal static library identifier. +The library is used to link programs referenced by this item, e.g. ``z`` for +``libz.a``. The library is placed before the use items of the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeConstraintLinkRole: + +Constraint Link Role +^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``constraint``. It defines the constraint role of links. The link +target shall be a constraint. + +.. _SpecTypeCopyright: + +Copyright +^^^^^^^^^ + +The value shall be a string. It shall be a copyright statement of a copyright +holder of the specification item. The value + +* shall match with the regular expression + "``^\s*Copyright\s+\(C\)\s+[0-9]+,\s*[0-9]+\s+.+\s*$``", + +* or, shall match with the regular expression + "``^\s*Copyright\s+\(C\)\s+[0-9]+\s+.+\s*$``", + +* or, shall match with the regular expression + "``^\s*Copyright\s+\(C\)\s+.+\s*$``". + +This type is used by the following types: + +* :ref:`SpecTypeRootItemType` + +.. _SpecTypeEnabledByExpression: + +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 + :ref:`SpecTypeEnabledByExpression`. 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 :ref:`SpecTypeEnabledByExpression`. 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 + :ref:`SpecTypeEnabledByExpression`. 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 + :ref:`SpecTypeEnabledByExpression`. 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: + +* :ref:`SpecTypeActionRequirementTransition` + +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildOptionDefaultValue` + +* :ref:`SpecTypeEnabledByExpression` + +* :ref:`SpecTypeInterfaceIncludeLinkRole` + +* :ref:`SpecTypeRootItemType` + +Please have a look at the following example: + +.. code-block:: yaml + + enabled-by: + and: + - RTEMS_NETWORKING + - not: RTEMS_SMP + +.. _SpecTypeExternalDocumentReference: + +External Document Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeExternalReference` through the ``type`` +attribute if the value is ``document``. It specifies a reference to a document. + +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 + document. + +.. _SpecTypeExternalFileReference: + +External File Reference +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeExternalReference` through the ``type`` +attribute if the value is ``file``. It specifies a reference to a file. + +All explicit attributes shall be specified. The explicit attributes for this +type are: + +hash + The attribute value shall be a :ref:`SpecTypeSHA256HashValue`. It shall be + the SHA256 hash value of the content of the referenced file. + +.. _SpecTypeExternalReference: + +External Reference +^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a reference to some object external to the +specification. 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 referenced object. For *group* references use the Doxygen + group identifier. For *file* references use a file system path to the + file. + +type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the type of + the referenced object. + +This type is refined by the following types: + +* :ref:`SpecTypeExternalDocumentReference` + +* :ref:`SpecTypeExternalFileReference` + +* :ref:`SpecTypeGenericExternalReference` + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + +* :ref:`SpecTypeInterfaceUnspecifiedItemType` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRequirementValidationItemType` + +.. _SpecTypeFunctionImplementationLinkRole: + +Function Implementation Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``function-implementation``. It defines the function implementation +role of links. It is used to indicate that a +:ref:`SpecTypeFunctionalRequirementItemType` item specifies parts of the +function. + +.. _SpecTypeGenericExternalReference: + +Generic External Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``define`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``function`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``group`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``macro`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``url`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``variable`` + +It specifies a reference to an object of the specified type. + +.. _SpecTypeGlossaryMembershipLinkRole: + +Glossary Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``glossary-member``. It defines the glossary membership role of links. + +.. _SpecTypeIntegerOrString: + +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: + +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeInterfaceBriefDescription: + +Interface Brief Description +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the brief description of the + interface. It should be a single sentence. The value shall not match with + the regular expression "``\n\n``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceHeaderFileItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + +.. _SpecTypeInterfaceCompoundDefinitionKind: + +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: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +.. _SpecTypeInterfaceCompoundMemberCompound: + +Interface Compound Member Compound +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind`` + attribute if the value is ``struct`` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind`` + attribute if the value is ``union`` + +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 + :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`. + +.. _SpecTypeInterfaceCompoundMemberDeclaration: + +Interface Compound Member Declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceCompoundMemberDefinition` through +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. + +.. _SpecTypeInterfaceCompoundMemberDefinition: + +Interface Compound Member Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 + interface compound member definition. All explicit attributes shall be + specified. The explicit attributes for this type are: + + brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + + description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + + 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. + +* There may be no value (null). + +This type is refined by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberCompound` + +* :ref:`SpecTypeInterfaceCompoundMemberDeclaration` + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant` + +.. _SpecTypeInterfaceCompoundMemberDefinitionDirective: + +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 + :ref:`SpecTypeInterfaceCompoundMemberDefinition`. 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 + :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberCompound` + +.. _SpecTypeInterfaceCompoundMemberDefinitionVariant: + +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 + :ref:`SpecTypeInterfaceCompoundMemberDefinition`. 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 + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective` + +.. _SpecTypeInterfaceDefinition: + +Interface Definition +^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may 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: + +* :ref:`SpecTypeInterfaceDefinitionDirective` + +* :ref:`SpecTypeInterfaceDefinitionVariant` + +.. _SpecTypeInterfaceDefinitionDirective: + +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 :ref:`SpecTypeInterfaceDefinition`. 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 + :ref:`SpecTypeInterfaceDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +.. _SpecTypeInterfaceDefinitionVariant: + +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 :ref:`SpecTypeInterfaceDefinition`. 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 + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceDefinitionDirective` + +.. _SpecTypeInterfaceDescription: + +Interface Description +^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may 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 + :ref:`SpecTypeInterfaceNotes`. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceParameter` + +* :ref:`SpecTypeInterfaceReturnValue` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + +.. _SpecTypeInterfaceEnabledByExpression: + +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 + :ref:`SpecTypeInterfaceEnabledByExpression`. The *and* operator defines a + *logical and* of the expressions in the list. + + not + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. The *not* operator defines a + *logical not* of the expression. + + or + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. 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 + :ref:`SpecTypeInterfaceEnabledByExpression`. 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: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant` + +* :ref:`SpecTypeInterfaceDefinitionVariant` + +* :ref:`SpecTypeInterfaceEnabledByExpression` + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + +.. _SpecTypeInterfaceEnumDefinitionKind: + +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: + +* :ref:`SpecTypeInterfaceEnumItemType` + +.. _SpecTypeInterfaceEnumeratorLinkRole: + +Interface Enumerator Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-enumerator``. It defines the interface enumerator role of +links. + +.. _SpecTypeInterfaceFunctionLinkRole: + +Interface Function Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-function``. It defines the interface function role of +links. It is used to indicate that a :ref:`SpecTypeActionRequirementItemType` +item specifies functional requirements of an +:ref:`SpecTypeInterfaceFunctionOrMacroItemType` item. + +.. _SpecTypeInterfaceFunctionOrMacroDefinition: + +Interface Function or Macro Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 a + function definition. All explicit attributes shall be specified. The explicit + attributes for this type are: + + attributes + The attribute value shall be an optional string. If the value is present, + then it shall be the function attributes. On the attributes a + context-sensitive substitution of item variables is performed. A + function attribute is for example the indication that the function does + not return to the caller. + + 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 an optional string. If the value is present, + then it shall be the function return type. On the return type a + context-sensitive substitution of item variables is performed. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective` + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` + +.. _SpecTypeInterfaceFunctionOrMacroDefinitionDirective: + +Interface Function or Macro Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function or macro definition directive. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +default + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. 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 + :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +.. _SpecTypeInterfaceFunctionOrMacroDefinitionVariant: + +Interface Function or Macro Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function or macro definition variant. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. 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 + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective` + +.. _SpecTypeInterfaceGroupIdentifier: + +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: + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeInterfaceGroupMembershipLinkRole: + +Interface Group Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-ingroup``. It defines the interface group membership role +of links. + +.. _SpecTypeInterfaceHiddenGroupMembershipLinkRole: + +Interface Hidden Group Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-ingroup-hidden``. It defines the interface hidden group +membership role of links. This role may be used to make an interface a group +member and hide this relationship in the documentation. An example is an +optimized macro implementation of a directive which has the same name as the +corresponding directive. + +.. _SpecTypeInterfaceIncludeLinkRole: + +Interface Include Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-include``. It defines the interface include role of links +and is used to indicate that an interface container includes another interface +container. For example, one header file includes another header file. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It + shall define under which conditions the interface container is included. + +.. _SpecTypeInterfaceNotes: + +Interface Notes +^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may 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: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeInterfaceParameter: + +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 :ref:`SpecTypeInterfaceDescription`. + +dir + The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`. + +name + The attribute value shall be a string. It shall be the interface parameter + name. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +.. _SpecTypeInterfaceParameterDirection: + +Interface Parameter Direction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may 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: + +* :ref:`SpecTypeInterfaceParameter` + +* :ref:`SpecTypeTestRunParameter` + +.. _SpecTypeInterfacePlacementLinkRole: + +Interface Placement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-placement``. It defines the interface placement role of +links. It is used to indicate that an interface definition is placed into an +interface container, for example a header file. + +.. _SpecTypeInterfaceReturnDirective: + +Interface Return Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 + 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 + :ref:`SpecTypeInterfaceReturnValue`. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +.. _SpecTypeInterfaceReturnValue: + +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 :ref:`SpecTypeInterfaceDescription`. + +value + The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. It + shall be the described interface return value. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceReturnDirective` + +.. _SpecTypeInterfaceTargetLinkRole: + +Interface Target Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-target``. It defines the interface target role of links. +It is used for interface forward declarations. + +.. _SpecTypeLink: + +Link +^^^^ + +This set of attributes specifies a link from one specification item to another +specification item. The links in a list are ordered. The first link in the +list is processed first. All explicit attributes shall be specified. The +explicit attributes for this type are: + +role + The attribute value shall be a :ref:`SpecTypeName`. It shall be the role of + the link. + +uid + The attribute value shall be an :ref:`SpecTypeUID`. It shall be the + absolute or relative UID of the link target item. + +This type is refined by the following types: + +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildDependencyLinkRole` + +* :ref:`SpecTypeConstraintLinkRole` + +* :ref:`SpecTypeFunctionImplementationLinkRole` + +* :ref:`SpecTypeGlossaryMembershipLinkRole` + +* :ref:`SpecTypeInterfaceEnumeratorLinkRole` + +* :ref:`SpecTypeInterfaceFunctionLinkRole` + +* :ref:`SpecTypeInterfaceGroupMembershipLinkRole` + +* :ref:`SpecTypeInterfaceHiddenGroupMembershipLinkRole` + +* :ref:`SpecTypeInterfaceIncludeLinkRole` + +* :ref:`SpecTypeInterfacePlacementLinkRole` + +* :ref:`SpecTypeInterfaceTargetLinkRole` + +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + +* :ref:`SpecTypePlacementOrderLinkRole` + +* :ref:`SpecTypeProxyMemberLinkRole` + +* :ref:`SpecTypeRegisterBlockIncludeRole` + +* :ref:`SpecTypeRequirementRefinementLinkRole` + +* :ref:`SpecTypeRequirementValidationLinkRole` + +* :ref:`SpecTypeRuntimeMeasurementRequestLinkRole` + +* :ref:`SpecTypeSpecificationMemberLinkRole` + +* :ref:`SpecTypeSpecificationRefinementLinkRole` + +* :ref:`SpecTypeUnitTestLinkRole` + +This type is used by the following types: + +* :ref:`SpecTypeRootItemType` + +* :ref:`SpecTypeTestCaseAction` + +* :ref:`SpecTypeTestCaseCheck` + +.. _SpecTypeName: + +Name +^^^^ + +The value shall be a string. A string is a valid name if it matches with the +``^([a-z][a-z0-9-]*|SPDX-License-Identifier)$`` regular expression. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeBuildItemType` + +* :ref:`SpecTypeExternalReference` + +* :ref:`SpecTypeFunctionalRequirementItemType` + +* :ref:`SpecTypeGlossaryItemType` + +* :ref:`SpecTypeInterfaceItemType` + +* :ref:`SpecTypeLink` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` + +* :ref:`SpecTypeRegisterDefinition` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRequirementValidationItemType` + +* :ref:`SpecTypeRootItemType` + +* :ref:`SpecTypeRuntimeMeasurementParameterSet` + +* :ref:`SpecTypeRuntimePerformanceParameterSet` + +* :ref:`SpecTypeSpecificationAttributeValue` + +* :ref:`SpecTypeSpecificationExplicitAttributes` + +* :ref:`SpecTypeSpecificationGenericAttributes` + +* :ref:`SpecTypeSpecificationItemType` + +* :ref:`SpecTypeSpecificationList` + +* :ref:`SpecTypeSpecificationRefinementLinkRole` + +.. _SpecTypeOptionalFloatingPointNumber: + +Optional Floating-Point Number +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a floating-point number. + +* There may be no value (null). + +.. _SpecTypeOptionalInteger: + +Optional Integer +^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be an integer number. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeOptionalString: + +Optional String +^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. + +.. _SpecTypePerformanceRuntimeLimitsLinkRole: + +Performance Runtime Limits Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``performance-runtime-limits``. It defines the performance runtime +limits role of links. All explicit attributes shall be specified. The explicit +attributes for this type are: + +limits + The attribute value shall be a + :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. + +.. _SpecTypePlacementOrderLinkRole: + +Placement Order Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``placement-order``. This link role defines the placement order of +items in a container item (for example an interface function in a header file +or a documentation section). + +.. _SpecTypeProxyMemberLinkRole: + +Proxy Member Link Role +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``proxy-member``. It defines the proxy member role of links. Items +may use this role to link to :ref:`SpecTypeProxyItemTypes` items. + +.. _SpecTypeRegisterBitsDefinition: + +Register Bits Definition +^^^^^^^^^^^^^^^^^^^^^^^^ + +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 a + register bit field. Single bits are bit fields with a width of one. All + explicit attributes shall be specified. The explicit attributes for this type + are: + + brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + + description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + + name + The attribute value shall be a string. It shall be the name of the + register bit field. + + properties + The attribute value shall be a list of strings. It shall be the list of + bit field properties. Properties are for example if the bit field can be + read or written, or an access has side-effects such as clearing a status. + + start + The attribute value shall be an integer number. It shall be the start bit + of the bit field. Bit ``0`` is the least-significant bit. + + width + The attribute value shall be an integer number. It shall be the width in + bits of the bit field. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBitsDefinitionDirective` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +.. _SpecTypeRegisterBitsDefinitionDirective: + +Register Bits Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register bits directive. All explicit +attributes shall be specified. The explicit attributes for this type are: + +default + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinition`. 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 a + :ref:`SpecTypeRegisterBitsDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterDefinition` + +.. _SpecTypeRegisterBitsDefinitionVariant: + +Register Bits Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register bits variant. 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 a + :ref:`SpecTypeRegisterBitsDefinition`. 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 + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBitsDefinitionDirective` + +.. _SpecTypeRegisterBlockIncludeRole: + +Register Block Include Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``register-block-include``. It defines the register block include role +of links. Links of this role are used to build register blocks using other +register blocks. All explicit attributes shall be specified. The explicit +attributes for this type are: + +name + The attribute value shall be a string. It shall be a name to identify the + included register block within the item. The name shall be unique within + the scope of the item links of this role and the + :ref:`SpecTypeRegisterList`. + +.. _SpecTypeRegisterBlockMemberDefinition: + +Register Block Member Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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 a + register block member definition. All explicit attributes shall be specified. + The explicit attributes for this type are: + + count + The attribute value shall be an integer number. It shall be the count of + registers of the register block member. + + name + The attribute value shall be a :ref:`SpecTypeRegisterName`. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + +.. _SpecTypeRegisterBlockMemberDefinitionDirective: + +Register Block Member Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition directive. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +default + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. The default definition will + be used if no variant-specific definition is enabled. + +offset + The attribute value shall be an integer number. It shall be the address of + the register block member relative to the base address of the register + block. + +variants + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterBlockMemberDefinitionVariant: + +Register Block Member Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition variant. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +definition + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. 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 + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +.. _SpecTypeRegisterDefinition: + +Register Definition +^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register. All explicit attributes shall be +specified. The explicit attributes for this type are: + +bits + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinitionDirective`. + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name to identify the + register definition. The name shall be unique within the scope of the + :ref:`SpecTypeRegisterBlockIncludeRole` links of the item and the + :ref:`SpecTypeRegisterList`. + +width + The attribute value shall be an integer number. It shall be the width of + the register in bits. + +In addition to the explicit attributes, generic attributes may be specified. +Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value +may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterName: + +Register Name +^^^^^^^^^^^^^ + +The value shall be a string. The name consists either of an identifier, or an +identifier and an alias. The identifier and alias are separated by a colon +(``:``). The identifier shall match with the name of a register definition of +the item (see :ref:`SpecTypeRegisterDefinition`) or the name of a register +block include of the item (see :ref:`SpecTypeRegisterBlockIncludeRole`). If no +alias is specified, then the identifier is used for the register block member +name, otherwise the alias is used. If the register block member names are not +unique within the item, then a postfix number is appended to the names. The +number starts with zero for each set of names. The value shall match with the +regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*(:[a-zA-Z_][a-zA-Z0-9_]*)?$``". + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinition` + +.. _SpecTypeRequirementDesignGroupIdentifier: + +Requirement Design Group Identifier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the identifier of the requirement + design group. The value shall match with the regular expression + "``^[a-zA-Z0-9_]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeDesignGroupRequirementItemType` + +.. _SpecTypeRequirementRefinementLinkRole: + +Requirement Refinement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``requirement-refinement``. It defines the requirement refinement role +of links. + +.. _SpecTypeRequirementText: + +Requirement Text +^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall state a requirement or constraint. The +text should not use one of the following words or phrases: + +* 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 + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementState` + +* :ref:`SpecTypeApplicationConfigurationGroupItemType` + +* :ref:`SpecTypeConstraintItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeRequirementItemType` + +.. _SpecTypeRequirementValidationLinkRole: + +Requirement Validation Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``validation``. It defines the requirement validation role of links. + +.. _SpecTypeRuntimeMeasurementEnvironmentName: + +Runtime Measurement Environment Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the runtime measurement environment +name. The value + +* shall be an element of + + * "``FullCache``", + + * "``HotCache``", and + + * "``DirtyCache``", + +* or, shall match with the regular expression "``^Load/[1-9][0-9]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` + +.. _SpecTypeRuntimeMeasurementEnvironmentTable: + +Runtime Measurement Environment Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes provides runtime performance limits for a set of runtime +measurement environments. Generic attributes may be specified. Each generic +attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. Each +generic attribute value shall be a :ref:`SpecTypeRuntimeMeasurementValueTable`. + +This type is used by the following types: + +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + +.. _SpecTypeRuntimeMeasurementParameterSet: + +Runtime Measurement Parameter Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines parameters of the runtime measurement test case. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +sample-count + The attribute value shall be an integer number. It shall be the sample + count of the runtime measurement context. + +In addition to the explicit attributes, generic attributes may be specified. +Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value +may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +.. _SpecTypeRuntimeMeasurementRequestLinkRole: + +Runtime Measurement Request Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``runtime-measurement-request``. It defines the runtime measurement +request role of links. The link target shall be a +:ref:`SpecTypeRuntimeMeasurementTestItemType` item. + +.. _SpecTypeRuntimeMeasurementValueKind: + +Runtime Measurement Value Kind +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the kind of a runtime measurement +value. The value shall be an element of + +* "``max-lower-bound``", + +* "``max-upper-bound``", + +* "``mean-lower-bound``", + +* "``mean-upper-bound``", + +* "``median-lower-bound``", + +* "``median-upper-bound``", + +* "``min-lower-bound``", and + +* "``min-upper-bound``". + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementValueTable` + +.. _SpecTypeRuntimeMeasurementValueTable: + +Runtime Measurement Value Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes provides a set of runtime measurement values each of a +specified kind. The unit of the values shall be one second. Generic attributes +may be specified. Each generic attribute key shall be a +:ref:`SpecTypeRuntimeMeasurementValueKind`. Each generic attribute value shall +be a floating-point number. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` + +.. _SpecTypeRuntimePerformanceParameterSet: + +Runtime Performance Parameter Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines parameters of the runtime performance +requirement. Generic attributes may be specified. Each generic attribute key +shall be a :ref:`SpecTypeName`. The attribute value may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +.. _SpecTypeSHA256HashValue: + +SHA256 Hash Value +^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be a SHA256 hash value encoded in +base64url. The value shall match with the regular expression +"``^[A-Za-z0-9+_=-]{44}$``". + +This type is used by the following types: + +* :ref:`SpecTypeExternalFileReference` + +.. _SpecTypeSPDXLicenseIdentifier: + +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: + +* :ref:`SpecTypeRootItemType` + +.. _SpecTypeSpecificationAttributeSet: + +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 + :ref:`SpecTypeSpecificationExplicitAttributes`. 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 + :ref:`SpecTypeSpecificationGenericAttributes`. It shall specify the generic + attributes of the attribute set. + +mandatory-attributes + The attribute value shall be a + :ref:`SpecTypeSpecificationMandatoryAttributes`. It shall specify the + mandatory attributes of the attribute set. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationAttributeValue: + +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 :ref:`SpecTypeName`. It shall be the + specification type of the attribute value. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationExplicitAttributes` + +.. _SpecTypeSpecificationBooleanValue: + +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: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationExplicitAttributes: + +Specification Explicit Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generic attributes may be specified. Each generic attribute key shall be a +:ref:`SpecTypeName`. Each generic attribute value shall be a +:ref:`SpecTypeSpecificationAttributeValue`. 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: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationFloatingPointAssert: + +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 + :ref:`SpecTypeSpecificationFloatingPointAssert`. 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 + :ref:`SpecTypeSpecificationFloatingPointAssert`. 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 + :ref:`SpecTypeSpecificationFloatingPointAssert`. 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 + :ref:`SpecTypeSpecificationFloatingPointAssert`. 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: + +* :ref:`SpecTypeSpecificationFloatingPointAssert` + +* :ref:`SpecTypeSpecificationFloatingPointValue` + +.. _SpecTypeSpecificationFloatingPointValue: + +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 + :ref:`SpecTypeSpecificationFloatingPointAssert`. 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: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationGenericAttributes: + +Specification Generic Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies generic attributes. Generic attributes are +attributes which are not explicitly specified by +:ref:`SpecTypeSpecificationExplicitAttributes`. 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 :ref:`SpecTypeName`. It shall be the + specification type of the generic attribute keys. + +value-spec-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type of the generic attribute values. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationInformation: + +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 :ref:`SpecTypeSpecificationBooleanValue`. It + shall specify a boolean value. + +dict + The attribute value shall be a :ref:`SpecTypeSpecificationAttributeSet`. It + shall specify a set of attributes. + +float + The attribute value shall be a + :ref:`SpecTypeSpecificationFloatingPointValue`. It shall specify a + floating-point value. + +int + The attribute value shall be a :ref:`SpecTypeSpecificationIntegerValue`. It + shall specify an integer value. + +list + The attribute value shall be a :ref:`SpecTypeSpecificationList`. 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 :ref:`SpecTypeSpecificationStringValue`. It + shall specify a string. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationItemType` + +.. _SpecTypeSpecificationIntegerAssert: + +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 + :ref:`SpecTypeSpecificationIntegerAssert`. 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 :ref:`SpecTypeSpecificationIntegerAssert`. + 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 + :ref:`SpecTypeSpecificationIntegerAssert`. 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 + :ref:`SpecTypeSpecificationIntegerAssert`. 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: + +* :ref:`SpecTypeSpecificationIntegerAssert` + +* :ref:`SpecTypeSpecificationIntegerValue` + +.. _SpecTypeSpecificationIntegerValue: + +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 :ref:`SpecTypeSpecificationIntegerAssert`. + 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: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationList: + +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 :ref:`SpecTypeName`. It shall be the + specification type of elements of the list. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationMandatoryAttributes: + +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 :ref:`SpecTypeName`. + 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: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationMemberLinkRole: + +Specification Member Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``spec-member``. It defines the specification membership role of +links. + +.. _SpecTypeSpecificationRefinementLinkRole: + +Specification Refinement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``spec-refinement``. It defines the specification refinement role of +links. All explicit attributes shall be specified. The explicit attributes for +this type are: + +spec-key + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type refinement attribute key of the specification + refinement. + +spec-value + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type refinement attribute value of the specification + refinement. + +.. _SpecTypeSpecificationStringAssert: + +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 + :ref:`SpecTypeSpecificationStringAssert`. 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 :ref:`SpecTypeSpecificationStringAssert`. + 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 + :ref:`SpecTypeSpecificationStringAssert`. 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 + :ref:`SpecTypeSpecificationStringAssert`. 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: + +* :ref:`SpecTypeSpecificationStringAssert` + +* :ref:`SpecTypeSpecificationStringValue` + +.. _SpecTypeSpecificationStringValue: + +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 :ref:`SpecTypeSpecificationStringAssert`. + 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: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeTestCaseAction: + +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-brief + The attribute value shall be an optional string. It shall be the test case + action brief description. + +action-code + 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 + :ref:`SpecTypeTestCaseCheck`. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. The links should use the + :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the + :ref:`SpecTypeUnitTestLinkRole` for unit tests. + +This type is used by the following types: + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestCaseCheck: + +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: + +brief + The attribute value shall be an optional string. It shall be the test case + check brief description. + +code + The attribute value shall be a string. It shall be the test case check + code. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. The links should use the + :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the + :ref:`SpecTypeUnitTestLinkRole` for unit tests. + +This type is used by the following types: + +* :ref:`SpecTypeTestCaseAction` + +.. _SpecTypeTestContextMember: + +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 be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestHeader: + +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 a 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 header code. The header code is placed at file + scope after the general test declarations and before the test run + function declaration. + + freestanding + The attribute value shall be a boolean. The value shall be ``true``, if + the test case is freestanding, otherwise ``false``. Freestanding test + cases are not statically registered. Instead the generated test runner + uses :c:func:`T_case_begin` and :c:func:`T_case_end`. + + 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 a + :ref:`SpecTypeTestRunParameter`. + + target + The attribute value shall be a string. It shall be the path to the + generated test header file. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestRunParameter: + +Test Run Parameter +^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a parameter for the test run function. In case +this parameter is used in an :ref:`SpecTypeActionRequirementItemType` item, +then the parameter is also added as a member to the test context, see +:ref:`SpecTypeTestContextMember`. 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 :ref:`SpecTypeInterfaceParameterDirection`. + +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: + +* :ref:`SpecTypeTestHeader` + +.. _SpecTypeTestSupportMethod: + +Test Support 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 support 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 + support method brief description. + + code + The attribute value shall be a string. It shall be the test support + method code. The code may use a local variable ``ctx`` which points to + the test context, see :ref:`SpecTypeTestContextMember`. + + description + The attribute value shall be an optional string. It shall be the test + support method description. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeUID: + +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: + +* :ref:`SpecTypeLink` + +.. _SpecTypeUnitTestLinkRole: + +Unit Test Link Role +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``unit-test``. It defines the unit test role of links. For unit tests +the link target should be the :ref:`SpecTypeInterfaceDomainItemType` containing +the software unit. 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 tested + software unit. diff --git a/eng/req/management.rst b/eng/req/management.rst new file mode 100644 index 0000000..4fb379c --- /dev/null +++ b/eng/req/management.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +Requirement Management +====================== + +Change Control Board +-------------------- + +Working with requirements usually involves a Change Control Board +(:term:`CCB`). The CCB of the RTEMS Project is the +`RTEMS developer mailing list <https://lists.rtems.org/mailman/listinfo/devel>`_. + +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 <https://git.rtems.org/rtems/tree/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 <https://docs.rtems.org/branches/master/user/support/contrib.html#patch-review-process>`_. +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 (:term:`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. + +Add a Requirement +----------------- + +.. image:: ../../images/eng/req-add.* + :scale: 70 + :align: center + +.. _ReqEngModifyRequirement: + +Modify a Requirement +-------------------- + +.. image:: ../../images/eng/req-modify.* + :scale: 70 + :align: center + +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 :ref:`modify a requirement +<ReqEngModifyRequirement>`. diff --git a/eng/req/req-for-req.rst b/eng/req/req-for-req.rst new file mode 100644 index 0000000..5631b7d --- /dev/null +++ b/eng/req/req-for-req.rst @@ -0,0 +1,406 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +Requirements for Requirements +============================= + +.. _ReqEngIdent: + +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 :file:`build/cpukit/librtemscpu.yml` inside a +:file:`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 +:c:func:`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 :c:func:`rtems_task_create`) + * delete-* (requirements for :c:func:`rtems_task_delete`) + * exit-* (requirements for :c:func:`rtems_task_exit`) + * getaff-* (requirements for :c:func:`rtems_task_get_affinity`) + * getpri-* (requirements for :c:func:`rtems_task_get_priority`) + * getsched-* (requirements for :c:func:`rtems_task_get_scheduler`) + * ident-* (requirements for :c:func:`rtems_task_ident`) + * issusp-* (requirements for :c:func:`rtems_task_is_suspended`) + * iter-* (requirements for :c:func:`rtems_task_iterate`) + * mode-* (requirements for :c:func:`rtems_task_mode`) + * restart-* (requirements for :c:func:`rtems_task_restart`) + * resume* (requirements for :c:func:`rtems_task_resume`) + * self* (requirements for :c:func:`rtems_task_self`) + * setaff-* (requirements for :c:func:`rtems_task_set_affinity`) + * setpri-* (requirements for :c:func:`rtems_task_set_priority`) + * setsched* (requirements for :c:func:`rtems_task_set_scheduler`) + * start-* (requirements for :c:func:`rtems_task_start`) + * susp-* (requirements for :c:func:`rtems_task_suspend`) + * wkafter-* (requirements for :c:func:`rtems_task_wake_after`) + * wkwhen-* (requirements for :c:func:`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. :file:`spec/classic/task/test`. A +test specification directory may contain also validations by analysis, by +inspection, and by design, see :ref:`ReqEngValidation`. + +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 :cite:`RFC2119` and ECSS-E-ST-10-06C :cite:`ECSS_E_ST_10_06C`. + +Absolute Requirements +~~~~~~~~~~~~~~~~~~~~~ + +Absolute requirements shall be expressed with the verbal form *shall* and no +other terms. + +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. + +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. + +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.) + +Possibilities and Capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Possibilities and capabilities shall be expressed with the verbal form *can* +and no other terms. + +.. _ReqEngSyntax: + +Syntax +------ + +Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate +requirements. A recommended reading list to get familiar with this approach is +:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, +:cite:`Mavin:2016:LLEARS`, and `Alisair Mavin's web site +<https://alistairmavin.com/ears/>`_. 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). + +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 :cite:`Wiegers:2013:SR`. 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. + +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. + + ... + +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. + +Use of Project-Specific Terms and Abbreviations +----------------------------------------------- + +All project-specific terms and abbreviations used to formulate requirements +shall be defined in the project glossary. + +.. _ReqEngJustReq: + +Justification of Requirements +----------------------------- + +Each requirement shall have a rationale or justification recorded in a +dedicated section of the requirement file. See ``rationale`` attribute for +:ref:`ReqEngSpecificationItems`. + +.. _ReqEngValidation: + +Requirement Validation +---------------------- + +The validation of each :ref:`SpecTypeRequirementItemType` item shall be +accomplished by one or more specification items of the types +:ref:`SpecTypeTestCaseItemType` or :ref:`SpecTypeRequirementValidationItemType` +through a link from the validation item to the requirement item with the +:ref:`SpecTypeRequirementValidationLinkRole`. + +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. + +.. _ReqEngResAndPerf: + +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. diff --git a/eng/req/tooling.rst b/eng/req/tooling.rst new file mode 100644 index 0000000..2853932 --- /dev/null +++ b/eng/req/tooling.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +Tooling +======= + +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 :term:`ReqIF`. + +Tool Evaluation +--------------- + +During an evaluation phase the following tools were considered: + +* `aNimble <https://sourceforge.net/projects/nimble/>`_ +* :term:`Doorstop` +* `OSRMT <https://github.com/osrmt/osrmt>`_ +* `Papyrus <https://www.eclipse.org/papyrus/>`_ +* `ProR <https://www.eclipse.org/rmf/pror/>`_ +* `ReqIF Studio <https://formalmind.com/tools/studio/>`_ +* `Requirement Heap <https://sourceforge.net/projects/reqheap/>`_ +* `rmToo <http://rmtoo.florath.net/>`_ + +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. + +.. _ReqEngDoorstop: + +Best Available Tool - Doorstop +------------------------------ + +:term:`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 :term:`YAML` format. Requirements +are organized in documents and can be linked to each other +:cite:`Browning:2014:RequirementsManagement`. + +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 <https://doorstop.readthedocs.io/en/latest/reference/item/>`_ +(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 +<https://doorstop.readthedocs.io/en/latest/reference/item/#reviewed>`_. +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 <https://github.com/doorstop-dev/doorstop/issues/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. + +.. _ReqEngManagementTool: + +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. diff --git a/eng/req/traceability.rst b/eng/req/traceability.rst new file mode 100644 index 0000000..99c4931 --- /dev/null +++ b/eng/req/traceability.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +.. _ReqEngTrace: + +Traceability of Specification Items +=================================== + +The standard ECSS-E-ST-10-06C demands that requirements shall be under +configuration management, backwards-traceable and forward-traceable +:cite:`ECSS_E_ST_10_06C`. Requirements are a specialization of specification +items in RTEMS. + +.. _ReqEngTraceHistory: + +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 <https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_). +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. + +.. _ReqEngTraceBackward: + +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. + +.. _ReqEngTraceForward: + +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. + +.. _ReqEngTraceReqArchDesign: + +Traceability between Software Requirements, Architecture and Design +------------------------------------------------------------------- + +The software requirements are implemented in custom YAML files, see +:ref:`ReqEngSpecificationItems`. 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. RTEMSTopLevel\ MidLevel\ +LowLevel. The link from a Doxygen group to its parent group is realized +through the ``@ingroup`` special command. The link from a Doxygen group or +:term:`software component` to the corresponding requirement is realized through +a ``@satisfy{req}`` `custom command +<http://www.doxygen.nl/manual/custcmd.html>`_ 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. diff --git a/eng/stakeholders.rst b/eng/stakeholders.rst index 756c462..184f890 100644 --- a/eng/stakeholders.rst +++ b/eng/stakeholders.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2018 RTEMS Foundation, The RTEMS Documentation Project RTEMS Stakeholders diff --git a/eng/test-framework.rst b/eng/test-framework.rst index b6411b5..25bbad9 100644 --- a/eng/test-framework.rst +++ b/eng/test-framework.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018, 2019 embedded brains GmbH -.. Copyright (C) 2018, 2019 Sebastian Huber +.. Copyright (C) 2018, 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 2018, 2020 Sebastian Huber Software Test Framework *********************** @@ -16,6 +16,8 @@ features: * Implemented in standard C11 +* Tests can be written in C or C++ + * Runs on at least FreeBSD, MSYS2, Linux and RTEMS * Test runner and test case code can be in separate translation units @@ -67,11 +69,11 @@ A `test suite` is a collection of test cases. A `test case` consists of individual test actions and checks. A `test check` determines if the outcome of a test action meets its expectation. A `test action` is a program sequence with an observable outcome, for example a function invocation with a return -status. If the test action outcome is all right, then the test check passes, -otherwise the test check fails. The test check failures of a test case are -summed up. A test case passes, if the failure count of this test case is zero, -otherwise the test case fails. The test suite passes if all test cases pass, -otherwise it fails. +status. If a test action produces the expected outcome as determined by the +corresponding test check, then this test check passes, otherwise this test +check fails. The test check failures of a test case are summed up. A test +case passes, if the failure count of this test case is zero, otherwise the test +case fails. The test suite passes if all test cases pass, otherwise it fails. Test Cases ---------- @@ -89,7 +91,7 @@ body: The test case `name` must be a valid C designator. The test case names must be unique within the test suite. Just link modules with test cases to the test runner to form a test suite. The test cases are automatically registered via -static constructors. +static C constructors. .. code-block:: c :caption: Test Case Example @@ -129,6 +131,8 @@ two test steps (`N`) and one test failure (`F`). The test case execution duration (`D`) was 0.001657 seconds. For test report details see: :ref:`Test Reporting <RTEMSTestFrameworkTestReporting>`. +.. _RTEMSTestFrameworkFixture: + Test Fixture ------------ @@ -144,13 +148,43 @@ macro followed by a function body: The test case `name` must be a valid C designator. The test case names must be unique within the test suite. The `fixture` must point to a statically -initialized read-only object of type `T_fixture`. The test fixture -provides methods to setup, stop and tear down a test case. A context is passed -to the methods. The initial context is defined by the read-only fixture -object. The context can be obtained by the `T_fixture_context()` -function. It can be set within the scope of one test case by the -`T_set_fixture_context()` function. This can be used for example to -dynamically allocate a test environment in the setup method. +initialized read-only object of type `T_fixture`. + +.. code-block:: c + + typedef struct T_fixture { + void (*setup)(void *context); + void (*stop)(void *context); + void (*teardown)(void *context); + void (*scope)(void *context, char *buffer, size_t size); + void *initial_context; + } T_fixture; + +The test fixture provides methods to setup, stop, and teardown a test case as +well as the scope for log messages. A context is passed to each of the +methods. The initial context is defined by the read-only fixture object. The +context can be obtained by the `T_fixture_context()` function. The context can +be changed within the scope of one test case by the `T_set_fixture_context()` +function. The next test case execution using the same fixture will start again +with the initial context defined by the read-only fixture object. Setting the +context can be used for example to dynamically allocate a test environment in +the setup method. + +The test case fixtures of a test case are organized as a stack. Fixtures can +be dynamically added to a test case and removed from a test case via the +`T_push_fixture()` and `T_pop_fixture()` functions. + +.. code-block:: c + + void *T_push_fixture(T_fixture_node *node, const T_fixture *fixture); + + void T_pop_fixture(void); + +The `T_push_fixture()` function needs an uninitialized fixture node which must +exist until `T_pop_fixture()` is called. It returns the initial context of the +fixture. At the end of a test case all pushed fixtures are popped +automatically. A call of `T_pop_fixture()` invokes the teardown method of the +fixture and must correspond to a previous call to `T_push_fixture()`. .. code-block:: c :caption: Test Fixture Example @@ -237,9 +271,9 @@ dynamically allocate a test environment in the setup method. Test Case Planning ------------------ -Each non-quiet test check fetches and increments the test step counter -atomically. For each test case execution the planned steps can be specified -with the `T_plan()` function. +A non-quiet test check fetches and increments the test step counter atomically. +For each test case execution the planned steps can be specified with the +`T_plan()` function. .. code-block:: c @@ -318,7 +352,7 @@ execution follows exactly the planned steps. Test Case Resource Accounting ----------------------------- -The framework can check if various resources are leaked during a test case +The framework can check if various resources have leaked during a test case execution. The resource checkers are specified by the test run configuration. On RTEMS, checks for the following resources are available @@ -452,13 +486,14 @@ test case execution. You can provide an optional destroy function to Test Case Destructors --------------------- -You can add test case destructors with `T_add_destructor()`. They are called -automatically at the test case end before the resource accounting takes place. -Optionally, a registered destructor can be removed before the test case end -with `T_remove_destructor()`. The `T_destructor` structure of a destructor -must exist after the return from the test case body. Do not use stack memory -or dynamic memory obtained via `T_malloc()`, `T_calloc()` or `T_zalloc()` for -the `T_destructor` structure. +You can add test case destructors with `T_add_destructor()`. The destructors +are called automatically at the test case end before the resource accounting +takes place. Optionally, a registered destructor can be removed before the +test case end with `T_remove_destructor()`. The `T_destructor` structure of a +destructor must exist after the return from the test case body. It is +recommended to use statically allocated memory. Do not use stack memory or +dynamic memory obtained via `T_malloc()`, `T_calloc()` or `T_zalloc()` for the +`T_destructor` structure. .. code-block:: c @@ -497,16 +532,31 @@ the `T_destructor` structure. Test Checks ----------- -A `test check` determines if the actual value presented to the test check meets -its expectation. The actual value should represent the outcome of a test -action. If the actual value is all right, then the test check passes, -otherwise the test check fails. A failed test check does not stop the test -case execution immediately unless the `T_assert_*()` test variant is used. -Each test check increments the test step counter unless the `T_quiet_*()` test -variant is used. The test step counter is initialized to zero before the test -case begins to execute. The `T_step_*(step, ...)` test check variants verify -that the test step counter is equal to the planned test step value, otherwise -the test check fails. +A `test check` determines if the actual value presented to the test check has +the expected properties. The actual value should represent the outcome of a +test action. If a test action produces the expected outcome as determined by +the corresponding test check, then this test check passes, otherwise this test +check fails. A failed test check does not stop the test case execution +immediately unless the `T_assert_*()` test variant is used. Each test check +increments the test step counter unless the `T_quiet_*()` test variant is used. +The test step counter is initialized to zero before the test case begins to +execute. The `T_step_*(step, ...)` test check variants verify that the test +step counter is equal to the planned test step value, otherwise the test check +fails. + +Test Check Variant Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `T_quiet_*()` test check variants do not increment the test step counter +and only print a message if the test check fails. This is helpful in case a +test check appears in a tight loop. + +The `T_step_*(step, ...)` test check variants check in addition that the test +step counter is equal to the specified test step value, otherwise the test +check fails. + +The `T_assert_*()` and `T_step_assert_*(step, ...)` test check variants stop +the current test case execution if the test check fails. Test Check Parameter Conventions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -557,21 +607,10 @@ lt If the actual value satisfies the test check condition, then the test check passes, otherwise it fails. -Test Check Variant Conventions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Test Check Type Conventions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The `T_quiet_*()` test check variants do not increment the test step counter -and only print a message if the test check fails. This is helpful in case a -test check appears in a tight loop. - -The `T_step_*(step, ...)` test check variants check in addition that the test -step counter is equal to the specified test step value, otherwise the test -check fails. - -The `T_assert_*()` and `T_step_assert_*(step, ...)` test check variants stop -the current test case execution if the test check fails. - -The following names for test check type variants are used: +The following names for test check types are used: ptr The test value must be a pointer (`void *`). @@ -654,6 +693,57 @@ ssz sz The test value must be of type `size_t`. +Integers +~~~~~~~~ + +Let `xyz` be the type variant which shall be one of `schar`, `uchar`, `short`, +`ushort`, `int`, `uint`, `long`, `ulong`, `ll`, `ull`, `i8`, `u8`, `i16`, +`u16`, `i32`, `u32`, `i64`, `u64`, `iptr`, `uptr`, `ssz`, and `sz`. + +Let `I` be the type name which shall be compatible to the type variant. + +The following test checks for integers are available: + +.. code-block:: c + + void T_eq_xyz(I a, I e); + void T_assert_eq_xyz(I a, I e); + void T_quiet_eq_xyz(I a, I e); + void T_step_eq_xyz(unsigned int step, I a, I e); + void T_step_assert_eq_xyz(unsigned int step, I a, I e); + + void T_ne_xyz(I a, I e); + void T_assert_ne_xyz(I a, I e); + void T_quiet_ne_xyz(I a, I e); + void T_step_ne_xyz(unsigned int step, I a, I e); + void T_step_assert_ne_xyz(unsigned int step, I a, I e); + + void T_ge_xyz(I a, I e); + void T_assert_ge_xyz(I a, I e); + void T_quiet_ge_xyz(I a, I e); + void T_step_ge_xyz(unsigned int step, I a, I e); + void T_step_assert_ge_xyz(unsigned int step, I a, I e); + + void T_gt_xyz(I a, I e); + void T_assert_gt_xyz(I a, I e); + void T_quiet_gt_xyz(I a, I e); + void T_step_gt_xyz(unsigned int step, I a, I e); + void T_step_assert_gt_xyz(unsigned int step, I a, I e); + + void T_le_xyz(I a, I e); + void T_assert_le_xyz(I a, I e); + void T_quiet_le_xyz(I a, I e); + void T_step_le_xyz(unsigned int step, I a, I e); + void T_step_assert_le_xyz(unsigned int step, I a, I e); + + void T_lt_xyz(I a, I e); + void T_assert_lt_xyz(I a, I e); + void T_quiet_lt_xyz(I a, I e); + void T_step_lt_xyz(unsigned int step, I a, I e); + void T_step_assert_lt_xyz(unsigned int step, I a, I e); + +An automatically generated message is printed in case the test check fails. + Boolean Expressions ~~~~~~~~~~~~~~~~~~~ @@ -669,9 +759,9 @@ The following test checks for boolean expressions are available: void T_false(bool a, const char *fmt, ...); void T_assert_false(bool a, const char *fmt, ...); - void T_quiet_true(bool a, const char *fmt, ...); - void T_step_true(unsigned int step, bool a, const char *fmt, ...); - void T_step_assert_true(unsigned int step, bool a, const char *fmt, ...); + void T_quiet_false(bool a, const char *fmt, ...); + void T_step_false(unsigned int step, bool a, const char *fmt, ...); + void T_step_assert_false(unsigned int step, bool a, const char *fmt, ...); The message is only printed in case the test check fails. The format parameter is mandatory. @@ -838,57 +928,6 @@ The following test checks for characters (`char`) are available: An automatically generated message is printed in case the test check fails. -Integers -~~~~~~~~ - -The following test checks for integers are available: - -.. code-block:: c - - void T_eq_xyz(I a, I e); - void T_assert_eq_xyz(I a, I e); - void T_quiet_eq_xyz(I a, I e); - void T_step_eq_xyz(unsigned int step, I a, I e); - void T_step_assert_eq_xyz(unsigned int step, I a, I e); - - void T_ne_xyz(I a, I e); - void T_assert_ne_xyz(I a, I e); - void T_quiet_ne_xyz(I a, I e); - void T_step_ne_xyz(unsigned int step, I a, I e); - void T_step_assert_ne_xyz(unsigned int step, I a, I e); - - void T_ge_xyz(I a, I e); - void T_assert_ge_xyz(I a, I e); - void T_quiet_ge_xyz(I a, I e); - void T_step_ge_xyz(unsigned int step, I a, I e); - void T_step_assert_ge_xyz(unsigned int step, I a, I e); - - void T_gt_xyz(I a, I e); - void T_assert_gt_xyz(I a, I e); - void T_quiet_gt_xyz(I a, I e); - void T_step_gt_xyz(unsigned int step, I a, I e); - void T_step_assert_gt_xyz(unsigned int step, I a, I e); - - void T_le_xyz(I a, I e); - void T_assert_le_xyz(I a, I e); - void T_quiet_le_xyz(I a, I e); - void T_step_le_xyz(unsigned int step, I a, I e); - void T_step_assert_le_xyz(unsigned int step, I a, I e); - - void T_lt_xyz(I a, I e); - void T_assert_lt_xyz(I a, I e); - void T_quiet_lt_xyz(I a, I e); - void T_step_lt_xyz(unsigned int step, I a, I e); - void T_step_assert_lt_xyz(unsigned int step, I a, I e); - -The type variant `xyz` must be `schar`, `uchar`, `short`, `ushort`, `int`, -`uint`, `long`, `ulong`, `ll`, `ull`, `i8`, `u8`, `i16`, `u16`, `i32`, `u32`, -`i64`, `u64`, `iptr`, `uptr`, `ssz`, or `sz`. - -The type name `I` must be compatible to the type variant. - -An automatically generated message is printed in case the test check fails. - RTEMS Status Codes ~~~~~~~~~~~~~~~~~~ @@ -1028,6 +1067,35 @@ RTEMS, floating-point operations are only supported in special tasks and may be forbidden in interrupt context. The formatted output functions provided by the test framework work in every context. +Utility +------- + +You can stop a test case via the ``T_stop()`` function. This function does not +return. You can indicate unreachable code paths with the ``T_unreachable()`` +function. If this function is called, then the test case stops. + +You can busy wait with the ``T_busy()`` function: + +.. code-block:: c + + void T_busy(uint_fast32_t count); + +It performs a busy loop with the specified iteration count. This function is +optimized to not perform memory accesses and should have a small jitter. The +loop iterations have a processor-specific duration. + +You can get an iteration count for the ``T_busy()`` function which corresponds +roughly to one clock tick interval with the ``T_get_one_clock_tick_busy()`` +function: + +.. code-block:: c + + uint_fast32_t T_get_one_clock_tick_busy(void); + +This function requires a clock driver. It must be called from thread context +with interrupts enabled. It may return a different value each time it is +called. + Time Services ------------- @@ -1190,8 +1258,8 @@ T_MEASURE_RUNTIME_ALLOW_CLOCK_ISR T_MEASURE_RUNTIME_REPORT_SAMPLES Report all measurement samples. -T_MEASURE_RUNTIME_DISABLE_VALID_CACHE - Disable the `ValidCache` execution environment variant. +T_MEASURE_RUNTIME_DISABLE_FULL_CACHE + Disable the `FullCache` execution environment variant. T_MEASURE_RUNTIME_DISABLE_HOT_CACHE Disable the `HotCache` execution environment variant. @@ -1209,14 +1277,15 @@ T_MEASURE_RUNTIME_DISABLE_MAX_LOAD The execution environment variants (`M:V`) are: -ValidCache +FullCache Before the `body` request handler is invoked a memory area with twice the size of the outer-most data cache is completely read. This fills the data cache with valid cache lines which are unrelated to the `body` request - handler. + handler. The cache is full with valid data and loading memory used by the + handler needs to evict cache lines. You can disable this variant with the - `T_MEASURE_RUNTIME_DISABLE_VALID_CACHE` request flag. + `T_MEASURE_RUNTIME_DISABLE_FULL_CACHE` request flag. HotCache Before the `body` request handler is invoked the `body` request handler is @@ -1236,14 +1305,14 @@ DirtyCache You can disable this variant with the `T_MEASURE_RUNTIME_DISABLE_DIRTY_CACHE` request flag. -Load +Load/<WorkerCount> This variant tries to get close to worst-case conditions. The cache is set up according to the `DirtyCache` variant. In addition, other processors try to fully load the memory system. The load is produced through writes to a memory area with twice the size of the outer-most data cache. The load variant is performed multiple times with a different set of active - load worker threads (`M:L`). The active workers range from one up to the - processor count. + load worker threads. The <WorkerCount> value is the count of active + workers which ranges from one to the processor count. You can disable these variants with the `T_MEASURE_RUNTIME_DISABLE_MINOR_LOAD` and @@ -1293,7 +1362,7 @@ reported. B:measure_empty P:0:0:UI1:test-rtems-measure.c:18 M:B:Empty - M:V:ValidCache + M:V:FullCache M:N:1024 M:MI:0.000000000 M:Q1:0.000000000 @@ -1326,8 +1395,7 @@ reported. M:D:0.000033244 M:E:Empty:D:1.887834875 M:B:Empty - M:V:Load - M:L:1 + M:V:Load/1 M:N:1024 M:MI:0.000000000 M:Q1:0.000000002 @@ -1340,8 +1408,7 @@ reported. [... 22 more load variants ...] M:E:Empty:D:0.021252583 M:B:Empty - M:V:Load - M:L:24 + M:V:Load/24 M:N:1024 M:MI:0.000000001 M:Q1:0.000000002 @@ -1353,6 +1420,150 @@ reported. M:E:Empty:D:0.015188063 E:measure_empty:N:1:F:0:D:14.284869 +Interrupt Tests +--------------- + +In the operating system implementation you may have two kinds of critical +sections. Firstly, there are low-level critical sections protected by +interrupts disabled and maybe also some SMP spin lock. Secondly, there are +high-level critical sections which are protected by disabled thread +dispatching. The high-level critical sections may contain several low-level +critical sections. Between these low-level critical sections interrupts may +happen which could alter the code path taken in the high-level critical +section. + +The test framework provides support to write test cases for high-level critical +sections though the `T_interrupt_test()` function: + +.. code-block:: c + + typedef enum { + T_INTERRUPT_TEST_INITIAL, + T_INTERRUPT_TEST_ACTION, + T_INTERRUPT_TEST_BLOCKED, + T_INTERRUPT_TEST_CONTINUE, + T_INTERRUPT_TEST_DONE, + T_INTERRUPT_TEST_EARLY, + T_INTERRUPT_TEST_INTERRUPT, + T_INTERRUPT_TEST_LATE, + T_INTERRUPT_TEST_TIMEOUT + } T_interrupt_test_state; + + typedef struct { + void (*prepare)(void *arg); + void (*action)(void *arg); + T_interrupt_test_state (*interrupt)(void *arg); + void (*blocked)(void *arg); + uint32_t max_iteration_count; + } T_interrupt_test_config; + + T_interrupt_test_state T_interrupt_test( + const T_interrupt_test_config *config, + void *arg + ); + +This function returns ``T_INTERRUPT_TEST_DONE`` if the test condition was +satisfied within the maximum iteration count, otherwise it returns +``T_INTERRUPT_TEST_TIMEOUT``. The interrupt test run uses the specified +configuration and passes the specified argument to all configured handlers. +The function shall be called from thread context with interrupts enabled. + +.. image:: ../images/eng/interrupt-test.* + :scale: 60 + :align: center + +The interrupt test uses an *adaptive bisection algorithm* to try to hit the +code section under test by an interrupt. In each test iteration, it waits for +a time point one quarter of the clock tick interval after a clock tick using +the monotonic clock. Then it performs a busy wait using ``T_busy()`` with a +busy count controlled by the adaptive bisection algorithm. The test maintains +a sample set of upper and lower bound busy wait count values. Initially, the +lower bound values are zero and the upper bound values are set to a value +returned by ``T_get_one_clock_tick_busy()``. The busy wait count for an +iteration is set to the middle point between the arithmetic mean of the lower +and upper bound sample values. After the action handler returns, the set of +lower and upper bound sample values is updated based on the test state. If the +test state is ``T_INTERRUPT_TEST_EARLY``, then the oldest upper bound sample +value is replaced by the busy wait count used to delay the action and the +latest lower bound sample value is slightly decreased. Reducing the lower +bound helps to avoid a zero length interval between the upper and lower bounds. +If the test state is ``T_INTERRUPT_TEST_LATE``, then the oldest lower bound +sample value is replaced by the busy wait count used to delay the action and +the latest upper bound sample value is slightly increased. In all other test +states the timing values remain as is. Using the arithmetic mean of a sample +set dampens the effect of each test iteration and is an heuristic to mitigate +the influence of jitters in the action code execution. + +The optional *prepare* handler should prepare the system so that the *action* +handler can be called. It is called in a tight loop, so all the time consuming +setup should be done before ``T_interrupt_test()`` is called. During the +preparation the test state is ``T_INTERRUPT_TEST_INITIAL``. The preparation +handler shall not change the test state. + +The *action* handler should call the function which executes the code section +under test. The execution path up to the code section under test should have a +low jitter. Otherwise, the adaptive bisection algorithm may not find the right +spot. + +The *interrupt* handler should check if the test condition is satisfied or a +new iteration is necessary. This handler is called in interrupt context. It +shall return ``T_INTERRUPT_TEST_DONE`` if the test condition is satisfied and +the test run is done. It shall return ``T_INTERRUPT_TEST_EARLY`` if the +interrupt happened too early to satisfy the test condition. It shall return +``T_INTERRUPT_TEST_LATE`` if the interrupt happened too late to satisfy the +test condition. It shall return ``T_INTERRUPT_TEST_CONTINUE`` if the test +should continue with the current timing settings. Other states shall not be +returned. It is critical to return the early and late states if the test +condition was not satisfied, otherwise the adaptive bisection algorithm may not +work. The returned state is used to try to change the test state from +``T_INTERRUPT_TEST_ACTION`` to the returned state. + +The optional *blocked* handler is invoked if the executing thread blocks during +the action processing. It should remove the blocking condition of the thread +so that the next iteration can start. It can use +``T_interrupt_change_state()`` to change the interrupt test state. + +The *max iteration count* configuration member defines the maximum iteration +count of the test loop. If the maximum iteration count is reached before the +test condition is satisfied, then ``T_interrupt_test()`` returns +``T_INTERRUPT_TEST_TIMEOUT``. + +The *interrupt* and *blocked* handlers may be called in arbitrary test states. + +The *action*, *interrupt*, and *blocked* handlers can use +``T_interrupt_test_get_state()`` to get the current test state: + +.. code-block:: c + + T_interrupt_test_state T_interrupt_test_get_state(void); + +The *action*, *interrupt*, and *blocked* handlers can use +``T_interrupt_test_change_state()`` to try to change the test state from an +expected state to a desired state: + +.. code-block:: c + + T_interrupt_test_state T_interrupt_test_change_state( + T_interrupt_test_state expected_state, + T_interrupt_test_state desired_state + ); + +The function returns the previous state. If it **differs from the expected +state**, then the requested state **change to the desired state did not take +place**. In an SMP configuration, do not call this function in a tight loop. +It could lock up the test run. To busy wait for a state change, use +``T_interrupt_test_get_state()``. + +The *action* handler can use ``T_interrupt_test_busy_wait_for_interrupt()`` to +busy wait for the interrupt: + +.. code-block:: c + + void T_interrupt_test_busy_wait_for_interrupt(void); + +This is useful if the action code does not block to wait for the interrupt. If +the action handler just returns the test code immediately prepares the next +iteration and may miss an interrupt which happens too late. Test Runner ----------- @@ -1696,8 +1907,6 @@ M **M:V:<Variant>** - **M:L:<Load>** - **M:N:<SampleCount>** **M:S:<Count>:<Value>** @@ -1725,12 +1934,9 @@ M (`:`). <Variant> - The execution variant which is one of **ValidCache**, **HotCache**, - **DirtyCache**, or **Load**. - - <Load> - The active load workers count which ranges from one to the processor - count. + The execution variant which is one of **FullCache**, **HotCache**, + **DirtyCache**, or **Load/<WorkerCount>**. The <WorkerCount> is the + count of active workers which ranges from one to the processor count. <SampleCount> The sample count as defined by the runtime measurement configuration. diff --git a/eng/tester.rst b/eng/tester.rst index a538caf..5b57842 100644 --- a/eng/tester.rst +++ b/eng/tester.rst @@ -1,12 +1,17 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018. +.. Copyright (C) 2018, 2022. .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project RTEMS Tester ************ -TBD - Convert the following to Rest and insert into this file -TBD https://devel.rtems.org/wiki/Testing/Tester -TBD - Above file is horribly out of date. Find new docs and refer to them +The RTEMS Tester is a test tool which provides a command line interface and +automates execution of test executables. It is part of the `rtems-tools` +repository and built as part of the RTEMS Tools for all targets by the +RTEMS Source Builder. The RTEMS Tester can be configured to test based +on local lab setup or to test on custom boards. + +The RTEMS Tester is documented the `RTEMS Tester and Run` section of the +`RTEMS User Manual`. diff --git a/eng/vc-authors.rst b/eng/vc-authors.rst index dcbbeb9..179ad08 100644 --- a/eng/vc-authors.rst +++ b/eng/vc-authors.rst @@ -166,6 +166,52 @@ flag to prevent merge from issuing an automatic merge commit message. When you have committed changes on a branch that is public/shared with another developer you should not rebase that branch. +Migrate a Personal Repository to top-level +------------------------------------------ + +Once a project is production ready in the personal repository, it's time to +migrate it to the top-level RTEMS git directory. First, the project directory +needs to be copied and then the permissions need to be set, so that everyone can +push into that repository. + +.. code-block:: shell + + cp -R /data/git/user/my-rtems-project.git /data/git + cd /data/git/my-rtems-project.git + chgrp -R gitrw ./ + chmod -R g+rws ./ + +Then copy the post-receive script from the rtems.git directory and change the +name of REPO. + +.. code-block:: shell + + cp /data/git/rtems.git/hooks/post-receive /data/git/my-rtems-project.git/hooks/ + +After making the change the post-receive script in the new repository should +look like this + +.. code-block:: shell + + #!/bin/sh + # + # The "post-receive" script is run after receive-pack has accepted a pack + # and the repository has been updated. It is passed arguments in through + # stdin in the form + # <oldrev> <newrev> <refname> + # For example: + # aa453216d1b3e49e7f6f98441fa56946ddcd6a20 68f7abf4e6f922807889f52bc043ecd31b79f814 refs/heads/master + # + + REPO=my-rtems-project + + . /data/support/git-support/hooks/post-receive-0 + . /data/support/git-support/hooks/post-receive-1 + #. /data/support/git-support/hooks/post-receive-2 + . /data/support/git-support/hooks/post-receive-3 + . /data/support/git-support/hooks/post-receive-4 + . /data/support/git-support/hooks/post-receive-5 + GIT Push Configuration ---------------------- diff --git a/eng/vc-users.rst b/eng/vc-users.rst index 31de516..37fee64 100644 --- a/eng/vc-users.rst +++ b/eng/vc-users.rst @@ -422,20 +422,91 @@ 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. -Accessing a developer's repository +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. +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: + +.. code-block:: shell + + 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. + Creating a Patch ----------------- +----------------- -Before submitting a patch read about `Contributing -<https://devel.rtems.org/wiki/Developer/Contributing>`_ to RTEMS and the -`Commit Message <https://devel.rtems.org/wiki/Developer/Git#GitCommits>`_ -formatting we require. +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 @@ -458,6 +529,20 @@ specify a version number for your patch, for example, use to indicate the second version of a patch, ``-v3`` for a third, and so forth. +Also, in order to create a patch specifying the repo name in the patch message, +you should use the``--subject-prefix`` flag. For example, if contributing to +the rtems-docs repo, use + +.. code-block:: shell + + git format-patch --subject-prefix="PATCH rtems-docs" ... + +You can set a default subject prefix for each repository locally, for example: + +.. code-block:: shell + + git config format.subjectprefix "PATCH rtems-docs" + 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 |