diff options
Diffstat (limited to '')
| -rw-r--r-- | eng/req/items.rst | 991 |
1 files changed, 755 insertions, 236 deletions
diff --git a/eng/req/items.rst b/eng/req/items.rst index e718605..286e998 100644 --- a/eng/req/items.rst +++ b/eng/req/items.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2022 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 @@ -95,10 +95,16 @@ The specification item types have the following hierarchy: * :ref:`SpecTypeInterfaceTypedefItemType` + * :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + * :ref:`SpecTypeInterfaceUnspecifiedItemType` * :ref:`SpecTypeInterfaceVariableItemType` + * :ref:`SpecTypeRegisterBlockItemType` + + * :ref:`SpecTypeProxyItemTypes` + * :ref:`SpecTypeRequirementItemType` * :ref:`SpecTypeFunctionalRequirementItemType` @@ -111,8 +117,12 @@ The specification item types have the following hierarchy: * :ref:`SpecTypeDesignGroupRequirementItemType` + * :ref:`SpecTypeDesignTargetItemType` + * :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + * :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + * :ref:`SpecTypeRuntimePerformanceRequirementItemType` * :ref:`SpecTypeRequirementValidationItemType` @@ -189,6 +199,8 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceItemType` +* :ref:`SpecTypeProxyItemTypes` + * :ref:`SpecTypeRequirementItemType` * :ref:`SpecTypeRequirementValidationItemType` @@ -327,7 +339,7 @@ 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 @@ -394,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 @@ -464,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: [] @@ -553,7 +565,7 @@ Please have a look at the following example: 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: @@ -625,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 @@ -649,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 @@ -684,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 @@ -714,8 +730,6 @@ option. The following explicit attributes are mandatory: * ``default`` -* ``default-by-variant`` - * ``description`` The explicit attributes for this type are: @@ -729,19 +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 checked two times - and processed from top to bottom. Firstly, the base BSP name is used to - match with a variant. Secondly, the BSP family name prefixed by ``bsps/`` - is used to match with a variant. 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 @@ -766,17 +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 @@ -863,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`. @@ -878,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: | @@ -938,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: [] @@ -1014,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 @@ -1153,10 +1162,14 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceTypedefItemType` +* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + * :ref:`SpecTypeInterfaceUnspecifiedItemType` * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeApplicationConfigurationGroupItemType: Application Configuration Group Item Type @@ -1528,6 +1541,24 @@ params return The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`. +.. _SpecTypeInterfaceUnspecifiedHeaderFileItemType: + +Interface Unspecified Header File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``unspecified-header-file``. This +set of attributes specifies an unspecified header file. All explicit attributes +shall be specified. The explicit attributes for this type are: + +path + The attribute value shall be a string. It shall be the path used to include + the header file. For example :file:`rtems/confdefs.h`. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + .. _SpecTypeInterfaceUnspecifiedItemType: Interface Unspecified Item Type @@ -1539,9 +1570,6 @@ This type refines the following types: the value is ``unspecified-define`` * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if - the value is ``unspecified-define-or-object`` - -* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if the value is ``unspecified-enum`` * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if @@ -1557,9 +1585,6 @@ This type refines the following types: the value is ``unspecified-macro`` * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if - the value is ``unspecified-macro-or-function`` - -* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if the value is ``unspecified-object`` * :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if @@ -1579,7 +1604,8 @@ name unspecified interface. references - The attribute value shall be an :ref:`SpecTypeInterfaceReferencesSet`. + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. .. _SpecTypeInterfaceVariableItemType: @@ -1608,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 @@ -1623,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 @@ -1646,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: [] @@ -1792,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: [] @@ -1928,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`` @@ -1954,8 +2055,12 @@ This type is refined by the following types: * :ref:`SpecTypeDesignGroupRequirementItemType` +* :ref:`SpecTypeDesignTargetItemType` + * :ref:`SpecTypeGenericNonFunctionalRequirementItemType` +* :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + * :ref:`SpecTypeRuntimePerformanceRequirementItemType` .. _SpecTypeDesignGroupRequirementItemType: @@ -1974,7 +2079,29 @@ software source code. All explicit attributes shall be specified. The explicit attributes for this type are: identifier - The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`. + 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: @@ -2008,6 +2135,10 @@ This type refines the following types: ``non-functional-type`` attribute if the value is ``performance`` * :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is + ``performance-runtime-limits`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the ``non-functional-type`` attribute if the value is ``portability`` * :ref:`SpecTypeNonFunctionalRequirementItemType` through the @@ -2025,6 +2156,22 @@ This type refines the following types: Items of this type state a non-functional requirement with the non-functional type defined by the specification type refinement. +.. _SpecTypeRuntimeMeasurementEnvironmentItemType: + +Runtime Measurement Environment Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is +``performance-runtime-environment``. This set of attributes specifies a runtime +measurement environment. All explicit attributes shall be specified. The +explicit attributes for this type are: + +name + The attribute value shall be a string. It shall be the runtime measurement + environment name. See also + :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. + .. _SpecTypeRuntimePerformanceRequirementItemType: Runtime Performance Requirement Item Type @@ -2073,9 +2220,6 @@ the requirement, the validation test code to execute a measure runtime request is specified. All explicit attributes shall be specified. The explicit attributes for this type are: -limits - The attribute value shall be a :ref:`SpecTypeRuntimePerformanceLimitTable`. - params The attribute value shall be a :ref:`SpecTypeRuntimePerformanceParameterSet`. @@ -2111,34 +2255,11 @@ Please have a look at the following example: SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true links: - role: runtime-measurement-request - uid: ../val/performance - limits: - sparc/leon3: - DirtyCache: - max-upper-bound: 0.000005 - mean-upper-bound: 0.000005 - FullCache: - max-upper-bound: 0.000005 - mean-upper-bound: 0.000005 - HotCache: - max-upper-bound: 0.000005 - mean-upper-bound: 0.000005 - Load/1: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 - Load/2: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 - Load/3: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 - Load/4: - max-upper-bound: 0.00001 - mean-upper-bound: 0.00001 + uid: ../val/perf params: {} rationale: null references: [] @@ -2165,11 +2286,11 @@ Please have a look at the following example: return tic == toc; description: null text: | - When a partition has exactly ${../val/performance:/params/buffer-count} free - buffers, the ${.:limit-kind} runtime of exactly - ${../val/performance:/params/sample-count} successful calls to + When a partition has exactly ${../val/perf:/params/buffer-count} free + buffers, the ${.:/limit-kind} runtime of exactly + ${../val/perf:/params/sample-count} successful calls to ${../if/get-buffer:/name} in the ${.:/environment} shall be - ${.:limit-condition}. + ${.:/limit-condition}. non-functional-type: performance-runtime requirement-type: non-functional type: requirement @@ -2187,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 @@ -2328,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 @@ -2503,10 +2629,6 @@ test-local-includes The attribute value shall be a list of strings. It shall be a list of header files included via ``#include "..."``. -test-suite-name - The attribute value shall be a string. It shall be the name of the test - suite. - test-target The attribute value shall be a string. It shall be the path to the generated target test suite source file. @@ -2978,6 +3100,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildBSPItemType` +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -3004,6 +3128,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildBSPItemType` +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -3026,6 +3152,10 @@ context. This type is used by the following types: +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + * :ref:`SpecTypeBuildLibraryItemType` * :ref:`SpecTypeBuildObjectsItemType` @@ -3036,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 @@ -3415,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: @@ -3453,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: @@ -3487,9 +3640,7 @@ This type is used by the following types: * :ref:`SpecTypeBuildOptionAction` -* :ref:`SpecTypeBuildOptionDefaultByVariant` - -* :ref:`SpecTypeBuildOptionItemType` +* :ref:`SpecTypeBuildOptionDefaultValue` .. _SpecTypeBuildSource: @@ -3532,6 +3683,8 @@ This type is used by the following types: * :ref:`SpecTypeBuildLibraryItemType` +* :ref:`SpecTypeBuildScriptItemType` + * :ref:`SpecTypeBuildStartFileItemType` * :ref:`SpecTypeBuildTestProgramItemType` @@ -3673,6 +3826,10 @@ This type is used by the following types: * :ref:`SpecTypeActionRequirementTransition` +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildOptionDefaultValue` + * :ref:`SpecTypeEnabledByExpression` * :ref:`SpecTypeInterfaceIncludeLinkRole` @@ -3688,6 +3845,73 @@ 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 @@ -3699,6 +3923,33 @@ 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 @@ -3759,6 +4010,12 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + .. _SpecTypeInterfaceCompoundDefinitionKind: Interface Compound Definition Kind @@ -4014,6 +4271,12 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + .. _SpecTypeInterfaceEnabledByExpression: Interface Enabled-By Expression @@ -4063,6 +4326,10 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + .. _SpecTypeInterfaceEnumDefinitionKind: Interface Enum Definition Kind @@ -4202,10 +4469,10 @@ The value shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``". This type is used by the following types: -* :ref:`SpecTypeDesignGroupRequirementItemType` - * :ref:`SpecTypeInterfaceGroupItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeInterfaceGroupMembershipLinkRole: Interface Group Membership Link Role @@ -4270,6 +4537,8 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceVariableItemType` +* :ref:`SpecTypeRegisterBlockItemType` + .. _SpecTypeInterfaceParameter: Interface Parameter @@ -4328,20 +4597,6 @@ value is ``interface-placement``. It defines the interface placement role of links. It is used to indicate that an interface definition is placed into an interface container, for example a header file. -.. _SpecTypeInterfaceReferencesSet: - -Interface References Set -^^^^^^^^^^^^^^^^^^^^^^^^ - -This set of attributes defines references for the interface. Generic attributes -may be specified. Each generic attribute key shall be a :ref:`SpecTypeName`. -Each generic attribute value shall be a string. The key defines the reference -kind. The value shall be a kind-specific reference target. - -This type is used by the following types: - -* :ref:`SpecTypeInterfaceUnspecifiedItemType` - .. _SpecTypeInterfaceReturnDirective: Interface Return Directive @@ -4417,7 +4672,7 @@ uid This type is refined by the following types: -* :ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole` +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` * :ref:`SpecTypeBuildDependencyLinkRole` @@ -4441,8 +4696,14 @@ This type is refined by the following types: * :ref:`SpecTypeInterfaceTargetLinkRole` +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + * :ref:`SpecTypePlacementOrderLinkRole` +* :ref:`SpecTypeProxyMemberLinkRole` + +* :ref:`SpecTypeRegisterBlockIncludeRole` + * :ref:`SpecTypeRequirementRefinementLinkRole` * :ref:`SpecTypeRequirementValidationLinkRole` @@ -4477,7 +4738,7 @@ This type is used by the following types: * :ref:`SpecTypeBuildItemType` -* :ref:`SpecTypeBuildOptionSetTestStateAction` +* :ref:`SpecTypeExternalReference` * :ref:`SpecTypeFunctionalRequirementItemType` @@ -4485,14 +4746,16 @@ This type is used by the following types: * :ref:`SpecTypeInterfaceItemType` -* :ref:`SpecTypeInterfaceReferencesSet` - * :ref:`SpecTypeLink` * :ref:`SpecTypeNonFunctionalRequirementItemType` +* :ref:`SpecTypeRegisterDefinition` + * :ref:`SpecTypeRequirementItemType` +* :ref:`SpecTypeRequirementValidationItemType` + * :ref:`SpecTypeRootItemType` * :ref:`SpecTypeRuntimeMeasurementParameterSet` @@ -4511,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 @@ -4522,6 +4811,20 @@ A value of this type shall be of one of the following variants: * 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 @@ -4532,49 +4835,267 @@ value is ``placement-order``. This link role defines the placement order of items in a container item (for example an interface function in a header file or a documentation section). -.. _SpecTypeRequirementReference: +.. _SpecTypeProxyMemberLinkRole: -Requirement Reference -^^^^^^^^^^^^^^^^^^^^^ +Proxy Member Link Role +^^^^^^^^^^^^^^^^^^^^^^ -This set of attributes specifies a requirement reference. All explicit +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``proxy-member``. It defines the proxy member role of links. Items +may use this role to link to :ref:`SpecTypeProxyItemTypes` items. + +.. _SpecTypeRegisterBitsDefinition: + +Register Bits Definition +^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies a + register bit field. Single bits are bit fields with a width of one. All + explicit attributes shall be specified. The explicit attributes for this type + are: + + brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + + description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + + name + The attribute value shall be a string. It shall be the name of the + register bit field. + + properties + The attribute value shall be a list of strings. It shall be the list of + bit field properties. Properties are for example if the bit field can be + read or written, or an access has side-effects such as clearing a status. + + start + The attribute value shall be an integer number. It shall be the start bit + of the bit field. Bit ``0`` is the least-significant bit. + + width + The attribute value shall be an integer number. It shall be the width in + bits of the bit field. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBitsDefinitionDirective` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +.. _SpecTypeRegisterBitsDefinitionDirective: + +Register Bits Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register bits directive. All explicit attributes shall be specified. The explicit attributes for this type are: -identifier - The attribute value shall be a string. It shall be the type-specific - identifier of the reference target. For *group* references use the Doxygen - group identifier. +default + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinition`. The default definition will be used + if no variant-specific definition is enabled. -type - The attribute value shall be a :ref:`SpecTypeRequirementReferenceType`. +variants + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinitionVariant`. This type is used by the following types: -* :ref:`SpecTypeRequirementItemType` +* :ref:`SpecTypeRegisterDefinition` -.. _SpecTypeRequirementReferenceType: +.. _SpecTypeRegisterBitsDefinitionVariant: -Requirement Reference Type -^^^^^^^^^^^^^^^^^^^^^^^^^^ +Register Bits Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register bits variant. All explicit +attributes shall be specified. The explicit attributes for this type are: + +definition + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinition`. The definition will be used if the + expression defined by the ``enabled-by`` attribute evaluates to true. In + generated header files, the expression is evaluated by the C preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBitsDefinitionDirective` + +.. _SpecTypeRegisterBlockIncludeRole: -The value shall be a string. It specifies the type of a requirement reference. -The value shall be an element of +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: -* "``define``", +Register Block Member Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* "``file``", +A value of this type shall be of one of the following variants: -* "``function``", +* 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: -* "``group``", + count + The attribute value shall be an integer number. It shall be the count of + registers of the register block member. -* "``macro``", and + name + The attribute value shall be a :ref:`SpecTypeRegisterName`. -* "``variable``". +* There may be no value (null). This type is used by the following types: -* :ref:`SpecTypeRequirementReference` +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + +.. _SpecTypeRegisterBlockMemberDefinitionDirective: + +Register Block Member Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition directive. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +default + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. The default definition will + be used if no variant-specific definition is enabled. + +offset + The attribute value shall be an integer number. It shall be the address of + the register block member relative to the base address of the register + block. + +variants + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterBlockMemberDefinitionVariant: + +Register Block Member Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition variant. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +definition + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. The definition will be used + if the expression defined by the ``enabled-by`` attribute evaluates to + true. In generated header files, the expression is evaluated by the C + preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +.. _SpecTypeRegisterDefinition: + +Register Definition +^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register. All explicit attributes shall be +specified. The explicit attributes for this type are: + +bits + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinitionDirective`. + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name to identify the + register definition. The name shall be unique within the scope of the + :ref:`SpecTypeRegisterBlockIncludeRole` links of the item and the + :ref:`SpecTypeRegisterList`. + +width + The attribute value shall be an integer number. It shall be the width of + the register in bits. + +In addition to the explicit attributes, generic attributes may be specified. +Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value +may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterName: + +Register Name +^^^^^^^^^^^^^ + +The value shall be a string. The name consists either of an identifier, or an +identifier and an alias. The identifier and alias are separated by a colon +(``:``). The identifier shall match with the name of a register definition of +the item (see :ref:`SpecTypeRegisterDefinition`) or the name of a register +block include of the item (see :ref:`SpecTypeRegisterBlockIncludeRole`). If no +alias is specified, then the identifier is used for the register block member +name, otherwise the alias is used. If the register block member names are not +unique within the item, then a postfix number is appended to the names. The +number starts with zero for each set of names. The value shall match with the +regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*(:[a-zA-Z_][a-zA-Z0-9_]*)?$``". + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinition` + +.. _SpecTypeRequirementDesignGroupIdentifier: + +Requirement Design Group Identifier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the identifier of the requirement + design group. The value shall match with the regular expression + "``^[a-zA-Z0-9_]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeDesignGroupRequirementItemType` .. _SpecTypeRequirementRefinementLinkRole: @@ -4590,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: @@ -4735,13 +5256,13 @@ Requirement Validation Link Role This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the value is ``validation``. It defines the requirement validation role of links. -.. _SpecTypeRuntimeMeasurementEnvironment: +.. _SpecTypeRuntimeMeasurementEnvironmentName: -Runtime Measurement Environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Runtime Measurement Environment Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The value shall be a string. It specifies the runtime measurement environment. -The value +The value shall be a string. It specifies the runtime measurement environment +name. The value * shall be an element of @@ -4764,12 +5285,12 @@ Runtime Measurement Environment Table This set of attributes provides runtime performance limits for a set of runtime measurement environments. Generic attributes may be specified. Each generic -attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironment`. Each +attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. Each generic attribute value shall be a :ref:`SpecTypeRuntimeMeasurementValueTable`. This type is used by the following types: -* :ref:`SpecTypeRuntimePerformanceLimitTable` +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` .. _SpecTypeRuntimeMeasurementParameterSet: @@ -4845,21 +5366,6 @@ This type is used by the following types: * :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` -.. _SpecTypeRuntimePerformanceLimitTable: - -Runtime Performance Limit Table -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This set of attributes provides runtime performance limits for BSP variants -specified by ``"<arch>/<bsp>"`` with <arch> being the architecture of the BSP -and <bsp> being the base name of the BSP. Generic attributes may be specified. -Each generic attribute key shall be a string. Each generic attribute value -shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. - -This type is used by the following types: - -* :ref:`SpecTypeRuntimePerformanceRequirementItemType` - .. _SpecTypeRuntimePerformanceParameterSet: Runtime Performance Parameter Set @@ -4873,6 +5379,19 @@ This type is used by the following types: * :ref:`SpecTypeRuntimePerformanceRequirementItemType` +.. _SpecTypeSHA256HashValue: + +SHA256 Hash Value +^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be a SHA256 hash value encoded in +base64url. The value shall match with the regular expression +"``^[A-Za-z0-9+_=-]{44}$``". + +This type is used by the following types: + +* :ref:`SpecTypeExternalFileReference` + .. _SpecTypeSPDXLicenseIdentifier: SPDX License Identifier |