[PATCH 3/4] eng: Add a specification type for directives
Sebastian Huber
sebastian.huber at embedded-brains.de
Thu Jun 4 13:02:28 UTC 2020
Add support to specify functional requirements for directives (functions
or macros) via a transition map of pre-conditions to post-conditions.
This will be the work horse for functional requirements. Generation of
corresponding validation tests is supported.
Update #3715.
---
eng/req/items.rst | 333 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 333 insertions(+)
diff --git a/eng/req/items.rst b/eng/req/items.rst
index cf0805d..d23fba3 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -92,6 +92,8 @@ The specification item types have the following hierarchy:
* :ref:`SpecTypeFunctionalRequirementItemType`
+ * :ref:`SpecTypeDirectiveRequirementItemType`
+
* :ref:`SpecTypeNonXFunctionalRequirementItemType`
* :ref:`SpecTypeRequirementValidationItemType`
@@ -1631,6 +1633,95 @@ functional-type
The attribute value shall be a :ref:`SpecTypeRequirementFunctionalType`. It
shall be the functional type of the requirement.
+This type is refined by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementItemType`
+
+.. _SpecTypeDirectiveRequirementItemType:
+
+Directive Requirement Item Type
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeFunctionalRequirementItemType` though the
+``functional-type`` attribute if the value is ``directive``. This set of
+attributes specifies functional requirements and corresponding validation tests
+for a directive. A directive is a function or a macro. There shall be exactly
+one link with the :ref:`SpecTypeInterfaceFunctionLinkRole` to the interface of
+the directive. The directive requirement specifies
+
+* a list of pre-conditions, each with a set of states,
+
+* a list of post-conditions, each with a set of states,
+
+* the transition of pre-conditions to post-conditions through a call of
+ the directive, and
+
+* the test code to generate a validation test.
+
+For a directive requirement it is verified that all variations of
+pre-condition states have a set of post-condition states specified in the
+transition map. All explicit attributes shall be specified. The explicit
+attributes for this type are:
+
+post-conditions
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeDirectiveRequirementCondition`.
+
+pre-conditions
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeDirectiveRequirementCondition`.
+
+test-action
+ The attribute value shall be a string. It shall be the test action code.
+
+test-brief
+ The attribute value shall be an optional string. If the value is present,
+ then it shall be the test case brief description.
+
+test-context
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeDirectiveRequirementTestContextMember`.
+
+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-name
+ The attribute value shall be a :ref:`SpecTypeTestName`.
+
+test-setup
+ The attribute value shall be a
+ :ref:`SpecTypeDirectiveRequirementTestFixtureMethod`.
+
+test-stop
+ The attribute value shall be a
+ :ref:`SpecTypeDirectiveRequirementTestFixtureMethod`.
+
+test-support
+ The attribute value shall be an optional string. If the value is present,
+ then it shall be the test case support code. The support code is placed at
+ file scope before the test case code.
+
+test-target
+ The attribute value shall be a string. It shall be the path to the
+ generated target test case source file.
+
+test-teardown
+ The attribute value shall be a
+ :ref:`SpecTypeDirectiveRequirementTestFixtureMethod`.
+
+transition-map
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeDirectiveRequirementTransition`.
+
.. _SpecTypeNonXFunctionalRequirementItemType:
Non-Functional Requirement Item Type
@@ -2619,6 +2710,226 @@ This type is used by the following types:
* :ref:`SpecTypeRootItemType`
+.. _SpecTypeDirectiveRequirementCondition:
+
+Directive Requirement Condition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes defines a directive pre-condition or post-condition. All
+explicit attributes shall be specified. The explicit attributes for this type
+are:
+
+name
+ The attribute value shall be a :ref:`SpecTypeDirectiveRequirementName`.
+
+states
+ The attribute value shall be a list. Each list element shall be a
+ :ref:`SpecTypeDirectiveRequirementState`.
+
+test-epilogue
+ The attribute value shall be an optional string. If the value is present,
+ then it shall be the test epilogue code. The epilogue code is placed in the
+ test condition preparation or check before the state-specific code.
+
+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.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementItemType`
+
+.. _SpecTypeDirectiveRequirementName:
+
+Directive Requirement Name
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The value shall be a string. It shall be the name of a condition or a state of
+a condition used to define pre-conditions and post-conditions of a directive
+requirement. It shall be formatted in CamelCase. It should be brief and
+abbreviated. The rationale for this is that the names are used in tables and
+the horizontal space is limited by the page width. The more conditions you
+have in a directive requirement, the shorter the names should be. The value
+shall match with the regular expression "``^[A-Z][a-zA-Z0-9]+$"``.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementCondition`
+
+* :ref:`SpecTypeDirectiveRequirementState`
+
+* :ref:`SpecTypeDirectiveRequirementTransitionPostXConditions`
+
+* :ref:`SpecTypeDirectiveRequirementTransitionPreXConditions`
+
+.. _SpecTypeDirectiveRequirementState:
+
+Directive Requirement State
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes defines a directive pre-condition or post-condition
+state. All explicit attributes shall be specified. The explicit attributes for
+this type are:
+
+name
+ The attribute value shall be a :ref:`SpecTypeDirectiveRequirementName`.
+
+test-code
+ The attribute value shall be a string. It shall be the test code to prepare
+ or check the state of the condition.
+
+text
+ The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
+ define the state of the condition.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementCondition`
+
+.. _SpecTypeDirectiveRequirementTestContextMember:
+
+Directive 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 a
+ directive 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:`SpecTypeDirectiveRequirementItemType`
+
+.. _SpecTypeDirectiveRequirementTestFixtureMethod:
+
+Directive 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 a
+ directive 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:`SpecTypeDirectiveRequirementTestContextMember`.
+
+ 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:`SpecTypeDirectiveRequirementItemType`
+
+.. _SpecTypeDirectiveRequirementTransition:
+
+Directive Requirement Transition
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes defines the transition from a set of pre-conditions to
+post-conditions through a directive call in a directive requirement. All
+explicit attributes shall be specified. The explicit attributes for this type
+are:
+
+enabled-by
+ The attribute value shall be an :ref:`SpecTypeEnabledXByExpression`. The
+ transition map may be customized to support configuration variants through
+ this attribute. The default transitions (``enabled-by: true``) shall be
+ specified before the customized variants in the list.
+
+post-conditions
+ The attribute value shall be a
+ :ref:`SpecTypeDirectiveRequirementTransitionPostXConditions`.
+
+pre-conditions
+ The attribute value shall be a
+ :ref:`SpecTypeDirectiveRequirementTransitionPreXConditions`.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementItemType`
+
+.. _SpecTypeDirectiveRequirementTransitionPostXConditions:
+
+Directive Requirement Transition Post-Conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes defines for each post-condition the state after the
+directive call for a transition in a directive requirement. Generic attributes
+may be specified. Each generic attribute key shall be a
+:ref:`SpecTypeDirectiveRequirementName`. Each generic attribute value shall be
+a :ref:`SpecTypeDirectiveRequirementName`. 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.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementTransition`
+
+.. _SpecTypeDirectiveRequirementTransitionPreXConditionStateSet:
+
+Directive Requirement Transition Pre-Condition State Set
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A value of this type shall be of one of the following variants:
+
+* The value may be a list. Each list element shall be a
+ :ref:`SpecTypeDirectiveRequirementName`. The list defines the set of states
+ of the pre-condition in the transition.
+
+* The value may be a string. The value represents all states of the
+ pre-condition in the transition. The value shall be equal to "``all``".
+
+This type is used by the following types:
+
+* :ref:`SpecTypeDirectiveRequirementTransitionPreXConditions`
+
+.. _SpecTypeDirectiveRequirementTransitionPreXConditions:
+
+Directive Requirement Transition Pre-Conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes defines for each pre-condition the set of states before
+the directive call for a transition in a directive requirement. Generic
+attributes may be specified. Each generic attribute key shall be a
+:ref:`SpecTypeDirectiveRequirementName`. Each generic attribute value shall be
+a :ref:`SpecTypeDirectiveRequirementTransitionPreXConditionStateSet`. 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:`SpecTypeDirectiveRequirementTransition`
+
.. _SpecTypeEnabledXByExpression:
Enabled-By Expression
@@ -2662,6 +2973,8 @@ A value of this type shall be of one of the following variants:
This type is used by the following types:
+* :ref:`SpecTypeDirectiveRequirementTransition`
+
* :ref:`SpecTypeEnabledXByExpression`
* :ref:`SpecTypeInterfaceIncludeLinkRole`
@@ -3145,6 +3458,18 @@ This type is used by the following types:
* :ref:`SpecTypeInterfaceFunctionDefinitionDirective`
+.. _SpecTypeInterfaceFunctionLinkRole:
+
+Interface Function Link Role
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This type refines the :ref:`SpecTypeLink` though 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:`SpecTypeDirectiveRequirementItemType` item specifies functional
+requirements of an :ref:`SpecTypeInterfaceFunctionItemType` or a
+:ref:`SpecTypeInterfaceMacroItemType` item.
+
.. _SpecTypeInterfaceGroupIdentifier:
Interface Group Identifier
@@ -3347,6 +3672,8 @@ This type is refined by the following types:
* :ref:`SpecTypeInterfaceEnumeratorLinkRole`
+* :ref:`SpecTypeInterfaceFunctionLinkRole`
+
* :ref:`SpecTypeInterfaceGroupMembershipLinkRole`
* :ref:`SpecTypeInterfaceIncludeLinkRole`
@@ -3432,6 +3759,8 @@ types. The value shall be an element of
* "``dependability-function``",
+* "``directive``",
+
* "``function``",
* "``operational``", and
@@ -3673,6 +4002,8 @@ This type is used by the following types:
* :ref:`SpecTypeConstraintItemType`
+* :ref:`SpecTypeDirectiveRequirementState`
+
* :ref:`SpecTypeRequirementItemType`
.. _SpecTypeRequirementValidationLinkRole:
@@ -4332,6 +4663,8 @@ with the regular expression "``^[A-Z][a-zA-Z0-9 _]+$"``.
This type is used by the following types:
+* :ref:`SpecTypeDirectiveRequirementItemType`
+
* :ref:`SpecTypeTestCaseItemType`
* :ref:`SpecTypeTestSuiteItemType`
--
2.26.2
More information about the devel
mailing list