diff options
Diffstat (limited to 'eng/req/howto.rst')
| -rw-r--r-- | eng/req/howto.rst | 235 |
1 files changed, 208 insertions, 27 deletions
diff --git a/eng/req/howto.rst b/eng/req/howto.rst index c8bd8c5..325c443 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, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG How-To ====== @@ -33,16 +33,110 @@ environment in your shell: cd rtems-central . env/bin/activate +View the Specification Graph +---------------------------- + +The specification items form directed graphs through :ref:`SpecTypeLink` +attributes. Each link has a role. For a particular view only specific roles +may be of interest. For example, the requirements specification of RTEMS +starts with the ``spec:/req/root`` specification item. It should form a tree +(connected graph without cycles). A text representation of the tree can be +printed with the ``./specview.py`` script: + +.. code-block:: none + + cd rtems-central + . env/bin/activate + ./specview.py + +This gives the following example output (shortened): + +.. code-block:: none + + /req/root (type=requirement/non-functional/design) + /bsp/if/group (type=requirement/non-functional/design-group, role=requirement-refinement) + /bsp/if/acfg-idle-task-body (type=interface/unspecified-define, role=interface-ingroup) + /bsp/sparc/leon3/req/idle-task-body (type=requirement/functional/function, role=interface-function) + /bsp/sparc/leon3/req/idle-task-power-down (type=requirement/functional/function, role=requirement-refinement) + /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation) + /bsp/sparc/leon3/req/idle-task-power-down-errata (type=requirement/functional/function, role=requirement-refinement) + /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation) + +The actual specification graph depends on build configuration options which +enable or disable specification items. The ``--enabled`` command line option +may be used to specify the build configuration options, for example +``--enabled=sparc,bsps/sparc/leon3,sparc/gr740,RTEMS_SMP,RTEMS_QUAL``. + +The ``./specview.py`` script can display other views of the specification +through the ``--filter`` command line option. Transition maps of +:ref:`SpecTypeActionRequirementItemType` items can be printed using the +``--filter=action-table`` or ``--filter=action-list`` filters. For example, +``./specview.py --filter=action-table /rtems/timer/req/create`` prints +something like this: + +.. code-block:: none + + .. table:: + :class: longtable + + ===== ========== ======= ===== ==== ======= ======= ===== + Entry Descriptor Name Id Free Status Name IdVar + ===== ========== ======= ===== ==== ======= ======= ===== + 0 0 Valid Valid Yes Ok Valid Set + 1 0 Valid Valid No TooMany Invalid Nop + 2 0 Valid Null Yes InvAddr Invalid Nop + 3 0 Valid Null No InvAddr Invalid Nop + 4 0 Invalid Valid Yes InvName Invalid Nop + 5 0 Invalid Valid No InvName Invalid Nop + 6 0 Invalid Null Yes InvName Invalid Nop + 7 0 Invalid Null No InvName Invalid Nop + ===== ========== ======= ===== ==== ======= ======= ===== + +For example, ``./specview.py --filter=action-list /rtems/timer/req/create`` +prints something like this: + +.. code-block:: none + + Status = Ok, Name = Valid, IdVar = Set + + * Name = Valid, Id = Valid, Free = Yes + + Status = TooMany, Name = Invalid, IdVar = Nop + + * Name = Valid, Id = Valid, Free = No + + Status = InvAddr, Name = Invalid, IdVar = Nop + + * Name = Valid, Id = Null, Free = { Yes, No } + + Status = InvName, Name = Invalid, IdVar = Nop + + * Name = Invalid, Id = { Valid, Null }, Free = { Yes, No } + +The view above yields for each variation of post-condition states the list of +associated pre-condition state variations. + +Generate Files from Specification Items +--------------------------------------- + +The ``./spec2modules.py`` script generates program and documentation files in +:file:`modules/rtems` and :file:`modules/rtems-docs` using the specification +items as input. The script should be invoked whenever a specification item was +modified. After running the script, go into the subdirectories and create +corresponding patch sets. For these patch sets, the normal patch review +process applies, see *Support and Contributing* chapter of the *RTEMS User +Manual*. + Application Configuration Options --------------------------------- The application configuration options and groups are maintained by -specification items in the directory :file:`spec/if/acfg`. Application +specification items in the directory :file:`spec/acfg/if`. Application configuration options are grouped by :ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be -stored in files using the :file:`spec/if/acfg/group-*.yml` pattern. Each +stored in files using the :file:`spec/acfg/if/group-*.yml` pattern. Each application configuration option shall link to exactly one group item with the -:ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`. There are four +:ref:`SpecTypeInterfaceGroupMembershipLinkRole`. There are four application option item types available which cover all existing options: * The *feature enable options* let the application enable a feature option. If @@ -83,9 +177,9 @@ restricted Sphinx formatting. Emphasis via one asterisk ("*"), strong emphasis via two asterisk ("**"), code samples via blockquotes ("``"), code blocks (".. code-block:: c") and lists are allowed. References to interface items are also allowed, for example "${appl-needs-clock-driver:/name}" and -"${../rtems/tasks/create:/name}". References to other parts of the -documentation are possible, however, they are currently provided by hard-coded -tables in :file:`rtemsspec/applconfig.py`. +"${/rtems/task/if/create:/name}". References to other parts of the +documentation are possible, however, they have to be provided by +:file:`spec:/doc/if/*` items. Modify an Existing Group ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -95,9 +189,9 @@ file. For example: .. code-block:: none - $ grep -rl "name: General System Configuration" spec/if/acfg - spec/if/acfg/group-general.yml - $ vi spec/if/acfg/group-general.yml + $ grep -rl "name: General System Configuration" spec/acfg/if + spec/acfg/if/group-general.yml + $ vi spec/acfg/if/group-general.yml Modify an Existing Option ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -107,20 +201,20 @@ specification item file. For example: .. code-block:: none - $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/if/acfg - spec/if/acfg/appl-needs-clock-driver.yml - $ vi spec/if/acfg/appl-needs-clock-driver.yml + $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/acfg/if + spec/acfg/if/appl-needs-clock-driver.yml + $ vi spec/acfg/if/appl-needs-clock-driver.yml Add a New Group ^^^^^^^^^^^^^^^ Let ``new`` be the UID name part of the new group. Create the file -:file:`spec/if/acfg/group-new.yml` and provide all attributes for an +:file:`spec/acfg/if/group-new.yml` and provide all attributes for an :ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example: .. code-block:: none - $ vi spec/if/acfg/group-new.yml + $ vi spec/acfg/if/group-new.yml Add a New Option ^^^^^^^^^^^^^^^^ @@ -132,7 +226,7 @@ example: .. code-block:: none - $ vi spec/if/acfg/my-new-option.yml + $ vi spec/acfg/if/my-new-option.yml Generate Content after Changes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -144,7 +238,7 @@ make sure the Git submodules are up-to-date. .. code-block:: none - $ ./spec2dmodules.py + $ ./spec2modules.py The script modifies or creates source files in :file:`modules/rtems` and :file:`modules/rtems-docs`. Create patch sets for these changes just as if @@ -169,7 +263,7 @@ specification. SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true glossary-type: term links: @@ -206,23 +300,25 @@ Interface Specification Specify an API Header File ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The RTEMS :term:`API` header files are specified under ``spec:/if/rtems/*``. +The RTEMS :term:`API` header files are specified under ``spec:/rtems/*/if``. Create a subdirectory with a corresponding name for the API, for example in -:file:`spec/if/rtems/foo` for the `foo` API. In this new subdirectory place an +:file:`spec/rtems/foo/if` for the `foo` API. In this new subdirectory place an :ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml` -(:file:`spec/if/rtems/foo/header.yml`) and populate it with the required +(:file:`spec/rtems/foo/if/header.yml`) and populate it with the required attributes. .. code-block:: yaml SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG enabled-by: true interface-type: header-file links: - role: interface-placement - uid: /if/domains/api + uid: /if/domain + - role: interface-ingroup + uid: ../req/group path: rtems/rtems/foo.h prefix: cpukit/include type: interface @@ -233,7 +329,7 @@ Specify an API Element Figure out the corresponding header file item. If it does not exist, see :ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an :ref:`SpecTypeInterfaceItemType` item into the directory of the header file -item, for example :file:`spec/if/rtems/foo/bar.yml` for the :c:func:`bar` +item, for example :file:`spec/rtems/foo/if/bar.yml` for the :c:func:`bar` function. Add the required attributes for the new interface item. Do not hard code interface names which are used to define the new interface. Use ``${uid-of-interface-item:/name}`` instead. If the referenced interface is @@ -250,7 +346,7 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item. SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause brief: Tries to create a magic object and returns it. copyrights: - - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2020 embedded brains GmbH & Co. KG definition: default: body: null @@ -277,7 +373,7 @@ an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item. return: Otherwise, the magic object is returned. return-values: - description: The caller did not have enough magic power. - value: ${/if/c/null} + value: ${/c/if/null} type: interface Requirements Depending on Build Configuration Options @@ -514,7 +610,7 @@ presentation we use a structured order. SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause copyrights: - - Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + - Copyright (C) 2021 embedded brains GmbH & Co. KG enabled-by: true functional-type: action rationale: null @@ -1030,3 +1126,88 @@ the following post-condition states. Objects referenced by the ${../if/directive:/params[0]/name} parameter in past calls to ${../if/directive:/name} shall not be accessed by the ${../if/directive:/name} call. + +Validation Test Guidelines +-------------------------- + +The validation test cases, test runners, and test suites are generated by the +``./spec2modules.py`` script from specification items. For the placement and +naming of the generated sources use the following rules: + +* Place architecture-specific validation test sources and programs into the + ``testsuites/validation/cpu`` directory. + +* Place BSP-specific validation test sources and programs into the + ``testsuites/validation/bsps`` directory. + +* Place all other validation test sources and programs into the + ``testsuites/validation`` directory. + +* Place architecture-specific unit test sources and programs into the + ``testsuites/unit/cpu`` directory. + +* Place BSP-specific unit test sources and programs into the + ``testsuites/unit/bsps`` directory. + +* Place all other unit test sources and programs into the + ``testsuites/unit`` directory. + +* Use dashes (``-``) to separate parts of a file name. Use only dashes, the + digits ``0`` to ``9``, and the lower case characters ``a`` to ``z`` for file + names. In particular, do not use underscores (``_``). + +* The parts of a file name shall be separated by dashes and ordered from most + general (left) to more specific (right), for example ``tc-task-construct.c``. + +* The file names associated with tests shall be unique within the system since + the test framework prints out only the base file names. + +* Use the prefix ``tc-`` for test case files. + +* Use the prefix ``tr-`` for test runner files. + +* Use the prefix ``ts-`` for test suite files. + +* Use the prefix ``tx-`` for test extension files (test support code). + +* Tests for fatal errors shall have ``fatal`` as the most general file part, + for example ``ts-fatal-too-large-tls-size.c``. + +* Validation test suites shall have ``validation`` as the most general file + part, for example ``ts-validation-no-clock-0.c``. + +* Unit test suites shall have ``unit`` as the most general file part, for + example ``ts-unit-no-clock-0.c``. + +* Architecture-specific files shall have the architecture name as a file part, + for example ``ts-fatal-sparc-leon3-clock-initialization.c``. + +* BSP-specific files shall have the BSP family or variant name as a file part, + for example ``tc-sparc-gr712rc.c``. + +* Architecture-specific or BSP-specific tests shall use the ``enabled-by`` + attribute of the associated specification item to make the build item + conditional, for example: + + .. code-block:: yaml + + ... + build-type: objects + enabled-by: arm + type: build + ... + + .. code-block:: yaml + + ... + build-type: test-program + enabled-by: bsps/sparc/leon3 + type: build + ... + +Verify the Specification Items +------------------------------ + +The ``./specverify.py`` script verifies that the specification items have the +format documented in :ref:`ReqEngSpecificationItems`. To some extent the +values of attributes are verified as well. |