diff options
Diffstat (limited to '')
| -rw-r--r-- | eng/req/howto.rst | 134 |
1 files changed, 107 insertions, 27 deletions
diff --git a/eng/req/howto.rst b/eng/req/howto.rst index bd94b77..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, 2022 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG How-To ====== @@ -131,12 +131,12 @@ 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 @@ -177,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 ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -189,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 ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -201,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 ^^^^^^^^^^^^^^^^ @@ -226,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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -238,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 @@ -263,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: @@ -300,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 @@ -327,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 @@ -344,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 @@ -371,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 @@ -608,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 @@ -1125,6 +1127,84 @@ the following post-condition states. 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 ------------------------------ |