From db3892b5b8eaed97705bf552ed010bc7f8e80149 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Wed, 10 Jun 2020 10:12:00 +0200
Subject: eng: Update action requirement specification

Update #3715.
---
 eng/req/items.rst | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 1 deletion(-)

(limited to 'eng')

diff --git a/eng/req/items.rst b/eng/req/items.rst
index 98f62ad..a7ca58a 100644
--- a/eng/req/items.rst
+++ b/eng/req/items.rst
@@ -1697,6 +1697,9 @@ test-description
     The attribute value shall be an optional string. If the value is present,
     then it shall be the test case description.
 
+test-header
+    The attribute value shall be an :ref:`SpecTypeActionRequirementTestHeader`.
+
 test-includes
     The attribute value shall be a list of strings. It shall be a list of
     header files included via ``#include <...>``.
@@ -1723,7 +1726,7 @@ test-support
 
 test-target
     The attribute value shall be a string. It shall be the path to the
-    generated target test case source file.
+    generated test case source file.
 
 test-teardown
     The attribute value shall be an
@@ -2161,6 +2164,80 @@ This type is used by the following types:
 
 * :ref:`SpecTypeActionRequirementItemType`
 
+.. _SpecTypeActionRequirementTestHeader:
+
+Action Requirement Test Header
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A value of this type shall be of one of the following variants:
+
+* The value may be a set of attributes. This set of attributes specifies an
+  action requirement test header.  In case a test header is specified, then
+  instead of a test case a test run function will be generated.  The test run
+  function will be declared in the test header target file and defined in the
+  test source target file. The test run function can be used to compose test
+  cases.  The test header file is not automatically included in the test source
+  file.  It should be added to the includes or local includes of the test. All
+  explicit attributes shall be specified. The explicit attributes for this type
+  are:
+
+  code
+      The attribute value shall be an optional string. If the value is present,
+      then it shall be the test case header code. The header code is placed at
+      file scope after the test enum declarations and before the test run
+      function declaration.
+
+  includes
+      The attribute value shall be a list of strings. It shall be a list of
+      header files included by the header file via ``#include <...>``.
+
+  local-includes
+      The attribute value shall be a list of strings. It shall be a list of
+      header files included by the header file via ``#include "..."``.
+
+  run-params
+      The attribute value shall be a list. Each list element shall be an
+      :ref:`SpecTypeActionRequirementTestRunParameter`.
+
+  target
+      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).
+
+This type is used by the following types:
+
+* :ref:`SpecTypeActionRequirementItemType`
+
+.. _SpecTypeActionRequirementTestRunParameter:
+
+Action Requirement Test Run Parameter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This set of attributes specifies a parameter for the test run function. 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:
+
+description
+    The attribute value shall be a string. It shall be the description of the
+    parameter.
+
+dir
+    The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`.
+
+name
+    The attribute value shall be a string. It shall be the parameter name.
+
+specifier
+    The attribute value shall be a string. It shall be the complete function
+    parameter specifier.  Use ``${.:name}`` for the parameter name, for example
+    ``"int ${.:name}"``.
+
+This type is used by the following types:
+
+* :ref:`SpecTypeActionRequirementTestHeader`
+
 .. _SpecTypeActionRequirementTransition:
 
 Action Requirement Transition
@@ -3622,6 +3699,8 @@ A value of this type shall be of one of the following variants:
 
 This type is used by the following types:
 
+* :ref:`SpecTypeActionRequirementTestRunParameter`
+
 * :ref:`SpecTypeInterfaceParameter`
 
 .. _SpecTypeInterfacePlacementLinkRole:
-- 
cgit v1.2.3