mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-17 22:21:45 +08:00
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.
This commit is contained in:
Sebastian Huber
parent
66591316dc
commit
239644be82
@ -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
|
||||
<ReqEngSyntax>`:
|
||||
|
||||
*When* <optional preconditions> <trigger>, the <system name> shall
|
||||
<system response>.
|
||||
**While** <pre-condition 0>, **while** <pre-condition 1>, ..., **while**
|
||||
<pre-condition *n*>, **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 *i*> 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`.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Link the action requirement item to an :ref:`SpecTypeInterfaceFunctionItemType`
|
||||
or an :ref:`SpecTypeInterfaceMacroItemType` item using the
|
||||
:ref:`SpecTypeInterfaceFunctionLinkRole`.
|
||||
Each post-condition state of the action requirement item generates a <system
|
||||
name> shall <system response> 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
|
||||
|
||||
|
||||
@ -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,34 @@ 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 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
|
||||
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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user