diff options
Diffstat (limited to 'eng/req-eng.rst')
| -rw-r--r-- | eng/req-eng.rst | 1177 |
1 files changed, 0 insertions, 1177 deletions
diff --git a/eng/req-eng.rst b/eng/req-eng.rst deleted file mode 100644 index 61b82be..0000000 --- a/eng/req-eng.rst +++ /dev/null @@ -1,1177 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019 embedded brains GmbH - -.. |E40| replace:: ECSS-E-ST-40C - -.. |E10-06| replace:: ECSS-E-ST-10-06C - -.. _ReqEng: - -Software Requirements Engineering -********************************* - -Software engineering standards for critical software such as |E40| demand that -software requirements for a software product are collected in a software -requirements specification (technical specification in |E40| terms). They are -usually derived from system requirements (requirements baseline in |E40| -terms). RTEMS is designed as a reusable software product which can be utilized -by application designers to ease the development of their applications. The -requirements of the end system (system requirements) using RTEMS are only known -to the application designer. RTEMS itself is developed by the RTEMS -maintainers and they do not know the requirements of a particular end system in -general. RTEMS is designed as a real-time operating system to meet typical -system requirements for a wide range of applications. Its suitability for a -particular application must be determined by the application designer based on -the technical specification provided by RTEMS accompanied with performance data -for a particular target platform. - -Currently, no technical specification of RTEMS exists in the form of a -dedicated document. Since the beginning of the RTEMS evolution in the late -1980s it was developed iteratively. It was never developed in a waterfall -model. During initial development the RTEID :cite:`Motorola:1988:RTEID` and -later the ORKID :cite:`VITA:1990:ORKID` draft specifications were used as -requirements. These were evolving during the development and an iterative -approach was followed often using simple algorithms and coming back to -optimise. In 1993 and 1994 a subset of pthreads sufficient to support -:term:`GNAT` was added as requirements. At this time the Ada tasking was -defined, however, not implemented in GNAT, so this involved guessing during the -development. Later some adjustments were made when Ada tasking was actually -implemented. So, it was consciously iterative with the specifications evolving -and feedback from performance analysis. Benchmarks published from other real -time operating systems were used for comparison. Optimizations were carried -out until the results were comparable. Development was done with distinct -contractual phases and tasks for development, optimization, and the addition of -priority inheritance and rate monotonic scheduling. The pthreads requirement -has grown to be as much POSIX as possible. - -Portability from FreeBSD to use its network stack, USB stack, SD/MMC card stack -and device drivers resulted in another set of requirements. The addition of -support for symmetric multiprocessing (SMP) was a huge driver for change. It -was developed step by step and sponsored by several independent users with -completely different applications and target platforms in mind. The high -performance OpenMP support introduced the Futex as a new synchronization -primitive. - -.. topic:: Guidance - - A key success element of RTEMS is the ability to accept changes driven by - user needs and still keep the operating system stable enough for production - systems. Procedures that place a high burden on changes are doomed to be - discarded by the RTEMS Project. We have to keep this in mind when we - introduce a requirements management work flow which should be followed by - RTEMS community members and new contributors. - -We have to put in some effort first into the reconstruction of software -requirements through reverse engineering using the RTEMS documentation, test -cases, sources, standard references, mailing list archives, etc. as input. -Writing a technical specification for the complete RTEMS code base is probably -a job of several person-years. We have to get started with a moderate feature -set (e.g. subset of the Classic API) and extend it based on user demands step -by step. - -The development of the technical specification will take place in two phases. -The first phase tries to establish an initial technical specification for an -initial feature set. This technical specification will be integrated into -RTEMS as a big chunk. In the second phase the technical specification is -modified through arranged procedures. There will be procedures - -* to modify existing requirements, - -* add new requirements, and - -* mark requirements as obsolete. - -All procedures should be based on a peer review principles. - -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. As -a best effort approach, the name *RTEMS* shall be used as a part in all -requirement identifiers. This should ensure that the RTEMS requirements can be -referenced easily in larger systems. 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. - -.. topic:: Doorstop - - The UID of an item (requirement) is defined by its file name without the - extension. An UID consists of two parts, the prefix and a name or a number. - The parts are divided by an optional separator. The prefix is determined by - the document. - -The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or -more component names, and a name. Each part is separated by a "-" -character. For example, the UID RTEMS-CLASSIC-TASK-CREATERRINVADDR may specify -that the `rtems_task_create()` directive shall return a status of -`RTEMS_INVALID_ADDRESS` if the `id` parameter is `NULL`. - -.. topic:: Doorstop - - Doorstop uses documents to create namespaces (named a prefix in Doorstop). - For the example above, you can create the documents like this: - - .. code-block:: none - - doorstop create -s - RTEMS-CLASSIC -p RTEMS spec/classic - doorstop create -s - RTEMS-CLASSIC-TASK -p RTEMS-CLASSIC spec/classic/task - doorstop create -s - RTEMS-CLASSIC-SEMAPHORE -p RTEMS-CLASSIC spec/classic/semaphore - - The requirement files are organized in directories. - -A initial requirement item hierarchy could be this: - -* RTEMS - - * BUILD (building RTEMS BSPs and libraries) - - * CONFIG (application configuration) - - * CLASSIC - - * TASK - - * CREAT* (requirements for `rtems_task_create()`) - * DELT* (requirements for `rtems_task_delete()`) - * EXIT* (requirements for `rtems_task_exit()`) - * GETAFF* (requirements for `rtems_task_get_affinity()`) - * GETPRI* (requirements for `rtems_task_get_priority()`) - * GETSHD* (requirements for `rtems_task_get_scheduler()`) - * IDNT* (requirements for `rtems_task_ident()`) - * ISSUSP* (requirements for `rtems_task_is_suspended()`) - * ITER* (requirements for `rtems_task_iterate()`) - * MODE* (requirements for `rtems_task_mode()`) - * RESTRT* (requirements for `rtems_task_restart()`) - * RESUME* (requirements for `rtems_task_resume()`) - * SELF* (requirements for `rtems_task_self()`) - * SETAFF* (requirements for `rtems_task_set_affinity()`) - * SETPRI* (requirements for `rtems_task_set_priority()`) - * SETSHD* (requirements for `rtems_task_set_scheduler()`) - * START* (requirements for `rtems_task_start()`) - * SUSP* (requirements for `rtems_task_suspend()`) - * WKAFT* (requirements for `rtems_task_wake_after()`) - * WKWHN* (requirements for `rtems_task_wake_when()`) - - * Semaphore - - * ... - - * 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 -Doorstop. For each requirement document there should be a validation child -Doorstop document with a *TEST* component name, e.g. RTEMS-CLASSIC-TASK-TEST. A -test document 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 |E10-06| :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`, and -:cite:`Mavin:2016:LLEARS`. Please also have a look at the EARS quick reference -sheet :cite:`Uusitalo:2012:EARS`. The sentence types are: - -* Ubiquitous - - The <system name> shall <system response>. - -* Event-driven - - *When* <optional preconditions> <trigger>, the <system name> shall <system response>. - -* State-driven - - *While* <in state>, the <system name> shall <system response>. - -* Unwanted behaviour - - *If* <optional preconditions> <trigger>, *then* the <system name> shall <system response>. - -* Optional - - *Where* <feature>, the <system name> shall <system response>. - -The optional sentence type 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: - -RTEMS-CLASSIC-TASK-CRAT - 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: - -RTEMS-CLASSIC-TASK-CRAT - 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. - -RTEMS-CLASSIC-TASK-CRATERRTOOMANY - If no free task objects exists, the task create directive shall return the - RTEMS_TOO_MANY status. - -RTEMS-CLASSIC-TASK-CRATERRINVADDR - If the id parameter is NULL, the task create directive shall return the - RTEMS_INVALID_ADDRESS status. - -RTEMS-CLASSIC-TASK-CRATERRINVNAME - If the name parameter is not valid, 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: - -RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT - If a mutex is not available, the mutex obtain directive shall enqueue the - calling thread on the wait queue of the mutex. - -RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT - 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: - -RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT - If a mutex is not available, when the RTEMS_WAIT option is set, the mutex - obtain directive shall enqueue the calling thread on the wait queue of the - mutex. - -RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT - 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. - -.. topic:: Doorstop - - See *rationale* attribute for :ref:`ReqEngSpecItems`. - -.. _ReqEngSpecItems: - -Specification Items -=================== - -The technical specification of RTEMS will contain requirements, specializations -of requirements, :ref:`test procedures <ReqEngTestProcedure>`, -:ref:`test suites <ReqEngTestSuite>`, :ref:`test cases <ReqEngTestCase>`, and -:ref:`requirement validations <ReqEngValidation>`. These things will be called -*specification items* or just *items* if it is clear from the context. - -.. topic:: Doorstop - - Doorstop maintains *items* which are included in *documents*. The normal - use case is to store a requirement with meta-data in an item. However, - items can be also used to store other things like test procedures, test - suites, test cases, and requirement validations. Items contain key-value - pairs called attributes. Specializations of requirements may contain extra - attributes, e.g. interface, build, configuration requirements. All items - have the following standard Doorstop attributes: - - active - A boolean value which indicates if the requirement is active or not. - The value is included in the fingerprint via a document configuration - option. - - derived - A boolean value which indicates if the requirement is derived or not. - For the - `definition of derived <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#derived>`_. - see the Doorstop documentation. For RTEMS, this value shall be false - for all requirements. The value is not included in the fingerprint. - - normative - A boolean value which indicates if the requirement is normative or not. - For the - `definition of normative <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#normative>`_. - see the Doorstop documentation. For RTEMS, this value shall be true - for all requirements. The value is not included in the fingerprint. - - level - Indicates the presentation order within a document. For RTEMS, this - value shall be unused. The value is not included in the fingerprint. - - header - A header for an item. For RTEMS, this value shall be the empty string. - The value is not included in the fingerprint. - - reviewed - The fingerprint of the item. Maintain this attribute with the - `doorstop clear` command. - - links - The links from this item to parent items. Maintain this attribute with - the `doorstop link` command. The value is included in the fingerprint. - - ref - References to files and directories. See - `#365 <https://github.com/jacebrowning/doorstop/issues/365>`_, - The value is included in the fingerprint. - - text - The item text. The value is included in the fingerprint. - - All specification items shall have the following extended attributes: - - type: - A list of :ref:`item types <ReqEngItemTypes>`. The value is not - included in the fingerprint. - - enabled-by: - The value is a list of expressions. The value is included in the - fingerprint. 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 - -.. _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 ------------- - -.. topic:: Doorstop - - All requirement specification items shall have the following extended - attribute: - - rationale: - The rationale or justification of the specification item. The value is - **not** included in the fingerprint. - -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 ---------- - -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* - -.. _ReqEngInterfaceApplicationConfig: - -Interface - Application Configuration -------------------------------------- - -.. topic:: Doorstop - - The application configuration items shall have the following attribute - specializations: - - type - The type value shall be *interface*. - - interface-category - The interface category value shall be *application-configuration*. - - interface-type - The interface type value shall be *configuration-option*. - - link - There shall be a link to a higher level requirement. - - text - The application configuration requirement. - - configuration-category: - A category to which this application configuration option belongs. - - define: - The name of the configuration define. - - data-type: - The data type of the configuration define. - - value-range: - The range of valid values. - - default-value: - The default value. - - description: - The description of the application configuration. 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. - - note: - Notes for this application configuration. The notes should explain - everything which was omitted from the description. It should cover all - the details. - -.. _ReqEngTestProcedure: - -Test Procedure --------------- - -Test procedures shall be executed by the Qualification Toolchain. - -.. topic:: Doorstop - - 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 <RTEMSTestFramework>`. - -.. topic:: Doorstop - - 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 <RTEMSTestFramework>`. - -.. topic:: Doorstop - - 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. - -.. _ReqEngTrace: - -Traceability of Specification Items -=================================== - -The standard |E10-06| demands that requirements shall be under configuration -management, backwards-traceable and forward-traceable. Requirements are a -specialization of specification items in RTEMS. - -.. _ReqEngTraceHistory: - -History of Specification Items ------------------------------- - -The RTEMS specification items should placed in the RTEMS sources using Git for -version control. The history of specification items can be traced with Git. -Special commit procedures for changes in specification item files should be -established. For example, it should be allowed to change only one -specification item per commit. A dedicated Git commit message format may be -used as well, e.g. use of ``Approved-by:`` or ``Reviewed-by:`` lines which -indicate an agreed statement (similar to the -`Linux kernel patch submission guidelines <https://www.kernel.org/doc/html/latest//process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_). -Git commit procedures may be ensured through a server-side pre-receive hook. -The history of requirements may be also added to the specification items -directly in a ``revision`` attribute. This would make it possible to generate -the history information for documents without having the Git repository -available, e.g. from an RTEMS source release archive. - -.. _ReqEngTraceBackward: - -Backward Traceability of Specification Items --------------------------------------------- - -Providing backward traceability of specification items means that we must be -able to find the corresponding higher level specification item for each refined -specification item. This is a standard Doorstop feature. - -.. _ReqEngTraceForward: - -Forward Traceability of Specification Items -------------------------------------------- - -Providing forward traceability of specification items means that we must be -able to find all the refined specification items for each higher level -specification item. This is a standard Doorstop feature. The links from -parent to child specification items are implicitly defined by links from a -child item to a parent item. - -.. _ReqEngTraceReqArchDesign: - -Traceability between Software Requirements, Architecture and Design -------------------------------------------------------------------- - -The software requirements are implemented in Doorstop compatible YAML files. -The software architecture and design is written in Doxygen markup. Doxygen -markup is used throughout all header and source files. A Doxygen filter -program may be provided to place Doxygen markup in assembler files. The -software architecture is documented via Doxygen groups. Each Doxygen group -name should have a project-specific name and the name should be unique within -the project, e.g. RTEMSTopLevel\ MidLevel\ LowLevel. The link from a Doxygen -group to its parent group is realized through the `@ingroup` special command. -The link from a Doxygen group or software component to the corresponding -requirement is realized through a `@satisfy{req}` -`custom command <http://www.doxygen.nl/manual/custcmd.html>`_ -which needs the identifier of the requirement as its one and only parameter. -Only links to parents are explicitly given in the Doxygen markup. The links -from a parent to its children are only implicitly specified via the link from a -child to its parent. So, a tool must process all files to get the complete -hierarchy of software requirements, architecture and design. Links from a -software component to another software component are realized through automatic -Doxygen references or the ``@ref`` and ``@see`` special commands. - -.. _ReqEngValidation: - -Requirement Validation -====================== - -The validation of each requirement shall be accomplished by one or more of -the following methods and nothing else: - -* *By test*: A :ref:`ReqEngTestCase` specification item is provided to - demonstrate that the requirement is satisfied when the software product is - executed on the target platform. - -* *By analysis*: A statement is provided how the requirement is met, by - analysing static properties of the software product. - -* *By inspection*: A statement is provided how the requirement is met, by - inspection of the :term:`source code`. - -* *By review of design*: A rationale is provided to demonstrate how the - qualification requirement is satisfied implicitly by the software design. - -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. - -.. topic:: Doorstop - - For an item in a parent document it is checked that at least one item in a - child document has a link to it. For example a child document could - contain validation items. With this feature you can check that all - requirements are covered by at least one validation item. - - The requirement validation by analysis, by inspection, and by design - specification items shall have the following attribute specializations: - - type - The type attribute value shall be *validation-by-analysis*, - *validation-by-inspection*, or *validation-by-review-of-design*. - - link - There shall be exactly one link to the validated requirement. - - text - The statement or rational of the requirement validation. - -Requirement Management -====================== - -Change Control Board --------------------- - -Working with requirements usually involves a Change Control Board -(:term:`CCB`). The CCB of the RTEMS Project is the -`RTEMS developer mailing list <https://lists.rtems.org/mailman/listinfo/devel>`_. - -There are the following actors involved: - -* *RTEMS users*: Everyone using the RTEMS real-time operating system to design, - develop and build an application on top of it. - -* *RTEMS developers*: The persons developing and maintaining RTEMS. They write - patches to add or modify code, requirements, tests and documentation. - -* *RTEMS maintainers*: They are listed in the - `MAINTAINERS <https://git.rtems.org/rtems/tree/MAINTAINERS>`_ file and have - write access to the project repositories. - -Adding and changing requirements follows the normal patch review process. The -normal patch review process is described in the -`RTEMS User Manual <https://docs.rtems.org/branches/master/user/support/contrib.html#patch-review-process>`_. -Reviews and comments may be submitted by anyone, but a maintainer review is -required to approve *significant* changes. In addition for significant -changes, there should be at least one reviewer with a sufficient independence -from the author which proposes a new requirement or a change of an existing -requirement. Working in another company on different projects is sufficiently -independent. RTEMS maintainers do not know all the details, so they trust in -general people with experience on a certain platform. Sometimes no review -comments may appear in a reasonable time frame, then an implicit agreement to -the proposed changes is assumed. Patches can be sent at anytime, so -controlling changes in RTEMS requires a permanent involvement on the RTEMS -developer mailing list. - -For a qualification of RTEMS according to certain standards, the requirements -may be approved by an RTEMS user. The approval by RTEMS users is not the -concern of the RTEMS Project, however, the RTEMS Project should enable RTEMS -users to manage the approval of requirements easily. This information may be -also used by a independent authority which comes into play with an Independent -Software Verification and Validation (:term:`ISVV`). It could be used to -select a subset of requirements, e.g. look only at the ones approved by a -certain user. RTEMS users should be able to reference the determinative -content of requirements, test procedures, test cases and justification reports -in their own documentation. Changes in the determinative content should -invalidate all references to previous versions. - -Add a Requirement ------------------ - -.. image:: ../images/eng/req-add.* - :scale: 70 - :align: center - -.. _ReqEngModifyRequirement: - -Modify a Requirement --------------------- - -.. image:: ../images/eng/req-modify.* - :scale: 70 - :align: center - -Mark a Requirement as Obsolete ------------------------------- - -Requirements shall be never removed. They shall be marked as obsolete. This -ensures that requirement identifiers are not reused. The procedure to obsolete -a requirement is the same as the one to :ref:`modify a requirement -<ReqEngModifyRequirement>`. - -Tooling -======= - -Tool Requirements ------------------ - -To manage requirements some tool support is helpful. Here is a list of -requirements for the tool: - -* The tool shall be open source. - -* The tool should be actively maintained during the initial phase of the RTEMS - requirements specification. - -* The tool shall use plain text storage (no binary formats, no database). - -* The tool shall support version control via Git. - -* The tool should export the requirements in a human readable form using the - Sphinx documentation framework. - -* The tool shall support traceability of requirements to items external to the - tool. - -* The tool shall support traceability between requirements. - -* The tool shall support custom requirement attributes. - -* The tool should ensure that there are no cyclic dependencies between - requirements. - -* The tool should provide an export to :term:`ReqIF`. - -Tool Evaluation ---------------- - -During an evaluation phase the following tools were considered: - -* `aNimble <https://sourceforge.net/projects/nimble/>`_ -* :term:`Doorstop` -* `OSRMT <https://github.com/osrmt/osrmt>`_ -* `Papyrus <https://www.eclipse.org/papyrus/>`_ -* `ProR <https://www.eclipse.org/rmf/pror/>`_ -* `ReqIF Studio <https://formalmind.com/tools/studio/>`_ -* `Requirement Heap <https://sourceforge.net/projects/reqheap/>`_ -* `rmToo <http://rmtoo.florath.net/>`_ - -The tools aNimble, OSRMT and Requirement Heap were not selected since they use -a database. The tools Papyrus, ProR and ReqIF are Eclipse based and use -complex XML files for data storage. They were difficult to use and lack good -documentation/tutorials. The tools rmToo and Doorstop turned out to be the -best candidates to manage requirements in the RTEMS Project. The Doorstop tool -was selected as the first candidate mainly due a recommendation by an RTEMS -user. - -.. _ReqEngDoorstop: - -Selected Tool - Doorstop ------------------------- - -:term:`Doorstop` is a requirements management tool. It has a modern, -object-oriented and well-structured implementation in Python 3.6 under the -LGPLv3 license. It uses a continuous integration build with style checkers, -static analysis, documentation checks, code coverage, unit test and integration -tests. In 2019, the project was actively maintained. Pull requests for minor -improvements and new features were reviewed and integrated within days. Each -requirement is contained in a single file in :term:`YAML` format. Requirements -are organized in documents and can be linked to each other -:cite:`Browning:2014:RequirementsManagement`. - -Doorstop consists of three main parts - -* a stateless command line tool `doorstop`, - -* a file format with a pre-defined set of attributes (YAML), and - -* a primitive GUI tool (not intended to be used). - -For RTEMS, its scope will be extended to manage specifications in general. The -primary reason for selecting Doorstop as the requirements management tool for -the RTEMS Project is its data format which allows a high degree of -customization. Doorstop uses a directed, acyclic graph of items. The items are -files in YAML format. Each item has a set of -`standard attributes <https://doorstop.readthedocs.io/en/latest/reference/item/>`_ -(key-value pairs). - -The use case for the standard attributes is requirements management. However, -Doorstop is capable to manage custom attributes as well. We will heavily use -custom attributes for the specification items. Enabling Doorstop to effectively -use custom attributes was done specifically for the RTEMS Project in several -patch sets. - -A key feature of Doorstop is the `fingerprint of items -<https://doorstop.readthedocs.io/en/latest/reference/item/#reviewed>`_. -For the RTEMS Project, the fingerprint hash algorithm was changed from MD5 to -SHA256. In 2019, it can be considered cryptographically secure. The -fingerprint should cover the normative values of an item, e.g. comments etc. are -not included. The fingerprint helps RTEMS users to track the significant -changes in the requirements (in contrast to all the changes visible in Git). As -an example use case, a user may want to assign a project-specific status to -specification items. This can be done with a table which contains columns for - -1. the UID of the item, - -2. the fingerprint, and - -3. the project-specific status. - -Given the source code of RTEMS (which includes the specification items) and this -table, it can be determined which items are unchanged and which have another -status (e.g. unknown, changed, etc.). |