rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-17 21:51:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

eng: Update EARS syntax

Browse Source 
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.
This commit is contained in:
Sebastian Huber 2021-03-17 10:29:48 +01:00
parent 66591316dc
commit 239644be82
2 changed files with 61 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
eng/req/howto.rst
View File

@ -283,30 +283,41 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
Action Requirements Action Requirements
------------------- -------------------
Use :ref:`SpecTypeActionRequirementItemType` items to specify and validate :ref:`SpecTypeActionRequirementItemType` items may be used to specify and
directive calls. Action requirements are a generator for event-driven validate directive calls. They are a generator for event-driven requirements.
requirements which should be written in the following :ref:`syntax Event-driven requirements should be written in the following :ref:`syntax
<ReqEngSyntax>`: <ReqEngSyntax>`:
*When* <optional preconditions> <trigger>, the <system name> shall **While** <pre-condition 0>, **while** <pre-condition 1>, ..., **while**
<system response>. <pre-condition *n*>, **when** <trigger>, the <system name> shall <system
response>.
The <optional preconditions> are the pre-conditions of the action requirement. The list of *while* <pre-condition *i*> clauses for *i* from 1 to *n* in the
The <trigger> is the action of the action requirement. The post-conditions EARS notation is generated by *n* pre-condition states in the action
should provide a list of the <system name> shall <system response> clauses. requirement item, see the ``pre-condition`` attribute in the
Each transition in the transition map is an event-driven requirement composed :ref:`SpecTypeActionRequirementItemType`.
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 The <trigger> in the EARS notation is defined for an action requirement item by
names, and state names. The more conditions a directive has, the shorter the link to an :ref:`SpecTypeInterfaceFunctionItemType` or an
should be the names. The transition map may be documented as a table and more :ref:`SpecTypeInterfaceMacroItemType` item using the
conditions need more table columns. Use item attribute references in the :ref:`SpecTypeInterfaceFunctionLinkRole`. The code provided by the
``text`` attributes. This allows context-sensitive substitutions. ``test-action`` attribute defines the action code which should invoke the
trigger directive in a particular set of pre-condition states.
Link the action requirement item to an :ref:`SpecTypeInterfaceFunctionItemType` Each post-condition state of the action requirement item generates a <system
or an :ref:`SpecTypeInterfaceMacroItemType` item using the name> shall <system response> clause in the EARS notation, see the
:ref:`SpecTypeInterfaceFunctionLinkRole`. ``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 Pre-Conditions
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
@ -322,20 +333,20 @@ syntax for directive object identifier parameters:
test-code: | test-code: |
ctx->id = 0xffffffff; ctx->id = 0xffffffff;
text: | 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. associated with a thing.
- name: ClassA - name: ClassA
test-code: | test-code: |
ctx->id = ctx->class_a_id; ctx->id = ctx->class_a_id;
text: | text: |
The ${../if/directive:/params[0]/name} parameter shall be associated with a While the ${../if/directive:/params[0]/name} parameter is associated
class A thing. with a class A thing.
- name: ClassB - name: ClassB
test-code: | test-code: |
ctx->id = ctx->class_b_id; ctx->id = ctx->class_b_id;
text: | text: |
The ${../if/directive:/params[0]/name} parameter shall be associated with a While the ${../if/directive:/params[0]/name} parameter is associated
class B thing. with a class B thing.
test-epilogue: null test-epilogue: null
test-prologue: null test-prologue: null
@ -354,13 +365,13 @@ the following syntax for directive pointer parameters:
test-code: | test-code: |
ctx->id = &ctx->id_value; ctx->id = &ctx->id_value;
text: | 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}. object of type ${../../type/if/id:/name}.
- name: 'Null' - name: 'Null'
test-code: | test-code: |
ctx->id = NULL; ctx->id = NULL;
text: | text: |
The ${../if/directive:/params[3]/name} parameter shall be While the ${../if/directive:/params[3]/name} parameter is
${/c/if/null:/name}. ${/c/if/null:/name}.
test-epilogue: null test-epilogue: null
test-prologue: null test-prologue: null
@ -375,12 +386,12 @@ Use the following syntax for other directive parameters:
test-code: | test-code: |
ctx->name = NAME; ctx->name = NAME;
text: | text: |
The ${../if/directive:/params[0]/name} parameter shall be valid. While the ${../if/directive:/params[0]/name} parameter is valid.
- name: Invalid - name: Invalid
test-code: | test-code: |
ctx->name = 0; ctx->name = 0;
text: | 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-epilogue: null
test-prologue: null test-prologue: null

32
eng/req/req-for-req.rst
View File

@ -171,9 +171,9 @@ Syntax
Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate
requirements. A recommended reading list to get familiar with this approach is requirements. A recommended reading list to get familiar with this approach is
:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, and :cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`,
:cite:`Mavin:2016:LLEARS`. Please also have a look at the EARS quick reference :cite:`Mavin:2016:LLEARS`, and `Alisair Mavin's web site
sheet :cite:`Uusitalo:2012:EARS`. The sentence types are: <https://alistairmavin.com/ears/>`_. The patterns are:
* Ubiquitous * Ubiquitous
@ -181,22 +181,34 @@ sheet :cite:`Uusitalo:2012:EARS`. The sentence types are:
* Event-driven * Event-driven
*When* <optional preconditions> <trigger>, the <system name> shall <system response>. **When** <trigger>, the <system name> shall <system response>.
* State-driven * State-driven
*While* <in state>, the <system name> shall <system response>. **While** <pre-condition>, the <system name> shall <system response>.
* Unwanted behaviour * Unwanted behaviour
*If* <optional preconditions> <trigger>, *then* the <system name> shall <system response>. **If** <trigger>, **then** the <system name> shall <system response>.
* Optional * 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 * Complex
options. The goal is to use the *enabled-by* attribute to enable or disable
**Where** <feature 0 is included>, **where** <feature 1 is included>, ...,
**where** <feature *n* is included>, **while** <pre-condition 0>, **while**
<pre-condition 1>, ..., **while** <pre-condition *m*>, **when** <trigger>,
the <system name> shall <system response>.
**Where** <feature 0 is included>, **where** <feature 1 is included>, ...,
**where** <feature *n* is included>, **while** <pre-condition 0>, **while**
<pre-condition 1>, ..., **while** <pre-condition *m*>, **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 requirements based on configuration parameters that define the RTEMS artefacts
used to build an application executable (header files, libraries, linker command used to build an application executable (header files, libraries, linker command
files). Such configuration parameters are for example the architecture, the 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 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`. :ref:`ReqEngSpecificationItems`.
.. _ReqEngValidation: .. _ReqEngValidation: