[rtems-docs commit] eng: Add how-to for action requirements
Sebastian Huber
sebh at rtems.org
Mon Mar 8 07:29:20 UTC 2021
Module: rtems-docs
Branch: master
Commit: a4b3019d99956226fcc28cf56880264b8cc84017
Changeset: http://git.rtems.org/rtems-docs/commit/?id=a4b3019d99956226fcc28cf56880264b8cc84017
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Mon Mar 8 08:15:54 2021 +0100
eng: Add how-to for action requirements
Update #3715.
---
eng/req/howto.rst | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 178 insertions(+), 1 deletion(-)
diff --git a/eng/req/howto.rst b/eng/req/howto.rst
index 5316649..7294e54 100644
--- a/eng/req/howto.rst
+++ b/eng/req/howto.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+.. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
How-To
======
@@ -279,3 +279,180 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
- description: The caller did not have enough magic power.
value: ${/if/c/null}
type: interface
+
+Action Requirements
+-------------------
+
+Use :ref:`SpecTypeActionRequirementItemType` items to specify and validate
+directive calls. 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.
+
+Pre-Conditions
+^^^^^^^^^^^^^^
+
+Specify all directive parameters as separate pre-conditions. Use the following
+syntax for directive object identifier parameters:
+
+.. code-block:: yaml
+
+ - name: Id
+ states:
+ - name: NoObj
+ test-code: |
+ ctx->id = 0xffffffff;
+ text: |
+ The ${../if/directive:/params[0]/name} parameter shall be 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.
+ - 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.
+ test-epilogue: null
+ test-prologue: null
+
+Do not add specifications for invalid pointers. In general, there are a lot of
+invalid pointers and the use of an invalid pointer is in almost all cases
+undefined behaviour in RTEMS. There may be specifications for special cases
+which deal with some very specific invalid pointers such as the :c:data:`NULL`
+pointer or pointers which do not satisfy a range or boundary condition. Use
+the following syntax for directive pointer parameters:
+
+.. code-block:: yaml
+
+ - name: Id
+ states:
+ - name: Valid
+ test-code: |
+ ctx->id = &ctx->id_value;
+ text: |
+ The ${../if/directive:/params[3]/name} parameter shall reference 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
+ ${/c/if/null:/name}.
+ test-epilogue: null
+ test-prologue: null
+
+Use the following syntax for other directive parameters:
+
+.. code-block:: yaml
+
+ - name: Name
+ states:
+ - name: Valid
+ test-code: |
+ ctx->name = NAME;
+ text: |
+ The ${../if/directive:/params[0]/name} parameter shall be valid.
+ - name: Invalid
+ test-code: |
+ ctx->name = 0;
+ text: |
+ The ${../if/directive:/params[0]/name} parameter shall be invalid.
+ test-epilogue: null
+ test-prologue: null
+
+Post-Conditions
+^^^^^^^^^^^^^^^
+
+Do not mix different things into one post-condition. If you write multiple
+sentences to describe what happened, then think about splitting up the
+post-condition. Keep the post-condition simple and focus on one testable
+aspect which may be changed by a directive call.
+
+For directives returning an :c:type:`rtems_status_code` use the following
+post-condition states. Specify only status codes which may be returned by the
+directive. Use it as the first post-condition.
+
+.. code-block:: yaml
+
+ - name: Status
+ states:
+ - name: Ok
+ test-code: |
+ T_rsc_success( ctx->status );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/successful:/name}.
+ - name: IncStat
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INCORRECT_STATE );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/incorrect-state:/name}.
+ - name: InvAddr
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INVALID_ADDRESS );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/invalid-address:/name}.
+ - name: InvName
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INVALID_NAME );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/invalid-name:/name}.
+ - name: InvNum
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INVALID_NUMBER );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/invalid-number:/name}.
+ - name: InvSize
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INVALID_SIZE );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/invalid-size:/name}.
+ - name: InvPrio
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INVALID_PRIORITY );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/invalid-priority:/name}.
+ - name: NotConf
+ test-code: |
+ T_rsc( ctx->status, RTEMS_NOT_CONFIGURED );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/not-configured:/name}.
+ - name: NotDef
+ test-code: |
+ T_rsc( ctx->status, RTEMS_NOT_DEFINED );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/not-defined:/name}.
+ - name: NotImpl
+ test-code: |
+ T_rsc( ctx->status, RTEMS_NOT_IMPLEMENTED );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/not-implemented:/name}.
+ - name: TooMany
+ test-code: |
+ T_rsc( ctx->status, RTEMS_TOO_MANY );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/too-many:/name}.
+ - name: Unsat
+ test-code: |
+ T_rsc( ctx->status, RTEMS_UNSATISFIED );
+ text: |
+ The return status of ${../if/directive:/name} shall be
+ ${../../status/if/unsatisfied:/name}.
+ test-epilogue: null
+ test-prologue: null
More information about the vc
mailing list