[PATCH v2] eng: Update EARS syntax
Sebastian Huber
sebastian.huber at embedded-brains.de
Thu Mar 18 06:38:34 UTC 2021
The document used the EARS syntax from 2009 which slightly changed in
2016, see "Listens Learned (8 Lessons Learned Applying EARS)". The
optional pre-conditions moved to the state-driven pattern. This refined
syntax fits better to the action requirements.
Update #3715.
---
eng/req/howto.rst | 57 ++++++++++++++++++++++++-----------------
eng/req/req-for-req.rst | 30 ++++++++++++++--------
2 files changed, 53 insertions(+), 34 deletions(-)
diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index 8481214..fee8c90 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -284,19 +284,32 @@ Action Requirements
-------------------
Use :ref:`SpecTypeActionRequirementItemType` items to specify and validate
-directive calls. Action requirements are a generator for event-driven
-requirements which should be written in the following :ref:`syntax
-<ReqEngSyntax>`:
+directive calls. Action requirement items are a generator for event-driven
+requirements. Event-driven requirements should be written in the following
+:ref:`syntax <ReqEngSyntax>`:
- *When* <optional preconditions> <trigger>, the <system name> shall
- <system response>.
+ **While** <pre-condition>, **while** ..., **when** <trigger>, the <system
+ name> shall <system response>.
-The <optional preconditions> are the pre-conditions of the action requirement.
-The <trigger> is the action of the action requirement. The post-conditions
-should provide a list of the <system name> shall <system response> clauses.
-Each transition in the transition map is an event-driven requirement composed
-of the pre-condition states, the action, and the post-condition states defined
-by the map entry.
+The list of *while* <pre-condition> clauses in the EARS notation is generated
+by the pre-condition states in the action requirement item, see the
+``pre-condition`` attribute in :ref:`SpecTypeActionRequirementItemType`.
+
+The <trigger> in the EARS notation is defined for an action requirement item by
+the link to an :ref:`SpecTypeInterfaceFunctionItemType` or an
+:ref:`SpecTypeInterfaceMacroItemType` item using the
+:ref:`SpecTypeInterfaceFunctionLinkRole`. The code provided by the
+``test-action`` attribute defines the action code which should invoke the
+trigger directive in a particular set of pre-condition states.
+
+The list of <system name> shall <system response> clauses in the EARS notation
+is generated by the post-condition states in the action requirement item, see
+the ``post-condition`` attribute in :ref:`SpecTypeActionRequirementItemType`.
+
+Each entry in the transition map is an event-driven requirement composed of the
+pre-condition states, the trigger defined by the link to a directive, and the
+post-condition states. The transition map is defined by a list of
+:ref:`SpecTypeActionRequirementTransition` descriptors.
Use ``CamelCase`` for the pre-condition names, post-condition
names, and state names. The more conditions a directive has, the shorter
@@ -304,10 +317,6 @@ should be the names. The transition map may be documented as a table and more
conditions need more table columns. Use item attribute references in the
``text`` attributes. This allows context-sensitive substitutions.
-Link the action requirement item to an :ref:`SpecTypeInterfaceFunctionItemType`
-or an :ref:`SpecTypeInterfaceMacroItemType` item using the
-:ref:`SpecTypeInterfaceFunctionLinkRole`.
-
Pre-Conditions
^^^^^^^^^^^^^^
@@ -322,20 +331,20 @@ syntax for directive object identifier parameters:
test-code: |
ctx->id = 0xffffffff;
text: |
- The ${../if/directive:/params[0]/name} parameter shall not be
+ While the ${../if/directive:/params[0]/name} parameter is not
associated with a thing.
- name: ClassA
test-code: |
ctx->id = ctx->class_a_id;
text: |
- The ${../if/directive:/params[0]/name} parameter shall be associated with a
- class A thing.
+ While the ${../if/directive:/params[0]/name} parameter is associated
+ with a class A thing.
- name: ClassB
test-code: |
ctx->id = ctx->class_b_id;
text: |
- The ${../if/directive:/params[0]/name} parameter shall be associated with a
- class B thing.
+ While the ${../if/directive:/params[0]/name} parameter is associated
+ with a class B thing.
test-epilogue: null
test-prologue: null
@@ -354,13 +363,13 @@ the following syntax for directive pointer parameters:
test-code: |
ctx->id = &ctx->id_value;
text: |
- The ${../if/directive:/params[3]/name} parameter shall reference an
+ While the ${../if/directive:/params[3]/name} parameter references an
object of type ${../../type/if/id:/name}.
- name: 'Null'
test-code: |
ctx->id = NULL;
text: |
- The ${../if/directive:/params[3]/name} parameter shall be
+ While the ${../if/directive:/params[3]/name} parameter is
${/c/if/null:/name}.
test-epilogue: null
test-prologue: null
@@ -375,12 +384,12 @@ Use the following syntax for other directive parameters:
test-code: |
ctx->name = NAME;
text: |
- The ${../if/directive:/params[0]/name} parameter shall be valid.
+ While the ${../if/directive:/params[0]/name} parameter is valid.
- name: Invalid
test-code: |
ctx->name = 0;
text: |
- The ${../if/directive:/params[0]/name} parameter shall be invalid.
+ While the ${../if/directive:/params[0]/name} parameter is invalid.
test-epilogue: null
test-prologue: null
diff --git a/eng/req/req-for-req.rst b/eng/req/req-for-req.rst
index 9225e95..b86236e 100644
--- a/eng/req/req-for-req.rst
+++ b/eng/req/req-for-req.rst
@@ -171,9 +171,9 @@ Syntax
Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate
requirements. A recommended reading list to get familiar with this approach is
-:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and
-:cite:`Mavin:2016:LLEARS`. Please also have a look at the EARS quick reference
-sheet :cite:`Uusitalo:2012:EARS`. The sentence types are:
+:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`,
+:cite:`Mavin:2016:LLEARS`, and `Alisair Mavin's web site
+<https://alistairmavin.com/ears/>`_. The patterns are:
* Ubiquitous
@@ -181,22 +181,32 @@ sheet :cite:`Uusitalo:2012:EARS`. The sentence types are:
* Event-driven
- *When* <optional preconditions> <trigger>, the <system name> shall <system response>.
+ **When** <trigger>, the <system name> shall <system response>.
* State-driven
- *While* <in state>, the <system name> shall <system response>.
+ **While** <pre-condition>, the <system name> shall <system response>.
* Unwanted behaviour
- *If* <optional preconditions> <trigger>, *then* the <system name> shall <system response>.
+ **If** <trigger>, **then** the <system name> shall <system response>.
* Optional
- *Where* <feature>, the <system name> shall <system response>.
+ **Where** <feature is included>, the <system name> shall <system response>.
-The optional sentence type should be only used for application configuration
-options. The goal is to use the *enabled-by* attribute to enable or disable
+* Complex
+
+ **Where** <feature is included>, **where** ..., **while** <pre-condition>,
+ **while** ..., **when** <trigger>, the <system name> shall <system
+ response>.
+
+ **Where** <feature is included>, **where** ..., **while** <pre-condition>,
+ **while** ..., **if** <trigger>, **then** the <system name> shall <system
+ response>.
+
+The optional pattern should be only used for application configuration
+options. The goal is to use the ``enabled-by`` attribute to enable or disable
requirements based on configuration parameters that define the RTEMS artefacts
used to build an application executable (header files, libraries, linker command
files). Such configuration parameters are for example the architecture, the
@@ -345,7 +355,7 @@ Justification of Requirements
-----------------------------
Each requirement shall have a rationale or justification recorded in a
-dedicated section of the requirement file. See *rationale* attribute for
+dedicated section of the requirement file. See ``rationale`` attribute for
:ref:`ReqEngSpecificationItems`.
.. _ReqEngValidation:
--
2.26.2
More information about the devel
mailing list