source: rtems-docs/eng/req/items.rst

.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2019, 2023 embedded brains GmbH & Co. KG

.. This file is part of the RTEMS quality process and was automatically
.. generated.  If you find something that needs to be fixed or
.. worded better please post a report or patch to an RTEMS mailing list
.. or raise a bug report:
..
.. https://www.rtems.org/bugs.html
..
.. For information on updating and regenerating please refer to the How-To
.. section in the Software Requirements Engineering chapter of the
.. RTEMS Software Engineering manual.  The manual is provided as a part of
.. a release.  For development sources please refer to the online
.. documentation at:
..
.. https://docs.rtems.org

.. _ReqEngSpecificationItems:

Specification Items
===================

.. _ReqEngSpecificationItemHierarchy:

Specification Item Hierarchy
----------------------------

The specification item types have the following hierarchy:

* :ref:`SpecTypeRootItemType`

  * :ref:`SpecTypeBuildItemType`

    * :ref:`SpecTypeBuildAdaTestProgramItemType`

    * :ref:`SpecTypeBuildBSPItemType`

    * :ref:`SpecTypeBuildConfigurationFileItemType`

    * :ref:`SpecTypeBuildConfigurationHeaderItemType`

    * :ref:`SpecTypeBuildGroupItemType`

    * :ref:`SpecTypeBuildLibraryItemType`

    * :ref:`SpecTypeBuildObjectsItemType`

    * :ref:`SpecTypeBuildOptionItemType`

    * :ref:`SpecTypeBuildScriptItemType`

    * :ref:`SpecTypeBuildStartFileItemType`

    * :ref:`SpecTypeBuildTestProgramItemType`

  * :ref:`SpecTypeConstraintItemType`

  * :ref:`SpecTypeGlossaryItemType`

    * :ref:`SpecTypeGlossaryGroupItemType`

    * :ref:`SpecTypeGlossaryTermItemType`

  * :ref:`SpecTypeInterfaceItemType`

    * :ref:`SpecTypeApplicationConfigurationGroupItemType`

    * :ref:`SpecTypeApplicationConfigurationOptionItemType`

      * :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType`

      * :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType`

      * :ref:`SpecTypeApplicationConfigurationValueOptionItemType`

    * :ref:`SpecTypeInterfaceCompoundItemType`

    * :ref:`SpecTypeInterfaceDefineItemType`

    * :ref:`SpecTypeInterfaceDomainItemType`

    * :ref:`SpecTypeInterfaceEnumItemType`

    * :ref:`SpecTypeInterfaceEnumeratorItemType`

    * :ref:`SpecTypeInterfaceForwardDeclarationItemType`

    * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

    * :ref:`SpecTypeInterfaceGroupItemType`

    * :ref:`SpecTypeInterfaceHeaderFileItemType`

    * :ref:`SpecTypeInterfaceTypedefItemType`

    * :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType`

    * :ref:`SpecTypeInterfaceUnspecifiedItemType`

    * :ref:`SpecTypeInterfaceVariableItemType`

    * :ref:`SpecTypeRegisterBlockItemType`

  * :ref:`SpecTypeProxyItemTypes`

  * :ref:`SpecTypeRequirementItemType`

    * :ref:`SpecTypeFunctionalRequirementItemType`

      * :ref:`SpecTypeActionRequirementItemType`

      * :ref:`SpecTypeGenericFunctionalRequirementItemType`

    * :ref:`SpecTypeNonFunctionalRequirementItemType`

      * :ref:`SpecTypeDesignGroupRequirementItemType`

      * :ref:`SpecTypeDesignTargetItemType`

      * :ref:`SpecTypeGenericNonFunctionalRequirementItemType`

      * :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType`

      * :ref:`SpecTypeRuntimePerformanceRequirementItemType`

  * :ref:`SpecTypeRequirementValidationItemType`

    * :ref:`SpecTypeRequirementValidationMethod`

  * :ref:`SpecTypeRuntimeMeasurementTestItemType`

  * :ref:`SpecTypeSpecificationItemType`

  * :ref:`SpecTypeTestCaseItemType`

  * :ref:`SpecTypeTestPlatformItemType`

  * :ref:`SpecTypeTestProcedureItemType`

  * :ref:`SpecTypeTestSuiteItemType`

.. _ReqEngSpecificationItemTypes:

Specification Item Types
------------------------

.. _SpecTypeRootItemType:

Root Item Type
^^^^^^^^^^^^^^

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

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

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

SPDX-License-Identifier
    The attribute value shall be a :ref:`SpecTypeSPDXLicenseIdentifier`. It
    shall be the license of the item.

copyrights
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeCopyright`. It shall be the list of copyright statements of
    the item.

enabled-by
    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It
    shall define the conditions under which the item is enabled.

links
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeLink`.

type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the item
    type.  The selection of types and the level of detail depends on a
    particular standard and product model.  We need enough flexibility to be in
    line with ECSS-E-ST-10-06 and possible future applications of other
    standards.  The item type may be refined further with additional
    type-specific subtypes.

This type is refined by the following types:

* :ref:`SpecTypeBuildItemType`

* :ref:`SpecTypeConstraintItemType`

* :ref:`SpecTypeGlossaryItemType`

* :ref:`SpecTypeInterfaceItemType`

* :ref:`SpecTypeProxyItemTypes`

* :ref:`SpecTypeRequirementItemType`

* :ref:`SpecTypeRequirementValidationItemType`

* :ref:`SpecTypeRuntimeMeasurementTestItemType`

* :ref:`SpecTypeSpecificationItemType`

* :ref:`SpecTypeTestCaseItemType`

* :ref:`SpecTypeTestPlatformItemType`

* :ref:`SpecTypeTestProcedureItemType`

* :ref:`SpecTypeTestSuiteItemType`

.. _SpecTypeBuildItemType:

Build Item Type
^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``build``. This set of attributes specifies a build
item. All explicit attributes shall be specified. The explicit attributes for
this type are:

build-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the build
    item type.

This type is refined by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildBSPItemType`

* :ref:`SpecTypeBuildConfigurationFileItemType`

* :ref:`SpecTypeBuildConfigurationHeaderItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

* :ref:`SpecTypeBuildOptionItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildStartFileItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildAdaTestProgramItemType:

Build Ada Test Program Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

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

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

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

ldflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildLinkerOption`.

source
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildSource`.

stlib
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`.

use-after
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseAfterDirective`.

use-before
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseBeforeDirective`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildBSPItemType:

Build BSP Item Type
^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
attribute if the value is ``bsp``. This set of attributes specifies a base BSP
variant to build. All explicit attributes shall be specified. The explicit
attributes for this type are:

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

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

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

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

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

install
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildInstallDirective`.

source
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildSource`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildConfigurationFileItemType:

Build Configuration File Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

install-path
    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildConfigurationHeaderItemType:

Build Configuration Header Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

install-path
    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`.

.. _SpecTypeBuildGroupItemType:

Build Group Item Type
^^^^^^^^^^^^^^^^^^^^^

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

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

install
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildInstallDirective`.

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

use-after
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseAfterDirective`.

use-before
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseBeforeDirective`.

Please have a look at the following example:

.. code-block:: yaml

    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    build-type: group
    cflags: []
    copyrights:
    - Copyright (C) 2020 embedded brains GmbH & Co. KG
    cppflags: []
    cxxflags: []
    enabled-by:
    - BUILD_TESTS
    - BUILD_SAMPLES
    includes:
    - testsuites/support/include
    install: []
    ldflags:
    - -Wl,--wrap=printf
    - -Wl,--wrap=puts
    links:
    - role: build-dependency
      uid: ticker
    type: build
    use-after: []
    use-before:
    - rtemstest

.. _SpecTypeBuildLibraryItemType:

Build Library Item Type
^^^^^^^^^^^^^^^^^^^^^^^

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

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

install
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildInstallDirective`.

install-path
    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.

source
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildSource`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`. It shall be the
    name of the static library, e.g. ``z`` for ``libz.a``.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildObjectsItemType:

Build Objects Item Type
^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
attribute if the value is ``objects``. This set of attributes specifies a set
of object files used to build static libraries or test programs. Objects Items
must not be included on multiple paths through the build dependency graph with
identical build options. Violating this can cause race conditions in the build
system due to duplicate installs and multiple instances of build tasks. All
explicit attributes shall be specified. The explicit attributes for this type
are:

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

install
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildInstallDirective`.

source
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildSource`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildOptionItemType:

Build Option Item Type
^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
attribute if the value is ``option``. This set of attributes specifies a build
option. The following explicit attributes are mandatory:

* ``actions``

* ``default``

* ``description``

The explicit attributes for this type are:

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

default
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildOptionDefaultValue`. It shall be the list of default
    values of the option.  When a default value is needed, the first value on
    the list which is enabled according to the enabled set is choosen.  If no
    value is enabled, then the default value is ``null``.

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

format
    The attribute value shall be an optional string. It shall be a `Python
    format string
    <https://docs.python.org/3/library/string.html#formatstrings>`_, for
    example ``'{}'`` or ``'{:#010x}'``.

name
    The attribute value shall be a :ref:`SpecTypeBuildOptionName`.

Please have a look at the following example:

.. code-block:: yaml

    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    actions:
    - get-integer: null
    - define: null
    build-type: option
    copyrights:
    - Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG
    default:
    - enabled-by:
      - bsps/powerpc/motorola_powerpc
      - m68k/m5484FireEngine
      - powerpc/hsc_cm01
      value: 9600
    - enabled-by: m68k/COBRA5475
      value: 19200
    - enabled-by: true
      value: 115200
    description: |
      Default baud for console and other serial devices.
    enabled-by: true
    format: '{}'
    links: []
    name: BSP_CONSOLE_BAUD
    type: build

.. _SpecTypeBuildScriptItemType:

Build Script Item Type
^^^^^^^^^^^^^^^^^^^^^^

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

* ``do-build``

* ``do-configure``

* ``prepare-build``

* ``prepare-configure``

The explicit attributes for this type are:

asflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildAssemblerOption`.

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

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

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

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

ldflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildLinkerOption`.

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

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

stlib
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`.

use-after
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseAfterDirective`.

use-before
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseBeforeDirective`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildStartFileItemType:

Build Start File Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

asflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildAssemblerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

install-path
    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.

source
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildSource`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeBuildTestProgramItemType:

Build Test Program Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

cppflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCPreprocessorOption`.

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

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

includes
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildIncludePath`.

ldflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildLinkerOption`.

source
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildSource`.

stlib
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.

target
    The attribute value shall be a :ref:`SpecTypeBuildTarget`.

use-after
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseAfterDirective`.

use-before
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildUseBeforeDirective`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeConstraintItemType:

Constraint Item Type
^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``constraint``. This set of attributes specifies a
constraint. All explicit attributes shall be specified. The explicit attributes
for this type are:

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

text
    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
    state the constraint.

.. _SpecTypeGlossaryItemType:

Glossary Item Type
^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``glossary``. This set of attributes specifies a
glossary item. All explicit attributes shall be specified. The explicit
attributes for this type are:

glossary-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    glossary item type.

This type is refined by the following types:

* :ref:`SpecTypeGlossaryGroupItemType`

* :ref:`SpecTypeGlossaryTermItemType`

.. _SpecTypeGlossaryGroupItemType:

