diff options
Diffstat (limited to 'eng/req/items.rst')
| -rw-r--r-- | eng/req/items.rst | 2247 |
1 files changed, 1710 insertions, 537 deletions
diff --git a/eng/req/items.rst b/eng/req/items.rst index 0529d0a..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,8 +115,22 @@ 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` * :ref:`SpecTypeTestCaseItemType` @@ -179,10 +199,14 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceItemType` +* :ref:`SpecTypeProxyItemTypes` + * :ref:`SpecTypeRequirementItemType` * :ref:`SpecTypeRequirementValidationItemType` +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + * :ref:`SpecTypeSpecificationItemType` * :ref:`SpecTypeTestCaseItemType` @@ -270,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`. @@ -311,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: [] @@ -377,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 @@ -447,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: [] @@ -495,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`. @@ -522,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 @@ -593,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 @@ -617,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 @@ -652,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 @@ -682,8 +730,6 @@ option. The following explicit attributes are mandatory: * ``default`` -* ``default-by-variant`` - * ``description`` The explicit attributes for this type are: @@ -697,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 @@ -731,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 @@ -827,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`. @@ -842,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: | @@ -902,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: [] @@ -978,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 @@ -1009,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. @@ -1103,8 +1144,6 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceCompoundItemType` -* :ref:`SpecTypeInterfaceContainerItemType` - * :ref:`SpecTypeInterfaceDefineItemType` * :ref:`SpecTypeInterfaceDomainItemType` @@ -1115,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 @@ -1166,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 @@ -1177,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` @@ -1231,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: @@ -1276,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 @@ -1321,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: @@ -1399,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`. @@ -1485,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`. @@ -1506,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`. @@ -1518,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: @@ -1552,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-enum`` * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if - the value is ``unspecified-define`` + 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: @@ -1570,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: @@ -1601,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 @@ -1616,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 @@ -1639,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: [] @@ -1729,8 +1834,8 @@ test-cleanup action loop body after the test post-condition checks. test-context - The attribute value shall be a list. Each list element shall be an - :ref:`SpecTypeActionRequirementTestContextMember`. + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. test-context-support The attribute value shall be an optional string. If the value is present, @@ -1758,12 +1863,10 @@ test-prepare the test action loop body before the test pre-condition preparations. test-setup - The attribute value shall be an - :ref:`SpecTypeActionRequirementTestFixtureMethod`. + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. test-stop - The attribute value shall be an - :ref:`SpecTypeActionRequirementTestFixtureMethod`. + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. test-support The attribute value shall be an optional string. If the value is present, @@ -1775,8 +1878,7 @@ test-target generated test case source file. test-teardown - The attribute value shall be an - :ref:`SpecTypeActionRequirementTestFixtureMethod`. + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. transition-map The attribute value shall be a list. Each list element shall be an @@ -1788,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: [] @@ -1924,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`` @@ -1943,8 +2048,252 @@ attributes specifies a non-functional requirement. All explicit attributes shall be specified. The explicit attributes for this type are: non-functional-type - The attribute value shall be a :ref:`SpecTypeRequirementNonFunctionalType`. - It shall be the non-functional type of the requirement. + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + non-functional type of the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeDesignGroupRequirementItemType` + +* :ref:`SpecTypeDesignTargetItemType` + +* :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +.. _SpecTypeDesignGroupRequirementItemType: + +Design Group Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``design-group``. This +set of attributes specifies a design group requirement. Design group +requirements have an explicit reference to the associated Doxygen group +specified by the ``identifier`` attribute. Design group requirements have an +implicit validation by inspection method. The qualification toolchain shall +perform the inspection and check that the specified Doxygen group exists in the +software source code. All explicit attributes shall be specified. The explicit +attributes for this type are: + +identifier + The attribute value shall be a + :ref:`SpecTypeRequirementDesignGroupIdentifier`. + +.. _SpecTypeDesignTargetItemType: + +Design Target Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``design-target``. This +set of attributes specifies a design :term:`target`. All explicit attributes +shall be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an optional string. If the value is present, + then it shall briefly describe the target. + +description + The attribute value shall be an optional string. If the value is present, + then it shall thoroughly describe the target. + +name + The attribute value shall be a string. It shall be the target name. + +.. _SpecTypeGenericNonFunctionalRequirementItemType: + +Generic Non-Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``build-configuration`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``constraint`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``design`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``documentation`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``interface`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``interface-requirement`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``maintainability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``performance`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is + ``performance-runtime-limits`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``portability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``quality`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``reliability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``resource`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``safety`` + +Items of this type state a non-functional requirement with the non-functional +type defined by the specification type refinement. + +.. _SpecTypeRuntimeMeasurementEnvironmentItemType: + +Runtime Measurement Environment Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is +``performance-runtime-environment``. This set of attributes specifies a runtime +measurement environment. All explicit attributes shall be specified. The +explicit attributes for this type are: + +name + The attribute value shall be a string. It shall be the runtime measurement + environment name. See also + :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. + +.. _SpecTypeRuntimePerformanceRequirementItemType: + +Runtime Performance Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``performance-runtime``. +The item shall have exactly one link with the +:ref:`SpecTypeRuntimeMeasurementRequestLinkRole`. A requirement text processor +shall support a substitution of ${.:/limit-kind}: + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound`` or + ``min-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"minimum"``. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``mean-lower-bound`` or + ``mean-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"mean"``. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``max-lower-bound`` or + ``max-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"maximum"``. + +A requirement text processor shall support a substitution of +${.:/limit-condition}: + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound``, + ``mean-lower-bound``, or ``max-lower-bound``, the substitution of + ${.:/limit-condition} shall be ``"greater than or equal to <value>"`` with + <value> being the value of the corresponding entry in the + :ref:`SpecTypeRuntimeMeasurementValueTable`. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-upper-bound``, + ``mean-upper-bound``, or ``max-upper-bound``, the substitution of + ${.:/limit-condition} shall be ``"less than or equal to <value>"`` with + <value> being the value of the corresponding entry in the + :ref:`SpecTypeRuntimeMeasurementValueTable`. + +A requirement text processor shall support a substitution of ${.:/environment}. +The value of the substitution shall be ``"<environment> environment"`` with +<environment> being the environment of the corresponding entry in the +:ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. + +This set of attributes specifies a runtime performance requirement. Along with +the requirement, the validation test code to execute a measure runtime request +is specified. All explicit attributes shall be specified. The explicit +attributes for this type are: + +params + The attribute value shall be a + :ref:`SpecTypeRuntimePerformanceParameterSet`. + +test-body + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It shall + provide the code of the measure runtime body handler. In contrast to other + methods, this method is mandatory. + +test-cleanup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code to clean up the measure runtime request. This method is + called before the cleanup method of the corresponding + :ref:`SpecTypeRuntimeMeasurementTestItemType` item and after the request. + +test-prepare + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code to prepare the measure runtime request. This method is + called after the prepare method of the corresponding + :ref:`SpecTypeRuntimeMeasurementTestItemType` item and before the request. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code of the measure runtime setup handler. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code of the measure runtime teardown handler. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + links: + - role: runtime-measurement-request + uid: ../val/perf + params: {} + rationale: null + references: [] + test-body: + brief: | + Get a buffer. + code: | + ctx->status = rtems_partition_get_buffer( ctx->part_many, &ctx->buffer ); + description: null + test-cleanup: null + test-prepare: null + test-setup: null + test-teardown: + brief: | + Return the buffer. + code: | + rtems_status_code sc; + + T_quiet_rsc_success( ctx->status ); + + sc = rtems_partition_return_buffer( ctx->part_many, ctx->buffer ); + T_quiet_rsc_success( sc ); + + return tic == toc; + description: null + text: | + When a partition has exactly ${../val/perf:/params/buffer-count} free + buffers, the ${.:/limit-kind} runtime of exactly + ${../val/perf:/params/sample-count} successful calls to + ${../if/get-buffer:/name} in the ${.:/environment} shall be + ${.:/limit-condition}. + non-functional-type: performance-runtime + requirement-type: non-functional + type: requirement .. _SpecTypeRequirementValidationItemType: @@ -1959,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 @@ -1975,6 +2329,96 @@ 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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``runtime-measurement-test``. This set of attributes +specifies a runtime measurement test case. All explicit attributes shall be +specified. The explicit attributes for this type are: + +params + The attribute value shall be a + :ref:`SpecTypeRuntimeMeasurementParameterSet`. + +test-brief + The attribute value shall be an optional string. If the value is present, + then it shall be the test case brief description. + +test-cleanup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the measure runtime request cleanup + method. The method is called after each measure runtime request. + +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. + +test-context-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test context support code. The context support code + is placed at file scope before the test context definition. + +test-description + The attribute value shall be an optional string. If the value is present, + then it shall be the test case description. + +test-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. + +test-local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. + +test-prepare + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the measure runtime request prepare + method. The method is called before each measure runtime request. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case setup fixture method. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case stop fixture method. + +test-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test case support code. The support code is placed at + file scope before the test case code. + +test-target + The attribute value shall be a string. It shall be the path to the + generated test case source file. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case teardown fixture method. + .. _SpecTypeSpecificationItemType: Specification Item Type @@ -2010,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 @@ -2057,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`. @@ -2083,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, @@ -2098,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 @@ -2153,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 @@ -2187,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 @@ -2208,19 +2715,113 @@ test-epilogue then it shall be the test epilogue code. The epilogue code is placed in the test condition preparation or check before the state-specific code. The code may use a local variable ``ctx`` which points to the test context, see - :ref:`SpecTypeActionRequirementTestContextMember`. + :ref:`SpecTypeTestContextMember`. test-prologue The attribute value shall be an optional string. If the value is present, then it shall be the test prologue code. The prologue code is placed in the test condition preparation or check after the state-specific code. The code may use a local variable ``ctx`` which points to the test context, see - :ref:`SpecTypeActionRequirementTestContextMember`. + :ref:`SpecTypeTestContextMember`. This type is used by the following types: * :ref:`SpecTypeActionRequirementItemType` +.. _SpecTypeActionRequirementExpression: + +Action Requirement Expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines an expression which may define the state of a +post-condition. The ``else`` and ``specified-by`` shall be used individually. +The ``if`` and ``then`` or ``then-specified-by`` expressions shall be used +together. At least one of the explicit attributes shall be specified. The +explicit attributes for this type are: + +else + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name + of the state of the post-condition. + +if + The attribute value shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. If the boolean + expression evaluates to true, then the state is defined according to the + ``then`` attribute value. + +specified-by + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It + shall be the name of a pre-condition. The name of the state of the + pre-condition in the associated transition defines the name of the state of + the post-condition. + +then + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name + of the state of the post-condition. + +then-specified-by + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It + shall be the name of a pre-condition. The name of the state of the + pre-condition in the associated transition defines the name of the state of + the post-condition. + +.. _SpecTypeActionRequirementExpressionConditionSet: + +Action Requirement Expression Condition Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines for the specified conditions a set of states. +Generic attributes may be specified. Each generic attribute key shall be an +:ref:`SpecTypeActionRequirementName`. Each generic attribute value shall be an +:ref:`SpecTypeActionRequirementExpressionStateSet`. There shall be at most one +generic attribute key for each condition. The key name shall be the condition +name. The value of each generic attribute shall be a set of states of the +condition. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementBooleanExpression` + +.. _SpecTypeActionRequirementExpressionStateName: + +Action Requirement Expression State Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the name of a state of the condition +or ``N/A`` if the condition is not applicable. The value + +* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + +* or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementExpression` + +.. _SpecTypeActionRequirementExpressionStateSet: + +Action Requirement Expression State Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. The list defines a set + of states of the condition. + +* The value may be a string. It shall be the name of a state of the condition + or ``N/A`` if the condition is not applicable. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + .. _SpecTypeActionRequirementName: Action Requirement Name @@ -2234,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``". @@ -2242,6 +2843,10 @@ This type is used by the following types: * :ref:`SpecTypeActionRequirementCondition` +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + +* :ref:`SpecTypeActionRequirementExpression` + * :ref:`SpecTypeActionRequirementSkipReasons` * :ref:`SpecTypeActionRequirementState` @@ -2284,7 +2889,7 @@ test-code The attribute value shall be a string. It shall be the test code to prepare or check the state of the condition. The code may use a local variable ``ctx`` which points to the test context, see - :ref:`SpecTypeActionRequirementTestContextMember`. + :ref:`SpecTypeTestContextMember`. text The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall @@ -2294,66 +2899,6 @@ This type is used by the following types: * :ref:`SpecTypeActionRequirementCondition` -.. _SpecTypeActionRequirementTestContextMember: - -Action Requirement Test Context Member -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A value of this type shall be of one of the following variants: - -* The value may be a set of attributes. This set of attributes defines an - action requirement test context member. All explicit attributes shall be - specified. The explicit attributes for this type are: - - brief - The attribute value shall be an optional string. It shall be the test - context member brief description. - - description - The attribute value shall be an optional string. It shall be the test - context member description. - - member - The attribute value shall be a string. It shall be the test context - member definition. It shall be a valid C structure member definition - without a trailing ``;``. - -* There may by be no value (null). - -This type is used by the following types: - -* :ref:`SpecTypeActionRequirementItemType` - -.. _SpecTypeActionRequirementTestFixtureMethod: - -Action Requirement Test Fixture Method -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A value of this type shall be of one of the following variants: - -* The value may be a set of attributes. This set of attributes defines an - action requirement test fixture method. All explicit attributes shall be - specified. The explicit attributes for this type are: - - brief - The attribute value shall be an optional string. It shall be the test - fixture method brief description. - - code - The attribute value shall be a string. It shall be the test fixture - method code. The code may use a local variable ``ctx`` which points to - the test context, see :ref:`SpecTypeActionRequirementTestContextMember`. - - description - The attribute value shall be an optional string. It shall be the test - fixture method description. - -* There may by be no value (null). - -This type is used by the following types: - -* :ref:`SpecTypeActionRequirementItemType` - .. _SpecTypeActionRequirementTransition: Action Requirement Transition @@ -2389,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 @@ -2400,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``". @@ -2445,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: @@ -2564,6 +3100,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildBSPItemType` +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -2590,6 +3128,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildBSPItemType` +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -2612,6 +3152,10 @@ context. This type is used by the following types: +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -2622,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 @@ -2698,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`. @@ -2919,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 @@ -2995,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: @@ -3033,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: @@ -3059,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. @@ -3067,9 +3640,7 @@ This type is used by the following types: * :ref:`SpecTypeBuildOptionAction` -* :ref:`SpecTypeBuildOptionDefaultByVariant` - -* :ref:`SpecTypeBuildOptionItemType` +* :ref:`SpecTypeBuildOptionDefaultValue` .. _SpecTypeBuildSource: @@ -3112,6 +3683,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildLibraryItemType` +* :ref:`SpecTypeBuildScriptItemType` + * :ref:`SpecTypeBuildStartFileItemType` * :ref:`SpecTypeBuildTestProgramItemType` @@ -3253,6 +3826,10 @@ This type is used by the following types: * :ref:`SpecTypeActionRequirementTransition` +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildOptionDefaultValue` + * :ref:`SpecTypeEnabledByExpression` * :ref:`SpecTypeInterfaceIncludeLinkRole` @@ -3268,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 @@ -3289,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` @@ -3302,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 @@ -3320,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 @@ -3396,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: @@ -3481,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. @@ -3516,8 +4204,6 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnumeratorItemType` -* :ref:`SpecTypeInterfaceMacroItemType` - * :ref:`SpecTypeInterfaceTypedefItemType` * :ref:`SpecTypeInterfaceVariableItemType` @@ -3551,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 @@ -3573,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` @@ -3587,6 +4271,12 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + .. _SpecTypeInterfaceEnabledByExpression: Interface Enabled-By Expression @@ -3634,7 +4324,11 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceEnabledByExpression` -* :ref:`SpecTypeInterfaceFunctionDefinitionVariant` +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` .. _SpecTypeInterfaceEnumDefinitionKind: @@ -3664,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 @@ -3744,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: @@ -3770,6 +4471,8 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceGroupItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeInterfaceGroupMembershipLinkRole: Interface Group Membership Link Role @@ -3779,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 @@ -3802,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. @@ -3816,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 @@ -3844,9 +4559,9 @@ name This type is used by the following types: -* :ref:`SpecTypeInterfaceFunctionItemType` +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` -* :ref:`SpecTypeInterfaceMacroItemType` +* :ref:`SpecTypeInterfaceTypedefItemType` .. _SpecTypeInterfaceParameterDirection: @@ -3855,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 @@ -3887,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: @@ -3952,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` @@ -3966,22 +4688,34 @@ 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` +* :ref:`SpecTypeRuntimeMeasurementRequestLinkRole` + * :ref:`SpecTypeSpecificationMemberLinkRole` * :ref:`SpecTypeSpecificationRefinementLinkRole` +* :ref:`SpecTypeUnitTestLinkRole` + This type is used by the following types: * :ref:`SpecTypeRootItemType` @@ -4004,7 +4738,7 @@ This type is used by the following types: * :ref:`SpecTypeBuildItemType` -* :ref:`SpecTypeBuildOptionSetTestStateAction` +* :ref:`SpecTypeExternalReference` * :ref:`SpecTypeFunctionalRequirementItemType` @@ -4014,10 +4748,20 @@ This type is used by the following types: * :ref:`SpecTypeLink` +* :ref:`SpecTypeNonFunctionalRequirementItemType` + +* :ref:`SpecTypeRegisterDefinition` + * :ref:`SpecTypeRequirementItemType` +* :ref:`SpecTypeRequirementValidationItemType` + * :ref:`SpecTypeRootItemType` +* :ref:`SpecTypeRuntimeMeasurementParameterSet` + +* :ref:`SpecTypeRuntimePerformanceParameterSet` + * :ref:`SpecTypeSpecificationAttributeValue` * :ref:`SpecTypeSpecificationExplicitAttributes` @@ -4030,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 @@ -4037,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 @@ -4051,87 +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). -.. _SpecTypeRequirementNonFunctionalType: +.. _SpecTypeProxyMemberLinkRole: -Requirement Non-Functional Type -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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: -The value shall be a string. This type shall be used for non-functional -requirement types. The value shall be an element of +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`. -* "``build-configuration``", + name + The attribute value shall be a string. It shall be the name of the + register bit field. -* "``constraint``", + 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. -* "``design``", + 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. -* "``documentation``", + width + The attribute value shall be an integer number. It shall be the width in + bits of the bit field. -* "``interface``", +* There may be no value (null). -* "``interface-requirement``", +This type is used by the following types: -* "``maintainability``", +* :ref:`SpecTypeRegisterBitsDefinitionDirective` -* "``performance``", +* :ref:`SpecTypeRegisterBitsDefinitionVariant` -* "``portability``", +.. _SpecTypeRegisterBitsDefinitionDirective: -* "``quality``", +Register Bits Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* "``reliability``", +This set of attributes specifies a register bits directive. All explicit +attributes shall be specified. The explicit attributes for this type are: -* "``resource``", and +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. -* "``safety``". +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:`SpecTypeNonFunctionalRequirementItemType` +* :ref:`SpecTypeRegisterDefinition` -.. _SpecTypeRequirementReference: +.. _SpecTypeRegisterBitsDefinitionVariant: -Requirement Reference -^^^^^^^^^^^^^^^^^^^^^ +Register Bits Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies a requirement reference. All explicit +This set of attributes specifies a register bits variant. 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. +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. -type - The attribute value shall be a :ref:`SpecTypeRequirementReferenceType`. +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. This type is used by the following types: -* :ref:`SpecTypeRequirementItemType` +* :ref:`SpecTypeRegisterBitsDefinitionDirective` -.. _SpecTypeRequirementReferenceType: +.. _SpecTypeRegisterBlockIncludeRole: -Requirement Reference Type -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Register Block Include Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``register-block-include``. It defines the register block include role +of links. Links of this role are used to build register blocks using other +register blocks. All explicit attributes shall be specified. The explicit +attributes for this type are: + +name + The attribute value shall be a string. It shall be a name to identify the + included register block within the item. The name shall be unique within + the scope of the item links of this role and the + :ref:`SpecTypeRegisterList`. + +.. _SpecTypeRegisterBlockMemberDefinition: + +Register Block Member Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies a + register block member definition. All explicit attributes shall be specified. + The explicit attributes for this type are: + + count + The attribute value shall be an integer number. It shall be the count of + registers of the register block member. + + name + The attribute value shall be a :ref:`SpecTypeRegisterName`. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + +.. _SpecTypeRegisterBlockMemberDefinitionDirective: + +Register Block Member Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition directive. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +default + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. The default definition will + be used if no variant-specific definition is enabled. + +offset + The attribute value shall be an integer number. It shall be the address of + the register block member relative to the base address of the register + block. + +variants + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterBlockMemberDefinitionVariant: -The value shall be a string. It specifies the type of a requirement reference. -The value shall be an element of +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. -* "``define``", +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. -* "``file``", +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` -* "``function``", +.. _SpecTypeRequirementDesignGroupIdentifier: -* "``group``", +Requirement Design Group Identifier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: -* "``macro``", and +* There may be no value (null). -* "``variable``". +* 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:`SpecTypeRequirementReference` +* :ref:`SpecTypeDesignGroupRequirementItemType` .. _SpecTypeRequirementRefinementLinkRole: @@ -4147,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: @@ -4278,10 +5242,6 @@ This type is used by the following types: * :ref:`SpecTypeApplicationConfigurationGroupItemType` -* :ref:`SpecTypeApplicationConfigurationOptionConstraintSet` - -* :ref:`SpecTypeApplicationConfigurationOptionItemType` - * :ref:`SpecTypeConstraintItemType` * :ref:`SpecTypeInterfaceGroupItemType` @@ -4296,23 +5256,141 @@ 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: +.. _SpecTypeRuntimeMeasurementEnvironmentName: -Requirement Validation Method -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Runtime Measurement Environment Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the runtime measurement environment +name. The value + +* shall be an element of -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 + * "``FullCache``", -* "``by-analysis``", + * "``HotCache``", and -* "``by-inspection``", and + * "``DirtyCache``", -* "``by-review-of-design``". +* or, shall match with the regular expression "``^Load/[1-9][0-9]*$``". This type is used by the following types: -* :ref:`SpecTypeRequirementValidationItemType` +* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` + +.. _SpecTypeRuntimeMeasurementEnvironmentTable: + +Runtime Measurement Environment Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes provides runtime performance limits for a set of runtime +measurement environments. Generic attributes may be specified. Each generic +attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. Each +generic attribute value shall be a :ref:`SpecTypeRuntimeMeasurementValueTable`. + +This type is used by the following types: + +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + +.. _SpecTypeRuntimeMeasurementParameterSet: + +Runtime Measurement Parameter Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines parameters of the runtime measurement test case. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +sample-count + The attribute value shall be an integer number. It shall be the sample + count of the runtime measurement context. + +In addition to the explicit attributes, generic attributes may be specified. +Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value +may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +.. _SpecTypeRuntimeMeasurementRequestLinkRole: + +Runtime Measurement Request Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``runtime-measurement-request``. It defines the runtime measurement +request role of links. The link target shall be a +:ref:`SpecTypeRuntimeMeasurementTestItemType` item. + +.. _SpecTypeRuntimeMeasurementValueKind: + +Runtime Measurement Value Kind +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the kind of a runtime measurement +value. The value shall be an element of + +* "``max-lower-bound``", + +* "``max-upper-bound``", + +* "``mean-lower-bound``", + +* "``mean-upper-bound``", + +* "``median-lower-bound``", + +* "``median-upper-bound``", + +* "``min-lower-bound``", and + +* "``min-upper-bound``". + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementValueTable` + +.. _SpecTypeRuntimeMeasurementValueTable: + +Runtime Measurement Value Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes provides a set of runtime measurement values each of a +specified kind. The unit of the values shall be one second. Generic attributes +may be specified. Each generic attribute key shall be a +:ref:`SpecTypeRuntimeMeasurementValueKind`. Each generic attribute value shall +be a floating-point number. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` + +.. _SpecTypeRuntimePerformanceParameterSet: + +Runtime Performance Parameter Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines parameters of the runtime performance +requirement. Generic attributes may be specified. Each generic attribute key +shall be a :ref:`SpecTypeName`. The attribute value may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +.. _SpecTypeSHA256HashValue: + +SHA256 Hash Value +^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be a SHA256 hash value encoded in +base64url. The value shall match with the regular expression +"``^[A-Za-z0-9+_=-]{44}$``". + +This type is used by the following types: + +* :ref:`SpecTypeExternalFileReference` .. _SpecTypeSPDXLicenseIdentifier: @@ -4889,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. @@ -4897,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: @@ -4917,22 +5997,58 @@ 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: * :ref:`SpecTypeTestCaseAction` +.. _SpecTypeTestContextMember: + +Test Context Member +^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes defines an + action requirement test context member. All explicit attributes shall be + specified. The explicit attributes for this type are: + + brief + The attribute value shall be an optional string. It shall be the test + context member brief description. + + description + The attribute value shall be an optional string. It shall be the test + context member description. + + member + The attribute value shall be a string. It shall be the test context + member definition. It shall be a valid C structure member definition + without a trailing ``;``. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeTestCaseItemType` + .. _SpecTypeTestHeader: Test Header @@ -4955,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 <...>``. @@ -4971,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: @@ -4987,8 +6109,8 @@ Test Run Parameter This set of attributes specifies a parameter for the test run function. In case this parameter is used in an :ref:`SpecTypeActionRequirementItemType` item, then the parameter is also added as a member to the test context, see -:ref:`SpecTypeActionRequirementTestContextMember`. All explicit attributes -shall be specified. The explicit attributes for this type are: +:ref:`SpecTypeTestContextMember`. All explicit attributes shall be specified. +The explicit attributes for this type are: description The attribute value shall be a string. It shall be the description of the @@ -5009,6 +6131,42 @@ This type is used by the following types: * :ref:`SpecTypeTestHeader` +.. _SpecTypeTestSupportMethod: + +Test Support Method +^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes defines an + action requirement test support method. All explicit attributes shall be + specified. The explicit attributes for this type are: + + brief + The attribute value shall be an optional string. It shall be the test + support method brief description. + + code + The attribute value shall be a string. It shall be the test support + method code. The code may use a local variable ``ctx`` which points to + the test context, see :ref:`SpecTypeTestContextMember`. + + description + The attribute value shall be an optional string. It shall be the test + support method description. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +* :ref:`SpecTypeTestCaseItemType` + .. _SpecTypeUID: UID @@ -5020,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. |