diff options
Diffstat (limited to 'eng/req/items.rst')
| -rw-r--r-- | eng/req/items.rst | 1800 |
1 files changed, 1292 insertions, 508 deletions
diff --git a/eng/req/items.rst b/eng/req/items.rst index be3ff38..286e998 100644 --- a/eng/req/items.rst +++ b/eng/req/items.rst @@ -1,17 +1,21 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. 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://docs.rtems.org/branches/master/user/support/bugs.html +.. https://www.rtems.org/bugs.html .. -.. For information on updating and regenerating please refer to: +.. 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/branches/master/eng/req/howto.html +.. https://docs.rtems.org .. _ReqEngSpecificationItems: @@ -73,8 +77,6 @@ The specification item types have the following hierarchy: * :ref:`SpecTypeInterfaceCompoundItemType` - * :ref:`SpecTypeInterfaceContainerItemType` - * :ref:`SpecTypeInterfaceDefineItemType` * :ref:`SpecTypeInterfaceDomainItemType` @@ -85,20 +87,24 @@ The specification item types have the following hierarchy: * :ref:`SpecTypeInterfaceForwardDeclarationItemType` - * :ref:`SpecTypeInterfaceFunctionItemType` + * :ref:`SpecTypeInterfaceFunctionOrMacroItemType` * :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceHeaderFileItemType` - * :ref:`SpecTypeInterfaceMacroItemType` - * :ref:`SpecTypeInterfaceTypedefItemType` + * :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + * :ref:`SpecTypeInterfaceUnspecifiedItemType` * :ref:`SpecTypeInterfaceVariableItemType` + * :ref:`SpecTypeRegisterBlockItemType` + + * :ref:`SpecTypeProxyItemTypes` + * :ref:`SpecTypeRequirementItemType` * :ref:`SpecTypeFunctionalRequirementItemType` @@ -109,12 +115,20 @@ The specification item types have the following hierarchy: * :ref:`SpecTypeNonFunctionalRequirementItemType` + * :ref:`SpecTypeDesignGroupRequirementItemType` + + * :ref:`SpecTypeDesignTargetItemType` + * :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + * :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + * :ref:`SpecTypeRuntimePerformanceRequirementItemType` * :ref:`SpecTypeRequirementValidationItemType` + * :ref:`SpecTypeRequirementValidationMethod` + * :ref:`SpecTypeRuntimeMeasurementTestItemType` * :ref:`SpecTypeSpecificationItemType` @@ -185,6 +199,8 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceItemType` +* :ref:`SpecTypeProxyItemTypes` + * :ref:`SpecTypeRequirementItemType` * :ref:`SpecTypeRequirementValidationItemType` @@ -278,6 +294,10 @@ 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`. @@ -319,8 +339,9 @@ Please have a look at the following example: build-type: ada-test-program cflags: [] copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG cppflags: [] + cxxflags: [] enabled-by: true includes: [] ldflags: [] @@ -385,7 +406,7 @@ Please have a look at the following example: build-type: bsp cflags: [] copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG cppflags: [] enabled-by: true family: mybsp @@ -455,7 +476,7 @@ Please have a look at the following example: Name: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME} # ... copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true install-path: ${PREFIX}/lib/pkgconfig links: [] @@ -503,6 +524,18 @@ referenced build items. The ``includes``, ``ldflags``, ``objects``, and 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`. @@ -530,8 +563,11 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause build-type: group + cflags: [] copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + cxxflags: [] enabled-by: - BUILD_TESTS - BUILD_SAMPLES @@ -601,7 +637,7 @@ Please have a look at the following example: cflags: - -Wno-pointer-sign copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG cppflags: [] cxxflags: [] enabled-by: true @@ -625,8 +661,12 @@ 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. All explicit -attributes shall be specified. The explicit attributes for this type are: +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 @@ -660,7 +700,7 @@ Please have a look at the following example: build-type: objects cflags: [] copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG cppflags: [] cxxflags: [] enabled-by: true @@ -690,8 +730,6 @@ option. The following explicit attributes are mandatory: * ``default`` -* ``default-by-variant`` - * ``description`` The explicit attributes for this type are: @@ -705,16 +743,11 @@ actions actions are carried out during the configure command execution. default - The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It shall be - the default value of the option if no variant-specific default value is - specified. Use ``null`` to specify that no default value exits. The - variant-specific default values may be specified by the - ``default-by-variant`` attribute. - -default-by-variant The attribute value shall be a list. Each list element shall be a - :ref:`SpecTypeBuildOptionDefaultByVariant`. The list is processed from top - to bottom. If a matching variant is found, then the processing stops. + :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 @@ -739,16 +772,17 @@ Please have a look at the following example: - define: null build-type: option copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) - default: 115200 - default-by-variant: - - value: 9600 - variants: + - Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG + default: + - enabled-by: + - bsps/powerpc/motorola_powerpc - m68k/m5484FireEngine - powerpc/hsc_cm01 - - value: 19200 - variants: - - m68k/COBRA5475 + 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 @@ -835,6 +869,9 @@ 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`. @@ -850,7 +887,7 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause build-type: script copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG default: null default-by-variant: [] do-build: | @@ -910,7 +947,7 @@ Please have a look at the following example: asflags: [] build-type: start-file copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG cppflags: [] enabled-by: true includes: [] @@ -986,7 +1023,7 @@ Please have a look at the following example: build-type: test-program cflags: [] copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG cppflags: [] cxxflags: [] enabled-by: true @@ -1017,10 +1054,6 @@ rationale The attribute value shall be an optional string. If the value is present, then it shall state the rationale or justification of the constraint. -scope - The attribute value shall be a string. It shall be the scope of the - constraint. - text The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall state the constraint. @@ -1111,8 +1144,6 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceCompoundItemType` -* :ref:`SpecTypeInterfaceContainerItemType` - * :ref:`SpecTypeInterfaceDefineItemType` * :ref:`SpecTypeInterfaceDomainItemType` @@ -1123,20 +1154,22 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceForwardDeclarationItemType` -* :ref:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` * :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceHeaderFileItemType` -* :ref:`SpecTypeInterfaceMacroItemType` - * :ref:`SpecTypeInterfaceTypedefItemType` +* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + * :ref:`SpecTypeInterfaceUnspecifiedItemType` * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeApplicationConfigurationGroupItemType: Application Configuration Group Item Type @@ -1174,9 +1207,7 @@ appl-config-option-type application configuration option type. description - The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. The - :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items have an - attribute for constraints. + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. name The attribute value shall be an @@ -1185,10 +1216,6 @@ name notes The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. -text - The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall - state the requirement for the application configuration option. - This type is refined by the following types: * :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` @@ -1239,13 +1266,9 @@ This set of attributes specifies application configuration initializer or integer option. All explicit attributes shall be specified. The explicit attributes for this type are: -constraints - The attribute value shall be an - :ref:`SpecTypeApplicationConfigurationOptionConstraintSet`. - default-value The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall - shall describe the default value of the application configuration option. + describe the default value of the application configuration option. .. _SpecTypeInterfaceCompoundItemType: @@ -1284,18 +1307,6 @@ name notes The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. -.. _SpecTypeInterfaceContainerItemType: - -Interface Container Item Type -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This type refines the :ref:`SpecTypeInterfaceItemType` through the -``interface-type`` attribute if the value is ``container``. Items of this type -specify an interface container. The item shall have exactly one link with the -:ref:`SpecTypeInterfacePlacementLinkRole` to an -:ref:`SpecTypeInterfaceDomainItemType` item. This link defines the interface -domain of the container. - .. _SpecTypeInterfaceDefineItemType: Interface Define Item Type @@ -1329,9 +1340,7 @@ 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. Items of the types -:ref:`SpecTypeInterfaceContainerItemType` and -:ref:`SpecTypeInterfaceHeaderFileItemType` are placed into domains through +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: @@ -1407,29 +1416,35 @@ with the :ref:`SpecTypeInterfaceTargetLinkRole` to an :ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the type declared by the forward declaration. -.. _SpecTypeInterfaceFunctionItemType: +.. _SpecTypeInterfaceFunctionOrMacroItemType: -Interface Function Item Type -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Interface Function or Macro Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This type refines the :ref:`SpecTypeInterfaceItemType` through the -``interface-type`` attribute if the value is ``function``. This set of -attributes specifies a function. All explicit attributes shall be specified. -The explicit attributes for this type are: +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:`SpecTypeInterfaceFunctionDefinitionDirective`. + :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. + 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`. @@ -1493,15 +1508,15 @@ prefix path to the header file in the interface domain. For example :file:`cpukit/include`. -.. _SpecTypeInterfaceMacroItemType: +.. _SpecTypeInterfaceTypedefItemType: -Interface Macro Item Type -^^^^^^^^^^^^^^^^^^^^^^^^^ +Interface Typedef Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^ This type refines the :ref:`SpecTypeInterfaceItemType` through the -``interface-type`` attribute if the value is ``macro``. This set of attributes -specifies a macro. All explicit attributes shall be specified. The explicit -attributes for this type are: +``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`. @@ -1514,7 +1529,7 @@ description The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. name - The attribute value shall be a string. It shall be the name of the macro. + The attribute value shall be a string. It shall be the name of the typedef. notes The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. @@ -1526,31 +1541,23 @@ params return The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`. -.. _SpecTypeInterfaceTypedefItemType: +.. _SpecTypeInterfaceUnspecifiedHeaderFileItemType: -Interface Typedef Item Type -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Interface Unspecified Header File 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`. +``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: -name - The attribute value shall be a string. It shall be the name of the typedef. +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`. -notes - The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. .. _SpecTypeInterfaceUnspecifiedItemType: @@ -1560,16 +1567,34 @@ Interface Unspecified Item Type This type refines the following types: * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if - the value is ``unspecified`` + the value is ``unspecified-define`` * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if - the value is ``unspecified-define`` + 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-type`` + 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: @@ -1578,9 +1603,9 @@ name The attribute value shall be a string. It shall be the name of the unspecified interface. -reference - The attribute value shall be an optional string. If the value is present, - then it shall be an URL to the standard or specification of the interface. +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. .. _SpecTypeInterfaceVariableItemType: @@ -1609,6 +1634,78 @@ name 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 @@ -1624,8 +1721,8 @@ rationale then it shall state the rationale or justification of the requirement. references - The attribute value shall be a list. Each list element shall be a - :ref:`SpecTypeRequirementReference`. + 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 @@ -1647,7 +1744,7 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true functional-type: capability links: [] @@ -1793,7 +1890,7 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true functional-type: action links: [] @@ -1929,6 +2026,9 @@ This type refines the following types: 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`` @@ -1953,10 +2053,56 @@ non-functional-type 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 @@ -1989,6 +2135,10 @@ This type refines the following types: ``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 @@ -2006,6 +2156,22 @@ This type refines the following types: 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 @@ -2054,9 +2220,6 @@ 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: -limits - The attribute value shall be a :ref:`SpecTypeRuntimePerformanceLimitTable`. - params The attribute value shall be a :ref:`SpecTypeRuntimePerformanceParameterSet`. @@ -2092,34 +2255,11 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true links: - role: runtime-measurement-request - uid: ../val/performance - limits: - sparc/leon3: - DirtyCache: - max-upper-bound: 0.000005 - mean-upper-bound: 0.000005 - FullCache: - max-upper-bound: 0.000005 - mean-upper-bound: 0.000005 - HotCache: - max-upper-bound: 0.000005 - mean-upper-bound: 0.000005 - Load/1: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 - Load/2: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 - Load/3: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 - Load/4: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 + uid: ../val/perf params: {} rationale: null references: [] @@ -2146,11 +2286,11 @@ Please have a look at the following example: return tic == toc; description: null text: | - When a partition has exactly ${../val/performance:/params/buffer-count} free - buffers, the ${.:limit-kind} runtime of exactly - ${../val/performance:/params/sample-count} successful calls to + 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}. + ${.:/limit-condition}. non-functional-type: performance-runtime requirement-type: non-functional type: requirement @@ -2168,8 +2308,13 @@ All explicit attributes shall be specified. The explicit attributes for this type are: method - The attribute value shall be a :ref:`SpecTypeRequirementValidationMethod`. - Validation by test is done through :ref:`SpecTypeTestCaseItemType` items. + 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 @@ -2184,6 +2329,26 @@ text * *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 @@ -2289,7 +2454,7 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true links: - role: spec-member @@ -2336,20 +2501,18 @@ test-brief The attribute value shall be a string. It shall be the test case brief description. -test-description - The attribute value shall be an optional string. It shall be the test case - description. +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. -test-epilogue +test-context-support The attribute value shall be an optional string. If the value is present, - then it shall be the test case epilogue code. The epilogue code is placed - in the test case body after the test case actions. + then it shall be the test context support code. The context support code + is placed at file scope before the test context definition. -test-fixture - The attribute value shall be an optional string. If the value is present, - then it shall be a pointer to the test case fixture. The test case fixture - pointer declaration may be provided by the test case support code or via an - included header file. +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`. @@ -2362,11 +2525,11 @@ test-local-includes The attribute value shall be a list of strings. It shall be a list of header files included via ``#include "..."``. -test-prologue - The attribute value shall be an optional string. If the value is present, - then it shall be the test case prologue code. The prologue code is placed - in the test case body before the test case actions. A use case is the - declaration of local variables used by the test case actions. +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, @@ -2377,6 +2540,9 @@ 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 @@ -2432,10 +2598,16 @@ steps Test Suite Item Type ^^^^^^^^^^^^^^^^^^^^ -This type refines the :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: +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 @@ -2466,6 +2638,62 @@ test-target 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 @@ -2500,6 +2728,100 @@ 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 @@ -2513,7 +2835,7 @@ 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]+$``", +* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", * and, shall be not equal to "``NA``". @@ -2521,6 +2843,10 @@ This type is used by the following types: * :ref:`SpecTypeActionRequirementCondition` +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + +* :ref:`SpecTypeActionRequirementExpression` + * :ref:`SpecTypeActionRequirementSkipReasons` * :ref:`SpecTypeActionRequirementState` @@ -2608,6 +2934,29 @@ 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 @@ -2619,16 +2968,18 @@ A value of this type shall be of one of the following variants: 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:`SpecTypeActionRequirementName`. There shall be + 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. + 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]+$``", + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", * and, shall be not equal to "``NA``". @@ -2664,60 +3015,26 @@ This type is used by the following types: Action Requirement Transition Pre-Conditions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes defines for each pre-condition the set of states before -the action for a transition in an actin requirement. Generic attributes may be -specified. Each generic attribute key shall be an -: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. - -This type is used by the following types: - -* :ref:`SpecTypeActionRequirementTransition` - -.. _SpecTypeApplicationConfigurationGroupMemberLinkRole: - -Application Configuration Group Member Link Role -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the -value is ``appl-config-group-member``. It defines the application configuration -group membership role of links. - -.. _SpecTypeApplicationConfigurationOptionConstraintSet: - -Application Configuration Option Constraint Set -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This set of attributes defines application configuration option constraints. -Additional constraints can be added through the links of the item using the -:ref:`SpecTypeConstraintLinkRole`. None of the explicit attributes is -mandatory, they are all optional. The explicit attributes for this type are: - -max - The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall be - the maximum value of the application configuration option. - -min - The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall be - the minimum value of the application configuration option. - -set - The attribute value shall be a list. Each list element shall be an - :ref:`SpecTypeIntegerOrString`. It shall be the set of valid values for the - application configuration option. +A value of this type shall be of one of the following variants: -texts - The attribute value shall be a list. Each list element shall be a - :ref:`SpecTypeRequirementText`. It shall be a list of constraints specific - to this application configuration option. For general constraints, use a - link with the :ref:`SpecTypeConstraintLinkRole` to a constraint item. +* 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:`SpecTypeApplicationConfigurationValueOptionItemType` +* :ref:`SpecTypeActionRequirementTransition` .. _SpecTypeApplicationConfigurationOptionName: @@ -2783,6 +3100,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildBSPItemType` +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -2809,6 +3128,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildBSPItemType` +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -2831,6 +3152,10 @@ context. This type is used by the following types: +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -2841,6 +3166,20 @@ This type is used by the following types: * :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 @@ -2917,7 +3256,7 @@ Build Install Path A value of this type shall be of one of the following variants: -* There may by be no value (null). +* There may be no value (null). * The value may be a string. It shall be the installation path of a :ref:`SpecTypeBuildTarget`. @@ -3138,6 +3477,12 @@ get-string ``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 @@ -3214,22 +3559,20 @@ This type is used by the following types: * :ref:`SpecTypeBuildOptionAction` -.. _SpecTypeBuildOptionDefaultByVariant: +.. _SpecTypeBuildOptionDefaultValue: -Build Option Default by Variant -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Build Option Default Value +^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies build option default values by variant. All -explicit attributes shall be specified. The explicit attributes for this type -are: +This set of attributes specifies a build option default value. All explicit +attributes shall be specified. The explicit attributes for this type are: -value - The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It value - shall be the default value for the matching variants. +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. -variants - The attribute value shall be a list of strings. It shall be a list of - Python regular expression matching with the desired variants. +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: @@ -3252,14 +3595,25 @@ This type is used by the following types: Build Option Set Test State Action ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies test states for a set of test programs. -Generic attributes may be specified. Each generic attribute key shall be a -:ref:`SpecTypeName`. Each generic attribute value shall be a -:ref:`SpecTypeBuildTestState`. The keys shall be test program names. The names -shall correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType` or -:ref:`SpecTypeBuildAdaTestProgramItemType` item. Due to the processing order -of items, there is no way to check if the name specified by the attribute key -is valid. +This 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: @@ -3278,7 +3632,7 @@ 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 string. -* There may by be no value (null). +* There may be no value (null). * The value may be a string. @@ -3286,9 +3640,7 @@ This type is used by the following types: * :ref:`SpecTypeBuildOptionAction` -* :ref:`SpecTypeBuildOptionDefaultByVariant` - -* :ref:`SpecTypeBuildOptionItemType` +* :ref:`SpecTypeBuildOptionDefaultValue` .. _SpecTypeBuildSource: @@ -3331,6 +3683,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildLibraryItemType` +* :ref:`SpecTypeBuildScriptItemType` + * :ref:`SpecTypeBuildStartFileItemType` * :ref:`SpecTypeBuildTestProgramItemType` @@ -3472,6 +3826,10 @@ This type is used by the following types: * :ref:`SpecTypeActionRequirementTransition` +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildOptionDefaultValue` + * :ref:`SpecTypeEnabledByExpression` * :ref:`SpecTypeInterfaceIncludeLinkRole` @@ -3487,6 +3845,111 @@ Please have a look at the following example: - 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 @@ -3508,8 +3971,6 @@ A value of this type shall be of one of the following variants: This type is used by the following types: -* :ref:`SpecTypeApplicationConfigurationOptionConstraintSet` - * :ref:`SpecTypeApplicationConfigurationValueOptionItemType` * :ref:`SpecTypeBuildOptionAction` @@ -3521,7 +3982,7 @@ Interface Brief Description A value of this type shall be of one of the following variants: -* There may by be no value (null). +* 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 @@ -3539,18 +4000,22 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnumeratorItemType` -* :ref:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` * :ref:`SpecTypeInterfaceGroupItemType` * :ref:`SpecTypeInterfaceHeaderFileItemType` -* :ref:`SpecTypeInterfaceMacroItemType` - * :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + .. _SpecTypeInterfaceCompoundDefinitionKind: Interface Compound Definition Kind @@ -3615,23 +4080,27 @@ definition Interface Compound Member Definition ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies an interface compound member definition. All -explicit attributes shall be specified. The explicit attributes for this type -are: +A value of this type shall be of one of the following variants: -brief - The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. +* 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: -description - The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. -kind - The attribute value shall be a string. It shall be the interface compound - member kind. + description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. -name - The attribute value shall be a string. It shall be the interface compound - member name. + 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: @@ -3700,7 +4169,7 @@ Interface Definition A value of this type shall be of one of the following variants: -* There may by be no value (null). +* 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. @@ -3735,8 +4204,6 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnumeratorItemType` -* :ref:`SpecTypeInterfaceMacroItemType` - * :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceVariableItemType` @@ -3770,7 +4237,7 @@ Interface Description A value of this type shall be of one of the following variants: -* There may by be no value (null). +* 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 @@ -3792,12 +4259,10 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnumeratorItemType` -* :ref:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` * :ref:`SpecTypeInterfaceGroupItemType` -* :ref:`SpecTypeInterfaceMacroItemType` - * :ref:`SpecTypeInterfaceParameter` * :ref:`SpecTypeInterfaceReturnValue` @@ -3806,6 +4271,12 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + .. _SpecTypeInterfaceEnabledByExpression: Interface Enabled-By Expression @@ -3853,7 +4324,11 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnabledByExpression` -* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` .. _SpecTypeInterfaceEnumDefinitionKind: @@ -3883,79 +4358,98 @@ This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the value is ``interface-enumerator``. It defines the interface enumerator role of links. -.. _SpecTypeInterfaceFunctionDefinition: +.. _SpecTypeInterfaceFunctionLinkRole: -Interface Function Definition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Interface Function Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies a function definition. All explicit attributes -shall be specified. The explicit attributes for this type are: +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. -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. +.. _SpecTypeInterfaceFunctionOrMacroDefinition: -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. +Interface Function or Macro Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -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. +A value of this type shall be of one of the following variants: -return - The attribute value shall be a string. It shall be the function return - type. On the return type a context-sensitive substitution of item - variables is performed. +* 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:`SpecTypeInterfaceFunctionDefinitionDirective` +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective` -* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` -.. _SpecTypeInterfaceFunctionDefinitionDirective: +.. _SpecTypeInterfaceFunctionOrMacroDefinitionDirective: -Interface Function Definition Directive -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Interface Function or Macro Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies a function definition directive. All explicit -attributes shall be specified. The explicit attributes for this type are: +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:`SpecTypeInterfaceFunctionDefinition`. - The default definition will be used if no variant-specific definition is - enabled. + 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:`SpecTypeInterfaceFunctionDefinitionVariant`. + :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`. This type is used by the following types: -* :ref:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` -.. _SpecTypeInterfaceFunctionDefinitionVariant: +.. _SpecTypeInterfaceFunctionOrMacroDefinitionVariant: -Interface Function Definition Variant -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Interface Function or Macro Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies a function definition variant. All explicit -attributes shall be specified. The explicit attributes for this type are: +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:`SpecTypeInterfaceFunctionDefinition`. - The definition will be used if the expression defined by the ``enabled-by`` - attribute evaluates to true. In generated header files, the expression is - evaluated by the C preprocessor. + 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 @@ -3963,19 +4457,7 @@ enabled-by This type is used by the following types: -* :ref:`SpecTypeInterfaceFunctionDefinitionDirective` - -.. _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:`SpecTypeInterfaceFunctionItemType` or a -:ref:`SpecTypeInterfaceMacroItemType` item. +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective` .. _SpecTypeInterfaceGroupIdentifier: @@ -3989,6 +4471,8 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceGroupItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeInterfaceGroupMembershipLinkRole: Interface Group Membership Link Role @@ -3998,6 +4482,18 @@ 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 @@ -4021,7 +4517,7 @@ Interface Notes A value of this type shall be of one of the following variants: -* There may by be no value (null). +* There may be no value (null). * The value may be a string. It shall be the notes for the interface. @@ -4035,14 +4531,14 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnumeratorItemType` -* :ref:`SpecTypeInterfaceFunctionItemType` - -* :ref:`SpecTypeInterfaceMacroItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` * :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeInterfaceParameter: Interface Parameter @@ -4063,9 +4559,9 @@ name This type is used by the following types: -* :ref:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` -* :ref:`SpecTypeInterfaceMacroItemType` +* :ref:`SpecTypeInterfaceTypedefItemType` .. _SpecTypeInterfaceParameterDirection: @@ -4074,7 +4570,7 @@ Interface Parameter Direction A value of this type shall be of one of the following variants: -* There may by be no value (null). +* 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 @@ -4106,22 +4602,27 @@ interface container, for example a header file. Interface Return Directive ^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies an interface return. All explicit attributes -shall be specified. The explicit attributes for this type are: +A value of this type shall be of one of the following variants: -return - The attribute value shall be an optional string. It shall describe the - interface return for unspecified return values. +* 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-values - The attribute value shall be a list. Each list element shall be an - :ref:`SpecTypeInterfaceReturnValue`. + 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:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` -* :ref:`SpecTypeInterfaceMacroItemType` +* :ref:`SpecTypeInterfaceTypedefItemType` .. _SpecTypeInterfaceReturnValue: @@ -4171,12 +4672,14 @@ uid This type is refined by the following types: -* :ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole` +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` * :ref:`SpecTypeBuildDependencyLinkRole` * :ref:`SpecTypeConstraintLinkRole` +* :ref:`SpecTypeFunctionImplementationLinkRole` + * :ref:`SpecTypeGlossaryMembershipLinkRole` * :ref:`SpecTypeInterfaceEnumeratorLinkRole` @@ -4185,14 +4688,22 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceGroupMembershipLinkRole` +* :ref:`SpecTypeInterfaceHiddenGroupMembershipLinkRole` + * :ref:`SpecTypeInterfaceIncludeLinkRole` * :ref:`SpecTypeInterfacePlacementLinkRole` * :ref:`SpecTypeInterfaceTargetLinkRole` +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + * :ref:`SpecTypePlacementOrderLinkRole` +* :ref:`SpecTypeProxyMemberLinkRole` + +* :ref:`SpecTypeRegisterBlockIncludeRole` + * :ref:`SpecTypeRequirementRefinementLinkRole` * :ref:`SpecTypeRequirementValidationLinkRole` @@ -4203,6 +4714,8 @@ This type is refined by the following types: * :ref:`SpecTypeSpecificationRefinementLinkRole` +* :ref:`SpecTypeUnitTestLinkRole` + This type is used by the following types: * :ref:`SpecTypeRootItemType` @@ -4225,7 +4738,7 @@ This type is used by the following types: * :ref:`SpecTypeBuildItemType` -* :ref:`SpecTypeBuildOptionSetTestStateAction` +* :ref:`SpecTypeExternalReference` * :ref:`SpecTypeFunctionalRequirementItemType` @@ -4237,8 +4750,12 @@ This type is used by the following types: * :ref:`SpecTypeNonFunctionalRequirementItemType` +* :ref:`SpecTypeRegisterDefinition` + * :ref:`SpecTypeRequirementItemType` +* :ref:`SpecTypeRequirementValidationItemType` + * :ref:`SpecTypeRootItemType` * :ref:`SpecTypeRuntimeMeasurementParameterSet` @@ -4257,6 +4774,32 @@ This type is used by the following types: * :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 @@ -4264,10 +4807,24 @@ Optional String A value of this type shall be of one of the following variants: -* There may by be no value (null). +* 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 @@ -4278,49 +4835,267 @@ 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). -.. _SpecTypeRequirementReference: +.. _SpecTypeProxyMemberLinkRole: -Requirement Reference -^^^^^^^^^^^^^^^^^^^^^ +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: -This set of attributes specifies a requirement reference. All explicit +* :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: -identifier - The attribute value shall be a string. It shall be the type-specific - identifier of the reference target. For *group* references use the Doxygen - group identifier. +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. -type - The attribute value shall be a :ref:`SpecTypeRequirementReferenceType`. +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:`SpecTypeRequirementItemType` +* :ref:`SpecTypeRegisterDefinition` -.. _SpecTypeRequirementReferenceType: +.. _SpecTypeRegisterBitsDefinitionVariant: -Requirement Reference Type -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Register Bits Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The value shall be a string. It specifies the type of a requirement reference. -The value shall be an element of +This set of attributes specifies a register bits variant. All explicit +attributes shall be specified. The explicit attributes for this type are: -* "``define``", +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. -* "``file``", +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. -* "``function``", +This type is used by the following types: -* "``group``", +* :ref:`SpecTypeRegisterBitsDefinitionDirective` -* "``macro``", and +.. _SpecTypeRegisterBlockIncludeRole: -* "``variable``". +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:`SpecTypeRequirementReference` +* :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: @@ -4336,130 +5111,130 @@ of links. Requirement Text ^^^^^^^^^^^^^^^^ -The value shall be a string. It shall state a requirement or constraint. The -value shall not contain an element of +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``", +* acceptable -* "``adequate``", +* adequate -* "``almost always``", +* almost always -* "``and/or``", +* and/or -* "``appropriate``", +* appropriate -* "``approximately``", +* approximately -* "``as far as possible``", +* as far as possible -* "``as much as practicable``", +* as much as practicable -* "``best``", +* best -* "``best possible``", +* best possible -* "``easy``", +* easy -* "``efficient``", +* efficient -* "``e.g.``", +* e.g. -* "``enable``", +* enable -* "``enough``", +* enough -* "``etc.``", +* etc. -* "``few``", +* few -* "``first rate``", +* first rate -* "``flexible``", +* flexible -* "``generally``", +* generally -* "``goal``", +* goal -* "``graceful``", +* graceful -* "``great``", +* great -* "``greatest``", +* greatest -* "``ideally``", +* ideally -* "``i.e.``", +* i.e. -* "``if possible``", +* if possible -* "``in most cases``", +* in most cases -* "``large``", +* large -* "``many``", +* many -* "``maximize``", +* maximize -* "``minimize``", +* minimize -* "``most``", +* most -* "``multiple``", +* multiple -* "``necessary``", +* necessary -* "``numerous``", +* numerous -* "``optimize``", +* optimize -* "``ought to``", +* ought to -* "``probably``", +* probably -* "``quick``", +* quick -* "``rapid``", +* rapid -* "``reasonably``", +* reasonably -* "``relevant``", +* relevant -* "``robust``", +* robust -* "``satisfactory``", +* satisfactory -* "``several``", +* several -* "``shall be included but not limited to``", +* shall be included but not limited to -* "``simple``", +* simple -* "``small``", +* small -* "``some``", +* some -* "``state of the art``", +* state of the art -* "``sufficient``", +* sufficient -* "``suitable``", +* suitable -* "``support``", +* support -* "``systematically``", +* systematically -* "``transparent``", +* transparent -* "``typical``", +* typical -* "``user friendly``", +* user friendly -* "``usually``", +* usually -* "``versatile``", and +* versatile -* "``when necessary``". +* when necessary This type is used by the following types: @@ -4467,10 +5242,6 @@ This type is used by the following types: * :ref:`SpecTypeApplicationConfigurationGroupItemType` -* :ref:`SpecTypeApplicationConfigurationOptionConstraintSet` - -* :ref:`SpecTypeApplicationConfigurationOptionItemType` - * :ref:`SpecTypeConstraintItemType` * :ref:`SpecTypeInterfaceGroupItemType` @@ -4485,31 +5256,13 @@ 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. -.. _SpecTypeRequirementValidationMethod: - -Requirement Validation Method -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The value shall be a string. This value type characterizes a requirement -validation method (except validation by test). The value shall be an element of - -* "``by-analysis``", - -* "``by-inspection``", and - -* "``by-review-of-design``". - -This type is used by the following types: - -* :ref:`SpecTypeRequirementValidationItemType` - -.. _SpecTypeRuntimeMeasurementEnvironment: +.. _SpecTypeRuntimeMeasurementEnvironmentName: -Runtime Measurement Environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Runtime Measurement Environment Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The value shall be a string. It specifies the runtime measurement environment. -The value +The value shall be a string. It specifies the runtime measurement environment +name. The value * shall be an element of @@ -4532,12 +5285,12 @@ 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:`SpecTypeRuntimeMeasurementEnvironment`. Each +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:`SpecTypeRuntimePerformanceLimitTable` +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` .. _SpecTypeRuntimeMeasurementParameterSet: @@ -4586,6 +5339,10 @@ value. The value shall be an element of * "``mean-upper-bound``", +* "``median-lower-bound``", + +* "``median-upper-bound``", + * "``min-lower-bound``", and * "``min-upper-bound``". @@ -4609,21 +5366,6 @@ This type is used by the following types: * :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` -.. _SpecTypeRuntimePerformanceLimitTable: - -Runtime Performance Limit Table -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This set of attributes provides runtime performance limits for BSP variants -specified by ``"<arch>/<bsp>"`` with <arch> being the architecture of the BSP -and <bsp> being the base name of the BSP. Generic attributes may be specified. -Each generic attribute key shall be a string. Each generic attribute value -shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. - -This type is used by the following types: - -* :ref:`SpecTypeRuntimePerformanceRequirementItemType` - .. _SpecTypeRuntimePerformanceParameterSet: Runtime Performance Parameter Set @@ -4637,6 +5379,19 @@ 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 @@ -5212,7 +5967,11 @@ 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 +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. @@ -5220,13 +5979,11 @@ checks The attribute value shall be a list. Each list element shall be a :ref:`SpecTypeTestCaseCheck`. -description - The attribute value shall be an optional string. It shall be the test case - action description. - links The attribute value shall be a list. Each list element shall be a - :ref:`SpecTypeLink`. + :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: @@ -5240,17 +5997,19 @@ Test Case Check This set of attributes specifies a test case check. All explicit attributes shall be specified. The explicit attributes for this type are: -check +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. -description - The attribute value shall be an optional string. It shall be the test case - check description. - links The attribute value shall be a list. Each list element shall be a - :ref:`SpecTypeLink`. + :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: @@ -5280,7 +6039,7 @@ A value of this type shall be of one of the following variants: member definition. It shall be a valid C structure member definition without a trailing ``;``. -* There may by be no value (null). +* There may be no value (null). This type is used by the following types: @@ -5288,6 +6047,8 @@ This type is used by the following types: * :ref:`SpecTypeRuntimeMeasurementTestItemType` +* :ref:`SpecTypeTestCaseItemType` + .. _SpecTypeTestHeader: Test Header @@ -5310,6 +6071,12 @@ A value of this type shall be of one of the following variants: 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 <...>``. @@ -5326,7 +6093,7 @@ A value of this type shall be of one of the following variants: The attribute value shall be a string. It shall be the path to the generated test header file. -* There may by be no value (null). +* There may be no value (null). This type is used by the following types: @@ -5388,7 +6155,7 @@ A value of this type shall be of one of the following variants: The attribute value shall be an optional string. It shall be the test support method description. -* There may by be no value (null). +* There may be no value (null). This type is used by the following types: @@ -5398,6 +6165,8 @@ This type is used by the following types: * :ref:`SpecTypeRuntimePerformanceRequirementItemType` +* :ref:`SpecTypeTestCaseItemType` + .. _SpecTypeUID: UID @@ -5409,3 +6178,18 @@ 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. |