From 59312aa9653a9d4133209e25e21ff9724ecd476f Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 20 May 2020 19:42:11 +0200 Subject: eng: Split up requirements engineering chapter This allows to more easily generate the specification item section with a script using specification items. Update #3715. --- eng/req/items.rst | 520 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 520 insertions(+) create mode 100644 eng/req/items.rst (limited to 'eng/req/items.rst') diff --git a/eng/req/items.rst b/eng/req/items.rst new file mode 100644 index 0000000..0c13bb2 --- /dev/null +++ b/eng/req/items.rst @@ -0,0 +1,520 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) + +.. _ReqEngSpecItems: + +Specification Items +=================== + +The technical specification of RTEMS will contain requirements, specializations +of requirements, :ref:`test procedures `, +:ref:`test suites `, :ref:`test cases `, and +:ref:`requirement validations `. These things will be called +*specification items* or just *items* if it is clear from the context. + +The specification items are stored in files in :term:`YAML` format with a +defined set of key-value pairs called attributes. The key name shall match +with the pattern defined by the regular expression +``[a-zA-Z0-9][a-zA-Z0-9-]+``. In particular, key names which begin with an +underscore (``_``) are reserved for internal use in tools. + +Each specification item shall have the following attributes: + +enabled-by + The value shall be a list of expressions. An expression is an operator + or an option. An option evaluates to true if it is included the set of + enabled options of the configuration. An operator is a dictionary with + exactly one key and a value. Valid keys are *and*, *or*, and *not*: + + * The value of the *and* operator shall be a list of expressions. It + evaluates to the *logical and* of all outcomes of the expressions in + the list. + + * The value of the *or* operator shall be a list of expressions. It + evaluates to the *logical or* of all outcomes of the expressions in + the list. + + * The value of the *not* operator shall be an expression. It negates + the outcome of its expression. + + The outcome of a list of expressions without an operator is the + *logical or* of all outcomes of the expressions in the list. An empty + list evaluates to true. Examples: + + .. code-block:: none + + enabled-by: + - RTEMS_SMP + + .. code-block:: none + + enabled-by: + - and: + - RTEMS_NETWORKING + - not: RTEMS_SMP + + .. code-block:: none + + enabled-by: + - and: + - not: TEST_DEBUGGER01_EXCLUDE + - or: + - arm + - i386 + +links + The value shall be a list of key-value pairs defining links to other + specification items. The list is ordered and defines the order in + which links are processed. There shall be a key *role* with an + unspecified value. There shall be a key *uid* with a relative UID to + the item referenced by this link. Other keys are type-specific. + Example: + + .. code-block:: yaml + + links: + - role: build-dependency + uid: optpwrdwnhlt + - role: build-dependency + uid: ../../bspopts + - role: build-dependency + uid: ../start + +type + The value shall be the specification :ref:`item type `. + +The following attributes are used in specification items of various types: + +.. _ReqEngItemAttrLicense: + +SPDX-License-Identifier + The value should be ``BSD-2-Clause OR CC-BY-SA-4.0``. If content is + imported from external sources, then the corresponding license shall be + used. Acceptable licenses are BSD-2-Clause and CC-BY-SA-4.0. The + copyright holder of the external work should be asked to allow a + dual-licensing BSD-2-Clause or CC-BY-SA-4.0. This allows generation of + BSD-2-Clause licensed source code and CC-BY-SA-4.0 licensed documentation. + +.. _ReqEngItemAttrCopyrights: + +copyrights + The value shall be a list of copyright statements of the following formats: + + * ``Copyright (C) `` + + * ``Copyright (C) , `` + + See also :ref:`FileHeaderCopyright`. + +.. _ReqEngItemTypes: + +Item Types +---------- + +Specification items can have all sorts of *types*. The selection of types and +the level of detail depends on a particular standard and product model. We need +enough flexibility to be in line with ECSS-E-ST-10-06 and possible future +applications of other standards. Each item may have a list of types. Valid +types are listed below. This list may change over time. If new types are +added, then a mapping between types should be specified. The item types and +their definition is work in progress. A list of types follows: + +* requirement + + * functional - Functional requirements shall describe the behaviour of the + software product under specific conditions. + + * *capability* + + * *dependability-function* + + * *function* + + * *operational* - Operational requirements shall + + * define the operation modes (e.g. initialization, multitasking, termination), + + * describe the operation modes, and + + * describe the operation mode transitions. + + * *safety-function* + + * non-functional + + * *build-configuration* + + * *constraint* + + * *design* + + * *interface* + + * *interface-requirement* + + * *maintainability* + + * *performance* + + * *portability* + + * *quality* + + * *reliability* + + * *resource* + + * *safety* + +* *test-procedure* + +* *test-suite* + +* *test-case* + +* *validation-by-analysis* + +* *validation-by-inspection* + +* *validation-by-review-of-design* + +* *validation-platform* + +.. image:: ../../images/eng/req-spec-items.* + :scale: 70 + :align: center + +Requirements +------------ + +All requirement specification items shall have the following attribute: + +rationale: + The rationale or justification of the specification item. + +Build Configuration +------------------- + +Build configuration requirements define what needs to be built (libraries, +object files, test executables, etc.) and how (configuration option header +files, compiler flags, linker flags, etc.). The goal is to generate build +files (Makefile or waf) and content for the Software Configuration File (SCF) +from it. A YAML scheme needs to be defined for this purpose. + +.. _ReqEngInterfaceReq: + +Interface Requirement +--------------------- + +Interface requirements shall describe the high level aspects of interfaces. +The item type shall be *interface-requirement*. + +.. _ReqEngInterface: + +Interface +--------- + +.. warning:: + + This is work in progress. + +Interface items shall specify the interface of the software product to other +software products and the hardware. The item type shall be *interface*. The +interface items shall have an *interface-category* which is one of the +following and nothing else: + +* *application*: Application interface items shall describe the interface + between the software product and the application (:term:`API`). The goal is + to generate header files with Doxygen markup and user manual documentation + parts from the application interface specification. + +* *application-configuration*: Application configuration items shall define + parameters of the software product which can be set by the application at + link-time. The goal is to generate user manual documentation parts and test + cases from the application configuration specification. + +* *architecture*: Architecture interface items shall define the + interface between the software product and the processor architecture + (:term:`ABI`). + +* *gcc*: GCC interface items shall define the interface between the software + product and GCC components such as libgcc.a, libatomic.a, libgomp.a, + libstdc++.a, etc. + +* *hardware*: Hardware interface items shall define the interface between the + software product and the hardware. + +* *newlib*: Newlib interface items shall define the interface between the + software product and the Newlib (libc.a). + +The interface items shall have an *interface-type* which is one of the +following and nothing else: + +* *configuration-option* + +* *define* + +* *enum* + +* *function* + +* *header* + +* *macro* + +* *register-block* + +* *structure* + +* *typedef* + +* *union* + +* *variable* + +.. _ReqEngInterfaceApplicationConfigGroups: + +Interface - Application Configuration Groups +-------------------------------------------- + +The application configuration group items shall have the following attribute +specializations: + +SPDX-License-Identifier + See :ref:`SPDX-License-Identifier `. + +appl-config-group-description: + The value shall be the description of this application configuration group. + +appl-config-group-name: + The value shall be the name of this application configuration group. + +copyrights + See :ref:`copyrights `. + +interface-type + The interface type value shall be *appl-config-group*. + +link + There shall be a link to a higher level requirement. + +text + The application configuration group requirement. + +type + The type value shall be *interface*. + +.. _ReqEngInterfaceApplicationConfigOptions: + +Interface - Application Configuration Options +--------------------------------------------- + +The application configuration option items shall have the following attribute +specializations: + +SPDX-License-Identifier + See :ref:`SPDX-License-Identifier `. + +appl-config-option-constraint + This attribute shall be present only for *initializer* and *integer* + type options. The value shall be a dictionary of the following optional + key-value pairs. + + custom + The value shall be a list of constraints in natural language. Use the + following wording: + + The value of this configuration option shall be ... + + min + The value shall be the minimum value of the option. + + max + The value shall be the maximum value of the option. + + links + The value shall be a list of relative UIDs to constraints. + + set + The value shall be the list of valid values of the option. + +appl-config-option-default + This attribute shall be present only for *feature* type options. The value + shall be a description of the default configuration in case this boolean + feature define is undefined. Use the following wording: + + If this configuration option is undefined, then ... + +appl-config-option-default-value + This attribute shall be present only for *initializer* and *integer* + type options. The value shall be an initializer, an integer, or a + descriptive text. + +appl-config-option-description + For *feature* and *feature-enable* type options, the value shall be a + description of the configuration in case this boolean feature define is + defined. Use the following wording: + + In case this configuration option is defined, then ... + + For *initializer* and *integer* options, the value shall describe the + effect of the option value. The description should focus on the average + use-case. It should not cover potential problems, constraints, obscure + use-cases, corner cases and everything which makes matters complicated. + Add these things to *appl-config-option-constraint* and + *appl-config-option-notes*. Use the following wording: + + The value of this configuration option defines ... + +appl-config-option-index + The value shall be a list of entries for the document index. By default, + the application configuration option name is added to the index. + +appl-config-option-name + The value shall be the name of the application configuration option. Use a + pattern of ``CONFIGURE_[A-Z0-9_]+`` for the name. + +appl-config-option-notes + The value shall be the notes for this option. The notes should explain + everything which was omitted from the description. It should cover all the + details, special cases, usage notes, error conditions, configuration + dependencies, and references. + +appl-config-option-type + The value shall be one of the following and nothing else: + + feature + Use this type for boolean feature opions which have a behaviour in the + default configuration which is not just that the feature is disabled. + + feature-enable + Use this type for boolean feature opions which just enables a feature. + + initializer + Use this type for options which initialize a data structure. + + integer + Use this type for integer options. + +copyrights + See :ref:`copyrights `. + +interface-type + The interface type value shall be *appl-config-option*. + +link + There shall be a link to the application configuration group to which this + option belongs. + +text + The application configuration option requirement. + +type + The type value shall be *interface*. + +.. _ReqEngTestProcedure: + +Test Procedure +-------------- + +Test procedures shall be executed by the Qualification Toolchain. + +The test procedure items shall have the following attribute +specializations: + +type + The type value shall be *test-procedure*. + +text + The purpose of this test procedure. + +platform + There shall be links to validation platform requirements. + +steps + The test procedure steps. Could be a list of key-value pairs. The key + is the step name and the value is a description of the actions + performed in this step. + +.. _ReqEngTestSuite: + +Test Suite +---------- + +Test suites shall use the :ref:`RTEMS Test Framework `. + +The test suite items shall have the following attribute specializations: + +type + The type value shall be *test-suite*. + +text + The test suite description. + +.. _ReqEngTestCase: + +Test Case +--------- + +Test cases shall use the :ref:`RTEMS Test Framework `. + +The test case items shall have the following attribute specializations: + +type + The type value shall be *test-case*. + +link + The link to the requirement validated by this test case or no links if + this is a unit or integration test case. + +ref + If this is a unit test case, then a reference to the :term:`software + item` under test shall be provided. If this is an integration test + case, then a reference to the integration under test shall be provided. + The integration is identified by its Doxygen group name. + +text + A short description of the test case. + +inputs + The inputs to execute the test case. + +outputs + The expected outputs. + +The test case code may be also contained in the test case specification +item in a *code* attribute. This is subject to discussion on the RTEMS +mailing list. Alternatively, the test code could be placed directly in +source files. A method is required to find the test case specification of +a test case code and vice versa. + +.. _ReqEngResAndPerf: + +Resources and Performance +------------------------- + +Normally, resource and performance requirements are formulated like this: + +* The resource U shall need less than V storage units. + +* The operation Y shall complete within X time units. + +Such statements are difficult to make for a software product like RTEMS which +runs on many different target platforms in various configurations. So, the +performance requirements of RTEMS shall be stated in terms of benchmarks. The +benchmarks are run on the project-specific target platform and configuration. +The results obtained by the benchmark runs are reported in a human readable +presentation. The application designer can then use the benchmark results to +determine if its system performance requirements are met. The benchmarks shall +be executed under different environment conditions, e.g. varying cache states +(dirty, empty, valid) and system bus load generated by other processors. The +application designer shall have the ability to add additional environment +conditions, e.g. system bus load by DMA engines or different system bus +arbitration schemes. + +To catch resource and performance regressions via test suite runs there shall be +a means to specify threshold values for the measured quantities. The threshold +values should be provided for each validation platform. How this can be done +and if the threshold values are maintained by the RTEMS Project is subject to +discussion. -- cgit v1.2.3