From 23ab40d3e6899c5956c26770f07f3a5eb910be8b Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 28 May 2020 09:21:38 +0200 Subject: eng: Add generated documentation of spec items The documentation of the specification items is generated by an RTEMS qualification tool from a specification of specification items. Move non-generated content to "req-for-req.rst". Update #3715. --- eng/glossary.rst | 6 - eng/req/index.rst | 1 - eng/req/items.rst | 4536 ++++++++++++++++++++++++++++++++++++++++++---- eng/req/req-for-req.rst | 47 +- eng/req/traceability.rst | 35 +- eng/req/validation.rst | 46 - 6 files changed, 4256 insertions(+), 415 deletions(-) delete mode 100644 eng/req/validation.rst diff --git a/eng/glossary.rst b/eng/glossary.rst index d0fc1eb..f0c0fce 100644 --- a/eng/glossary.rst +++ b/eng/glossary.rst @@ -9,9 +9,6 @@ Glossary .. glossary:: :sorted: - ABI - An acronym for Application Binary Interface. - API An acronym for Application Programming Interface. @@ -103,9 +100,6 @@ Glossary linker) such as jump tables, linker trampolines, exception frame information, etc. - software item - This term has the same meaning as :term:`software product`. - software product The *software product* is the :term:`RTEMS` real-time operating system. diff --git a/eng/req/index.rst b/eng/req/index.rst index b793130..fbda0b8 100644 --- a/eng/req/index.rst +++ b/eng/req/index.rst @@ -86,7 +86,6 @@ All procedures should be based on a peer review principles. req-for-req items - validation traceability management tooling diff --git a/eng/req/items.rst b/eng/req/items.rst index 0c13bb2..05104a6 100644 --- a/eng/req/items.rst +++ b/eng/req/items.rst @@ -2,519 +2,4367 @@ .. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) -.. _ReqEngSpecItems: +.. _ReqEngSpecificationItems: Specification Items =================== -The technical specification of RTEMS will contain requirements, specializations -of requirements, :ref:`test procedures `, -:ref:`test suites `, :ref:`test cases `, and -:ref:`requirement validations `. These things will be called -*specification items* or just *items* if it is clear from the context. +.. _ReqEngSpecificationItemHierarchy: -The specification items are stored in files in :term:`YAML` format with a -defined set of key-value pairs called attributes. The key name shall match -with the pattern defined by the regular expression -``[a-zA-Z0-9][a-zA-Z0-9-]+``. In particular, key names which begin with an -underscore (``_``) are reserved for internal use in tools. +Specification Item Hierarchy +---------------------------- -Each specification item shall have the following attributes: +The specification item types have the following hierarchy: -enabled-by - The value shall be a list of expressions. 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*: +* :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:`SpecTypeInterfaceContainerItemType` + + * :ref:`SpecTypeInterfaceDefineItemType` + + * :ref:`SpecTypeInterfaceDomainItemType` + + * :ref:`SpecTypeInterfaceEnumItemType` + + * :ref:`SpecTypeInterfaceEnumeratorItemType` + + * :ref:`SpecTypeInterfaceForwardDeclarationItemType` + + * :ref:`SpecTypeInterfaceFunctionItemType` + + * :ref:`SpecTypeInterfaceGroupItemType` - * 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. + * :ref:`SpecTypeInterfaceHeaderFileItemType` - * 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. + * :ref:`SpecTypeInterfaceMacroItemType` - * The value of the *not* operator shall be an expression. It negates - the outcome of its expression. + * :ref:`SpecTypeInterfaceTypedefItemType` - 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: + * :ref:`SpecTypeInterfaceUnspecifiedItemType` - .. code-block:: none + * :ref:`SpecTypeInterfaceVariableItemType` - enabled-by: - - RTEMS_SMP + * :ref:`SpecTypeRequirementItemType` - .. code-block:: none + * :ref:`SpecTypeFunctionalRequirementItemType` - enabled-by: - - and: - - RTEMS_NETWORKING - - not: RTEMS_SMP + * :ref:`SpecTypeNonXFunctionalRequirementItemType` - .. code-block:: none + * :ref:`SpecTypeRequirementValidationItemType` - enabled-by: - - and: - - not: TEST_DEBUGGER01_EXCLUDE - - or: - - arm - - i386 + * :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 explicitly defined attributes +shall be specified. The following attributes are explicitly defined for this +type: + +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:`SpecTypeEnabledXByExpression`. It + shall define the conditions under which the item is enabled. links - The value shall be a list of key-value pairs defining links to other - specification items. The list is ordered and defines the order in - which links are processed. There shall be a key *role* with an - unspecified value. There shall be a key *uid* with a relative UID to - the item referenced by this link. Other keys are type-specific. - Example: - - .. code-block:: yaml - - links: - - role: build-dependency - uid: optpwrdwnhlt - - role: build-dependency - uid: ../../bspopts - - role: build-dependency - uid: ../start + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. type - The value shall be the specification :ref:`item 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. -The following attributes are used in specification items of various types: +This type is refined by the following types: -.. _ReqEngItemAttrLicense: +* :ref:`SpecTypeBuildItemType` -SPDX-License-Identifier - The value should be ``BSD-2-Clause OR CC-BY-SA-4.0``. If content is - imported from external sources, then the corresponding license shall be - used. Acceptable licenses are BSD-2-Clause and CC-BY-SA-4.0. The - copyright holder of the external work should be asked to allow a - dual-licensing BSD-2-Clause or CC-BY-SA-4.0. This allows generation of - BSD-2-Clause licensed source code and CC-BY-SA-4.0 licensed documentation. +* :ref:`SpecTypeConstraintItemType` -.. _ReqEngItemAttrCopyrights: +* :ref:`SpecTypeGlossaryItemType` -copyrights - The value shall be a list of copyright statements of the following formats: +* :ref:`SpecTypeInterfaceItemType` + +* :ref:`SpecTypeRequirementItemType` - * ``Copyright (C) `` +* :ref:`SpecTypeRequirementValidationItemType` - * ``Copyright (C) , `` +* :ref:`SpecTypeSpecificationItemType` - See also :ref:`FileHeaderCopyright`. +* :ref:`SpecTypeTestCaseItemType` -.. _ReqEngItemTypes: +* :ref:`SpecTypeTestPlatformItemType` -Item Types ----------- +* :ref:`SpecTypeTestProcedureItemType` -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: +* :ref:`SpecTypeTestSuiteItemType` -* requirement +.. _SpecTypeBuildItemType: - * functional - Functional requirements shall describe the behaviour of the - software product under specific conditions. +Build Item Type +^^^^^^^^^^^^^^^ - * *capability* +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``build``. This set of attributes specifies a build item. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: - * *dependability-function* +build-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the build + item type. - * *function* +This type is refined by the following types: - * *operational* - Operational requirements shall +* :ref:`SpecTypeBuildAdaTestProgramItemType` - * define the operation modes (e.g. initialization, multitasking, termination), +* :ref:`SpecTypeBuildBSPItemType` - * describe the operation modes, and +* :ref:`SpecTypeBuildConfigurationFileItemType` - * describe the operation mode transitions. +* :ref:`SpecTypeBuildConfigurationHeaderItemType` - * *safety-function* +* :ref:`SpecTypeBuildGroupItemType` - * non-functional +* :ref:`SpecTypeBuildLibraryItemType` - * *build-configuration* +* :ref:`SpecTypeBuildObjectsItemType` - * *constraint* +* :ref:`SpecTypeBuildOptionItemType` - * *design* +* :ref:`SpecTypeBuildScriptItemType` - * *interface* +* :ref:`SpecTypeBuildStartFileItemType` - * *interface-requirement* +* :ref:`SpecTypeBuildTestProgramItemType` - * *maintainability* +.. _SpecTypeBuildAdaTestProgramItemType: - * *performance* +Build Ada Test Program Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * *portability* +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``ada-test-program``. This set of attributes +specifies an Ada test program executable to build. Test programs may use +additional objects provided by :ref:`SpecTypeBuildObjectsItemType` items. Test +programs have an implicit ``enabled-by`` attribute value which is controlled by +the option action :ref:`set-test-state `. If the +test state is set to ``exclude``, then the test program is not built. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: - * *quality* +ada-main + The attribute value shall be a string. It shall be the path to the Ada main + body file. - * *reliability* +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``). - * *resource* +adaflags + The attribute value shall be a list of strings. It shall be a list of + options for the Ada compiler. - * *safety* +adaincludes + The attribute value shall be a list of strings. It shall be a list of Ada + include paths. -* *test-procedure* +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. -* *test-suite* +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. -* *test-case* +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. -* *validation-by-analysis* +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. -* *validation-by-inspection* +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. -* *validation-by-review-of-design* +stlib + The attribute value shall be a list of strings. It shall be a list of + external static library identifiers used to link this test program, e.g. + ``m`` for ``libm.a``. -* *validation-platform* +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. -.. image:: ../../images/eng/req-spec-items.* - :scale: 70 - :align: center +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 (http://www.embedded-brains.de) + cppflags: [] + enabled-by: true + includes: [] + ldflags: [] + links: [] + source: + - testsuites/ada/samples/hello/init.c + stlib: [] + target: testsuites/ada/ada_hello.exe + type: build + use-after: [] + use-before: [] + +.. _SpecTypeBuildBSPItemType: + +Build BSP Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``bsp``. This set of attributes specifies a base BSP +variant to build. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: + +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 (http://www.embedded-brains.de) + cppflags: [] + enabled-by: true + family: mybsp + includes: [] + install: + - destination: ${BSP_INCLUDEDIR} + source: + - bsps/myarch/mybsp/include/bsp.h + - bsps/myarch/mybsp/include/tm27.h + - destination: ${BSP_INCLUDEDIR}/bsp + source: + - bsps/myarch/mybsp/include/bsp/irq.h + - destination: ${BSP_LIBDIR} + source: + - bsps/myarch/mybsp/start/linkcmds + links: + - role: build-dependency + uid: ../../obj + - role: build-dependency + uid: ../../opto2 + - role: build-dependency + uid: abi + - role: build-dependency + uid: obj + - role: build-dependency + uid: ../start + - role: build-dependency + uid: ../../bspopts + source: + - bsps/myarch/mybsp/start/bspstart.c + type: build + +.. _SpecTypeBuildConfigurationFileItemType: + +Build Configuration File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``config-file``. This set of attributes specifies a +configuration file placed in the build tree. The configuration file is +generated during the configure command execution and are placed in the build +tree. All explicitly defined attributes shall be specified. The following +attributes are explicitly defined for this type: + +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 (http://www.embedded-brains.de) + 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` though the ``build-type`` +attribute if the value is ``config-header``. This set of attributes specifies +configuration header file. The configuration header file is generated during +configure command execution and is placed in the build tree. All collected +configuration defines are written to the configuration header file during the +configure command execution. To have all configuration defines from sibling +items available it is recommended to link them in the proper order. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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` though the ``build-type`` +attribute if the value is ``group``. This set of attributes provides a means to +aggregate other build items and modify the build item context which is used by +referenced build items. The ``includes``, ``ldflags``, ``objects``, and +``use`` variables of the build item context are updated by the corresponding +attributes of the build group. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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 + copyrights: + - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + enabled-by: + - BUILD_TESTS + - BUILD_SAMPLES + includes: + - testsuites/support/include + install: [] + ldflags: + - -Wl,--wrap=printf + - -Wl,--wrap=puts + links: + - role: build-dependency + uid: ticker + type: build + use-after: [] + use-before: + - rtemstest + +.. _SpecTypeBuildLibraryItemType: + +Build Library Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``library``. This set of attributes specifies a +static library. Library items may use additional objects provided by +:ref:`SpecTypeBuildObjectsItemType` items through the build dependency links of +the item. All explicitly defined attributes shall be specified. The following +attributes are explicitly defined for this type: + +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 (http://www.embedded-brains.de) + cppflags: [] + cxxflags: [] + enabled-by: true + includes: + - cpukit/libfs/src/jffs2/include + install: + - destination: ${BSP_INCLUDEDIR}/rtems + source: + - cpukit/include/rtems/jffs2.h + install-path: ${BSP_LIBDIR} + links: [] + source: + - cpukit/libfs/src/jffs2/src/build.c + target: jffs2 + type: build + +.. _SpecTypeBuildObjectsItemType: + +Build Objects Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``objects``. This set of attributes specifies a set +of object files used to build static libraries or test programs. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +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 (http://www.embedded-brains.de) + cppflags: [] + cxxflags: [] + enabled-by: true + includes: [] + install: + - destination: ${BSP_INCLUDEDIR}/bsp + source: + - bsps/include/bsp/bootcard.h + - bsps/include/bsp/default-initial-extension.h + - bsps/include/bsp/fatal.h + links: [] + source: + - bsps/shared/start/bootcard.c + - bsps/shared/rtems-version.c + type: build + +.. _SpecTypeBuildOptionItemType: + +Build Option Item Type +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``option``. This set of attributes specifies a build +option. The following explicitly defined attributes are required: + +* ``actions`` + +* ``default`` + +* ``default-by-variant`` + +* ``description`` + +The following attributes are explicitly defined for this type: + +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 :ref:`SpecTypeBuildOptionValue`. It shall be + the default value of the option if no variant-specific default value is + specified. Use ``null`` to specify that no default value exits. The + variant-specific default values may be specified by the + ``default-by-variant`` attribute. + +default-by-variant + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildOptionDefaultByVariant`. The list is processed from top + to bottom. If a matching variant is found, then the processing stops. + +description + The attribute value shall be an optional string. It shall be the + description of the option. + +format + The attribute value shall be an optional string. It shall be a `Python + format string + `_, for + example ``'{}'`` or ``'{:#010x}'``. + +name + The attribute value shall be a :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 embedded brains GmbH (http://www.embedded-brains.de) + default: 115200 + default-by-variant: + - value: 9600 + variants: + - m68k/m5484FireEngine + - powerpc/hsc_cm01 + - value: 19200 + variants: + - m68k/COBRA5475 + description: | + Default baud for console and other serial devices. + enabled-by: true + format: '{}' + links: [] + name: BSP_CONSOLE_BAUD + type: build + +.. _SpecTypeBuildScriptItemType: + +Build Script Item Type +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``script``. This set of attributes specifies a build +script. The optional attributes may be required by commands executed through +the scripts. The following explicitly defined attributes are required: + +* ``do-build`` + +* ``do-configure`` + +* ``prepare-build`` + +* ``prepare-configure`` + +The following attributes are explicitly defined for this type: + +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 of strings. It shall be a list of + external static library identifiers used to link this test program, e.g. + ``m`` for ``libm.a``. + +use-after + The attribute value shall be a list. Each list element shall be a + :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 (http://www.embedded-brains.de) + default: null + default-by-variant: [] + do-build: | + bld.install_as( + "${BSP_LIBDIR}/linkcmds", + "bsps/" + bld.env.ARCH + "/" + bld.env.BSP_FAMILY + + "/start/linkcmds." + bld.env.BSP_BASE + ) + do-configure: | + conf.env.append_value( + "LINKFLAGS", + ["-qnolinkcmds", "-T", "linkcmds." + conf.env.BSP_BASE] + ) + enabled-by: true + links: [] + prepare-build: null + prepare-configure: null + type: build + +.. _SpecTypeBuildStartFileItemType: + +Build Start File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``start-file``. This set of attributes specifies a +start file to build. A start file is used to link an executable. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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 (http://www.embedded-brains.de) + cppflags: [] + enabled-by: true + includes: [] + install-path: ${BSP_LIBDIR} + links: [] + source: + - bsps/sparc/shared/start/start.S + target: start.o + type: build + +.. _SpecTypeBuildTestProgramItemType: + +Build Test Program Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` though the ``build-type`` +attribute if the value is ``test-program``. This set of attributes specifies a +test program executable to build. Test programs may use additional objects +provided by :ref:`SpecTypeBuildObjectsItemType` items. Test programs have an +implicit ``enabled-by`` attribute value which is controlled by the option +action :ref:`set-test-state `. If the test state +is set to ``exclude``, then the test program is not built. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +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 of strings. It shall be a list of + external static library identifiers used to link this test program, e.g. + ``m`` for ``libm.a``. + +target + The attribute value shall be a :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 (http://www.embedded-brains.de) + cppflags: [] + cxxflags: [] + enabled-by: true + features: c cprogram + includes: [] + ldflags: [] + links: [] + source: + - testsuites/samples/ticker/init.c + - testsuites/samples/ticker/tasks.c + stlib: [] + target: testsuites/samples/ticker.exe + type: build + use-after: [] + use-before: [] + +.. _SpecTypeConstraintItemType: + +Constraint Item Type +^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``constraint``. This set of attributes specifies a constraint. +All explicitly defined attributes shall be specified. The following attributes +are explicitly defined for this type: + +rationale + The attribute value shall be an optional string. If the value is present, + then it shall state the rationale or justification of the constraint. + +scope + The attribute value shall be a string. It shall be the scope of the + constraint. -Requirements ------------- +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the constraint. -All requirement specification items shall have the following attribute: +.. _SpecTypeGlossaryItemType: -rationale: - The rationale or justification of the specification item. +Glossary Item Type +^^^^^^^^^^^^^^^^^^ -Build Configuration -------------------- +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``glossary``. This set of attributes specifies a glossary item. +All explicitly defined attributes shall be specified. The following attributes +are explicitly defined for this type: -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. +glossary-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + glossary item type. -.. _ReqEngInterfaceReq: +This type is refined by the following types: -Interface Requirement ---------------------- +* :ref:`SpecTypeGlossaryGroupItemType` -Interface requirements shall describe the high level aspects of interfaces. -The item type shall be *interface-requirement*. +* :ref:`SpecTypeGlossaryTermItemType` -.. _ReqEngInterface: +.. _SpecTypeGlossaryGroupItemType: -Interface ---------- +Glossary Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ -.. warning:: +This type refines the :ref:`SpecTypeGlossaryItemType` though the +``glossary-type`` attribute if the value is ``group``. This set of attributes +specifies a glossary group. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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. - This is work in progress. +.. _SpecTypeGlossaryTermItemType: -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: +Glossary Term Item Type +^^^^^^^^^^^^^^^^^^^^^^^ -* *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. +This type refines the :ref:`SpecTypeGlossaryItemType` though the +``glossary-type`` attribute if the value is ``term``. This set of attributes +specifies a glossary term. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: -* *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. +term + The attribute value shall be a string. It shall be the glossary term. -* *architecture*: Architecture interface items shall define the - interface between the software product and the processor architecture - (:term:`ABI`). +text + The attribute value shall be a string. It shall be the definition of the + glossary term. -* *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. +.. _SpecTypeInterfaceItemType: -* *hardware*: Hardware interface items shall define the interface between the - software product and the hardware. +Interface Item Type +^^^^^^^^^^^^^^^^^^^ -* *newlib*: Newlib interface items shall define the interface between the - software product and the Newlib (libc.a). +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``interface``. This set of attributes specifies an interface +specification item. Interface items shall specify the interface of the software +product to other software products and the hardware. Use +:ref:`SpecTypeInterfaceDomainItemType` items to specify interface domains, for +example the :term:`API`, C language, compiler, interfaces to the +implementation, and the hardware. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: -The interface items shall have an *interface-type* which is one of the -following and nothing else: +interface-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + interface item type. -* *configuration-option* +This type is refined by the following types: -* *define* +* :ref:`SpecTypeApplicationConfigurationGroupItemType` -* *enum* +* :ref:`SpecTypeApplicationConfigurationOptionItemType` -* *function* +* :ref:`SpecTypeInterfaceCompoundItemType` -* *header* +* :ref:`SpecTypeInterfaceContainerItemType` -* *macro* +* :ref:`SpecTypeInterfaceDefineItemType` -* *register-block* +* :ref:`SpecTypeInterfaceDomainItemType` -* *structure* +* :ref:`SpecTypeInterfaceEnumItemType` -* *typedef* +* :ref:`SpecTypeInterfaceEnumeratorItemType` -* *union* +* :ref:`SpecTypeInterfaceForwardDeclarationItemType` -* *variable* +* :ref:`SpecTypeInterfaceFunctionItemType` -.. _ReqEngInterfaceApplicationConfigGroups: +* :ref:`SpecTypeInterfaceGroupItemType` -Interface - Application Configuration Groups --------------------------------------------- +* :ref:`SpecTypeInterfaceHeaderFileItemType` -The application configuration group items shall have the following attribute -specializations: +* :ref:`SpecTypeInterfaceMacroItemType` -SPDX-License-Identifier - See :ref:`SPDX-License-Identifier `. +* :ref:`SpecTypeInterfaceTypedefItemType` -appl-config-group-description: - The value shall be the description of this application configuration group. +* :ref:`SpecTypeInterfaceUnspecifiedItemType` -appl-config-group-name: - The value shall be the name of this application configuration group. +* :ref:`SpecTypeInterfaceVariableItemType` -copyrights - See :ref:`copyrights `. +.. _SpecTypeApplicationConfigurationGroupItemType: -interface-type - The interface type value shall be *appl-config-group*. +Application Configuration Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``appl-config-group``. This set of +attributes specifies an application configuration group. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: -link - There shall be a link to a higher level requirement. +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 application configuration group requirement. + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement for the application configuration group. -type - The type value shall be *interface*. +.. _SpecTypeApplicationConfigurationOptionItemType: -.. _ReqEngInterfaceApplicationConfigOptions: +Application Configuration Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Interface - Application Configuration Options ---------------------------------------------- +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``appl-config-option``. This set +of attributes specifies an application configuration option. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: -The application configuration option items shall have the following attribute -specializations: +appl-config-option-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + application configuration option type. -SPDX-License-Identifier - See :ref:`SPDX-License-Identifier `. +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. The + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items have an + attribute for constraints. -appl-config-option-constraint - This attribute shall be present only for *initializer* and *integer* - type options. The value shall be a dictionary of the following optional - key-value pairs. +index-entries + The attribute value shall be a list of strings. It shall be a list of + additional application configuration option document index entries. The + application configuration option name is automatically added to the + document index. - custom - The value shall be a list of constraints in natural language. Use the - following wording: +name + The attribute value shall be an + :ref:`SpecTypeApplicationConfigurationOptionName`. - The value of this configuration option shall be ... +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. - min - The value shall be the minimum value of the option. +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement for the application configuration option. - max - The value shall be the maximum value of the option. +This type is refined by the following types: - links - The value shall be a list of relative UIDs to constraints. +* :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` - set - The value shall be the list of valid values of the option. +* :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` -appl-config-option-default - This attribute shall be present only for *feature* type options. The value - shall be a description of the default configuration in case this boolean - feature define is undefined. Use the following wording: +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` - If this configuration option is undefined, then ... +.. _SpecTypeApplicationConfigurationFeatureEnableOptionItemType: -appl-config-option-default-value - This attribute shall be present only for *initializer* and *integer* - type options. The value shall be an initializer, an integer, or a - descriptive text. +Application Configuration Feature Enable Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -appl-config-option-description - For *feature* and *feature-enable* type options, the value shall be a - description of the configuration in case this boolean feature define is - defined. Use the following wording: +This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType` +though the ``appl-config-option-type`` attribute if the value is +``feature-enable``. This set of attributes specifies an application +configuration feature enable option. - In case this configuration option is defined, then ... +.. _SpecTypeApplicationConfigurationFeatureOptionItemType: - For *initializer* and *integer* options, the value shall describe the - effect of the option value. 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. - Add these things to *appl-config-option-constraint* and - *appl-config-option-notes*. Use the following wording: +Application Configuration Feature Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The value of this configuration option defines ... +This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType` +though the ``appl-config-option-type`` attribute if the value is ``feature``. +This set of attributes specifies an application configuration feature option. +All explicitly defined attributes shall be specified. The following attributes +are explicitly defined for this type: -appl-config-option-index - The value shall be a list of entries for the document index. By default, - the application configuration option name is added to the index. +default + The attribute value shall be a string. It shall describe what happens if + the configuration option is undefined. -appl-config-option-name - The value shall be the name of the application configuration option. Use a - pattern of ``CONFIGURE_[A-Z0-9_]+`` for the name. +.. _SpecTypeApplicationConfigurationValueOptionItemType: -appl-config-option-notes - The value shall be the notes for this option. The notes should explain - everything which was omitted from the description. It should cover all the - details, special cases, usage notes, error conditions, configuration - dependencies, and references. +Application Configuration Value Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -appl-config-option-type - The value shall be one of the following and nothing else: +This type refines the following types: - feature - Use this type for boolean feature opions which have a behaviour in the - default configuration which is not just that the feature is disabled. +* :ref:`SpecTypeApplicationConfigurationOptionItemType` though the + ``appl-config-option-type`` attribute if the value is ``initializer`` - feature-enable - Use this type for boolean feature opions which just enables a feature. +* :ref:`SpecTypeApplicationConfigurationOptionItemType` though the + ``appl-config-option-type`` attribute if the value is ``integer`` - initializer - Use this type for options which initialize a data structure. +This set of attributes specifies application configuration initializer or +integer option. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: - integer - Use this type for integer options. +constraints + The attribute value shall be an + :ref:`SpecTypeApplicationConfigurationOptionConstraintSet`. -copyrights - See :ref:`copyrights `. +default-value + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall + shall describe the default value of the application configuration option. -interface-type - The interface type value shall be *appl-config-option*. +.. _SpecTypeInterfaceCompoundItemType: + +Interface Compound Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` though the ``interface-type`` attribute if + the value is ``struct`` + +* :ref:`SpecTypeInterfaceItemType` though the ``interface-type`` attribute if + the value is ``union`` + +This set of attributes specifies a compound (struct or union). All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +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`. + +.. _SpecTypeInterfaceContainerItemType: + +Interface Container Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``container``. Items of this type +specify an interface container. The item shall have exactly one link with the +:ref:`SpecTypeInterfacePlacementLinkRole` to an +:ref:`SpecTypeInterfaceDomainItemType` item. This link defines the interface +domain of the container. + +.. _SpecTypeInterfaceDefineItemType: + +Interface Define Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``define``. This set of attributes +specifies a define. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: + +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` though the +``interface-type`` attribute if the value is ``domain``. This set of attributes +specifies an interface domain. Items of the types +:ref:`SpecTypeInterfaceContainerItemType` and +:ref:`SpecTypeInterfaceHeaderFileItemType` are placed into domains through +links with the :ref:`SpecTypeInterfacePlacementLinkRole`. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +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` though the +``interface-type`` attribute if the value is ``enum``. This set of attributes +specifies an enum. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: + +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` though the +``interface-type`` attribute if the value is ``enumerator``. This set of +attributes specifies an enumerator. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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` though the +``interface-type`` attribute if the value is ``forward-declaration``. Items of +this type specify a forward declaration. The item shall have exactly one link +with the :ref:`SpecTypeInterfaceTargetLinkRole` to an +:ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the type +declared by the forward declaration. + +.. _SpecTypeInterfaceFunctionItemType: + +Interface Function Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``function``. This set of +attributes specifies a function. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionDefinitionDirective`. + +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. + +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`. -link - There shall be a link to the application configuration group to which this - option belongs. +.. _SpecTypeInterfaceGroupItemType: + +Interface Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``group``. This set of attributes +specifies an interface group. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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. + +.. _SpecTypeInterfaceHeaderFileItemType: + +Interface Header File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``header-file``. This set of +attributes specifies a header file. The item shall have exactly one link with +the :ref:`SpecTypeInterfacePlacementLinkRole` to an +:ref:`SpecTypeInterfaceDomainItemType` item. This link defines the interface +domain of the header file. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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`. + +.. _SpecTypeInterfaceMacroItemType: + +Interface Macro Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``macro``. This set of attributes +specifies a macro. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: + +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 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`. + +.. _SpecTypeInterfaceTypedefItemType: + +Interface Typedef Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``typedef``. This set of +attributes specifies a typedef. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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`. + +.. _SpecTypeInterfaceUnspecifiedItemType: + +Interface Unspecified Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``unspecified``. This set of +attributes specifies an unspecified interface. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +name + The attribute value shall be a string. It shall be the name of the + unspecified interface. + +.. _SpecTypeInterfaceVariableItemType: + +Interface Variable Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` though the +``interface-type`` attribute if the value is ``variable``. This set of +attributes specifies a variable. All explicitly defined attributes shall be +specified. The following attributes are explicitly defined for this type: + +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`. + +.. _SpecTypeRequirementItemType: + +Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``requirement``. This set of attributes specifies a +requirement. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: + +rationale + The attribute value shall be an optional string. If the value is present, + then it shall state the rationale or justification of the requirement. + +references + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRequirementReference`. + +requirement-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + requirement item type. text - The application configuration option requirement. + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement. -type - The type value shall be *interface*. +This type is refined by the following types: -.. _ReqEngTestProcedure: +* :ref:`SpecTypeFunctionalRequirementItemType` -Test Procedure --------------- +* :ref:`SpecTypeNonXFunctionalRequirementItemType` -Test procedures shall be executed by the Qualification Toolchain. +Please have a look at the following example: -The test procedure items shall have the following attribute -specializations: +.. code-block:: yaml -type - The type value shall be *test-procedure*. + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de + enabled-by: true + functional-type: capability + links: [] + rationale: | + It keeps you busy. + requirement-type: functional + text: | + The system shall do crazy things. + type: requirement + +.. _SpecTypeFunctionalRequirementItemType: + +Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRequirementItemType` though the +``requirement-type`` attribute if the value is ``functional``. This set of +attributes specifies a functional requirement. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +functional-type + The attribute value shall be a :ref:`SpecTypeRequirementFunctionalType`. It + shall be the functional type of the requirement. + +.. _SpecTypeNonXFunctionalRequirementItemType: + +Non-Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRequirementItemType` though the +``requirement-type`` attribute if the value is ``non-functional``. This set of +attributes specifies a non-functional requirement. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +non-functional-type + The attribute value shall be a + :ref:`SpecTypeRequirementNonXFunctionalType`. It shall be the + non-functional type of the requirement. + +.. _SpecTypeRequirementValidationItemType: + +Requirement Validation Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``validation``. This set of attributes provides a requirement +validation evidence. The item shall have exactly one link to the validated +requirement with the :ref:`SpecTypeRequirementValidationLinkRole`. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +method + The attribute value shall be a :ref:`SpecTypeRequirementValidationMethod`. + Validation by test is done through :ref:`SpecTypeTestCaseItemType` items. text - The purpose of this test procedure. + 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. + +.. _SpecTypeSpecificationItemType: + +Specification Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``spec``. This set of attributes specifies specification types. +All explicitly defined attributes shall be specified. The following attributes +are explicitly defined for this type: + +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 this value is present, + then tt 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 (http://www.embedded-brains.de) + enabled-by: true + links: + - role: spec-member + uid: root + - role: spec-refinement + spec-key: type + spec-value: example + uid: root + spec-description: null + spec-example: null + spec-info: + dict: + attributes: + an-example-attribute: + description: | + It shall be an example. + spec-type: optional-str + example-number: + description: | + It shall be the example number. + spec-type: int + description: | + This set of attributes specifies an example. + required-attributes: all + spec-name: Example Item Type + spec-type: spec + type: spec + +.. _SpecTypeTestCaseItemType: + +Test Case Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``test-case``. This set of attributes specifies a test case. +All explicitly defined attributes shall be specified. The following attributes +are explicitly defined for this type: + +actions + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestCaseAction`. + +brief + The attribute value shall be a string. It shall be the test case brief + description. + +description + The attribute value shall be an optional string. It shall be the test case + description. + +epilogue + The attribute value shall be an optional string. If the attribute value is + present, then it shall be the test case epilogue code. The epilogue code + is placed in the test case body after the test case actions. + +fixture + The attribute value shall be an optional string. If the attribute value is + present, then it shall be a pointer to the test case fixture. The test + case fixture pointer declaration may be provided by the test case support + code or via an included header file. + +includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. + +local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. + +name + The attribute value shall be a :ref:`SpecTypeTestName`. + +prologue + The attribute value shall be an optional string. If the attribute value is + present, then it shall be the test case prologue code. The prologue code + is placed in the test case body before the test case actions. A use case + is the declaration of local variables used by the test case actions. + +support + The attribute value shall be an optional string. If the attribute value is + present, then it shall be the test case support code. The support code is + placed at file scope before the test case code. + +target + The attribute value shall be a string. It shall be the path to the + generated target test case source file. + +.. _SpecTypeTestPlatformItemType: + +Test Platform Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``test-platform``. Please note: + +.. warning:: + + This item type is work in progress. -platform - There shall be links to validation platform requirements. +This set of attributes specifies a test platform. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +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` though the ``type`` attribute +if the value is ``test-procedure``. Please note: + +.. warning:: + + This item type is work in progress. + +This set of attributes specifies a test procedure. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +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 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. + The attribute value shall be a string. It shall describe the steps of the + test procedure execution. -.. _ReqEngTestSuite: +.. _SpecTypeTestSuiteItemType: -Test Suite ----------- +Test Suite Item Type +^^^^^^^^^^^^^^^^^^^^ -Test suites shall use the :ref:`RTEMS Test Framework `. +This type refines the :ref:`SpecTypeRootItemType` though the ``type`` attribute +if the value is ``test-suite``. This set of attributes specifies a test suite. +All explicitly defined attributes shall be specified. The following attributes +are explicitly defined for this type: -The test suite items shall have the following attribute specializations: +brief + The attribute value shall be a string. It shall be the test suite brief + description. -type - The type value shall be *test-suite*. +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. -text - The test suite description. +description + The attribute value shall be an optional string. It shall be the test suite + description. -.. _ReqEngTestCase: +includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. -Test Case ---------- +local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. -Test cases shall use the :ref:`RTEMS Test Framework `. +name + The attribute value shall be a :ref:`SpecTypeTestName`. -The test case items shall have the following attribute specializations: +target + The attribute value shall be a string. It shall be the path to the + generated target test suite source file. -type - The type value shall be *test-case*. +.. _ReqEngSpecificationAttributeSetsAndValueTypes: -link - The link to the requirement validated by this test case or no links if - this is a unit or integration test case. +Specification Attribute Sets and Value Types +-------------------------------------------- -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. +.. _SpecTypeApplicationConfigurationGroupMemberLinkRole: -text - A short description of the test case. +Application Configuration Group Member Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though the ``role`` attribute if the +value is ``appl-config-group-member``. It defines the application configuration +group membership role of links. + +.. _SpecTypeApplicationConfigurationOptionConstraintSet: + +Application Configuration Option Constraint Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines application configuration option constraints. +Additional constraints can be added through the links of the item using the +:ref:`SpecTypeConstraintLinkRole`. None of the explicitly defined attributes +are required. The following attributes are explicitly defined for this type: + +max + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall be + the maximum value of the application configuration option. + +min + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall be + the minimum value of the application configuration option. + +set + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeIntegerOrString`. It shall be the set of valid values for the + application configuration option. + +texts + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRequirementText`. It shall be a list of constraints specific + to this application configuration option. For general constraints, use a + link with the :ref:`SpecTypeConstraintLinkRole` to a constraint item. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + +.. _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:`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:`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:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionCXXCompilerCheckAction` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildDependencyLinkRole: + +Build Dependency Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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 +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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 by 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` + +.. _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 +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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. + +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 +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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 +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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` + +.. _SpecTypeBuildOptionDefaultByVariant: + +Build Option Default by Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies build option default values by variant. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +value + The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It value + shall be the default value for the matching variants. + +variants + The attribute value shall be a list of strings. It shall be a list of + Python regular expression matching with the desired variants. + +This type is used by the following types: + +* :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 test states for a set of test programs. +Generic attributes may be defined. Each attribute key shall be a +:ref:`SpecTypeName`. The attribute value shall be a +:ref:`SpecTypeBuildTestState`. The keys shall be test program names. 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 the name specified by the attribute key +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 by be no value (null). + +* The value may be a string. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +* :ref:`SpecTypeBuildOptionDefaultByVariant` + +* :ref:`SpecTypeBuildOptionItemType` + +.. _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:`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. +They are used to link programs referenced by this item, e.g. ``z`` for +``libz.a``. They are placed after the use items of the build item context. + +This type is used by the following types: + +* :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. +They are used to link programs referenced by this item, e.g. ``z`` for +``libz.a``. They are placed before the use items of the build item context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeConstraintLinkRole: + +Constraint Link Role +^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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` + +.. _SpecTypeEnabledXByExpression: + +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 explicitly defined attributes shall be specified. The + following attributes are explicitly defined for this type: + + and + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeEnabledXByExpression`. 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:`SpecTypeEnabledXByExpression`. 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:`SpecTypeEnabledXByExpression`. 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:`SpecTypeEnabledXByExpression`. 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:`SpecTypeEnabledXByExpression` + +* :ref:`SpecTypeInterfaceIncludeLinkRole` + +* :ref:`SpecTypeRootItemType` + +Please have a look at the following example: + +.. code-block:: yaml + + enabled-by: + and: + - RTEMS_NETWORKING + - not: RTEMS_SMP + +.. _SpecTypeGlossaryMembershipLinkRole: + +Glossary Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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:`SpecTypeApplicationConfigurationOptionConstraintSet` + +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeInterfaceBriefDescription: + +Interface Brief Description +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may by be no value (null). + +* The value may be a string. It shall be the brief description of the + interface. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +.. _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` though the ``kind`` + attribute if the value is ``struct`` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` though the ``kind`` + attribute if the value is ``union`` + +This set of attributes specifies an interface compound member compound. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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` though +the ``kind`` attribute if the value is ``member``. This set of attributes +specifies an interface compound member declaration. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface compound member definition. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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. + +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 explicitly defined attributes shall be specified. The following +attributes are explicitly defined for this type: + +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 explicitly defined attributes shall be specified. The following +attributes are explicitly defined for this type: + +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:`SpecTypeInterfaceEnabledXByExpression`. + +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 by be no value (null). + +* The value may be a string. It shall be the definition. On the definition a + context-sensitive substitution of item variables is performed. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceDefinitionDirective` + +* :ref:`SpecTypeInterfaceDefinitionVariant` + +.. _SpecTypeInterfaceDefinitionDirective: + +Interface Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface definition directive. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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:`SpecTypeInterfaceMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +.. _SpecTypeInterfaceDefinitionVariant: + +Interface Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface definition variant. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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:`SpecTypeInterfaceEnabledXByExpression`. + +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 by be no value (null). + +* The value may be a string. It shall be the description of the interface. The + description should be short and concentrate on the average case. All special + cases, usage notes, constraints, error conditions, configuration + dependencies, references, etc. should be described in the + :ref:`SpecTypeInterfaceNotes`. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceMacroItemType` + +* :ref:`SpecTypeInterfaceParameter` + +* :ref:`SpecTypeInterfaceReturnValue` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +.. _SpecTypeInterfaceEnabledXByExpression: + +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 explicitly defined attributes shall be specified. The + following attributes are explicitly defined for this type: + + and + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceEnabledXByExpression`. The *and* operator defines + a *logical and* of the expressions in the list. + + not + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledXByExpression`. 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:`SpecTypeInterfaceEnabledXByExpression`. 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:`SpecTypeInterfaceEnabledXByExpression`. 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:`SpecTypeInterfaceEnabledXByExpression` + +* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` + +.. _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` though the ``role`` attribute if the +value is ``interface-enumerator``. It defines the interface enumerator role of +links. + +.. _SpecTypeInterfaceFunctionDefinition: + +Interface Function Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function definition. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +body + The attribute value shall be an optional string. If the value is present, + then it shall be the definition of a static inline function. On the + function definition a context-sensitive substitution of item variables is + performed. If no value is present, then the function is declared as an + external function. + +params + The attribute value shall be a list of strings. It shall be the list of + parameter declarations of the function. On the function parameter + declarations a context-sensitive substitution of item variables is + performed. + +return + The attribute value shall be a string. It shall be the function return + type. On the return type a context-sensitive substitution of item + variables is performed. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionDefinitionDirective` + +* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` + +.. _SpecTypeInterfaceFunctionDefinitionDirective: + +Interface Function Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function definition directive. All +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +default + The attribute value shall be an :ref:`SpecTypeInterfaceFunctionDefinition`. + 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:`SpecTypeInterfaceFunctionDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionItemType` + +.. _SpecTypeInterfaceFunctionDefinitionVariant: + +Interface Function Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function definition variant. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +definition + The attribute value shall be an :ref:`SpecTypeInterfaceFunctionDefinition`. + 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:`SpecTypeInterfaceEnabledXByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionDefinitionDirective` + +.. _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` + +.. _SpecTypeInterfaceGroupMembershipLinkRole: + +Interface Group Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though the ``role`` attribute if the +value is ``interface-ingroup``. It defines the interface group membership role +of links. + +.. _SpecTypeInterfaceIncludeLinkRole: + +Interface Include Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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 +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledXByExpression`. 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 by be no value (null). + +* The value may be a string. It shall be the notes for the interface. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionItemType` + +* :ref:`SpecTypeInterfaceMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +.. _SpecTypeInterfaceParameter: + +Interface Parameter +^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface parameter. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +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:`SpecTypeInterfaceFunctionItemType` + +* :ref:`SpecTypeInterfaceMacroItemType` + +.. _SpecTypeInterfaceParameterDirection: + +Interface Parameter Direction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may by be no value (null). + +* The value may be a string. It specifies the interface parameter direction. + The value shall be an element of + + * "``in``", + + * "``out``", and + + * "``inout``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceParameter` + +.. _SpecTypeInterfacePlacementLinkRole: + +Interface Placement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface return. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +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`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionItemType` + +* :ref:`SpecTypeInterfaceMacroItemType` + +.. _SpecTypeInterfaceReturnValue: + +Interface Return Value +^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface return value. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +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` though 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 explicitly defined attributes shall be specified. +The following attributes are explicitly defined for this type: + +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:`SpecTypeApplicationConfigurationGroupMemberLinkRole` + +* :ref:`SpecTypeBuildDependencyLinkRole` + +* :ref:`SpecTypeConstraintLinkRole` + +* :ref:`SpecTypeGlossaryMembershipLinkRole` + +* :ref:`SpecTypeInterfaceEnumeratorLinkRole` + +* :ref:`SpecTypeInterfaceGroupMembershipLinkRole` + +* :ref:`SpecTypeInterfaceIncludeLinkRole` + +* :ref:`SpecTypeInterfacePlacementLinkRole` + +* :ref:`SpecTypeInterfaceTargetLinkRole` + +* :ref:`SpecTypeRequirementRefinementLinkRole` + +* :ref:`SpecTypeRequirementValidationLinkRole` + +* :ref:`SpecTypeSpecificationMemberLinkRole` + +* :ref:`SpecTypeSpecificationRefinementLinkRole` + +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:`SpecTypeGlossaryItemType` + +* :ref:`SpecTypeInterfaceItemType` + +* :ref:`SpecTypeLink` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRootItemType` + +* :ref:`SpecTypeSpecificationAttributeValue` + +* :ref:`SpecTypeSpecificationGenericAttributes` + +* :ref:`SpecTypeSpecificationItemType` + +* :ref:`SpecTypeSpecificationList` + +* :ref:`SpecTypeSpecificationRefinementLinkRole` + +.. _SpecTypeOptionalString: + +Optional String +^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may by be no value (null). + +* The value may be a string. + +.. _SpecTypeRequirementFunctionalType: + +Requirement Functional Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. This type shall be used for functional requirement +types. The value shall be an element of + +* "``capability``", + +* "``dependability-function``", + +* "``function``", + +* "``operational``", and + +* "``safety-function``". + +This type is used by the following types: + +* :ref:`SpecTypeFunctionalRequirementItemType` + +.. _SpecTypeRequirementNonXFunctionalType: + +Requirement Non-Functional Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. This type shall be used for non-functional +requirement types. The value shall be an element of + +* "``build-configuration``", + +* "``constraint``", + +* "``design``", + +* "``documentation``", + +* "``interface``", + +* "``interface-requirement``", + +* "``maintainability``", + +* "``performance``", + +* "``portability``", + +* "``quality``", + +* "``reliability``", + +* "``resource``", and + +* "``safety``". + +This type is used by the following types: + +* :ref:`SpecTypeNonXFunctionalRequirementItemType` + +.. _SpecTypeRequirementReference: + +Requirement Reference +^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a requirement reference. All explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +identifier + The attribute value shall be a string. It shall be the type-specific + identifier of the reference target. For *group* references use the Doxygen + group identifier. + +type + The attribute value shall be a :ref:`SpecTypeRequirementReferenceType`. + +This type is used by the following types: + +* :ref:`SpecTypeRequirementItemType` + +.. _SpecTypeRequirementReferenceType: + +Requirement Reference Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the type of a requirement reference. +The value shall be an element of + +* "``define``", + +* "``file``", + +* "``function``", + +* "``group``", + +* "``macro``", and + +* "``variable``". + +This type is used by the following types: + +* :ref:`SpecTypeRequirementReference` + +.. _SpecTypeRequirementRefinementLinkRole: + +Requirement Refinement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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 +value shall not contain an element of + +* "``acceptable``", + +* "``adequate``", + +* "``almost always``", + +* "``and/or``", + +* "``appropriate``", + +* "``approximately``", + +* "``as far as possible``", + +* "``as much as practicable``", + +* "``best``", + +* "``best possible``", + +* "``easy``", + +* "``efficient``", + +* "``e.g.``", + +* "``enable``", + +* "``enough``", + +* "``etc.``", + +* "``few``", + +* "``first rate``", + +* "``flexible``", + +* "``generally``", + +* "``goal``", + +* "``graceful``", + +* "``great``", + +* "``greatest``", + +* "``ideally``", + +* "``i.e.``", + +* "``if possible``", + +* "``in most cases``", + +* "``large``", + +* "``many``", + +* "``maximize``", + +* "``minimize``", + +* "``most``", + +* "``multiple``", + +* "``necessary``", + +* "``numerous``", + +* "``optimize``", + +* "``ought to``", + +* "``probably``", + +* "``quick``", + +* "``rapid``", + +* "``reasonably``", + +* "``relevant``", + +* "``robust``", + +* "``satisfactory``", + +* "``several``", + +* "``shall be included but not limited to``", + +* "``simple``", + +* "``small``", + +* "``some``", + +* "``state of the art``", + +* "``sufficient``", + +* "``suitable``", + +* "``support``", + +* "``systematically``", + +* "``transparent``", + +* "``typical``", + +* "``user friendly``", + +* "``usually``", + +* "``versatile``", and + +* "``when necessary``". + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationGroupItemType` + +* :ref:`SpecTypeApplicationConfigurationOptionConstraintSet` + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeConstraintItemType` + +* :ref:`SpecTypeRequirementItemType` + +.. _SpecTypeRequirementValidationLinkRole: + +Requirement Validation Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though the ``role`` attribute if the +value is ``validation``. It defines the requirement validation role of links. + +.. _SpecTypeRequirementValidationMethod: + +Requirement Validation Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. This value type characterizes a requirement +validation method (except validation by test). The value shall be an element of + +* "``by-analysis``", + +* "``by-inspection``", and + +* "``by-review-of-design``". + +This type is used by the following types: + +* :ref:`SpecTypeRequirementValidationItemType` + +.. _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` + +.. _SpecTypeSpecificationAttribute: + +Specification Attribute +^^^^^^^^^^^^^^^^^^^^^^^ + +Generic attributes may be defined. Each attribute key shall be a +:ref:`SpecTypeName`. The attribute value shall be a +:ref:`SpecTypeSpecificationAttributeValue`. The generic attributes specify an +attribute set. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationAttributeSet: + +Specification Attribute Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a set of attributes. The following explicitly +defined attributes are required: + +* ``attributes`` + +* ``description`` + +* ``required-attributes`` + +The following attributes are explicitly defined for this type: + +attributes + The attribute value shall be a :ref:`SpecTypeSpecificationAttribute`. It + shall be the specification of the set of explicitly defined attributes. + +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 be the + specification of the generic attributes of the attribute set. + +required-attributes + The attribute value shall be a + :ref:`SpecTypeSpecificationRequiredAttributes`. It shall be the set of + required 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 explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +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:`SpecTypeSpecificationAttribute` + +.. _SpecTypeSpecificationBooleanValue: + +Specification Boolean Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This attribute set specifies a boolean value. Only the ``description`` +attribute is required. The following attributes are explicitly defined for this +type: + +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` + +.. _SpecTypeSpecificationFloatingXPointAssert: + +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 explicitly defined attributes shall be specified. The + following attributes are explicitly defined for this type: + + and + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationFloatingXPointAssert`. 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:`SpecTypeSpecificationFloatingXPointAssert`. 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:`SpecTypeSpecificationFloatingXPointAssert`. 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:`SpecTypeSpecificationFloatingXPointAssert`. 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:`SpecTypeSpecificationFloatingXPointAssert` + +* :ref:`SpecTypeSpecificationFloatingXPointValue` + +.. _SpecTypeSpecificationFloatingXPointValue: + +Specification Floating-Point Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a floating-point value. Only the +``description`` attribute is required. The following attributes are explicitly +defined for this type: + +assert + The attribute value shall be a + :ref:`SpecTypeSpecificationFloatingXPointAssert`. 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 defined. They are restricted to a uniform +attribute value type. All explicitly defined attributes shall be specified. The +following attributes are explicitly defined for this type: + +description + The attribute value shall be an optional string. It shall be the + description of the generic attributes. + +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 +explicitly defined attributes shall be specified. The following attributes are +explicitly defined for this type: + +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:`SpecTypeSpecificationFloatingXPointValue`. 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 explicitly defined attributes shall be specified. The + following attributes are explicitly defined for this type: + + 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 required. The following attributes are explicitly defined for this +type: + +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 explicitly +defined attributes shall be specified. The following attributes are explicitly +defined for this type: + +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` + +.. _SpecTypeSpecificationMemberLinkRole: + +Specification Member Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` though 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` though the ``role`` attribute if the +value is ``spec-refinement``. It defines the specification refinement role of +links. All explicitly defined attributes shall be specified. The following +attributes are explicitly defined for this type: + +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. + +.. _SpecTypeSpecificationRequiredAttributes: + +Specification Required Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This attribute value defines which of the explicitly defined attributes are +required. + +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`. + This list defines the required attributes through their keys. + +* The value may be a string. This string defines the how many explicitly + defined attributes are required. 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` + +.. _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 explicitly defined attributes shall be specified. The + following attributes are explicitly defined for this type: + + 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 required. The following attributes are explicitly defined for this type: + +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 explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +action + The attribute value shall be a string. It shall be the test case action + code. + +checks + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestCaseCheck`. + +description + The attribute value shall be an optional string. It shall be the test case + action description. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. + +This type is used by the following types: + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestCaseCheck: + +Test Case Check +^^^^^^^^^^^^^^^ + +This set of attributes specifies a test case check. All explicitly defined +attributes shall be specified. The following attributes are explicitly defined +for this type: + +check + The attribute value shall be a string. It shall be the test case check + code. + +description + The attribute value shall be an optional string. It shall be the test case + check description. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. + +This type is used by the following types: + +* :ref:`SpecTypeTestCaseAction` + +.. _SpecTypeTestName: -inputs - The inputs to execute the test case. +Test Name +^^^^^^^^^ -outputs - The expected outputs. +The value shall be a string. It shall be the name of a test suite or test case. +It shall be formatted in the style of a caption. If shall form a valid C +designator after removal of all white space characters. The value shall match +with the regular expression "``^[A-Z][a-zA-Z0-9 _]+$"``. -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. +This type is used by the following types: -.. _ReqEngResAndPerf: +* :ref:`SpecTypeTestCaseItemType` -Resources and Performance -------------------------- +* :ref:`SpecTypeTestSuiteItemType` -Normally, resource and performance requirements are formulated like this: +.. _SpecTypeUID: -* The resource U shall need less than V storage units. +UID +^^^ -* The operation Y shall complete within X time units. +The value shall be a string. The string shall be a valid absolute or relative +item UID. -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. +This type is used by the following types: -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. +* :ref:`SpecTypeLink` diff --git a/eng/req/req-for-req.rst b/eng/req/req-for-req.rst index d38e384..9225e95 100644 --- a/eng/req/req-for-req.rst +++ b/eng/req/req-for-req.rst @@ -346,4 +346,49 @@ 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:`ReqEngSpecItems`. +: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/traceability.rst b/eng/req/traceability.rst index 012c3db..9376a5f 100644 --- a/eng/req/traceability.rst +++ b/eng/req/traceability.rst @@ -57,20 +57,21 @@ Traceability between Software Requirements, Architecture and Design ------------------------------------------------------------------- The software requirements are implemented in custom YAML files, see -:ref:`ReqEngSpecItems`. 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 `_ 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. +: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 +`_ 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/req/validation.rst b/eng/req/validation.rst deleted file mode 100644 index b4d4286..0000000 --- a/eng/req/validation.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) - -.. _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. - -For a specification item in a parent directory it could be checked that at -least one item in a subdirectory has a link to it. For example a subdirectory -could contain validation items. With this feature you could 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. -- cgit v1.2.3