spec: Clarify action requirements

2 files changed, 131 insertions, 6 deletions

diff --git a/spec/spec/requirement-action-transition.yml b/spec/spec/requirement-action-transition.yml
index 45484566..77cac693 100644
--- a/spec/spec/requirement-action-transition.yml
+++ b/spec/spec/requirement-action-transition.yml
@@ -24,9 +24,16 @@ spec-info:
         description: null
         spec-type: requirement-action-transition-pre
     description: |
-      This set of attributes defines the transition from all state variations
-      of the set of pre-conditions to states of post-conditions through an
-      action in an action requirement.
+      This set of attributes defines the transition from multiple sets of
+      states of pre-conditions to a set of states of post-conditions through an
+      action in an action requirement.  The ability to specify multiple sets of
+      states of pre-conditions which result in a common set of post-conditions
+      may allow a more compact specification of the transition map.  For
+      example, let us suppose you want to specify the action of a function with
+      a pointer parameter.  The function performs an early check that the
+      pointer is NULL and in this case returns an error code.  The pointer
+      condition dominates the action outcome if the pointer is NULL.  Other
+      pre-condition states can be simply set to ``all`` for this transition.
     mandatory-attributes: all
 spec-name: Action Requirement Transition
 spec-type: requirement-action-transition
diff --git a/spec/spec/requirement-action.yml b/spec/spec/requirement-action.yml
index 1ae672f4..8eb7b7be 100644
--- a/spec/spec/requirement-action.yml
+++ b/spec/spec/requirement-action.yml
@@ -10,7 +10,124 @@ links:
   spec-value: action
   uid: requirement-functional
 spec-description: null
-spec-example: null
+spec-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)
+  enabled-by: true
+  functional-type: action
+  links: []
+  post-conditions:
+  - name: Status
+    states:
+    - name: Success
+      test-code: |
+        /* Check that the status is SUCCESS */
+      text: |
+        The status shall be SUCCESS.
+    - name: Error
+      test-code: |
+        /* Check that the status is ERROR */
+      text: |
+        The status shall be ERROR.
+    test-epilogue: null
+    test-prologue: null
+  - name: Data
+    states:
+    - name: Unchanged
+      test-code: |
+        /* Check that the data is unchanged */
+      text: |
+        The data shall be unchanged by the action.
+    - name: Red
+      test-code: |
+        /* Check that the data is red */
+      text: |
+        The data shall be red.
+    - name: Green
+      test-code: |
+        /* Check that the data is green */
+      text: |
+        The data shall be green.
+    test-epilogue: null
+    test-prologue: null
+  pre-conditions:
+  - name: Data
+    states:
+    - name: NullPtr
+      test-code: |
+        /* Set data pointer to NULL */
+      text: |
+        The data pointer shall be NULL.
+    - name: Valid
+      test-code: |
+        /* Set data pointer to reference a valid data buffer */
+      text: |
+        The data pointer shall reference a valid data buffer.
+    test-epilogue: null
+    test-prologue: null
+  - name: Option
+    states:
+    - name: Red
+      test-code: |
+        /* Set option to RED */
+      text: |
+        The option shall be RED.
+    - name: Green
+      test-code: |
+        /* Set option to GREEN */
+      text: |
+        The option shall be GREEN.
+    test-epilogue: null
+    test-prologue: null
+  requirement-type: functional
+  test-action: |
+    /* Call the function of the action */
+  test-brief: null
+  test-context:
+  - brief: null
+    description: null
+    member: void *data
+  - brief: null
+    description: null
+    member: option_type option
+  test-description: null
+  test-header: null
+  test-includes: []
+  test-local-includes: []
+  test-name: RedGreenData
+  test-setup: null
+  test-stop: null
+  test-support: null
+  test-target: tc-red-green-data.c
+  test-teardown: null
+  transition-map:
+  - enabled-by: true
+    post-conditions:
+      Status: Error
+      Data: Unchanged
+    pre-conditions:
+      Data: NullPtr
+      Option: all
+  - enabled-by: true
+    post-conditions:
+      Status: Success
+      Data: Red
+    pre-conditions:
+      Data: Valid
+      Option: Red
+  - enabled-by: true
+    post-conditions:
+      Status: Success
+      Data: Green
+    pre-conditions:
+      Data: Valid
+      Option: Green
+  rationale: null
+  references: []
+  text: |
+    ${.:/text-template}
+  type: requirement
 spec-info:
   dict:
     attributes:
@@ -80,8 +197,9 @@ spec-info:
       code of a macro expansion by an actor.  The actor is for example a task
       or an interrupt service routine.
 
-      There shall be exactly one link with the
-      ${interface-function-role:/spec-name} to the interface of the action.
+      For action requirements which specify the function of an interface, there
+      shall be exactly one link with the ${interface-function-role:/spec-name}
+      to the interface of the action.
 
       The action requirements are specified by