Changeset dd60a4a in rtems-docs


Ignore:
Timestamp:
01/21/22 16:02:27 (6 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
7073017
Parents:
1ba0f41
git-author:
Sebastian Huber <sebastian.huber@…> (01/21/22 16:02:27)
git-committer:
Sebastian Huber <sebastian.huber@…> (01/24/22 14:35:30)
Message:

eng: Add script usage to how-to

Update #3715.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/req/howto.rst

    r1ba0f41 rdd60a4a  
    11.. SPDX-License-Identifier: CC-BY-SA-4.0
    22
    3 .. Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
     3.. Copyright (C) 2020, 2022 embedded brains GmbH (http://www.embedded-brains.de)
    44
    55How-To
     
    3333    cd rtems-central
    3434    . env/bin/activate
     35
     36View the Specification Graph
     37----------------------------
     38
     39The specification items form directed graphs through :ref:`SpecTypeLink`
     40attributes.  Each link has a role.  For a particular view only specific roles
     41may be of interest.  For example, the requirements specification of RTEMS
     42starts with the ``spec:/req/root`` specification item.  It should form a tree
     43(connected graph without cycles).  A text representation of the tree can be
     44printed with the ``./specview.py`` script:
     45
     46.. code-block:: none
     47
     48    cd rtems-central
     49    . env/bin/activate
     50    ./specview.py
     51
     52This gives the following example output (shortened):
     53
     54.. code-block:: none
     55
     56    /req/root (type=requirement/non-functional/design)
     57      /bsp/if/group (type=requirement/non-functional/design-group, role=requirement-refinement)
     58        /bsp/if/acfg-idle-task-body (type=interface/unspecified-define, role=interface-ingroup)
     59          /bsp/sparc/leon3/req/idle-task-body (type=requirement/functional/function, role=interface-function)
     60            /bsp/sparc/leon3/req/idle-task-power-down (type=requirement/functional/function, role=requirement-refinement)
     61              /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation)
     62            /bsp/sparc/leon3/req/idle-task-power-down-errata (type=requirement/functional/function, role=requirement-refinement)
     63              /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation)
     64
     65The actual specification graph depends on build configuration options which
     66enable or disable specification items.  The ``--enabled`` command line option
     67may be used to specify the build configuration options, for example
     68``--enabled=sparc,bsps/sparc/leon3,sparc/gr740,RTEMS_SMP,RTEMS_QUAL``.
     69
     70The ``./specview.py`` script can display other views of the specification
     71through the ``--filter`` command line option.  Transition maps of
     72:ref:`SpecTypeActionRequirementItemType` items can be printed using the
     73``--filter=action-table`` or ``--filter=action-list`` filters.  For example,
     74``./specview.py --filter=action-table /rtems/timer/req/create`` prints
     75something like this:
     76
     77.. code-block:: none
     78
     79    .. table::
     80        :class: longtable
     81
     82        ===== ========== ======= ===== ==== ======= ======= =====
     83        Entry Descriptor Name    Id    Free Status  Name    IdVar
     84        ===== ========== ======= ===== ==== ======= ======= =====
     85        0     0          Valid   Valid Yes  Ok      Valid   Set
     86        1     0          Valid   Valid No   TooMany Invalid Nop
     87        2     0          Valid   Null  Yes  InvAddr Invalid Nop
     88        3     0          Valid   Null  No   InvAddr Invalid Nop
     89        4     0          Invalid Valid Yes  InvName Invalid Nop
     90        5     0          Invalid Valid No   InvName Invalid Nop
     91        6     0          Invalid Null  Yes  InvName Invalid Nop
     92        7     0          Invalid Null  No   InvName Invalid Nop
     93        ===== ========== ======= ===== ==== ======= ======= =====
     94
     95For example, ``./specview.py --filter=action-list /rtems/timer/req/create``
     96prints something like this:
     97
     98.. code-block:: none
     99
     100    Status = Ok, Name = Valid, IdVar = Set
     101
     102        * Name = Valid, Id = Valid, Free = Yes
     103
     104    Status = TooMany, Name = Invalid, IdVar = Nop
     105
     106        * Name = Valid, Id = Valid, Free = No
     107
     108    Status = InvAddr, Name = Invalid, IdVar = Nop
     109
     110        * Name = Valid, Id = Null, Free = { Yes, No }
     111
     112    Status = InvName, Name = Invalid, IdVar = Nop
     113
     114        * Name = Invalid, Id = { Valid, Null }, Free = { Yes, No }
     115
     116The view above yields for each variation of post-condition states the list of
     117associated pre-condition state variations.
     118
     119Generate Files from Specification Items
     120---------------------------------------
     121
     122The ``./spec2modules.py`` script generates program and documentation files in
     123:file:`modules/rtems` and :file:`modules/rtems-docs` using the specification
     124items as input.  The script should be invoked whenever a specification item was
     125modified.  After running the script, go into the subdirectories and create
     126corresponding patch sets.  For these patch sets, the normal patch review
     127process applies, see *Support and Contributing* chapter of the *RTEMS User
     128Manual*.
    35129
    36130Application Configuration Options
     
    10311125          parameter in past calls to ${../if/directive:/name} shall not be
    10321126          accessed by the ${../if/directive:/name} call.
     1127
     1128Verify the Specification Items
     1129------------------------------
     1130
     1131The ``./specverify.py`` script verifies that the specification items have the
     1132format documented in :ref:`ReqEngSpecificationItems`.  To some extent the
     1133values of attributes are verified as well.
Note: See TracChangeset for help on using the changeset viewer.