diff options
Diffstat (limited to 'eng/req')
| -rw-r--r-- | eng/req/howto.rst | 1213 | ||||
| -rw-r--r-- | eng/req/index.rst | 92 | ||||
| -rw-r--r-- | eng/req/items.rst | 6195 | ||||
| -rw-r--r-- | eng/req/management.rst | 76 | ||||
| -rw-r--r-- | eng/req/req-for-req.rst | 406 | ||||
| -rw-r--r-- | eng/req/tooling.rst | 160 | ||||
| -rw-r--r-- | eng/req/traceability.rst | 77 |
7 files changed, 8219 insertions, 0 deletions
diff --git a/eng/req/howto.rst b/eng/req/howto.rst new file mode 100644 index 0000000..325c443 --- /dev/null +++ b/eng/req/howto.rst @@ -0,0 +1,1213 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020, 2023 embedded brains GmbH & Co. KG + +How-To +====== + +Getting Started +--------------- + +The RTEMS specification items and qualification tools are work in progress. The +first step to work with the RTEMS specification and the corresponding tools is a +clone of the following repository: + +.. code-block:: none + + git clone git://git.rtems.org/rtems-central.git + git submodule init + git submodule update + +The tools need a virtual Python 3 environment. To set it up use: + +.. code-block:: none + + cd rtems-central + make env + +Each time you want to use one of the tools, you have to activate the +environment in your shell: + +.. code-block:: none + + cd rtems-central + . env/bin/activate + +View the Specification Graph +---------------------------- + +The specification items form directed graphs through :ref:`SpecTypeLink` +attributes. Each link has a role. For a particular view only specific roles +may be of interest. For example, the requirements specification of RTEMS +starts with the ``spec:/req/root`` specification item. It should form a tree +(connected graph without cycles). A text representation of the tree can be +printed with the ``./specview.py`` script: + +.. code-block:: none + + cd rtems-central + . env/bin/activate + ./specview.py + +This gives the following example output (shortened): + +.. code-block:: none + + /req/root (type=requirement/non-functional/design) + /bsp/if/group (type=requirement/non-functional/design-group, role=requirement-refinement) + /bsp/if/acfg-idle-task-body (type=interface/unspecified-define, role=interface-ingroup) + /bsp/sparc/leon3/req/idle-task-body (type=requirement/functional/function, role=interface-function) + /bsp/sparc/leon3/req/idle-task-power-down (type=requirement/functional/function, role=requirement-refinement) + /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation) + /bsp/sparc/leon3/req/idle-task-power-down-errata (type=requirement/functional/function, role=requirement-refinement) + /bsp/sparc/leon3/val/errata-gr712rc-08 (type=validation, role=validation) + +The actual specification graph depends on build configuration options which +enable or disable specification items. The ``--enabled`` command line option +may be used to specify the build configuration options, for example +``--enabled=sparc,bsps/sparc/leon3,sparc/gr740,RTEMS_SMP,RTEMS_QUAL``. + +The ``./specview.py`` script can display other views of the specification +through the ``--filter`` command line option. Transition maps of +:ref:`SpecTypeActionRequirementItemType` items can be printed using the +``--filter=action-table`` or ``--filter=action-list`` filters. For example, +``./specview.py --filter=action-table /rtems/timer/req/create`` prints +something like this: + +.. code-block:: none + + .. table:: + :class: longtable + + ===== ========== ======= ===== ==== ======= ======= ===== + Entry Descriptor Name Id Free Status Name IdVar + ===== ========== ======= ===== ==== ======= ======= ===== + 0 0 Valid Valid Yes Ok Valid Set + 1 0 Valid Valid No TooMany Invalid Nop + 2 0 Valid Null Yes InvAddr Invalid Nop + 3 0 Valid Null No InvAddr Invalid Nop + 4 0 Invalid Valid Yes InvName Invalid Nop + 5 0 Invalid Valid No InvName Invalid Nop + 6 0 Invalid Null Yes InvName Invalid Nop + 7 0 Invalid Null No InvName Invalid Nop + ===== ========== ======= ===== ==== ======= ======= ===== + +For example, ``./specview.py --filter=action-list /rtems/timer/req/create`` +prints something like this: + +.. code-block:: none + + Status = Ok, Name = Valid, IdVar = Set + + * Name = Valid, Id = Valid, Free = Yes + + Status = TooMany, Name = Invalid, IdVar = Nop + + * Name = Valid, Id = Valid, Free = No + + Status = InvAddr, Name = Invalid, IdVar = Nop + + * Name = Valid, Id = Null, Free = { Yes, No } + + Status = InvName, Name = Invalid, IdVar = Nop + + * Name = Invalid, Id = { Valid, Null }, Free = { Yes, No } + +The view above yields for each variation of post-condition states the list of +associated pre-condition state variations. + +Generate Files from Specification Items +--------------------------------------- + +The ``./spec2modules.py`` script generates program and documentation files in +:file:`modules/rtems` and :file:`modules/rtems-docs` using the specification +items as input. The script should be invoked whenever a specification item was +modified. After running the script, go into the subdirectories and create +corresponding patch sets. For these patch sets, the normal patch review +process applies, see *Support and Contributing* chapter of the *RTEMS User +Manual*. + +Application Configuration Options +--------------------------------- + +The application configuration options and groups are maintained by +specification items in the directory :file:`spec/acfg/if`. Application +configuration options are grouped by +:ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be +stored in files using the :file:`spec/acfg/if/group-*.yml` pattern. Each +application configuration option shall link to exactly one group item with the +:ref:`SpecTypeInterfaceGroupMembershipLinkRole`. There are four +application option item types available which cover all existing options: + +* The *feature enable options* let the application enable a feature option. If + the option is not defined, then the feature is simply not available or + active. There should be no feature-specific code linked to the application + if the option is not defined. Examples are options which enable a device + driver like ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``. These options are + specified by + :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` items. + +* The *feature options* let the application enable a specific feature option. + If the option is not defined, then a default feature option is used. + Regardless whether the option is defined or not defined, feature-specific + code may be linked to the application. Examples are options which disable a + feature if the option is defined such as + ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` and options which provide a stub + implementation of a feature by default and a full implementation if the + option is defined such as ``CONFIGURE_IMFS_ENABLE_MKFIFO``. These options + are specified by :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` + items. + +* The *integer value options* let the application define a specific value for a + system parameter. If the option is not defined, then a default value is used + for the system parameter. Examples are options which define the maximum + count of objects available for application use such as + ``CONFIGURE_MAXIMUM_TASKS``. These options are specified by + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. + +* The *initializer options* let the application define a specific initializer + for a system parameter. If the option is not defined, then a default setting + is used for the system parameter. An example option of this type is + ``CONFIGURE_INITIAL_EXTENSIONS``. These options are specified by + :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. + +Sphinx documentation sources and header files with Doxygen markup are generated +from the specification items. The descriptions in the items shall use a +restricted Sphinx formatting. Emphasis via one asterisk ("*"), strong emphasis +via two asterisk ("**"), code samples via blockquotes ("``"), code blocks (".. +code-block:: c") and lists are allowed. References to interface items are also +allowed, for example "${appl-needs-clock-driver:/name}" and +"${/rtems/task/if/create:/name}". References to other parts of the +documentation are possible, however, they have to be provided by +:file:`spec:/doc/if/*` items. + +Modify an Existing Group +^^^^^^^^^^^^^^^^^^^^^^^^ + +Search for the group by its section header and edit the specification item +file. For example: + +.. code-block:: none + + $ grep -rl "name: General System Configuration" spec/acfg/if + spec/acfg/if/group-general.yml + $ vi spec/acfg/if/group-general.yml + +Modify an Existing Option +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Search for the option by its C preprocessor define name and edit the +specification item file. For example: + +.. code-block:: none + + $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/acfg/if + spec/acfg/if/appl-needs-clock-driver.yml + $ vi spec/acfg/if/appl-needs-clock-driver.yml + +Add a New Group +^^^^^^^^^^^^^^^ + +Let ``new`` be the UID name part of the new group. Create the file +:file:`spec/acfg/if/group-new.yml` and provide all attributes for an +:ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example: + +.. code-block:: none + + $ vi spec/acfg/if/group-new.yml + +Add a New Option +^^^^^^^^^^^^^^^^ + +Let ``my-new-option`` be the UID name of the option. Create the file +:file:`if/acfg/my-new-option.yml` and provide all attributes for an appropriate +refinement of :ref:`SpecTypeApplicationConfigurationOptionItemType`. For +example: + +.. code-block:: none + + $ vi spec/acfg/if/my-new-option.yml + +Generate Content after Changes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once you are done with the modifications of an existing item or the creation of +a new item, the changes need to be propagated to generated source files. This +is done by the :file:`spec2modules.py` script. Before you call this script, +make sure the Git submodules are up-to-date. + +.. code-block:: none + + $ ./spec2modules.py + +The script modifies or creates source files in :file:`modules/rtems` and +:file:`modules/rtems-docs`. Create patch sets for these changes just as if +these were work done by a human and follow the normal patch review process +described in the *RTEMS User Manual*. When the changes are integrated, update +the Git submodules and check in the changed items. + +Glossary Specification +---------------------- + +The glossary of terms for the RTEMS Project is defined by +:ref:`SpecTypeGlossaryTermItemType` items in the :file:`spec/glossary` +directory. For a new glossary term add a glossary item to this directory. As +the file name use the term in lower case with all white space and special +characters removed or replaced by alphanumeric characters, for example +:file:`spec/glossary/magicpower.yml` for the term `magic power`. + +Use ``${uid:/attribute}`` substitutions to reference other parts of the +specification. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + glossary-type: term + links: + - role: glossary-member + uid: ../glossary-general + term: magic power + text: | + Magic power enables a caller to create magic objects using a + ${magicwand:/term}. + type: glossary + +Define acronyms with the phrase `This term is an acronym for *.` in the +``text`` attribute: + +.. code-block:: yaml + + ... + term: MP + ... + text: | + This term is an acronym for Magic Power. + ... + +Once you are done with the glossary items, run the script +:file:`spec2modules.py` to generate the derived documentation content. Send +patches for the generated documentation and the specification to the +:r:list:`devel` and follow the normal patch review process. + +Interface Specification +----------------------- + +.. _ReqEngAddAPIHeaderFile: + +Specify an API Header File +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The RTEMS :term:`API` header files are specified under ``spec:/rtems/*/if``. +Create a subdirectory with a corresponding name for the API, for example in +:file:`spec/rtems/foo/if` for the `foo` API. In this new subdirectory place an +:ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml` +(:file:`spec/rtems/foo/if/header.yml`) and populate it with the required +attributes. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + interface-type: header-file + links: + - role: interface-placement + uid: /if/domain + - role: interface-ingroup + uid: ../req/group + path: rtems/rtems/foo.h + prefix: cpukit/include + type: interface + +Specify an API Element +^^^^^^^^^^^^^^^^^^^^^^ + +Figure out the corresponding header file item. If it does not exist, see +:ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an +:ref:`SpecTypeInterfaceItemType` item into the directory of the header file +item, for example :file:`spec/rtems/foo/if/bar.yml` for the :c:func:`bar` +function. Add the required attributes for the new interface item. Do not hard +code interface names which are used to define the new interface. Use +``${uid-of-interface-item:/name}`` instead. If the referenced interface is +specified in the same directory, then use a relative UID. Using interface +references creates implicit dependencies and helps the header file generator to +resolve the interface dependencies and header file includes for you. Use +:ref:`SpecTypeInterfaceUnspecifiedItemType` items for interface dependencies to +other domains such as the C language, the compiler, the implementation, or +user-provided defines. To avoid cyclic dependencies between types you may use +an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + brief: Tries to create a magic object and returns it. + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + definition: + default: + body: null + params: + - ${magic-wand:/name} ${.:/params[0]/name} + return: ${magic-type:/name} * + variants: [] + description: | + The magic object is created out of nothing with the help of a magic wand. + enabled-by: true + interface-type: function + links: + - role: interface-placement + uid: header + - role: interface-ingroup + uid: /groups/api/classic/foo + name: bar + notes: null + params: + - description: is the magic wand. + dir: null + name: magic_wand + return: + return: Otherwise, the magic object is returned. + return-values: + - description: The caller did not have enough magic power. + value: ${/c/if/null} + type: interface + +Requirements Depending on Build Configuration Options +----------------------------------------------------- + +Use the ``enabled-by`` attribute of items or parts of an item to make it +dependent on build configuration options such as :c:data:`RTEMS_SMP` or +architecture-specific options such as +:c:data:`CPU_ENABLE_ROBUST_THREAD_DISPATCH`, see +:ref:`SpecTypeEnabledByExpression`. With this attribute the specification can +be customized at the level of an item or parts of an item. If the +``enabled-by`` attribute evaluates to false for a particular configuration, +then the item or the associated part is disabled in the specification. The +``enabled-by`` attribute acts as a formalized *where* clause, see +:ref:`recommended requirements syntax <ReqEngSyntax>`. + +Please have a look at the following example which specifies the transition map +of :c:func:`rtems_signal_catch`: + +.. code-block:: yaml + + transition-map: + - enabled-by: true + post-conditions: + Status: Ok + ASRInfo: + - if: + pre-conditions: + Handler: Valid + then: New + - else: Inactive + pre-conditions: + Pending: all + Handler: all + Preempt: all + Timeslice: all + ASR: all + IntLvl: all + - enabled-by: CPU_ENABLE_ROBUST_THREAD_DISPATCH + post-conditions: + Status: NotImplIntLvl + ASRInfo: NopIntLvl + pre-conditions: + Pending: all + Handler: + - Valid + Preempt: all + Timeslice: all + ASR: all + IntLvl: + - Positive + - enabled-by: RTEMS_SMP + post-conditions: + Status: NotImplNoPreempt + ASRInfo: NopNoPreempt + pre-conditions: + Pending: all + Handler: + - Valid + Preempt: + - 'No' + Timeslice: all + ASR: all + IntLvl: all + +Requirements Depending on Application Configuration Options +----------------------------------------------------------- + +Requirements which depend on application configuration options such as +:c:data:`CONFIGURE_MAXIMUM_PROCESSORS` should be written in the following +:ref:`syntax <ReqEngSyntax>`: + + **Where** <feature is included>, the <system name> shall <system response>. + +Use these clauses with care. Make sure all feature combinations are covered. +Using a truth table may help. If a requirement depends on multiple features, +use: + + **Where** <feature 0>, **where** <feature 1>, **where** <feature ...>, the + <system name> shall <system response>. + +For application configuration options, use the clauses like this: + +:c:data:`CONFIGURE_MAXIMUM_PROCESSORS` equal to one + + **Where** the system was configured with a processor maximum of exactly + one, ... + +:c:data:`CONFIGURE_MAXIMUM_PROCESSORS` greater than one + + **Where** the system was configured with a processor maximum greater than + one, ... + +Please have a look at the following example used to specify +:c:func:`rtems_signal_catch`. The example is a post-condition state +specification of an action requirement, so there is an implicit set of +pre-conditions and the trigger: + + **While** <pre-condition(s)>, **when** rtems_signal_catch() is called, ... + +The *where* clauses should be mentally placed before the *while* clauses. + +.. code-block:: yaml + + post-conditions: + - name: ASRInfo + states: + - name: NopNoPreempt + test-code: | + if ( rtems_configuration_get_maximum_processors() > 1 ) { + CheckNoASRChange( ctx ); + } else { + CheckNewASRSettings( ctx ); + } + text: | + Where the scheduler does not support the no-preempt mode, the ASR + information of the caller of ${../if/catch:/name} shall not be + changed by the ${../if/catch:/name} call. + + Where the scheduler does support the no-preempt mode, the ASR + processing for the caller of ${../if/catch:/name} shall be done using + the handler specified by ${../if/catch:/params[0]/name} in the mode + specified by ${../if/catch:/params[1]/name}. + +Action Requirements +------------------- + +:ref:`SpecTypeActionRequirementItemType` items may be used to specify and +validate directive calls. They are a generator for event-driven requirements. +Event-driven requirements should be written in the following :ref:`syntax +<ReqEngSyntax>`: + + **While** <pre-condition 0>, **while** <pre-condition 1>, ..., **while** + <pre-condition *n*>, **when** <trigger>, the <system name> shall <system + response>. + +The list of *while* <pre-condition *i*> clauses for *i* from 1 to *n* in the +EARS notation is generated by *n* pre-condition states in the action +requirement item, see the ``pre-condition`` attribute in the +:ref:`SpecTypeActionRequirementItemType`. + +The <trigger> in the EARS notation is defined for an action requirement item by +the link to an :ref:`SpecTypeInterfaceFunctionItemType` or an +:ref:`SpecTypeInterfaceMacroItemType` item using the +:ref:`SpecTypeInterfaceFunctionLinkRole`. The code provided by the +``test-action`` attribute defines the action code which should invoke the +trigger directive in a particular set of pre-condition states. + +Each post-condition state of the action requirement item generates a <system +name> shall <system response> clause in the EARS notation, see the +``post-condition`` attribute in the :ref:`SpecTypeActionRequirementItemType`. + +Each entry in the transition map is an event-driven requirement composed of the +pre-condition states, the trigger defined by the link to a directive, and the +post-condition states. The transition map is defined by a list of +:ref:`SpecTypeActionRequirementTransition` descriptors. + +Use ``CamelCase`` for the pre-condition names, post-condition names, and state +names in action requirement items. The more conditions a directive has, the +shorter should be the names. The transition map may be documented as a table +and more conditions need more table columns. Use item attribute references in +the ``text`` attributes. This allows context-sensitive substitutions. + +Example +^^^^^^^ + +Lets have a look at an example of an action requirement item. We would like to +specify and validate the behaviour of the + +.. code-block:: c + + rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); + +directive which is particularly simple. For a more complex example see the +specification of :c:func:`rtems_signal_catch` or :c:func:`rtems_signal_send` in +``spec:/rtems/signal/req/catch`` or ``spec:/rtems/signal/send`` respectively. + +The event triggers are calls to :c:func:`rtems_timer_create`. Firstly, we need +the list of pre-conditions relevant to this directive. Good candidates are the +directive parameters, this gives us the ``Name`` and ``Id`` conditions. A +system condition is if an inactive timer object is available so that we can +create a timer, this gives us the ``Free`` condition. Secondly, we need the +list of post-conditions relevant to this directive. They are the return status +of the directive, ``Status``, the validity of a unique object name, ``Name``, +and the value of an object identifier variable, ``IdVar``. Each condition has +a set of states, see the YAML data below for the details. The specified +conditions and states yield the following transition map: + +.. table:: + :class: longtable + + ===== ========== ======= ===== ==== ======= ======= ===== + Entry Descriptor Name Id Free Status Name IdVar + ===== ========== ======= ===== ==== ======= ======= ===== + 0 0 Valid Valid Yes Ok Valid Set + 1 0 Valid Valid No TooMany Invalid Nop + 2 0 Valid Null Yes InvAddr Invalid Nop + 3 0 Valid Null No InvAddr Invalid Nop + 4 0 Invalid Valid Yes InvName Invalid Nop + 5 0 Invalid Valid No InvName Invalid Nop + 6 0 Invalid Null Yes InvName Invalid Nop + 7 0 Invalid Null No InvName Invalid Nop + ===== ========== ======= ===== ==== ======= ======= ===== + +Not all transition maps are that small, the transition map of +:c:func:`rtems_task_mode` has more than 8000 entries. We can construct +requirements from the clauses of the entries. For example, the three +requirements of entry 0 (Name=Valid, Id=Valid, and Free=Yes results in +Status=Ok, Name=Valid, and IdVar=Set) are: + + While the ``name`` parameter is valid, while the ``id`` parameter + references an object of type rtems_id, while the system has at least one + inactive timer object available, when rtems_timer_create() is called, the + return status of rtems_timer_create() shall be RTEMS_SUCCESSFUL. + + While the ``name`` parameter is valid, while the ``id`` parameter + references an object of type rtems_id, while the system has at least one + inactive timer object available, when rtems_timer_create() is called, the + unique object name shall identify the timer created by the + rtems_timer_create() call. + + While the ``name`` parameter is valid, while the ``id`` parameter + references an object of type rtems_id, while the system has at least one + inactive timer object available, when rtems_timer_create() is called, the + value of the object referenced by the ``id`` parameter shall be set to the + object identifier of the created timer after the return of the + rtems_timer_create() call. + +Now we will have a look at the specification item line by line. The top-level +attributes are normally in alphabetical order in an item file. For this +presentation we use a structured order. + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2021 embedded brains GmbH & Co. KG + enabled-by: true + functional-type: action + rationale: null + references: [] + requirement-type: functional + +The specification items need a bit of boilerplate to tell you what they are, +who wrote them, and what their license is. + +.. code-block:: yaml + + text: ${.:text-template} + +Each requirement item needs a ``text`` attribute. For the action requirements, +we do not have a single requirement. There is just a template indicator and no +plain text. Several event-driven requirements are defined by the +pre-conditions, the trigger, and the post-conditions. + +.. code-block:: yaml + + pre-conditions: + - name: Name + states: + - name: Valid + test-code: | + ctx->name = NAME; + text: | + While the ${../if/create:/params[0]/name} parameter is valid. + - name: Invalid + test-code: | + ctx->name = 0; + text: | + While the ${../if/create:/params[0]/name} parameter is invalid. + test-epilogue: null + test-prologue: null + - name: Id + states: + - name: Valid + test-code: | + ctx->id = &ctx->id_value; + text: | + While the ${../if/create:/params[1]/name} parameter references an object + of type ${../../type/if/id:/name}. + - name: 'Null' + test-code: | + ctx->id = NULL; + text: | + While the ${../if/create:/params[1]/name} parameter is + ${/c/if/null:/name}. + test-epilogue: null + test-prologue: null + - name: Free + states: + - name: 'Yes' + test-code: | + /* Ensured by the test suite configuration */ + text: | + While the system has at least one inactive timer object available. + - name: 'No' + test-code: | + ctx->seized_objects = T_seize_objects( Create, NULL ); + text: | + While the system has no inactive timer object available. + test-epilogue: null + test-prologue: null + +This list defines the pre-conditions. Each pre-condition has a list of states +and corresponding validation test code. + +.. code-block:: yaml + + links: + - role: interface-function + uid: ../if/create + test-action: | + ctx->status = rtems_timer_create( ctx->name, ctx->id ); + +The link to the :c:func:`rtems_timer_create` interface specification item with +the ``interface-function`` link role defines the trigger. The ``test-action`` +defines the how the triggering directive is invoked for the validation test +depending on the pre-condition states. The code is not always as simple as in +this example. The validation test is defined in this item along with the +specification. + +.. code-block:: yaml + + post-conditions: + - name: Status + states: + - name: Ok + test-code: | + T_rsc_success( ctx->status ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/successful:/name}. + - name: InvName + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_NAME ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/invalid-name:/name}. + - name: InvAddr + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_ADDRESS ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/invalid-address:/name}. + - name: TooMany + test-code: | + T_rsc( ctx->status, RTEMS_TOO_MANY ); + text: | + The return status of ${../if/create:/name} shall be + ${../../status/if/too-many:/name}. + test-epilogue: null + test-prologue: null + - name: Name + states: + - name: Valid + test-code: | + id = 0; + sc = rtems_timer_ident( NAME, &id ); + T_rsc_success( sc ); + T_eq_u32( id, ctx->id_value ); + text: | + The unique object name shall identify the timer created by the + ${../if/create:/name} call. + - name: Invalid + test-code: | + sc = rtems_timer_ident( NAME, &id ); + T_rsc( sc, RTEMS_INVALID_NAME ); + text: | + The unique object name shall not identify a timer. + test-epilogue: null + test-prologue: | + rtems_status_code sc; + rtems_id id; + - name: IdVar + states: + - name: Set + test-code: | + T_eq_ptr( ctx->id, &ctx->id_value ); + T_ne_u32( ctx->id_value, INVALID_ID ); + text: | + The value of the object referenced by the ${../if/create:/params[1]/name} + parameter shall be set to the object identifier of the created timer + after the return of the ${../if/create:/name} call. + - name: Nop + test-code: | + T_eq_u32( ctx->id_value, INVALID_ID ); + text: | + Objects referenced by the ${../if/create:/params[1]/name} parameter in + past calls to ${../if/create:/name} shall not be accessed by the + ${../if/create:/name} call. + test-epilogue: null + test-prologue: null + +This list defines the post-conditions. Each post-condition has a list of +states and corresponding validation test code. + +.. code-block:: yaml + + skip-reasons: {} + transition-map: + - enabled-by: true + post-conditions: + Status: + - if: + pre-conditions: + Name: Invalid + then: InvName + - if: + pre-conditions: + Id: 'Null' + then: InvAddr + - if: + pre-conditions: + Free: 'No' + then: TooMany + - else: Ok + Name: + - if: + post-conditions: + Status: Ok + then: Valid + - else: Invalid + IdVar: + - if: + post-conditions: + Status: Ok + then: Set + - else: Nop + pre-conditions: + Name: all + Id: all + Free: all + type: requirement + +This list of transition descriptors defines the transition map. For the +post-conditions, you can use expressions to ease the specification, see +:ref:`SpecTypeActionRequirementTransitionPostConditionState`. The +``skip-reasons`` can be used to skip entire entries in the transition map, see +:ref:`SpecTypeActionRequirementSkipReasons`. + +.. code-block:: yaml + + test-brief: null + test-description: null + +The item contains the validation test code. The validation test in general can +be described by these two attributes. + +.. code-block:: yaml + + test-target: testsuites/validation/tc-timer-create.c + +This is the target file for the generated validation test code. Make sure this +file is included in the build specification, otherwise the test code generation +will fail. + +.. code-block:: yaml + + test-includes: + - rtems.h + - string.h + test-local-includes: [] + +You can specify a list of includes for the validation test. + +.. code-block:: yaml + + test-header: null + +A test header may be used to create a parameterized validation test, see +:ref:`SpecTypeTestHeader`. This is an advanced topic, see the specification of +:c:func:`rtems_task_ident` for an example. + +.. code-block:: yaml + + test-context-support: null + test-context: + - brief: | + This member is used by the T_seize_objects() and T_surrender_objects() + support functions. + description: null + member: | + void *seized_objects + - brief: | + This member may contain the object identifier returned by + rtems_timer_create(). + description: null + member: | + rtems_id id_value + - brief: | + This member specifies the ${../if/create:/params[0]/name} parameter for the + action. + description: null + member: | + rtems_name name + - brief: | + This member specifies the ${../if/create:/params[1]/name} parameter for the + action. + description: null + member: | + rtems_id *id + - brief: | + This member contains the return status of the action. + description: null + member: | + rtems_status_code status + +You can specify a list of validation test context members which can be used to +maintain the state of the validation test. The context is available through an +implicit ``ctx`` variable in all code blocks except the support blocks. The +context support code can be used to define test-specific types used by context +members. Do not use global variables. + +.. code-block:: yaml + + test-support: | + #define NAME rtems_build_name( 'T', 'E', 'S', 'T' ) + + #define INVALID_ID 0xffffffff + + static rtems_status_code Create( void *arg, uint32_t *id ) + { + return rtems_timer_create( rtems_build_name( 'S', 'I', 'Z', 'E' ), id ); + } + +The support code block can be used to provide functions, data structures, and +constants for the validation test. + +.. code-block:: yaml + + test-prepare: null + test-cleanup: | + if ( ctx->id_value != INVALID_ID ) { + rtems_status_code sc; + + sc = rtems_timer_delete( ctx->id_value ); + T_rsc_success( sc ); + + ctx->id_value = INVALID_ID; + } + + T_surrender_objects( &ctx->seized_objects, rtems_timer_delete ); + +The validation test basically executes a couple of nested for loops to iterate +over each pre-condition and each state of the pre-conditions. These two +optional code blocks can be used to prepare the pre-condition state +preparations and clean up after the post-condition checks in each loop +iteration. + +.. code-block:: yaml + + test-setup: + brief: null + code: | + memset( ctx, 0, sizeof( *ctx ) ); + ctx->id_value = INVALID_ID; + description: null + test-stop: null + test-teardown: null + +These optional code blocks correspond to test fixture methods, see +:ref:`RTEMSTestFrameworkFixture`. + +Pre-Condition Templates +^^^^^^^^^^^^^^^^^^^^^^^ + +Specify all directive parameters as separate pre-conditions. Use the following +syntax for directive object identifier parameters: + +.. code-block:: yaml + + - name: Id + states: + - name: NoObj + test-code: | + ctx->id = 0xffffffff; + text: | + While the ${../if/directive:/params[0]/name} parameter is not + associated with a thing. + - name: ClassA + test-code: | + ctx->id = ctx->class_a_id; + text: | + While the ${../if/directive:/params[0]/name} parameter is associated + with a class A thing. + - name: ClassB + test-code: | + ctx->id = ctx->class_b_id; + text: | + While the ${../if/directive:/params[0]/name} parameter is associated + with a class B thing. + test-epilogue: null + test-prologue: null + +Do not add specifications for invalid pointers. In general, there are a lot of +invalid pointers and the use of an invalid pointer is in almost all cases +undefined behaviour in RTEMS. There may be specifications for special cases +which deal with some very specific invalid pointers such as the :c:data:`NULL` +pointer or pointers which do not satisfy a range or boundary condition. Use +the following syntax for directive pointer parameters: + +.. code-block:: yaml + + - name: Id + states: + - name: Valid + test-code: | + ctx->id = &ctx->id_value; + text: | + While the ${../if/directive:/params[3]/name} parameter references an + object of type ${../../type/if/id:/name}. + - name: 'Null' + test-code: | + ctx->id = NULL; + text: | + While the ${../if/directive:/params[3]/name} parameter is + ${/c/if/null:/name}. + test-epilogue: null + test-prologue: null + +Use the following syntax for other directive parameters: + +.. code-block:: yaml + + - name: Name + states: + - name: Valid + test-code: | + ctx->name = NAME; + text: | + While the ${../if/directive:/params[0]/name} parameter is valid. + - name: Invalid + test-code: | + ctx->name = 0; + text: | + While the ${../if/directive:/params[0]/name} parameter is invalid. + test-epilogue: null + test-prologue: null + +Post-Condition Templates +^^^^^^^^^^^^^^^^^^^^^^^^ + +Do not mix different things into one post-condition. If you write multiple +sentences to describe what happened, then think about splitting up the +post-condition. Keep the post-condition simple and focus on one testable +aspect which may be changed by a directive call. + +For directives returning an :c:type:`rtems_status_code` use the following +post-condition states. Specify only status codes which may be returned by the +directive. Use it as the first post-condition. The first state shall be +``Ok``. The other states shall be listed in the order in which they can occur. + +.. code-block:: yaml + + - name: Status + states: + - name: Ok + test-code: | + T_rsc_success( ctx->status ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/successful:/name}. + - name: IncStat + test-code: | + T_rsc( ctx->status, RTEMS_INCORRECT_STATE ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/incorrect-state:/name}. + - name: InvAddr + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_ADDRESS ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-address:/name}. + - name: InvName + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_NAME ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-name:/name}. + - name: InvNum + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_NUMBER ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-number:/name}. + - name: InvSize + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_SIZE ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-size:/name}. + - name: InvPrio + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_PRIORITY ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/invalid-priority:/name}. + - name: NotConf + test-code: | + T_rsc( ctx->status, RTEMS_NOT_CONFIGURED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/not-configured:/name}. + - name: NotDef + test-code: | + T_rsc( ctx->status, RTEMS_NOT_DEFINED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/not-defined:/name}. + - name: NotImpl + test-code: | + T_rsc( ctx->status, RTEMS_NOT_IMPLEMENTED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/not-implemented:/name}. + - name: TooMany + test-code: | + T_rsc( ctx->status, RTEMS_TOO_MANY ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/too-many:/name}. + - name: Unsat + test-code: | + T_rsc( ctx->status, RTEMS_UNSATISFIED ); + text: | + The return status of ${../if/directive:/name} shall be + ${../../status/if/unsatisfied:/name}. + test-epilogue: null + test-prologue: null + +For values which are returned by reference through directive parameters, use +the following post-condition states. + +.. code-block:: yaml + + - name: SomeParamVar + states: + - name: Set + test-code: | + /* Add code to check that the object value was set to X */ + text: | + The value of the object referenced by the + ${../if/directive:/params[0]/name} parameter shall be set to X after + the return of the ${../if/directive:/name} call. + - name: Nop + test-code: | + /* Add code to check that the object was not modified */ + text: | + Objects referenced by the ${../if/directive:/params[0]/name} + parameter in past calls to ${../if/directive:/name} shall not be + accessed by the ${../if/directive:/name} call. + +Validation Test Guidelines +-------------------------- + +The validation test cases, test runners, and test suites are generated by the +``./spec2modules.py`` script from specification items. For the placement and +naming of the generated sources use the following rules: + +* Place architecture-specific validation test sources and programs into the + ``testsuites/validation/cpu`` directory. + +* Place BSP-specific validation test sources and programs into the + ``testsuites/validation/bsps`` directory. + +* Place all other validation test sources and programs into the + ``testsuites/validation`` directory. + +* Place architecture-specific unit test sources and programs into the + ``testsuites/unit/cpu`` directory. + +* Place BSP-specific unit test sources and programs into the + ``testsuites/unit/bsps`` directory. + +* Place all other unit test sources and programs into the + ``testsuites/unit`` directory. + +* Use dashes (``-``) to separate parts of a file name. Use only dashes, the + digits ``0`` to ``9``, and the lower case characters ``a`` to ``z`` for file + names. In particular, do not use underscores (``_``). + +* The parts of a file name shall be separated by dashes and ordered from most + general (left) to more specific (right), for example ``tc-task-construct.c``. + +* The file names associated with tests shall be unique within the system since + the test framework prints out only the base file names. + +* Use the prefix ``tc-`` for test case files. + +* Use the prefix ``tr-`` for test runner files. + +* Use the prefix ``ts-`` for test suite files. + +* Use the prefix ``tx-`` for test extension files (test support code). + +* Tests for fatal errors shall have ``fatal`` as the most general file part, + for example ``ts-fatal-too-large-tls-size.c``. + +* Validation test suites shall have ``validation`` as the most general file + part, for example ``ts-validation-no-clock-0.c``. + +* Unit test suites shall have ``unit`` as the most general file part, for + example ``ts-unit-no-clock-0.c``. + +* Architecture-specific files shall have the architecture name as a file part, + for example ``ts-fatal-sparc-leon3-clock-initialization.c``. + +* BSP-specific files shall have the BSP family or variant name as a file part, + for example ``tc-sparc-gr712rc.c``. + +* Architecture-specific or BSP-specific tests shall use the ``enabled-by`` + attribute of the associated specification item to make the build item + conditional, for example: + + .. code-block:: yaml + + ... + build-type: objects + enabled-by: arm + type: build + ... + + .. code-block:: yaml + + ... + build-type: test-program + enabled-by: bsps/sparc/leon3 + type: build + ... + +Verify the Specification Items +------------------------------ + +The ``./specverify.py`` script verifies that the specification items have the +format documented in :ref:`ReqEngSpecificationItems`. To some extent the +values of attributes are verified as well. diff --git a/eng/req/index.rst b/eng/req/index.rst new file mode 100644 index 0000000..524835d --- /dev/null +++ b/eng/req/index.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +.. |E40| replace:: ECSS-E-ST-40C + +.. _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. + +.. toctree:: + + req-for-req + items + traceability + management + tooling + howto diff --git a/eng/req/items.rst b/eng/req/items.rst new file mode 100644 index 0000000..286e998 --- /dev/null +++ b/eng/req/items.rst @@ -0,0 +1,6195 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2023 embedded brains GmbH & Co. KG + +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _ReqEngSpecificationItems: + +Specification Items +=================== + +.. _ReqEngSpecificationItemHierarchy: + +Specification Item Hierarchy +---------------------------- + +The specification item types have the following hierarchy: + +* :ref:`SpecTypeRootItemType` + + * :ref:`SpecTypeBuildItemType` + + * :ref:`SpecTypeBuildAdaTestProgramItemType` + + * :ref:`SpecTypeBuildBSPItemType` + + * :ref:`SpecTypeBuildConfigurationFileItemType` + + * :ref:`SpecTypeBuildConfigurationHeaderItemType` + + * :ref:`SpecTypeBuildGroupItemType` + + * :ref:`SpecTypeBuildLibraryItemType` + + * :ref:`SpecTypeBuildObjectsItemType` + + * :ref:`SpecTypeBuildOptionItemType` + + * :ref:`SpecTypeBuildScriptItemType` + + * :ref:`SpecTypeBuildStartFileItemType` + + * :ref:`SpecTypeBuildTestProgramItemType` + + * :ref:`SpecTypeConstraintItemType` + + * :ref:`SpecTypeGlossaryItemType` + + * :ref:`SpecTypeGlossaryGroupItemType` + + * :ref:`SpecTypeGlossaryTermItemType` + + * :ref:`SpecTypeInterfaceItemType` + + * :ref:`SpecTypeApplicationConfigurationGroupItemType` + + * :ref:`SpecTypeApplicationConfigurationOptionItemType` + + * :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` + + * :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` + + * :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + + * :ref:`SpecTypeInterfaceCompoundItemType` + + * :ref:`SpecTypeInterfaceDefineItemType` + + * :ref:`SpecTypeInterfaceDomainItemType` + + * :ref:`SpecTypeInterfaceEnumItemType` + + * :ref:`SpecTypeInterfaceEnumeratorItemType` + + * :ref:`SpecTypeInterfaceForwardDeclarationItemType` + + * :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + + * :ref:`SpecTypeInterfaceGroupItemType` + + * :ref:`SpecTypeInterfaceHeaderFileItemType` + + * :ref:`SpecTypeInterfaceTypedefItemType` + + * :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + + * :ref:`SpecTypeInterfaceUnspecifiedItemType` + + * :ref:`SpecTypeInterfaceVariableItemType` + + * :ref:`SpecTypeRegisterBlockItemType` + + * :ref:`SpecTypeProxyItemTypes` + + * :ref:`SpecTypeRequirementItemType` + + * :ref:`SpecTypeFunctionalRequirementItemType` + + * :ref:`SpecTypeActionRequirementItemType` + + * :ref:`SpecTypeGenericFunctionalRequirementItemType` + + * :ref:`SpecTypeNonFunctionalRequirementItemType` + + * :ref:`SpecTypeDesignGroupRequirementItemType` + + * :ref:`SpecTypeDesignTargetItemType` + + * :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + + * :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + + * :ref:`SpecTypeRuntimePerformanceRequirementItemType` + + * :ref:`SpecTypeRequirementValidationItemType` + + * :ref:`SpecTypeRequirementValidationMethod` + + * :ref:`SpecTypeRuntimeMeasurementTestItemType` + + * :ref:`SpecTypeSpecificationItemType` + + * :ref:`SpecTypeTestCaseItemType` + + * :ref:`SpecTypeTestPlatformItemType` + + * :ref:`SpecTypeTestProcedureItemType` + + * :ref:`SpecTypeTestSuiteItemType` + +.. _ReqEngSpecificationItemTypes: + +Specification Item Types +------------------------ + +.. _SpecTypeRootItemType: + +Root Item Type +^^^^^^^^^^^^^^ + +The technical specification of RTEMS will contain for example requirements, +specializations of requirements, interface specifications, test suites, test +cases, and requirement validations. These things will be called *specification +items* or just *items* if it is clear from the context. + +The specification items are stored in files in :term:`YAML` format with a +defined set of key-value pairs called attributes. Each attribute key name +shall be a :ref:`SpecTypeName`. In particular, key names which begin with an +underscore (``_``) are reserved for internal use in tools. + +This is the root specification item type. All explicit attributes shall be +specified. The explicit attributes for this type are: + +SPDX-License-Identifier + The attribute value shall be a :ref:`SpecTypeSPDXLicenseIdentifier`. It + shall be the license of the item. + +copyrights + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeCopyright`. It shall be the list of copyright statements of + the item. + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It + shall define the conditions under which the item is enabled. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. + +type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the item + type. 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. The item type may be refined further with additional + type-specific subtypes. + +This type is refined by the following types: + +* :ref:`SpecTypeBuildItemType` + +* :ref:`SpecTypeConstraintItemType` + +* :ref:`SpecTypeGlossaryItemType` + +* :ref:`SpecTypeInterfaceItemType` + +* :ref:`SpecTypeProxyItemTypes` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRequirementValidationItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeSpecificationItemType` + +* :ref:`SpecTypeTestCaseItemType` + +* :ref:`SpecTypeTestPlatformItemType` + +* :ref:`SpecTypeTestProcedureItemType` + +* :ref:`SpecTypeTestSuiteItemType` + +.. _SpecTypeBuildItemType: + +Build Item Type +^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``build``. This set of attributes specifies a build +item. All explicit attributes shall be specified. The explicit attributes for +this type are: + +build-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the build + item type. + +This type is refined by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildConfigurationFileItemType` + +* :ref:`SpecTypeBuildConfigurationHeaderItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildAdaTestProgramItemType: + +Build Ada Test Program Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``ada-test-program``. This set of attributes +specifies an Ada test program executable to build. Test programs may use +additional objects provided by :ref:`SpecTypeBuildObjectsItemType` items. Test +programs have an implicit ``enabled-by`` attribute value which is controlled by +the option action :ref:`set-test-state <SpecTypeBuildOptionItemType>`. If the +test state is set to ``exclude``, then the test program is not built. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +ada-main + The attribute value shall be a string. It shall be the path to the Ada main + body file. + +ada-object-directory + The attribute value shall be a string. It shall be the path to the Ada + object directory (``-D`` option value for ``gnatmake``). + +adaflags + The attribute value shall be a list of strings. It shall be a list of + options for the Ada compiler. + +adaincludes + The attribute value shall be a list of strings. It shall be a list of Ada + include paths. + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +stlib + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkStaticLibraryDirective`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + ada-main: testsuites/ada/samples/hello/hello.adb + ada-object-directory: testsuites/ada/samples/hello + adaflags: [] + adaincludes: + - cpukit/include/adainclude + - testsuites/ada/support + build-type: ada-test-program + cflags: [] + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + cxxflags: [] + enabled-by: true + includes: [] + ldflags: [] + links: [] + source: + - testsuites/ada/samples/hello/init.c + stlib: [] + target: testsuites/ada/ada_hello.exe + type: build + use-after: [] + use-before: [] + +.. _SpecTypeBuildBSPItemType: + +Build BSP Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``bsp``. This set of attributes specifies a base BSP +variant to build. All explicit attributes shall be specified. The explicit +attributes for this type are: + +arch + The attribute value shall be a string. It shall be the target architecture + of the BSP. + +bsp + The attribute value shall be a string. It shall be the base BSP variant + name. + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +family + The attribute value shall be a string. It shall be the BSP family name. + The name shall be the last directory of the path to the BSP sources. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + arch: myarch + bsp: mybsp + build-type: bsp + cflags: [] + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + enabled-by: true + family: mybsp + includes: [] + install: + - destination: ${BSP_INCLUDEDIR} + source: + - bsps/myarch/mybsp/include/bsp.h + - bsps/myarch/mybsp/include/tm27.h + - destination: ${BSP_INCLUDEDIR}/bsp + source: + - bsps/myarch/mybsp/include/bsp/irq.h + - destination: ${BSP_LIBDIR} + source: + - bsps/myarch/mybsp/start/linkcmds + links: + - role: build-dependency + uid: ../../obj + - role: build-dependency + uid: ../../opto2 + - role: build-dependency + uid: abi + - role: build-dependency + uid: obj + - role: build-dependency + uid: ../start + - role: build-dependency + uid: ../../bspopts + source: + - bsps/myarch/mybsp/start/bspstart.c + type: build + +.. _SpecTypeBuildConfigurationFileItemType: + +Build Configuration File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``config-file``. This set of attributes specifies a +configuration file placed in the build tree. The configuration file is +generated during the configure command execution and is placed in the build +tree. All explicit attributes shall be specified. The explicit attributes for +this type are: + +content + The attribute value shall be a string. It shall be the content of the + configuration file. A ${VARIABLE} substitution is performed during the + configure command execution using the variables of the configuration set. + Use $$ for a plain $ character. To have all variables from sibling items + available for substitution it is recommended to link them in the proper + order. + +install-path + The attribute value shall be a :ref:`SpecTypeBuildInstallPath`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + build-type: config-file + content: | + # ... + Name: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME} + # ... + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + install-path: ${PREFIX}/lib/pkgconfig + links: [] + target: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME}.pc + type: build + +.. _SpecTypeBuildConfigurationHeaderItemType: + +Build Configuration Header Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``config-header``. This set of attributes specifies +configuration header file. The configuration header file is generated during +configure command execution and is placed in the build tree. All collected +configuration defines are written to the configuration header file during the +configure command execution. To have all configuration defines from sibling +items available it is recommended to link them in the proper order. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +guard + The attribute value shall be a string. It shall be the header guard define. + +include-headers + The attribute value shall be a list of strings. It shall be a list of + header files to include via ``#include <...>``. + +install-path + The attribute value shall be a :ref:`SpecTypeBuildInstallPath`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +.. _SpecTypeBuildGroupItemType: + +Build Group Item Type +^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``group``. This set of attributes provides a means to +aggregate other build items and modify the build item context which is used by +referenced build items. The ``includes``, ``ldflags``, ``objects``, and +``use`` variables of the build item context are updated by the corresponding +attributes of the build group. All explicit attributes shall be specified. The +explicit attributes for this type are: + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +ldflags + The attribute value shall be a list of strings. It shall be a list of + options for the linker. They are used to link executables referenced by + this item. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + build-type: group + cflags: [] + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + cxxflags: [] + enabled-by: + - BUILD_TESTS + - BUILD_SAMPLES + includes: + - testsuites/support/include + install: [] + ldflags: + - -Wl,--wrap=printf + - -Wl,--wrap=puts + links: + - role: build-dependency + uid: ticker + type: build + use-after: [] + use-before: + - rtemstest + +.. _SpecTypeBuildLibraryItemType: + +Build Library Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``library``. This set of attributes specifies a +static library. Library items may use additional objects provided by +:ref:`SpecTypeBuildObjectsItemType` items through the build dependency links of +the item. All explicit attributes shall be specified. The explicit attributes +for this type are: + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +install-path + The attribute value shall be a :ref:`SpecTypeBuildInstallPath`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. It shall be the + name of the static library, e.g. ``z`` for ``libz.a``. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + build-type: library + cflags: + - -Wno-pointer-sign + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + cxxflags: [] + enabled-by: true + includes: + - cpukit/libfs/src/jffs2/include + install: + - destination: ${BSP_INCLUDEDIR}/rtems + source: + - cpukit/include/rtems/jffs2.h + install-path: ${BSP_LIBDIR} + links: [] + source: + - cpukit/libfs/src/jffs2/src/build.c + target: jffs2 + type: build + +.. _SpecTypeBuildObjectsItemType: + +Build Objects Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``objects``. This set of attributes specifies a set +of object files used to build static libraries or test programs. Objects Items +must not be included on multiple paths through the build dependency graph with +identical build options. Violating this can cause race conditions in the build +system due to duplicate installs and multiple instances of build tasks. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildInstallDirective`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + build-type: objects + cflags: [] + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + cxxflags: [] + enabled-by: true + includes: [] + install: + - destination: ${BSP_INCLUDEDIR}/bsp + source: + - bsps/include/bsp/bootcard.h + - bsps/include/bsp/default-initial-extension.h + - bsps/include/bsp/fatal.h + links: [] + source: + - bsps/shared/start/bootcard.c + - bsps/shared/rtems-version.c + type: build + +.. _SpecTypeBuildOptionItemType: + +Build Option Item Type +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``option``. This set of attributes specifies a build +option. The following explicit attributes are mandatory: + +* ``actions`` + +* ``default`` + +* ``description`` + +The explicit attributes for this type are: + +actions + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildOptionAction`. Each action operates on the *action + value* handed over by a previous action and action-specific attribute + values. The actions pass the processed action value to the next action in + the list. The first action starts with an action value of ``None``. The + actions are carried out during the configure command execution. + +default + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildOptionDefaultValue`. It shall be the list of default + values of the option. When a default value is needed, the first value on + the list which is enabled according to the enabled set is choosen. If no + value is enabled, then the default value is ``null``. + +description + The attribute value shall be an optional string. It shall be the + description of the option. + +format + The attribute value shall be an optional string. It shall be a `Python + format string + <https://docs.python.org/3/library/string.html#formatstrings>`_, for + example ``'{}'`` or ``'{:#010x}'``. + +name + The attribute value shall be a :ref:`SpecTypeBuildOptionName`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + actions: + - get-integer: null + - define: null + build-type: option + copyrights: + - Copyright (C) 2020, 2022 embedded brains GmbH & Co. KG + default: + - enabled-by: + - bsps/powerpc/motorola_powerpc + - m68k/m5484FireEngine + - powerpc/hsc_cm01 + value: 9600 + - enabled-by: m68k/COBRA5475 + value: 19200 + - enabled-by: true + value: 115200 + description: | + Default baud for console and other serial devices. + enabled-by: true + format: '{}' + links: [] + name: BSP_CONSOLE_BAUD + type: build + +.. _SpecTypeBuildScriptItemType: + +Build Script Item Type +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``script``. This set of attributes specifies a build +script. The optional attributes may be required by commands executed through +the scripts. The following explicit attributes are mandatory: + +* ``do-build`` + +* ``do-configure`` + +* ``prepare-build`` + +* ``prepare-configure`` + +The explicit attributes for this type are: + +asflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildAssemblerOption`. + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +do-build + The attribute value shall be an optional string. If this script shall + execute, then it shall be Python code which is executed via ``exec()`` in + the context of the ``do_build()`` method of the :file:`wscript`. A local + variable ``bld`` is available with the ``waf`` build context. A local + variable ``bic`` is available with the build item context. + +do-configure + The attribute value shall be an optional string. If this script shall + execute, then it shall be Python code which is executed via ``exec()`` in + the context of the ``do_configure()`` method of the :file:`wscript`. A + local variable ``conf`` is available with the ``waf`` configuration + context. A local variable ``cic`` is available with the configuration item + context. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. + +prepare-build + The attribute value shall be an optional string. If this script shall + execute, then it shall be Python code which is executed via ``exec()`` in + the context of the ``prepare_build()`` method of the :file:`wscript`. A + local variable ``bld`` is available with the ``waf`` build context. A + local variable ``bic`` is available with the build item context. + +prepare-configure + The attribute value shall be an optional string. If this script shall + execute, then it shall be Python code which is executed via ``exec()`` in + the context of the ``prepare_configure()`` method of the :file:`wscript`. + A local variable ``conf`` is available with the ``waf`` configuration + context. A local variable ``cic`` is available with the configuration item + context. + +stlib + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkStaticLibraryDirective`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + build-type: script + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + default: null + default-by-variant: [] + do-build: | + bld.install_as( + "${BSP_LIBDIR}/linkcmds", + "bsps/" + bld.env.ARCH + "/" + bld.env.BSP_FAMILY + + "/start/linkcmds." + bld.env.BSP_BASE + ) + do-configure: | + conf.env.append_value( + "LINKFLAGS", + ["-qnolinkcmds", "-T", "linkcmds." + conf.env.BSP_BASE] + ) + enabled-by: true + links: [] + prepare-build: null + prepare-configure: null + type: build + +.. _SpecTypeBuildStartFileItemType: + +Build Start File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``start-file``. This set of attributes specifies a +start file to build. A start file is used to link an executable. All explicit +attributes shall be specified. The explicit attributes for this type are: + +asflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildAssemblerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +install-path + The attribute value shall be a :ref:`SpecTypeBuildInstallPath`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + asflags: [] + build-type: start-file + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + enabled-by: true + includes: [] + install-path: ${BSP_LIBDIR} + links: [] + source: + - bsps/sparc/shared/start/start.S + target: start.o + type: build + +.. _SpecTypeBuildTestProgramItemType: + +Build Test Program Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type`` +attribute if the value is ``test-program``. This set of attributes specifies a +test program executable to build. Test programs may use additional objects +provided by :ref:`SpecTypeBuildObjectsItemType` items. Test programs have an +implicit ``enabled-by`` attribute value which is controlled by the option +action :ref:`set-test-state <SpecTypeBuildOptionItemType>`. If the test state +is set to ``exclude``, then the test program is not built. All explicit +attributes shall be specified. The explicit attributes for this type are: + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +cppflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCPreprocessorOption`. + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +features + The attribute value shall be a string. It shall be the ``waf`` build + features for this test program. + +includes + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildIncludePath`. + +ldflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkerOption`. + +source + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildSource`. + +stlib + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildLinkStaticLibraryDirective`. + +target + The attribute value shall be a :ref:`SpecTypeBuildTarget`. + +use-after + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseAfterDirective`. + +use-before + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildUseBeforeDirective`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + build-type: test-program + cflags: [] + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + cppflags: [] + cxxflags: [] + enabled-by: true + features: c cprogram + includes: [] + ldflags: [] + links: [] + source: + - testsuites/samples/ticker/init.c + - testsuites/samples/ticker/tasks.c + stlib: [] + target: testsuites/samples/ticker.exe + type: build + use-after: [] + use-before: [] + +.. _SpecTypeConstraintItemType: + +Constraint Item Type +^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``constraint``. This set of attributes specifies a +constraint. All explicit attributes shall be specified. The explicit attributes +for this type are: + +rationale + The attribute value shall be an optional string. If the value is present, + then it shall state the rationale or justification of the constraint. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the constraint. + +.. _SpecTypeGlossaryItemType: + +Glossary Item Type +^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``glossary``. This set of attributes specifies a +glossary item. All explicit attributes shall be specified. The explicit +attributes for this type are: + +glossary-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + glossary item type. + +This type is refined by the following types: + +* :ref:`SpecTypeGlossaryGroupItemType` + +* :ref:`SpecTypeGlossaryTermItemType` + +.. _SpecTypeGlossaryGroupItemType: + +Glossary Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeGlossaryItemType` through the +``glossary-type`` attribute if the value is ``group``. This set of attributes +specifies a glossary group. All explicit attributes shall be specified. The +explicit attributes for this type are: + +name + The attribute value shall be a string. It shall be the human readable name + of the glossary group. + +text + The attribute value shall be a string. It shall state the requirement for + the glossary group. + +.. _SpecTypeGlossaryTermItemType: + +Glossary Term Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeGlossaryItemType` through the +``glossary-type`` attribute if the value is ``term``. This set of attributes +specifies a glossary term. All explicit attributes shall be specified. The +explicit attributes for this type are: + +term + The attribute value shall be a string. It shall be the glossary term. + +text + The attribute value shall be a string. It shall be the definition of the + glossary term. + +.. _SpecTypeInterfaceItemType: + +Interface Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``interface``. This set of attributes specifies an +interface specification item. Interface items shall specify the interface of +the software product to other software products and the hardware. Use +:ref:`SpecTypeInterfaceDomainItemType` items to specify interface domains, for +example the :term:`API`, C language, compiler, interfaces to the +implementation, and the hardware. All explicit attributes shall be specified. +The explicit attributes for this type are: + +index-entries + The attribute value shall be a list of strings. It shall be a list of + additional document index entries. A document index entry derived from the + interface name is added automatically. + +interface-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + interface item type. + +This type is refined by the following types: + +* :ref:`SpecTypeApplicationConfigurationGroupItemType` + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceDomainItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceForwardDeclarationItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceHeaderFileItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + +* :ref:`SpecTypeInterfaceUnspecifiedItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeApplicationConfigurationGroupItemType: + +Application Configuration Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``appl-config-group``. This set of +attributes specifies an application configuration group. All explicit +attributes shall be specified. The explicit attributes for this type are: + +description + The attribute value shall be a string. It shall be the description of the + application configuration group. + +name + The attribute value shall be a string. It shall be human readable name of + the application configuration group. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement for the application configuration group. + +.. _SpecTypeApplicationConfigurationOptionItemType: + +Application Configuration Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``appl-config-option``. This set +of attributes specifies an application configuration option. All explicit +attributes shall be specified. The explicit attributes for this type are: + +appl-config-option-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + application configuration option type. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be an + :ref:`SpecTypeApplicationConfigurationOptionName`. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +This type is refined by the following types: + +* :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` + +* :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` + +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + +.. _SpecTypeApplicationConfigurationFeatureEnableOptionItemType: + +Application Configuration Feature Enable Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType` +through the ``appl-config-option-type`` attribute if the value is +``feature-enable``. This set of attributes specifies an application +configuration feature enable option. + +.. _SpecTypeApplicationConfigurationFeatureOptionItemType: + +Application Configuration Feature Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType` +through the ``appl-config-option-type`` attribute if the value is ``feature``. +This set of attributes specifies an application configuration feature option. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +default + The attribute value shall be a string. It shall describe what happens if + the configuration option is undefined. + +.. _SpecTypeApplicationConfigurationValueOptionItemType: + +Application Configuration Value Option Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the + ``appl-config-option-type`` attribute if the value is ``initializer`` + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the + ``appl-config-option-type`` attribute if the value is ``integer`` + +This set of attributes specifies application configuration initializer or +integer option. All explicit attributes shall be specified. The explicit +attributes for this type are: + +default-value + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall + describe the default value of the application configuration option. + +.. _SpecTypeInterfaceCompoundItemType: + +Interface Compound Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``struct`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``union`` + +This set of attributes specifies a compound (struct or union). All explicit +attributes shall be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`. + +definition-kind + The attribute value shall be an + :ref:`SpecTypeInterfaceCompoundDefinitionKind`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the compound + (struct or union). + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeInterfaceDefineItemType: + +Interface Define Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``define``. This set of attributes +specifies a define. All explicit attributes shall be specified. The explicit +attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the define. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeInterfaceDomainItemType: + +Interface Domain Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``domain``. This set of attributes +specifies an interface domain. Interface items are placed into domains through +links with the :ref:`SpecTypeInterfacePlacementLinkRole`. All explicit +attributes shall be specified. The explicit attributes for this type are: + +description + The attribute value shall be a string. It shall be the description of the + domain + +name + The attribute value shall be a string. It shall be the human readable name + of the domain. + +.. _SpecTypeInterfaceEnumItemType: + +Interface Enum Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``enum``. This set of attributes +specifies an enum. All explicit attributes shall be specified. The explicit +attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition-kind + The attribute value shall be an :ref:`SpecTypeInterfaceEnumDefinitionKind`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the enum. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +.. _SpecTypeInterfaceEnumeratorItemType: + +Interface Enumerator Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``enumerator``. This set of +attributes specifies an enumerator. All explicit attributes shall be specified. +The explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the + enumerator. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeInterfaceForwardDeclarationItemType: + +Interface Forward Declaration Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``forward-declaration``. Items of +this type specify a forward declaration. The item shall have exactly one link +with the :ref:`SpecTypeInterfaceTargetLinkRole` to an +:ref:`SpecTypeInterfaceCompoundItemType` item. This link defines the type +declared by the forward declaration. + +.. _SpecTypeInterfaceFunctionOrMacroItemType: + +Interface Function or Macro Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``function`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``macro`` + +This set of attributes specifies a function or a macro. All explicit attributes +shall be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the function + or macro. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +params + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceParameter`. + +return + The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`. + +.. _SpecTypeInterfaceGroupItemType: + +Interface Group Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``group``. This set of attributes +specifies an interface group. All explicit attributes shall be specified. The +explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +identifier + The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`. + +name + The attribute value shall be a string. It shall be the human readable name + of the interface group. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement for the interface group. + +.. _SpecTypeInterfaceHeaderFileItemType: + +Interface Header File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``header-file``. This set of +attributes specifies a header file. The item shall have exactly one link with +the :ref:`SpecTypeInterfacePlacementLinkRole` to an +:ref:`SpecTypeInterfaceDomainItemType` item. This link defines the interface +domain of the header file. All explicit attributes shall be specified. The +explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +path + The attribute value shall be a string. It shall be the path used to include + the header file. For example :file:`rtems/confdefs.h`. + +prefix + The attribute value shall be a string. It shall be the prefix directory + path to the header file in the interface domain. For example + :file:`cpukit/include`. + +.. _SpecTypeInterfaceTypedefItemType: + +Interface Typedef Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``typedef``. This set of +attributes specifies a typedef. All explicit attributes shall be specified. The +explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the typedef. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +params + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceParameter`. + +return + The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`. + +.. _SpecTypeInterfaceUnspecifiedHeaderFileItemType: + +Interface Unspecified Header File Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``unspecified-header-file``. This +set of attributes specifies an unspecified header file. All explicit attributes +shall be specified. The explicit attributes for this type are: + +path + The attribute value shall be a string. It shall be the path used to include + the header file. For example :file:`rtems/confdefs.h`. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + +.. _SpecTypeInterfaceUnspecifiedItemType: + +Interface Unspecified Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-define`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-enum`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-enumerator`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-function`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-group`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-macro`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-object`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-struct`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-typedef`` + +* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if + the value is ``unspecified-union`` + +This set of attributes specifies an unspecified interface. All explicit +attributes shall be specified. The explicit attributes for this type are: + +name + The attribute value shall be a string. It shall be the name of the + unspecified interface. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + +.. _SpecTypeInterfaceVariableItemType: + +Interface Variable Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``variable``. This set of +attributes specifies a variable. All explicit attributes shall be specified. +The explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name of the + variable. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +.. _SpecTypeRegisterBlockItemType: + +Register Block Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceItemType` through the +``interface-type`` attribute if the value is ``register-block``. This set of +attributes specifies a register block. A register block may be used to specify +the interface of devices. Register blocks consist of register block members +specified by the ``definition`` attribute. Register block members are either +instances of registers specified by the ``registers`` attribute or instances of +other register blocks specified by links with the +:ref:`SpecTypeRegisterBlockIncludeRole`. Registers consists of bit fields (see +:ref:`SpecTypeRegisterBitsDefinition`. The register block members are placed +into the address space of the device relative to the base address of the +register block. Register member offsets and the register block size are +specified in units of the address space granule. All explicit attributes shall +be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +definition + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBlockMemberDefinitionDirective`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +identifier + The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`. + +name + The attribute value shall be a string. It shall be the name of the register + block. + +notes + The attribute value shall be an :ref:`SpecTypeInterfaceNotes`. + +register-block-group + The attribute value shall be a string. It shall be the name of the + interface group defined for the register block. For the group identifier + see the ``identifier`` attribute. + +register-block-size + The attribute value shall be an :ref:`SpecTypeOptionalInteger`. If the + value is present, then it shall be the size of the register block in units + of the address space granule. + +register-prefix + The attribute value shall be an optional string. If the value is present, + then it will be used to prefix register bit field names, otherwise the + value of the ``name`` attribute will be used. + +registers + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterDefinition`. + +.. _SpecTypeProxyItemTypes: + +Proxy Item Types +^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``proxy``. Items of similar characteristics may link +to a proxy item through links with the :ref:`SpecTypeProxyMemberLinkRole`. A +proxy item resolves to the first member item which is enabled. Proxies may be +used to provide an interface with a common name and implementations which +depend on configuration options. For example, in one configuration a constant +could be a compile time constant and in another configuration it could be a +read-only object. + +.. _SpecTypeRequirementItemType: + +Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``requirement``. This set of attributes specifies a +requirement. All explicit attributes shall be specified. The explicit +attributes for this type are: + +rationale + The attribute value shall be an optional string. If the value is present, + then it shall state the rationale or justification of the requirement. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + +requirement-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + requirement item type. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + state the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeFunctionalRequirementItemType` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + functional-type: capability + links: [] + rationale: | + It keeps you busy. + requirement-type: functional + text: | + The system shall do crazy things. + type: requirement + +.. _SpecTypeFunctionalRequirementItemType: + +Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRequirementItemType` through the +``requirement-type`` attribute if the value is ``functional``. This set of +attributes specifies a functional requirement. All explicit attributes shall be +specified. The explicit attributes for this type are: + +functional-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + functional type of the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeGenericFunctionalRequirementItemType` + +.. _SpecTypeActionRequirementItemType: + +Action Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeFunctionalRequirementItemType` through the +``functional-type`` attribute if the value is ``action``. This set of +attributes specifies functional requirements and corresponding validation test +code. The functional requirements of an action are specified. An action +performs a step in a finite state machine. An action is implemented through a +function or a macro. The action is performed through a call of the function or +an execution of the code of a macro expansion by an actor. The actor is for +example a task or an interrupt service routine. + +For action requirements which specify the function of an interface, there shall +be exactly one link with the :ref:`SpecTypeInterfaceFunctionLinkRole` to the +interface of the action. + +The action requirements are specified by + +* a list of pre-conditions, each with a set of states, + +* a list of post-conditions, each with a set of states, + +* the transition of pre-condition states to post-condition states through the + action. + +Along with the requirements, the test code to generate a validation test is +specified. For an action requirement it is verified that all variations of +pre-condition states have a set of post-condition states specified in the +transition map. All transitions are covered by the generated test code. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +post-conditions + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementCondition`. + +pre-conditions + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementCondition`. + +skip-reasons + The attribute value shall be an + :ref:`SpecTypeActionRequirementSkipReasons`. + +test-action + The attribute value shall be a string. It shall be the test action code. + +test-brief + The attribute value shall be an optional string. If the value is present, + then it shall be the test case brief description. + +test-cleanup + The attribute value shall be an optional string. If the value is present, + then it shall be the test cleanup code. The code is placed in the test + action loop body after the test post-condition checks. + +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. + +test-context-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test context support code. The context support code + is placed at file scope before the test context definition. + +test-description + The attribute value shall be an optional string. If the value is present, + then it shall be the test case description. + +test-header + The attribute value shall be a :ref:`SpecTypeTestHeader`. + +test-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. + +test-local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. + +test-prepare + The attribute value shall be an optional string. If the value is present, + then it shall be the early test preparation code. The code is placed in + the test action loop body before the test pre-condition preparations. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +test-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test case support code. The support code is placed at + file scope before the test case code. + +test-target + The attribute value shall be a string. It shall be the path to the + generated test case source file. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +transition-map + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementTransition`. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + functional-type: action + links: [] + post-conditions: + - name: Status + states: + - name: Success + test-code: | + /* Check that the status is SUCCESS */ + text: | + The status shall be SUCCESS. + - name: Error + test-code: | + /* Check that the status is ERROR */ + text: | + The status shall be ERROR. + test-epilogue: null + test-prologue: null + - name: Data + states: + - name: Unchanged + test-code: | + /* Check that the data is unchanged */ + text: | + The data shall be unchanged by the action. + - name: Red + test-code: | + /* Check that the data is red */ + text: | + The data shall be red. + - name: Green + test-code: | + /* Check that the data is green */ + text: | + The data shall be green. + test-epilogue: null + test-prologue: null + pre-conditions: + - name: Data + states: + - name: NullPtr + test-code: | + /* Set data pointer to NULL */ + text: | + The data pointer shall be NULL. + - name: Valid + test-code: | + /* Set data pointer to reference a valid data buffer */ + text: | + The data pointer shall reference a valid data buffer. + test-epilogue: null + test-prologue: null + - name: Option + states: + - name: Red + test-code: | + /* Set option to RED */ + text: | + The option shall be RED. + - name: Green + test-code: | + /* Set option to GREEN */ + text: | + The option shall be GREEN. + test-epilogue: null + test-prologue: null + requirement-type: functional + skip-reasons: {} + test-action: | + /* Call the function of the action */ + test-brief: null + test-cleanup: null + test-context: + - brief: null + description: null + member: void *data + - brief: null + description: null + member: option_type option + test-context-support: null + test-description: null + test-header: null + test-includes: [] + test-local-includes: [] + test-prepare: null + test-setup: null + test-stop: null + test-support: null + test-target: tc-red-green-data.c + test-teardown: null + transition-map: + - enabled-by: true + post-conditions: + Status: Error + Data: Unchanged + pre-conditions: + Data: NullPtr + Option: all + - enabled-by: true + post-conditions: + Status: Success + Data: Red + pre-conditions: + Data: Valid + Option: Red + - enabled-by: true + post-conditions: + Status: Success + Data: Green + pre-conditions: + Data: Valid + Option: Green + rationale: null + references: [] + text: | + ${.:/text-template} + type: requirement + +.. _SpecTypeGenericFunctionalRequirementItemType: + +Generic Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``capability`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``dependability-function`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``function`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``interface-define-not-defined`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``operational`` + +* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type`` + attribute if the value is ``safety-function`` + +Items of this type state a functional requirement with the functional type +defined by the specification type refinement. + +.. _SpecTypeNonFunctionalRequirementItemType: + +Non-Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRequirementItemType` through the +``requirement-type`` attribute if the value is ``non-functional``. This set of +attributes specifies a non-functional requirement. All explicit attributes +shall be specified. The explicit attributes for this type are: + +non-functional-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + non-functional type of the requirement. + +This type is refined by the following types: + +* :ref:`SpecTypeDesignGroupRequirementItemType` + +* :ref:`SpecTypeDesignTargetItemType` + +* :ref:`SpecTypeGenericNonFunctionalRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentItemType` + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +.. _SpecTypeDesignGroupRequirementItemType: + +Design Group Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``design-group``. This +set of attributes specifies a design group requirement. Design group +requirements have an explicit reference to the associated Doxygen group +specified by the ``identifier`` attribute. Design group requirements have an +implicit validation by inspection method. The qualification toolchain shall +perform the inspection and check that the specified Doxygen group exists in the +software source code. All explicit attributes shall be specified. The explicit +attributes for this type are: + +identifier + The attribute value shall be a + :ref:`SpecTypeRequirementDesignGroupIdentifier`. + +.. _SpecTypeDesignTargetItemType: + +Design Target Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``design-target``. This +set of attributes specifies a design :term:`target`. All explicit attributes +shall be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an optional string. If the value is present, + then it shall briefly describe the target. + +description + The attribute value shall be an optional string. If the value is present, + then it shall thoroughly describe the target. + +name + The attribute value shall be a string. It shall be the target name. + +.. _SpecTypeGenericNonFunctionalRequirementItemType: + +Generic Non-Functional Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``build-configuration`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``constraint`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``design`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``documentation`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``interface`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``interface-requirement`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``maintainability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``performance`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is + ``performance-runtime-limits`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``portability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``quality`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``reliability`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``resource`` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` through the + ``non-functional-type`` attribute if the value is ``safety`` + +Items of this type state a non-functional requirement with the non-functional +type defined by the specification type refinement. + +.. _SpecTypeRuntimeMeasurementEnvironmentItemType: + +Runtime Measurement Environment Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is +``performance-runtime-environment``. This set of attributes specifies a runtime +measurement environment. All explicit attributes shall be specified. The +explicit attributes for this type are: + +name + The attribute value shall be a string. It shall be the runtime measurement + environment name. See also + :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. + +.. _SpecTypeRuntimePerformanceRequirementItemType: + +Runtime Performance Requirement Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through +the ``non-functional-type`` attribute if the value is ``performance-runtime``. +The item shall have exactly one link with the +:ref:`SpecTypeRuntimeMeasurementRequestLinkRole`. A requirement text processor +shall support a substitution of ${.:/limit-kind}: + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound`` or + ``min-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"minimum"``. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``mean-lower-bound`` or + ``mean-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"mean"``. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``max-lower-bound`` or + ``max-upper-bound``, the substitution of ${.:/limit-kind} shall be + ``"maximum"``. + +A requirement text processor shall support a substitution of +${.:/limit-condition}: + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound``, + ``mean-lower-bound``, or ``max-lower-bound``, the substitution of + ${.:/limit-condition} shall be ``"greater than or equal to <value>"`` with + <value> being the value of the corresponding entry in the + :ref:`SpecTypeRuntimeMeasurementValueTable`. + +* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-upper-bound``, + ``mean-upper-bound``, or ``max-upper-bound``, the substitution of + ${.:/limit-condition} shall be ``"less than or equal to <value>"`` with + <value> being the value of the corresponding entry in the + :ref:`SpecTypeRuntimeMeasurementValueTable`. + +A requirement text processor shall support a substitution of ${.:/environment}. +The value of the substitution shall be ``"<environment> environment"`` with +<environment> being the environment of the corresponding entry in the +:ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. + +This set of attributes specifies a runtime performance requirement. Along with +the requirement, the validation test code to execute a measure runtime request +is specified. All explicit attributes shall be specified. The explicit +attributes for this type are: + +params + The attribute value shall be a + :ref:`SpecTypeRuntimePerformanceParameterSet`. + +test-body + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It shall + provide the code of the measure runtime body handler. In contrast to other + methods, this method is mandatory. + +test-cleanup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code to clean up the measure runtime request. This method is + called before the cleanup method of the corresponding + :ref:`SpecTypeRuntimeMeasurementTestItemType` item and after the request. + +test-prepare + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code to prepare the measure runtime request. This method is + called after the prepare method of the corresponding + :ref:`SpecTypeRuntimeMeasurementTestItemType` item and before the request. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code of the measure runtime setup handler. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may + provide the code of the measure runtime teardown handler. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + links: + - role: runtime-measurement-request + uid: ../val/perf + params: {} + rationale: null + references: [] + test-body: + brief: | + Get a buffer. + code: | + ctx->status = rtems_partition_get_buffer( ctx->part_many, &ctx->buffer ); + description: null + test-cleanup: null + test-prepare: null + test-setup: null + test-teardown: + brief: | + Return the buffer. + code: | + rtems_status_code sc; + + T_quiet_rsc_success( ctx->status ); + + sc = rtems_partition_return_buffer( ctx->part_many, ctx->buffer ); + T_quiet_rsc_success( sc ); + + return tic == toc; + description: null + text: | + When a partition has exactly ${../val/perf:/params/buffer-count} free + buffers, the ${.:/limit-kind} runtime of exactly + ${../val/perf:/params/sample-count} successful calls to + ${../if/get-buffer:/name} in the ${.:/environment} shall be + ${.:/limit-condition}. + non-functional-type: performance-runtime + requirement-type: non-functional + type: requirement + +.. _SpecTypeRequirementValidationItemType: + +Requirement Validation Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``validation``. This set of attributes provides a +requirement validation evidence. The item shall have exactly one link to the +validated requirement with the :ref:`SpecTypeRequirementValidationLinkRole`. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +method + The attribute value shall be a :ref:`SpecTypeName`. It shall specify the + requirement validation method (except validation by test). Validation by + test is done through :ref:`SpecTypeTestCaseItemType` items. + +references + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeExternalReference`. + +text + The attribute value shall be a string. It shall provide the validation + evidence depending on the validation method: + + * *By analysis*: A statement shall be provided how the requirement is met, + by analysing static properties of the :term:`software product`. + + * *By inspection*: A statement shall be provided how the requirement is + met, by inspection of the :term:`source code`. + + * *By review of design*: A rationale shall be provided to demonstrate how + the requirement is satisfied implicitly by the software design. + +This type is refined by the following types: + +* :ref:`SpecTypeRequirementValidationMethod` + +.. _SpecTypeRequirementValidationMethod: + +Requirement Validation Method +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute + if the value is ``by-analysis`` + +* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute + if the value is ``by-inspection`` + +* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute + if the value is ``by-review-of-design`` + +.. _SpecTypeRuntimeMeasurementTestItemType: + +Runtime Measurement Test Item Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``runtime-measurement-test``. This set of attributes +specifies a runtime measurement test case. All explicit attributes shall be +specified. The explicit attributes for this type are: + +params + The attribute value shall be a + :ref:`SpecTypeRuntimeMeasurementParameterSet`. + +test-brief + The attribute value shall be an optional string. If the value is present, + then it shall be the test case brief description. + +test-cleanup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the measure runtime request cleanup + method. The method is called after each measure runtime request. + +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. + +test-context-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test context support code. The context support code + is placed at file scope before the test context definition. + +test-description + The attribute value shall be an optional string. If the value is present, + then it shall be the test case description. + +test-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. + +test-local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. + +test-prepare + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the measure runtime request prepare + method. The method is called before each measure runtime request. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case setup fixture method. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case stop fixture method. + +test-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test case support code. The support code is placed at + file scope before the test case code. + +test-target + The attribute value shall be a string. It shall be the path to the + generated test case source file. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the + value is present, then it shall be the test case teardown fixture method. + +.. _SpecTypeSpecificationItemType: + +Specification Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``spec``. This set of attributes specifies +specification types. All explicit attributes shall be specified. The explicit +attributes for this type are: + +spec-description + The attribute value shall be an optional string. It shall be the + description of the specification type. + +spec-example + The attribute value shall be an optional string. If the value is present, + then it shall be an example of the specification type. + +spec-info + The attribute value shall be a :ref:`SpecTypeSpecificationInformation`. + +spec-name + The attribute value shall be an optional string. It shall be the human + readable name of the specification type. + +spec-type + The attribute value shall be a :ref:`SpecTypeName`. It shall the + specification type. + +Please have a look at the following example: + +.. code-block:: yaml + + SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause + copyrights: + - Copyright (C) 2020 embedded brains GmbH & Co. KG + enabled-by: true + links: + - role: spec-member + uid: root + - role: spec-refinement + spec-key: type + spec-value: example + uid: root + spec-description: null + spec-example: null + spec-info: + dict: + attributes: + an-example-attribute: + description: | + It shall be an example. + spec-type: optional-str + example-number: + description: | + It shall be the example number. + spec-type: int + description: | + This set of attributes specifies an example. + mandatory-attributes: all + spec-name: Example Item Type + spec-type: spec + type: spec + +.. _SpecTypeTestCaseItemType: + +Test Case Item Type +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``test-case``. This set of attributes specifies a +test case. All explicit attributes shall be specified. The explicit attributes +for this type are: + +test-actions + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestCaseAction`. + +test-brief + The attribute value shall be a string. It shall be the test case brief + description. + +test-context + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestContextMember`. + +test-context-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test context support code. The context support code + is placed at file scope before the test context definition. + +test-description + The attribute value shall be an optional string. It shall be the test case + description. + +test-header + The attribute value shall be a :ref:`SpecTypeTestHeader`. + +test-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. + +test-local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. + +test-setup + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +test-stop + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +test-support + The attribute value shall be an optional string. If the value is present, + then it shall be the test case support code. The support code is placed at + file scope before the test case code. + +test-target + The attribute value shall be a string. It shall be the path to the + generated target test case source file. + +test-teardown + The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. + +.. _SpecTypeTestPlatformItemType: + +Test Platform Item Type +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``test-platform``. Please note: + +.. warning:: + + This item type is work in progress. + +This set of attributes specifies a test platform. All explicit attributes shall +be specified. The explicit attributes for this type are: + +description + The attribute value shall be a string. It shall be the description of the + test platform. + +name + The attribute value shall be a string. It shall be the human readable name + of the test platform. + +.. _SpecTypeTestProcedureItemType: + +Test Procedure Item Type +^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeRootItemType` through the ``type`` +attribute if the value is ``test-procedure``. Please note: + +.. warning:: + + This item type is work in progress. + +This set of attributes specifies a test procedure. All explicit attributes +shall be specified. The explicit attributes for this type are: + +name + The attribute value shall be a string. It shall be the human readable name + of the test procedure. + +purpose + The attribute value shall be a string. It shall state the purpose of the + test procedure. + +steps + The attribute value shall be a string. It shall describe the steps of the + test procedure execution. + +.. _SpecTypeTestSuiteItemType: + +Test Suite Item Type +^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is + ``memory-benchmark`` + +* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is + ``test-suite`` + +This set of attributes specifies a test suite. All explicit attributes shall be +specified. The explicit attributes for this type are: + +test-brief + The attribute value shall be a string. It shall be the test suite brief + description. + +test-code + The attribute value shall be a string. It shall be the test suite code. + The test suite code is placed at file scope in the target source file. + +test-description + The attribute value shall be an optional string. It shall be the test suite + description. + +test-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include <...>``. + +test-local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included via ``#include "..."``. + +test-target + The attribute value shall be a string. It shall be the path to the + generated target test suite source file. + +.. _ReqEngSpecificationAttributeSetsAndValueTypes: + +Specification Attribute Sets and Value Types +-------------------------------------------- + +.. _SpecTypeActionRequirementBooleanExpression: + +Action Requirement Boolean Expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type is a boolean expression. + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. Each attribute defines an operator. + Exactly one of the explicit attributes shall be specified. The explicit + attributes for this type are: + + and + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. The *and* operator + evaluates to the *logical and* of the evaluation results of the + expressions in the list. + + not + The attribute value shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. The *not* operator + evaluates to the *logical not* of the evaluation results of the + expression. + + or + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. The *or* operator + evaluates to the *logical or* of the evaluation results of the + expressions in the list. + + post-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionConditionSet`. The + *post-conditions* operator evaluates to true, if the post-condition + states of the associated transition are contained in the specified + post-condition set, otherwise to false. + + pre-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionConditionSet`. The + *pre-conditions* operator evaluates to true, if the pre-condition states + of the associated transition are contained in the specified pre-condition + set, otherwise to false. + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. This list of expressions + evaluates to the *logical or* of the evaluation results of the expressions in + the list. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementBooleanExpression` + +* :ref:`SpecTypeActionRequirementExpression` + +.. _SpecTypeActionRequirementCondition: + +Action Requirement Condition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines an action pre-condition or post-condition. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +name + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. + +states + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementState`. + +test-epilogue + The attribute value shall be an optional string. If the value is present, + then it shall be the test epilogue code. The epilogue code is placed in the + test condition preparation or check before the state-specific code. The + code may use a local variable ``ctx`` which points to the test context, see + :ref:`SpecTypeTestContextMember`. + +test-prologue + The attribute value shall be an optional string. If the value is present, + then it shall be the test prologue code. The prologue code is placed in the + test condition preparation or check after the state-specific code. The + code may use a local variable ``ctx`` which points to the test context, see + :ref:`SpecTypeTestContextMember`. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +.. _SpecTypeActionRequirementExpression: + +Action Requirement Expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines an expression which may define the state of a +post-condition. The ``else`` and ``specified-by`` shall be used individually. +The ``if`` and ``then`` or ``then-specified-by`` expressions shall be used +together. At least one of the explicit attributes shall be specified. The +explicit attributes for this type are: + +else + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name + of the state of the post-condition. + +if + The attribute value shall be an + :ref:`SpecTypeActionRequirementBooleanExpression`. If the boolean + expression evaluates to true, then the state is defined according to the + ``then`` attribute value. + +specified-by + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It + shall be the name of a pre-condition. The name of the state of the + pre-condition in the associated transition defines the name of the state of + the post-condition. + +then + The attribute value shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name + of the state of the post-condition. + +then-specified-by + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It + shall be the name of a pre-condition. The name of the state of the + pre-condition in the associated transition defines the name of the state of + the post-condition. + +.. _SpecTypeActionRequirementExpressionConditionSet: + +Action Requirement Expression Condition Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines for the specified conditions a set of states. +Generic attributes may be specified. Each generic attribute key shall be an +:ref:`SpecTypeActionRequirementName`. Each generic attribute value shall be an +:ref:`SpecTypeActionRequirementExpressionStateSet`. There shall be at most one +generic attribute key for each condition. The key name shall be the condition +name. The value of each generic attribute shall be a set of states of the +condition. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementBooleanExpression` + +.. _SpecTypeActionRequirementExpressionStateName: + +Action Requirement Expression State Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the name of a state of the condition +or ``N/A`` if the condition is not applicable. The value + +* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + +* or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementExpression` + +.. _SpecTypeActionRequirementExpressionStateSet: + +Action Requirement Expression State Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementExpressionStateName`. The list defines a set + of states of the condition. + +* The value may be a string. It shall be the name of a state of the condition + or ``N/A`` if the condition is not applicable. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + +.. _SpecTypeActionRequirementName: + +Action Requirement Name +^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the name of a condition or a state of +a condition used to define pre-conditions and post-conditions of an action +requirement. It shall be formatted in CamelCase. It should be brief and +abbreviated. The rationale for this is that the names are used in tables and +the horizontal space is limited by the page width. The more conditions you +have in an action requirement, the shorter the names should be. The name +``NA`` is reserved and indicates that a condition is not applicable. The value + +* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + +* and, shall be not equal to "``NA``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementCondition` + +* :ref:`SpecTypeActionRequirementExpressionConditionSet` + +* :ref:`SpecTypeActionRequirementExpression` + +* :ref:`SpecTypeActionRequirementSkipReasons` + +* :ref:`SpecTypeActionRequirementState` + +* :ref:`SpecTypeActionRequirementTransitionPostConditions` + +* :ref:`SpecTypeActionRequirementTransitionPreConditions` + +.. _SpecTypeActionRequirementSkipReasons: + +Action Requirement Skip Reasons +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies skip reasons used to justify why transitions +in the transition map are skipped. Generic attributes may be specified. Each +generic attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each +generic attribute value shall be a string. The key defines the name of a skip +reason. The name can be used in +:ref:`SpecTypeActionRequirementTransitionPostConditions` to skip the +corresponding transitions. The value shall give a reason why the transitions +are skipped. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +.. _SpecTypeActionRequirementState: + +Action Requirement State +^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines an action pre-condition or post-condition state. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +name + The attribute value shall be an :ref:`SpecTypeActionRequirementName`. + +test-code + The attribute value shall be a string. It shall be the test code to prepare + or check the state of the condition. The code may use a local variable + ``ctx`` which points to the test context, see + :ref:`SpecTypeTestContextMember`. + +text + The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall + define the state of the condition. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementCondition` + +.. _SpecTypeActionRequirementTransition: + +Action Requirement Transition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines the transition from multiple sets of states of +pre-conditions to a set of states of post-conditions through an action in an +action requirement. The ability to specify multiple sets of states of +pre-conditions which result in a common set of post-conditions may allow a more +compact specification of the transition map. For example, let us suppose you +want to specify the action of a function with a pointer parameter. The +function performs an early check that the pointer is NULL and in this case +returns an error code. The pointer condition dominates the action outcome if +the pointer is NULL. Other pre-condition states can be simply set to ``all`` +for this transition. All explicit attributes shall be specified. The explicit +attributes for this type are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. The + transition map may be customized to support configuration variants through + this attribute. The default transitions (``enabled-by: true``) shall be + specified before the customized variants in the list. + +post-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementTransitionPostConditions`. + +pre-conditions + The attribute value shall be an + :ref:`SpecTypeActionRequirementTransitionPreConditions`. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +.. _SpecTypeActionRequirementTransitionPostConditionState: + +Action Requirement Transition Post-Condition State +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementExpression`. The list contains expressions to + define the state of the corresponding post-condition. + +* The value may be a string. It shall be the name of a state of the + corresponding post-condition or ``N/A`` if the post-condition is not + applicable. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * or, shall be equal to "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransitionPostConditions` + +.. _SpecTypeActionRequirementTransitionPostConditions: + +Action Requirement Transition Post-Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes defines for each + post-condition the state after the action for a transition in an action + requirement. Generic attributes may be specified. Each generic attribute key + shall be an :ref:`SpecTypeActionRequirementName`. Each generic attribute + value shall be an + :ref:`SpecTypeActionRequirementTransitionPostConditionState`. There shall be + exactly one generic attribute key for each post-condition. The key name + shall be the post-condition name. The value of each generic attribute shall + be the state of the post-condition or ``N/A`` if the post-condition is not + applicable. + +* The value may be a string. It shall be the name of a skip reason. If a skip + reason is given instead of a listing of post-condition states, then this + transition is skipped and no test code runs for this transition. The value + + * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``", + + * and, shall be not equal to "``NA``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransition` + +.. _SpecTypeActionRequirementTransitionPreConditionStateSet: + +Action Requirement Transition Pre-Condition State Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeActionRequirementName`. The list defines the set of states of + the pre-condition in the transition. + +* The value may be a string. The value ``all`` represents all states of the + pre-condition in this transition. The value ``N/A`` marks the pre-condition + as not applicable in this transition. The value shall be an element of + + * "``all``", and + + * "``N/A``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransitionPreConditions` + +.. _SpecTypeActionRequirementTransitionPreConditions: + +Action Requirement Transition Pre-Conditions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes defines for each + pre-condition the set of states before the action for a transition in an + action requirement. Generic attributes may be specified. Each generic + attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each generic + attribute value shall be an + :ref:`SpecTypeActionRequirementTransitionPreConditionStateSet`. There shall + be exactly one generic attribute key for each pre-condition. The key name + shall be the pre-condition name. The value of each generic attribute shall + be a set of states of the pre-condition. + +* The value may be a string. If this name is specified instead of explicit + pre-condition states, then the post-condition states of this entry are used + to define all remaining transitions of the map. The value shall be equal to + "``default``". + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransition` + +.. _SpecTypeApplicationConfigurationOptionName: + +Application Configuration Option Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the name of an application +configuration option. The value shall match with the regular expression +"``^(CONFIGURE_|BSP_)[A-Z0-9_]+$``". + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +.. _SpecTypeBooleanOrIntegerOrString: + +Boolean or Integer or String +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a boolean. + +* The value may be an integer number. + +* The value may be a string. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +* :ref:`SpecTypeInterfaceReturnValue` + +.. _SpecTypeBuildAssemblerOption: + +Build Assembler Option +^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an option for the assembler. The +options are used to assemble the sources of this item. The options defined by +this attribute succeed the options presented to the item by the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +.. _SpecTypeBuildCCompilerOption: + +Build C Compiler Option +^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an option for the C compiler. The +options are used to compile the sources of this item. The options defined by +this attribute succeed the options presented to the item by the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionCCompilerCheckAction` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildCPreprocessorOption: + +Build C Preprocessor Option +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an option for the C preprocessor. The +options are used to preprocess the sources of this item. The options defined +by this attribute succeed the options presented to the item by the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildCXXCompilerOption: + +Build C++ Compiler Option +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an option for the C++ compiler. The +options are used to compile the sources of this item. The options defined by +this attribute succeed the options presented to the item by the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildOptionCXXCompilerCheckAction` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildDependencyConditionalLinkRole: + +Build Dependency Conditional Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``build-dependency-conditional``. It defines the build dependency +conditional role of links. All explicit attributes shall be specified. The +explicit attributes for this type are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It + shall define under which conditions the build dependency is enabled. + +.. _SpecTypeBuildDependencyLinkRole: + +Build Dependency Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``build-dependency``. It defines the build dependency role of links. + +.. _SpecTypeBuildIncludePath: + +Build Include Path +^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be a path to header files. The path is +used by the C preprocessor to search for header files. It succeeds the +includes presented to the item by the build item context. For an +:ref:`SpecTypeBuildGroupItemType` item the includes are visible to all items +referenced by the group item. For :ref:`SpecTypeBuildBSPItemType`, +:ref:`SpecTypeBuildObjectsItemType`, :ref:`SpecTypeBuildLibraryItemType`, +:ref:`SpecTypeBuildStartFileItemType`, and +:ref:`SpecTypeBuildTestProgramItemType` items the includes are only visible to +the sources specified by the item itself and they do not propagate to +referenced items. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildInstallDirective: + +Build Install Directive +^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies files installed by a build item. All explicit +attributes shall be specified. The explicit attributes for this type are: + +destination + The attribute value shall be a string. It shall be the install destination + directory. + +source + The attribute value shall be a list of strings. It shall be the list of + source files to be installed in the destination directory. The path to a + source file shall be relative to the directory of the :file:`wscript`. + +This type is used by the following types: + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +.. _SpecTypeBuildInstallPath: + +Build Install Path +^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the installation path of a + :ref:`SpecTypeBuildTarget`. + +This type is used by the following types: + +* :ref:`SpecTypeBuildConfigurationFileItemType` + +* :ref:`SpecTypeBuildConfigurationHeaderItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +.. _SpecTypeBuildLinkStaticLibraryDirective: + +Build Link Static Library Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an external static library identifier. +The library is used to link programs referenced by this item, e.g. ``m`` for +``libm.a``. The library is added to the build command through the ``stlib`` +attribute. It shall not be used for internal static libraries. Internal static +libraries shall be specified through the ``use-after`` and ``use-before`` +attributes to enable a proper build dependency tracking. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildLinkerOption: + +Build Linker Option +^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an option for the linker. The options +are used to link executables. The options defined by this attribute succeed +the options presented to the item by the build item context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildOptionAction: + +Build Option Action +^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a build option action. Exactly one of the +explicit attributes shall be specified. The explicit attributes for this type +are: + +append-test-cppflags + The attribute value shall be a string. It shall be the name of a test + program. The action appends the action value to the ``CPPFLAGS`` of the + test program. The name shall correspond to the name of a + :ref:`SpecTypeBuildTestProgramItemType` item. Due to the processing order + of items, there is no way to check if the name specified by the attribute + value is valid. + +assert-aligned + The attribute value shall be an integer number. The action asserts that the + action value is aligned according to the attribute value. + +assert-eq + The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. The + action asserts that the action value is equal to the attribute value. + +assert-ge + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is greater than or equal to the attribute + value. + +assert-gt + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is greater than the attribute value. + +assert-int16 + The attribute shall have no value. The action asserts that the action value + is a valid signed 16-bit integer. + +assert-int32 + The attribute shall have no value. The action asserts that the action value + is a valid signed 32-bit integer. + +assert-int64 + The attribute shall have no value. The action asserts that the action value + is a valid signed 64-bit integer. + +assert-int8 + The attribute shall have no value. The action asserts that the action value + is a valid signed 8-bit integer. + +assert-le + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is less than or equal to the attribute value. + +assert-lt + The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action + asserts that the action value is less than the attribute value. + +assert-ne + The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. The + action asserts that the action value is not equal to the attribute value. + +assert-power-of-two + The attribute shall have no value. The action asserts that the action value + is a power of two. + +assert-uint16 + The attribute shall have no value. The action asserts that the action value + is a valid unsigned 16-bit integer. + +assert-uint32 + The attribute shall have no value. The action asserts that the action value + is a valid unsigned 32-bit integer. + +assert-uint64 + The attribute shall have no value. The action asserts that the action value + is a valid unsigned 64-bit integer. + +assert-uint8 + The attribute shall have no value. The action asserts that the action value + is a valid unsigned 8-bit integer. + +check-cc + The attribute value shall be a + :ref:`SpecTypeBuildOptionCCompilerCheckAction`. + +check-cxx + The attribute value shall be a + :ref:`SpecTypeBuildOptionCXXCompilerCheckAction`. + +define + The attribute value shall be an optional string. The action adds a define + to the configuration set. If the attribute value is present, then it is + used as the name of the define, otherwise the ``name`` of the item is used. + The value of the define is the action value. If the action value is a + string, then it is quoted. + +define-condition + The attribute value shall be an optional string. The action adds a + conditional define to the configuration set. If the attribute value is + present, then it is used as the name of the define, otherwise the ``name`` + of the item is used. The value of the define is the action value. + +define-unquoted + The attribute value shall be an optional string. The action adds a define + to the configuration set. If the attribute value is present, then it is + used as the name of the define, otherwise the ``name`` of the item is used. + The value of the define is the action value. If the action value is a + string, then it is not quoted. + +env-append + The attribute value shall be an optional string. The action appends the + action value to an environment of the configuration set. If the attribute + value is present, then it is used as the name of the environment variable, + otherwise the ``name`` of the item is used. + +env-assign + The attribute value shall be an optional string. The action assigns the + action value to an environment of the configuration set. If the attribute + value is present, then it is used as the name of the environment variable, + otherwise the ``name`` of the item is used. + +env-enable + The attribute value shall be an optional string. If the action value is + true, then a name is appended to the ``ENABLE`` environment variable of the + configuration set. If the attribute value is present, then it is used as + the name, otherwise the ``name`` of the item is used. + +find-program + The attribute shall have no value. The action tries to find the program + specified by the action value. Uses the ``${PATH}`` to find the program. + Returns the result of the find operation, e.g. a path to the program. + +find-tool + The attribute shall have no value. The action tries to find the tool + specified by the action value. Uses the tool paths specified by the + ``--rtems-tools`` command line option. Returns the result of the find + operation, e.g. a path to the program. + +format-and-define + The attribute value shall be an optional string. The action adds a define + to the configuration set. If the attribute value is present, then it is + used as the name of the define, otherwise the ``name`` of the item is used. + The value of the define is the action value. The value is formatted + according to the ``format`` attribute value. + +get-boolean + The attribute shall have no value. The action gets the action value for + subsequent actions from a configuration file variable named by the items + ``name`` attribute. If no such variable exists in the configuration file, + then the default value is used. The value is converted to a boolean. + +get-env + The attribute value shall be a string. The action gets the action value for + subsequent actions from the environment variable of the configuration set + named by the attribute value. + +get-integer + The attribute shall have no value. The action gets the action value for + subsequent actions from a configuration file variable named by the items + ``name`` attribute. If no such variable exists in the configuration file, + then the default value is used. The value is converted to an integer. + +get-string + The attribute shall have no value. The action gets the action value for + subsequent actions from a configuration file variable named by the items + ``name`` attribute. If no such variable exists in the configuration file, + then the default value is used. The value is converted to a string. + +get-string-command-line + The attribute value shall be a string. The action gets the action value for + subsequent actions from the value of a command line option named by the + items ``name`` attribute. If no such command line option is present, then + the attribute value is used. The value is converted to a string. + +script + The attribute value shall be a string. The action executes the attribute + value with the Python ``eval()`` function in the context of the script + action handler. + +set-test-state + The attribute value shall be a + :ref:`SpecTypeBuildOptionSetTestStateAction`. + +set-value + The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. The action + sets the action value for subsequent actions to the attribute value. + +split + The attribute shall have no value. The action splits the action value. + +substitute + The attribute shall have no value. The action performs a ``${VARIABLE}`` + substitution on the action value. Use ``$$`` for a plain ``$`` character. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionItemType` + +.. _SpecTypeBuildOptionCCompilerCheckAction: + +Build Option C Compiler Check Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a check done using the C compiler. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +cflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCCompilerOption`. + +fragment + The attribute value shall be a string. It shall be a code fragment used to + check the availability of a certain feature through compilation with the C + compiler. The resulting object is not linked to an executable. + +message + The attribute value shall be a string. It shall be a description of the + feature to check. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeBuildOptionCXXCompilerCheckAction: + +Build Option C++ Compiler Check Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a check done using the C++ compiler. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +cxxflags + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeBuildCXXCompilerOption`. + +fragment + The attribute value shall be a string. It shall be a code fragment used to + check the availability of a certain feature through compilation with the + C++ compiler. The resulting object is not linked to an executable. + +message + The attribute value shall be a string. It shall be a description of the + feature to check. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeBuildOptionDefaultValue: + +Build Option Default Value +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a build option default value. All explicit +attributes shall be specified. The explicit attributes for this type are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. + +value + The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. Its value + shall be the default value for the associated enabled-by expression. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionItemType` + +.. _SpecTypeBuildOptionName: + +Build Option Name +^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the name of the build option. The +value shall match with the regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionItemType` + +.. _SpecTypeBuildOptionSetTestStateAction: + +Build Option Set Test State Action +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies the test state for a set of test programs with +an optional reason. All explicit attributes shall be specified. The explicit +attributes for this type are: + +reason + The attribute value shall be an optional string. If the value is present, + then it shall be the reason for the test state definition. + +state + The attribute value shall be a :ref:`SpecTypeBuildTestState`. It shall be + the test state for the associated list of tests. + +tests + The attribute value shall be a list of strings. It shall be the list of + test program names associated with the test state. The names shall + correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType` or + :ref:`SpecTypeBuildAdaTestProgramItemType` item. Due to the processing + order of items, there is no way to check if a specified test program name + is valid. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeBuildOptionValue: + +Build Option Value +^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a boolean. + +* The value may be an integer number. + +* The value may be a list. Each list element shall be a string. + +* There may be no value (null). + +* The value may be a string. + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionAction` + +* :ref:`SpecTypeBuildOptionDefaultValue` + +.. _SpecTypeBuildSource: + +Build Source +^^^^^^^^^^^^ + +The value shall be a string. It shall be a source file. The path to a source +file shall be relative to the directory of the :file:`wscript`. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildBSPItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildObjectsItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildTarget: + +Build Target +^^^^^^^^^^^^ + +The value shall be a string. It shall be the target file path. The path to the +target file shall be relative to the directory of the :file:`wscript`. The +target file is located in the build tree. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildConfigurationFileItemType` + +* :ref:`SpecTypeBuildConfigurationHeaderItemType` + +* :ref:`SpecTypeBuildLibraryItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildStartFileItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildTestState: + +Build Test State +^^^^^^^^^^^^^^^^ + +The value shall be a string. This string defines a test state. The value shall +be an element of + +* "``benchmark``", + +* "``exclude``", + +* "``expected-fail``", + +* "``indeterminate``", and + +* "``user-input``". + +This type is used by the following types: + +* :ref:`SpecTypeBuildOptionSetTestStateAction` + +.. _SpecTypeBuildUseAfterDirective: + +Build Use After Directive +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an internal static library identifier. +The library is used to link programs referenced by this item, e.g. ``z`` for +``libz.a``. The library is placed after the use items of the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeBuildUseBeforeDirective: + +Build Use Before Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be an internal static library identifier. +The library is used to link programs referenced by this item, e.g. ``z`` for +``libz.a``. The library is placed before the use items of the build item +context. + +This type is used by the following types: + +* :ref:`SpecTypeBuildAdaTestProgramItemType` + +* :ref:`SpecTypeBuildGroupItemType` + +* :ref:`SpecTypeBuildScriptItemType` + +* :ref:`SpecTypeBuildTestProgramItemType` + +.. _SpecTypeConstraintLinkRole: + +Constraint Link Role +^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``constraint``. It defines the constraint role of links. The link +target shall be a constraint. + +.. _SpecTypeCopyright: + +Copyright +^^^^^^^^^ + +The value shall be a string. It shall be a copyright statement of a copyright +holder of the specification item. The value + +* shall match with the regular expression + "``^\s*Copyright\s+\(C\)\s+[0-9]+,\s*[0-9]+\s+.+\s*$``", + +* or, shall match with the regular expression + "``^\s*Copyright\s+\(C\)\s+[0-9]+\s+.+\s*$``", + +* or, shall match with the regular expression + "``^\s*Copyright\s+\(C\)\s+.+\s*$``". + +This type is used by the following types: + +* :ref:`SpecTypeRootItemType` + +.. _SpecTypeEnabledByExpression: + +Enabled-By Expression +^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be an expression which defines under which +conditions the specification item or parts of it are enabled. The expression +is evaluated with the use of an *enabled set*. This is a set of strings which +indicate enabled features. + +A value of this type shall be of one of the following variants: + +* The value may be a boolean. This expression evaluates directly to the boolean + value. + +* The value may be a set of attributes. Each attribute defines an operator. + Exactly one of the explicit attributes shall be specified. The explicit + attributes for this type are: + + and + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeEnabledByExpression`. The *and* operator evaluates to the + *logical and* of the evaluation results of the expressions in the list. + + not + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. The + *not* operator evaluates to the *logical not* of the evaluation results + of the expression. + + or + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeEnabledByExpression`. The *or* operator evaluates to the + *logical or* of the evaluation results of the expressions in the list. + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeEnabledByExpression`. This list of expressions evaluates to the + *logical or* of the evaluation results of the expressions in the list. + +* The value may be a string. If the value is in the *enabled set*, this + expression evaluates to true, otherwise to false. + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementTransition` + +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildOptionDefaultValue` + +* :ref:`SpecTypeEnabledByExpression` + +* :ref:`SpecTypeInterfaceIncludeLinkRole` + +* :ref:`SpecTypeRootItemType` + +Please have a look at the following example: + +.. code-block:: yaml + + enabled-by: + and: + - RTEMS_NETWORKING + - not: RTEMS_SMP + +.. _SpecTypeExternalDocumentReference: + +External Document Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeExternalReference` through the ``type`` +attribute if the value is ``document``. It specifies a reference to a document. + +All explicit attributes shall be specified. The explicit attributes for this +type are: + +name + The attribute value shall be a string. It shall be the name of the + document. + +.. _SpecTypeExternalFileReference: + +External File Reference +^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeExternalReference` through the ``type`` +attribute if the value is ``file``. It specifies a reference to a file. + +All explicit attributes shall be specified. The explicit attributes for this +type are: + +hash + The attribute value shall be a :ref:`SpecTypeSHA256HashValue`. It shall be + the SHA256 hash value of the content of the referenced file. + +.. _SpecTypeExternalReference: + +External Reference +^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a reference to some object external to the +specification. All explicit attributes shall be specified. The explicit +attributes for this type are: + +identifier + The attribute value shall be a string. It shall be the type-specific + identifier of the referenced object. For *group* references use the Doxygen + group identifier. For *file* references use a file system path to the + file. + +type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the type of + the referenced object. + +This type is refined by the following types: + +* :ref:`SpecTypeExternalDocumentReference` + +* :ref:`SpecTypeExternalFileReference` + +* :ref:`SpecTypeGenericExternalReference` + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceUnspecifiedHeaderFileItemType` + +* :ref:`SpecTypeInterfaceUnspecifiedItemType` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRequirementValidationItemType` + +.. _SpecTypeFunctionImplementationLinkRole: + +Function Implementation Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``function-implementation``. It defines the function implementation +role of links. It is used to indicate that a +:ref:`SpecTypeFunctionalRequirementItemType` item specifies parts of the +function. + +.. _SpecTypeGenericExternalReference: + +Generic External Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``define`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``function`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``group`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``macro`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``url`` + +* :ref:`SpecTypeExternalReference` through the ``type`` attribute if the value + is ``variable`` + +It specifies a reference to an object of the specified type. + +.. _SpecTypeGlossaryMembershipLinkRole: + +Glossary Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``glossary-member``. It defines the glossary membership role of links. + +.. _SpecTypeIntegerOrString: + +Integer or String +^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be an integer number. + +* The value may be a string. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationValueOptionItemType` + +* :ref:`SpecTypeBuildOptionAction` + +.. _SpecTypeInterfaceBriefDescription: + +Interface Brief Description +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the brief description of the + interface. It should be a single sentence. The value shall not match with + the regular expression "``\n\n``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceHeaderFileItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + +.. _SpecTypeInterfaceCompoundDefinitionKind: + +Interface Compound Definition Kind +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies how the interface compound is +defined. It may be a typedef only, the struct or union only, or a typedef with +a struct or union definition. The value shall be an element of + +* "``struct-only``", + +* "``typedef-and-struct``", + +* "``typedef-and-union``", + +* "``typedef-only``", and + +* "``union-only``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +.. _SpecTypeInterfaceCompoundMemberCompound: + +Interface Compound Member Compound +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind`` + attribute if the value is ``struct`` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind`` + attribute if the value is ``union`` + +This set of attributes specifies an interface compound member compound. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +definition + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`. + +.. _SpecTypeInterfaceCompoundMemberDeclaration: + +Interface Compound Member Declaration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeInterfaceCompoundMemberDefinition` through +the ``kind`` attribute if the value is ``member``. This set of attributes +specifies an interface compound member declaration. All explicit attributes +shall be specified. The explicit attributes for this type are: + +definition + The attribute value shall be a string. It shall be the interface compound + member declaration. On the declaration a context-sensitive substitution of + item variables is performed. + +.. _SpecTypeInterfaceCompoundMemberDefinition: + +Interface Compound Member Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies an + interface compound member definition. All explicit attributes shall be + specified. The explicit attributes for this type are: + + brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + + description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + + kind + The attribute value shall be a string. It shall be the interface compound + member kind. + + name + The attribute value shall be a string. It shall be the interface compound + member name. + +* There may be no value (null). + +This type is refined by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberCompound` + +* :ref:`SpecTypeInterfaceCompoundMemberDeclaration` + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant` + +.. _SpecTypeInterfaceCompoundMemberDefinitionDirective: + +Interface Compound Member Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface compound member definition +directive. All explicit attributes shall be specified. The explicit attributes +for this type are: + +default + The attribute value shall be an + :ref:`SpecTypeInterfaceCompoundMemberDefinition`. The default definition + will be used if no variant-specific definition is enabled. + +variants + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberCompound` + +.. _SpecTypeInterfaceCompoundMemberDefinitionVariant: + +Interface Compound Member Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface compound member definition +variant. All explicit attributes shall be specified. The explicit attributes +for this type are: + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceCompoundMemberDefinition`. The definition will be + used if the expression defined by the ``enabled-by`` attribute evaluates to + true. In generated header files, the expression is evaluated by the C + preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective` + +.. _SpecTypeInterfaceDefinition: + +Interface Definition +^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the definition. On the definition a + context-sensitive substitution of item variables is performed. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceDefinitionDirective` + +* :ref:`SpecTypeInterfaceDefinitionVariant` + +.. _SpecTypeInterfaceDefinitionDirective: + +Interface Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface definition directive. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +default + The attribute value shall be an :ref:`SpecTypeInterfaceDefinition`. The + default definition will be used if no variant-specific definition is + enabled. + +variants + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +.. _SpecTypeInterfaceDefinitionVariant: + +Interface Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface definition variant. All explicit +attributes shall be specified. The explicit attributes for this type are: + +definition + The attribute value shall be an :ref:`SpecTypeInterfaceDefinition`. The + definition will be used if the expression defined by the ``enabled-by`` + attribute evaluates to true. In generated header files, the expression is + evaluated by the C preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceDefinitionDirective` + +.. _SpecTypeInterfaceDescription: + +Interface Description +^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the description of the interface. The + description should be short and concentrate on the average case. All special + cases, usage notes, constraints, error conditions, configuration + dependencies, references, etc. should be described in the + :ref:`SpecTypeInterfaceNotes`. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceCompoundMemberDefinition` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeInterfaceParameter` + +* :ref:`SpecTypeInterfaceReturnValue` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBitsDefinition` + +* :ref:`SpecTypeRegisterBlockItemType` + +* :ref:`SpecTypeRegisterDefinition` + +.. _SpecTypeInterfaceEnabledByExpression: + +Interface Enabled-By Expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be an expression which defines under which +conditions an interface definition is enabled. In generated header files, the +expression is evaluated by the C preprocessor. + +A value of this type shall be of one of the following variants: + +* The value may be a boolean. It is converted to 0 or 1. It defines a symbol + in the expression. + +* The value may be a set of attributes. Each attribute defines an operator. + Exactly one of the explicit attributes shall be specified. The explicit + attributes for this type are: + + and + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. The *and* operator defines a + *logical and* of the expressions in the list. + + not + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. The *not* operator defines a + *logical not* of the expression. + + or + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. The *or* operator defines a + *logical or* of the expressions in the list. + +* The value may be a list. Each list element shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. It defines a *logical or* of the + expressions in the list. + +* The value may be a string. It defines a symbol in the expression. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant` + +* :ref:`SpecTypeInterfaceDefinitionVariant` + +* :ref:`SpecTypeInterfaceEnabledByExpression` + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + +.. _SpecTypeInterfaceEnumDefinitionKind: + +Interface Enum Definition Kind +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies how the enum is defined. It may be a +typedef only, the enum only, or a typedef with an enum definition. The value +shall be an element of + +* "``enum-only``", + +* "``typedef-and-enum``", and + +* "``typedef-only``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceEnumItemType` + +.. _SpecTypeInterfaceEnumeratorLinkRole: + +Interface Enumerator Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-enumerator``. It defines the interface enumerator role of +links. + +.. _SpecTypeInterfaceFunctionLinkRole: + +Interface Function Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-function``. It defines the interface function role of +links. It is used to indicate that a :ref:`SpecTypeActionRequirementItemType` +item specifies functional requirements of an +:ref:`SpecTypeInterfaceFunctionOrMacroItemType` item. + +.. _SpecTypeInterfaceFunctionOrMacroDefinition: + +Interface Function or Macro Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies a + function definition. All explicit attributes shall be specified. The explicit + attributes for this type are: + + attributes + The attribute value shall be an optional string. If the value is present, + then it shall be the function attributes. On the attributes a + context-sensitive substitution of item variables is performed. A + function attribute is for example the indication that the function does + not return to the caller. + + body + The attribute value shall be an optional string. If the value is present, + then it shall be the definition of a static inline function. On the + function definition a context-sensitive substitution of item variables is + performed. If no value is present, then the function is declared as an + external function. + + params + The attribute value shall be a list of strings. It shall be the list of + parameter declarations of the function. On the function parameter + declarations a context-sensitive substitution of item variables is + performed. + + return + The attribute value shall be an optional string. If the value is present, + then it shall be the function return type. On the return type a + context-sensitive substitution of item variables is performed. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective` + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant` + +.. _SpecTypeInterfaceFunctionOrMacroDefinitionDirective: + +Interface Function or Macro Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function or macro definition directive. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +default + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The default definition + will be used if no variant-specific definition is enabled. + +variants + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +.. _SpecTypeInterfaceFunctionOrMacroDefinitionVariant: + +Interface Function or Macro Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a function or macro definition variant. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +definition + The attribute value shall be an + :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The definition will be + used if the expression defined by the ``enabled-by`` attribute evaluates to + true. In generated header files, the expression is evaluated by the C + preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective` + +.. _SpecTypeInterfaceGroupIdentifier: + +Interface Group Identifier +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be the identifier of the interface group. +The value shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeInterfaceGroupMembershipLinkRole: + +Interface Group Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-ingroup``. It defines the interface group membership role +of links. + +.. _SpecTypeInterfaceHiddenGroupMembershipLinkRole: + +Interface Hidden Group Membership Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-ingroup-hidden``. It defines the interface hidden group +membership role of links. This role may be used to make an interface a group +member and hide this relationship in the documentation. An example is an +optimized macro implementation of a directive which has the same name as the +corresponding directive. + +.. _SpecTypeInterfaceIncludeLinkRole: + +Interface Include Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-include``. It defines the interface include role of links +and is used to indicate that an interface container includes another interface +container. For example, one header file includes another header file. All +explicit attributes shall be specified. The explicit attributes for this type +are: + +enabled-by + The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It + shall define under which conditions the interface container is included. + +.. _SpecTypeInterfaceNotes: + +Interface Notes +^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the notes for the interface. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeInterfaceCompoundItemType` + +* :ref:`SpecTypeInterfaceDefineItemType` + +* :ref:`SpecTypeInterfaceEnumeratorItemType` + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +* :ref:`SpecTypeInterfaceVariableItemType` + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeInterfaceParameter: + +Interface Parameter +^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface parameter. All explicit +attributes shall be specified. The explicit attributes for this type are: + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +dir + The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`. + +name + The attribute value shall be a string. It shall be the interface parameter + name. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +.. _SpecTypeInterfaceParameterDirection: + +Interface Parameter Direction +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It specifies the interface parameter direction. + The value shall be an element of + + * "``in``", + + * "``out``", and + + * "``inout``". + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceParameter` + +* :ref:`SpecTypeTestRunParameter` + +.. _SpecTypeInterfacePlacementLinkRole: + +Interface Placement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-placement``. It defines the interface placement role of +links. It is used to indicate that an interface definition is placed into an +interface container, for example a header file. + +.. _SpecTypeInterfaceReturnDirective: + +Interface Return Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies an + interface return. All explicit attributes shall be specified. The explicit + attributes for this type are: + + return + The attribute value shall be an optional string. It shall describe the + interface return for unspecified return values. + + return-values + The attribute value shall be a list. Each list element shall be an + :ref:`SpecTypeInterfaceReturnValue`. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceFunctionOrMacroItemType` + +* :ref:`SpecTypeInterfaceTypedefItemType` + +.. _SpecTypeInterfaceReturnValue: + +Interface Return Value +^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an interface return value. All explicit +attributes shall be specified. The explicit attributes for this type are: + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +value + The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. It + shall be the described interface return value. + +This type is used by the following types: + +* :ref:`SpecTypeInterfaceReturnDirective` + +.. _SpecTypeInterfaceTargetLinkRole: + +Interface Target Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``interface-target``. It defines the interface target role of links. +It is used for interface forward declarations. + +.. _SpecTypeLink: + +Link +^^^^ + +This set of attributes specifies a link from one specification item to another +specification item. The links in a list are ordered. The first link in the +list is processed first. All explicit attributes shall be specified. The +explicit attributes for this type are: + +role + The attribute value shall be a :ref:`SpecTypeName`. It shall be the role of + the link. + +uid + The attribute value shall be an :ref:`SpecTypeUID`. It shall be the + absolute or relative UID of the link target item. + +This type is refined by the following types: + +* :ref:`SpecTypeBuildDependencyConditionalLinkRole` + +* :ref:`SpecTypeBuildDependencyLinkRole` + +* :ref:`SpecTypeConstraintLinkRole` + +* :ref:`SpecTypeFunctionImplementationLinkRole` + +* :ref:`SpecTypeGlossaryMembershipLinkRole` + +* :ref:`SpecTypeInterfaceEnumeratorLinkRole` + +* :ref:`SpecTypeInterfaceFunctionLinkRole` + +* :ref:`SpecTypeInterfaceGroupMembershipLinkRole` + +* :ref:`SpecTypeInterfaceHiddenGroupMembershipLinkRole` + +* :ref:`SpecTypeInterfaceIncludeLinkRole` + +* :ref:`SpecTypeInterfacePlacementLinkRole` + +* :ref:`SpecTypeInterfaceTargetLinkRole` + +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + +* :ref:`SpecTypePlacementOrderLinkRole` + +* :ref:`SpecTypeProxyMemberLinkRole` + +* :ref:`SpecTypeRegisterBlockIncludeRole` + +* :ref:`SpecTypeRequirementRefinementLinkRole` + +* :ref:`SpecTypeRequirementValidationLinkRole` + +* :ref:`SpecTypeRuntimeMeasurementRequestLinkRole` + +* :ref:`SpecTypeSpecificationMemberLinkRole` + +* :ref:`SpecTypeSpecificationRefinementLinkRole` + +* :ref:`SpecTypeUnitTestLinkRole` + +This type is used by the following types: + +* :ref:`SpecTypeRootItemType` + +* :ref:`SpecTypeTestCaseAction` + +* :ref:`SpecTypeTestCaseCheck` + +.. _SpecTypeName: + +Name +^^^^ + +The value shall be a string. A string is a valid name if it matches with the +``^([a-z][a-z0-9-]*|SPDX-License-Identifier)$`` regular expression. + +This type is used by the following types: + +* :ref:`SpecTypeApplicationConfigurationOptionItemType` + +* :ref:`SpecTypeBuildItemType` + +* :ref:`SpecTypeExternalReference` + +* :ref:`SpecTypeFunctionalRequirementItemType` + +* :ref:`SpecTypeGlossaryItemType` + +* :ref:`SpecTypeInterfaceItemType` + +* :ref:`SpecTypeLink` + +* :ref:`SpecTypeNonFunctionalRequirementItemType` + +* :ref:`SpecTypeRegisterDefinition` + +* :ref:`SpecTypeRequirementItemType` + +* :ref:`SpecTypeRequirementValidationItemType` + +* :ref:`SpecTypeRootItemType` + +* :ref:`SpecTypeRuntimeMeasurementParameterSet` + +* :ref:`SpecTypeRuntimePerformanceParameterSet` + +* :ref:`SpecTypeSpecificationAttributeValue` + +* :ref:`SpecTypeSpecificationExplicitAttributes` + +* :ref:`SpecTypeSpecificationGenericAttributes` + +* :ref:`SpecTypeSpecificationItemType` + +* :ref:`SpecTypeSpecificationList` + +* :ref:`SpecTypeSpecificationRefinementLinkRole` + +.. _SpecTypeOptionalFloatingPointNumber: + +Optional Floating-Point Number +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a floating-point number. + +* There may be no value (null). + +.. _SpecTypeOptionalInteger: + +Optional Integer +^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be an integer number. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeOptionalString: + +Optional String +^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. + +.. _SpecTypePerformanceRuntimeLimitsLinkRole: + +Performance Runtime Limits Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``performance-runtime-limits``. It defines the performance runtime +limits role of links. All explicit attributes shall be specified. The explicit +attributes for this type are: + +limits + The attribute value shall be a + :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`. + +.. _SpecTypePlacementOrderLinkRole: + +Placement Order Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``placement-order``. This link role defines the placement order of +items in a container item (for example an interface function in a header file +or a documentation section). + +.. _SpecTypeProxyMemberLinkRole: + +Proxy Member Link Role +^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``proxy-member``. It defines the proxy member role of links. Items +may use this role to link to :ref:`SpecTypeProxyItemTypes` items. + +.. _SpecTypeRegisterBitsDefinition: + +Register Bits Definition +^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies a + register bit field. Single bits are bit fields with a width of one. All + explicit attributes shall be specified. The explicit attributes for this type + are: + + brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + + description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + + name + The attribute value shall be a string. It shall be the name of the + register bit field. + + properties + The attribute value shall be a list of strings. It shall be the list of + bit field properties. Properties are for example if the bit field can be + read or written, or an access has side-effects such as clearing a status. + + start + The attribute value shall be an integer number. It shall be the start bit + of the bit field. Bit ``0`` is the least-significant bit. + + width + The attribute value shall be an integer number. It shall be the width in + bits of the bit field. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBitsDefinitionDirective` + +* :ref:`SpecTypeRegisterBitsDefinitionVariant` + +.. _SpecTypeRegisterBitsDefinitionDirective: + +Register Bits Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register bits directive. All explicit +attributes shall be specified. The explicit attributes for this type are: + +default + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinition`. The default definition will be used + if no variant-specific definition is enabled. + +variants + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterDefinition` + +.. _SpecTypeRegisterBitsDefinitionVariant: + +Register Bits Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register bits variant. All explicit +attributes shall be specified. The explicit attributes for this type are: + +definition + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinition`. The definition will be used if the + expression defined by the ``enabled-by`` attribute evaluates to true. In + generated header files, the expression is evaluated by the C preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBitsDefinitionDirective` + +.. _SpecTypeRegisterBlockIncludeRole: + +Register Block Include Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``register-block-include``. It defines the register block include role +of links. Links of this role are used to build register blocks using other +register blocks. All explicit attributes shall be specified. The explicit +attributes for this type are: + +name + The attribute value shall be a string. It shall be a name to identify the + included register block within the item. The name shall be unique within + the scope of the item links of this role and the + :ref:`SpecTypeRegisterList`. + +.. _SpecTypeRegisterBlockMemberDefinition: + +Register Block Member Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies a + register block member definition. All explicit attributes shall be specified. + The explicit attributes for this type are: + + count + The attribute value shall be an integer number. It shall be the count of + registers of the register block member. + + name + The attribute value shall be a :ref:`SpecTypeRegisterName`. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +* :ref:`SpecTypeRegisterBlockMemberDefinitionVariant` + +.. _SpecTypeRegisterBlockMemberDefinitionDirective: + +Register Block Member Definition Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition directive. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +default + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. The default definition will + be used if no variant-specific definition is enabled. + +offset + The attribute value shall be an integer number. It shall be the address of + the register block member relative to the base address of the register + block. + +variants + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBlockMemberDefinitionVariant`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterBlockMemberDefinitionVariant: + +Register Block Member Definition Variant +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register block member definition variant. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +definition + The attribute value shall be a + :ref:`SpecTypeRegisterBlockMemberDefinition`. The definition will be used + if the expression defined by the ``enabled-by`` attribute evaluates to + true. In generated header files, the expression is evaluated by the C + preprocessor. + +enabled-by + The attribute value shall be an + :ref:`SpecTypeInterfaceEnabledByExpression`. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinitionDirective` + +.. _SpecTypeRegisterDefinition: + +Register Definition +^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a register. All explicit attributes shall be +specified. The explicit attributes for this type are: + +bits + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeRegisterBitsDefinitionDirective`. + +brief + The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`. + +description + The attribute value shall be an :ref:`SpecTypeInterfaceDescription`. + +name + The attribute value shall be a string. It shall be the name to identify the + register definition. The name shall be unique within the scope of the + :ref:`SpecTypeRegisterBlockIncludeRole` links of the item and the + :ref:`SpecTypeRegisterList`. + +width + The attribute value shall be an integer number. It shall be the width of + the register in bits. + +In addition to the explicit attributes, generic attributes may be specified. +Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value +may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockItemType` + +.. _SpecTypeRegisterName: + +Register Name +^^^^^^^^^^^^^ + +The value shall be a string. The name consists either of an identifier, or an +identifier and an alias. The identifier and alias are separated by a colon +(``:``). The identifier shall match with the name of a register definition of +the item (see :ref:`SpecTypeRegisterDefinition`) or the name of a register +block include of the item (see :ref:`SpecTypeRegisterBlockIncludeRole`). If no +alias is specified, then the identifier is used for the register block member +name, otherwise the alias is used. If the register block member names are not +unique within the item, then a postfix number is appended to the names. The +number starts with zero for each set of names. The value shall match with the +regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*(:[a-zA-Z_][a-zA-Z0-9_]*)?$``". + +This type is used by the following types: + +* :ref:`SpecTypeRegisterBlockMemberDefinition` + +.. _SpecTypeRequirementDesignGroupIdentifier: + +Requirement Design Group Identifier +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* There may be no value (null). + +* The value may be a string. It shall be the identifier of the requirement + design group. The value shall match with the regular expression + "``^[a-zA-Z0-9_]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeDesignGroupRequirementItemType` + +.. _SpecTypeRequirementRefinementLinkRole: + +Requirement Refinement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``requirement-refinement``. It defines the requirement refinement role +of links. + +.. _SpecTypeRequirementText: + +Requirement Text +^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall state a requirement or constraint. The +text should not use one of the following words or phrases: + +* 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 + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementState` + +* :ref:`SpecTypeApplicationConfigurationGroupItemType` + +* :ref:`SpecTypeConstraintItemType` + +* :ref:`SpecTypeInterfaceGroupItemType` + +* :ref:`SpecTypeRequirementItemType` + +.. _SpecTypeRequirementValidationLinkRole: + +Requirement Validation Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``validation``. It defines the requirement validation role of links. + +.. _SpecTypeRuntimeMeasurementEnvironmentName: + +Runtime Measurement Environment Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the runtime measurement environment +name. The value + +* shall be an element of + + * "``FullCache``", + + * "``HotCache``", and + + * "``DirtyCache``", + +* or, shall match with the regular expression "``^Load/[1-9][0-9]*$``". + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` + +.. _SpecTypeRuntimeMeasurementEnvironmentTable: + +Runtime Measurement Environment Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes provides runtime performance limits for a set of runtime +measurement environments. Generic attributes may be specified. Each generic +attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentName`. Each +generic attribute value shall be a :ref:`SpecTypeRuntimeMeasurementValueTable`. + +This type is used by the following types: + +* :ref:`SpecTypePerformanceRuntimeLimitsLinkRole` + +.. _SpecTypeRuntimeMeasurementParameterSet: + +Runtime Measurement Parameter Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines parameters of the runtime measurement test case. +All explicit attributes shall be specified. The explicit attributes for this +type are: + +sample-count + The attribute value shall be an integer number. It shall be the sample + count of the runtime measurement context. + +In addition to the explicit attributes, generic attributes may be specified. +Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value +may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +.. _SpecTypeRuntimeMeasurementRequestLinkRole: + +Runtime Measurement Request Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``runtime-measurement-request``. It defines the runtime measurement +request role of links. The link target shall be a +:ref:`SpecTypeRuntimeMeasurementTestItemType` item. + +.. _SpecTypeRuntimeMeasurementValueKind: + +Runtime Measurement Value Kind +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It specifies the kind of a runtime measurement +value. The value shall be an element of + +* "``max-lower-bound``", + +* "``max-upper-bound``", + +* "``mean-lower-bound``", + +* "``mean-upper-bound``", + +* "``median-lower-bound``", + +* "``median-upper-bound``", + +* "``min-lower-bound``", and + +* "``min-upper-bound``". + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementValueTable` + +.. _SpecTypeRuntimeMeasurementValueTable: + +Runtime Measurement Value Table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes provides a set of runtime measurement values each of a +specified kind. The unit of the values shall be one second. Generic attributes +may be specified. Each generic attribute key shall be a +:ref:`SpecTypeRuntimeMeasurementValueKind`. Each generic attribute value shall +be a floating-point number. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable` + +.. _SpecTypeRuntimePerformanceParameterSet: + +Runtime Performance Parameter Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes defines parameters of the runtime performance +requirement. Generic attributes may be specified. Each generic attribute key +shall be a :ref:`SpecTypeName`. The attribute value may have any type. + +This type is used by the following types: + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +.. _SpecTypeSHA256HashValue: + +SHA256 Hash Value +^^^^^^^^^^^^^^^^^ + +The value shall be a string. It shall be a SHA256 hash value encoded in +base64url. The value shall match with the regular expression +"``^[A-Za-z0-9+_=-]{44}$``". + +This type is used by the following types: + +* :ref:`SpecTypeExternalFileReference` + +.. _SpecTypeSPDXLicenseIdentifier: + +SPDX License Identifier +^^^^^^^^^^^^^^^^^^^^^^^ + +The value shall be a string. It defines the license of the item expressed +though an SPDX License Identifier. The value + +* shall be equal to "``CC-BY-SA-4.0 OR BSD-2-Clause``", + +* or, shall be equal to "``BSD-2-Clause``", + +* or, shall be equal to "``CC-BY-SA-4.0``". + +This type is used by the following types: + +* :ref:`SpecTypeRootItemType` + +.. _SpecTypeSpecificationAttributeSet: + +Specification Attribute Set +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a set of attributes. The following explicit +attributes are mandatory: + +* ``attributes`` + +* ``description`` + +* ``mandatory-attributes`` + +The explicit attributes for this type are: + +attributes + The attribute value shall be a + :ref:`SpecTypeSpecificationExplicitAttributes`. It shall specify the + explicit attributes of the attribute set. + +description + The attribute value shall be an optional string. It shall be the + description of the attribute set. + +generic-attributes + The attribute value shall be a + :ref:`SpecTypeSpecificationGenericAttributes`. It shall specify the generic + attributes of the attribute set. + +mandatory-attributes + The attribute value shall be a + :ref:`SpecTypeSpecificationMandatoryAttributes`. It shall specify the + mandatory attributes of the attribute set. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationAttributeValue: + +Specification Attribute Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an attribute value. All explicit attributes +shall be specified. The explicit attributes for this type are: + +description + The attribute value shall be an optional string. It shall be the + description of the attribute value. + +spec-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type of the attribute value. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationExplicitAttributes` + +.. _SpecTypeSpecificationBooleanValue: + +Specification Boolean Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This attribute set specifies a boolean value. Only the ``description`` +attribute is mandatory. The explicit attributes for this type are: + +assert + The attribute value shall be a boolean. This optional attribute defines the + value constraint of the specified boolean value. If the value of the + assert attribute is true, then the value of the specified boolean value + shall be true. If the value of the assert attribute is false, then the + value of the specified boolean value shall be false. In case the assert + attribute is not present, then the value of the specified boolean value may + be true or false. + +description + The attribute value shall be an optional string. It shall be the + description of the specified boolean value. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationExplicitAttributes: + +Specification Explicit Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generic attributes may be specified. Each generic attribute key shall be a +:ref:`SpecTypeName`. Each generic attribute value shall be a +:ref:`SpecTypeSpecificationAttributeValue`. Each generic attribute specifies an +explicit attribute of the attribute set. The key of the each generic attribute +defines the attribute key of the explicit attribute. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationFloatingPointAssert: + +Specification Floating-Point Assert +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be an expression which asserts that the +floating-point value of the specified attribute satisfies the required +constraints. + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. Each attribute defines an operator. + Exactly one of the explicit attributes shall be specified. The explicit + attributes for this type are: + + and + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationFloatingPointAssert`. The *and* operator + evaluates to the *logical and* of the evaluation results of the + expressions in the list. + + eq + The attribute value shall be a floating-point number. The *eq* operator + evaluates to true, if the value to check is equal to the value of this + attribute, otherwise to false. + + ge + The attribute value shall be a floating-point number. The *ge* operator + evaluates to true, if the value to check is greater than or equal to the + value of this attribute, otherwise to false. + + gt + The attribute value shall be a floating-point number. The *gt* operator + evaluates to true, if the value to check is greater than the value of + this attribute, otherwise to false. + + le + The attribute value shall be a floating-point number. The *le* operator + evaluates to true, if the value to check is less than or equal to the + value of this attribute, otherwise to false. + + lt + The attribute value shall be a floating-point number. The *lt* operator + evaluates to true, if the value to check is less than the value of this + attribute, otherwise to false. + + ne + The attribute value shall be a floating-point number. The *ne* operator + evaluates to true, if the value to check is not equal to the value of + this attribute, otherwise to false. + + not + The attribute value shall be a + :ref:`SpecTypeSpecificationFloatingPointAssert`. The *not* operator + evaluates to the *logical not* of the evaluation results of the + expression. + + or + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationFloatingPointAssert`. The *or* operator + evaluates to the *logical or* of the evaluation results of the + expressions in the list. + +* The value may be a list. Each list element shall be a + :ref:`SpecTypeSpecificationFloatingPointAssert`. This list of expressions + evaluates to the *logical or* of the evaluation results of the expressions in + the list. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationFloatingPointAssert` + +* :ref:`SpecTypeSpecificationFloatingPointValue` + +.. _SpecTypeSpecificationFloatingPointValue: + +Specification Floating-Point Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a floating-point value. Only the +``description`` attribute is mandatory. The explicit attributes for this type +are: + +assert + The attribute value shall be a + :ref:`SpecTypeSpecificationFloatingPointAssert`. This optional attribute + defines the value constraints of the specified floating-point value. In + case the assert attribute is not present, then the value of the specified + floating-point value may be every valid floating-point number. + +description + The attribute value shall be an optional string. It shall be the + description of the specified floating-point value. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationGenericAttributes: + +Specification Generic Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies generic attributes. Generic attributes are +attributes which are not explicitly specified by +:ref:`SpecTypeSpecificationExplicitAttributes`. They are restricted to uniform +attribute key and value types. All explicit attributes shall be specified. The +explicit attributes for this type are: + +description + The attribute value shall be an optional string. It shall be the + description of the generic attributes. + +key-spec-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type of the generic attribute keys. + +value-spec-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type of the generic attribute values. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationInformation: + +Specification Information +^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies attribute values. At least one of the explicit +attributes shall be specified. The explicit attributes for this type are: + +bool + The attribute value shall be a :ref:`SpecTypeSpecificationBooleanValue`. It + shall specify a boolean value. + +dict + The attribute value shall be a :ref:`SpecTypeSpecificationAttributeSet`. It + shall specify a set of attributes. + +float + The attribute value shall be a + :ref:`SpecTypeSpecificationFloatingPointValue`. It shall specify a + floating-point value. + +int + The attribute value shall be a :ref:`SpecTypeSpecificationIntegerValue`. It + shall specify an integer value. + +list + The attribute value shall be a :ref:`SpecTypeSpecificationList`. It shall + specify a list of attributes or values. + +none + The attribute shall have no value. It specifies that no value is required. + +str + The attribute value shall be a :ref:`SpecTypeSpecificationStringValue`. It + shall specify a string. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationItemType` + +.. _SpecTypeSpecificationIntegerAssert: + +Specification Integer Assert +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be an expression which asserts that the integer +value of the specified attribute satisfies the required constraints. + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. Each attribute defines an operator. + Exactly one of the explicit attributes shall be specified. The explicit + attributes for this type are: + + and + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationIntegerAssert`. The *and* operator evaluates + to the *logical and* of the evaluation results of the expressions in the + list. + + eq + The attribute value shall be an integer number. The *eq* operator + evaluates to true, if the value to check is equal to the value of this + attribute, otherwise to false. + + ge + The attribute value shall be an integer number. The *ge* operator + evaluates to true, if the value to check is greater than or equal to the + value of this attribute, otherwise to false. + + gt + The attribute value shall be an integer number. The *gt* operator + evaluates to true, if the value to check is greater than the value of + this attribute, otherwise to false. + + le + The attribute value shall be an integer number. The *le* operator + evaluates to true, if the value to check is less than or equal to the + value of this attribute, otherwise to false. + + lt + The attribute value shall be an integer number. The *lt* operator + evaluates to true, if the value to check is less than the value of this + attribute, otherwise to false. + + ne + The attribute value shall be an integer number. The *ne* operator + evaluates to true, if the value to check is not equal to the value of + this attribute, otherwise to false. + + not + The attribute value shall be a :ref:`SpecTypeSpecificationIntegerAssert`. + The *not* operator evaluates to the *logical not* of the evaluation + results of the expression. + + or + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationIntegerAssert`. The *or* operator evaluates to + the *logical or* of the evaluation results of the expressions in the + list. + +* The value may be a list. Each list element shall be a + :ref:`SpecTypeSpecificationIntegerAssert`. This list of expressions evaluates + to the *logical or* of the evaluation results of the expressions in the list. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationIntegerAssert` + +* :ref:`SpecTypeSpecificationIntegerValue` + +.. _SpecTypeSpecificationIntegerValue: + +Specification Integer Value +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies an integer value. Only the ``description`` +attribute is mandatory. The explicit attributes for this type are: + +assert + The attribute value shall be a :ref:`SpecTypeSpecificationIntegerAssert`. + This optional attribute defines the value constraints of the specified + integer value. In case the assert attribute is not present, then the value + of the specified integer value may be every valid integer number. + +description + The attribute value shall be an optional string. It shall be the + description of the specified integer value. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationList: + +Specification List +^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a list of attributes or values. All explicit +attributes shall be specified. The explicit attributes for this type are: + +description + The attribute value shall be an optional string. It shall be the + description of the list. + +spec-type + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type of elements of the list. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeSpecificationMandatoryAttributes: + +Specification Mandatory Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It defines which explicit attributes are mandatory. + +A value of this type shall be of one of the following variants: + +* The value may be a list. Each list element shall be a :ref:`SpecTypeName`. + The list defines the mandatory attributes through their key names. + +* The value may be a string. It defines how many explicit attributes are + mandatory. If `none` is used, then none of the explicit attributes is + mandatory, they are all optional. The value shall be an element of + + * "``all``", + + * "``at-least-one``", + + * "``at-most-one``", + + * "``exactly-one``", and + + * "``none``". + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationAttributeSet` + +.. _SpecTypeSpecificationMemberLinkRole: + +Specification Member Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``spec-member``. It defines the specification membership role of +links. + +.. _SpecTypeSpecificationRefinementLinkRole: + +Specification Refinement Link Role +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``spec-refinement``. It defines the specification refinement role of +links. All explicit attributes shall be specified. The explicit attributes for +this type are: + +spec-key + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type refinement attribute key of the specification + refinement. + +spec-value + The attribute value shall be a :ref:`SpecTypeName`. It shall be the + specification type refinement attribute value of the specification + refinement. + +.. _SpecTypeSpecificationStringAssert: + +Specification String Assert +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be an expression which asserts that the string of +the specified attribute satisfies the required constraints. + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. Each attribute defines an operator. + Exactly one of the explicit attributes shall be specified. The explicit + attributes for this type are: + + and + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationStringAssert`. The *and* operator evaluates to + the *logical and* of the evaluation results of the expressions in the + list. + + contains + The attribute value shall be a list of strings. The *contains* operator + evaluates to true, if the string to check converted to lower case with + all white space characters converted to a single space character contains + a string of the list of strings of this attribute, otherwise to false. + + eq + The attribute value shall be a string. The *eq* operator evaluates to + true, if the string to check is equal to the value of this attribute, + otherwise to false. + + ge + The attribute value shall be a string. The *ge* operator evaluates to + true, if the string to check is greater than or equal to the value of + this attribute, otherwise to false. + + gt + The attribute value shall be a string. The *gt* operator evaluates to + true, if the string to check is greater than the value of this attribute, + otherwise to false. + + in + The attribute value shall be a list of strings. The *in* operator + evaluates to true, if the string to check is contained in the list of + strings of this attribute, otherwise to false. + + le + The attribute value shall be a string. The *le* operator evaluates to + true, if the string to check is less than or equal to the value of this + attribute, otherwise to false. + + lt + The attribute value shall be a string. The *lt* operator evaluates to + true, if the string to check is less than the value of this attribute, + otherwise to false. + + ne + The attribute value shall be a string. The *ne* operator evaluates to + true, if the string to check is not equal to the value of this attribute, + otherwise to false. + + not + The attribute value shall be a :ref:`SpecTypeSpecificationStringAssert`. + The *not* operator evaluates to the *logical not* of the evaluation + results of the expression. + + or + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeSpecificationStringAssert`. The *or* operator evaluates to + the *logical or* of the evaluation results of the expressions in the + list. + + re + The attribute value shall be a string. The *re* operator evaluates to + true, if the string to check matches with the regular expression of this + attribute, otherwise to false. + + uid + The attribute shall have no value. The *uid* operator evaluates to true, + if the string is a valid UID, otherwise to false. + +* The value may be a list. Each list element shall be a + :ref:`SpecTypeSpecificationStringAssert`. This list of expressions evaluates + to the *logical or* of the evaluation results of the expressions in the list. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationStringAssert` + +* :ref:`SpecTypeSpecificationStringValue` + +.. _SpecTypeSpecificationStringValue: + +Specification String Value +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a string. Only the ``description`` attribute +is mandatory. The explicit attributes for this type are: + +assert + The attribute value shall be a :ref:`SpecTypeSpecificationStringAssert`. + This optional attribute defines the constraints of the specified string. + In case the assert attribute is not present, then the specified string may + be every valid string. + +description + The attribute value shall be an optional string. It shall be the + description of the specified string attribute. + +This type is used by the following types: + +* :ref:`SpecTypeSpecificationInformation` + +.. _SpecTypeTestCaseAction: + +Test Case Action +^^^^^^^^^^^^^^^^ + +This set of attributes specifies a test case action. All explicit attributes +shall be specified. The explicit attributes for this type are: + +action-brief + The attribute value shall be an optional string. It shall be the test case + action brief description. + +action-code + The attribute value shall be a string. It shall be the test case action + code. + +checks + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestCaseCheck`. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. The links should use the + :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the + :ref:`SpecTypeUnitTestLinkRole` for unit tests. + +This type is used by the following types: + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestCaseCheck: + +Test Case Check +^^^^^^^^^^^^^^^ + +This set of attributes specifies a test case check. All explicit attributes +shall be specified. The explicit attributes for this type are: + +brief + The attribute value shall be an optional string. It shall be the test case + check brief description. + +code + The attribute value shall be a string. It shall be the test case check + code. + +links + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeLink`. The links should use the + :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the + :ref:`SpecTypeUnitTestLinkRole` for unit tests. + +This type is used by the following types: + +* :ref:`SpecTypeTestCaseAction` + +.. _SpecTypeTestContextMember: + +Test Context Member +^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes defines an + action requirement test context member. All explicit attributes shall be + specified. The explicit attributes for this type are: + + brief + The attribute value shall be an optional string. It shall be the test + context member brief description. + + description + The attribute value shall be an optional string. It shall be the test + context member description. + + member + The attribute value shall be a string. It shall be the test context + member definition. It shall be a valid C structure member definition + without a trailing ``;``. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestHeader: + +Test Header +^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes specifies a test + header. In case a test header is specified, then instead of a test case a + test run function will be generated. The test run function will be declared + in the test header target file and defined in the test source target file. + The test run function can be used to compose test cases. The test header + file is not automatically included in the test source file. It should be + added to the includes or local includes of the test. All explicit attributes + shall be specified. The explicit attributes for this type are: + + code + The attribute value shall be an optional string. If the value is present, + then it shall be the test header code. The header code is placed at file + scope after the general test declarations and before the test run + function declaration. + + freestanding + The attribute value shall be a boolean. The value shall be ``true``, if + the test case is freestanding, otherwise ``false``. Freestanding test + cases are not statically registered. Instead the generated test runner + uses :c:func:`T_case_begin` and :c:func:`T_case_end`. + + includes + The attribute value shall be a list of strings. It shall be a list of + header files included by the header file via ``#include <...>``. + + local-includes + The attribute value shall be a list of strings. It shall be a list of + header files included by the header file via ``#include "..."``. + + run-params + The attribute value shall be a list. Each list element shall be a + :ref:`SpecTypeTestRunParameter`. + + target + The attribute value shall be a string. It shall be the path to the + generated test header file. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeTestRunParameter: + +Test Run Parameter +^^^^^^^^^^^^^^^^^^ + +This set of attributes specifies a parameter for the test run function. In case +this parameter is used in an :ref:`SpecTypeActionRequirementItemType` item, +then the parameter is also added as a member to the test context, see +:ref:`SpecTypeTestContextMember`. All explicit attributes shall be specified. +The explicit attributes for this type are: + +description + The attribute value shall be a string. It shall be the description of the + parameter. + +dir + The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`. + +name + The attribute value shall be a string. It shall be the parameter name. + +specifier + The attribute value shall be a string. It shall be the complete function + parameter specifier. Use ``${.:name}`` for the parameter name, for example + ``"int ${.:name}"``. + +This type is used by the following types: + +* :ref:`SpecTypeTestHeader` + +.. _SpecTypeTestSupportMethod: + +Test Support Method +^^^^^^^^^^^^^^^^^^^ + +A value of this type shall be of one of the following variants: + +* The value may be a set of attributes. This set of attributes defines an + action requirement test support method. All explicit attributes shall be + specified. The explicit attributes for this type are: + + brief + The attribute value shall be an optional string. It shall be the test + support method brief description. + + code + The attribute value shall be a string. It shall be the test support + method code. The code may use a local variable ``ctx`` which points to + the test context, see :ref:`SpecTypeTestContextMember`. + + description + The attribute value shall be an optional string. It shall be the test + support method description. + +* There may be no value (null). + +This type is used by the following types: + +* :ref:`SpecTypeActionRequirementItemType` + +* :ref:`SpecTypeRuntimeMeasurementTestItemType` + +* :ref:`SpecTypeRuntimePerformanceRequirementItemType` + +* :ref:`SpecTypeTestCaseItemType` + +.. _SpecTypeUID: + +UID +^^^ + +The value shall be a string. The string shall be a valid absolute or relative +item UID. + +This type is used by the following types: + +* :ref:`SpecTypeLink` + +.. _SpecTypeUnitTestLinkRole: + +Unit Test Link Role +^^^^^^^^^^^^^^^^^^^ + +This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the +value is ``unit-test``. It defines the unit test role of links. For unit tests +the link target should be the :ref:`SpecTypeInterfaceDomainItemType` containing +the software unit. All explicit attributes shall be specified. The explicit +attributes for this type are: + +name + The attribute value shall be a string. It shall be the name of the tested + software unit. diff --git a/eng/req/management.rst b/eng/req/management.rst new file mode 100644 index 0000000..4fb379c --- /dev/null +++ b/eng/req/management.rst @@ -0,0 +1,76 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +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>`. diff --git a/eng/req/req-for-req.rst b/eng/req/req-for-req.rst new file mode 100644 index 0000000..5631b7d --- /dev/null +++ b/eng/req/req-for-req.rst @@ -0,0 +1,406 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +Requirements for Requirements +============================= + +.. _ReqEngIdent: + +Identification +-------------- + +Each requirement shall have a unique identifier (UID). The question is in +which scope should it be unique? Ideally, it should be universally unique. +Therefore all UIDs used to link one specification item to another should use +relative UIDs. This ensures that the RTEMS requirements can be referenced +easily in larger systems though a system-specific prefix. The standard +ECSS-E-ST-10-06C recommends in section 8.2.6 that the identifier should reflect +the type of the requirement and the life profile situation. Other standards +may have other recommendations. To avoid a bias of RTEMS in the direction of +ECSS, this recommendation will not be followed. + +The *absolute UID* of a specification item (for example a requirement) is +defined by a leading ``/`` and the path of directories from the specification +base directory to the file of the item separated by ``/`` characters and the +file name without the ``.yml`` extension. For example, a specification item +contained in the file :file:`build/cpukit/librtemscpu.yml` inside a +:file:`spec` directory has the absolute UID of ``/build/cpukit/librtemscpu``. + +The *relative UID* to a specification item is defined by the path of +directories from the file containing the source specification item to the file +of the destination item separated by ``/`` characters and the file name of the +destination item without the ``.yml`` extension. For example the relative UID +from ``/build/bsps/sparc/leon3/grp`` to ``/build/bsps/bspopts`` is +``../../bspopts``. + +Basically, the valid characters of an UID are determined by the file system +storing the item files. By convention, UID characters shall be restricted to +the following set defined by the regular expression ``[a-zA-Z0-9_-]+``. Use +``-`` as a separator inside an UID part. + +In documents the URL-like prefix ``spec:`` shall be used to indicated +specification item UIDs. + +The UID scheme for RTEMS requirements shall be component based. For example, +the UID ``spec:/classic/task/create-err-invaddr`` may specify that the +:c:func:`rtems_task_create` directive shall return a status of +``RTEMS_INVALID_ADDRESS`` if the ``id`` parameter is ``NULL``. + +A initial requirement item hierarchy could be this: + +* build (building RTEMS BSPs and libraries) + +* acfg (application configuration groups) + + * opt (application configuration options) + +* classic + + * task + + * create-* (requirements for :c:func:`rtems_task_create`) + * delete-* (requirements for :c:func:`rtems_task_delete`) + * exit-* (requirements for :c:func:`rtems_task_exit`) + * getaff-* (requirements for :c:func:`rtems_task_get_affinity`) + * getpri-* (requirements for :c:func:`rtems_task_get_priority`) + * getsched-* (requirements for :c:func:`rtems_task_get_scheduler`) + * ident-* (requirements for :c:func:`rtems_task_ident`) + * issusp-* (requirements for :c:func:`rtems_task_is_suspended`) + * iter-* (requirements for :c:func:`rtems_task_iterate`) + * mode-* (requirements for :c:func:`rtems_task_mode`) + * restart-* (requirements for :c:func:`rtems_task_restart`) + * resume* (requirements for :c:func:`rtems_task_resume`) + * self* (requirements for :c:func:`rtems_task_self`) + * setaff-* (requirements for :c:func:`rtems_task_set_affinity`) + * setpri-* (requirements for :c:func:`rtems_task_set_priority`) + * setsched* (requirements for :c:func:`rtems_task_set_scheduler`) + * start-* (requirements for :c:func:`rtems_task_start`) + * susp-* (requirements for :c:func:`rtems_task_suspend`) + * wkafter-* (requirements for :c:func:`rtems_task_wake_after`) + * wkwhen-* (requirements for :c:func:`rtems_task_wake_when`) + + * sema + + * ... + +* posix + +* ... + +A more detailed naming scheme and guidelines should be established. We have to +find the right balance between the length of UIDs and self-descriptive UIDs. A +clear scheme for all Classic API managers may help to keep the UIDs short and +descriptive. + +The specification of the validation of requirements should be maintained also +by specification items. For each requirement directory there should be a +validation subdirectory named *test*, e.g. :file:`spec/classic/task/test`. A +test specification directory may contain also validations by analysis, by +inspection, and by design, see :ref:`ReqEngValidation`. + +Level of Requirements +--------------------- + +The level of a requirement shall be expressed with one of the verbal forms +listed below and nothing else. The level of requirements are derived from RFC +2119 :cite:`RFC2119` and ECSS-E-ST-10-06C :cite:`ECSS_E_ST_10_06C`. + +Absolute Requirements +~~~~~~~~~~~~~~~~~~~~~ + +Absolute requirements shall be expressed with the verbal form *shall* and no +other terms. + +Absolute Prohibitions +~~~~~~~~~~~~~~~~~~~~~ + +Absolute prohibitions shall be expressed with the verbal form *shall not* and +no other terms. + +.. warning:: + + Absolute prohibitions may be difficult to validate. They should not be + used. + +Recommendations +~~~~~~~~~~~~~~~ + +Recommendations shall be expressed with the verbal forms *should* and +*should not* and no other terms with guidance from RFC 2119: + + SHOULD This word, or the adjective "RECOMMENDED", mean that there + may exist valid reasons in particular circumstances to ignore a + particular item, but the full implications must be understood and + carefully weighed before choosing a different course. + + SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that + there may exist valid reasons in particular circumstances when the + particular behavior is acceptable or even useful, but the full + implications should be understood and the case carefully weighed + before implementing any behavior described with this label. + +Permissions +~~~~~~~~~~~ + +Permissions shall be expressed with the verbal form *may* and no other terms +with guidance from RFC 2119: + + MAY This word, or the adjective "OPTIONAL", mean that an item is + truly optional. One vendor may choose to include the item because a + particular marketplace requires it or because the vendor feels that + it enhances the product while another vendor may omit the same item. + An implementation which does not include a particular option MUST be + prepared to interoperate with another implementation which does + include the option, though perhaps with reduced functionality. In the + same vein an implementation which does include a particular option + MUST be prepared to interoperate with another implementation which + does not include the option (except, of course, for the feature the + option provides.) + +Possibilities and Capabilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Possibilities and capabilities shall be expressed with the verbal form *can* +and no other terms. + +.. _ReqEngSyntax: + +Syntax +------ + +Use the Easy Approach to Requirements Syntax (:term:`EARS`) to formulate +requirements. A recommended reading list to get familiar with this approach is +:cite:`Mavin:2009:EARS`, :cite:`Mavin:2010:BigEars`, +:cite:`Mavin:2016:LLEARS`, and `Alisair Mavin's web site +<https://alistairmavin.com/ears/>`_. The patterns are: + +* Ubiquitous + + The <system name> shall <system response>. + +* Event-driven + + **When** <trigger>, the <system name> shall <system response>. + +* State-driven + + **While** <pre-condition>, the <system name> shall <system response>. + +* Unwanted behaviour + + **If** <trigger>, **then** the <system name> shall <system response>. + +* Optional + + **Where** <feature is included>, the <system name> shall <system response>. + +* Complex + + **Where** <feature 0 is included>, **where** <feature 1 is included>, ..., + **where** <feature *n* is included>, **while** <pre-condition 0>, **while** + <pre-condition 1>, ..., **while** <pre-condition *m*>, **when** <trigger>, + the <system name> shall <system response>. + + **Where** <feature 0 is included>, **where** <feature 1 is included>, ..., + **where** <feature *n* is included>, **while** <pre-condition 0>, **while** + <pre-condition 1>, ..., **while** <pre-condition *m*>, **if** <trigger>, + **then** the <system name> shall <system response>. + +The optional pattern should be only used for application configuration +options. The goal is to use the ``enabled-by`` attribute to enable or disable +requirements based on configuration parameters that define the RTEMS artefacts +used to build an application executable (header files, libraries, linker command +files). Such configuration parameters are for example the architecture, the +platform, CPU port options, and build configuration options (e.g. uniprocessor +vs. SMP). + +Wording Restrictions +-------------------- + +To prevent the expression of imprecise requirements, the following terms shall +not be used in requirement formulations: + +* "acceptable" +* "adequate" +* "almost always" +* "and/or" +* "appropriate" +* "approximately" +* "as far as possible" +* "as much as practicable" +* "best" +* "best possible" +* "easy" +* "efficient" +* "e.g." +* "enable" +* "enough" +* "etc." +* "few" +* "first rate" +* "flexible" +* "generally" +* "goal" +* "graceful" +* "great" +* "greatest" +* "ideally" +* "i.e." +* "if possible" +* "in most cases" +* "large" +* "many" +* "maximize" +* "minimize" +* "most" +* "multiple" +* "necessary" +* "numerous" +* "optimize" +* "ought to" +* "probably" +* "quick" +* "rapid" +* "reasonably" +* "relevant" +* "robust" +* "satisfactory" +* "several" +* "shall be included but not limited to" +* "simple" +* "small" +* "some" +* "state-of-the-art". +* "sufficient" +* "suitable" +* "support" +* "systematically" +* "transparent" +* "typical" +* "user-friendly" +* "usually" +* "versatile" +* "when necessary" + +For guidelines to avoid these terms see Table 11-2, "Some ambiguous terms to +avoid in requirements" in :cite:`Wiegers:2013:SR`. There should be some means +to enforce that these terms are not used, e.g. through a client-side pre-commit +Git hook, a server-side pre-receive Git hook, or some scripts run by special +build commands. + +Separate Requirements +--------------------- + +Requirements shall be stated separately. A bad example is: + +spec:/classic/task/create + The task create directive shall evaluate the parameters, allocate a task + object and initialize it. + +To make this a better example, it should be split into separate requirements: + +spec:/classic/task/create + When the task create directive is called with valid parameters and a free + task object exists, the task create directive shall assign the identifier of + an initialized task object to the ``id`` parameter and return the + ``RTEMS_SUCCESSFUL`` status. + +spec:/classic/task/create-err-toomany + If no free task objects exists, the task create directive shall return the + ``RTEMS_TOO_MANY`` status. + +spec:/classic/task/create-err-invaddr + If the ``id`` parameter is ``NULL``, the task create directive shall return the + ``RTEMS_INVALID_ADDRESS`` status. + +spec:/classic/task/create-err-invname + If the ``name`` parameter is invalid, the task create directive shall + return the ``RTEMS_INVALID_NAME`` status. + + ... + +Conflict Free Requirements +-------------------------- + +Requirements shall not be in conflict with each other inside a specification. +A bad example is: + +spec:/classic/sema/mtx-obtain-wait + When a mutex is not available, the mutex obtain directive shall enqueue the + calling thread on the wait queue of the mutex. + +spec:/classic/sema/mtx-obtain-err-unsat + If a mutex is not available, the mutex obtain directive shall return the + RTEMS_UNSATISFIED status. + +To resolve this conflict, a condition may be added: + +spec:/classic/sema/mtx-obtain-wait + When a mutex is not available and the RTEMS_WAIT option is set, the mutex + obtain directive shall enqueue the calling thread on the wait queue of the + mutex. + +spec:/classic/sema/mtx-obtain-err-unsat + If a mutex is not available, when the RTEMS_WAIT option is not set, the + mutex obtain directive shall return the RTEMS_UNSATISFIED status. + +Use of Project-Specific Terms and Abbreviations +----------------------------------------------- + +All project-specific terms and abbreviations used to formulate requirements +shall be defined in the project glossary. + +.. _ReqEngJustReq: + +Justification of Requirements +----------------------------- + +Each requirement shall have a rationale or justification recorded in a +dedicated section of the requirement file. See ``rationale`` attribute for +:ref:`ReqEngSpecificationItems`. + +.. _ReqEngValidation: + +Requirement Validation +---------------------- + +The validation of each :ref:`SpecTypeRequirementItemType` item shall be +accomplished by one or more specification items of the types +:ref:`SpecTypeTestCaseItemType` or :ref:`SpecTypeRequirementValidationItemType` +through a link from the validation item to the requirement item with the +:ref:`SpecTypeRequirementValidationLinkRole`. + +Validation by test is strongly recommended. The choice of any other validation +method shall be strongly justified. The requirements author is obligated to +provide the means to validate the requirement with detailed instructions. + +.. _ReqEngResAndPerf: + +Resources and Performance +------------------------- + +Normally, resource and performance requirements are formulated like this: + +* The resource U shall need less than V storage units. + +* The operation Y shall complete within X time units. + +Such statements are difficult to make for a software product like RTEMS which +runs on many different target platforms in various configurations. So, the +performance requirements of RTEMS shall be stated in terms of benchmarks. The +benchmarks are run on the project-specific target platform and configuration. +The results obtained by the benchmark runs are reported in a human readable +presentation. The application designer can then use the benchmark results to +determine if its system performance requirements are met. The benchmarks shall +be executed under different environment conditions, e.g. varying cache states +(dirty, empty, valid) and system bus load generated by other processors. The +application designer shall have the ability to add additional environment +conditions, e.g. system bus load by DMA engines or different system bus +arbitration schemes. + +To catch resource and performance regressions via test suite runs there shall be +a means to specify threshold values for the measured quantities. The threshold +values should be provided for each validation platform. How this can be done +and if the threshold values are maintained by the RTEMS Project is subject to +discussion. diff --git a/eng/req/tooling.rst b/eng/req/tooling.rst new file mode 100644 index 0000000..2853932 --- /dev/null +++ b/eng/req/tooling.rst @@ -0,0 +1,160 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +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: + +Best Available 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 could be extended to manage specifications in general. +The primary reason for a close consideration of Doorstop as the requirements +management tool for the RTEMS Project was its data format which allows a high +degree of customization. Doorstop uses a directed, acyclic graph (DAG) 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 which in the end turned out to be not enough to use Doorstop for the +RTEMS Project. + +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 would help 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.). + +After some initial work with Doorstop some issues surfaced +(`#471 <https://github.com/doorstop-dev/doorstop/issues/471>`_). +It turned out that Doorstop is not designed as a library and contains too much +policy. This results in a lack of flexibility required for the RTEMS Project. + +1. Its primary use case is requirements management. So, it has some standard + attributes useful in this domain, like derived, header, level, normative, + ref, reviewed, and text. However, we want to use it more generally for + specification items and these attributes make not always sense. Having them + in every item is just overhead and may cause confusion. + +2. The links cannot have custom attributes, e.g. role, enabled-by. With + link-specific attributes you could have multiple DAGs formed up by the same + set of items. + +3. Inside a document (directory) items are supposed to have a common type (set + of attributes). We would like to store at a hierarchy level also distinct + specializations. + +4. The verification of the items is quite limited. We need verification with + type-based rules. + +5. The UIDs in combination with the document hierarchy lead to duplication, + e.g. a/b/c/a-b-c-d.yml. You have the path (a/b/c) also in the file name + (a-b-c). You cannot have relative UIDs in links (e.g. ../parent-req) . The + specification items may contain multiple requirements, e.g. min/max + attributes. There is no way to identify them. + +6. The links are ordered by Doorstop alphabetically by UID. For some + applications, it would be better to use the order specified by the user. For + example, we want to use specification items for a new build system. Here it + is handy if you can express things like this: A is composed of B and C. + Build B before C. + +.. _ReqEngManagementTool: + +Custom Requirements Management Tool +----------------------------------- + +No requirements management tool was available that fits the need of the RTEMS +Qualification Project. The decision was to develop a custom requirements +management tool written in Python 3.6 or later. The design for it is heavily +inspired by Doorstop. diff --git a/eng/req/traceability.rst b/eng/req/traceability.rst new file mode 100644 index 0000000..99c4931 --- /dev/null +++ b/eng/req/traceability.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG + +.. _ReqEngTrace: + +Traceability of Specification Items +=================================== + +The standard ECSS-E-ST-10-06C demands that requirements shall be under +configuration management, backwards-traceable and forward-traceable +:cite:`ECSS_E_ST_10_06C`. 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. A custom tool needs to verify this. + +.. _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. A custom tool needs to verify this. 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 custom YAML files, see +:ref:`ReqEngSpecificationItems`. 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 +:term:`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. |