Glossary Group Item Type
^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeGlossaryItemType` through the
``glossary-type`` attribute if the value is ``group``. This set of attributes
specifies a glossary group. All explicit attributes shall be specified. The
explicit attributes for this type are:

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

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

.. _SpecTypeGlossaryTermItemType:

Glossary Term Item Type
^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeGlossaryItemType` through the
``glossary-type`` attribute if the value is ``term``. This set of attributes
specifies a glossary term. All explicit attributes shall be specified. The
explicit attributes for this type are:

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

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

.. _SpecTypeInterfaceItemType:

Interface Item Type
^^^^^^^^^^^^^^^^^^^

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

index-entries
    The attribute value shall be a list of strings. It shall be a list of
    additional document index entries.  A document index entry derived from the
    interface name is added automatically.

interface-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    interface item type.

This type is refined by the following types:

* :ref:`SpecTypeApplicationConfigurationGroupItemType`

* :ref:`SpecTypeApplicationConfigurationOptionItemType`

* :ref:`SpecTypeInterfaceCompoundItemType`

* :ref:`SpecTypeInterfaceDefineItemType`

* :ref:`SpecTypeInterfaceDomainItemType`

* :ref:`SpecTypeInterfaceEnumItemType`

* :ref:`SpecTypeInterfaceEnumeratorItemType`

* :ref:`SpecTypeInterfaceForwardDeclarationItemType`

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

* :ref:`SpecTypeInterfaceGroupItemType`

* :ref:`SpecTypeInterfaceHeaderFileItemType`

* :ref:`SpecTypeInterfaceTypedefItemType`

* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType`

* :ref:`SpecTypeInterfaceUnspecifiedItemType`

* :ref:`SpecTypeInterfaceVariableItemType`

* :ref:`SpecTypeRegisterBlockItemType`

.. _SpecTypeApplicationConfigurationGroupItemType:

Application Configuration Group Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``appl-config-group``. This set of
attributes specifies an application configuration group. All explicit
attributes shall be specified. The explicit attributes for this type are:

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

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

text
    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
    state the requirement for the application configuration group.

.. _SpecTypeApplicationConfigurationOptionItemType:

Application Configuration Option Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``appl-config-option``. This set
of attributes specifies an application configuration option. All explicit
attributes shall be specified. The explicit attributes for this type are:

appl-config-option-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    application configuration option type.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

name
    The attribute value shall be an
    :ref:`SpecTypeApplicationConfigurationOptionName`.

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

This type is refined by the following types:

* :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType`

* :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType`

* :ref:`SpecTypeApplicationConfigurationValueOptionItemType`

.. _SpecTypeApplicationConfigurationFeatureEnableOptionItemType:

Application Configuration Feature Enable Option Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType`
through the ``appl-config-option-type`` attribute if the value is
``feature-enable``. This set of attributes specifies an application
configuration feature enable option.

.. _SpecTypeApplicationConfigurationFeatureOptionItemType:

Application Configuration Feature Option Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType`
through the ``appl-config-option-type`` attribute if the value is ``feature``.
This set of attributes specifies an application configuration feature option.
All explicit attributes shall be specified. The explicit attributes for this
type are:

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

.. _SpecTypeApplicationConfigurationValueOptionItemType:

Application Configuration Value Option Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the
  ``appl-config-option-type`` attribute if the value is ``initializer``

* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the
  ``appl-config-option-type`` attribute if the value is ``integer``

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

default-value
    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall
    describe the default value of the application configuration option.

.. _SpecTypeInterfaceCompoundItemType:

Interface Compound Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``struct``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``union``

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

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`.

definition-kind
    The attribute value shall be an
    :ref:`SpecTypeInterfaceCompoundDefinitionKind`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

.. _SpecTypeInterfaceDefineItemType:

Interface Define Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``define``. This set of attributes
specifies a define. All explicit attributes shall be specified. The explicit
attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be an
    :ref:`SpecTypeInterfaceDefinitionDirective`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

.. _SpecTypeInterfaceDomainItemType:

Interface Domain Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``domain``. This set of attributes
specifies an interface domain.  Interface items are placed into domains through
links with the :ref:`SpecTypeInterfacePlacementLinkRole`. All explicit
attributes shall be specified. The explicit attributes for this type are:

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

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

.. _SpecTypeInterfaceEnumItemType:

Interface Enum Item Type
^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``enum``. This set of attributes
specifies an enum. All explicit attributes shall be specified. The explicit
attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition-kind
    The attribute value shall be an :ref:`SpecTypeInterfaceEnumDefinitionKind`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

.. _SpecTypeInterfaceEnumeratorItemType:

Interface Enumerator Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``enumerator``. This set of
attributes specifies an enumerator. All explicit attributes shall be specified.
The explicit attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be an
    :ref:`SpecTypeInterfaceDefinitionDirective`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

.. _SpecTypeInterfaceForwardDeclarationItemType:

Interface Forward Declaration Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``forward-declaration``. Items of
this type specify a forward declaration.  The item shall have exactly one link
with the :ref:`SpecTypeInterfaceTargetLinkRole` to an
:ref:`SpecTypeInterfaceCompoundItemType` item.  This link defines the type
declared by the forward declaration.

.. _SpecTypeInterfaceFunctionOrMacroItemType:

Interface Function or Macro Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``function``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``macro``

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

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be an
    :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

params
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceParameter`.

return
    The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`.

.. _SpecTypeInterfaceGroupItemType:

Interface Group Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``group``. This set of attributes
specifies an interface group. All explicit attributes shall be specified. The
explicit attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

identifier
    The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`.

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

text
    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
    state the requirement for the interface group.

.. _SpecTypeInterfaceHeaderFileItemType:

Interface Header File Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``header-file``. This set of
attributes specifies a header file.  The item shall have exactly one link with
the :ref:`SpecTypeInterfacePlacementLinkRole` to an
:ref:`SpecTypeInterfaceDomainItemType` item.  This link defines the interface
domain of the header file. All explicit attributes shall be specified. The
explicit attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

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

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

.. _SpecTypeInterfaceTypedefItemType:

Interface Typedef Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``typedef``. This set of
attributes specifies a typedef. All explicit attributes shall be specified. The
explicit attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be an
    :ref:`SpecTypeInterfaceDefinitionDirective`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

params
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceParameter`.

return
    The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`.

.. _SpecTypeInterfaceUnspecifiedHeaderFileItemType:

Interface Unspecified Header File Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``unspecified-header-file``. This
set of attributes specifies an unspecified header file. All explicit attributes
shall be specified. The explicit attributes for this type are:

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

references
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeExternalReference`.

.. _SpecTypeInterfaceUnspecifiedItemType:

Interface Unspecified Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-define``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-enum``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-enumerator``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-function``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-group``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-macro``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-object``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-struct``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-typedef``

* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
  the value is ``unspecified-union``

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

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

