Changeset d4ba908 in rtems-docs


Ignore:
Timestamp:
Apr 22, 2020, 11:43:25 AM (4 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
5, master
Children:
a23b1fb
Parents:
2d22d74
git-author:
Sebastian Huber <sebastian.huber@…> (04/22/20 11:43:25)
git-committer:
Sebastian Huber <sebastian.huber@…> (05/05/20 05:03:40)
Message:

eng: Update requirements engineering chapter

Update requirements engineering chapter due to the removal of Doorstop
as the requirements management tool.

Update the application configuration related specification items.

Update #3715.

Files:
7 edited

Legend:

Unmodified
Added
Removed
  • eng/req-eng.rst

    r2d22d74 rd4ba908  
    11.. SPDX-License-Identifier: CC-BY-SA-4.0
    22
    3 .. Copyright (C) 2019 embedded brains GmbH
     3.. Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
    44
    55.. |E40| replace:: ECSS-E-ST-40C
     
    9494
    9595Each requirement shall have a unique identifier (UID).  The question is in
    96 which scope should it be unique?  Ideally, it should be universally unique. As
    97 a best effort approach, the name *RTEMS* shall be used as a part in all
    98 requirement identifiers. This should ensure that the RTEMS requirements can be
    99 referenced easily in larger systems.  The standard ECSS-E-ST-10-06C recommends
    100 in section 8.2.6 that the identifier should reflect the type of the requirement
    101 and the life profile situation.  Other standards may have other
    102 recommendations.  To avoid a bias of RTEMS in the direction of ECSS, this
    103 recommendation will not be followed.
    104 
    105 .. topic:: Doorstop
    106 
    107     The UID of an item (requirement) is defined by its file name without the
    108     extension. An UID consists of two parts, the prefix and a name or a number.
    109     The parts are divided by an optional separator. The prefix is determined by
    110     the document.
    111 
    112 The UID scheme for RTEMS requirements is the concatenation of *RTEMS*, one or
    113 more component names, and a name.  Each part is separated by a "-"
    114 character.  For example, the UID RTEMS-CLASSIC-TASK-CREATERRINVADDR may specify
    115 that the `rtems_task_create()` directive shall return a status of
    116 `RTEMS_INVALID_ADDRESS` if the `id` parameter is `NULL`.
    117 
    118 .. topic:: Doorstop
    119 
    120     Doorstop uses documents to create namespaces (named a prefix in Doorstop).
    121     For the example above, you can create the documents like this:
    122 
    123     .. code-block:: none
    124 
    125         doorstop create -s - RTEMS-CLASSIC -p RTEMS spec/classic
    126         doorstop create -s - RTEMS-CLASSIC-TASK -p RTEMS-CLASSIC spec/classic/task
    127         doorstop create -s - RTEMS-CLASSIC-SEMAPHORE -p RTEMS-CLASSIC spec/classic/semaphore
    128 
    129     The requirement files are organized in directories.
     96which scope should it be unique?  Ideally, it should be universally unique.
     97Therefore all UIDs used to link one specification item to another should use
     98relative UIDs.  This ensures that the RTEMS requirements can be referenced
     99easily in larger systems though a system-specific prefix.  The standard
     100ECSS-E-ST-10-06C recommends in section 8.2.6 that the identifier should reflect
     101the type of the requirement and the life profile situation.  Other standards
     102may have other recommendations.  To avoid a bias of RTEMS in the direction of
     103ECSS, this recommendation will not be followed.
     104
     105The *absolute UID* of a specification item (for example a requirement) is
     106defined by a leading ``/`` and the path of directories from the specification
     107base directory to the file of the item separated by ``/`` characters and the
     108file name without the ``.yml`` extension.  For example, a specification item
     109contained in the file :file:`build/cpukit/librtemscpu.yml` inside a
     110:file:`spec` directory has the absolute UID of ``/build/cpukit/librtemscpu``.
     111
     112The *relative UID* to a specification item is defined by the path of
     113directories from the file containing the source specification item to the file
     114of the destination item separated by ``/`` characters and the file name of the
     115destination item without the ``.yml`` extension.  For example the relative UID
     116from ``/build/bsps/sparc/leon3/grp`` to ``/build/bsps/bspopts`` is
     117``../../bspopts``.
     118
     119Basically, the valid characters of an UID are determined by the file system
     120storing the item files.  By convention, UID characters shall be restricted to
     121the following set defined by the regular expression ``[a-zA-Z0-9_-]+``.  Use
     122``-`` as a separator inside an UID part.
     123
     124In documents the URL-like prefix ``spec:`` shall be used to indicated
     125specification item UIDs.
     126
     127The UID scheme for RTEMS requirements shall be component based.  For example,
     128the UID ``spec:/classic/task/create-err-invaddr`` may specify that the
     129:c:func:`rtems_task_create` directive shall return a status of
     130``RTEMS_INVALID_ADDRESS`` if the ``id`` parameter is ``NULL``.
    130131
    131132A initial requirement item hierarchy could be this:
    132133
    133 * RTEMS
    134 
    135   * BUILD (building RTEMS BSPs and libraries)
    136 
    137   * CONFIG (application configuration)
    138 
    139   * CLASSIC
    140 
    141     * TASK
    142 
    143       * CREAT* (requirements for `rtems_task_create()`)
    144       * DELT* (requirements for `rtems_task_delete()`)
    145       * EXIT* (requirements for `rtems_task_exit()`)
    146       * GETAFF* (requirements for `rtems_task_get_affinity()`)
    147       * GETPRI* (requirements for `rtems_task_get_priority()`)
    148       * GETSHD* (requirements for `rtems_task_get_scheduler()`)
    149       * IDNT* (requirements for `rtems_task_ident()`)
    150       * ISSUSP* (requirements for `rtems_task_is_suspended()`)
    151       * ITER* (requirements for `rtems_task_iterate()`)
    152       * MODE* (requirements for `rtems_task_mode()`)
    153       * RESTRT* (requirements for `rtems_task_restart()`)
    154       * RESUME* (requirements for `rtems_task_resume()`)
    155       * SELF* (requirements for `rtems_task_self()`)
    156       * SETAFF* (requirements for `rtems_task_set_affinity()`)
    157       * SETPRI* (requirements for `rtems_task_set_priority()`)
    158       * SETSHD* (requirements for `rtems_task_set_scheduler()`)
    159       * START* (requirements for `rtems_task_start()`)
    160       * SUSP* (requirements for `rtems_task_suspend()`)
    161       * WKAFT* (requirements for `rtems_task_wake_after()`)
    162       * WKWHN* (requirements for `rtems_task_wake_when()`)
    163 
    164     * Semaphore
    165 
    166       * ...
    167 
    168   * POSIX
    169 
    170   * ...
     134* build (building RTEMS BSPs and libraries)
     135
     136* acfg (application configuration groups)
     137
     138    * opt (application configuration options)
     139
     140* classic
     141
     142    * task
     143
     144        * create-* (requirements for :c:func:`rtems_task_create`)
     145        * delete-* (requirements for :c:func:`rtems_task_delete`)
     146        * exit-* (requirements for :c:func:`rtems_task_exit`)
     147        * getaff-* (requirements for :c:func:`rtems_task_get_affinity`)
     148        * getpri-* (requirements for :c:func:`rtems_task_get_priority`)
     149        * getsched-* (requirements for :c:func:`rtems_task_get_scheduler`)
     150        * ident-* (requirements for :c:func:`rtems_task_ident`)
     151        * issusp-* (requirements for :c:func:`rtems_task_is_suspended`)
     152        * iter-* (requirements for :c:func:`rtems_task_iterate`)
     153        * mode-* (requirements for :c:func:`rtems_task_mode`)
     154        * restart-* (requirements for :c:func:`rtems_task_restart`)
     155        * resume* (requirements for :c:func:`rtems_task_resume`)
     156        * self* (requirements for :c:func:`rtems_task_self`)
     157        * setaff-* (requirements for :c:func:`rtems_task_set_affinity`)
     158        * setpri-* (requirements for :c:func:`rtems_task_set_priority`)
     159        * setsched* (requirements for :c:func:`rtems_task_set_scheduler`)
     160        * start-* (requirements for :c:func:`rtems_task_start`)
     161        * susp-* (requirements for :c:func:`rtems_task_suspend`)
     162        * wkafter-* (requirements for :c:func:`rtems_task_wake_after`)
     163        * wkwhen-* (requirements for :c:func:`rtems_task_wake_when`)
     164
     165    * sema
     166
     167        * ...
     168
     169* posix
     170
     171* ...
    171172
    172173A more detailed naming scheme and guidelines should be established.  We have to
     
    175176descriptive.
    176177
    177 The specification of the validation of requirements should be maintained also by
    178 Doorstop.  For each requirement document there should be a validation child
    179 Doorstop document with a *TEST* component name, e.g. RTEMS-CLASSIC-TASK-TEST.  A
    180 test document may contain also validations by analysis, by inspection, and by
    181 design, see :ref:`ReqEngValidation`.
     178The specification of the validation of requirements should be maintained also
     179by specification items.  For each requirement directory there should be a
     180validation subdirectory named *test*, e.g. :file:`spec/classic/task/test`.  A
     181test specification directory may contain also validations by analysis, by
     182inspection, and by design, see :ref:`ReqEngValidation`.
    182183
    183184Level of Requirements
     
    364365Requirements shall be stated separately.  A bad example is:
    365366
    366 RTEMS-CLASSIC-TASK-CRAT
     367spec:/classic/task/create
    367368    The task create directive shall evaluate the parameters, allocate a task
    368369    object and initialize it.
     
    370371To make this a better example, it should be split into separate requirements:
    371372
    372 RTEMS-CLASSIC-TASK-CRAT
     373spec:/classic/task/create
    373374    When the task create directive is called with valid parameters and a free
    374375    task object exists, the task create directive shall assign the identifier of
    375     an initialized task object to the id parameter and return the
    376     RTEMS_SUCCESSFUL status.
    377 
    378 RTEMS-CLASSIC-TASK-CRATERRTOOMANY
     376    an initialized task object to the ``id`` parameter and return the
     377    ``RTEMS_SUCCESSFUL`` status.
     378
     379spec:/classic/task/create-err-toomany
    379380    If no free task objects exists, the task create directive shall return the
    380     RTEMS_TOO_MANY status.
    381 
    382 RTEMS-CLASSIC-TASK-CRATERRINVADDR
    383     If the id parameter is NULL, the task create directive shall return the
    384     RTEMS_INVALID_ADDRESS status.
    385 
    386 RTEMS-CLASSIC-TASK-CRATERRINVNAME
    387     If the name parameter is not valid, the task create directive shall return
    388     the RTEMS_INVALID_NAME status.
     381    ``RTEMS_TOO_MANY`` status.
     382
     383spec:/classic/task/create-err-invaddr
     384    If the ``id`` parameter is ``NULL``, the task create directive shall return the
     385    ``RTEMS_INVALID_ADDRESS`` status.
     386
     387spec:/classic/task/create-err-invname
     388    If the ``name`` parameter is invalid, the task create directive shall
     389    return the ``RTEMS_INVALID_NAME`` status.
    389390
    390391    ...
     
    396397A bad example is:
    397398
    398 RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT
    399     If a mutex is not available, the mutex obtain directive shall enqueue the
     399spec:/classic/sema/mtx-obtain-wait
     400    When a mutex is not available, the mutex obtain directive shall enqueue the
    400401    calling thread on the wait queue of the mutex.
    401402
    402 RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT
     403spec:/classic/sema/mtx-obtain-err-unsat
    403404    If a mutex is not available, the mutex obtain directive shall return the
    404405    RTEMS_UNSATISFIED status.
     
    406407To resolve this conflict, a condition may be added:
    407408
    408 RTEMS-CLASSIC-SEMAPHORE-MTXOBWAIT
    409     If a mutex is not available, when the RTEMS_WAIT option is set, the mutex
     409spec:/classic/sema/mtx-obtain-wait
     410    When a mutex is not available and the RTEMS_WAIT option is set, the mutex
    410411    obtain directive shall enqueue the calling thread on the wait queue of the
    411412    mutex.
    412413
    413 RTEMS-CLASSIC-SEMAPHORE-MTXOBERRUNSAT
     414spec:/classic/sema/mtx-obtain-err-unsat
    414415    If a mutex is not available, when the RTEMS_WAIT option is not set, the
    415416    mutex obtain directive shall return the RTEMS_UNSATISFIED status.
     
    427428
    428429Each requirement shall have a rationale or justification recorded in a
    429 dedicated section of the requirement file.
    430 
    431 .. topic:: Doorstop
    432 
    433     See *rationale* attribute for :ref:`ReqEngSpecItems`.
     430dedicated section of the requirement file.  See *rationale* attribute for
     431:ref:`ReqEngSpecItems`.
    434432
    435433.. _ReqEngSpecItems:
     
    444442*specification items* or just *items* if it is clear from the context.
    445443
    446 .. topic:: Doorstop
    447 
    448     Doorstop maintains *items* which are included in *documents*.  The normal
    449     use case is to store a requirement with meta-data in an item.  However,
    450     items can be also used to store other things like test procedures, test
    451     suites, test cases, and requirement validations.  Items contain key-value
    452     pairs called attributes.  Specializations of requirements may contain extra
    453     attributes, e.g. interface, build, configuration requirements. All items
    454     have the following standard Doorstop attributes:
    455 
    456     active
    457         A boolean value which indicates if the requirement is active or not.
    458         The value is included in the fingerprint via a document configuration
    459         option.
    460 
    461     derived
    462         A boolean value which indicates if the requirement is derived or not.
    463         For the
    464         `definition of derived <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#derived>`_.
    465         see the Doorstop documentation.  For RTEMS, this value shall be false
    466         for all requirements.  The value is not included in the fingerprint.
    467 
    468     normative
    469         A boolean value which indicates if the requirement is normative or not.
    470         For the
    471         `definition of normative <https://github.com/jacebrowning/doorstop/blob/develop/docs/reference/item.md#normative>`_.
    472         see the Doorstop documentation.  For RTEMS, this value shall be true
    473         for all requirements.  The value is not included in the fingerprint.
    474 
    475     level
    476         Indicates the presentation order within a document.  For RTEMS, this
    477         value shall be unused.  The value is not included in the fingerprint.
    478 
    479     header
    480         A header for an item.  For RTEMS, this value shall be the empty string.
    481         The value is not included in the fingerprint.
    482 
    483     reviewed
    484         The fingerprint of the item.  Maintain this attribute with the
    485         `doorstop clear` command.
    486 
    487     links
    488         The links from this item to parent items.  Maintain this attribute with
    489         the `doorstop link` command.  The value is included in the fingerprint.
    490 
    491     ref
    492         References to files and directories. See
    493         `#365 <https://github.com/jacebrowning/doorstop/issues/365>`_,
    494         The value is included in the fingerprint.
    495 
    496     text
    497         The item text.  The value is included in the fingerprint.
    498 
    499     All specification items shall have the following extended attributes:
    500 
    501     type:
    502         A list of :ref:`item types <ReqEngItemTypes>`.  The value is not
    503         included in the fingerprint.
    504 
    505     enabled-by:
    506         The value is a list of expressions.  The value is included in the
    507         fingerprint.  An expression is an operator or an option.  An option
    508         evaluates to true if it is included the set of enabled options of  the
    509         configuration.  An operator is a dictionary with exactly one key and a
    510         value.  Valid keys are `and`, `or`, and `not`:
    511 
    512         * The value of the `and` operator shall be a list of expressions.  It
    513           evaluates to the `logical and` of all outcomes of the expressions in
    514           the list.
    515 
    516         * The value of the `or` operator shall be a list of expressions.  It
    517           evaluates to the `logical or` of all outcomes of the expressions in
    518           the list.
    519 
    520         * The value of the `not` operator shall be an expression.  It negates
    521           the outcome of its expression.
    522 
    523         The outcome of a list of expressions without an operator is the
    524         `logical or` of all outcomes of the expressions in the list.  An empty
    525         list evaluates to true.  Examples:
    526 
    527         .. code-block:: none
    528 
    529             enabled-by:
    530             - RTEMS_SMP
    531 
    532         .. code-block:: none
    533 
    534             enabled-by:
    535             - and:
    536               - RTEMS_NETWORKING
    537               - not: RTEMS_SMP
    538 
    539         .. code-block:: none
    540 
    541             enabled-by:
    542             - and:
    543               - not: TEST_DEBUGGER01_EXCLUDE
    544               - or:
    545                 - arm
    546                 - i386
     444The specification items are stored in files in :term:`YAML` format with a
     445defined set of key-value pairs called attributes.  The key name shall match
     446with the pattern defined by the regular expression
     447``[a-zA-Z0-9][a-zA-Z0-9-]+``.  In particular, key names which begin with an
     448underscore (``_``) are reserved for internal use in tools.
     449
     450Each specification item shall have the following attributes:
     451
     452enabled-by
     453    The value shall be a list of expressions.  An expression is an operator
     454    or an option.  An option evaluates to true if it is included the set of
     455    enabled options of the configuration.  An operator is a dictionary with
     456    exactly one key and a value.  Valid keys are *and*, *or*, and *not*:
     457
     458    * The value of the *and* operator shall be a list of expressions.  It
     459      evaluates to the *logical and* of all outcomes of the expressions in
     460      the list.
     461
     462    * The value of the *or* operator shall be a list of expressions.  It
     463      evaluates to the *logical or* of all outcomes of the expressions in
     464      the list.
     465
     466    * The value of the *not* operator shall be an expression.  It negates
     467      the outcome of its expression.
     468
     469    The outcome of a list of expressions without an operator is the
     470    *logical or* of all outcomes of the expressions in the list.  An empty
     471    list evaluates to true.  Examples:
     472
     473    .. code-block:: none
     474
     475        enabled-by:
     476        - RTEMS_SMP
     477
     478    .. code-block:: none
     479
     480        enabled-by:
     481        - and:
     482          - RTEMS_NETWORKING
     483          - not: RTEMS_SMP
     484
     485    .. code-block:: none
     486
     487        enabled-by:
     488        - and:
     489          - not: TEST_DEBUGGER01_EXCLUDE
     490          - or:
     491            - arm
     492            - i386
     493
     494links
     495    The value shall be a list of key-value pairs defining links to other
     496    specification items.  The list is ordered and defines the order in
     497    which links are processed.  There shall be a key *role* with an
     498    unspecified value.  There shall be a key *uid* with a relative UID to
     499    the item referenced by this link.  Other keys are type-specific.
     500    Example:
     501
     502    .. code-block:: yaml
     503
     504        links:
     505        - role: build-dependency
     506          uid: optpwrdwnhlt
     507        - role: build-dependency
     508          uid: ../../bspopts
     509        - role: build-dependency
     510          uid: ../start
     511
     512type
     513    The value shall be the specification :ref:`item type <ReqEngItemTypes>`.
     514
     515The following attributes are used in specification items of various types:
     516
     517.. _ReqEngItemAttrLicense:
     518
     519SPDX-License-Identifier
     520    The value should be ``BSD-2-Clause OR CC-BY-SA-4.0``.  If content is
     521    imported from external sources, then the corresponding license shall be
     522    used.  Acceptable licenses are BSD-2-Clause and CC-BY-SA-4.0.  The
     523    copyright holder of the external work should be asked to allow a
     524    dual-licensing BSD-2-Clause or CC-BY-SA-4.0.  This allows generation of
     525    BSD-2-Clause licensed source code and CC-BY-SA-4.0 licensed documentation.
     526
     527.. _ReqEngItemAttrCopyrights:
     528
     529copyrights
     530    The value shall be a list of copyright statements of the following formats:
     531
     532    * ``Copyright (C) <YEAR> <COPYRIGHT HOLDER>``
     533
     534    * ``Copyright (C) <FIRST YEAR>, <LAST YEAR> <COPYRIGHT HOLDER>``
     535
     536    See also :ref:`FileHeaderCopyright`.
    547537
    548538.. _ReqEngItemTypes:
     
    627617------------
    628618
    629 .. topic:: Doorstop
    630 
    631     All requirement specification items shall have the following extended
    632     attribute:
    633 
    634     rationale:
    635         The rationale or justification of the specification item.  The value is
    636         **not** included in the fingerprint.
     619All requirement specification items shall have the following attribute:
     620
     621rationale:
     622    The rationale or justification of the specification item.
    637623
    638624Build Configuration
     
    658644---------
    659645
     646.. warning::
     647
     648    This is work in progress.
     649
    660650Interface items shall specify the interface of the software product to other
    661651software products and the hardware.  The item type shall be *interface*.  The
     
    712702* *variable*
    713703
    714 .. _ReqEngInterfaceApplicationConfig:
    715 
    716 Interface - Application Configuration
    717 -------------------------------------
    718 
    719 .. topic:: Doorstop
    720 
    721     The application configuration items shall have the following attribute
    722     specializations:
    723 
    724     type
    725         The type value shall be *interface*.
    726 
    727     interface-category
    728         The interface category value shall be *application-configuration*.
    729 
    730     interface-type
    731         The interface type value shall be *configuration-option*.
    732 
    733     link
    734         There shall be a link to a higher level requirement.
    735 
    736     text
    737         The application configuration requirement.
    738 
    739     configuration-category:
    740         A category to which this application configuration option belongs.
    741 
    742     define:
    743         The name of the configuration define.
    744 
    745     data-type:
    746         The data type of the configuration define.
    747 
    748     value-range:
    749         The range of valid values.
    750 
    751     default-value:
    752         The default value.
    753 
    754     description:
    755         The description of the application configuration.  The description
    756         should focus on the average use-case.  It should not cover potential
    757         problems, constraints, obscure use-cases, corner cases and everything
    758         which makes matters complicated.
    759 
    760     note:
    761         Notes for this application configuration.  The notes should explain
    762         everything which was omitted from the description.  It should cover all
    763         the details.
     704.. _ReqEngInterfaceApplicationConfigGroups:
     705
     706Interface - Application Configuration Groups
     707--------------------------------------------
     708
     709The application configuration group items shall have the following attribute
     710specializations:
     711
     712SPDX-License-Identifier
     713    See :ref:`SPDX-License-Identifier <ReqEngItemAttrLicense>`.
     714
     715appl-config-group-description:
     716    The value shall be the description of this application configuration group.
     717
     718appl-config-group-name:
     719    The value shall be the name of this application configuration group.
     720
     721copyrights
     722    See :ref:`copyrights <ReqEngItemAttrCopyrights>`.
     723
     724interface-type
     725    The interface type value shall be *appl-config-group*.
     726
     727link
     728    There shall be a link to a higher level requirement.
     729
     730text
     731    The application configuration group requirement.
     732
     733type
     734    The type value shall be *interface*.
     735
     736.. _ReqEngInterfaceApplicationConfigOptions:
     737
     738Interface - Application Configuration Options
     739---------------------------------------------
     740
     741The application configuration option items shall have the following attribute
     742specializations:
     743
     744SPDX-License-Identifier
     745    See :ref:`SPDX-License-Identifier <ReqEngItemAttrLicense>`.
     746
     747appl-config-option-constraint
     748    This attribute shall be present only for *initializer* and *integer*
     749    type options.  The value shall be a dictionary of the following optional
     750    key-value pairs.
     751
     752    custom
     753        The value shall be a list of constraints in natural language.  Use the
     754        following wording:
     755
     756            The value of this configuration option shall be ...
     757
     758    min
     759        The value shall be the minimum value of the option.
     760
     761    max
     762        The value shall be the maximum value of the option.
     763
     764    links
     765        The value shall be a list of relative UIDs to constraints.
     766
     767    set
     768        The value shall be the list of valid values of the option.
     769
     770appl-config-option-default
     771    This attribute shall be present only for *feature* type options.  The value
     772    shall be a description of the default configuration in case this boolean
     773    feature define is undefined.  Use the following wording:
     774
     775        If this configuration option is undefined, then ...
     776
     777appl-config-option-default-value
     778    This attribute shall be present only for *initializer* and *integer*
     779    type options.  The value shall be an initializer, an integer, or a
     780    descriptive text.
     781
     782appl-config-option-description
     783    For *feature* and *feature-enable* type options, the value shall be a
     784    description of the configuration in case this boolean feature define is
     785    defined.  Use the following wording:
     786
     787        In case this configuration option is defined, then ...
     788
     789    For *initializer* and *integer* options, the value shall describe the
     790    effect of the option value.  The description should focus on the average
     791    use-case.  It should not cover potential problems, constraints, obscure
     792    use-cases, corner cases and everything which makes matters complicated.
     793    Add these things to *appl-config-option-constraint* and
     794    *appl-config-option-notes*.  Use the following wording:
     795
     796        The value of this configuration option defines ...
     797
     798appl-config-option-index
     799    The value shall be a list of entries for the document index.  By default,
     800    the application configuration option name is added to the index.
     801
     802appl-config-option-name
     803    The value shall be the name of the application configuration option.  Use a
     804    pattern of ``CONFIGURE_[A-Z0-9_]+`` for the name.
     805
     806appl-config-option-notes
     807    The value shall be the notes for this option.  The notes should explain
     808    everything which was omitted from the description.  It should cover all the
     809    details, special cases, usage notes, error conditions, configuration
     810    dependencies, and references.
     811
     812appl-config-option-type
     813    The value shall be one of the following and nothing else:
     814
     815    feature
     816        Use this type for boolean feature opions which have a behaviour in the
     817        default configuration which is not just that the feature is disabled.
     818
     819    feature-enable
     820        Use this type for boolean feature opions which just enables a feature.
     821
     822    initializer
     823        Use this type for options which initialize a data structure.
     824
     825    integer
     826        Use this type for integer options.
     827
     828copyrights
     829    See :ref:`copyrights <ReqEngItemAttrCopyrights>`.
     830
     831interface-type
     832    The interface type value shall be *appl-config-option*.
     833
     834link
     835    There shall be a link to the application configuration group to which this
     836    option belongs.
     837
     838text
     839    The application configuration option requirement.
     840
     841type
     842    The type value shall be *interface*.
    764843
    765844.. _ReqEngTestProcedure:
     
    770849Test procedures shall be executed by the Qualification Toolchain.
    771850
    772 .. topic:: Doorstop
    773 
    774     The test procedure items shall have the following attribute
    775     specializations:
    776 
    777     type
    778         The type value shall be *test-procedure*.
    779 
    780     text
    781         The purpose of this test procedure.
    782 
    783     platform
    784         There shall be links to validation platform requirements.
    785 
    786     steps
    787         The test procedure steps.  Could be a list of key-value pairs.  The key
    788         is the step name and the value is a description of the actions
    789         performed in this step.
     851The test procedure items shall have the following attribute
     852specializations:
     853
     854type
     855    The type value shall be *test-procedure*.
     856
     857text
     858    The purpose of this test procedure.
     859
     860platform
     861    There shall be links to validation platform requirements.
     862
     863steps
     864    The test procedure steps.  Could be a list of key-value pairs.  The key
     865    is the step name and the value is a description of the actions
     866    performed in this step.
    790867
    791868.. _ReqEngTestSuite:
     
    796873Test suites shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.
    797874
    798 .. topic:: Doorstop
    799 
    800     The test suite items shall have the following attribute specializations:
    801 
    802     type
    803         The type value shall be *test-suite*.
    804 
    805     text
    806         The test suite description.
     875The test suite items shall have the following attribute specializations:
     876
     877type
     878    The type value shall be *test-suite*.
     879
     880text
     881    The test suite description.
    807882
    808883.. _ReqEngTestCase:
     
    813888Test cases shall use the :ref:`RTEMS Test Framework <RTEMSTestFramework>`.
    814889
    815 .. topic:: Doorstop
    816 
    817     The test case items shall have the following attribute specializations:
    818 
    819     type
    820         The type value shall be *test-case*.
    821 
    822     link
    823         The link to the requirement validated by this test case or no links if
    824         this is a unit or integration test case.
    825 
    826     ref
    827         If this is a unit test case, then a reference to the :term:`software
    828         item` under test shall be provided.  If this is an integration test
    829         case, then a reference to the integration under test shall be provided.
    830         The integration is identified by its Doxygen group name.
    831 
    832     text
    833         A short description of the test case.
    834 
    835     inputs
    836         The inputs to execute the test case.
    837 
    838     outputs
    839         The expected outputs.
    840 
    841     The test case code may be also contained in the test case specification
    842     item in a *code* attribute.  This is subject to discussion on the RTEMS
    843     mailing list.  Alternatively, the test code could be placed directly in
    844     source files.  A method is required to find the test case specification of
    845     a test case code and vice versa.
     890The test case items shall have the following attribute specializations:
     891
     892type
     893    The type value shall be *test-case*.
     894
     895link
     896    The link to the requirement validated by this test case or no links if
     897    this is a unit or integration test case.
     898
     899ref
     900    If this is a unit test case, then a reference to the :term:`software
     901    item` under test shall be provided.  If this is an integration test
     902    case, then a reference to the integration under test shall be provided.
     903    The integration is identified by its Doxygen group name.
     904
     905text
     906    A short description of the test case.
     907
     908inputs
     909    The inputs to execute the test case.
     910
     911outputs
     912    The expected outputs.
     913
     914The test case code may be also contained in the test case specification
     915item in a *code* attribute.  This is subject to discussion on the RTEMS
     916mailing list.  Alternatively, the test code could be placed directly in
     917source files.  A method is required to find the test case specification of
     918a test case code and vice versa.
    846919
    847920.. _ReqEngResAndPerf:
     
    899972Git commit procedures may be ensured through a server-side pre-receive hook.
    900973The history of requirements may be also added to the specification items
    901 directly in a ``revision`` attribute.  This would make it possible to generate
     974directly in a *revision* attribute.  This would make it possible to generate
    902975the history information for documents without having the Git repository
    903976available, e.g. from an RTEMS source release archive.
     
    910983Providing backward traceability of specification items means that we must be
    911984able to find the corresponding higher level specification item for each refined
    912 specification item.  This is a standard Doorstop feature.
     985specification item.  A custom tool needs to verify this.
    913986
    914987.. _ReqEngTraceForward:
     
    919992Providing forward traceability of specification items means that we must be
    920993able to find all the refined specification items for each higher level
    921 specification item.  This is a standard Doorstop feature.  The links from
     994specification item.  A custom tool needs to verify this.  The links from
    922995parent to child specification items are implicitly defined by links from a
    923996child item to a parent item.
     
    9281001-------------------------------------------------------------------
    9291002
    930 The software requirements are implemented in Doorstop compatible YAML files.
    931 The software architecture and design is written in Doxygen markup.  Doxygen
    932 markup is used throughout all header and source files.  A Doxygen filter
    933 program may be provided to place Doxygen markup in assembler files.  The
    934 software architecture is documented via Doxygen groups.  Each Doxygen group
    935 name should have a project-specific name and the name should be unique within
    936 the project, e.g.  RTEMSTopLevel\ MidLevel\ LowLevel.  The link from a Doxygen
    937 group to its parent group is realized through the ``@ingroup`` special command.
    938 The link from a Doxygen group or :term:`software component` to the
    939 corresponding requirement is realized through a ``@satisfy{req}``
    940 `custom command <http://www.doxygen.nl/manual/custcmd.html>`_
    941 which needs the identifier of the requirement as its one and only parameter.
    942 Only links to parents are explicitly given in the Doxygen markup.  The links
    943 from a parent to its children are only implicitly specified via the link from a
    944 child to its parent.  So, a tool must process all files to get the complete
    945 hierarchy of software requirements, architecture and design. Links from a
    946 software component to another software component are realized through automatic
    947 Doxygen references or the ``@ref`` and ``@see`` special commands.
     1003The software requirements are implemented in custom YAML files, see
     1004:ref:`ReqEngSpecItems`.  The software architecture and design is written in
     1005Doxygen markup.  Doxygen markup is used throughout all header and source files.
     1006A Doxygen filter program may be provided to place Doxygen markup in assembler
     1007files.  The software architecture is documented via Doxygen groups.  Each
     1008Doxygen group name should have a project-specific name and the name should be
     1009unique within the project, e.g.  RTEMSTopLevel\ MidLevel\ LowLevel.  The link
     1010from a Doxygen group to its parent group is realized through the ``@ingroup``
     1011special command.  The link from a Doxygen group or :term:`software component`
     1012to the corresponding requirement is realized through a ``@satisfy{req}``
     1013`custom command <http://www.doxygen.nl/manual/custcmd.html>`_ which needs the
     1014identifier of the requirement as its one and only parameter.  Only links to
     1015parents are explicitly given in the Doxygen markup.  The links from a parent to
     1016its children are only implicitly specified via the link from a child to its
     1017parent.  So, a tool must process all files to get the complete hierarchy of
     1018software requirements, architecture and design. Links from a software component
     1019to another software component are realized through automatic Doxygen references
     1020or the ``@ref`` and ``@see`` special commands.
    9481021
    9491022.. _ReqEngValidation:
     
    9721045provide the means to validate the requirement with detailed instructions.
    9731046
    974 .. topic:: Doorstop
    975 
    976     For an item in a parent document it is checked that at least one item in a
    977     child document has a link to it.  For example a child document could
    978     contain validation items.  With this feature you can check that all
    979     requirements are covered by at least one validation item.
    980 
    981     The requirement validation by analysis, by inspection, and by design
    982     specification items shall have the following attribute specializations:
    983 
    984     type
    985         The type attribute value shall be *validation-by-analysis*,
    986         *validation-by-inspection*, or *validation-by-review-of-design*.
    987 
    988     link
    989         There shall be exactly one link to the validated requirement.
    990 
    991     text
    992         The statement or rational of the requirement validation.
     1047For a specification item in a parent directory it could be checked that at
     1048least one item in a subdirectory has a link to it.  For example a subdirectory
     1049could contain validation items.  With this feature you could check that all
     1050requirements are covered by at least one validation item.
     1051
     1052The requirement validation by analysis, by inspection, and by design
     1053specification items shall have the following attribute specializations:
     1054
     1055type
     1056    The type attribute value shall be *validation-by-analysis*,
     1057    *validation-by-inspection*, or *validation-by-review-of-design*.
     1058
     1059link
     1060    There shall be exactly one link to the validated requirement.
     1061
     1062text
     1063    The statement or rational of the requirement validation.
    9931064
    9941065Requirement Management
     
    11221193.. _ReqEngDoorstop:
    11231194
    1124 Selected Tool - Doorstop
    1125 ------------------------
     1195Best Available Tool - Doorstop
     1196------------------------------
    11261197
    11271198:term:`Doorstop` is a requirements management tool.  It has a modern,
     
    11461217primary reason for selecting Doorstop as the requirements management tool for
    11471218the RTEMS Project is its data format which allows a high degree of
    1148 customization.  Doorstop uses a directed, acyclic graph of items.  The items are
    1149 files in YAML format.  Each item has a set of
     1219customization.  Doorstop uses a directed, acyclic graph (DAG) of items.  The
     1220items are files in YAML format.  Each item has a set of
    11501221`standard attributes <https://doorstop.readthedocs.io/en/latest/reference/item/>`_
    11511222(key-value pairs).
     
    11761247table, it can be determined which items are unchanged and which have another
    11771248status (e.g. unknown, changed, etc.).
     1249
     1250After some initial work with Doorstop some issues surfaced
     1251(`#471 <https://github.com/doorstop-dev/doorstop/issues/471>`_)
     1252It turned out that Doorstop is not designed as a library and contains to much
     1253policy. This results in a lack of flexibility required for the RTEMS Project.
     1254
     12551. Its primary use case is requirements management. So, it has some standard
     1256   attributes useful in this domain, like derived, header, level, normative,
     1257   ref, reviewed, and text. However, we want to use it more generally for
     1258   specification items and these attributes make not always sense.  Having them
     1259   in every item is just overhead and may cause confusion.
     1260
     12612. The links cannot have custom attributes, e.g. role, enabled-by. With
     1262   link-specific attributes you could have multiple DAGs formed up by the same
     1263   set of items.
     1264
     12653. Inside a document (directory) items are supposed to have a common type (set
     1266   of attributes). We would like to store at a hierarchy level also distinct
     1267   specializations.
     1268
     12694. The verification of the items is quite limited.  We need verification with
     1270   type-based rules.
     1271
     12725. The UIDs in combination with the document hierarchy lead to duplication,
     1273   e.g. a/b/c/a-b-c-d.yml. You have the path (a/b/c) also in the file name
     1274   (a-b-c). You cannot have relative UIDs in links (e.g. ../parent-req) . The
     1275   specification items may contain multiple requirements, e.g. min/max
     1276   attributes.  There is no way to identify them.
     1277
     12786. The links are ordered by Doorstop alphabetically by UID. For some
     1279   applications, it would be better to use the order specified by the user. For
     1280   example, we want to use specification items for a new build system. Here it
     1281   is handy if you can express things like this: A is composed of B and C.
     1282   Build B before C.
  • images/eng/req-add.puml

    r2d22d74 rd4ba908  
    11' SPDX-License-Identifier: CC-BY-SA-4.0
    22
    3 ' Copyright (C) 2019 embedded brains GmbH
     3' Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
    44
    55@startuml
     
    77start
    88
    9 :Invoke: ""doorstop add RTEMS"";
     9:Create file: ""spec/component/new.yml"";
    1010
    1111note right
    12   This will create a new requirement.
    13   For this activity its UID shall be NEW.
    14   It is located in a file NEW.yml.
     12  Create a new file in the specification
     13  directory.  For this activity its UID
     14  shall be spec:/component/new.  It is
     15  located in the file spec/component/new.yml.
    1516end note
    1617
    1718while (Needs a link to a parent requirement?) is (Yes)
    18   :Invoke: ""doorstop link NEW PARENT"";
     19  :Add link to links attribute of file: ""spec/component/new.yml"";
    1920endwhile (No)
    2021
    2122repeat
    22   :Invoke: ""doorstop edit NEW"";
     23  :Edit file: ""spec/component/new.yml"";
    2324
    24   :Edit the requirement according to your needs and save it;
     25  :Add attributes according to your needs and save the file;
    2526
    26   :Commit NEW.yml with a proper message;
     27  :Commit the changes with a proper message;
    2728
    2829  :Send the patch to the devel@rtems.org mailing list for review;
     
    3334  :Push the commit to the project repository;
    3435else (No)
    35   :Discard the NEW requirement;
     36  :Discard the new requirement;
    3637endif
    3738
  • images/eng/req-modify.puml

    r2d22d74 rd4ba908  
    11' SPDX-License-Identifier: CC-BY-SA-4.0
    22
    3 ' Copyright (C) 2019 embedded brains GmbH
     3' Copyright (C) 2019, 2020 embedded brains GmbH (http://www.embedded-brains.de)
    44
    55@startuml
     
    88
    99repeat
    10   :Invoke: ""doorstop edit REQ"";
     10  :Edit: ""spec/component/req.yml"";
    1111
    1212  note right
    13     For this activity the UID
    14     of the requirement shall be REQ.
    15     It is located in a file REQ.yml.
     13    For this activity the UID of the
     14    requirement shall be spec:/component/req.
     15    It is located in a file spec/component/req.yml.
    1616  end note
    1717
    18   :Edit the requirement according to your needs and save it;
     18  :Edit the attributes according to your needs and save the file;
    1919
    20   :Commit REQ.yml with a proper message;
     20  :Commit the changes with a proper message;
    2121
    2222  :Send the patch to the devel@rtems.org mailing list for review;
Note: See TracChangeset for help on using the changeset viewer.