.. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de) Requirements for Requirements ============================= .. _ReqEngIdent: Identification -------------- Each requirement shall have a unique identifier (UID). The question is in which scope should it be unique? Ideally, it should be universally unique. Therefore all UIDs used to link one specification item to another should use relative UIDs. This ensures that the RTEMS requirements can be referenced easily in larger systems though a system-specific prefix. The standard ECSS-E-ST-10-06C recommends in section 8.2.6 that the identifier should reflect the type of the requirement and the life profile situation. Other standards may have other recommendations. To avoid a bias of RTEMS in the direction of ECSS, this recommendation will not be followed. The *absolute UID* of a specification item (for example a requirement) is defined by a leading ``/`` and the path of directories from the specification base directory to the file of the item separated by ``/`` characters and the file name without the ``.yml`` extension. For example, a specification item contained in the file :file:`build/cpukit/librtemscpu.yml` inside a :file:`spec` directory has the absolute UID of ``/build/cpukit/librtemscpu``. The *relative UID* to a specification item is defined by the path of directories from the file containing the source specification item to the file of the destination item separated by ``/`` characters and the file name of the destination item without the ``.yml`` extension. For example the relative UID from ``/build/bsps/sparc/leon3/grp`` to ``/build/bsps/bspopts`` is ``../../bspopts``. Basically, the valid characters of an UID are determined by the file system storing the item files. By convention, UID characters shall be restricted to the following set defined by the regular expression ``[a-zA-Z0-9_-]+``. Use ``-`` as a separator inside an UID part. In documents the URL-like prefix ``spec:`` shall be used to indicated specification item UIDs. The UID scheme for RTEMS requirements shall be component based. For example, the UID ``spec:/classic/task/create-err-invaddr`` may specify that the :c:func:`rtems_task_create` directive shall return a status of ``RTEMS_INVALID_ADDRESS`` if the ``id`` parameter is ``NULL``. A initial requirement item hierarchy could be this: * build (building RTEMS BSPs and libraries) * acfg (application configuration groups) * opt (application configuration options) * classic * task * create-* (requirements for :c:func:`rtems_task_create`) * delete-* (requirements for :c:func:`rtems_task_delete`) * exit-* (requirements for :c:func:`rtems_task_exit`) * getaff-* (requirements for :c:func:`rtems_task_get_affinity`) * getpri-* (requirements for :c:func:`rtems_task_get_priority`) * getsched-* (requirements for :c:func:`rtems_task_get_scheduler`) * ident-* (requirements for :c:func:`rtems_task_ident`) * issusp-* (requirements for :c:func:`rtems_task_is_suspended`) * iter-* (requirements for :c:func:`rtems_task_iterate`) * mode-* (requirements for :c:func:`rtems_task_mode`) * restart-* (requirements for :c:func:`rtems_task_restart`) * resume* (requirements for :c:func:`rtems_task_resume`) * self* (requirements for :c:func:`rtems_task_self`) * setaff-* (requirements for :c:func:`rtems_task_set_affinity`) * setpri-* (requirements for :c:func:`rtems_task_set_priority`) * setsched* (requirements for :c:func:`rtems_task_set_scheduler`) * start-* (requirements for :c:func:`rtems_task_start`) * susp-* (requirements for :c:func:`rtems_task_suspend`) * wkafter-* (requirements for :c:func:`rtems_task_wake_after`) * wkwhen-* (requirements for :c:func:`rtems_task_wake_when`) * sema * ... * posix * ... A more detailed naming scheme and guidelines should be established. We have to find the right balance between the length of UIDs and self-descriptive UIDs. A clear scheme for all Classic API managers may help to keep the UIDs short and descriptive. The specification of the validation of requirements should be maintained also by specification items. For each requirement directory there should be a validation subdirectory named *test*, e.g. :file:`spec/classic/task/test`. A test specification directory may contain also validations by analysis, by inspection, and by design, see :ref:`ReqEngValidation`. Level of Requirements --------------------- The level of a requirement shall be expressed with one of the verbal forms listed below and nothing else. The level of requirements are derived from RFC 2119 :cite:`RFC2119` and ECSS-E-ST-10-06C :cite:`ECSS_E_ST_10_06C`. Absolute Requirements ~~~~~~~~~~~~~~~~~~~~~ Absolute requirements shall be expressed with the verbal form *shall* and no other terms. Absolute Prohibitions ~~~~~~~~~~~~~~~~~~~~~ Absolute prohibitions shall be expressed with the verbal form *shall not* and no other terms. .. warning:: Absolute prohibitions may be difficult to validate. They should not be used. Recommendations ~~~~~~~~~~~~~~~ Recommendations shall be expressed with the verbal forms *should* and *should not* and no other terms with guidance from RFC 2119: SHOULD This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. Permissions ~~~~~~~~~~~ Permissions shall be expressed with the verbal form *may* and no other terms with guidance from RFC 2119: MAY This word, or the adjective "OPTIONAL", mean that an item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.) Possibilities and Capabilities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Possibilities and capabilities shall be expressed with the verbal form *can* and no other terms. .. _ReqEngSyntax: 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`, :cite:`Mavin:2016:LLEARS`, and `Alisair Mavin's web site `_. The patterns are: * Ubiquitous The shall . * Event-driven **When** , the shall . * State-driven **While** , the shall . * Unwanted behaviour **If** , **then** the shall . * Optional **Where** , the shall . * Complex **Where** , **where** , ..., **where** , **while** , **while** , ..., **while** , **when** , the shall . **Where** , **where** , ..., **where** , **while** , **while** , ..., **while** , **if** , **then** the shall . 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 platform, CPU port options, and build configuration options (e.g. uniprocessor vs. SMP). Wording Restrictions -------------------- To prevent the expression of imprecise requirements, the following terms shall not be used in requirement formulations: * "acceptable" * "adequate" * "almost always" * "and/or" * "appropriate" * "approximately" * "as far as possible" * "as much as practicable" * "best" * "best possible" * "easy" * "efficient" * "e.g." * "enable" * "enough" * "etc." * "few" * "first rate" * "flexible" * "generally" * "goal" * "graceful" * "great" * "greatest" * "ideally" * "i.e." * "if possible" * "in most cases" * "large" * "many" * "maximize" * "minimize" * "most" * "multiple" * "necessary" * "numerous" * "optimize" * "ought to" * "probably" * "quick" * "rapid" * "reasonably" * "relevant" * "robust" * "satisfactory" * "several" * "shall be included but not limited to" * "simple" * "small" * "some" * "state-of-the-art". * "sufficient" * "suitable" * "support" * "systematically" * "transparent" * "typical" * "user-friendly" * "usually" * "versatile" * "when necessary" For guidelines to avoid these terms see Table 11-2, "Some ambiguous terms to avoid in requirements" in :cite:`Wiegers:2013:SR`. There should be some means to enforce that these terms are not used, e.g. through a client-side pre-commit Git hook, a server-side pre-receive Git hook, or some scripts run by special build commands. Separate Requirements --------------------- Requirements shall be stated separately. A bad example is: spec:/classic/task/create The task create directive shall evaluate the parameters, allocate a task object and initialize it. To make this a better example, it should be split into separate requirements: spec:/classic/task/create When the task create directive is called with valid parameters and a free task object exists, the task create directive shall assign the identifier of an initialized task object to the ``id`` parameter and return the ``RTEMS_SUCCESSFUL`` status. spec:/classic/task/create-err-toomany If no free task objects exists, the task create directive shall return the ``RTEMS_TOO_MANY`` status. spec:/classic/task/create-err-invaddr If the ``id`` parameter is ``NULL``, the task create directive shall return the ``RTEMS_INVALID_ADDRESS`` status. spec:/classic/task/create-err-invname If the ``name`` parameter is invalid, the task create directive shall return the ``RTEMS_INVALID_NAME`` status. ... Conflict Free Requirements -------------------------- Requirements shall not be in conflict with each other inside a specification. A bad example is: spec:/classic/sema/mtx-obtain-wait When a mutex is not available, the mutex obtain directive shall enqueue the calling thread on the wait queue of the mutex. spec:/classic/sema/mtx-obtain-err-unsat If a mutex is not available, the mutex obtain directive shall return the RTEMS_UNSATISFIED status. To resolve this conflict, a condition may be added: spec:/classic/sema/mtx-obtain-wait When a mutex is not available and the RTEMS_WAIT option is set, the mutex obtain directive shall enqueue the calling thread on the wait queue of the mutex. spec:/classic/sema/mtx-obtain-err-unsat If a mutex is not available, when the RTEMS_WAIT option is not set, the mutex obtain directive shall return the RTEMS_UNSATISFIED status. Use of Project-Specific Terms and Abbreviations ----------------------------------------------- All project-specific terms and abbreviations used to formulate requirements shall be defined in the project glossary. .. _ReqEngJustReq: Justification of Requirements ----------------------------- Each requirement shall have a rationale or justification recorded in a dedicated section of the requirement file. See ``rationale`` attribute for :ref:`ReqEngSpecificationItems`. .. _ReqEngValidation: Requirement Validation ---------------------- The validation of each :ref:`SpecTypeRequirementItemType` item shall be accomplished by one or more specification items of the types :ref:`SpecTypeTestCaseItemType` or :ref:`SpecTypeRequirementValidationItemType` through a link from the validation item to the requirement item with the :ref:`SpecTypeRequirementValidationLinkRole`. Validation by test is strongly recommended. The choice of any other validation method shall be strongly justified. The requirements author is obligated to provide the means to validate the requirement with detailed instructions. .. _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.