references
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeExternalReference`.

.. _SpecTypeInterfaceVariableItemType:

Interface Variable Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``variable``. This set of
attributes specifies a variable. All explicit attributes shall be specified.
The explicit attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be an
    :ref:`SpecTypeInterfaceDefinitionDirective`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

.. _SpecTypeRegisterBlockItemType:

Register Block Item Type
^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceItemType` through the
``interface-type`` attribute if the value is ``register-block``. This set of
attributes specifies a register block.  A register block may be used to specify
the interface of devices.  Register blocks consist of register block members
specified by the ``definition`` attribute. Register block members are either
instances of registers specified by the ``registers`` attribute or instances of
other register blocks specified by links with the
:ref:`SpecTypeRegisterBlockIncludeRole`. Registers consists of bit fields (see
:ref:`SpecTypeRegisterBitsDefinition`.  The register block members are placed
into the address space of the device relative to the base address of the
register block.  Register member offsets and the register block size are
specified in units of the address space granule. All explicit attributes shall
be specified. The explicit attributes for this type are:

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

definition
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

identifier
    The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`.

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

notes
    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.

register-block-group
    The attribute value shall be a string. It shall be the name of the
    interface group defined for the register block.  For the group identifier
    see the ``identifier`` attribute.

register-block-size
    The attribute value shall be an :ref:`SpecTypeOptionalInteger`. If the
    value is present, then it shall be the size of the register block in units
    of the address space granule.

register-prefix
    The attribute value shall be an optional string. If the value is present,
    then it will be used to prefix register bit field names, otherwise the
    value of the ``name`` attribute will be used.

registers
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterDefinition`.

.. _SpecTypeProxyItemTypes:

Proxy Item Types
^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``proxy``. Items of similar characteristics may link
to a proxy item through links with the :ref:`SpecTypeProxyMemberLinkRole`.  A
proxy item resolves to the first member item which is enabled.  Proxies may be
used to provide an interface with a common name and implementations which
depend on configuration options.  For example, in one configuration a constant
could be a compile time constant and in another configuration it could be a
read-only object.

.. _SpecTypeRequirementItemType:

Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``requirement``. This set of attributes specifies a
requirement. All explicit attributes shall be specified. The explicit
attributes for this type are:

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

references
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeExternalReference`.

requirement-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    requirement item type.

text
    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
    state the requirement.

This type is refined by the following types:

* :ref:`SpecTypeFunctionalRequirementItemType`

* :ref:`SpecTypeNonFunctionalRequirementItemType`

Please have a look at the following example:

.. code-block:: yaml

    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    copyrights:
    - Copyright (C) 2020 embedded brains GmbH & Co. KG
    enabled-by: true
    functional-type: capability
    links: []
    rationale: |
      It keeps you busy.
    requirement-type: functional
    text: |
      The system shall do crazy things.
    type: requirement

.. _SpecTypeFunctionalRequirementItemType:

Functional Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRequirementItemType` through the
``requirement-type`` attribute if the value is ``functional``. This set of
attributes specifies a functional requirement. All explicit attributes shall be
specified. The explicit attributes for this type are:

functional-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    functional type of the requirement.

This type is refined by the following types:

* :ref:`SpecTypeActionRequirementItemType`

* :ref:`SpecTypeGenericFunctionalRequirementItemType`

.. _SpecTypeActionRequirementItemType:

Action Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

For action requirements which specify the function of an interface, there shall
be exactly one link with the :ref:`SpecTypeInterfaceFunctionLinkRole` to the
interface of the action.

The action requirements are specified by

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

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

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

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

post-conditions
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeActionRequirementCondition`.

pre-conditions
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeActionRequirementCondition`.

skip-reasons
    The attribute value shall be an
    :ref:`SpecTypeActionRequirementSkipReasons`.

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

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

test-cleanup
    The attribute value shall be an optional string. If the value is present,
    then it shall be the test cleanup code.  The code is placed in the test
    action loop body after the test post-condition checks.

test-context
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeTestContextMember`.

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

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

test-header
    The attribute value shall be a :ref:`SpecTypeTestHeader`.

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

test-local-includes
    The attribute value shall be a list of strings. It shall be a list of
    header files included via ``#include "..."``.

test-prepare
    The attribute value shall be an optional string. If the value is present,
    then it shall be the early test preparation code.  The code is placed in
    the test action loop body before the test pre-condition preparations.

test-setup
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.

test-stop
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.

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

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

test-teardown
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.

transition-map
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeActionRequirementTransition`.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeGenericFunctionalRequirementItemType:

Generic Functional Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
  attribute if the value is ``capability``

* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
  attribute if the value is ``dependability-function``

* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
  attribute if the value is ``function``

* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
  attribute if the value is ``interface-define-not-defined``

* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
  attribute if the value is ``operational``

* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
  attribute if the value is ``safety-function``

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

.. _SpecTypeNonFunctionalRequirementItemType:

Non-Functional Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRequirementItemType` through the
``requirement-type`` attribute if the value is ``non-functional``. This set of
attributes specifies a non-functional requirement. All explicit attributes
shall be specified. The explicit attributes for this type are:

non-functional-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    non-functional type of the requirement.

This type is refined by the following types:

* :ref:`SpecTypeDesignGroupRequirementItemType`

* :ref:`SpecTypeDesignTargetItemType`

* :ref:`SpecTypeGenericNonFunctionalRequirementItemType`

* :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType`

* :ref:`SpecTypeRuntimePerformanceRequirementItemType`

.. _SpecTypeDesignGroupRequirementItemType:

Design Group Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through
the ``non-functional-type`` attribute if the value is ``design-group``. This
set of attributes specifies a design group requirement.  Design group
requirements have an explicit reference to the associated Doxygen group
specified by the ``identifier`` attribute.  Design group requirements have an
implicit validation by inspection method.  The qualification toolchain shall
perform the inspection and check that the specified Doxygen group exists in the
software source code. All explicit attributes shall be specified. The explicit
attributes for this type are:

identifier
    The attribute value shall be a
    :ref:`SpecTypeRequirementDesignGroupIdentifier`.

.. _SpecTypeDesignTargetItemType:

Design Target Item Type
^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through
the ``non-functional-type`` attribute if the value is ``design-target``. This
set of attributes specifies a design :term:`target`. All explicit attributes
shall be specified. The explicit attributes for this type are:

brief
    The attribute value shall be an optional string. If the value is present,
    then it shall briefly describe the target.

description
    The attribute value shall be an optional string. If the value is present,
    then it shall thoroughly describe the target.

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

.. _SpecTypeGenericNonFunctionalRequirementItemType:

Generic Non-Functional Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``build-configuration``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``constraint``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``design``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``documentation``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``interface``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``interface-requirement``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``maintainability``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``performance``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is
  ``performance-runtime-limits``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``portability``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``quality``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``reliability``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``resource``

* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
  ``non-functional-type`` attribute if the value is ``safety``

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

.. _SpecTypeRuntimeMeasurementEnvironmentItemType:

Runtime Measurement Environment Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through
the ``non-functional-type`` attribute if the value is
``performance-runtime-environment``. This set of attributes specifies a runtime
measurement environment. All explicit attributes shall be specified. The
explicit attributes for this type are:

name
    The attribute value shall be a string. It shall be the runtime measurement
    environment name.  See also
    :ref:`SpecTypeRuntimeMeasurementEnvironmentName`.

.. _SpecTypeRuntimePerformanceRequirementItemType:

Runtime Performance Requirement Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through
the ``non-functional-type`` attribute if the value is ``performance-runtime``.
The item shall have exactly one link with the
:ref:`SpecTypeRuntimeMeasurementRequestLinkRole`.  A requirement text processor
shall support a substitution of ${.:/limit-kind}:

* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound`` or
  ``min-upper-bound``, the substitution of ${.:/limit-kind} shall be
  ``"minimum"``.

* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``mean-lower-bound`` or
  ``mean-upper-bound``, the substitution of ${.:/limit-kind} shall be
  ``"mean"``.

* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``max-lower-bound`` or
  ``max-upper-bound``, the substitution of ${.:/limit-kind} shall be
  ``"maximum"``.

A requirement text processor shall support a substitution of
${.:/limit-condition}:

* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound``,
  ``mean-lower-bound``, or ``max-lower-bound``, the substitution of
  ${.:/limit-condition} shall be ``"greater than or equal to <value>"`` with
  <value> being the value of the corresponding entry in the
  :ref:`SpecTypeRuntimeMeasurementValueTable`.

* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-upper-bound``,
  ``mean-upper-bound``, or ``max-upper-bound``, the substitution of
  ${.:/limit-condition} shall be ``"less than or equal to <value>"`` with
  <value> being the value of the corresponding entry in the
  :ref:`SpecTypeRuntimeMeasurementValueTable`.

A requirement text processor shall support a substitution of ${.:/environment}.
The value of the substitution shall be ``"<environment> environment"`` with
<environment> being the environment of the corresponding entry in the
:ref:`SpecTypeRuntimeMeasurementEnvironmentTable`.

This set of attributes specifies a runtime performance requirement. Along with
the requirement, the validation test code to execute a measure runtime request
is specified. All explicit attributes shall be specified. The explicit
attributes for this type are:

params
    The attribute value shall be a
    :ref:`SpecTypeRuntimePerformanceParameterSet`.

test-body
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It shall
    provide the code of the measure runtime body handler.  In contrast to other
    methods, this method is mandatory.

test-cleanup
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
    provide the code to clean up the measure runtime request. This method is
    called before the cleanup method of the corresponding
    :ref:`SpecTypeRuntimeMeasurementTestItemType` item and after the request.

test-prepare
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
    provide the code to prepare the measure runtime request.  This method is
    called after the prepare method of the corresponding
    :ref:`SpecTypeRuntimeMeasurementTestItemType` item and before the request.

test-setup
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
    provide the code of the measure runtime setup handler.

test-teardown
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
    provide the code of the measure runtime teardown handler.

Please have a look at the following example:

.. code-block:: yaml

    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
    copyrights:
    - Copyright (C) 2020 embedded brains GmbH & Co. KG
    enabled-by: true
    links:
    - role: runtime-measurement-request
      uid: ../val/perf
    params: {}
    rationale: null
    references: []
    test-body:
      brief: |
        Get a buffer.
      code: |
        ctx->status = rtems_partition_get_buffer( ctx->part_many, &ctx->buffer );
      description: null
    test-cleanup: null
    test-prepare: null
    test-setup: null
    test-teardown:
      brief: |
        Return the buffer.
      code: |
        rtems_status_code sc;

        T_quiet_rsc_success( ctx->status );

        sc = rtems_partition_return_buffer( ctx->part_many, ctx->buffer );
        T_quiet_rsc_success( sc );

        return tic == toc;
      description: null
    text: |
      When a partition has exactly ${../val/perf:/params/buffer-count} free
      buffers, the ${.:/limit-kind} runtime of exactly
      ${../val/perf:/params/sample-count} successful calls to
      ${../if/get-buffer:/name} in the ${.:/environment} shall be
      ${.:/limit-condition}.
    non-functional-type: performance-runtime
    requirement-type: non-functional
    type: requirement

.. _SpecTypeRequirementValidationItemType:

Requirement Validation Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``validation``. This set of attributes provides a
requirement validation evidence.  The item shall have exactly one link to the
validated requirement with the :ref:`SpecTypeRequirementValidationLinkRole`.
All explicit attributes shall be specified. The explicit attributes for this
type are:

method
    The attribute value shall be a :ref:`SpecTypeName`. It shall specify the
    requirement validation method (except validation by test).  Validation by
    test is done through :ref:`SpecTypeTestCaseItemType` items.

references
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeExternalReference`.

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

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

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

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

This type is refined by the following types:

* :ref:`SpecTypeRequirementValidationMethod`

.. _SpecTypeRequirementValidationMethod:

Requirement Validation Method
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute
  if the value is ``by-analysis``

* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute
  if the value is ``by-inspection``

* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute
  if the value is ``by-review-of-design``

.. _SpecTypeRuntimeMeasurementTestItemType:

Runtime Measurement Test Item Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``runtime-measurement-test``. This set of attributes
specifies a runtime measurement test case. All explicit attributes shall be
specified. The explicit attributes for this type are:

params
    The attribute value shall be a
    :ref:`SpecTypeRuntimeMeasurementParameterSet`.

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

test-cleanup
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
    value is present, then it shall be the measure runtime request cleanup
    method.  The method is called after each measure runtime request.

test-context
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeTestContextMember`.

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

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

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

test-local-includes
    The attribute value shall be a list of strings. It shall be a list of
    header files included via ``#include "..."``.

test-prepare
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
    value is present, then it shall be the measure runtime request prepare
    method.  The method is called before each measure runtime request.

test-setup
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
    value is present, then it shall be the test case setup fixture method.

test-stop
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
    value is present, then it shall be the test case stop fixture method.

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

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

test-teardown
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
    value is present, then it shall be the test case teardown fixture method.

.. _SpecTypeSpecificationItemType:

Specification Item Type
^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``spec``. This set of attributes specifies
specification types. All explicit attributes shall be specified. The explicit
attributes for this type are:

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

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

spec-info
    The attribute value shall be a :ref:`SpecTypeSpecificationInformation`.

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

spec-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall the
    specification type.

Please have a look at the following example:

.. code-block:: yaml

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

.. _SpecTypeTestCaseItemType:

Test Case Item Type
^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``test-case``. This set of attributes specifies a
test case. All explicit attributes shall be specified. The explicit attributes
for this type are:

test-actions
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeTestCaseAction`.

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

test-context
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeTestContextMember`.

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

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

test-header
    The attribute value shall be a :ref:`SpecTypeTestHeader`.

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

test-local-includes
    The attribute value shall be a list of strings. It shall be a list of
    header files included via ``#include "..."``.

test-setup
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.

test-stop
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.

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

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

test-teardown
    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.

.. _SpecTypeTestPlatformItemType:

Test Platform Item Type
^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``test-platform``. Please note:

.. warning::

     This item type is work in progress.

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

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

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

.. _SpecTypeTestProcedureItemType:

Test Procedure Item Type
^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeRootItemType` through the ``type``
attribute if the value is ``test-procedure``. Please note:

.. warning::

     This item type is work in progress.

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

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

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

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

.. _SpecTypeTestSuiteItemType:

Test Suite Item Type
^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is
  ``memory-benchmark``

* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is
  ``test-suite``

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

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

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

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

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

test-local-includes
    The attribute value shall be a list of strings. It shall be a list of
    header files included via ``#include "..."``.

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

.. _ReqEngSpecificationAttributeSetsAndValueTypes:

Specification Attribute Sets and Value Types
--------------------------------------------

.. _SpecTypeActionRequirementBooleanExpression:

Action Requirement Boolean Expression
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A value of this type is a boolean expression.

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

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

  and
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeActionRequirementBooleanExpression`. The *and* operator
      evaluates to the *logical and* of the evaluation results of the
      expressions in the list.

  not
      The attribute value shall be an
      :ref:`SpecTypeActionRequirementBooleanExpression`. The *not* operator
      evaluates to the *logical not* of the evaluation results of the
      expression.

  or
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeActionRequirementBooleanExpression`. The *or* operator
      evaluates to the *logical or* of the evaluation results of the
      expressions in the list.

  post-conditions
      The attribute value shall be an
      :ref:`SpecTypeActionRequirementExpressionConditionSet`. The
      *post-conditions* operator evaluates to true, if the post-condition
      states of the associated transition are contained in the specified
      post-condition set, otherwise to false.

  pre-conditions
      The attribute value shall be an
      :ref:`SpecTypeActionRequirementExpressionConditionSet`. The
      *pre-conditions* operator evaluates to true, if the pre-condition states
      of the associated transition are contained in the specified pre-condition
      set, otherwise to false.

* The value may be a list. Each list element shall be an
  :ref:`SpecTypeActionRequirementBooleanExpression`. This list of expressions
  evaluates to the *logical or* of the evaluation results of the expressions in
  the list.

This type is used by the following types:

* :ref:`SpecTypeActionRequirementBooleanExpression`

* :ref:`SpecTypeActionRequirementExpression`

.. _SpecTypeActionRequirementCondition:

Action Requirement Condition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

name
    The attribute value shall be an :ref:`SpecTypeActionRequirementName`.

states
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeActionRequirementState`.

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

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

This type is used by the following types:

* :ref:`SpecTypeActionRequirementItemType`

.. _SpecTypeActionRequirementExpression:

Action Requirement Expression
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes defines an expression which may define the state of a
post-condition.  The ``else`` and ``specified-by`` shall be used individually.
The ``if`` and ``then`` or ``then-specified-by`` expressions shall be used
together. At least one of the explicit attributes shall be specified. The
explicit attributes for this type are:

else
    The attribute value shall be an
    :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name
    of the state of the post-condition.

if
    The attribute value shall be an
    :ref:`SpecTypeActionRequirementBooleanExpression`. If the boolean
    expression evaluates to true, then the state is defined according to the
    ``then`` attribute value.

specified-by
    The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It
    shall be the name of a pre-condition.  The name of the state of the
    pre-condition in the associated transition defines the name of the state of
    the post-condition.

then
    The attribute value shall be an
    :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name
    of the state of the post-condition.

then-specified-by
    The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It
    shall be the name of a pre-condition.  The name of the state of the
    pre-condition in the associated transition defines the name of the state of
    the post-condition.

.. _SpecTypeActionRequirementExpressionConditionSet:

Action Requirement Expression Condition Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes defines for the specified conditions a set of states.
Generic attributes may be specified. Each generic attribute key shall be an
:ref:`SpecTypeActionRequirementName`. Each generic attribute value shall be an
:ref:`SpecTypeActionRequirementExpressionStateSet`. There shall be at most one
generic attribute key for each condition. The key name shall be the condition
name.  The value of each generic attribute shall be a set of states of the
condition.

This type is used by the following types:

* :ref:`SpecTypeActionRequirementBooleanExpression`

.. _SpecTypeActionRequirementExpressionStateName:

Action Requirement Expression State Name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The value shall be a string. It shall be the name of a state of the condition
or ``N/A`` if the condition is not applicable. The value

* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",

* or, shall be equal to "``N/A``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementExpression`

.. _SpecTypeActionRequirementExpressionStateSet:

Action Requirement Expression State Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a list. Each list element shall be an
  :ref:`SpecTypeActionRequirementExpressionStateName`. The list defines a set
  of states of the condition.

* The value may be a string. It shall be the name of a state of the condition
  or ``N/A`` if the condition is not applicable. The value

  * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",

  * or, shall be equal to "``N/A``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementExpressionConditionSet`

.. _SpecTypeActionRequirementName:

Action Requirement Name
^^^^^^^^^^^^^^^^^^^^^^^

The value shall be a string. It shall be the name of a condition or a state of
a condition used to define pre-conditions and post-conditions of an action
requirement.  It shall be formatted in CamelCase.  It should be brief and
abbreviated. The rationale for this is that the names are used in tables and
the horizontal space is limited by the page width.  The more conditions you
have in an action requirement, the shorter the names should be.  The name
``NA`` is reserved and indicates that a condition is not applicable. The value

* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",

* and, shall be not equal to "``NA``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementCondition`

* :ref:`SpecTypeActionRequirementExpressionConditionSet`

* :ref:`SpecTypeActionRequirementExpression`

* :ref:`SpecTypeActionRequirementSkipReasons`

* :ref:`SpecTypeActionRequirementState`

* :ref:`SpecTypeActionRequirementTransitionPostConditions`

* :ref:`SpecTypeActionRequirementTransitionPreConditions`

.. _SpecTypeActionRequirementSkipReasons:

Action Requirement Skip Reasons
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes specifies skip reasons used to justify why transitions
in the transition map are skipped. Generic attributes may be specified. Each
generic attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each
generic attribute value shall be a string. The key defines the name of a skip
reason.  The name can be used in
:ref:`SpecTypeActionRequirementTransitionPostConditions` to skip the
corresponding transitions.  The value shall give a reason why the transitions
are skipped.

This type is used by the following types:

* :ref:`SpecTypeActionRequirementItemType`

.. _SpecTypeActionRequirementState:

Action Requirement State
^^^^^^^^^^^^^^^^^^^^^^^^

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

name
    The attribute value shall be an :ref:`SpecTypeActionRequirementName`.

test-code
    The attribute value shall be a string. It shall be the test code to prepare
    or check the state of the condition.  The code may use a local variable
    ``ctx`` which points to the test context, see
    :ref:`SpecTypeTestContextMember`.

text
    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
    define the state of the condition.

This type is used by the following types:

* :ref:`SpecTypeActionRequirementCondition`

.. _SpecTypeActionRequirementTransition:

Action Requirement Transition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

post-conditions
    The attribute value shall be an
    :ref:`SpecTypeActionRequirementTransitionPostConditions`.

pre-conditions
    The attribute value shall be an
    :ref:`SpecTypeActionRequirementTransitionPreConditions`.

This type is used by the following types:

* :ref:`SpecTypeActionRequirementItemType`

.. _SpecTypeActionRequirementTransitionPostConditionState:

Action Requirement Transition Post-Condition State
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a list. Each list element shall be an
  :ref:`SpecTypeActionRequirementExpression`. The list contains expressions to
  define the state of the corresponding post-condition.

* The value may be a string. It shall be the name of a state of the
  corresponding post-condition or ``N/A`` if the post-condition is not
  applicable. The value

  * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",

  * or, shall be equal to "``N/A``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementTransitionPostConditions`

.. _SpecTypeActionRequirementTransitionPostConditions:

Action Requirement Transition Post-Conditions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a set of attributes. This set of attributes defines for each
  post-condition the state after the action for a transition in an action
  requirement. Generic attributes may be specified. Each generic attribute key
  shall be an :ref:`SpecTypeActionRequirementName`. Each generic attribute
  value shall be an
  :ref:`SpecTypeActionRequirementTransitionPostConditionState`. There shall be
  exactly one generic attribute key for each post-condition.  The key name
  shall be the post-condition name.  The value of each generic attribute shall
  be the state of the post-condition or ``N/A`` if the post-condition is not
  applicable.

* The value may be a string. It shall be the name of a skip reason.  If a skip
  reason is given instead of a listing of post-condition states, then this
  transition is skipped and no test code runs for this transition. The value

  * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",

  * and, shall be not equal to "``NA``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementTransition`

.. _SpecTypeActionRequirementTransitionPreConditionStateSet:

Action Requirement Transition Pre-Condition State Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a list. Each list element shall be an
  :ref:`SpecTypeActionRequirementName`. The list defines the set of states of
  the pre-condition in the transition.

* The value may be a string. The value ``all`` represents all states of the
  pre-condition in this transition.  The value ``N/A`` marks the pre-condition
  as not applicable in this transition. The value shall be an element of

  * "``all``", and

  * "``N/A``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementTransitionPreConditions`

.. _SpecTypeActionRequirementTransitionPreConditions:

Action Requirement Transition Pre-Conditions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a set of attributes. This set of attributes defines for each
  pre-condition the set of states before the action for a transition in an
  action requirement. Generic attributes may be specified. Each generic
  attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each generic
  attribute value shall be an
  :ref:`SpecTypeActionRequirementTransitionPreConditionStateSet`. There shall
  be exactly one generic attribute key for each pre-condition.  The key name
  shall be the pre-condition name.  The value of each generic attribute shall
  be a set of states of the pre-condition.

* The value may be a string. If this name is specified instead of explicit
  pre-condition states, then the post-condition states of this entry are used
  to define all remaining transitions of the map. The value shall be equal to
  "``default``".

This type is used by the following types:

* :ref:`SpecTypeActionRequirementTransition`

.. _SpecTypeApplicationConfigurationOptionName:

Application Configuration Option Name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeApplicationConfigurationOptionItemType`

.. _SpecTypeBooleanOrIntegerOrString:

Boolean or Integer or String
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a boolean.

* The value may be an integer number.

* The value may be a string.

This type is used by the following types:

* :ref:`SpecTypeBuildOptionAction`

* :ref:`SpecTypeInterfaceReturnValue`

.. _SpecTypeBuildAssemblerOption:

Build Assembler Option
^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildStartFileItemType`

.. _SpecTypeBuildCCompilerOption:

Build C Compiler Option
^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildBSPItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

* :ref:`SpecTypeBuildOptionCCompilerCheckAction`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildCPreprocessorOption:

Build C Preprocessor Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildBSPItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildStartFileItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildCXXCompilerOption:

Build C++ Compiler Option
^^^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

* :ref:`SpecTypeBuildOptionCXXCompilerCheckAction`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildDependencyConditionalLinkRole:

Build Dependency Conditional Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``build-dependency-conditional``. It defines the build dependency
conditional role of links. All explicit attributes shall be specified. The
explicit attributes for this type are:

enabled-by
    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It
    shall define under which conditions the build dependency is enabled.

.. _SpecTypeBuildDependencyLinkRole:

Build Dependency Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``build-dependency``. It defines the build dependency role of links.

.. _SpecTypeBuildIncludePath:

Build Include Path
^^^^^^^^^^^^^^^^^^

The value shall be a string. It shall be a path to header files.  The path is
used by the C preprocessor to search for header files.  It succeeds the
includes presented to the item by the build item context.  For an
:ref:`SpecTypeBuildGroupItemType` item the includes are visible to all items
referenced by the group item.  For :ref:`SpecTypeBuildBSPItemType`,
:ref:`SpecTypeBuildObjectsItemType`, :ref:`SpecTypeBuildLibraryItemType`,
:ref:`SpecTypeBuildStartFileItemType`, and
:ref:`SpecTypeBuildTestProgramItemType` items the includes are only visible to
the sources specified by the item itself and they do not propagate to
referenced items.

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildBSPItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildStartFileItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildInstallDirective:

Build Install Directive
^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

This type is used by the following types:

* :ref:`SpecTypeBuildBSPItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

.. _SpecTypeBuildInstallPath:

Build Install Path
^^^^^^^^^^^^^^^^^^

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

* There may be no value (null).

* The value may be a string. It shall be the installation path of a
  :ref:`SpecTypeBuildTarget`.

This type is used by the following types:

* :ref:`SpecTypeBuildConfigurationFileItemType`

* :ref:`SpecTypeBuildConfigurationHeaderItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildStartFileItemType`

.. _SpecTypeBuildLinkStaticLibraryDirective:

Build Link Static Library Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The value shall be a string. It shall be an external static library identifier.
The library is used to link programs referenced by this item, e.g. ``m`` for
``libm.a``.  The library is added to the build command through the ``stlib``
attribute. It shall not be used for internal static libraries.  Internal static
libraries shall be specified through the ``use-after`` and ``use-before``
attributes to enable a proper build dependency tracking.

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildLinkerOption:

Build Linker Option
^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildOptionAction:

Build Option Action
^^^^^^^^^^^^^^^^^^^

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

append-test-cppflags
    The attribute value shall be a string. It shall be the name of a test
    program.  The action appends the action value to the ``CPPFLAGS`` of the
    test program.  The name shall correspond to the name of a
    :ref:`SpecTypeBuildTestProgramItemType` item. Due to the processing order
    of items, there is no way to check if the name specified by the attribute
    value is valid.

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

assert-eq
    The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. The
    action asserts that the action value is equal to the attribute value.

assert-ge
    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
    asserts that the action value is greater than or equal to the attribute
    value.

assert-gt
    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
    asserts that the action value is greater than the attribute value.

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

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

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

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

assert-le
    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
    asserts that the action value is less than or equal to the attribute value.

assert-lt
    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
    asserts that the action value is less than the attribute value.

assert-ne
    The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. The
    action asserts that the action value is not equal to the attribute value.

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

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

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

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

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

check-cc
    The attribute value shall be a
    :ref:`SpecTypeBuildOptionCCompilerCheckAction`.

check-cxx
    The attribute value shall be a
    :ref:`SpecTypeBuildOptionCXXCompilerCheckAction`.

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

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

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

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

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

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

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

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

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

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

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

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

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

get-string-command-line
    The attribute value shall be a string. The action gets the action value for
    subsequent actions from the value of a command line option named by the
    items ``name`` attribute. If no such command line option is present, then
    the attribute value is used.  The value is converted to a string.

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

set-test-state
    The attribute value shall be a
    :ref:`SpecTypeBuildOptionSetTestStateAction`.

set-value
    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. The action
    sets the action value for subsequent actions to the attribute value.

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

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

This type is used by the following types:

* :ref:`SpecTypeBuildOptionItemType`

.. _SpecTypeBuildOptionCCompilerCheckAction:

Build Option C Compiler Check Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

cflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCCompilerOption`.

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

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

This type is used by the following types:

* :ref:`SpecTypeBuildOptionAction`

.. _SpecTypeBuildOptionCXXCompilerCheckAction:

Build Option C++ Compiler Check Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

cxxflags
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeBuildCXXCompilerOption`.

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

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

This type is used by the following types:

* :ref:`SpecTypeBuildOptionAction`

.. _SpecTypeBuildOptionDefaultValue:

Build Option Default Value
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

enabled-by
    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`.

value
    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. Its value
    shall be the default value for the associated enabled-by expression.

This type is used by the following types:

* :ref:`SpecTypeBuildOptionItemType`

.. _SpecTypeBuildOptionName:

Build Option Name
^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildOptionItemType`

.. _SpecTypeBuildOptionSetTestStateAction:

Build Option Set Test State Action
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes specifies the test state for a set of test programs with
an optional reason. All explicit attributes shall be specified. The explicit
attributes for this type are:

reason
    The attribute value shall be an optional string. If the value is present,
    then it shall be the reason for the test state definition.

state
    The attribute value shall be a :ref:`SpecTypeBuildTestState`. It shall be
    the test state for the associated list of tests.

tests
    The attribute value shall be a list of strings. It shall be the list of
    test program names associated with the test state.  The names shall
    correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType` or
    :ref:`SpecTypeBuildAdaTestProgramItemType` item.  Due to the processing
    order of items, there is no way to check if a specified test program name
    is valid.

This type is used by the following types:

* :ref:`SpecTypeBuildOptionAction`

.. _SpecTypeBuildOptionValue:

Build Option Value
^^^^^^^^^^^^^^^^^^

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

* The value may be a boolean.

* The value may be an integer number.

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

* There may be no value (null).

* The value may be a string.

This type is used by the following types:

* :ref:`SpecTypeBuildOptionAction`

* :ref:`SpecTypeBuildOptionDefaultValue`

.. _SpecTypeBuildSource:

Build Source
^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildBSPItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildObjectsItemType`

* :ref:`SpecTypeBuildStartFileItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildTarget:

Build Target
^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildConfigurationFileItemType`

* :ref:`SpecTypeBuildConfigurationHeaderItemType`

* :ref:`SpecTypeBuildLibraryItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildStartFileItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildTestState:

Build Test State
^^^^^^^^^^^^^^^^

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

* "``benchmark``",

* "``exclude``",

* "``expected-fail``",

* "``indeterminate``", and

* "``user-input``".

This type is used by the following types:

* :ref:`SpecTypeBuildOptionSetTestStateAction`

.. _SpecTypeBuildUseAfterDirective:

Build Use After Directive
^^^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeBuildUseBeforeDirective:

Build Use Before Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeBuildAdaTestProgramItemType`

* :ref:`SpecTypeBuildGroupItemType`

* :ref:`SpecTypeBuildScriptItemType`

* :ref:`SpecTypeBuildTestProgramItemType`

.. _SpecTypeConstraintLinkRole:

Constraint Link Role
^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``constraint``. It defines the constraint role of links.  The link
target shall be a constraint.

.. _SpecTypeCopyright:

Copyright
^^^^^^^^^

The value shall be a string. It shall be a copyright statement of a copyright
holder of the specification item. The value

* shall match with the regular expression
  "``^\s*Copyright\s+\(C\)\s+[0-9]+,\s*[0-9]+\s+.+\s*$``",

* or, shall match with the regular expression
  "``^\s*Copyright\s+\(C\)\s+[0-9]+\s+.+\s*$``",

* or, shall match with the regular expression
  "``^\s*Copyright\s+\(C\)\s+.+\s*$``".

This type is used by the following types:

* :ref:`SpecTypeRootItemType`

.. _SpecTypeEnabledByExpression:

Enabled-By Expression
^^^^^^^^^^^^^^^^^^^^^

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

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

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

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

  and
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeEnabledByExpression`. The *and* operator evaluates to the
      *logical and* of the evaluation results of the expressions in the list.

  not
      The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. The
      *not* operator evaluates to the *logical not* of the evaluation results
      of the expression.

  or
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeEnabledByExpression`. The *or* operator evaluates to the
      *logical or* of the evaluation results of the expressions in the list.

* The value may be a list. Each list element shall be an
  :ref:`SpecTypeEnabledByExpression`. This list of expressions evaluates to the
  *logical or* of the evaluation results of the expressions in the list.

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

This type is used by the following types:

* :ref:`SpecTypeActionRequirementTransition`

* :ref:`SpecTypeBuildDependencyConditionalLinkRole`

* :ref:`SpecTypeBuildOptionDefaultValue`

* :ref:`SpecTypeEnabledByExpression`

* :ref:`SpecTypeInterfaceIncludeLinkRole`

* :ref:`SpecTypeRootItemType`

Please have a look at the following example:

.. code-block:: yaml

    enabled-by:
      and:
      - RTEMS_NETWORKING
      - not: RTEMS_SMP

.. _SpecTypeExternalDocumentReference:

External Document Reference
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeExternalReference` through the ``type``
attribute if the value is ``document``. It specifies a reference to a document.

All explicit attributes shall be specified. The explicit attributes for this
type are:

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

.. _SpecTypeExternalFileReference:

External File Reference
^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeExternalReference` through the ``type``
attribute if the value is ``file``. It specifies a reference to a file.

All explicit attributes shall be specified. The explicit attributes for this
type are:

hash
    The attribute value shall be a :ref:`SpecTypeSHA256HashValue`. It shall be
    the SHA256 hash value of the content of the referenced file.

.. _SpecTypeExternalReference:

External Reference
^^^^^^^^^^^^^^^^^^

This set of attributes specifies a reference to some object external to the
specification. All explicit attributes shall be specified. The explicit
attributes for this type are:

identifier
    The attribute value shall be a string. It shall be the type-specific
    identifier of the referenced object. For *group* references use the Doxygen
    group identifier.  For *file* references use a file system path to the
    file.

type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the type of
    the referenced object.

This type is refined by the following types:

* :ref:`SpecTypeExternalDocumentReference`

* :ref:`SpecTypeExternalFileReference`

* :ref:`SpecTypeGenericExternalReference`

This type is used by the following types:

* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType`

* :ref:`SpecTypeInterfaceUnspecifiedItemType`

* :ref:`SpecTypeRequirementItemType`

* :ref:`SpecTypeRequirementValidationItemType`

.. _SpecTypeFunctionImplementationLinkRole:

Function Implementation Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``function-implementation``. It defines the function implementation
role of links.  It is used to indicate that a
:ref:`SpecTypeFunctionalRequirementItemType` item specifies parts of the
function.

.. _SpecTypeGenericExternalReference:

Generic External Reference
^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
  is ``define``

* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
  is ``function``

* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
  is ``group``

* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
  is ``macro``

* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
  is ``url``

* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value
  is ``variable``

It specifies a reference to an object of the specified type.

.. _SpecTypeGlossaryMembershipLinkRole:

Glossary Membership Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``glossary-member``. It defines the glossary membership role of links.

.. _SpecTypeIntegerOrString:

Integer or String
^^^^^^^^^^^^^^^^^

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

* The value may be an integer number.

* The value may be a string.

This type is used by the following types:

* :ref:`SpecTypeApplicationConfigurationValueOptionItemType`

* :ref:`SpecTypeBuildOptionAction`

.. _SpecTypeInterfaceBriefDescription:

Interface Brief Description
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* There may be no value (null).

* The value may be a string. It shall be the brief description of the
  interface.  It should be a single sentence. The value shall not match with
  the regular expression "``\n\n``".

This type is used by the following types:

* :ref:`SpecTypeInterfaceCompoundItemType`

* :ref:`SpecTypeInterfaceCompoundMemberDefinition`

* :ref:`SpecTypeInterfaceDefineItemType`

* :ref:`SpecTypeInterfaceEnumItemType`

* :ref:`SpecTypeInterfaceEnumeratorItemType`

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

* :ref:`SpecTypeInterfaceGroupItemType`

* :ref:`SpecTypeInterfaceHeaderFileItemType`

* :ref:`SpecTypeInterfaceTypedefItemType`

* :ref:`SpecTypeInterfaceVariableItemType`

* :ref:`SpecTypeRegisterBitsDefinition`

* :ref:`SpecTypeRegisterBlockItemType`

* :ref:`SpecTypeRegisterDefinition`

.. _SpecTypeInterfaceCompoundDefinitionKind:

Interface Compound Definition Kind
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* "``struct-only``",

* "``typedef-and-struct``",

* "``typedef-and-union``",

* "``typedef-only``", and

* "``union-only``".

This type is used by the following types:

* :ref:`SpecTypeInterfaceCompoundItemType`

.. _SpecTypeInterfaceCompoundMemberCompound:

Interface Compound Member Compound
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the following types:

* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind``
  attribute if the value is ``struct``

* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind``
  attribute if the value is ``union``

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

definition
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`.

.. _SpecTypeInterfaceCompoundMemberDeclaration:

Interface Compound Member Declaration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeInterfaceCompoundMemberDefinition` through
the ``kind`` attribute if the value is ``member``. This set of attributes
specifies an interface compound member declaration. All explicit attributes
shall be specified. The explicit attributes for this type are:

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

.. _SpecTypeInterfaceCompoundMemberDefinition:

Interface Compound Member Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

  brief
      The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

  description
      The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

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

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

* There may be no value (null).

This type is refined by the following types:

* :ref:`SpecTypeInterfaceCompoundMemberCompound`

* :ref:`SpecTypeInterfaceCompoundMemberDeclaration`

This type is used by the following types:

* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`

* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`

.. _SpecTypeInterfaceCompoundMemberDefinitionDirective:

Interface Compound Member Definition Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

default
    The attribute value shall be an
    :ref:`SpecTypeInterfaceCompoundMemberDefinition`. The default definition
    will be used if no variant-specific definition is enabled.

variants
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`.

This type is used by the following types:

* :ref:`SpecTypeInterfaceCompoundItemType`

* :ref:`SpecTypeInterfaceCompoundMemberCompound`

.. _SpecTypeInterfaceCompoundMemberDefinitionVariant:

Interface Compound Member Definition Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

enabled-by
    The attribute value shall be an
    :ref:`SpecTypeInterfaceEnabledByExpression`.

This type is used by the following types:

* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`

.. _SpecTypeInterfaceDefinition:

Interface Definition
^^^^^^^^^^^^^^^^^^^^

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

* There may be no value (null).

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

This type is used by the following types:

* :ref:`SpecTypeInterfaceDefinitionDirective`

* :ref:`SpecTypeInterfaceDefinitionVariant`

.. _SpecTypeInterfaceDefinitionDirective:

Interface Definition Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

default
    The attribute value shall be an :ref:`SpecTypeInterfaceDefinition`. The
    default definition will be used if no variant-specific definition is
    enabled.

variants
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceDefinitionVariant`.

This type is used by the following types:

* :ref:`SpecTypeInterfaceDefineItemType`

* :ref:`SpecTypeInterfaceEnumeratorItemType`

* :ref:`SpecTypeInterfaceTypedefItemType`

* :ref:`SpecTypeInterfaceVariableItemType`

.. _SpecTypeInterfaceDefinitionVariant:

Interface Definition Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

enabled-by
    The attribute value shall be an
    :ref:`SpecTypeInterfaceEnabledByExpression`.

This type is used by the following types:

* :ref:`SpecTypeInterfaceDefinitionDirective`

.. _SpecTypeInterfaceDescription:

Interface Description
^^^^^^^^^^^^^^^^^^^^^

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

* There may be no value (null).

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

This type is used by the following types:

* :ref:`SpecTypeApplicationConfigurationOptionItemType`

* :ref:`SpecTypeInterfaceCompoundItemType`

* :ref:`SpecTypeInterfaceCompoundMemberDefinition`

* :ref:`SpecTypeInterfaceDefineItemType`

* :ref:`SpecTypeInterfaceEnumItemType`

* :ref:`SpecTypeInterfaceEnumeratorItemType`

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

* :ref:`SpecTypeInterfaceGroupItemType`

* :ref:`SpecTypeInterfaceParameter`

* :ref:`SpecTypeInterfaceReturnValue`

* :ref:`SpecTypeInterfaceTypedefItemType`

* :ref:`SpecTypeInterfaceVariableItemType`

* :ref:`SpecTypeRegisterBitsDefinition`

* :ref:`SpecTypeRegisterBlockItemType`

* :ref:`SpecTypeRegisterDefinition`

.. _SpecTypeInterfaceEnabledByExpression:

Interface Enabled-By Expression
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

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

  and
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeInterfaceEnabledByExpression`. The *and* operator defines a
      *logical and* of the expressions in the list.

  not
      The attribute value shall be an
      :ref:`SpecTypeInterfaceEnabledByExpression`. The *not* operator defines a
      *logical not* of the expression.

  or
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeInterfaceEnabledByExpression`. The *or* operator defines a
      *logical or* of the expressions in the list.

* The value may be a list. Each list element shall be an
  :ref:`SpecTypeInterfaceEnabledByExpression`. It defines a *logical or* of the
  expressions in the list.

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

This type is used by the following types:

* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`

* :ref:`SpecTypeInterfaceDefinitionVariant`

* :ref:`SpecTypeInterfaceEnabledByExpression`

* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`

* :ref:`SpecTypeRegisterBitsDefinitionVariant`

* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`

.. _SpecTypeInterfaceEnumDefinitionKind:

Interface Enum Definition Kind
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* "``enum-only``",

* "``typedef-and-enum``", and

* "``typedef-only``".

This type is used by the following types:

* :ref:`SpecTypeInterfaceEnumItemType`

.. _SpecTypeInterfaceEnumeratorLinkRole:

Interface Enumerator Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-enumerator``. It defines the interface enumerator role of
links.

.. _SpecTypeInterfaceFunctionLinkRole:

Interface Function Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-function``. It defines the interface function role of
links.  It is used to indicate that a :ref:`SpecTypeActionRequirementItemType`
item specifies functional requirements of an
:ref:`SpecTypeInterfaceFunctionOrMacroItemType` item.

.. _SpecTypeInterfaceFunctionOrMacroDefinition:

Interface Function or Macro Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

  attributes
      The attribute value shall be an optional string. If the value is present,
      then it shall be the function attributes. On the attributes a
      context-sensitive substitution of item variables is performed.  A
      function attribute is for example the indication that the function does
      not return to the caller.

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

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

  return
      The attribute value shall be an optional string. If the value is present,
      then it shall be the function return type. On the return type a
      context-sensitive substitution of item variables is performed.

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`

* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`

.. _SpecTypeInterfaceFunctionOrMacroDefinitionDirective:

Interface Function or Macro Definition Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

default
    The attribute value shall be an
    :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The default definition
    will be used if no variant-specific definition is enabled.

variants
    The attribute value shall be a list. Each list element shall be an
    :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`.

This type is used by the following types:

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

.. _SpecTypeInterfaceFunctionOrMacroDefinitionVariant:

Interface Function or Macro Definition Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

enabled-by
    The attribute value shall be an
    :ref:`SpecTypeInterfaceEnabledByExpression`.

This type is used by the following types:

* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`

.. _SpecTypeInterfaceGroupIdentifier:

Interface Group Identifier
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

This type is used by the following types:

* :ref:`SpecTypeInterfaceGroupItemType`

* :ref:`SpecTypeRegisterBlockItemType`

.. _SpecTypeInterfaceGroupMembershipLinkRole:

Interface Group Membership Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-ingroup``. It defines the interface group membership role
of links.

.. _SpecTypeInterfaceHiddenGroupMembershipLinkRole:

Interface Hidden Group Membership Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-ingroup-hidden``. It defines the interface hidden group
membership role of links.  This role may be used to make an interface a group
member and hide this relationship in the documentation.  An example is an
optimized macro implementation of a directive which has the same name as the
corresponding directive.

.. _SpecTypeInterfaceIncludeLinkRole:

Interface Include Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-include``. It defines the interface include role of links
and is used to indicate that an interface container includes another interface
container.  For example, one header file includes another header file. All
explicit attributes shall be specified. The explicit attributes for this type
are:

enabled-by
    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It
    shall define under which conditions the interface container is included.

.. _SpecTypeInterfaceNotes:

Interface Notes
^^^^^^^^^^^^^^^

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

* There may be no value (null).

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

This type is used by the following types:

* :ref:`SpecTypeApplicationConfigurationOptionItemType`

* :ref:`SpecTypeInterfaceCompoundItemType`

* :ref:`SpecTypeInterfaceDefineItemType`

* :ref:`SpecTypeInterfaceEnumeratorItemType`

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

* :ref:`SpecTypeInterfaceTypedefItemType`

* :ref:`SpecTypeInterfaceVariableItemType`

* :ref:`SpecTypeRegisterBlockItemType`

.. _SpecTypeInterfaceParameter:

Interface Parameter
^^^^^^^^^^^^^^^^^^^

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

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

dir
    The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`.

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

This type is used by the following types:

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

* :ref:`SpecTypeInterfaceTypedefItemType`

.. _SpecTypeInterfaceParameterDirection:

Interface Parameter Direction
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* There may be no value (null).

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

  * "``in``",

  * "``out``", and

  * "``inout``".

This type is used by the following types:

* :ref:`SpecTypeInterfaceParameter`

* :ref:`SpecTypeTestRunParameter`

.. _SpecTypeInterfacePlacementLinkRole:

Interface Placement Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-placement``. It defines the interface placement role of
links.  It is used to indicate that an interface definition is placed into an
interface container, for example a header file.

.. _SpecTypeInterfaceReturnDirective:

Interface Return Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

  return-values
      The attribute value shall be a list. Each list element shall be an
      :ref:`SpecTypeInterfaceReturnValue`.

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`

* :ref:`SpecTypeInterfaceTypedefItemType`

.. _SpecTypeInterfaceReturnValue:

Interface Return Value
^^^^^^^^^^^^^^^^^^^^^^

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

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

value
    The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. It
    shall be the described interface return value.

This type is used by the following types:

* :ref:`SpecTypeInterfaceReturnDirective`

.. _SpecTypeInterfaceTargetLinkRole:

Interface Target Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``interface-target``. It defines the interface target role of links.
It is used for interface forward declarations.

.. _SpecTypeLink:

Link
^^^^

This set of attributes specifies a link from one specification item to another
specification item.  The links in a list are ordered.  The first link in the
list is processed first. All explicit attributes shall be specified. The
explicit attributes for this type are:

role
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the role of
    the link.

uid
    The attribute value shall be an :ref:`SpecTypeUID`. It shall be the
    absolute or relative UID of the link target item.

This type is refined by the following types:

* :ref:`SpecTypeBuildDependencyConditionalLinkRole`

* :ref:`SpecTypeBuildDependencyLinkRole`

* :ref:`SpecTypeConstraintLinkRole`

* :ref:`SpecTypeFunctionImplementationLinkRole`

* :ref:`SpecTypeGlossaryMembershipLinkRole`

* :ref:`SpecTypeInterfaceEnumeratorLinkRole`

* :ref:`SpecTypeInterfaceFunctionLinkRole`

* :ref:`SpecTypeInterfaceGroupMembershipLinkRole`

* :ref:`SpecTypeInterfaceHiddenGroupMembershipLinkRole`

* :ref:`SpecTypeInterfaceIncludeLinkRole`

* :ref:`SpecTypeInterfacePlacementLinkRole`

* :ref:`SpecTypeInterfaceTargetLinkRole`

* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole`

* :ref:`SpecTypePlacementOrderLinkRole`

* :ref:`SpecTypeProxyMemberLinkRole`

* :ref:`SpecTypeRegisterBlockIncludeRole`

* :ref:`SpecTypeRequirementRefinementLinkRole`

* :ref:`SpecTypeRequirementValidationLinkRole`

* :ref:`SpecTypeRuntimeMeasurementRequestLinkRole`

* :ref:`SpecTypeSpecificationMemberLinkRole`

* :ref:`SpecTypeSpecificationRefinementLinkRole`

* :ref:`SpecTypeUnitTestLinkRole`

This type is used by the following types:

* :ref:`SpecTypeRootItemType`

* :ref:`SpecTypeTestCaseAction`

* :ref:`SpecTypeTestCaseCheck`

.. _SpecTypeName:

Name
^^^^

The value shall be a string. A string is a valid name if it matches with the
``^([a-z][a-z0-9-]*|SPDX-License-Identifier)$`` regular expression.

This type is used by the following types:

* :ref:`SpecTypeApplicationConfigurationOptionItemType`

* :ref:`SpecTypeBuildItemType`

* :ref:`SpecTypeExternalReference`

* :ref:`SpecTypeFunctionalRequirementItemType`

* :ref:`SpecTypeGlossaryItemType`

* :ref:`SpecTypeInterfaceItemType`

* :ref:`SpecTypeLink`

* :ref:`SpecTypeNonFunctionalRequirementItemType`

* :ref:`SpecTypeRegisterDefinition`

* :ref:`SpecTypeRequirementItemType`

* :ref:`SpecTypeRequirementValidationItemType`

* :ref:`SpecTypeRootItemType`

* :ref:`SpecTypeRuntimeMeasurementParameterSet`

* :ref:`SpecTypeRuntimePerformanceParameterSet`

* :ref:`SpecTypeSpecificationAttributeValue`

* :ref:`SpecTypeSpecificationExplicitAttributes`

* :ref:`SpecTypeSpecificationGenericAttributes`

* :ref:`SpecTypeSpecificationItemType`

* :ref:`SpecTypeSpecificationList`

* :ref:`SpecTypeSpecificationRefinementLinkRole`

.. _SpecTypeOptionalFloatingPointNumber:

Optional Floating-Point Number
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a floating-point number.

* There may be no value (null).

.. _SpecTypeOptionalInteger:

Optional Integer
^^^^^^^^^^^^^^^^

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

* The value may be an integer number.

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeRegisterBlockItemType`

.. _SpecTypeOptionalString:

Optional String
^^^^^^^^^^^^^^^

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

* There may be no value (null).

* The value may be a string.

.. _SpecTypePerformanceRuntimeLimitsLinkRole:

Performance Runtime Limits Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``performance-runtime-limits``. It defines the performance runtime
limits role of links. All explicit attributes shall be specified. The explicit
attributes for this type are:

limits
    The attribute value shall be a
    :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`.

.. _SpecTypePlacementOrderLinkRole:

Placement Order Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``placement-order``. This link role defines the placement order of
items in a container item (for example an interface function in a header file
or a documentation section).

.. _SpecTypeProxyMemberLinkRole:

Proxy Member Link Role
^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``proxy-member``. It defines the proxy member role of links.  Items
may use this role to link to :ref:`SpecTypeProxyItemTypes` items.

.. _SpecTypeRegisterBitsDefinition:

Register Bits Definition
^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a set of attributes. This set of attributes specifies a
  register bit field.  Single bits are bit fields with a width of one. All
  explicit attributes shall be specified. The explicit attributes for this type
  are:

  brief
      The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

  description
      The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

  name
      The attribute value shall be a string. It shall be the name of the
      register bit field.

  properties
      The attribute value shall be a list of strings. It shall be the list of
      bit field properties.  Properties are for example if the bit field can be
      read or written, or an access has side-effects such as clearing a status.

  start
      The attribute value shall be an integer number. It shall be the start bit
      of the bit field.  Bit ``0`` is the least-significant bit.

  width
      The attribute value shall be an integer number. It shall be the width in
      bits of the bit field.

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeRegisterBitsDefinitionDirective`

* :ref:`SpecTypeRegisterBitsDefinitionVariant`

.. _SpecTypeRegisterBitsDefinitionDirective:

Register Bits Definition Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

default
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterBitsDefinition`. The default definition will be used
    if no variant-specific definition is enabled.

variants
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterBitsDefinitionVariant`.

This type is used by the following types:

* :ref:`SpecTypeRegisterDefinition`

.. _SpecTypeRegisterBitsDefinitionVariant:

Register Bits Definition Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

definition
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterBitsDefinition`. The definition will be used if the
    expression defined by the ``enabled-by`` attribute evaluates to true.  In
    generated header files, the expression is evaluated by the C preprocessor.

enabled-by
    The attribute value shall be an
    :ref:`SpecTypeInterfaceEnabledByExpression`.

This type is used by the following types:

* :ref:`SpecTypeRegisterBitsDefinitionDirective`

.. _SpecTypeRegisterBlockIncludeRole:

Register Block Include Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``register-block-include``. It defines the register block include role
of links.  Links of this role are used to build register blocks using other
register blocks. All explicit attributes shall be specified. The explicit
attributes for this type are:

name
    The attribute value shall be a string. It shall be a name to identify the
    included register block within the item.  The name shall be unique within
    the scope of the item links of this role and the
    :ref:`SpecTypeRegisterList`.

.. _SpecTypeRegisterBlockMemberDefinition:

Register Block Member Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* The value may be a set of attributes. This set of attributes specifies a
  register block member definition. All explicit attributes shall be specified.
  The explicit attributes for this type are:

  count
      The attribute value shall be an integer number. It shall be the count of
      registers of the register block member.

  name
      The attribute value shall be a :ref:`SpecTypeRegisterName`.

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`

* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`

.. _SpecTypeRegisterBlockMemberDefinitionDirective:

Register Block Member Definition Directive
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

default
    The attribute value shall be a
    :ref:`SpecTypeRegisterBlockMemberDefinition`. The default definition will
    be used if no variant-specific definition is enabled.

offset
    The attribute value shall be an integer number. It shall be the address of
    the register block member relative to the base address of the register
    block.

variants
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`.

This type is used by the following types:

* :ref:`SpecTypeRegisterBlockItemType`

.. _SpecTypeRegisterBlockMemberDefinitionVariant:

Register Block Member Definition Variant
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

definition
    The attribute value shall be a
    :ref:`SpecTypeRegisterBlockMemberDefinition`. The definition will be used
    if the expression defined by the ``enabled-by`` attribute evaluates to
    true.  In generated header files, the expression is evaluated by the C
    preprocessor.

enabled-by
    The attribute value shall be an
    :ref:`SpecTypeInterfaceEnabledByExpression`.

This type is used by the following types:

* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`

.. _SpecTypeRegisterDefinition:

Register Definition
^^^^^^^^^^^^^^^^^^^

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

bits
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeRegisterBitsDefinitionDirective`.

brief
    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.

description
    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.

name
    The attribute value shall be a string. It shall be the name to identify the
    register definition.  The name shall be unique within the scope of the
    :ref:`SpecTypeRegisterBlockIncludeRole` links of the item and the
    :ref:`SpecTypeRegisterList`.

width
    The attribute value shall be an integer number. It shall be the width of
    the register in bits.

In addition to the explicit attributes, generic attributes may be specified.
Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value
may have any type.

This type is used by the following types:

* :ref:`SpecTypeRegisterBlockItemType`

.. _SpecTypeRegisterName:

Register Name
^^^^^^^^^^^^^

The value shall be a string. The name consists either of an identifier, or an
identifier and an alias. The identifier and alias are separated by a colon
(``:``).  The identifier shall match with the name of a register definition of
the item (see :ref:`SpecTypeRegisterDefinition`) or the name of a register
block include of the item (see :ref:`SpecTypeRegisterBlockIncludeRole`).  If no
alias is specified, then the identifier is used for the register block member
name, otherwise the alias is used.  If the register block member names are not
unique within the item, then a postfix number is appended to the names.  The
number starts with zero for each set of names. The value shall match with the
regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*(:[a-zA-Z_][a-zA-Z0-9_]*)?$``".

This type is used by the following types:

* :ref:`SpecTypeRegisterBlockMemberDefinition`

.. _SpecTypeRequirementDesignGroupIdentifier:

Requirement Design Group Identifier
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* There may be no value (null).

* The value may be a string. It shall be the identifier of the requirement
  design group. The value shall match with the regular expression
  "``^[a-zA-Z0-9_]*$``".

This type is used by the following types:

* :ref:`SpecTypeDesignGroupRequirementItemType`

.. _SpecTypeRequirementRefinementLinkRole:

Requirement Refinement Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``requirement-refinement``. It defines the requirement refinement role
of links.

.. _SpecTypeRequirementText:

Requirement Text
^^^^^^^^^^^^^^^^

The value shall be a string. It shall state a requirement or constraint.  The
text should not use one of the following words or phrases:

* acceptable

* adequate

* almost always

* and/or

* appropriate

* approximately

* as far as possible

* as much as practicable

* best

* best possible

* easy

* efficient

* e.g.

* enable

* enough

* etc.

* few

* first rate

* flexible

* generally

* goal

* graceful

* great

* greatest

* ideally

* i.e.

* if possible

* in most cases

* large

* many

* maximize

* minimize

* most

* multiple

* necessary

* numerous

* optimize

* ought to

* probably

* quick

* rapid

* reasonably

* relevant

* robust

* satisfactory

* several

* shall be included but not limited to

* simple

* small

* some

* state of the art

* sufficient

* suitable

* support

* systematically

* transparent

* typical

* user friendly

* usually

* versatile

* when necessary

This type is used by the following types:

* :ref:`SpecTypeActionRequirementState`

* :ref:`SpecTypeApplicationConfigurationGroupItemType`

* :ref:`SpecTypeConstraintItemType`

* :ref:`SpecTypeInterfaceGroupItemType`

* :ref:`SpecTypeRequirementItemType`

.. _SpecTypeRequirementValidationLinkRole:

Requirement Validation Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``validation``. It defines the requirement validation role of links.

.. _SpecTypeRuntimeMeasurementEnvironmentName:

Runtime Measurement Environment Name
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The value shall be a string. It specifies the runtime measurement environment
name. The value

* shall be an element of

  * "``FullCache``",

  * "``HotCache``", and

  * "``DirtyCache``",

* or, shall match with the regular expression "``^Load/[1-9][0-9]*$``".

This type is used by the following types:

* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`

.. _SpecTypeRuntimeMeasurementEnvironmentTable:

Runtime Measurement Environment Table
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes provides runtime performance limits for a set of runtime
measurement environments. Generic attributes may be specified. Each generic
attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. Each
generic attribute value shall be a :ref:`SpecTypeRuntimeMeasurementValueTable`.

This type is used by the following types:

* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole`

.. _SpecTypeRuntimeMeasurementParameterSet:

Runtime Measurement Parameter Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes defines parameters of the runtime measurement test case.
All explicit attributes shall be specified. The explicit attributes for this
type are:

sample-count
    The attribute value shall be an integer number. It shall be the sample
    count of the runtime measurement context.

In addition to the explicit attributes, generic attributes may be specified.
Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value
may have any type.

This type is used by the following types:

* :ref:`SpecTypeRuntimeMeasurementTestItemType`

.. _SpecTypeRuntimeMeasurementRequestLinkRole:

Runtime Measurement Request Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``runtime-measurement-request``. It defines the runtime measurement
request role of links.  The link target shall be a
:ref:`SpecTypeRuntimeMeasurementTestItemType` item.

.. _SpecTypeRuntimeMeasurementValueKind:

Runtime Measurement Value Kind
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The value shall be a string. It specifies the kind of a runtime measurement
value. The value shall be an element of

* "``max-lower-bound``",

* "``max-upper-bound``",

* "``mean-lower-bound``",

* "``mean-upper-bound``",

* "``median-lower-bound``",

* "``median-upper-bound``",

* "``min-lower-bound``", and

* "``min-upper-bound``".

This type is used by the following types:

* :ref:`SpecTypeRuntimeMeasurementValueTable`

.. _SpecTypeRuntimeMeasurementValueTable:

Runtime Measurement Value Table
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes provides a set of runtime measurement values each of a
specified kind.  The unit of the values shall be one second. Generic attributes
may be specified. Each generic attribute key shall be a
:ref:`SpecTypeRuntimeMeasurementValueKind`. Each generic attribute value shall
be a floating-point number.

This type is used by the following types:

* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`

.. _SpecTypeRuntimePerformanceParameterSet:

Runtime Performance Parameter Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This set of attributes defines parameters of the runtime performance
requirement. Generic attributes may be specified. Each generic attribute key
shall be a :ref:`SpecTypeName`. The attribute value may have any type.

This type is used by the following types:

* :ref:`SpecTypeRuntimePerformanceRequirementItemType`

.. _SpecTypeSHA256HashValue:

SHA256 Hash Value
^^^^^^^^^^^^^^^^^

The value shall be a string. It shall be a SHA256 hash value encoded in
base64url. The value shall match with the regular expression
"``^[A-Za-z0-9+_=-]{44}$``".

This type is used by the following types:

* :ref:`SpecTypeExternalFileReference`

.. _SpecTypeSPDXLicenseIdentifier:

SPDX License Identifier
^^^^^^^^^^^^^^^^^^^^^^^

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

* shall be equal to "``CC-BY-SA-4.0 OR BSD-2-Clause``",

* or, shall be equal to "``BSD-2-Clause``",

* or, shall be equal to "``CC-BY-SA-4.0``".

This type is used by the following types:

* :ref:`SpecTypeRootItemType`

.. _SpecTypeSpecificationAttributeSet:

Specification Attribute Set
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

* ``attributes``

* ``description``

* ``mandatory-attributes``

The explicit attributes for this type are:

attributes
    The attribute value shall be a
    :ref:`SpecTypeSpecificationExplicitAttributes`. It shall specify the
    explicit attributes of the attribute set.

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

generic-attributes
    The attribute value shall be a
    :ref:`SpecTypeSpecificationGenericAttributes`. It shall specify the generic
    attributes of the attribute set.

mandatory-attributes
    The attribute value shall be a
    :ref:`SpecTypeSpecificationMandatoryAttributes`. It shall specify the
    mandatory attributes of the attribute set.

This type is used by the following types:

* :ref:`SpecTypeSpecificationInformation`

.. _SpecTypeSpecificationAttributeValue:

Specification Attribute Value
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

spec-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    specification type of the attribute value.

This type is used by the following types:

* :ref:`SpecTypeSpecificationExplicitAttributes`

.. _SpecTypeSpecificationBooleanValue:

Specification Boolean Value
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

This type is used by the following types:

* :ref:`SpecTypeSpecificationInformation`

.. _SpecTypeSpecificationExplicitAttributes:

Specification Explicit Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Generic attributes may be specified. Each generic attribute key shall be a
:ref:`SpecTypeName`. Each generic attribute value shall be a
:ref:`SpecTypeSpecificationAttributeValue`. Each generic attribute specifies an
explicit attribute of the attribute set.  The key of the each generic attribute
defines the attribute key of the explicit attribute.

This type is used by the following types:

* :ref:`SpecTypeSpecificationAttributeSet`

.. _SpecTypeSpecificationFloatingPointAssert:

Specification Floating-Point Assert
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

  and
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeSpecificationFloatingPointAssert`. The *and* operator
      evaluates to the *logical and* of the evaluation results of the
      expressions in the list.

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

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

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

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

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

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

  not
      The attribute value shall be a
      :ref:`SpecTypeSpecificationFloatingPointAssert`. The *not* operator
      evaluates to the *logical not* of the evaluation results of the
      expression.

  or
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeSpecificationFloatingPointAssert`. The *or* operator
      evaluates to the *logical or* of the evaluation results of the
      expressions in the list.

* The value may be a list. Each list element shall be a
  :ref:`SpecTypeSpecificationFloatingPointAssert`. This list of expressions
  evaluates to the *logical or* of the evaluation results of the expressions in
  the list.

This type is used by the following types:

* :ref:`SpecTypeSpecificationFloatingPointAssert`

* :ref:`SpecTypeSpecificationFloatingPointValue`

.. _SpecTypeSpecificationFloatingPointValue:

Specification Floating-Point Value
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

assert
    The attribute value shall be a
    :ref:`SpecTypeSpecificationFloatingPointAssert`. This optional attribute
    defines the value constraints of the specified floating-point value.  In
    case the assert attribute is not present, then the value of the specified
    floating-point value may be every valid floating-point number.

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

This type is used by the following types:

* :ref:`SpecTypeSpecificationInformation`

.. _SpecTypeSpecificationGenericAttributes:

Specification Generic Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

key-spec-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    specification type of the generic attribute keys.

value-spec-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    specification type of the generic attribute values.

This type is used by the following types:

* :ref:`SpecTypeSpecificationAttributeSet`

.. _SpecTypeSpecificationInformation:

Specification Information
^^^^^^^^^^^^^^^^^^^^^^^^^

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

bool
    The attribute value shall be a :ref:`SpecTypeSpecificationBooleanValue`. It
    shall specify a boolean value.

dict
    The attribute value shall be a :ref:`SpecTypeSpecificationAttributeSet`. It
    shall specify a set of attributes.

float
    The attribute value shall be a
    :ref:`SpecTypeSpecificationFloatingPointValue`. It shall specify a
    floating-point value.

int
    The attribute value shall be a :ref:`SpecTypeSpecificationIntegerValue`. It
    shall specify an integer value.

list
    The attribute value shall be a :ref:`SpecTypeSpecificationList`. It shall
    specify a list of attributes or values.

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

str
    The attribute value shall be a :ref:`SpecTypeSpecificationStringValue`. It
    shall specify a string.

This type is used by the following types:

* :ref:`SpecTypeSpecificationItemType`

.. _SpecTypeSpecificationIntegerAssert:

Specification Integer Assert
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

  and
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeSpecificationIntegerAssert`. The *and* operator evaluates
      to the *logical and* of the evaluation results of the expressions in the
      list.

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

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

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

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

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

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

  not
      The attribute value shall be a :ref:`SpecTypeSpecificationIntegerAssert`.
      The *not* operator evaluates to the *logical not* of the evaluation
      results of the expression.

  or
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeSpecificationIntegerAssert`. The *or* operator evaluates to
      the *logical or* of the evaluation results of the expressions in the
      list.

* The value may be a list. Each list element shall be a
  :ref:`SpecTypeSpecificationIntegerAssert`. This list of expressions evaluates
  to the *logical or* of the evaluation results of the expressions in the list.

This type is used by the following types:

* :ref:`SpecTypeSpecificationIntegerAssert`

* :ref:`SpecTypeSpecificationIntegerValue`

.. _SpecTypeSpecificationIntegerValue:

Specification Integer Value
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

assert
    The attribute value shall be a :ref:`SpecTypeSpecificationIntegerAssert`.
    This optional attribute defines the value constraints of the specified
    integer value.  In case the assert attribute is not present, then the value
    of the specified integer value may be every valid integer number.

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

This type is used by the following types:

* :ref:`SpecTypeSpecificationInformation`

.. _SpecTypeSpecificationList:

Specification List
^^^^^^^^^^^^^^^^^^

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

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

spec-type
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    specification type of elements of the list.

This type is used by the following types:

* :ref:`SpecTypeSpecificationInformation`

.. _SpecTypeSpecificationMandatoryAttributes:

Specification Mandatory Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It defines which explicit attributes are mandatory.

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

* The value may be a list. Each list element shall be a :ref:`SpecTypeName`.
  The list defines the mandatory attributes through their key names.

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

  * "``all``",

  * "``at-least-one``",

  * "``at-most-one``",

  * "``exactly-one``", and

  * "``none``".

This type is used by the following types:

* :ref:`SpecTypeSpecificationAttributeSet`

.. _SpecTypeSpecificationMemberLinkRole:

Specification Member Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``spec-member``. It defines the specification membership role of
links.

.. _SpecTypeSpecificationRefinementLinkRole:

Specification Refinement Link Role
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``spec-refinement``. It defines the specification refinement role of
links. All explicit attributes shall be specified. The explicit attributes for
this type are:

spec-key
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    specification type refinement attribute key of the specification
    refinement.

spec-value
    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
    specification type refinement attribute value of the specification
    refinement.

.. _SpecTypeSpecificationStringAssert:

Specification String Assert
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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

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

  and
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeSpecificationStringAssert`. The *and* operator evaluates to
      the *logical and* of the evaluation results of the expressions in the
      list.

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

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

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

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

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

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

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

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

  not
      The attribute value shall be a :ref:`SpecTypeSpecificationStringAssert`.
      The *not* operator evaluates to the *logical not* of the evaluation
      results of the expression.

  or
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeSpecificationStringAssert`. The *or* operator evaluates to
      the *logical or* of the evaluation results of the expressions in the
      list.

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

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

* The value may be a list. Each list element shall be a
  :ref:`SpecTypeSpecificationStringAssert`. This list of expressions evaluates
  to the *logical or* of the evaluation results of the expressions in the list.

This type is used by the following types:

* :ref:`SpecTypeSpecificationStringAssert`

* :ref:`SpecTypeSpecificationStringValue`

.. _SpecTypeSpecificationStringValue:

Specification String Value
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

assert
    The attribute value shall be a :ref:`SpecTypeSpecificationStringAssert`.
    This optional attribute defines the constraints of the specified string.
    In case the assert attribute is not present, then the specified string may
    be every valid string.

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

This type is used by the following types:

* :ref:`SpecTypeSpecificationInformation`

.. _SpecTypeTestCaseAction:

Test Case Action
^^^^^^^^^^^^^^^^

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

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

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

checks
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeTestCaseCheck`.

links
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeLink`. The links should use the
    :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the
    :ref:`SpecTypeUnitTestLinkRole` for unit tests.

This type is used by the following types:

* :ref:`SpecTypeTestCaseItemType`

.. _SpecTypeTestCaseCheck:

Test Case Check
^^^^^^^^^^^^^^^

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

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

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

links
    The attribute value shall be a list. Each list element shall be a
    :ref:`SpecTypeLink`. The links should use the
    :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the
    :ref:`SpecTypeUnitTestLinkRole` for unit tests.

This type is used by the following types:

* :ref:`SpecTypeTestCaseAction`

.. _SpecTypeTestContextMember:

Test Context Member
^^^^^^^^^^^^^^^^^^^

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

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

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

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

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

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeActionRequirementItemType`

* :ref:`SpecTypeRuntimeMeasurementTestItemType`

* :ref:`SpecTypeTestCaseItemType`

.. _SpecTypeTestHeader:

Test Header
^^^^^^^^^^^

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

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

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

  freestanding
      The attribute value shall be a boolean. The value shall be ``true``, if
      the test case is freestanding, otherwise ``false``.  Freestanding test
      cases are not statically registered.  Instead the generated test runner
      uses :c:func:`T_case_begin` and :c:func:`T_case_end`.

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

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

  run-params
      The attribute value shall be a list. Each list element shall be a
      :ref:`SpecTypeTestRunParameter`.

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

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeActionRequirementItemType`

* :ref:`SpecTypeTestCaseItemType`

.. _SpecTypeTestRunParameter:

Test Run Parameter
^^^^^^^^^^^^^^^^^^

This set of attributes specifies a parameter for the test run function. In case
this parameter is used in an :ref:`SpecTypeActionRequirementItemType` item,
then the parameter is also added as a member to the test context, see
:ref:`SpecTypeTestContextMember`. All explicit attributes shall be specified.
The explicit attributes for this type are:

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

dir
    The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`.

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

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

This type is used by the following types:

* :ref:`SpecTypeTestHeader`

.. _SpecTypeTestSupportMethod:

Test Support Method
^^^^^^^^^^^^^^^^^^^

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

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

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

  code
      The attribute value shall be a string. It shall be the test support
      method code.  The code may use a local variable ``ctx`` which points to
      the test context, see :ref:`SpecTypeTestContextMember`.

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

* There may be no value (null).

This type is used by the following types:

* :ref:`SpecTypeActionRequirementItemType`

* :ref:`SpecTypeRuntimeMeasurementTestItemType`

* :ref:`SpecTypeRuntimePerformanceRequirementItemType`

* :ref:`SpecTypeTestCaseItemType`

.. _SpecTypeUID:

UID
^^^

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

This type is used by the following types:

* :ref:`SpecTypeLink`

.. _SpecTypeUnitTestLinkRole:

Unit Test Link Role
^^^^^^^^^^^^^^^^^^^

This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
value is ``unit-test``. It defines the unit test role of links.  For unit tests
the link target should be the :ref:`SpecTypeInterfaceDomainItemType` containing
the software unit. All explicit attributes shall be specified. The explicit
attributes for this type are:

name
    The attribute value shall be a string. It shall be the name of the tested
    software unit.