From 239644be82bf36a1263741d6c6bfee6b81adbea3 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 17 Mar 2021 10:29:48 +0100 Subject: eng: Update EARS syntax 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 | 73 ++++++++++++++++++++++++++++--------------------- eng/req/req-for-req.rst | 32 +++++++++++++++------- 2 files changed, 64 insertions(+), 41 deletions(-) diff --git a/eng/req/howto.rst b/eng/req/howto.rst index 8481214..8d146a3 100644 --- a/eng/req/howto.rst +++ b/eng/req/howto.rst @@ -283,30 +283,41 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item. 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 +:ref:`SpecTypeActionRequirementItemType` items may be used to specify and +validate directive calls. They are a generator for event-driven requirements. +Event-driven requirements should be written in the following :ref:`syntax `: - *When* , the shall - . - -The are the pre-conditions of the action requirement. -The is the action of the action requirement. The post-conditions -should provide a list of the shall 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. - -Use ``CamelCase`` for the pre-condition names, post-condition -names, and state names. The more conditions a directive has, the shorter -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`. + **While** , **while** , ..., **while** + , **when** , the shall . + +The list of *while* clauses for *i* from 1 to *n* in the +EARS notation is generated by *n* pre-condition states in the action +requirement item, see the ``pre-condition`` attribute in the +:ref:`SpecTypeActionRequirementItemType`. + +The 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. + +Each post-condition state of the action requirement item generates a shall clause in the EARS notation, see the +``post-condition`` attribute in the :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 in action requirement items. The more conditions a directive has, the +shorter 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. Pre-Conditions ^^^^^^^^^^^^^^ @@ -322,20 +333,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 +365,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 +386,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..0c05ed6 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 +`_. The patterns are: * Ubiquitous @@ -181,22 +181,34 @@ sheet :cite:`Uusitalo:2012:EARS`. The sentence types are: * Event-driven - *When* , the shall . + **When** , the shall . * State-driven - *While* , the shall . + **While** , the shall . * Unwanted behaviour - *If* , *then* the shall . + **If** , **then** the shall . * Optional - *Where* , the shall . + **Where** , the shall . -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** , **where** , ..., + **where** , **while** , **while** + , ..., **while** , **when** , + the shall . + + **Where** , **where** , ..., + **where** , **while** , **while** + , ..., **while** , **if** , + **then** the shall . + +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 +357,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: -- cgit v1.2.3