source: rtems-docs/eng/req/items.rst @ 4fddb23

Last change on this file since 4fddb23 was 4fddb23, checked in by Sebastian Huber <sebastian.huber@…>, on 10/04/22 at 06:26:27

eng: Add memory benachmark type refinement

Update #3715.

  • Property mode set to 100644
File size: 175.3 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2019, 2022 embedded brains GmbH (http://www.embedded-brains.de)
4
5.. This file is part of the RTEMS quality process and was automatically
6.. generated.  If you find something that needs to be fixed or
7.. worded better please post a report or patch to an RTEMS mailing list
8.. or raise a bug report:
9..
10.. https://www.rtems.org/bugs.html
11..
12.. For information on updating and regenerating please refer to the How-To
13.. section in the Software Requirements Engineering chapter of the
14.. RTEMS Software Engineering manual.  The manual is provided as a part of
15.. a release.  For development sources please refer to the online
16.. documentation at:
17..
18.. https://docs.rtems.org
19
20.. _ReqEngSpecificationItems:
21
22Specification Items
23===================
24
25.. _ReqEngSpecificationItemHierarchy:
26
27Specification Item Hierarchy
28----------------------------
29
30The specification item types have the following hierarchy:
31
32* :ref:`SpecTypeRootItemType`
33
34  * :ref:`SpecTypeBuildItemType`
35
36    * :ref:`SpecTypeBuildAdaTestProgramItemType`
37
38    * :ref:`SpecTypeBuildBSPItemType`
39
40    * :ref:`SpecTypeBuildConfigurationFileItemType`
41
42    * :ref:`SpecTypeBuildConfigurationHeaderItemType`
43
44    * :ref:`SpecTypeBuildGroupItemType`
45
46    * :ref:`SpecTypeBuildLibraryItemType`
47
48    * :ref:`SpecTypeBuildObjectsItemType`
49
50    * :ref:`SpecTypeBuildOptionItemType`
51
52    * :ref:`SpecTypeBuildScriptItemType`
53
54    * :ref:`SpecTypeBuildStartFileItemType`
55
56    * :ref:`SpecTypeBuildTestProgramItemType`
57
58  * :ref:`SpecTypeConstraintItemType`
59
60  * :ref:`SpecTypeGlossaryItemType`
61
62    * :ref:`SpecTypeGlossaryGroupItemType`
63
64    * :ref:`SpecTypeGlossaryTermItemType`
65
66  * :ref:`SpecTypeInterfaceItemType`
67
68    * :ref:`SpecTypeApplicationConfigurationGroupItemType`
69
70    * :ref:`SpecTypeApplicationConfigurationOptionItemType`
71
72      * :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType`
73
74      * :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType`
75
76      * :ref:`SpecTypeApplicationConfigurationValueOptionItemType`
77
78    * :ref:`SpecTypeInterfaceCompoundItemType`
79
80    * :ref:`SpecTypeInterfaceDefineItemType`
81
82    * :ref:`SpecTypeInterfaceDomainItemType`
83
84    * :ref:`SpecTypeInterfaceEnumItemType`
85
86    * :ref:`SpecTypeInterfaceEnumeratorItemType`
87
88    * :ref:`SpecTypeInterfaceForwardDeclarationItemType`
89
90    * :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
91
92    * :ref:`SpecTypeInterfaceGroupItemType`
93
94    * :ref:`SpecTypeInterfaceHeaderFileItemType`
95
96    * :ref:`SpecTypeInterfaceTypedefItemType`
97
98    * :ref:`SpecTypeInterfaceUnspecifiedItemType`
99
100    * :ref:`SpecTypeInterfaceVariableItemType`
101
102  * :ref:`SpecTypeRequirementItemType`
103
104    * :ref:`SpecTypeFunctionalRequirementItemType`
105
106      * :ref:`SpecTypeActionRequirementItemType`
107
108      * :ref:`SpecTypeGenericFunctionalRequirementItemType`
109
110    * :ref:`SpecTypeNonFunctionalRequirementItemType`
111
112      * :ref:`SpecTypeDesignGroupRequirementItemType`
113
114      * :ref:`SpecTypeGenericNonFunctionalRequirementItemType`
115
116      * :ref:`SpecTypeRuntimePerformanceRequirementItemType`
117
118  * :ref:`SpecTypeRequirementValidationItemType`
119
120    * :ref:`SpecTypeRequirementValidationMethod`
121
122  * :ref:`SpecTypeRuntimeMeasurementTestItemType`
123
124  * :ref:`SpecTypeSpecificationItemType`
125
126  * :ref:`SpecTypeTestCaseItemType`
127
128  * :ref:`SpecTypeTestPlatformItemType`
129
130  * :ref:`SpecTypeTestProcedureItemType`
131
132  * :ref:`SpecTypeTestSuiteItemType`
133
134.. _ReqEngSpecificationItemTypes:
135
136Specification Item Types
137------------------------
138
139.. _SpecTypeRootItemType:
140
141Root Item Type
142^^^^^^^^^^^^^^
143
144The technical specification of RTEMS will contain for example requirements,
145specializations of requirements, interface specifications, test suites, test
146cases, and requirement validations.  These things will be called *specification
147items* or just *items* if it is clear from the context.
148
149The specification items are stored in files in :term:`YAML` format with a
150defined set of key-value pairs called attributes.  Each attribute key name
151shall be a :ref:`SpecTypeName`.  In particular, key names which begin with an
152underscore (``_``) are reserved for internal use in tools.
153
154This is the root specification item type. All explicit attributes shall be
155specified. The explicit attributes for this type are:
156
157SPDX-License-Identifier
158    The attribute value shall be a :ref:`SpecTypeSPDXLicenseIdentifier`. It
159    shall be the license of the item.
160
161copyrights
162    The attribute value shall be a list. Each list element shall be a
163    :ref:`SpecTypeCopyright`. It shall be the list of copyright statements of
164    the item.
165
166enabled-by
167    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It
168    shall define the conditions under which the item is enabled.
169
170links
171    The attribute value shall be a list. Each list element shall be a
172    :ref:`SpecTypeLink`.
173
174type
175    The attribute value shall be a :ref:`SpecTypeName`. It shall be the item
176    type.  The selection of types and the level of detail depends on a
177    particular standard and product model.  We need enough flexibility to be in
178    line with ECSS-E-ST-10-06 and possible future applications of other
179    standards.  The item type may be refined further with additional
180    type-specific subtypes.
181
182This type is refined by the following types:
183
184* :ref:`SpecTypeBuildItemType`
185
186* :ref:`SpecTypeConstraintItemType`
187
188* :ref:`SpecTypeGlossaryItemType`
189
190* :ref:`SpecTypeInterfaceItemType`
191
192* :ref:`SpecTypeRequirementItemType`
193
194* :ref:`SpecTypeRequirementValidationItemType`
195
196* :ref:`SpecTypeRuntimeMeasurementTestItemType`
197
198* :ref:`SpecTypeSpecificationItemType`
199
200* :ref:`SpecTypeTestCaseItemType`
201
202* :ref:`SpecTypeTestPlatformItemType`
203
204* :ref:`SpecTypeTestProcedureItemType`
205
206* :ref:`SpecTypeTestSuiteItemType`
207
208.. _SpecTypeBuildItemType:
209
210Build Item Type
211^^^^^^^^^^^^^^^
212
213This type refines the :ref:`SpecTypeRootItemType` through the ``type``
214attribute if the value is ``build``. This set of attributes specifies a build
215item. All explicit attributes shall be specified. The explicit attributes for
216this type are:
217
218build-type
219    The attribute value shall be a :ref:`SpecTypeName`. It shall be the build
220    item type.
221
222This type is refined by the following types:
223
224* :ref:`SpecTypeBuildAdaTestProgramItemType`
225
226* :ref:`SpecTypeBuildBSPItemType`
227
228* :ref:`SpecTypeBuildConfigurationFileItemType`
229
230* :ref:`SpecTypeBuildConfigurationHeaderItemType`
231
232* :ref:`SpecTypeBuildGroupItemType`
233
234* :ref:`SpecTypeBuildLibraryItemType`
235
236* :ref:`SpecTypeBuildObjectsItemType`
237
238* :ref:`SpecTypeBuildOptionItemType`
239
240* :ref:`SpecTypeBuildScriptItemType`
241
242* :ref:`SpecTypeBuildStartFileItemType`
243
244* :ref:`SpecTypeBuildTestProgramItemType`
245
246.. _SpecTypeBuildAdaTestProgramItemType:
247
248Build Ada Test Program Item Type
249^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
250
251This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
252attribute if the value is ``ada-test-program``. This set of attributes
253specifies an Ada test program executable to build. Test programs may use
254additional objects provided by :ref:`SpecTypeBuildObjectsItemType` items.  Test
255programs have an implicit ``enabled-by`` attribute value which is controlled by
256the option action :ref:`set-test-state <SpecTypeBuildOptionItemType>`.  If the
257test state is set to ``exclude``, then the test program is not built. All
258explicit attributes shall be specified. The explicit attributes for this type
259are:
260
261ada-main
262    The attribute value shall be a string. It shall be the path to the Ada main
263    body file.
264
265ada-object-directory
266    The attribute value shall be a string. It shall be the path to the Ada
267    object directory (``-D`` option value for ``gnatmake``).
268
269adaflags
270    The attribute value shall be a list of strings. It shall be a list of
271    options for the Ada compiler.
272
273adaincludes
274    The attribute value shall be a list of strings. It shall be a list of Ada
275    include paths.
276
277cflags
278    The attribute value shall be a list. Each list element shall be a
279    :ref:`SpecTypeBuildCCompilerOption`.
280
281cppflags
282    The attribute value shall be a list. Each list element shall be a
283    :ref:`SpecTypeBuildCPreprocessorOption`.
284
285cxxflags
286    The attribute value shall be a list. Each list element shall be a
287    :ref:`SpecTypeBuildCXXCompilerOption`.
288
289includes
290    The attribute value shall be a list. Each list element shall be a
291    :ref:`SpecTypeBuildIncludePath`.
292
293ldflags
294    The attribute value shall be a list. Each list element shall be a
295    :ref:`SpecTypeBuildLinkerOption`.
296
297source
298    The attribute value shall be a list. Each list element shall be a
299    :ref:`SpecTypeBuildSource`.
300
301stlib
302    The attribute value shall be a list. Each list element shall be a
303    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.
304
305target
306    The attribute value shall be a :ref:`SpecTypeBuildTarget`.
307
308use-after
309    The attribute value shall be a list. Each list element shall be a
310    :ref:`SpecTypeBuildUseAfterDirective`.
311
312use-before
313    The attribute value shall be a list. Each list element shall be a
314    :ref:`SpecTypeBuildUseBeforeDirective`.
315
316Please have a look at the following example:
317
318.. code-block:: yaml
319
320    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
321    ada-main: testsuites/ada/samples/hello/hello.adb
322    ada-object-directory: testsuites/ada/samples/hello
323    adaflags: []
324    adaincludes:
325    - cpukit/include/adainclude
326    - testsuites/ada/support
327    build-type: ada-test-program
328    cflags: []
329    copyrights:
330    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
331    cppflags: []
332    cxxflags: []
333    enabled-by: true
334    includes: []
335    ldflags: []
336    links: []
337    source:
338    - testsuites/ada/samples/hello/init.c
339    stlib: []
340    target: testsuites/ada/ada_hello.exe
341    type: build
342    use-after: []
343    use-before: []
344
345.. _SpecTypeBuildBSPItemType:
346
347Build BSP Item Type
348^^^^^^^^^^^^^^^^^^^
349
350This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
351attribute if the value is ``bsp``. This set of attributes specifies a base BSP
352variant to build. All explicit attributes shall be specified. The explicit
353attributes for this type are:
354
355arch
356    The attribute value shall be a string. It shall be the target architecture
357    of the BSP.
358
359bsp
360    The attribute value shall be a string. It shall be the base BSP variant
361    name.
362
363cflags
364    The attribute value shall be a list. Each list element shall be a
365    :ref:`SpecTypeBuildCCompilerOption`.
366
367cppflags
368    The attribute value shall be a list. Each list element shall be a
369    :ref:`SpecTypeBuildCPreprocessorOption`.
370
371family
372    The attribute value shall be a string. It shall be the BSP family name.
373    The name shall be the last directory of the path to the BSP sources.
374
375includes
376    The attribute value shall be a list. Each list element shall be a
377    :ref:`SpecTypeBuildIncludePath`.
378
379install
380    The attribute value shall be a list. Each list element shall be a
381    :ref:`SpecTypeBuildInstallDirective`.
382
383source
384    The attribute value shall be a list. Each list element shall be a
385    :ref:`SpecTypeBuildSource`.
386
387Please have a look at the following example:
388
389.. code-block:: yaml
390
391    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
392    arch: myarch
393    bsp: mybsp
394    build-type: bsp
395    cflags: []
396    copyrights:
397    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
398    cppflags: []
399    enabled-by: true
400    family: mybsp
401    includes: []
402    install:
403    - destination: ${BSP_INCLUDEDIR}
404      source:
405      - bsps/myarch/mybsp/include/bsp.h
406      - bsps/myarch/mybsp/include/tm27.h
407    - destination: ${BSP_INCLUDEDIR}/bsp
408      source:
409      - bsps/myarch/mybsp/include/bsp/irq.h
410    - destination: ${BSP_LIBDIR}
411      source:
412      - bsps/myarch/mybsp/start/linkcmds
413    links:
414    - role: build-dependency
415      uid: ../../obj
416    - role: build-dependency
417      uid: ../../opto2
418    - role: build-dependency
419      uid: abi
420    - role: build-dependency
421      uid: obj
422    - role: build-dependency
423      uid: ../start
424    - role: build-dependency
425      uid: ../../bspopts
426    source:
427    - bsps/myarch/mybsp/start/bspstart.c
428    type: build
429
430.. _SpecTypeBuildConfigurationFileItemType:
431
432Build Configuration File Item Type
433^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
434
435This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
436attribute if the value is ``config-file``. This set of attributes specifies a
437configuration file placed in the build tree.  The configuration file is
438generated during the configure command execution and is placed in the build
439tree. All explicit attributes shall be specified. The explicit attributes for
440this type are:
441
442content
443    The attribute value shall be a string. It shall be the content of the
444    configuration file. A ${VARIABLE} substitution is performed during the
445    configure command execution using the variables of the configuration set.
446    Use $$ for a plain $ character. To have all variables from sibling items
447    available for substitution it is recommended to link them in the proper
448    order.
449
450install-path
451    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.
452
453target
454    The attribute value shall be a :ref:`SpecTypeBuildTarget`.
455
456Please have a look at the following example:
457
458.. code-block:: yaml
459
460    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
461    build-type: config-file
462    content: |
463      # ...
464      Name: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME}
465      # ...
466    copyrights:
467    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
468    enabled-by: true
469    install-path: ${PREFIX}/lib/pkgconfig
470    links: []
471    target: ${ARCH}-rtems${__RTEMS_MAJOR__}-${BSP_NAME}.pc
472    type: build
473
474.. _SpecTypeBuildConfigurationHeaderItemType:
475
476Build Configuration Header Item Type
477^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
478
479This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
480attribute if the value is ``config-header``. This set of attributes specifies
481configuration header file.  The configuration header file is generated during
482configure command execution and is placed in the build tree.  All collected
483configuration defines are written to the configuration header file during the
484configure command execution.  To have all configuration defines from sibling
485items available it is recommended to link them in the proper order. All
486explicit attributes shall be specified. The explicit attributes for this type
487are:
488
489guard
490    The attribute value shall be a string. It shall be the header guard define.
491
492include-headers
493    The attribute value shall be a list of strings. It shall be a list of
494    header files to include via ``#include <...>``.
495
496install-path
497    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.
498
499target
500    The attribute value shall be a :ref:`SpecTypeBuildTarget`.
501
502.. _SpecTypeBuildGroupItemType:
503
504Build Group Item Type
505^^^^^^^^^^^^^^^^^^^^^
506
507This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
508attribute if the value is ``group``. This set of attributes provides a means to
509aggregate other build items and modify the build item context which is used by
510referenced build items.  The ``includes``, ``ldflags``, ``objects``, and
511``use`` variables of the build item context are updated by the corresponding
512attributes of the build group. All explicit attributes shall be specified. The
513explicit attributes for this type are:
514
515cflags
516    The attribute value shall be a list. Each list element shall be a
517    :ref:`SpecTypeBuildCCompilerOption`.
518
519cppflags
520    The attribute value shall be a list. Each list element shall be a
521    :ref:`SpecTypeBuildCPreprocessorOption`.
522
523cxxflags
524    The attribute value shall be a list. Each list element shall be a
525    :ref:`SpecTypeBuildCXXCompilerOption`.
526
527includes
528    The attribute value shall be a list. Each list element shall be a
529    :ref:`SpecTypeBuildIncludePath`.
530
531install
532    The attribute value shall be a list. Each list element shall be a
533    :ref:`SpecTypeBuildInstallDirective`.
534
535ldflags
536    The attribute value shall be a list of strings. It shall be a list of
537    options for the linker.  They are used to link executables referenced by
538    this item.
539
540use-after
541    The attribute value shall be a list. Each list element shall be a
542    :ref:`SpecTypeBuildUseAfterDirective`.
543
544use-before
545    The attribute value shall be a list. Each list element shall be a
546    :ref:`SpecTypeBuildUseBeforeDirective`.
547
548Please have a look at the following example:
549
550.. code-block:: yaml
551
552    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
553    build-type: group
554    cflags: []
555    copyrights:
556    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
557    cppflags: []
558    cxxflags: []
559    enabled-by:
560    - BUILD_TESTS
561    - BUILD_SAMPLES
562    includes:
563    - testsuites/support/include
564    install: []
565    ldflags:
566    - -Wl,--wrap=printf
567    - -Wl,--wrap=puts
568    links:
569    - role: build-dependency
570      uid: ticker
571    type: build
572    use-after: []
573    use-before:
574    - rtemstest
575
576.. _SpecTypeBuildLibraryItemType:
577
578Build Library Item Type
579^^^^^^^^^^^^^^^^^^^^^^^
580
581This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
582attribute if the value is ``library``. This set of attributes specifies a
583static library.  Library items may use additional objects provided by
584:ref:`SpecTypeBuildObjectsItemType` items through the build dependency links of
585the item. All explicit attributes shall be specified. The explicit attributes
586for this type are:
587
588cflags
589    The attribute value shall be a list. Each list element shall be a
590    :ref:`SpecTypeBuildCCompilerOption`.
591
592cppflags
593    The attribute value shall be a list. Each list element shall be a
594    :ref:`SpecTypeBuildCPreprocessorOption`.
595
596cxxflags
597    The attribute value shall be a list. Each list element shall be a
598    :ref:`SpecTypeBuildCXXCompilerOption`.
599
600includes
601    The attribute value shall be a list. Each list element shall be a
602    :ref:`SpecTypeBuildIncludePath`.
603
604install
605    The attribute value shall be a list. Each list element shall be a
606    :ref:`SpecTypeBuildInstallDirective`.
607
608install-path
609    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.
610
611source
612    The attribute value shall be a list. Each list element shall be a
613    :ref:`SpecTypeBuildSource`.
614
615target
616    The attribute value shall be a :ref:`SpecTypeBuildTarget`. It shall be the
617    name of the static library, e.g. ``z`` for ``libz.a``.
618
619Please have a look at the following example:
620
621.. code-block:: yaml
622
623    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
624    build-type: library
625    cflags:
626    - -Wno-pointer-sign
627    copyrights:
628    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
629    cppflags: []
630    cxxflags: []
631    enabled-by: true
632    includes:
633    - cpukit/libfs/src/jffs2/include
634    install:
635    - destination: ${BSP_INCLUDEDIR}/rtems
636      source:
637      - cpukit/include/rtems/jffs2.h
638    install-path: ${BSP_LIBDIR}
639    links: []
640    source:
641    - cpukit/libfs/src/jffs2/src/build.c
642    target: jffs2
643    type: build
644
645.. _SpecTypeBuildObjectsItemType:
646
647Build Objects Item Type
648^^^^^^^^^^^^^^^^^^^^^^^
649
650This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
651attribute if the value is ``objects``. This set of attributes specifies a set
652of object files used to build static libraries or test programs. All explicit
653attributes shall be specified. The explicit attributes for this type are:
654
655cflags
656    The attribute value shall be a list. Each list element shall be a
657    :ref:`SpecTypeBuildCCompilerOption`.
658
659cppflags
660    The attribute value shall be a list. Each list element shall be a
661    :ref:`SpecTypeBuildCPreprocessorOption`.
662
663cxxflags
664    The attribute value shall be a list. Each list element shall be a
665    :ref:`SpecTypeBuildCXXCompilerOption`.
666
667includes
668    The attribute value shall be a list. Each list element shall be a
669    :ref:`SpecTypeBuildIncludePath`.
670
671install
672    The attribute value shall be a list. Each list element shall be a
673    :ref:`SpecTypeBuildInstallDirective`.
674
675source
676    The attribute value shall be a list. Each list element shall be a
677    :ref:`SpecTypeBuildSource`.
678
679Please have a look at the following example:
680
681.. code-block:: yaml
682
683    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
684    build-type: objects
685    cflags: []
686    copyrights:
687    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
688    cppflags: []
689    cxxflags: []
690    enabled-by: true
691    includes: []
692    install:
693    - destination: ${BSP_INCLUDEDIR}/bsp
694      source:
695      - bsps/include/bsp/bootcard.h
696      - bsps/include/bsp/default-initial-extension.h
697      - bsps/include/bsp/fatal.h
698    links: []
699    source:
700    - bsps/shared/start/bootcard.c
701    - bsps/shared/rtems-version.c
702    type: build
703
704.. _SpecTypeBuildOptionItemType:
705
706Build Option Item Type
707^^^^^^^^^^^^^^^^^^^^^^
708
709This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
710attribute if the value is ``option``. This set of attributes specifies a build
711option. The following explicit attributes are mandatory:
712
713* ``actions``
714
715* ``default``
716
717* ``default-by-variant``
718
719* ``description``
720
721The explicit attributes for this type are:
722
723actions
724    The attribute value shall be a list. Each list element shall be a
725    :ref:`SpecTypeBuildOptionAction`. Each action operates on the *action
726    value* handed over by a previous action and action-specific attribute
727    values.  The actions pass the processed action value to the next action in
728    the list.  The first action starts with an action value of ``None``.  The
729    actions are carried out during the configure command execution.
730
731default
732    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It shall be
733    the default value of the option if no variant-specific default value is
734    specified.  Use ``null`` to specify that no default value exits.  The
735    variant-specific default values may be specified by the
736    ``default-by-variant`` attribute.
737
738default-by-variant
739    The attribute value shall be a list. Each list element shall be a
740    :ref:`SpecTypeBuildOptionDefaultByVariant`. The list is checked two times
741    and processed from top to bottom. Firstly, the base BSP name is used to
742    match with a variant. Secondly, the BSP family name prefixed by ``bsps/``
743    is used to match with a variant.  If a matching variant is found, then the
744    processing stops.
745
746description
747    The attribute value shall be an optional string. It shall be the
748    description of the option.
749
750format
751    The attribute value shall be an optional string. It shall be a `Python
752    format string
753    <https://docs.python.org/3/library/string.html#formatstrings>`_, for
754    example ``'{}'`` or ``'{:#010x}'``.
755
756name
757    The attribute value shall be a :ref:`SpecTypeBuildOptionName`.
758
759Please have a look at the following example:
760
761.. code-block:: yaml
762
763    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
764    actions:
765    - get-integer: null
766    - define: null
767    build-type: option
768    copyrights:
769    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
770    default: 115200
771    default-by-variant:
772    - value: 9600
773      variants:
774      - bsps/powerpc/motorola_powerpc
775      - m68k/m5484FireEngine
776      - powerpc/hsc_cm01
777    - value: 19200
778      variants:
779      - m68k/COBRA5475
780    description: |
781      Default baud for console and other serial devices.
782    enabled-by: true
783    format: '{}'
784    links: []
785    name: BSP_CONSOLE_BAUD
786    type: build
787
788.. _SpecTypeBuildScriptItemType:
789
790Build Script Item Type
791^^^^^^^^^^^^^^^^^^^^^^
792
793This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
794attribute if the value is ``script``. This set of attributes specifies a build
795script.  The optional attributes may be required by commands executed through
796the scripts. The following explicit attributes are mandatory:
797
798* ``do-build``
799
800* ``do-configure``
801
802* ``prepare-build``
803
804* ``prepare-configure``
805
806The explicit attributes for this type are:
807
808asflags
809    The attribute value shall be a list. Each list element shall be a
810    :ref:`SpecTypeBuildAssemblerOption`.
811
812cflags
813    The attribute value shall be a list. Each list element shall be a
814    :ref:`SpecTypeBuildCCompilerOption`.
815
816cppflags
817    The attribute value shall be a list. Each list element shall be a
818    :ref:`SpecTypeBuildCPreprocessorOption`.
819
820cxxflags
821    The attribute value shall be a list. Each list element shall be a
822    :ref:`SpecTypeBuildCXXCompilerOption`.
823
824do-build
825    The attribute value shall be an optional string. If this script shall
826    execute, then it shall be Python code which is executed via ``exec()`` in
827    the context of the ``do_build()`` method of the :file:`wscript`.  A local
828    variable ``bld`` is available with the ``waf`` build context.  A local
829    variable ``bic`` is available with the build item context.
830
831do-configure
832    The attribute value shall be an optional string. If this script shall
833    execute, then it shall be Python code which is executed via ``exec()`` in
834    the context of the ``do_configure()`` method of the :file:`wscript`.  A
835    local variable ``conf`` is available with the ``waf`` configuration
836    context.  A local variable ``cic`` is available with the configuration item
837    context.
838
839includes
840    The attribute value shall be a list. Each list element shall be a
841    :ref:`SpecTypeBuildIncludePath`.
842
843ldflags
844    The attribute value shall be a list. Each list element shall be a
845    :ref:`SpecTypeBuildLinkerOption`.
846
847prepare-build
848    The attribute value shall be an optional string. If this script shall
849    execute, then it shall be Python code which is executed via ``exec()`` in
850    the context of the ``prepare_build()`` method of the :file:`wscript`.  A
851    local variable ``bld`` is available with the ``waf`` build context.  A
852    local variable ``bic`` is available with the build item context.
853
854prepare-configure
855    The attribute value shall be an optional string. If this script shall
856    execute, then it shall be Python code which is executed via ``exec()`` in
857    the context of the ``prepare_configure()`` method of the :file:`wscript`.
858    A local variable ``conf`` is available with the ``waf`` configuration
859    context.  A local variable ``cic`` is available with the configuration item
860    context.
861
862stlib
863    The attribute value shall be a list. Each list element shall be a
864    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.
865
866use-after
867    The attribute value shall be a list. Each list element shall be a
868    :ref:`SpecTypeBuildUseAfterDirective`.
869
870use-before
871    The attribute value shall be a list. Each list element shall be a
872    :ref:`SpecTypeBuildUseBeforeDirective`.
873
874Please have a look at the following example:
875
876.. code-block:: yaml
877
878    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
879    build-type: script
880    copyrights:
881    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
882    default: null
883    default-by-variant: []
884    do-build: |
885      bld.install_as(
886          "${BSP_LIBDIR}/linkcmds",
887          "bsps/" + bld.env.ARCH + "/" + bld.env.BSP_FAMILY +
888          "/start/linkcmds." + bld.env.BSP_BASE
889      )
890    do-configure: |
891      conf.env.append_value(
892          "LINKFLAGS",
893          ["-qnolinkcmds", "-T", "linkcmds." + conf.env.BSP_BASE]
894      )
895    enabled-by: true
896    links: []
897    prepare-build: null
898    prepare-configure: null
899    type: build
900
901.. _SpecTypeBuildStartFileItemType:
902
903Build Start File Item Type
904^^^^^^^^^^^^^^^^^^^^^^^^^^
905
906This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
907attribute if the value is ``start-file``. This set of attributes specifies a
908start file to build.  A start file is used to link an executable. All explicit
909attributes shall be specified. The explicit attributes for this type are:
910
911asflags
912    The attribute value shall be a list. Each list element shall be a
913    :ref:`SpecTypeBuildAssemblerOption`.
914
915cppflags
916    The attribute value shall be a list. Each list element shall be a
917    :ref:`SpecTypeBuildCPreprocessorOption`.
918
919includes
920    The attribute value shall be a list. Each list element shall be a
921    :ref:`SpecTypeBuildIncludePath`.
922
923install-path
924    The attribute value shall be a :ref:`SpecTypeBuildInstallPath`.
925
926source
927    The attribute value shall be a list. Each list element shall be a
928    :ref:`SpecTypeBuildSource`.
929
930target
931    The attribute value shall be a :ref:`SpecTypeBuildTarget`.
932
933Please have a look at the following example:
934
935.. code-block:: yaml
936
937    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
938    asflags: []
939    build-type: start-file
940    copyrights:
941    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
942    cppflags: []
943    enabled-by: true
944    includes: []
945    install-path: ${BSP_LIBDIR}
946    links: []
947    source:
948    - bsps/sparc/shared/start/start.S
949    target: start.o
950    type: build
951
952.. _SpecTypeBuildTestProgramItemType:
953
954Build Test Program Item Type
955^^^^^^^^^^^^^^^^^^^^^^^^^^^^
956
957This type refines the :ref:`SpecTypeBuildItemType` through the ``build-type``
958attribute if the value is ``test-program``. This set of attributes specifies a
959test program executable to build. Test programs may use additional objects
960provided by :ref:`SpecTypeBuildObjectsItemType` items.  Test programs have an
961implicit ``enabled-by`` attribute value which is controlled by the option
962action :ref:`set-test-state <SpecTypeBuildOptionItemType>`.  If the test state
963is set to ``exclude``, then the test program is not built. All explicit
964attributes shall be specified. The explicit attributes for this type are:
965
966cflags
967    The attribute value shall be a list. Each list element shall be a
968    :ref:`SpecTypeBuildCCompilerOption`.
969
970cppflags
971    The attribute value shall be a list. Each list element shall be a
972    :ref:`SpecTypeBuildCPreprocessorOption`.
973
974cxxflags
975    The attribute value shall be a list. Each list element shall be a
976    :ref:`SpecTypeBuildCXXCompilerOption`.
977
978features
979    The attribute value shall be a string. It shall be the ``waf`` build
980    features for this test program.
981
982includes
983    The attribute value shall be a list. Each list element shall be a
984    :ref:`SpecTypeBuildIncludePath`.
985
986ldflags
987    The attribute value shall be a list. Each list element shall be a
988    :ref:`SpecTypeBuildLinkerOption`.
989
990source
991    The attribute value shall be a list. Each list element shall be a
992    :ref:`SpecTypeBuildSource`.
993
994stlib
995    The attribute value shall be a list. Each list element shall be a
996    :ref:`SpecTypeBuildLinkStaticLibraryDirective`.
997
998target
999    The attribute value shall be a :ref:`SpecTypeBuildTarget`.
1000
1001use-after
1002    The attribute value shall be a list. Each list element shall be a
1003    :ref:`SpecTypeBuildUseAfterDirective`.
1004
1005use-before
1006    The attribute value shall be a list. Each list element shall be a
1007    :ref:`SpecTypeBuildUseBeforeDirective`.
1008
1009Please have a look at the following example:
1010
1011.. code-block:: yaml
1012
1013    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
1014    build-type: test-program
1015    cflags: []
1016    copyrights:
1017    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
1018    cppflags: []
1019    cxxflags: []
1020    enabled-by: true
1021    features: c cprogram
1022    includes: []
1023    ldflags: []
1024    links: []
1025    source:
1026    - testsuites/samples/ticker/init.c
1027    - testsuites/samples/ticker/tasks.c
1028    stlib: []
1029    target: testsuites/samples/ticker.exe
1030    type: build
1031    use-after: []
1032    use-before: []
1033
1034.. _SpecTypeConstraintItemType:
1035
1036Constraint Item Type
1037^^^^^^^^^^^^^^^^^^^^
1038
1039This type refines the :ref:`SpecTypeRootItemType` through the ``type``
1040attribute if the value is ``constraint``. This set of attributes specifies a
1041constraint. All explicit attributes shall be specified. The explicit attributes
1042for this type are:
1043
1044rationale
1045    The attribute value shall be an optional string. If the value is present,
1046    then it shall state the rationale or justification of the constraint.
1047
1048text
1049    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
1050    state the constraint.
1051
1052.. _SpecTypeGlossaryItemType:
1053
1054Glossary Item Type
1055^^^^^^^^^^^^^^^^^^
1056
1057This type refines the :ref:`SpecTypeRootItemType` through the ``type``
1058attribute if the value is ``glossary``. This set of attributes specifies a
1059glossary item. All explicit attributes shall be specified. The explicit
1060attributes for this type are:
1061
1062glossary-type
1063    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
1064    glossary item type.
1065
1066This type is refined by the following types:
1067
1068* :ref:`SpecTypeGlossaryGroupItemType`
1069
1070* :ref:`SpecTypeGlossaryTermItemType`
1071
1072.. _SpecTypeGlossaryGroupItemType:
1073
1074Glossary Group Item Type
1075^^^^^^^^^^^^^^^^^^^^^^^^
1076
1077This type refines the :ref:`SpecTypeGlossaryItemType` through the
1078``glossary-type`` attribute if the value is ``group``. This set of attributes
1079specifies a glossary group. All explicit attributes shall be specified. The
1080explicit attributes for this type are:
1081
1082name
1083    The attribute value shall be a string. It shall be the human readable name
1084    of the glossary group.
1085
1086text
1087    The attribute value shall be a string. It shall state the requirement for
1088    the glossary group.
1089
1090.. _SpecTypeGlossaryTermItemType:
1091
1092Glossary Term Item Type
1093^^^^^^^^^^^^^^^^^^^^^^^
1094
1095This type refines the :ref:`SpecTypeGlossaryItemType` through the
1096``glossary-type`` attribute if the value is ``term``. This set of attributes
1097specifies a glossary term. All explicit attributes shall be specified. The
1098explicit attributes for this type are:
1099
1100term
1101    The attribute value shall be a string. It shall be the glossary term.
1102
1103text
1104    The attribute value shall be a string. It shall be the definition of the
1105    glossary term.
1106
1107.. _SpecTypeInterfaceItemType:
1108
1109Interface Item Type
1110^^^^^^^^^^^^^^^^^^^
1111
1112This type refines the :ref:`SpecTypeRootItemType` through the ``type``
1113attribute if the value is ``interface``. This set of attributes specifies an
1114interface specification item. Interface items shall specify the interface of
1115the software product to other software products and the hardware.  Use
1116:ref:`SpecTypeInterfaceDomainItemType` items to specify interface domains, for
1117example the :term:`API`, C language, compiler, interfaces to the
1118implementation, and the hardware. All explicit attributes shall be specified.
1119The explicit attributes for this type are:
1120
1121index-entries
1122    The attribute value shall be a list of strings. It shall be a list of
1123    additional document index entries.  A document index entry derived from the
1124    interface name is added automatically.
1125
1126interface-type
1127    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
1128    interface item type.
1129
1130This type is refined by the following types:
1131
1132* :ref:`SpecTypeApplicationConfigurationGroupItemType`
1133
1134* :ref:`SpecTypeApplicationConfigurationOptionItemType`
1135
1136* :ref:`SpecTypeInterfaceCompoundItemType`
1137
1138* :ref:`SpecTypeInterfaceDefineItemType`
1139
1140* :ref:`SpecTypeInterfaceDomainItemType`
1141
1142* :ref:`SpecTypeInterfaceEnumItemType`
1143
1144* :ref:`SpecTypeInterfaceEnumeratorItemType`
1145
1146* :ref:`SpecTypeInterfaceForwardDeclarationItemType`
1147
1148* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
1149
1150* :ref:`SpecTypeInterfaceGroupItemType`
1151
1152* :ref:`SpecTypeInterfaceHeaderFileItemType`
1153
1154* :ref:`SpecTypeInterfaceTypedefItemType`
1155
1156* :ref:`SpecTypeInterfaceUnspecifiedItemType`
1157
1158* :ref:`SpecTypeInterfaceVariableItemType`
1159
1160.. _SpecTypeApplicationConfigurationGroupItemType:
1161
1162Application Configuration Group Item Type
1163^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1164
1165This type refines the :ref:`SpecTypeInterfaceItemType` through the
1166``interface-type`` attribute if the value is ``appl-config-group``. This set of
1167attributes specifies an application configuration group. All explicit
1168attributes shall be specified. The explicit attributes for this type are:
1169
1170description
1171    The attribute value shall be a string. It shall be the description of the
1172    application configuration group.
1173
1174name
1175    The attribute value shall be a string. It shall be human readable name of
1176    the application configuration group.
1177
1178text
1179    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
1180    state the requirement for the application configuration group.
1181
1182.. _SpecTypeApplicationConfigurationOptionItemType:
1183
1184Application Configuration Option Item Type
1185^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1186
1187This type refines the :ref:`SpecTypeInterfaceItemType` through the
1188``interface-type`` attribute if the value is ``appl-config-option``. This set
1189of attributes specifies an application configuration option. All explicit
1190attributes shall be specified. The explicit attributes for this type are:
1191
1192appl-config-option-type
1193    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
1194    application configuration option type.
1195
1196description
1197    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1198
1199name
1200    The attribute value shall be an
1201    :ref:`SpecTypeApplicationConfigurationOptionName`.
1202
1203notes
1204    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1205
1206This type is refined by the following types:
1207
1208* :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType`
1209
1210* :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType`
1211
1212* :ref:`SpecTypeApplicationConfigurationValueOptionItemType`
1213
1214.. _SpecTypeApplicationConfigurationFeatureEnableOptionItemType:
1215
1216Application Configuration Feature Enable Option Item Type
1217^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1218
1219This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType`
1220through the ``appl-config-option-type`` attribute if the value is
1221``feature-enable``. This set of attributes specifies an application
1222configuration feature enable option.
1223
1224.. _SpecTypeApplicationConfigurationFeatureOptionItemType:
1225
1226Application Configuration Feature Option Item Type
1227^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1228
1229This type refines the :ref:`SpecTypeApplicationConfigurationOptionItemType`
1230through the ``appl-config-option-type`` attribute if the value is ``feature``.
1231This set of attributes specifies an application configuration feature option.
1232All explicit attributes shall be specified. The explicit attributes for this
1233type are:
1234
1235default
1236    The attribute value shall be a string. It shall describe what happens if
1237    the configuration option is undefined.
1238
1239.. _SpecTypeApplicationConfigurationValueOptionItemType:
1240
1241Application Configuration Value Option Item Type
1242^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1243
1244This type refines the following types:
1245
1246* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the
1247  ``appl-config-option-type`` attribute if the value is ``initializer``
1248
1249* :ref:`SpecTypeApplicationConfigurationOptionItemType` through the
1250  ``appl-config-option-type`` attribute if the value is ``integer``
1251
1252This set of attributes specifies application configuration initializer or
1253integer option. All explicit attributes shall be specified. The explicit
1254attributes for this type are:
1255
1256default-value
1257    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. It shall
1258    describe the default value of the application configuration option.
1259
1260.. _SpecTypeInterfaceCompoundItemType:
1261
1262Interface Compound Item Type
1263^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1264
1265This type refines the following types:
1266
1267* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1268  the value is ``struct``
1269
1270* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1271  the value is ``union``
1272
1273This set of attributes specifies a compound (struct or union). All explicit
1274attributes shall be specified. The explicit attributes for this type are:
1275
1276brief
1277    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1278
1279definition
1280    The attribute value shall be a list. Each list element shall be an
1281    :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`.
1282
1283definition-kind
1284    The attribute value shall be an
1285    :ref:`SpecTypeInterfaceCompoundDefinitionKind`.
1286
1287description
1288    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1289
1290name
1291    The attribute value shall be a string. It shall be the name of the compound
1292    (struct or union).
1293
1294notes
1295    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1296
1297.. _SpecTypeInterfaceDefineItemType:
1298
1299Interface Define Item Type
1300^^^^^^^^^^^^^^^^^^^^^^^^^^
1301
1302This type refines the :ref:`SpecTypeInterfaceItemType` through the
1303``interface-type`` attribute if the value is ``define``. This set of attributes
1304specifies a define. All explicit attributes shall be specified. The explicit
1305attributes for this type are:
1306
1307brief
1308    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1309
1310definition
1311    The attribute value shall be an
1312    :ref:`SpecTypeInterfaceDefinitionDirective`.
1313
1314description
1315    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1316
1317name
1318    The attribute value shall be a string. It shall be the name of the define.
1319
1320notes
1321    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1322
1323.. _SpecTypeInterfaceDomainItemType:
1324
1325Interface Domain Item Type
1326^^^^^^^^^^^^^^^^^^^^^^^^^^
1327
1328This type refines the :ref:`SpecTypeInterfaceItemType` through the
1329``interface-type`` attribute if the value is ``domain``. This set of attributes
1330specifies an interface domain.  Interface items are placed into domains through
1331links with the :ref:`SpecTypeInterfacePlacementLinkRole`. All explicit
1332attributes shall be specified. The explicit attributes for this type are:
1333
1334description
1335    The attribute value shall be a string. It shall be the description of the
1336    domain
1337
1338name
1339    The attribute value shall be a string. It shall be the human readable name
1340    of the domain.
1341
1342.. _SpecTypeInterfaceEnumItemType:
1343
1344Interface Enum Item Type
1345^^^^^^^^^^^^^^^^^^^^^^^^
1346
1347This type refines the :ref:`SpecTypeInterfaceItemType` through the
1348``interface-type`` attribute if the value is ``enum``. This set of attributes
1349specifies an enum. All explicit attributes shall be specified. The explicit
1350attributes for this type are:
1351
1352brief
1353    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1354
1355definition-kind
1356    The attribute value shall be an :ref:`SpecTypeInterfaceEnumDefinitionKind`.
1357
1358description
1359    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1360
1361name
1362    The attribute value shall be a string. It shall be the name of the enum.
1363
1364notes
1365    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1366
1367.. _SpecTypeInterfaceEnumeratorItemType:
1368
1369Interface Enumerator Item Type
1370^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1371
1372This type refines the :ref:`SpecTypeInterfaceItemType` through the
1373``interface-type`` attribute if the value is ``enumerator``. This set of
1374attributes specifies an enumerator. All explicit attributes shall be specified.
1375The explicit attributes for this type are:
1376
1377brief
1378    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1379
1380definition
1381    The attribute value shall be an
1382    :ref:`SpecTypeInterfaceDefinitionDirective`.
1383
1384description
1385    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1386
1387name
1388    The attribute value shall be a string. It shall be the name of the
1389    enumerator.
1390
1391notes
1392    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1393
1394.. _SpecTypeInterfaceForwardDeclarationItemType:
1395
1396Interface Forward Declaration Item Type
1397^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1398
1399This type refines the :ref:`SpecTypeInterfaceItemType` through the
1400``interface-type`` attribute if the value is ``forward-declaration``. Items of
1401this type specify a forward declaration.  The item shall have exactly one link
1402with the :ref:`SpecTypeInterfaceTargetLinkRole` to an
1403:ref:`SpecTypeInterfaceCompoundItemType` item.  This link defines the type
1404declared by the forward declaration.
1405
1406.. _SpecTypeInterfaceFunctionOrMacroItemType:
1407
1408Interface Function or Macro Item Type
1409^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1410
1411This type refines the following types:
1412
1413* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1414  the value is ``function``
1415
1416* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1417  the value is ``macro``
1418
1419This set of attributes specifies a function or a macro. All explicit attributes
1420shall be specified. The explicit attributes for this type are:
1421
1422brief
1423    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1424
1425definition
1426    The attribute value shall be an
1427    :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`.
1428
1429description
1430    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1431
1432name
1433    The attribute value shall be a string. It shall be the name of the function
1434    or macro.
1435
1436notes
1437    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1438
1439params
1440    The attribute value shall be a list. Each list element shall be an
1441    :ref:`SpecTypeInterfaceParameter`.
1442
1443return
1444    The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`.
1445
1446.. _SpecTypeInterfaceGroupItemType:
1447
1448Interface Group Item Type
1449^^^^^^^^^^^^^^^^^^^^^^^^^
1450
1451This type refines the :ref:`SpecTypeInterfaceItemType` through the
1452``interface-type`` attribute if the value is ``group``. This set of attributes
1453specifies an interface group. All explicit attributes shall be specified. The
1454explicit attributes for this type are:
1455
1456brief
1457    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1458
1459description
1460    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1461
1462identifier
1463    The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`.
1464
1465name
1466    The attribute value shall be a string. It shall be the human readable name
1467    of the interface group.
1468
1469text
1470    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
1471    state the requirement for the interface group.
1472
1473.. _SpecTypeInterfaceHeaderFileItemType:
1474
1475Interface Header File Item Type
1476^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1477
1478This type refines the :ref:`SpecTypeInterfaceItemType` through the
1479``interface-type`` attribute if the value is ``header-file``. This set of
1480attributes specifies a header file.  The item shall have exactly one link with
1481the :ref:`SpecTypeInterfacePlacementLinkRole` to an
1482:ref:`SpecTypeInterfaceDomainItemType` item.  This link defines the interface
1483domain of the header file. All explicit attributes shall be specified. The
1484explicit attributes for this type are:
1485
1486brief
1487    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1488
1489path
1490    The attribute value shall be a string. It shall be the path used to include
1491    the header file.  For example :file:`rtems/confdefs.h`.
1492
1493prefix
1494    The attribute value shall be a string. It shall be the prefix directory
1495    path to the header file in the interface domain.  For example
1496    :file:`cpukit/include`.
1497
1498.. _SpecTypeInterfaceTypedefItemType:
1499
1500Interface Typedef Item Type
1501^^^^^^^^^^^^^^^^^^^^^^^^^^^
1502
1503This type refines the :ref:`SpecTypeInterfaceItemType` through the
1504``interface-type`` attribute if the value is ``typedef``. This set of
1505attributes specifies a typedef. All explicit attributes shall be specified. The
1506explicit attributes for this type are:
1507
1508brief
1509    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1510
1511definition
1512    The attribute value shall be an
1513    :ref:`SpecTypeInterfaceDefinitionDirective`.
1514
1515description
1516    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1517
1518name
1519    The attribute value shall be a string. It shall be the name of the typedef.
1520
1521notes
1522    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1523
1524params
1525    The attribute value shall be a list. Each list element shall be an
1526    :ref:`SpecTypeInterfaceParameter`.
1527
1528return
1529    The attribute value shall be an :ref:`SpecTypeInterfaceReturnDirective`.
1530
1531.. _SpecTypeInterfaceUnspecifiedItemType:
1532
1533Interface Unspecified Item Type
1534^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1535
1536This type refines the following types:
1537
1538* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1539  the value is ``unspecified-define``
1540
1541* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1542  the value is ``unspecified-define-or-object``
1543
1544* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1545  the value is ``unspecified-enum``
1546
1547* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1548  the value is ``unspecified-enumerator``
1549
1550* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1551  the value is ``unspecified-function``
1552
1553* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1554  the value is ``unspecified-group``
1555
1556* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1557  the value is ``unspecified-macro``
1558
1559* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1560  the value is ``unspecified-macro-or-function``
1561
1562* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1563  the value is ``unspecified-object``
1564
1565* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1566  the value is ``unspecified-struct``
1567
1568* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1569  the value is ``unspecified-typedef``
1570
1571* :ref:`SpecTypeInterfaceItemType` through the ``interface-type`` attribute if
1572  the value is ``unspecified-union``
1573
1574This set of attributes specifies an unspecified interface. All explicit
1575attributes shall be specified. The explicit attributes for this type are:
1576
1577name
1578    The attribute value shall be a string. It shall be the name of the
1579    unspecified interface.
1580
1581references
1582    The attribute value shall be an :ref:`SpecTypeInterfaceReferencesSet`.
1583
1584.. _SpecTypeInterfaceVariableItemType:
1585
1586Interface Variable Item Type
1587^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1588
1589This type refines the :ref:`SpecTypeInterfaceItemType` through the
1590``interface-type`` attribute if the value is ``variable``. This set of
1591attributes specifies a variable. All explicit attributes shall be specified.
1592The explicit attributes for this type are:
1593
1594brief
1595    The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
1596
1597definition
1598    The attribute value shall be an
1599    :ref:`SpecTypeInterfaceDefinitionDirective`.
1600
1601description
1602    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
1603
1604name
1605    The attribute value shall be a string. It shall be the name of the
1606    variable.
1607
1608notes
1609    The attribute value shall be an :ref:`SpecTypeInterfaceNotes`.
1610
1611.. _SpecTypeRequirementItemType:
1612
1613Requirement Item Type
1614^^^^^^^^^^^^^^^^^^^^^
1615
1616This type refines the :ref:`SpecTypeRootItemType` through the ``type``
1617attribute if the value is ``requirement``. This set of attributes specifies a
1618requirement. All explicit attributes shall be specified. The explicit
1619attributes for this type are:
1620
1621rationale
1622    The attribute value shall be an optional string. If the value is present,
1623    then it shall state the rationale or justification of the requirement.
1624
1625references
1626    The attribute value shall be a list. Each list element shall be a
1627    :ref:`SpecTypeRequirementReference`.
1628
1629requirement-type
1630    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
1631    requirement item type.
1632
1633text
1634    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
1635    state the requirement.
1636
1637This type is refined by the following types:
1638
1639* :ref:`SpecTypeFunctionalRequirementItemType`
1640
1641* :ref:`SpecTypeNonFunctionalRequirementItemType`
1642
1643Please have a look at the following example:
1644
1645.. code-block:: yaml
1646
1647    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
1648    copyrights:
1649    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de
1650    enabled-by: true
1651    functional-type: capability
1652    links: []
1653    rationale: |
1654      It keeps you busy.
1655    requirement-type: functional
1656    text: |
1657      The system shall do crazy things.
1658    type: requirement
1659
1660.. _SpecTypeFunctionalRequirementItemType:
1661
1662Functional Requirement Item Type
1663^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1664
1665This type refines the :ref:`SpecTypeRequirementItemType` through the
1666``requirement-type`` attribute if the value is ``functional``. This set of
1667attributes specifies a functional requirement. All explicit attributes shall be
1668specified. The explicit attributes for this type are:
1669
1670functional-type
1671    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
1672    functional type of the requirement.
1673
1674This type is refined by the following types:
1675
1676* :ref:`SpecTypeActionRequirementItemType`
1677
1678* :ref:`SpecTypeGenericFunctionalRequirementItemType`
1679
1680.. _SpecTypeActionRequirementItemType:
1681
1682Action Requirement Item Type
1683^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1684
1685This type refines the :ref:`SpecTypeFunctionalRequirementItemType` through the
1686``functional-type`` attribute if the value is ``action``. This set of
1687attributes specifies functional requirements and corresponding validation test
1688code.  The functional requirements of an action are specified.  An action
1689performs a step in a finite state machine.  An action is implemented through a
1690function or a macro.  The action is performed through a call of the function or
1691an execution of the code of a macro expansion by an actor.  The actor is for
1692example a task or an interrupt service routine.
1693
1694For action requirements which specify the function of an interface, there shall
1695be exactly one link with the :ref:`SpecTypeInterfaceFunctionLinkRole` to the
1696interface of the action.
1697
1698The action requirements are specified by
1699
1700* a list of pre-conditions, each with a set of states,
1701
1702* a list of post-conditions, each with a set of states,
1703
1704* the transition of pre-condition states to post-condition states through the
1705  action.
1706
1707Along with the requirements, the test code to generate a validation test is
1708specified.  For an action requirement it is verified that all variations of
1709pre-condition states have a set of post-condition states specified in the
1710transition map.  All transitions are covered by the generated test code. All
1711explicit attributes shall be specified. The explicit attributes for this type
1712are:
1713
1714post-conditions
1715    The attribute value shall be a list. Each list element shall be an
1716    :ref:`SpecTypeActionRequirementCondition`.
1717
1718pre-conditions
1719    The attribute value shall be a list. Each list element shall be an
1720    :ref:`SpecTypeActionRequirementCondition`.
1721
1722skip-reasons
1723    The attribute value shall be an
1724    :ref:`SpecTypeActionRequirementSkipReasons`.
1725
1726test-action
1727    The attribute value shall be a string. It shall be the test action code.
1728
1729test-brief
1730    The attribute value shall be an optional string. If the value is present,
1731    then it shall be the test case brief description.
1732
1733test-cleanup
1734    The attribute value shall be an optional string. If the value is present,
1735    then it shall be the test cleanup code.  The code is placed in the test
1736    action loop body after the test post-condition checks.
1737
1738test-context
1739    The attribute value shall be a list. Each list element shall be a
1740    :ref:`SpecTypeTestContextMember`.
1741
1742test-context-support
1743    The attribute value shall be an optional string. If the value is present,
1744    then it shall be the test context support code.  The context support code
1745    is placed at file scope before the test context definition.
1746
1747test-description
1748    The attribute value shall be an optional string. If the value is present,
1749    then it shall be the test case description.
1750
1751test-header
1752    The attribute value shall be a :ref:`SpecTypeTestHeader`.
1753
1754test-includes
1755    The attribute value shall be a list of strings. It shall be a list of
1756    header files included via ``#include <...>``.
1757
1758test-local-includes
1759    The attribute value shall be a list of strings. It shall be a list of
1760    header files included via ``#include "..."``.
1761
1762test-prepare
1763    The attribute value shall be an optional string. If the value is present,
1764    then it shall be the early test preparation code.  The code is placed in
1765    the test action loop body before the test pre-condition preparations.
1766
1767test-setup
1768    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.
1769
1770test-stop
1771    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.
1772
1773test-support
1774    The attribute value shall be an optional string. If the value is present,
1775    then it shall be the test case support code. The support code is placed at
1776    file scope before the test case code.
1777
1778test-target
1779    The attribute value shall be a string. It shall be the path to the
1780    generated test case source file.
1781
1782test-teardown
1783    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.
1784
1785transition-map
1786    The attribute value shall be a list. Each list element shall be an
1787    :ref:`SpecTypeActionRequirementTransition`.
1788
1789Please have a look at the following example:
1790
1791.. code-block:: yaml
1792
1793    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
1794    copyrights:
1795    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
1796    enabled-by: true
1797    functional-type: action
1798    links: []
1799    post-conditions:
1800    - name: Status
1801      states:
1802      - name: Success
1803        test-code: |
1804          /* Check that the status is SUCCESS */
1805        text: |
1806          The status shall be SUCCESS.
1807      - name: Error
1808        test-code: |
1809          /* Check that the status is ERROR */
1810        text: |
1811          The status shall be ERROR.
1812      test-epilogue: null
1813      test-prologue: null
1814    - name: Data
1815      states:
1816      - name: Unchanged
1817        test-code: |
1818          /* Check that the data is unchanged */
1819        text: |
1820          The data shall be unchanged by the action.
1821      - name: Red
1822        test-code: |
1823          /* Check that the data is red */
1824        text: |
1825          The data shall be red.
1826      - name: Green
1827        test-code: |
1828          /* Check that the data is green */
1829        text: |
1830          The data shall be green.
1831      test-epilogue: null
1832      test-prologue: null
1833    pre-conditions:
1834    - name: Data
1835      states:
1836      - name: NullPtr
1837        test-code: |
1838          /* Set data pointer to NULL */
1839        text: |
1840          The data pointer shall be NULL.
1841      - name: Valid
1842        test-code: |
1843          /* Set data pointer to reference a valid data buffer */
1844        text: |
1845          The data pointer shall reference a valid data buffer.
1846      test-epilogue: null
1847      test-prologue: null
1848    - name: Option
1849      states:
1850      - name: Red
1851        test-code: |
1852          /* Set option to RED */
1853        text: |
1854          The option shall be RED.
1855      - name: Green
1856        test-code: |
1857          /* Set option to GREEN */
1858        text: |
1859          The option shall be GREEN.
1860      test-epilogue: null
1861      test-prologue: null
1862    requirement-type: functional
1863    skip-reasons: {}
1864    test-action: |
1865      /* Call the function of the action */
1866    test-brief: null
1867    test-cleanup: null
1868    test-context:
1869    - brief: null
1870      description: null
1871      member: void *data
1872    - brief: null
1873      description: null
1874      member: option_type option
1875    test-context-support: null
1876    test-description: null
1877    test-header: null
1878    test-includes: []
1879    test-local-includes: []
1880    test-prepare: null
1881    test-setup: null
1882    test-stop: null
1883    test-support: null
1884    test-target: tc-red-green-data.c
1885    test-teardown: null
1886    transition-map:
1887    - enabled-by: true
1888      post-conditions:
1889        Status: Error
1890        Data: Unchanged
1891      pre-conditions:
1892        Data: NullPtr
1893        Option: all
1894    - enabled-by: true
1895      post-conditions:
1896        Status: Success
1897        Data: Red
1898      pre-conditions:
1899        Data: Valid
1900        Option: Red
1901    - enabled-by: true
1902      post-conditions:
1903        Status: Success
1904        Data: Green
1905      pre-conditions:
1906        Data: Valid
1907        Option: Green
1908    rationale: null
1909    references: []
1910    text: |
1911      ${.:/text-template}
1912    type: requirement
1913
1914.. _SpecTypeGenericFunctionalRequirementItemType:
1915
1916Generic Functional Requirement Item Type
1917^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1918
1919This type refines the following types:
1920
1921* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
1922  attribute if the value is ``capability``
1923
1924* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
1925  attribute if the value is ``dependability-function``
1926
1927* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
1928  attribute if the value is ``function``
1929
1930* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
1931  attribute if the value is ``operational``
1932
1933* :ref:`SpecTypeFunctionalRequirementItemType` through the ``functional-type``
1934  attribute if the value is ``safety-function``
1935
1936Items of this type state a functional requirement with the functional type
1937defined by the specification type refinement.
1938
1939.. _SpecTypeNonFunctionalRequirementItemType:
1940
1941Non-Functional Requirement Item Type
1942^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1943
1944This type refines the :ref:`SpecTypeRequirementItemType` through the
1945``requirement-type`` attribute if the value is ``non-functional``. This set of
1946attributes specifies a non-functional requirement. All explicit attributes
1947shall be specified. The explicit attributes for this type are:
1948
1949non-functional-type
1950    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
1951    non-functional type of the requirement.
1952
1953This type is refined by the following types:
1954
1955* :ref:`SpecTypeDesignGroupRequirementItemType`
1956
1957* :ref:`SpecTypeGenericNonFunctionalRequirementItemType`
1958
1959* :ref:`SpecTypeRuntimePerformanceRequirementItemType`
1960
1961.. _SpecTypeDesignGroupRequirementItemType:
1962
1963Design Group Requirement Item Type
1964^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1965
1966This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through
1967the ``non-functional-type`` attribute if the value is ``design-group``. This
1968set of attributes specifies a design group requirement.  Design group
1969requirements have an explicit reference to the associated Doxygen group
1970specified by the ``identifier`` attribute.  Design group requirements have an
1971implicit validation by inspection method.  The qualification toolchain shall
1972perform the inspection and check that the specified Doxygen group exists in the
1973software source code. All explicit attributes shall be specified. The explicit
1974attributes for this type are:
1975
1976identifier
1977    The attribute value shall be an :ref:`SpecTypeInterfaceGroupIdentifier`.
1978
1979.. _SpecTypeGenericNonFunctionalRequirementItemType:
1980
1981Generic Non-Functional Requirement Item Type
1982^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1983
1984This type refines the following types:
1985
1986* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
1987  ``non-functional-type`` attribute if the value is ``build-configuration``
1988
1989* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
1990  ``non-functional-type`` attribute if the value is ``constraint``
1991
1992* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
1993  ``non-functional-type`` attribute if the value is ``design``
1994
1995* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
1996  ``non-functional-type`` attribute if the value is ``documentation``
1997
1998* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
1999  ``non-functional-type`` attribute if the value is ``interface``
2000
2001* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2002  ``non-functional-type`` attribute if the value is ``interface-requirement``
2003
2004* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2005  ``non-functional-type`` attribute if the value is ``maintainability``
2006
2007* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2008  ``non-functional-type`` attribute if the value is ``performance``
2009
2010* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2011  ``non-functional-type`` attribute if the value is ``portability``
2012
2013* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2014  ``non-functional-type`` attribute if the value is ``quality``
2015
2016* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2017  ``non-functional-type`` attribute if the value is ``reliability``
2018
2019* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2020  ``non-functional-type`` attribute if the value is ``resource``
2021
2022* :ref:`SpecTypeNonFunctionalRequirementItemType` through the
2023  ``non-functional-type`` attribute if the value is ``safety``
2024
2025Items of this type state a non-functional requirement with the non-functional
2026type defined by the specification type refinement.
2027
2028.. _SpecTypeRuntimePerformanceRequirementItemType:
2029
2030Runtime Performance Requirement Item Type
2031^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2032
2033This type refines the :ref:`SpecTypeNonFunctionalRequirementItemType` through
2034the ``non-functional-type`` attribute if the value is ``performance-runtime``.
2035The item shall have exactly one link with the
2036:ref:`SpecTypeRuntimeMeasurementRequestLinkRole`.  A requirement text processor
2037shall support a substitution of ${.:/limit-kind}:
2038
2039* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound`` or
2040  ``min-upper-bound``, the substitution of ${.:/limit-kind} shall be
2041  ``"minimum"``.
2042
2043* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``mean-lower-bound`` or
2044  ``mean-upper-bound``, the substitution of ${.:/limit-kind} shall be
2045  ``"mean"``.
2046
2047* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``max-lower-bound`` or
2048  ``max-upper-bound``, the substitution of ${.:/limit-kind} shall be
2049  ``"maximum"``.
2050
2051A requirement text processor shall support a substitution of
2052${.:/limit-condition}:
2053
2054* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-lower-bound``,
2055  ``mean-lower-bound``, or ``max-lower-bound``, the substitution of
2056  ${.:/limit-condition} shall be ``"greater than or equal to <value>"`` with
2057  <value> being the value of the corresponding entry in the
2058  :ref:`SpecTypeRuntimeMeasurementValueTable`.
2059
2060* For a :ref:`SpecTypeRuntimeMeasurementValueKind` of ``min-upper-bound``,
2061  ``mean-upper-bound``, or ``max-upper-bound``, the substitution of
2062  ${.:/limit-condition} shall be ``"less than or equal to <value>"`` with
2063  <value> being the value of the corresponding entry in the
2064  :ref:`SpecTypeRuntimeMeasurementValueTable`.
2065
2066A requirement text processor shall support a substitution of ${.:/environment}.
2067The value of the substitution shall be ``"<environment> environment"`` with
2068<environment> being the environment of the corresponding entry in the
2069:ref:`SpecTypeRuntimeMeasurementEnvironmentTable`.
2070
2071This set of attributes specifies a runtime performance requirement. Along with
2072the requirement, the validation test code to execute a measure runtime request
2073is specified. All explicit attributes shall be specified. The explicit
2074attributes for this type are:
2075
2076limits
2077    The attribute value shall be a :ref:`SpecTypeRuntimePerformanceLimitTable`.
2078
2079params
2080    The attribute value shall be a
2081    :ref:`SpecTypeRuntimePerformanceParameterSet`.
2082
2083test-body
2084    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It shall
2085    provide the code of the measure runtime body handler.  In contrast to other
2086    methods, this method is mandatory.
2087
2088test-cleanup
2089    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
2090    provide the code to clean up the measure runtime request. This method is
2091    called before the cleanup method of the corresponding
2092    :ref:`SpecTypeRuntimeMeasurementTestItemType` item and after the request.
2093
2094test-prepare
2095    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
2096    provide the code to prepare the measure runtime request.  This method is
2097    called after the prepare method of the corresponding
2098    :ref:`SpecTypeRuntimeMeasurementTestItemType` item and before the request.
2099
2100test-setup
2101    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
2102    provide the code of the measure runtime setup handler.
2103
2104test-teardown
2105    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. It may
2106    provide the code of the measure runtime teardown handler.
2107
2108Please have a look at the following example:
2109
2110.. code-block:: yaml
2111
2112    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2113    copyrights:
2114    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
2115    enabled-by: true
2116    links:
2117    - role: runtime-measurement-request
2118      uid: ../val/performance
2119    limits:
2120      sparc/leon3:
2121        DirtyCache:
2122          max-upper-bound: 0.000005
2123          mean-upper-bound: 0.000005
2124        FullCache:
2125          max-upper-bound: 0.000005
2126          mean-upper-bound: 0.000005
2127        HotCache:
2128          max-upper-bound: 0.000005
2129          mean-upper-bound: 0.000005
2130        Load/1:
2131          max-upper-bound: 0.00001
2132          mean-upper-bound: 0.00001
2133        Load/2:
2134          max-upper-bound: 0.00001
2135          mean-upper-bound: 0.00001
2136        Load/3:
2137          max-upper-bound: 0.00001
2138          mean-upper-bound: 0.00001
2139        Load/4:
2140          max-upper-bound: 0.00001
2141          mean-upper-bound: 0.00001
2142    params: {}
2143    rationale: null
2144    references: []
2145    test-body:
2146      brief: |
2147        Get a buffer.
2148      code: |
2149        ctx->status = rtems_partition_get_buffer( ctx->part_many, &ctx->buffer );
2150      description: null
2151    test-cleanup: null
2152    test-prepare: null
2153    test-setup: null
2154    test-teardown:
2155      brief: |
2156        Return the buffer.
2157      code: |
2158        rtems_status_code sc;
2159
2160        T_quiet_rsc_success( ctx->status );
2161
2162        sc = rtems_partition_return_buffer( ctx->part_many, ctx->buffer );
2163        T_quiet_rsc_success( sc );
2164
2165        return tic == toc;
2166      description: null
2167    text: |
2168      When a partition has exactly ${../val/performance:/params/buffer-count} free
2169      buffers, the ${.:limit-kind} runtime of exactly
2170      ${../val/performance:/params/sample-count} successful calls to
2171      ${../if/get-buffer:/name} in the ${.:/environment} shall be
2172      ${.:limit-condition}.
2173    non-functional-type: performance-runtime
2174    requirement-type: non-functional
2175    type: requirement
2176
2177.. _SpecTypeRequirementValidationItemType:
2178
2179Requirement Validation Item Type
2180^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2181
2182This type refines the :ref:`SpecTypeRootItemType` through the ``type``
2183attribute if the value is ``validation``. This set of attributes provides a
2184requirement validation evidence.  The item shall have exactly one link to the
2185validated requirement with the :ref:`SpecTypeRequirementValidationLinkRole`.
2186All explicit attributes shall be specified. The explicit attributes for this
2187type are:
2188
2189method
2190    The attribute value shall be a :ref:`SpecTypeRequirementValidationMethod`.
2191    Validation by test is done through :ref:`SpecTypeTestCaseItemType` items.
2192
2193text
2194    The attribute value shall be a string. It shall provide the validation
2195    evidence depending on the validation method:
2196
2197    * *By analysis*: A statement shall be provided how the requirement is met,
2198      by analysing static properties of the :term:`software product`.
2199
2200    * *By inspection*: A statement shall be provided how the requirement is
2201      met, by inspection of the :term:`source code`.
2202
2203    * *By review of design*: A rationale shall be provided to demonstrate how
2204      the requirement is satisfied implicitly by the software design.
2205
2206This type is refined by the following types:
2207
2208* :ref:`SpecTypeRequirementValidationMethod`
2209
2210.. _SpecTypeRequirementValidationMethod:
2211
2212Requirement Validation Method
2213^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2214
2215This type refines the following types:
2216
2217* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute
2218  if the value is ``by-analysis``
2219
2220* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute
2221  if the value is ``by-inspection``
2222
2223* :ref:`SpecTypeRequirementValidationItemType` through the ``method`` attribute
2224  if the value is ``by-review-of-design``
2225
2226.. _SpecTypeRuntimeMeasurementTestItemType:
2227
2228Runtime Measurement Test Item Type
2229^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2230
2231This type refines the :ref:`SpecTypeRootItemType` through the ``type``
2232attribute if the value is ``runtime-measurement-test``. This set of attributes
2233specifies a runtime measurement test case. All explicit attributes shall be
2234specified. The explicit attributes for this type are:
2235
2236params
2237    The attribute value shall be a
2238    :ref:`SpecTypeRuntimeMeasurementParameterSet`.
2239
2240test-brief
2241    The attribute value shall be an optional string. If the value is present,
2242    then it shall be the test case brief description.
2243
2244test-cleanup
2245    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
2246    value is present, then it shall be the measure runtime request cleanup
2247    method.  The method is called after each measure runtime request.
2248
2249test-context
2250    The attribute value shall be a list. Each list element shall be a
2251    :ref:`SpecTypeTestContextMember`.
2252
2253test-context-support
2254    The attribute value shall be an optional string. If the value is present,
2255    then it shall be the test context support code.  The context support code
2256    is placed at file scope before the test context definition.
2257
2258test-description
2259    The attribute value shall be an optional string. If the value is present,
2260    then it shall be the test case description.
2261
2262test-includes
2263    The attribute value shall be a list of strings. It shall be a list of
2264    header files included via ``#include <...>``.
2265
2266test-local-includes
2267    The attribute value shall be a list of strings. It shall be a list of
2268    header files included via ``#include "..."``.
2269
2270test-prepare
2271    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
2272    value is present, then it shall be the measure runtime request prepare
2273    method.  The method is called before each measure runtime request.
2274
2275test-setup
2276    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
2277    value is present, then it shall be the test case setup fixture method.
2278
2279test-stop
2280    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
2281    value is present, then it shall be the test case stop fixture method.
2282
2283test-support
2284    The attribute value shall be an optional string. If the value is present,
2285    then it shall be the test case support code. The support code is placed at
2286    file scope before the test case code.
2287
2288test-target
2289    The attribute value shall be a string. It shall be the path to the
2290    generated test case source file.
2291
2292test-teardown
2293    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`. If the
2294    value is present, then it shall be the test case teardown fixture method.
2295
2296.. _SpecTypeSpecificationItemType:
2297
2298Specification Item Type
2299^^^^^^^^^^^^^^^^^^^^^^^
2300
2301This type refines the :ref:`SpecTypeRootItemType` through the ``type``
2302attribute if the value is ``spec``. This set of attributes specifies
2303specification types. All explicit attributes shall be specified. The explicit
2304attributes for this type are:
2305
2306spec-description
2307    The attribute value shall be an optional string. It shall be the
2308    description of the specification type.
2309
2310spec-example
2311    The attribute value shall be an optional string. If the value is present,
2312    then it shall be an example of the specification type.
2313
2314spec-info
2315    The attribute value shall be a :ref:`SpecTypeSpecificationInformation`.
2316
2317spec-name
2318    The attribute value shall be an optional string. It shall be the human
2319    readable name of the specification type.
2320
2321spec-type
2322    The attribute value shall be a :ref:`SpecTypeName`. It shall the
2323    specification type.
2324
2325Please have a look at the following example:
2326
2327.. code-block:: yaml
2328
2329    SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
2330    copyrights:
2331    - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
2332    enabled-by: true
2333    links:
2334    - role: spec-member
2335      uid: root
2336    - role: spec-refinement
2337      spec-key: type
2338      spec-value: example
2339      uid: root
2340    spec-description: null
2341    spec-example: null
2342    spec-info:
2343      dict:
2344        attributes:
2345          an-example-attribute:
2346            description: |
2347              It shall be an example.
2348            spec-type: optional-str
2349          example-number:
2350            description: |
2351              It shall be the example number.
2352            spec-type: int
2353        description: |
2354          This set of attributes specifies an example.
2355        mandatory-attributes: all
2356    spec-name: Example Item Type
2357    spec-type: spec
2358    type: spec
2359
2360.. _SpecTypeTestCaseItemType:
2361
2362Test Case Item Type
2363^^^^^^^^^^^^^^^^^^^
2364
2365This type refines the :ref:`SpecTypeRootItemType` through the ``type``
2366attribute if the value is ``test-case``. This set of attributes specifies a
2367test case. All explicit attributes shall be specified. The explicit attributes
2368for this type are:
2369
2370test-actions
2371    The attribute value shall be a list. Each list element shall be a
2372    :ref:`SpecTypeTestCaseAction`.
2373
2374test-brief
2375    The attribute value shall be a string. It shall be the test case brief
2376    description.
2377
2378test-context
2379    The attribute value shall be a list. Each list element shall be a
2380    :ref:`SpecTypeTestContextMember`.
2381
2382test-context-support
2383    The attribute value shall be an optional string. If the value is present,
2384    then it shall be the test context support code.  The context support code
2385    is placed at file scope before the test context definition.
2386
2387test-description
2388    The attribute value shall be an optional string. It shall be the test case
2389    description.
2390
2391test-header
2392    The attribute value shall be a :ref:`SpecTypeTestHeader`.
2393
2394test-includes
2395    The attribute value shall be a list of strings. It shall be a list of
2396    header files included via ``#include <...>``.
2397
2398test-local-includes
2399    The attribute value shall be a list of strings. It shall be a list of
2400    header files included via ``#include "..."``.
2401
2402test-setup
2403    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.
2404
2405test-stop
2406    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.
2407
2408test-support
2409    The attribute value shall be an optional string. If the value is present,
2410    then it shall be the test case support code. The support code is placed at
2411    file scope before the test case code.
2412
2413test-target
2414    The attribute value shall be a string. It shall be the path to the
2415    generated target test case source file.
2416
2417test-teardown
2418    The attribute value shall be a :ref:`SpecTypeTestSupportMethod`.
2419
2420.. _SpecTypeTestPlatformItemType:
2421
2422Test Platform Item Type
2423^^^^^^^^^^^^^^^^^^^^^^^
2424
2425This type refines the :ref:`SpecTypeRootItemType` through the ``type``
2426attribute if the value is ``test-platform``. Please note:
2427
2428.. warning::
2429
2430     This item type is work in progress.
2431
2432This set of attributes specifies a test platform. All explicit attributes shall
2433be specified. The explicit attributes for this type are:
2434
2435description
2436    The attribute value shall be a string. It shall be the description of the
2437    test platform.
2438
2439name
2440    The attribute value shall be a string. It shall be the human readable name
2441    of the test platform.
2442
2443.. _SpecTypeTestProcedureItemType:
2444
2445Test Procedure Item Type
2446^^^^^^^^^^^^^^^^^^^^^^^^
2447
2448This type refines the :ref:`SpecTypeRootItemType` through the ``type``
2449attribute if the value is ``test-procedure``. Please note:
2450
2451.. warning::
2452
2453     This item type is work in progress.
2454
2455This set of attributes specifies a test procedure. All explicit attributes
2456shall be specified. The explicit attributes for this type are:
2457
2458name
2459    The attribute value shall be a string. It shall be the human readable name
2460    of the test procedure.
2461
2462purpose
2463    The attribute value shall be a string. It shall state the purpose of the
2464    test procedure.
2465
2466steps
2467    The attribute value shall be a string. It shall describe the steps of the
2468    test procedure execution.
2469
2470.. _SpecTypeTestSuiteItemType:
2471
2472Test Suite Item Type
2473^^^^^^^^^^^^^^^^^^^^
2474
2475This type refines the following types:
2476
2477* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is
2478  ``memory-benchmark``
2479
2480* :ref:`SpecTypeRootItemType` through the ``type`` attribute if the value is
2481  ``test-suite``
2482
2483This set of attributes specifies a test suite. All explicit attributes shall be
2484specified. The explicit attributes for this type are:
2485
2486test-brief
2487    The attribute value shall be a string. It shall be the test suite brief
2488    description.
2489
2490test-code
2491    The attribute value shall be a string. It shall be the test suite code.
2492    The test suite code is placed at file scope in the target source file.
2493
2494test-description
2495    The attribute value shall be an optional string. It shall be the test suite
2496    description.
2497
2498test-includes
2499    The attribute value shall be a list of strings. It shall be a list of
2500    header files included via ``#include <...>``.
2501
2502test-local-includes
2503    The attribute value shall be a list of strings. It shall be a list of
2504    header files included via ``#include "..."``.
2505
2506test-suite-name
2507    The attribute value shall be a string. It shall be the name of the test
2508    suite.
2509
2510test-target
2511    The attribute value shall be a string. It shall be the path to the
2512    generated target test suite source file.
2513
2514.. _ReqEngSpecificationAttributeSetsAndValueTypes:
2515
2516Specification Attribute Sets and Value Types
2517--------------------------------------------
2518
2519.. _SpecTypeActionRequirementBooleanExpression:
2520
2521Action Requirement Boolean Expression
2522^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2523
2524A value of this type is a boolean expression.
2525
2526A value of this type shall be of one of the following variants:
2527
2528* The value may be a set of attributes. Each attribute defines an operator.
2529  Exactly one of the explicit attributes shall be specified. The explicit
2530  attributes for this type are:
2531
2532  and
2533      The attribute value shall be a list. Each list element shall be an
2534      :ref:`SpecTypeActionRequirementBooleanExpression`. The *and* operator
2535      evaluates to the *logical and* of the evaluation results of the
2536      expressions in the list.
2537
2538  not
2539      The attribute value shall be an
2540      :ref:`SpecTypeActionRequirementBooleanExpression`. The *not* operator
2541      evaluates to the *logical not* of the evaluation results of the
2542      expression.
2543
2544  or
2545      The attribute value shall be a list. Each list element shall be an
2546      :ref:`SpecTypeActionRequirementBooleanExpression`. The *or* operator
2547      evaluates to the *logical or* of the evaluation results of the
2548      expressions in the list.
2549
2550  post-conditions
2551      The attribute value shall be an
2552      :ref:`SpecTypeActionRequirementExpressionConditionSet`. The
2553      *post-conditions* operator evaluates to true, if the post-condition
2554      states of the associated transition are contained in the specified
2555      post-condition set, otherwise to false.
2556
2557  pre-conditions
2558      The attribute value shall be an
2559      :ref:`SpecTypeActionRequirementExpressionConditionSet`. The
2560      *pre-conditions* operator evaluates to true, if the pre-condition states
2561      of the associated transition are contained in the specified pre-condition
2562      set, otherwise to false.
2563
2564* The value may be a list. Each list element shall be an
2565  :ref:`SpecTypeActionRequirementBooleanExpression`. This list of expressions
2566  evaluates to the *logical or* of the evaluation results of the expressions in
2567  the list.
2568
2569This type is used by the following types:
2570
2571* :ref:`SpecTypeActionRequirementBooleanExpression`
2572
2573* :ref:`SpecTypeActionRequirementExpression`
2574
2575.. _SpecTypeActionRequirementCondition:
2576
2577Action Requirement Condition
2578^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2579
2580This set of attributes defines an action pre-condition or post-condition. All
2581explicit attributes shall be specified. The explicit attributes for this type
2582are:
2583
2584name
2585    The attribute value shall be an :ref:`SpecTypeActionRequirementName`.
2586
2587states
2588    The attribute value shall be a list. Each list element shall be an
2589    :ref:`SpecTypeActionRequirementState`.
2590
2591test-epilogue
2592    The attribute value shall be an optional string. If the value is present,
2593    then it shall be the test epilogue code. The epilogue code is placed in the
2594    test condition preparation or check before the state-specific code.  The
2595    code may use a local variable ``ctx`` which points to the test context, see
2596    :ref:`SpecTypeTestContextMember`.
2597
2598test-prologue
2599    The attribute value shall be an optional string. If the value is present,
2600    then it shall be the test prologue code. The prologue code is placed in the
2601    test condition preparation or check after the state-specific code.  The
2602    code may use a local variable ``ctx`` which points to the test context, see
2603    :ref:`SpecTypeTestContextMember`.
2604
2605This type is used by the following types:
2606
2607* :ref:`SpecTypeActionRequirementItemType`
2608
2609.. _SpecTypeActionRequirementExpression:
2610
2611Action Requirement Expression
2612^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2613
2614This set of attributes defines an expression which may define the state of a
2615post-condition.  The ``else`` and ``specified-by`` shall be used individually.
2616The ``if`` and ``then`` or ``then-specified-by`` expressions shall be used
2617together. At least one of the explicit attributes shall be specified. The
2618explicit attributes for this type are:
2619
2620else
2621    The attribute value shall be an
2622    :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name
2623    of the state of the post-condition.
2624
2625if
2626    The attribute value shall be an
2627    :ref:`SpecTypeActionRequirementBooleanExpression`. If the boolean
2628    expression evaluates to true, then the state is defined according to the
2629    ``then`` attribute value.
2630
2631specified-by
2632    The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It
2633    shall be the name of a pre-condition.  The name of the state of the
2634    pre-condition in the associated transition defines the name of the state of
2635    the post-condition.
2636
2637then
2638    The attribute value shall be an
2639    :ref:`SpecTypeActionRequirementExpressionStateName`. It shall be the name
2640    of the state of the post-condition.
2641
2642then-specified-by
2643    The attribute value shall be an :ref:`SpecTypeActionRequirementName`. It
2644    shall be the name of a pre-condition.  The name of the state of the
2645    pre-condition in the associated transition defines the name of the state of
2646    the post-condition.
2647
2648.. _SpecTypeActionRequirementExpressionConditionSet:
2649
2650Action Requirement Expression Condition Set
2651^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2652
2653This set of attributes defines for the specified conditions a set of states.
2654Generic attributes may be specified. Each generic attribute key shall be an
2655:ref:`SpecTypeActionRequirementName`. Each generic attribute value shall be an
2656:ref:`SpecTypeActionRequirementExpressionStateSet`. There shall be at most one
2657generic attribute key for each condition. The key name shall be the condition
2658name.  The value of each generic attribute shall be a set of states of the
2659condition.
2660
2661This type is used by the following types:
2662
2663* :ref:`SpecTypeActionRequirementBooleanExpression`
2664
2665.. _SpecTypeActionRequirementExpressionStateName:
2666
2667Action Requirement Expression State Name
2668^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2669
2670The value shall be a string. It shall be the name of a state of the condition
2671or ``N/A`` if the condition is not applicable. The value
2672
2673* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
2674
2675* or, shall be equal to "``N/A``".
2676
2677This type is used by the following types:
2678
2679* :ref:`SpecTypeActionRequirementExpression`
2680
2681.. _SpecTypeActionRequirementExpressionStateSet:
2682
2683Action Requirement Expression State Set
2684^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2685
2686A value of this type shall be of one of the following variants:
2687
2688* The value may be a list. Each list element shall be an
2689  :ref:`SpecTypeActionRequirementExpressionStateName`. The list defines a set
2690  of states of the condition.
2691
2692* The value may be a string. It shall be the name of a state of the condition
2693  or ``N/A`` if the condition is not applicable. The value
2694
2695  * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
2696
2697  * or, shall be equal to "``N/A``".
2698
2699This type is used by the following types:
2700
2701* :ref:`SpecTypeActionRequirementExpressionConditionSet`
2702
2703.. _SpecTypeActionRequirementName:
2704
2705Action Requirement Name
2706^^^^^^^^^^^^^^^^^^^^^^^
2707
2708The value shall be a string. It shall be the name of a condition or a state of
2709a condition used to define pre-conditions and post-conditions of an action
2710requirement.  It shall be formatted in CamelCase.  It should be brief and
2711abbreviated. The rationale for this is that the names are used in tables and
2712the horizontal space is limited by the page width.  The more conditions you
2713have in an action requirement, the shorter the names should be.  The name
2714``NA`` is reserved and indicates that a condition is not applicable. The value
2715
2716* shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
2717
2718* and, shall be not equal to "``NA``".
2719
2720This type is used by the following types:
2721
2722* :ref:`SpecTypeActionRequirementCondition`
2723
2724* :ref:`SpecTypeActionRequirementExpressionConditionSet`
2725
2726* :ref:`SpecTypeActionRequirementExpression`
2727
2728* :ref:`SpecTypeActionRequirementSkipReasons`
2729
2730* :ref:`SpecTypeActionRequirementState`
2731
2732* :ref:`SpecTypeActionRequirementTransitionPostConditions`
2733
2734* :ref:`SpecTypeActionRequirementTransitionPreConditions`
2735
2736.. _SpecTypeActionRequirementSkipReasons:
2737
2738Action Requirement Skip Reasons
2739^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2740
2741This set of attributes specifies skip reasons used to justify why transitions
2742in the transition map are skipped. Generic attributes may be specified. Each
2743generic attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each
2744generic attribute value shall be a string. The key defines the name of a skip
2745reason.  The name can be used in
2746:ref:`SpecTypeActionRequirementTransitionPostConditions` to skip the
2747corresponding transitions.  The value shall give a reason why the transitions
2748are skipped.
2749
2750This type is used by the following types:
2751
2752* :ref:`SpecTypeActionRequirementItemType`
2753
2754.. _SpecTypeActionRequirementState:
2755
2756Action Requirement State
2757^^^^^^^^^^^^^^^^^^^^^^^^
2758
2759This set of attributes defines an action pre-condition or post-condition state.
2760All explicit attributes shall be specified. The explicit attributes for this
2761type are:
2762
2763name
2764    The attribute value shall be an :ref:`SpecTypeActionRequirementName`.
2765
2766test-code
2767    The attribute value shall be a string. It shall be the test code to prepare
2768    or check the state of the condition.  The code may use a local variable
2769    ``ctx`` which points to the test context, see
2770    :ref:`SpecTypeTestContextMember`.
2771
2772text
2773    The attribute value shall be a :ref:`SpecTypeRequirementText`. It shall
2774    define the state of the condition.
2775
2776This type is used by the following types:
2777
2778* :ref:`SpecTypeActionRequirementCondition`
2779
2780.. _SpecTypeActionRequirementTransition:
2781
2782Action Requirement Transition
2783^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2784
2785This set of attributes defines the transition from multiple sets of states of
2786pre-conditions to a set of states of post-conditions through an action in an
2787action requirement.  The ability to specify multiple sets of states of
2788pre-conditions which result in a common set of post-conditions may allow a more
2789compact specification of the transition map.  For example, let us suppose you
2790want to specify the action of a function with a pointer parameter.  The
2791function performs an early check that the pointer is NULL and in this case
2792returns an error code.  The pointer condition dominates the action outcome if
2793the pointer is NULL.  Other pre-condition states can be simply set to ``all``
2794for this transition. All explicit attributes shall be specified. The explicit
2795attributes for this type are:
2796
2797enabled-by
2798    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. The
2799    transition map may be customized to support configuration variants through
2800    this attribute.  The default transitions (``enabled-by: true``) shall be
2801    specified before the customized variants in the list.
2802
2803post-conditions
2804    The attribute value shall be an
2805    :ref:`SpecTypeActionRequirementTransitionPostConditions`.
2806
2807pre-conditions
2808    The attribute value shall be an
2809    :ref:`SpecTypeActionRequirementTransitionPreConditions`.
2810
2811This type is used by the following types:
2812
2813* :ref:`SpecTypeActionRequirementItemType`
2814
2815.. _SpecTypeActionRequirementTransitionPostConditionState:
2816
2817Action Requirement Transition Post-Condition State
2818^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2819
2820A value of this type shall be of one of the following variants:
2821
2822* The value may be a list. Each list element shall be an
2823  :ref:`SpecTypeActionRequirementExpression`. The list contains expressions to
2824  define the state of the corresponding post-condition.
2825
2826* The value may be a string. It shall be the name of a state of the
2827  corresponding post-condition or ``N/A`` if the post-condition is not
2828  applicable. The value
2829
2830  * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
2831
2832  * or, shall be equal to "``N/A``".
2833
2834This type is used by the following types:
2835
2836* :ref:`SpecTypeActionRequirementTransitionPostConditions`
2837
2838.. _SpecTypeActionRequirementTransitionPostConditions:
2839
2840Action Requirement Transition Post-Conditions
2841^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2842
2843A value of this type shall be of one of the following variants:
2844
2845* The value may be a set of attributes. This set of attributes defines for each
2846  post-condition the state after the action for a transition in an action
2847  requirement. Generic attributes may be specified. Each generic attribute key
2848  shall be an :ref:`SpecTypeActionRequirementName`. Each generic attribute
2849  value shall be an
2850  :ref:`SpecTypeActionRequirementTransitionPostConditionState`. There shall be
2851  exactly one generic attribute key for each post-condition.  The key name
2852  shall be the post-condition name.  The value of each generic attribute shall
2853  be the state of the post-condition or ``N/A`` if the post-condition is not
2854  applicable.
2855
2856* The value may be a string. It shall be the name of a skip reason.  If a skip
2857  reason is given instead of a listing of post-condition states, then this
2858  transition is skipped and no test code runs for this transition. The value
2859
2860  * shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``",
2861
2862  * and, shall be not equal to "``NA``".
2863
2864This type is used by the following types:
2865
2866* :ref:`SpecTypeActionRequirementTransition`
2867
2868.. _SpecTypeActionRequirementTransitionPreConditionStateSet:
2869
2870Action Requirement Transition Pre-Condition State Set
2871^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2872
2873A value of this type shall be of one of the following variants:
2874
2875* The value may be a list. Each list element shall be an
2876  :ref:`SpecTypeActionRequirementName`. The list defines the set of states of
2877  the pre-condition in the transition.
2878
2879* The value may be a string. The value ``all`` represents all states of the
2880  pre-condition in this transition.  The value ``N/A`` marks the pre-condition
2881  as not applicable in this transition. The value shall be an element of
2882
2883  * "``all``", and
2884
2885  * "``N/A``".
2886
2887This type is used by the following types:
2888
2889* :ref:`SpecTypeActionRequirementTransitionPreConditions`
2890
2891.. _SpecTypeActionRequirementTransitionPreConditions:
2892
2893Action Requirement Transition Pre-Conditions
2894^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2895
2896A value of this type shall be of one of the following variants:
2897
2898* The value may be a set of attributes. This set of attributes defines for each
2899  pre-condition the set of states before the action for a transition in an
2900  action requirement. Generic attributes may be specified. Each generic
2901  attribute key shall be an :ref:`SpecTypeActionRequirementName`. Each generic
2902  attribute value shall be an
2903  :ref:`SpecTypeActionRequirementTransitionPreConditionStateSet`. There shall
2904  be exactly one generic attribute key for each pre-condition.  The key name
2905  shall be the pre-condition name.  The value of each generic attribute shall
2906  be a set of states of the pre-condition.
2907
2908* The value may be a string. If this name is specified instead of explicit
2909  pre-condition states, then the post-condition states of this entry are used
2910  to define all remaining transitions of the map. The value shall be equal to
2911  "``default``".
2912
2913This type is used by the following types:
2914
2915* :ref:`SpecTypeActionRequirementTransition`
2916
2917.. _SpecTypeApplicationConfigurationOptionName:
2918
2919Application Configuration Option Name
2920^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2921
2922The value shall be a string. It shall be the name of an application
2923configuration option. The value shall match with the regular expression
2924"``^(CONFIGURE_|BSP_)[A-Z0-9_]+$``".
2925
2926This type is used by the following types:
2927
2928* :ref:`SpecTypeApplicationConfigurationOptionItemType`
2929
2930.. _SpecTypeBooleanOrIntegerOrString:
2931
2932Boolean or Integer or String
2933^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2934
2935A value of this type shall be of one of the following variants:
2936
2937* The value may be a boolean.
2938
2939* The value may be an integer number.
2940
2941* The value may be a string.
2942
2943This type is used by the following types:
2944
2945* :ref:`SpecTypeBuildOptionAction`
2946
2947* :ref:`SpecTypeInterfaceReturnValue`
2948
2949.. _SpecTypeBuildAssemblerOption:
2950
2951Build Assembler Option
2952^^^^^^^^^^^^^^^^^^^^^^
2953
2954The value shall be a string. It shall be an option for the assembler.  The
2955options are used to assemble the sources of this item.  The options defined by
2956this attribute succeed the options presented to the item by the build item
2957context.
2958
2959This type is used by the following types:
2960
2961* :ref:`SpecTypeBuildScriptItemType`
2962
2963* :ref:`SpecTypeBuildStartFileItemType`
2964
2965.. _SpecTypeBuildCCompilerOption:
2966
2967Build C Compiler Option
2968^^^^^^^^^^^^^^^^^^^^^^^
2969
2970The value shall be a string. It shall be an option for the C compiler.  The
2971options are used to compile the sources of this item.  The options defined by
2972this attribute succeed the options presented to the item by the build item
2973context.
2974
2975This type is used by the following types:
2976
2977* :ref:`SpecTypeBuildAdaTestProgramItemType`
2978
2979* :ref:`SpecTypeBuildBSPItemType`
2980
2981* :ref:`SpecTypeBuildLibraryItemType`
2982
2983* :ref:`SpecTypeBuildObjectsItemType`
2984
2985* :ref:`SpecTypeBuildOptionCCompilerCheckAction`
2986
2987* :ref:`SpecTypeBuildScriptItemType`
2988
2989* :ref:`SpecTypeBuildTestProgramItemType`
2990
2991.. _SpecTypeBuildCPreprocessorOption:
2992
2993Build C Preprocessor Option
2994^^^^^^^^^^^^^^^^^^^^^^^^^^^
2995
2996The value shall be a string. It shall be an option for the C preprocessor.  The
2997options are used to preprocess the sources of this item.  The options defined
2998by this attribute succeed the options presented to the item by the build item
2999context.
3000
3001This type is used by the following types:
3002
3003* :ref:`SpecTypeBuildAdaTestProgramItemType`
3004
3005* :ref:`SpecTypeBuildBSPItemType`
3006
3007* :ref:`SpecTypeBuildLibraryItemType`
3008
3009* :ref:`SpecTypeBuildObjectsItemType`
3010
3011* :ref:`SpecTypeBuildScriptItemType`
3012
3013* :ref:`SpecTypeBuildStartFileItemType`
3014
3015* :ref:`SpecTypeBuildTestProgramItemType`
3016
3017.. _SpecTypeBuildCXXCompilerOption:
3018
3019Build C++ Compiler Option
3020^^^^^^^^^^^^^^^^^^^^^^^^^
3021
3022The value shall be a string. It shall be an option for the C++ compiler.  The
3023options are used to compile the sources of this item.  The options defined by
3024this attribute succeed the options presented to the item by the build item
3025context.
3026
3027This type is used by the following types:
3028
3029* :ref:`SpecTypeBuildLibraryItemType`
3030
3031* :ref:`SpecTypeBuildObjectsItemType`
3032
3033* :ref:`SpecTypeBuildOptionCXXCompilerCheckAction`
3034
3035* :ref:`SpecTypeBuildScriptItemType`
3036
3037* :ref:`SpecTypeBuildTestProgramItemType`
3038
3039.. _SpecTypeBuildDependencyLinkRole:
3040
3041Build Dependency Link Role
3042^^^^^^^^^^^^^^^^^^^^^^^^^^
3043
3044This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
3045value is ``build-dependency``. It defines the build dependency role of links.
3046
3047.. _SpecTypeBuildIncludePath:
3048
3049Build Include Path
3050^^^^^^^^^^^^^^^^^^
3051
3052The value shall be a string. It shall be a path to header files.  The path is
3053used by the C preprocessor to search for header files.  It succeeds the
3054includes presented to the item by the build item context.  For an
3055:ref:`SpecTypeBuildGroupItemType` item the includes are visible to all items
3056referenced by the group item.  For :ref:`SpecTypeBuildBSPItemType`,
3057:ref:`SpecTypeBuildObjectsItemType`, :ref:`SpecTypeBuildLibraryItemType`,
3058:ref:`SpecTypeBuildStartFileItemType`, and
3059:ref:`SpecTypeBuildTestProgramItemType` items the includes are only visible to
3060the sources specified by the item itself and they do not propagate to
3061referenced items.
3062
3063This type is used by the following types:
3064
3065* :ref:`SpecTypeBuildAdaTestProgramItemType`
3066
3067* :ref:`SpecTypeBuildBSPItemType`
3068
3069* :ref:`SpecTypeBuildGroupItemType`
3070
3071* :ref:`SpecTypeBuildLibraryItemType`
3072
3073* :ref:`SpecTypeBuildObjectsItemType`
3074
3075* :ref:`SpecTypeBuildScriptItemType`
3076
3077* :ref:`SpecTypeBuildStartFileItemType`
3078
3079* :ref:`SpecTypeBuildTestProgramItemType`
3080
3081.. _SpecTypeBuildInstallDirective:
3082
3083Build Install Directive
3084^^^^^^^^^^^^^^^^^^^^^^^
3085
3086This set of attributes specifies files installed by a build item. All explicit
3087attributes shall be specified. The explicit attributes for this type are:
3088
3089destination
3090    The attribute value shall be a string. It shall be the install destination
3091    directory.
3092
3093source
3094    The attribute value shall be a list of strings. It shall be the list of
3095    source files to be installed in the destination directory.  The path to a
3096    source file shall be relative to the directory of the :file:`wscript`.
3097
3098This type is used by the following types:
3099
3100* :ref:`SpecTypeBuildBSPItemType`
3101
3102* :ref:`SpecTypeBuildGroupItemType`
3103
3104* :ref:`SpecTypeBuildLibraryItemType`
3105
3106* :ref:`SpecTypeBuildObjectsItemType`
3107
3108.. _SpecTypeBuildInstallPath:
3109
3110Build Install Path
3111^^^^^^^^^^^^^^^^^^
3112
3113A value of this type shall be of one of the following variants:
3114
3115* There may be no value (null).
3116
3117* The value may be a string. It shall be the installation path of a
3118  :ref:`SpecTypeBuildTarget`.
3119
3120This type is used by the following types:
3121
3122* :ref:`SpecTypeBuildConfigurationFileItemType`
3123
3124* :ref:`SpecTypeBuildConfigurationHeaderItemType`
3125
3126* :ref:`SpecTypeBuildLibraryItemType`
3127
3128* :ref:`SpecTypeBuildStartFileItemType`
3129
3130.. _SpecTypeBuildLinkStaticLibraryDirective:
3131
3132Build Link Static Library Directive
3133^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3134
3135The value shall be a string. It shall be an external static library identifier.
3136The library is used to link programs referenced by this item, e.g. ``m`` for
3137``libm.a``.  The library is added to the build command through the ``stlib``
3138attribute. It shall not be used for internal static libraries.  Internal static
3139libraries shall be specified through the ``use-after`` and ``use-before``
3140attributes to enable a proper build dependency tracking.
3141
3142This type is used by the following types:
3143
3144* :ref:`SpecTypeBuildAdaTestProgramItemType`
3145
3146* :ref:`SpecTypeBuildScriptItemType`
3147
3148* :ref:`SpecTypeBuildTestProgramItemType`
3149
3150.. _SpecTypeBuildLinkerOption:
3151
3152Build Linker Option
3153^^^^^^^^^^^^^^^^^^^
3154
3155The value shall be a string. It shall be an option for the linker.  The options
3156are used to link executables.  The options defined by this attribute succeed
3157the options presented to the item by the build item context.
3158
3159This type is used by the following types:
3160
3161* :ref:`SpecTypeBuildAdaTestProgramItemType`
3162
3163* :ref:`SpecTypeBuildScriptItemType`
3164
3165* :ref:`SpecTypeBuildTestProgramItemType`
3166
3167.. _SpecTypeBuildOptionAction:
3168
3169Build Option Action
3170^^^^^^^^^^^^^^^^^^^
3171
3172This set of attributes specifies a build option action. Exactly one of the
3173explicit attributes shall be specified. The explicit attributes for this type
3174are:
3175
3176append-test-cppflags
3177    The attribute value shall be a string. It shall be the name of a test
3178    program.  The action appends the action value to the ``CPPFLAGS`` of the
3179    test program.  The name shall correspond to the name of a
3180    :ref:`SpecTypeBuildTestProgramItemType` item. Due to the processing order
3181    of items, there is no way to check if the name specified by the attribute
3182    value is valid.
3183
3184assert-aligned
3185    The attribute value shall be an integer number. The action asserts that the
3186    action value is aligned according to the attribute value.
3187
3188assert-eq
3189    The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. The
3190    action asserts that the action value is equal to the attribute value.
3191
3192assert-ge
3193    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
3194    asserts that the action value is greater than or equal to the attribute
3195    value.
3196
3197assert-gt
3198    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
3199    asserts that the action value is greater than the attribute value.
3200
3201assert-int16
3202    The attribute shall have no value. The action asserts that the action value
3203    is a valid signed 16-bit integer.
3204
3205assert-int32
3206    The attribute shall have no value. The action asserts that the action value
3207    is a valid signed 32-bit integer.
3208
3209assert-int64
3210    The attribute shall have no value. The action asserts that the action value
3211    is a valid signed 64-bit integer.
3212
3213assert-int8
3214    The attribute shall have no value. The action asserts that the action value
3215    is a valid signed 8-bit integer.
3216
3217assert-le
3218    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
3219    asserts that the action value is less than or equal to the attribute value.
3220
3221assert-lt
3222    The attribute value shall be an :ref:`SpecTypeIntegerOrString`. The action
3223    asserts that the action value is less than the attribute value.
3224
3225assert-ne
3226    The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. The
3227    action asserts that the action value is not equal to the attribute value.
3228
3229assert-power-of-two
3230    The attribute shall have no value. The action asserts that the action value
3231    is a power of two.
3232
3233assert-uint16
3234    The attribute shall have no value. The action asserts that the action value
3235    is a valid unsigned 16-bit integer.
3236
3237assert-uint32
3238    The attribute shall have no value. The action asserts that the action value
3239    is a valid unsigned 32-bit integer.
3240
3241assert-uint64
3242    The attribute shall have no value. The action asserts that the action value
3243    is a valid unsigned 64-bit integer.
3244
3245assert-uint8
3246    The attribute shall have no value. The action asserts that the action value
3247    is a valid unsigned 8-bit integer.
3248
3249check-cc
3250    The attribute value shall be a
3251    :ref:`SpecTypeBuildOptionCCompilerCheckAction`.
3252
3253check-cxx
3254    The attribute value shall be a
3255    :ref:`SpecTypeBuildOptionCXXCompilerCheckAction`.
3256
3257define
3258    The attribute value shall be an optional string. The action adds a define
3259    to the configuration set.  If the attribute value is present, then it is
3260    used as the name of the define, otherwise the ``name`` of the item is used.
3261    The value of the define is the action value.  If the action value is a
3262    string, then it is quoted.
3263
3264define-condition
3265    The attribute value shall be an optional string. The action adds a
3266    conditional define to the configuration set.  If the attribute value is
3267    present, then it is used as the name of the define, otherwise the ``name``
3268    of the item is used.  The value of the define is the action value.
3269
3270define-unquoted
3271    The attribute value shall be an optional string. The action adds a define
3272    to the configuration set.  If the attribute value is present, then it is
3273    used as the name of the define, otherwise the ``name`` of the item is used.
3274    The value of the define is the action value.  If the action value is a
3275    string, then it is not quoted.
3276
3277env-append
3278    The attribute value shall be an optional string. The action appends the
3279    action value to an environment of the configuration set.  If the attribute
3280    value is present, then it is used as the name of the environment variable,
3281    otherwise the ``name`` of the item is used.
3282
3283env-assign
3284    The attribute value shall be an optional string. The action assigns the
3285    action value to an environment of the configuration set.  If the attribute
3286    value is present, then it is used as the name of the environment variable,
3287    otherwise the ``name`` of the item is used.
3288
3289env-enable
3290    The attribute value shall be an optional string. If the action value is
3291    true, then a name is appended to the ``ENABLE`` environment variable of the
3292    configuration set.  If the attribute value is present, then it is used as
3293    the name, otherwise the ``name`` of the item is used.
3294
3295find-program
3296    The attribute shall have no value. The action tries to find the program
3297    specified by the action value. Uses the ``${PATH}`` to find the program.
3298    Returns the result of the find operation, e.g. a path to the program.
3299
3300find-tool
3301    The attribute shall have no value. The action tries to find the tool
3302    specified by the action value. Uses the tool paths specified by the
3303    ``--rtems-tools`` command line option.  Returns the result of the find
3304    operation, e.g. a path to the program.
3305
3306format-and-define
3307    The attribute value shall be an optional string. The action adds a define
3308    to the configuration set.  If the attribute value is present, then it is
3309    used as the name of the define, otherwise the ``name`` of the item is used.
3310    The value of the define is the action value.  The value is formatted
3311    according to the ``format`` attribute value.
3312
3313get-boolean
3314    The attribute shall have no value. The action gets the action value for
3315    subsequent actions from a configuration file variable named by the items
3316    ``name`` attribute. If no such variable exists in the configuration file,
3317    then the default value is used.  The value is converted to a boolean.
3318
3319get-env
3320    The attribute value shall be a string. The action gets the action value for
3321    subsequent actions from the environment variable of the configuration set
3322    named by the attribute value.
3323
3324get-integer
3325    The attribute shall have no value. The action gets the action value for
3326    subsequent actions from a configuration file variable named by the items
3327    ``name`` attribute. If no such variable exists in the configuration file,
3328    then the default value is used.  The value is converted to an integer.
3329
3330get-string
3331    The attribute shall have no value. The action gets the action value for
3332    subsequent actions from a configuration file variable named by the items
3333    ``name`` attribute. If no such variable exists in the configuration file,
3334    then the default value is used.  The value is converted to a string.
3335
3336get-string-command-line
3337    The attribute value shall be a string. The action gets the action value for
3338    subsequent actions from the value of a command line option named by the
3339    items ``name`` attribute. If no such command line option is present, then
3340    the attribute value is used.  The value is converted to a string.
3341
3342script
3343    The attribute value shall be a string. The action executes the attribute
3344    value with the Python ``eval()`` function in the context of the script
3345    action handler.
3346
3347set-test-state
3348    The attribute value shall be a
3349    :ref:`SpecTypeBuildOptionSetTestStateAction`.
3350
3351set-value
3352    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. The action
3353    sets the action value for subsequent actions to the attribute value.
3354
3355split
3356    The attribute shall have no value. The action splits the action value.
3357
3358substitute
3359    The attribute shall have no value. The action performs a ``${VARIABLE}``
3360    substitution on the action value.  Use ``$$`` for a plain ``$`` character.
3361
3362This type is used by the following types:
3363
3364* :ref:`SpecTypeBuildOptionItemType`
3365
3366.. _SpecTypeBuildOptionCCompilerCheckAction:
3367
3368Build Option C Compiler Check Action
3369^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3370
3371This set of attributes specifies a check done using the C compiler. All
3372explicit attributes shall be specified. The explicit attributes for this type
3373are:
3374
3375cflags
3376    The attribute value shall be a list. Each list element shall be a
3377    :ref:`SpecTypeBuildCCompilerOption`.
3378
3379fragment
3380    The attribute value shall be a string. It shall be a code fragment used to
3381    check the availability of a certain feature through compilation with the C
3382    compiler.  The resulting object is not linked to an executable.
3383
3384message
3385    The attribute value shall be a string. It shall be a description of the
3386    feature to check.
3387
3388This type is used by the following types:
3389
3390* :ref:`SpecTypeBuildOptionAction`
3391
3392.. _SpecTypeBuildOptionCXXCompilerCheckAction:
3393
3394Build Option C++ Compiler Check Action
3395^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3396
3397This set of attributes specifies a check done using the C++ compiler. All
3398explicit attributes shall be specified. The explicit attributes for this type
3399are:
3400
3401cxxflags
3402    The attribute value shall be a list. Each list element shall be a
3403    :ref:`SpecTypeBuildCXXCompilerOption`.
3404
3405fragment
3406    The attribute value shall be a string. It shall be a code fragment used to
3407    check the availability of a certain feature through compilation with the
3408    C++ compiler.  The resulting object is not linked to an executable.
3409
3410message
3411    The attribute value shall be a string. It shall be a description of the
3412    feature to check.
3413
3414This type is used by the following types:
3415
3416* :ref:`SpecTypeBuildOptionAction`
3417
3418.. _SpecTypeBuildOptionDefaultByVariant:
3419
3420Build Option Default by Variant
3421^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3422
3423This set of attributes specifies build option default values by variant. All
3424explicit attributes shall be specified. The explicit attributes for this type
3425are:
3426
3427value
3428    The attribute value shall be a :ref:`SpecTypeBuildOptionValue`. It value
3429    shall be the default value for the matching variants.
3430
3431variants
3432    The attribute value shall be a list of strings. It shall be a list of
3433    Python regular expression matching with the desired variants.
3434
3435This type is used by the following types:
3436
3437* :ref:`SpecTypeBuildOptionItemType`
3438
3439.. _SpecTypeBuildOptionName:
3440
3441Build Option Name
3442^^^^^^^^^^^^^^^^^
3443
3444The value shall be a string. It shall be the name of the build option. The
3445value shall match with the regular expression "``^[a-zA-Z_][a-zA-Z0-9_]*$``".
3446
3447This type is used by the following types:
3448
3449* :ref:`SpecTypeBuildOptionItemType`
3450
3451.. _SpecTypeBuildOptionSetTestStateAction:
3452
3453Build Option Set Test State Action
3454^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3455
3456This set of attributes specifies test states for a set of test programs.
3457Generic attributes may be specified. Each generic attribute key shall be a
3458:ref:`SpecTypeName`. Each generic attribute value shall be a
3459:ref:`SpecTypeBuildTestState`. The keys shall be test program names.  The names
3460shall correspond to the name of a :ref:`SpecTypeBuildTestProgramItemType` or
3461:ref:`SpecTypeBuildAdaTestProgramItemType` item.  Due to the processing order
3462of items, there is no way to check if the name specified by the attribute key
3463is valid.
3464
3465This type is used by the following types:
3466
3467* :ref:`SpecTypeBuildOptionAction`
3468
3469.. _SpecTypeBuildOptionValue:
3470
3471Build Option Value
3472^^^^^^^^^^^^^^^^^^
3473
3474A value of this type shall be of one of the following variants:
3475
3476* The value may be a boolean.
3477
3478* The value may be an integer number.
3479
3480* The value may be a list. Each list element shall be a string.
3481
3482* There may be no value (null).
3483
3484* The value may be a string.
3485
3486This type is used by the following types:
3487
3488* :ref:`SpecTypeBuildOptionAction`
3489
3490* :ref:`SpecTypeBuildOptionDefaultByVariant`
3491
3492* :ref:`SpecTypeBuildOptionItemType`
3493
3494.. _SpecTypeBuildSource:
3495
3496Build Source
3497^^^^^^^^^^^^
3498
3499The value shall be a string. It shall be a source file.  The path to a source
3500file shall be relative to the directory of the :file:`wscript`.
3501
3502This type is used by the following types:
3503
3504* :ref:`SpecTypeBuildAdaTestProgramItemType`
3505
3506* :ref:`SpecTypeBuildBSPItemType`
3507
3508* :ref:`SpecTypeBuildLibraryItemType`
3509
3510* :ref:`SpecTypeBuildObjectsItemType`
3511
3512* :ref:`SpecTypeBuildStartFileItemType`
3513
3514* :ref:`SpecTypeBuildTestProgramItemType`
3515
3516.. _SpecTypeBuildTarget:
3517
3518Build Target
3519^^^^^^^^^^^^
3520
3521The value shall be a string. It shall be the target file path.  The path to the
3522target file shall be relative to the directory of the :file:`wscript`.  The
3523target file is located in the build tree.
3524
3525This type is used by the following types:
3526
3527* :ref:`SpecTypeBuildAdaTestProgramItemType`
3528
3529* :ref:`SpecTypeBuildConfigurationFileItemType`
3530
3531* :ref:`SpecTypeBuildConfigurationHeaderItemType`
3532
3533* :ref:`SpecTypeBuildLibraryItemType`
3534
3535* :ref:`SpecTypeBuildStartFileItemType`
3536
3537* :ref:`SpecTypeBuildTestProgramItemType`
3538
3539.. _SpecTypeBuildTestState:
3540
3541Build Test State
3542^^^^^^^^^^^^^^^^
3543
3544The value shall be a string. This string defines a test state. The value shall
3545be an element of
3546
3547* "``benchmark``",
3548
3549* "``exclude``",
3550
3551* "``expected-fail``",
3552
3553* "``indeterminate``", and
3554
3555* "``user-input``".
3556
3557This type is used by the following types:
3558
3559* :ref:`SpecTypeBuildOptionSetTestStateAction`
3560
3561.. _SpecTypeBuildUseAfterDirective:
3562
3563Build Use After Directive
3564^^^^^^^^^^^^^^^^^^^^^^^^^
3565
3566The value shall be a string. It shall be an internal static library identifier.
3567The library is used to link programs referenced by this item, e.g. ``z`` for
3568``libz.a``.  The library is placed after the use items of the build item
3569context.
3570
3571This type is used by the following types:
3572
3573* :ref:`SpecTypeBuildAdaTestProgramItemType`
3574
3575* :ref:`SpecTypeBuildGroupItemType`
3576
3577* :ref:`SpecTypeBuildScriptItemType`
3578
3579* :ref:`SpecTypeBuildTestProgramItemType`
3580
3581.. _SpecTypeBuildUseBeforeDirective:
3582
3583Build Use Before Directive
3584^^^^^^^^^^^^^^^^^^^^^^^^^^
3585
3586The value shall be a string. It shall be an internal static library identifier.
3587The library is used to link programs referenced by this item, e.g. ``z`` for
3588``libz.a``.  The library is placed before the use items of the build item
3589context.
3590
3591This type is used by the following types:
3592
3593* :ref:`SpecTypeBuildAdaTestProgramItemType`
3594
3595* :ref:`SpecTypeBuildGroupItemType`
3596
3597* :ref:`SpecTypeBuildScriptItemType`
3598
3599* :ref:`SpecTypeBuildTestProgramItemType`
3600
3601.. _SpecTypeConstraintLinkRole:
3602
3603Constraint Link Role
3604^^^^^^^^^^^^^^^^^^^^
3605
3606This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
3607value is ``constraint``. It defines the constraint role of links.  The link
3608target shall be a constraint.
3609
3610.. _SpecTypeCopyright:
3611
3612Copyright
3613^^^^^^^^^
3614
3615The value shall be a string. It shall be a copyright statement of a copyright
3616holder of the specification item. The value
3617
3618* shall match with the regular expression
3619  "``^\s*Copyright\s+\(C\)\s+[0-9]+,\s*[0-9]+\s+.+\s*$``",
3620
3621* or, shall match with the regular expression
3622  "``^\s*Copyright\s+\(C\)\s+[0-9]+\s+.+\s*$``",
3623
3624* or, shall match with the regular expression
3625  "``^\s*Copyright\s+\(C\)\s+.+\s*$``".
3626
3627This type is used by the following types:
3628
3629* :ref:`SpecTypeRootItemType`
3630
3631.. _SpecTypeEnabledByExpression:
3632
3633Enabled-By Expression
3634^^^^^^^^^^^^^^^^^^^^^
3635
3636A value of this type shall be an expression which defines under which
3637conditions the specification item or parts of it are enabled.  The expression
3638is evaluated with the use of an *enabled set*.  This is a set of strings which
3639indicate enabled features.
3640
3641A value of this type shall be of one of the following variants:
3642
3643* The value may be a boolean. This expression evaluates directly to the boolean
3644  value.
3645
3646* The value may be a set of attributes. Each attribute defines an operator.
3647  Exactly one of the explicit attributes shall be specified. The explicit
3648  attributes for this type are:
3649
3650  and
3651      The attribute value shall be a list. Each list element shall be an
3652      :ref:`SpecTypeEnabledByExpression`. The *and* operator evaluates to the
3653      *logical and* of the evaluation results of the expressions in the list.
3654
3655  not
3656      The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. The
3657      *not* operator evaluates to the *logical not* of the evaluation results
3658      of the expression.
3659
3660  or
3661      The attribute value shall be a list. Each list element shall be an
3662      :ref:`SpecTypeEnabledByExpression`. The *or* operator evaluates to the
3663      *logical or* of the evaluation results of the expressions in the list.
3664
3665* The value may be a list. Each list element shall be an
3666  :ref:`SpecTypeEnabledByExpression`. This list of expressions evaluates to the
3667  *logical or* of the evaluation results of the expressions in the list.
3668
3669* The value may be a string. If the value is in the *enabled set*, this
3670  expression evaluates to true, otherwise to false.
3671
3672This type is used by the following types:
3673
3674* :ref:`SpecTypeActionRequirementTransition`
3675
3676* :ref:`SpecTypeEnabledByExpression`
3677
3678* :ref:`SpecTypeInterfaceIncludeLinkRole`
3679
3680* :ref:`SpecTypeRootItemType`
3681
3682Please have a look at the following example:
3683
3684.. code-block:: yaml
3685
3686    enabled-by:
3687      and:
3688      - RTEMS_NETWORKING
3689      - not: RTEMS_SMP
3690
3691.. _SpecTypeFunctionImplementationLinkRole:
3692
3693Function Implementation Link Role
3694^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3695
3696This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
3697value is ``function-implementation``. It defines the function implementation
3698role of links.  It is used to indicate that a
3699:ref:`SpecTypeFunctionalRequirementItemType` item specifies parts of the
3700function.
3701
3702.. _SpecTypeGlossaryMembershipLinkRole:
3703
3704Glossary Membership Link Role
3705^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3706
3707This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
3708value is ``glossary-member``. It defines the glossary membership role of links.
3709
3710.. _SpecTypeIntegerOrString:
3711
3712Integer or String
3713^^^^^^^^^^^^^^^^^
3714
3715A value of this type shall be of one of the following variants:
3716
3717* The value may be an integer number.
3718
3719* The value may be a string.
3720
3721This type is used by the following types:
3722
3723* :ref:`SpecTypeApplicationConfigurationValueOptionItemType`
3724
3725* :ref:`SpecTypeBuildOptionAction`
3726
3727.. _SpecTypeInterfaceBriefDescription:
3728
3729Interface Brief Description
3730^^^^^^^^^^^^^^^^^^^^^^^^^^^
3731
3732A value of this type shall be of one of the following variants:
3733
3734* There may be no value (null).
3735
3736* The value may be a string. It shall be the brief description of the
3737  interface.  It should be a single sentence. The value shall not match with
3738  the regular expression "``\n\n``".
3739
3740This type is used by the following types:
3741
3742* :ref:`SpecTypeInterfaceCompoundItemType`
3743
3744* :ref:`SpecTypeInterfaceCompoundMemberDefinition`
3745
3746* :ref:`SpecTypeInterfaceDefineItemType`
3747
3748* :ref:`SpecTypeInterfaceEnumItemType`
3749
3750* :ref:`SpecTypeInterfaceEnumeratorItemType`
3751
3752* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
3753
3754* :ref:`SpecTypeInterfaceGroupItemType`
3755
3756* :ref:`SpecTypeInterfaceHeaderFileItemType`
3757
3758* :ref:`SpecTypeInterfaceTypedefItemType`
3759
3760* :ref:`SpecTypeInterfaceVariableItemType`
3761
3762.. _SpecTypeInterfaceCompoundDefinitionKind:
3763
3764Interface Compound Definition Kind
3765^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3766
3767The value shall be a string. It specifies how the interface compound is
3768defined.  It may be a typedef only, the struct or union only, or a typedef with
3769a struct or union definition. The value shall be an element of
3770
3771* "``struct-only``",
3772
3773* "``typedef-and-struct``",
3774
3775* "``typedef-and-union``",
3776
3777* "``typedef-only``", and
3778
3779* "``union-only``".
3780
3781This type is used by the following types:
3782
3783* :ref:`SpecTypeInterfaceCompoundItemType`
3784
3785.. _SpecTypeInterfaceCompoundMemberCompound:
3786
3787Interface Compound Member Compound
3788^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3789
3790This type refines the following types:
3791
3792* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind``
3793  attribute if the value is ``struct``
3794
3795* :ref:`SpecTypeInterfaceCompoundMemberDefinition` through the ``kind``
3796  attribute if the value is ``union``
3797
3798This set of attributes specifies an interface compound member compound. All
3799explicit attributes shall be specified. The explicit attributes for this type
3800are:
3801
3802definition
3803    The attribute value shall be a list. Each list element shall be an
3804    :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`.
3805
3806.. _SpecTypeInterfaceCompoundMemberDeclaration:
3807
3808Interface Compound Member Declaration
3809^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3810
3811This type refines the :ref:`SpecTypeInterfaceCompoundMemberDefinition` through
3812the ``kind`` attribute if the value is ``member``. This set of attributes
3813specifies an interface compound member declaration. All explicit attributes
3814shall be specified. The explicit attributes for this type are:
3815
3816definition
3817    The attribute value shall be a string. It shall be the interface compound
3818    member declaration.  On the declaration a context-sensitive substitution of
3819    item variables is performed.
3820
3821.. _SpecTypeInterfaceCompoundMemberDefinition:
3822
3823Interface Compound Member Definition
3824^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3825
3826A value of this type shall be of one of the following variants:
3827
3828* The value may be a set of attributes. This set of attributes specifies an
3829  interface compound member definition. All explicit attributes shall be
3830  specified. The explicit attributes for this type are:
3831
3832  brief
3833      The attribute value shall be an :ref:`SpecTypeInterfaceBriefDescription`.
3834
3835  description
3836      The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
3837
3838  kind
3839      The attribute value shall be a string. It shall be the interface compound
3840      member kind.
3841
3842  name
3843      The attribute value shall be a string. It shall be the interface compound
3844      member name.
3845
3846* There may be no value (null).
3847
3848This type is refined by the following types:
3849
3850* :ref:`SpecTypeInterfaceCompoundMemberCompound`
3851
3852* :ref:`SpecTypeInterfaceCompoundMemberDeclaration`
3853
3854This type is used by the following types:
3855
3856* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`
3857
3858* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`
3859
3860.. _SpecTypeInterfaceCompoundMemberDefinitionDirective:
3861
3862Interface Compound Member Definition Directive
3863^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3864
3865This set of attributes specifies an interface compound member definition
3866directive. All explicit attributes shall be specified. The explicit attributes
3867for this type are:
3868
3869default
3870    The attribute value shall be an
3871    :ref:`SpecTypeInterfaceCompoundMemberDefinition`. The default definition
3872    will be used if no variant-specific definition is enabled.
3873
3874variants
3875    The attribute value shall be a list. Each list element shall be an
3876    :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`.
3877
3878This type is used by the following types:
3879
3880* :ref:`SpecTypeInterfaceCompoundItemType`
3881
3882* :ref:`SpecTypeInterfaceCompoundMemberCompound`
3883
3884.. _SpecTypeInterfaceCompoundMemberDefinitionVariant:
3885
3886Interface Compound Member Definition Variant
3887^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3888
3889This set of attributes specifies an interface compound member definition
3890variant. All explicit attributes shall be specified. The explicit attributes
3891for this type are:
3892
3893definition
3894    The attribute value shall be an
3895    :ref:`SpecTypeInterfaceCompoundMemberDefinition`. The definition will be
3896    used if the expression defined by the ``enabled-by`` attribute evaluates to
3897    true.  In generated header files, the expression is evaluated by the C
3898    preprocessor.
3899
3900enabled-by
3901    The attribute value shall be an
3902    :ref:`SpecTypeInterfaceEnabledByExpression`.
3903
3904This type is used by the following types:
3905
3906* :ref:`SpecTypeInterfaceCompoundMemberDefinitionDirective`
3907
3908.. _SpecTypeInterfaceDefinition:
3909
3910Interface Definition
3911^^^^^^^^^^^^^^^^^^^^
3912
3913A value of this type shall be of one of the following variants:
3914
3915* There may be no value (null).
3916
3917* The value may be a string. It shall be the definition.  On the definition a
3918  context-sensitive substitution of item variables is performed.
3919
3920This type is used by the following types:
3921
3922* :ref:`SpecTypeInterfaceDefinitionDirective`
3923
3924* :ref:`SpecTypeInterfaceDefinitionVariant`
3925
3926.. _SpecTypeInterfaceDefinitionDirective:
3927
3928Interface Definition Directive
3929^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3930
3931This set of attributes specifies an interface definition directive. All
3932explicit attributes shall be specified. The explicit attributes for this type
3933are:
3934
3935default
3936    The attribute value shall be an :ref:`SpecTypeInterfaceDefinition`. The
3937    default definition will be used if no variant-specific definition is
3938    enabled.
3939
3940variants
3941    The attribute value shall be a list. Each list element shall be an
3942    :ref:`SpecTypeInterfaceDefinitionVariant`.
3943
3944This type is used by the following types:
3945
3946* :ref:`SpecTypeInterfaceDefineItemType`
3947
3948* :ref:`SpecTypeInterfaceEnumeratorItemType`
3949
3950* :ref:`SpecTypeInterfaceTypedefItemType`
3951
3952* :ref:`SpecTypeInterfaceVariableItemType`
3953
3954.. _SpecTypeInterfaceDefinitionVariant:
3955
3956Interface Definition Variant
3957^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3958
3959This set of attributes specifies an interface definition variant. All explicit
3960attributes shall be specified. The explicit attributes for this type are:
3961
3962definition
3963    The attribute value shall be an :ref:`SpecTypeInterfaceDefinition`. The
3964    definition will be used if the expression defined by the ``enabled-by``
3965    attribute evaluates to true.  In generated header files, the expression is
3966    evaluated by the C preprocessor.
3967
3968enabled-by
3969    The attribute value shall be an
3970    :ref:`SpecTypeInterfaceEnabledByExpression`.
3971
3972This type is used by the following types:
3973
3974* :ref:`SpecTypeInterfaceDefinitionDirective`
3975
3976.. _SpecTypeInterfaceDescription:
3977
3978Interface Description
3979^^^^^^^^^^^^^^^^^^^^^
3980
3981A value of this type shall be of one of the following variants:
3982
3983* There may be no value (null).
3984
3985* The value may be a string. It shall be the description of the interface.  The
3986  description should be short and concentrate on the average case.  All special
3987  cases, usage notes, constraints, error conditions, configuration
3988  dependencies, references, etc. should be described in the
3989  :ref:`SpecTypeInterfaceNotes`.
3990
3991This type is used by the following types:
3992
3993* :ref:`SpecTypeApplicationConfigurationOptionItemType`
3994
3995* :ref:`SpecTypeInterfaceCompoundItemType`
3996
3997* :ref:`SpecTypeInterfaceCompoundMemberDefinition`
3998
3999* :ref:`SpecTypeInterfaceDefineItemType`
4000
4001* :ref:`SpecTypeInterfaceEnumItemType`
4002
4003* :ref:`SpecTypeInterfaceEnumeratorItemType`
4004
4005* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
4006
4007* :ref:`SpecTypeInterfaceGroupItemType`
4008
4009* :ref:`SpecTypeInterfaceParameter`
4010
4011* :ref:`SpecTypeInterfaceReturnValue`
4012
4013* :ref:`SpecTypeInterfaceTypedefItemType`
4014
4015* :ref:`SpecTypeInterfaceVariableItemType`
4016
4017.. _SpecTypeInterfaceEnabledByExpression:
4018
4019Interface Enabled-By Expression
4020^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4021
4022A value of this type shall be an expression which defines under which
4023conditions an interface definition is enabled.  In generated header files, the
4024expression is evaluated by the C preprocessor.
4025
4026A value of this type shall be of one of the following variants:
4027
4028* The value may be a boolean. It is converted to 0 or 1.  It defines a symbol
4029  in the expression.
4030
4031* The value may be a set of attributes. Each attribute defines an operator.
4032  Exactly one of the explicit attributes shall be specified. The explicit
4033  attributes for this type are:
4034
4035  and
4036      The attribute value shall be a list. Each list element shall be an
4037      :ref:`SpecTypeInterfaceEnabledByExpression`. The *and* operator defines a
4038      *logical and* of the expressions in the list.
4039
4040  not
4041      The attribute value shall be an
4042      :ref:`SpecTypeInterfaceEnabledByExpression`. The *not* operator defines a
4043      *logical not* of the expression.
4044
4045  or
4046      The attribute value shall be a list. Each list element shall be an
4047      :ref:`SpecTypeInterfaceEnabledByExpression`. The *or* operator defines a
4048      *logical or* of the expressions in the list.
4049
4050* The value may be a list. Each list element shall be an
4051  :ref:`SpecTypeInterfaceEnabledByExpression`. It defines a *logical or* of the
4052  expressions in the list.
4053
4054* The value may be a string. It defines a symbol in the expression.
4055
4056This type is used by the following types:
4057
4058* :ref:`SpecTypeInterfaceCompoundMemberDefinitionVariant`
4059
4060* :ref:`SpecTypeInterfaceDefinitionVariant`
4061
4062* :ref:`SpecTypeInterfaceEnabledByExpression`
4063
4064* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`
4065
4066.. _SpecTypeInterfaceEnumDefinitionKind:
4067
4068Interface Enum Definition Kind
4069^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4070
4071The value shall be a string. It specifies how the enum is defined.  It may be a
4072typedef only, the enum only, or a typedef with an enum definition. The value
4073shall be an element of
4074
4075* "``enum-only``",
4076
4077* "``typedef-and-enum``", and
4078
4079* "``typedef-only``".
4080
4081This type is used by the following types:
4082
4083* :ref:`SpecTypeInterfaceEnumItemType`
4084
4085.. _SpecTypeInterfaceEnumeratorLinkRole:
4086
4087Interface Enumerator Link Role
4088^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4089
4090This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4091value is ``interface-enumerator``. It defines the interface enumerator role of
4092links.
4093
4094.. _SpecTypeInterfaceFunctionLinkRole:
4095
4096Interface Function Link Role
4097^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4098
4099This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4100value is ``interface-function``. It defines the interface function role of
4101links.  It is used to indicate that a :ref:`SpecTypeActionRequirementItemType`
4102item specifies functional requirements of an
4103:ref:`SpecTypeInterfaceFunctionOrMacroItemType` item.
4104
4105.. _SpecTypeInterfaceFunctionOrMacroDefinition:
4106
4107Interface Function or Macro Definition
4108^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4109
4110A value of this type shall be of one of the following variants:
4111
4112* The value may be a set of attributes. This set of attributes specifies a
4113  function definition. All explicit attributes shall be specified. The explicit
4114  attributes for this type are:
4115
4116  attributes
4117      The attribute value shall be an optional string. If the value is present,
4118      then it shall be the function attributes. On the attributes a
4119      context-sensitive substitution of item variables is performed.  A
4120      function attribute is for example the indication that the function does
4121      not return to the caller.
4122
4123  body
4124      The attribute value shall be an optional string. If the value is present,
4125      then it shall be the definition of a static inline function.  On the
4126      function definition a context-sensitive substitution of item variables is
4127      performed.  If no value is present, then the function is declared as an
4128      external function.
4129
4130  params
4131      The attribute value shall be a list of strings. It shall be the list of
4132      parameter declarations of the function.  On the function parameter
4133      declarations a context-sensitive substitution of item variables is
4134      performed.
4135
4136  return
4137      The attribute value shall be an optional string. If the value is present,
4138      then it shall be the function return type. On the return type a
4139      context-sensitive substitution of item variables is performed.
4140
4141* There may be no value (null).
4142
4143This type is used by the following types:
4144
4145* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`
4146
4147* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`
4148
4149.. _SpecTypeInterfaceFunctionOrMacroDefinitionDirective:
4150
4151Interface Function or Macro Definition Directive
4152^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4153
4154This set of attributes specifies a function or macro definition directive. All
4155explicit attributes shall be specified. The explicit attributes for this type
4156are:
4157
4158default
4159    The attribute value shall be an
4160    :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The default definition
4161    will be used if no variant-specific definition is enabled.
4162
4163variants
4164    The attribute value shall be a list. Each list element shall be an
4165    :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionVariant`.
4166
4167This type is used by the following types:
4168
4169* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
4170
4171.. _SpecTypeInterfaceFunctionOrMacroDefinitionVariant:
4172
4173Interface Function or Macro Definition Variant
4174^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4175
4176This set of attributes specifies a function or macro definition variant. All
4177explicit attributes shall be specified. The explicit attributes for this type
4178are:
4179
4180definition
4181    The attribute value shall be an
4182    :ref:`SpecTypeInterfaceFunctionOrMacroDefinition`. The definition will be
4183    used if the expression defined by the ``enabled-by`` attribute evaluates to
4184    true.  In generated header files, the expression is evaluated by the C
4185    preprocessor.
4186
4187enabled-by
4188    The attribute value shall be an
4189    :ref:`SpecTypeInterfaceEnabledByExpression`.
4190
4191This type is used by the following types:
4192
4193* :ref:`SpecTypeInterfaceFunctionOrMacroDefinitionDirective`
4194
4195.. _SpecTypeInterfaceGroupIdentifier:
4196
4197Interface Group Identifier
4198^^^^^^^^^^^^^^^^^^^^^^^^^^
4199
4200The value shall be a string. It shall be the identifier of the interface group.
4201The value shall match with the regular expression "``^[A-Z][a-zA-Z0-9]*$``".
4202
4203This type is used by the following types:
4204
4205* :ref:`SpecTypeDesignGroupRequirementItemType`
4206
4207* :ref:`SpecTypeInterfaceGroupItemType`
4208
4209.. _SpecTypeInterfaceGroupMembershipLinkRole:
4210
4211Interface Group Membership Link Role
4212^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4213
4214This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4215value is ``interface-ingroup``. It defines the interface group membership role
4216of links.
4217
4218.. _SpecTypeInterfaceHiddenGroupMembershipLinkRole:
4219
4220Interface Hidden Group Membership Link Role
4221^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4222
4223This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4224value is ``interface-ingroup-hidden``. It defines the interface hidden group
4225membership role of links.  This role may be used to make an interface a group
4226member and hide this relationship in the documentation.  An example is an
4227optimized macro implementation of a directive which has the same name as the
4228corresponding directive.
4229
4230.. _SpecTypeInterfaceIncludeLinkRole:
4231
4232Interface Include Link Role
4233^^^^^^^^^^^^^^^^^^^^^^^^^^^
4234
4235This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4236value is ``interface-include``. It defines the interface include role of links
4237and is used to indicate that an interface container includes another interface
4238container.  For example, one header file includes another header file. All
4239explicit attributes shall be specified. The explicit attributes for this type
4240are:
4241
4242enabled-by
4243    The attribute value shall be an :ref:`SpecTypeEnabledByExpression`. It
4244    shall define under which conditions the interface container is included.
4245
4246.. _SpecTypeInterfaceNotes:
4247
4248Interface Notes
4249^^^^^^^^^^^^^^^
4250
4251A value of this type shall be of one of the following variants:
4252
4253* There may be no value (null).
4254
4255* The value may be a string. It shall be the notes for the interface.
4256
4257This type is used by the following types:
4258
4259* :ref:`SpecTypeApplicationConfigurationOptionItemType`
4260
4261* :ref:`SpecTypeInterfaceCompoundItemType`
4262
4263* :ref:`SpecTypeInterfaceDefineItemType`
4264
4265* :ref:`SpecTypeInterfaceEnumeratorItemType`
4266
4267* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
4268
4269* :ref:`SpecTypeInterfaceTypedefItemType`
4270
4271* :ref:`SpecTypeInterfaceVariableItemType`
4272
4273.. _SpecTypeInterfaceParameter:
4274
4275Interface Parameter
4276^^^^^^^^^^^^^^^^^^^
4277
4278This set of attributes specifies an interface parameter. All explicit
4279attributes shall be specified. The explicit attributes for this type are:
4280
4281description
4282    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
4283
4284dir
4285    The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`.
4286
4287name
4288    The attribute value shall be a string. It shall be the interface parameter
4289    name.
4290
4291This type is used by the following types:
4292
4293* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
4294
4295* :ref:`SpecTypeInterfaceTypedefItemType`
4296
4297.. _SpecTypeInterfaceParameterDirection:
4298
4299Interface Parameter Direction
4300^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4301
4302A value of this type shall be of one of the following variants:
4303
4304* There may be no value (null).
4305
4306* The value may be a string. It specifies the interface parameter direction.
4307  The value shall be an element of
4308
4309  * "``in``",
4310
4311  * "``out``", and
4312
4313  * "``inout``".
4314
4315This type is used by the following types:
4316
4317* :ref:`SpecTypeInterfaceParameter`
4318
4319* :ref:`SpecTypeTestRunParameter`
4320
4321.. _SpecTypeInterfacePlacementLinkRole:
4322
4323Interface Placement Link Role
4324^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4325
4326This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4327value is ``interface-placement``. It defines the interface placement role of
4328links.  It is used to indicate that an interface definition is placed into an
4329interface container, for example a header file.
4330
4331.. _SpecTypeInterfaceReferencesSet:
4332
4333Interface References Set
4334^^^^^^^^^^^^^^^^^^^^^^^^
4335
4336This set of attributes defines references for the interface. Generic attributes
4337may be specified. Each generic attribute key shall be a :ref:`SpecTypeName`.
4338Each generic attribute value shall be a string. The key defines the reference
4339kind.  The value shall be a kind-specific reference target.
4340
4341This type is used by the following types:
4342
4343* :ref:`SpecTypeInterfaceUnspecifiedItemType`
4344
4345.. _SpecTypeInterfaceReturnDirective:
4346
4347Interface Return Directive
4348^^^^^^^^^^^^^^^^^^^^^^^^^^
4349
4350A value of this type shall be of one of the following variants:
4351
4352* The value may be a set of attributes. This set of attributes specifies an
4353  interface return. All explicit attributes shall be specified. The explicit
4354  attributes for this type are:
4355
4356  return
4357      The attribute value shall be an optional string. It shall describe the
4358      interface return for unspecified return values.
4359
4360  return-values
4361      The attribute value shall be a list. Each list element shall be an
4362      :ref:`SpecTypeInterfaceReturnValue`.
4363
4364* There may be no value (null).
4365
4366This type is used by the following types:
4367
4368* :ref:`SpecTypeInterfaceFunctionOrMacroItemType`
4369
4370* :ref:`SpecTypeInterfaceTypedefItemType`
4371
4372.. _SpecTypeInterfaceReturnValue:
4373
4374Interface Return Value
4375^^^^^^^^^^^^^^^^^^^^^^
4376
4377This set of attributes specifies an interface return value. All explicit
4378attributes shall be specified. The explicit attributes for this type are:
4379
4380description
4381    The attribute value shall be an :ref:`SpecTypeInterfaceDescription`.
4382
4383value
4384    The attribute value shall be a :ref:`SpecTypeBooleanOrIntegerOrString`. It
4385    shall be the described interface return value.
4386
4387This type is used by the following types:
4388
4389* :ref:`SpecTypeInterfaceReturnDirective`
4390
4391.. _SpecTypeInterfaceTargetLinkRole:
4392
4393Interface Target Link Role
4394^^^^^^^^^^^^^^^^^^^^^^^^^^
4395
4396This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4397value is ``interface-target``. It defines the interface target role of links.
4398It is used for interface forward declarations.
4399
4400.. _SpecTypeLink:
4401
4402Link
4403^^^^
4404
4405This set of attributes specifies a link from one specification item to another
4406specification item.  The links in a list are ordered.  The first link in the
4407list is processed first. All explicit attributes shall be specified. The
4408explicit attributes for this type are:
4409
4410role
4411    The attribute value shall be a :ref:`SpecTypeName`. It shall be the role of
4412    the link.
4413
4414uid
4415    The attribute value shall be an :ref:`SpecTypeUID`. It shall be the
4416    absolute or relative UID of the link target item.
4417
4418This type is refined by the following types:
4419
4420* :ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`
4421
4422* :ref:`SpecTypeBuildDependencyLinkRole`
4423
4424* :ref:`SpecTypeConstraintLinkRole`
4425
4426* :ref:`SpecTypeFunctionImplementationLinkRole`
4427
4428* :ref:`SpecTypeGlossaryMembershipLinkRole`
4429
4430* :ref:`SpecTypeInterfaceEnumeratorLinkRole`
4431
4432* :ref:`SpecTypeInterfaceFunctionLinkRole`
4433
4434* :ref:`SpecTypeInterfaceGroupMembershipLinkRole`
4435
4436* :ref:`SpecTypeInterfaceHiddenGroupMembershipLinkRole`
4437
4438* :ref:`SpecTypeInterfaceIncludeLinkRole`
4439
4440* :ref:`SpecTypeInterfacePlacementLinkRole`
4441
4442* :ref:`SpecTypeInterfaceTargetLinkRole`
4443
4444* :ref:`SpecTypePlacementOrderLinkRole`
4445
4446* :ref:`SpecTypeRequirementRefinementLinkRole`
4447
4448* :ref:`SpecTypeRequirementValidationLinkRole`
4449
4450* :ref:`SpecTypeRuntimeMeasurementRequestLinkRole`
4451
4452* :ref:`SpecTypeSpecificationMemberLinkRole`
4453
4454* :ref:`SpecTypeSpecificationRefinementLinkRole`
4455
4456* :ref:`SpecTypeUnitTestLinkRole`
4457
4458This type is used by the following types:
4459
4460* :ref:`SpecTypeRootItemType`
4461
4462* :ref:`SpecTypeTestCaseAction`
4463
4464* :ref:`SpecTypeTestCaseCheck`
4465
4466.. _SpecTypeName:
4467
4468Name
4469^^^^
4470
4471The value shall be a string. A string is a valid name if it matches with the
4472``^([a-z][a-z0-9-]*|SPDX-License-Identifier)$`` regular expression.
4473
4474This type is used by the following types:
4475
4476* :ref:`SpecTypeApplicationConfigurationOptionItemType`
4477
4478* :ref:`SpecTypeBuildItemType`
4479
4480* :ref:`SpecTypeBuildOptionSetTestStateAction`
4481
4482* :ref:`SpecTypeFunctionalRequirementItemType`
4483
4484* :ref:`SpecTypeGlossaryItemType`
4485
4486* :ref:`SpecTypeInterfaceItemType`
4487
4488* :ref:`SpecTypeInterfaceReferencesSet`
4489
4490* :ref:`SpecTypeLink`
4491
4492* :ref:`SpecTypeNonFunctionalRequirementItemType`
4493
4494* :ref:`SpecTypeRequirementItemType`
4495
4496* :ref:`SpecTypeRootItemType`
4497
4498* :ref:`SpecTypeRuntimeMeasurementParameterSet`
4499
4500* :ref:`SpecTypeRuntimePerformanceParameterSet`
4501
4502* :ref:`SpecTypeSpecificationAttributeValue`
4503
4504* :ref:`SpecTypeSpecificationExplicitAttributes`
4505
4506* :ref:`SpecTypeSpecificationGenericAttributes`
4507
4508* :ref:`SpecTypeSpecificationItemType`
4509
4510* :ref:`SpecTypeSpecificationList`
4511
4512* :ref:`SpecTypeSpecificationRefinementLinkRole`
4513
4514.. _SpecTypeOptionalString:
4515
4516Optional String
4517^^^^^^^^^^^^^^^
4518
4519A value of this type shall be of one of the following variants:
4520
4521* There may be no value (null).
4522
4523* The value may be a string.
4524
4525.. _SpecTypePlacementOrderLinkRole:
4526
4527Placement Order Link Role
4528^^^^^^^^^^^^^^^^^^^^^^^^^
4529
4530This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4531value is ``placement-order``. This link role defines the placement order of
4532items in a container item (for example an interface function in a header file
4533or a documentation section).
4534
4535.. _SpecTypeRequirementReference:
4536
4537Requirement Reference
4538^^^^^^^^^^^^^^^^^^^^^
4539
4540This set of attributes specifies a requirement reference. All explicit
4541attributes shall be specified. The explicit attributes for this type are:
4542
4543identifier
4544    The attribute value shall be a string. It shall be the type-specific
4545    identifier of the reference target. For *group* references use the Doxygen
4546    group identifier.
4547
4548type
4549    The attribute value shall be a :ref:`SpecTypeRequirementReferenceType`.
4550
4551This type is used by the following types:
4552
4553* :ref:`SpecTypeRequirementItemType`
4554
4555.. _SpecTypeRequirementReferenceType:
4556
4557Requirement Reference Type
4558^^^^^^^^^^^^^^^^^^^^^^^^^^
4559
4560The value shall be a string. It specifies the type of a requirement reference.
4561The value shall be an element of
4562
4563* "``define``",
4564
4565* "``file``",
4566
4567* "``function``",
4568
4569* "``group``",
4570
4571* "``macro``", and
4572
4573* "``variable``".
4574
4575This type is used by the following types:
4576
4577* :ref:`SpecTypeRequirementReference`
4578
4579.. _SpecTypeRequirementRefinementLinkRole:
4580
4581Requirement Refinement Link Role
4582^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4583
4584This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4585value is ``requirement-refinement``. It defines the requirement refinement role
4586of links.
4587
4588.. _SpecTypeRequirementText:
4589
4590Requirement Text
4591^^^^^^^^^^^^^^^^
4592
4593The value shall be a string. It shall state a requirement or constraint. The
4594value shall not contain an element of
4595
4596* "``acceptable``",
4597
4598* "``adequate``",
4599
4600* "``almost always``",
4601
4602* "``and/or``",
4603
4604* "``appropriate``",
4605
4606* "``approximately``",
4607
4608* "``as far as possible``",
4609
4610* "``as much as practicable``",
4611
4612* "``best``",
4613
4614* "``best possible``",
4615
4616* "``easy``",
4617
4618* "``efficient``",
4619
4620* "``e.g.``",
4621
4622* "``enable``",
4623
4624* "``enough``",
4625
4626* "``etc.``",
4627
4628* "``few``",
4629
4630* "``first rate``",
4631
4632* "``flexible``",
4633
4634* "``generally``",
4635
4636* "``goal``",
4637
4638* "``graceful``",
4639
4640* "``great``",
4641
4642* "``greatest``",
4643
4644* "``ideally``",
4645
4646* "``i.e.``",
4647
4648* "``if possible``",
4649
4650* "``in most cases``",
4651
4652* "``large``",
4653
4654* "``many``",
4655
4656* "``maximize``",
4657
4658* "``minimize``",
4659
4660* "``most``",
4661
4662* "``multiple``",
4663
4664* "``necessary``",
4665
4666* "``numerous``",
4667
4668* "``optimize``",
4669
4670* "``ought to``",
4671
4672* "``probably``",
4673
4674* "``quick``",
4675
4676* "``rapid``",
4677
4678* "``reasonably``",
4679
4680* "``relevant``",
4681
4682* "``robust``",
4683
4684* "``satisfactory``",
4685
4686* "``several``",
4687
4688* "``shall be included but not limited to``",
4689
4690* "``simple``",
4691
4692* "``small``",
4693
4694* "``some``",
4695
4696* "``state of the art``",
4697
4698* "``sufficient``",
4699
4700* "``suitable``",
4701
4702* "``support``",
4703
4704* "``systematically``",
4705
4706* "``transparent``",
4707
4708* "``typical``",
4709
4710* "``user friendly``",
4711
4712* "``usually``",
4713
4714* "``versatile``", and
4715
4716* "``when necessary``".
4717
4718This type is used by the following types:
4719
4720* :ref:`SpecTypeActionRequirementState`
4721
4722* :ref:`SpecTypeApplicationConfigurationGroupItemType`
4723
4724* :ref:`SpecTypeConstraintItemType`
4725
4726* :ref:`SpecTypeInterfaceGroupItemType`
4727
4728* :ref:`SpecTypeRequirementItemType`
4729
4730.. _SpecTypeRequirementValidationLinkRole:
4731
4732Requirement Validation Link Role
4733^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4734
4735This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4736value is ``validation``. It defines the requirement validation role of links.
4737
4738.. _SpecTypeRuntimeMeasurementEnvironment:
4739
4740Runtime Measurement Environment
4741^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4742
4743The value shall be a string. It specifies the runtime measurement environment.
4744The value
4745
4746* shall be an element of
4747
4748  * "``FullCache``",
4749
4750  * "``HotCache``", and
4751
4752  * "``DirtyCache``",
4753
4754* or, shall match with the regular expression "``^Load/[1-9][0-9]*$``".
4755
4756This type is used by the following types:
4757
4758* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`
4759
4760.. _SpecTypeRuntimeMeasurementEnvironmentTable:
4761
4762Runtime Measurement Environment Table
4763^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4764
4765This set of attributes provides runtime performance limits for a set of runtime
4766measurement environments. Generic attributes may be specified. Each generic
4767attribute key shall be a :ref:`SpecTypeRuntimeMeasurementEnvironment`. Each
4768generic attribute value shall be a :ref:`SpecTypeRuntimeMeasurementValueTable`.
4769
4770This type is used by the following types:
4771
4772* :ref:`SpecTypeRuntimePerformanceLimitTable`
4773
4774.. _SpecTypeRuntimeMeasurementParameterSet:
4775
4776Runtime Measurement Parameter Set
4777^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4778
4779This set of attributes defines parameters of the runtime measurement test case.
4780All explicit attributes shall be specified. The explicit attributes for this
4781type are:
4782
4783sample-count
4784    The attribute value shall be an integer number. It shall be the sample
4785    count of the runtime measurement context.
4786
4787In addition to the explicit attributes, generic attributes may be specified.
4788Each generic attribute key shall be a :ref:`SpecTypeName`. The attribute value
4789may have any type.
4790
4791This type is used by the following types:
4792
4793* :ref:`SpecTypeRuntimeMeasurementTestItemType`
4794
4795.. _SpecTypeRuntimeMeasurementRequestLinkRole:
4796
4797Runtime Measurement Request Link Role
4798^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4799
4800This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
4801value is ``runtime-measurement-request``. It defines the runtime measurement
4802request role of links.  The link target shall be a
4803:ref:`SpecTypeRuntimeMeasurementTestItemType` item.
4804
4805.. _SpecTypeRuntimeMeasurementValueKind:
4806
4807Runtime Measurement Value Kind
4808^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4809
4810The value shall be a string. It specifies the kind of a runtime measurement
4811value. The value shall be an element of
4812
4813* "``max-lower-bound``",
4814
4815* "``max-upper-bound``",
4816
4817* "``mean-lower-bound``",
4818
4819* "``mean-upper-bound``",
4820
4821* "``median-lower-bound``",
4822
4823* "``median-upper-bound``",
4824
4825* "``min-lower-bound``", and
4826
4827* "``min-upper-bound``".
4828
4829This type is used by the following types:
4830
4831* :ref:`SpecTypeRuntimeMeasurementValueTable`
4832
4833.. _SpecTypeRuntimeMeasurementValueTable:
4834
4835Runtime Measurement Value Table
4836^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4837
4838This set of attributes provides a set of runtime measurement values each of a
4839specified kind.  The unit of the values shall be one second. Generic attributes
4840may be specified. Each generic attribute key shall be a
4841:ref:`SpecTypeRuntimeMeasurementValueKind`. Each generic attribute value shall
4842be a floating-point number.
4843
4844This type is used by the following types:
4845
4846* :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`
4847
4848.. _SpecTypeRuntimePerformanceLimitTable:
4849
4850Runtime Performance Limit Table
4851^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4852
4853This set of attributes provides runtime performance limits for BSP variants
4854specified by ``"<arch>/<bsp>"`` with <arch> being the architecture of the BSP
4855and <bsp> being the base name of the BSP. Generic attributes may be specified.
4856Each generic attribute key shall be a string. Each generic attribute value
4857shall be a :ref:`SpecTypeRuntimeMeasurementEnvironmentTable`.
4858
4859This type is used by the following types:
4860
4861* :ref:`SpecTypeRuntimePerformanceRequirementItemType`
4862
4863.. _SpecTypeRuntimePerformanceParameterSet:
4864
4865Runtime Performance Parameter Set
4866^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4867
4868This set of attributes defines parameters of the runtime performance
4869requirement. Generic attributes may be specified. Each generic attribute key
4870shall be a :ref:`SpecTypeName`. The attribute value may have any type.
4871
4872This type is used by the following types:
4873
4874* :ref:`SpecTypeRuntimePerformanceRequirementItemType`
4875
4876.. _SpecTypeSPDXLicenseIdentifier:
4877
4878SPDX License Identifier
4879^^^^^^^^^^^^^^^^^^^^^^^
4880
4881The value shall be a string. It defines the license of the item expressed
4882though an SPDX License Identifier. The value
4883
4884* shall be equal to "``CC-BY-SA-4.0 OR BSD-2-Clause``",
4885
4886* or, shall be equal to "``BSD-2-Clause``",
4887
4888* or, shall be equal to "``CC-BY-SA-4.0``".
4889
4890This type is used by the following types:
4891
4892* :ref:`SpecTypeRootItemType`
4893
4894.. _SpecTypeSpecificationAttributeSet:
4895
4896Specification Attribute Set
4897^^^^^^^^^^^^^^^^^^^^^^^^^^^
4898
4899This set of attributes specifies a set of attributes. The following explicit
4900attributes are mandatory:
4901
4902* ``attributes``
4903
4904* ``description``
4905
4906* ``mandatory-attributes``
4907
4908The explicit attributes for this type are:
4909
4910attributes
4911    The attribute value shall be a
4912    :ref:`SpecTypeSpecificationExplicitAttributes`. It shall specify the
4913    explicit attributes of the attribute set.
4914
4915description
4916    The attribute value shall be an optional string. It shall be the
4917    description of the attribute set.
4918
4919generic-attributes
4920    The attribute value shall be a
4921    :ref:`SpecTypeSpecificationGenericAttributes`. It shall specify the generic
4922    attributes of the attribute set.
4923
4924mandatory-attributes
4925    The attribute value shall be a
4926    :ref:`SpecTypeSpecificationMandatoryAttributes`. It shall specify the
4927    mandatory attributes of the attribute set.
4928
4929This type is used by the following types:
4930
4931* :ref:`SpecTypeSpecificationInformation`
4932
4933.. _SpecTypeSpecificationAttributeValue:
4934
4935Specification Attribute Value
4936^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4937
4938This set of attributes specifies an attribute value. All explicit attributes
4939shall be specified. The explicit attributes for this type are:
4940
4941description
4942    The attribute value shall be an optional string. It shall be the
4943    description of the attribute value.
4944
4945spec-type
4946    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
4947    specification type of the attribute value.
4948
4949This type is used by the following types:
4950
4951* :ref:`SpecTypeSpecificationExplicitAttributes`
4952
4953.. _SpecTypeSpecificationBooleanValue:
4954
4955Specification Boolean Value
4956^^^^^^^^^^^^^^^^^^^^^^^^^^^
4957
4958This attribute set specifies a boolean value. Only the ``description``
4959attribute is mandatory. The explicit attributes for this type are:
4960
4961assert
4962    The attribute value shall be a boolean. This optional attribute defines the
4963    value constraint of the specified boolean value.  If the value of the
4964    assert attribute is true, then the value of the specified boolean value
4965    shall be true.  If the value of the assert attribute is false, then the
4966    value of the specified boolean value shall be false.  In case the assert
4967    attribute is not present, then the value of the specified boolean value may
4968    be true or false.
4969
4970description
4971    The attribute value shall be an optional string. It shall be the
4972    description of the specified boolean value.
4973
4974This type is used by the following types:
4975
4976* :ref:`SpecTypeSpecificationInformation`
4977
4978.. _SpecTypeSpecificationExplicitAttributes:
4979
4980Specification Explicit Attributes
4981^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4982
4983Generic attributes may be specified. Each generic attribute key shall be a
4984:ref:`SpecTypeName`. Each generic attribute value shall be a
4985:ref:`SpecTypeSpecificationAttributeValue`. Each generic attribute specifies an
4986explicit attribute of the attribute set.  The key of the each generic attribute
4987defines the attribute key of the explicit attribute.
4988
4989This type is used by the following types:
4990
4991* :ref:`SpecTypeSpecificationAttributeSet`
4992
4993.. _SpecTypeSpecificationFloatingPointAssert:
4994
4995Specification Floating-Point Assert
4996^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4997
4998A value of this type shall be an expression which asserts that the
4999floating-point value of the specified attribute satisfies the required
5000constraints.
5001
5002A value of this type shall be of one of the following variants:
5003
5004* The value may be a set of attributes. Each attribute defines an operator.
5005  Exactly one of the explicit attributes shall be specified. The explicit
5006  attributes for this type are:
5007
5008  and
5009      The attribute value shall be a list. Each list element shall be a
5010      :ref:`SpecTypeSpecificationFloatingPointAssert`. The *and* operator
5011      evaluates to the *logical and* of the evaluation results of the
5012      expressions in the list.
5013
5014  eq
5015      The attribute value shall be a floating-point number. The *eq* operator
5016      evaluates to true, if the value to check is equal to the value of this
5017      attribute, otherwise to false.
5018
5019  ge
5020      The attribute value shall be a floating-point number. The *ge* operator
5021      evaluates to true, if the value to check is greater than or equal to the
5022      value of this attribute, otherwise to false.
5023
5024  gt
5025      The attribute value shall be a floating-point number. The *gt* operator
5026      evaluates to true, if the value to check is greater than the value of
5027      this attribute, otherwise to false.
5028
5029  le
5030      The attribute value shall be a floating-point number. The *le* operator
5031      evaluates to true, if the value to check is less than or equal to the
5032      value of this attribute, otherwise to false.
5033
5034  lt
5035      The attribute value shall be a floating-point number. The *lt* operator
5036      evaluates to true, if the value to check is less than the value of this
5037      attribute, otherwise to false.
5038
5039  ne
5040      The attribute value shall be a floating-point number. The *ne* operator
5041      evaluates to true, if the value to check is not equal to the value of
5042      this attribute, otherwise to false.
5043
5044  not
5045      The attribute value shall be a
5046      :ref:`SpecTypeSpecificationFloatingPointAssert`. The *not* operator
5047      evaluates to the *logical not* of the evaluation results of the
5048      expression.
5049
5050  or
5051      The attribute value shall be a list. Each list element shall be a
5052      :ref:`SpecTypeSpecificationFloatingPointAssert`. The *or* operator
5053      evaluates to the *logical or* of the evaluation results of the
5054      expressions in the list.
5055
5056* The value may be a list. Each list element shall be a
5057  :ref:`SpecTypeSpecificationFloatingPointAssert`. This list of expressions
5058  evaluates to the *logical or* of the evaluation results of the expressions in
5059  the list.
5060
5061This type is used by the following types:
5062
5063* :ref:`SpecTypeSpecificationFloatingPointAssert`
5064
5065* :ref:`SpecTypeSpecificationFloatingPointValue`
5066
5067.. _SpecTypeSpecificationFloatingPointValue:
5068
5069Specification Floating-Point Value
5070^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5071
5072This set of attributes specifies a floating-point value. Only the
5073``description`` attribute is mandatory. The explicit attributes for this type
5074are:
5075
5076assert
5077    The attribute value shall be a
5078    :ref:`SpecTypeSpecificationFloatingPointAssert`. This optional attribute
5079    defines the value constraints of the specified floating-point value.  In
5080    case the assert attribute is not present, then the value of the specified
5081    floating-point value may be every valid floating-point number.
5082
5083description
5084    The attribute value shall be an optional string. It shall be the
5085    description of the specified floating-point value.
5086
5087This type is used by the following types:
5088
5089* :ref:`SpecTypeSpecificationInformation`
5090
5091.. _SpecTypeSpecificationGenericAttributes:
5092
5093Specification Generic Attributes
5094^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5095
5096This set of attributes specifies generic attributes.  Generic attributes are
5097attributes which are not explicitly specified by
5098:ref:`SpecTypeSpecificationExplicitAttributes`.  They are restricted to uniform
5099attribute key and value types. All explicit attributes shall be specified. The
5100explicit attributes for this type are:
5101
5102description
5103    The attribute value shall be an optional string. It shall be the
5104    description of the generic attributes.
5105
5106key-spec-type
5107    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
5108    specification type of the generic attribute keys.
5109
5110value-spec-type
5111    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
5112    specification type of the generic attribute values.
5113
5114This type is used by the following types:
5115
5116* :ref:`SpecTypeSpecificationAttributeSet`
5117
5118.. _SpecTypeSpecificationInformation:
5119
5120Specification Information
5121^^^^^^^^^^^^^^^^^^^^^^^^^
5122
5123This set of attributes specifies attribute values. At least one of the explicit
5124attributes shall be specified. The explicit attributes for this type are:
5125
5126bool
5127    The attribute value shall be a :ref:`SpecTypeSpecificationBooleanValue`. It
5128    shall specify a boolean value.
5129
5130dict
5131    The attribute value shall be a :ref:`SpecTypeSpecificationAttributeSet`. It
5132    shall specify a set of attributes.
5133
5134float
5135    The attribute value shall be a
5136    :ref:`SpecTypeSpecificationFloatingPointValue`. It shall specify a
5137    floating-point value.
5138
5139int
5140    The attribute value shall be a :ref:`SpecTypeSpecificationIntegerValue`. It
5141    shall specify an integer value.
5142
5143list
5144    The attribute value shall be a :ref:`SpecTypeSpecificationList`. It shall
5145    specify a list of attributes or values.
5146
5147none
5148    The attribute shall have no value. It specifies that no value is required.
5149
5150str
5151    The attribute value shall be a :ref:`SpecTypeSpecificationStringValue`. It
5152    shall specify a string.
5153
5154This type is used by the following types:
5155
5156* :ref:`SpecTypeSpecificationItemType`
5157
5158.. _SpecTypeSpecificationIntegerAssert:
5159
5160Specification Integer Assert
5161^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5162
5163A value of this type shall be an expression which asserts that the integer
5164value of the specified attribute satisfies the required constraints.
5165
5166A value of this type shall be of one of the following variants:
5167
5168* The value may be a set of attributes. Each attribute defines an operator.
5169  Exactly one of the explicit attributes shall be specified. The explicit
5170  attributes for this type are:
5171
5172  and
5173      The attribute value shall be a list. Each list element shall be a
5174      :ref:`SpecTypeSpecificationIntegerAssert`. The *and* operator evaluates
5175      to the *logical and* of the evaluation results of the expressions in the
5176      list.
5177
5178  eq
5179      The attribute value shall be an integer number. The *eq* operator
5180      evaluates to true, if the value to check is equal to the value of this
5181      attribute, otherwise to false.
5182
5183  ge
5184      The attribute value shall be an integer number. The *ge* operator
5185      evaluates to true, if the value to check is greater than or equal to the
5186      value of this attribute, otherwise to false.
5187
5188  gt
5189      The attribute value shall be an integer number. The *gt* operator
5190      evaluates to true, if the value to check is greater than the value of
5191      this attribute, otherwise to false.
5192
5193  le
5194      The attribute value shall be an integer number. The *le* operator
5195      evaluates to true, if the value to check is less than or equal to the
5196      value of this attribute, otherwise to false.
5197
5198  lt
5199      The attribute value shall be an integer number. The *lt* operator
5200      evaluates to true, if the value to check is less than the value of this
5201      attribute, otherwise to false.
5202
5203  ne
5204      The attribute value shall be an integer number. The *ne* operator
5205      evaluates to true, if the value to check is not equal to the value of
5206      this attribute, otherwise to false.
5207
5208  not
5209      The attribute value shall be a :ref:`SpecTypeSpecificationIntegerAssert`.
5210      The *not* operator evaluates to the *logical not* of the evaluation
5211      results of the expression.
5212
5213  or
5214      The attribute value shall be a list. Each list element shall be a
5215      :ref:`SpecTypeSpecificationIntegerAssert`. The *or* operator evaluates to
5216      the *logical or* of the evaluation results of the expressions in the
5217      list.
5218
5219* The value may be a list. Each list element shall be a
5220  :ref:`SpecTypeSpecificationIntegerAssert`. This list of expressions evaluates
5221  to the *logical or* of the evaluation results of the expressions in the list.
5222
5223This type is used by the following types:
5224
5225* :ref:`SpecTypeSpecificationIntegerAssert`
5226
5227* :ref:`SpecTypeSpecificationIntegerValue`
5228
5229.. _SpecTypeSpecificationIntegerValue:
5230
5231Specification Integer Value
5232^^^^^^^^^^^^^^^^^^^^^^^^^^^
5233
5234This set of attributes specifies an integer value. Only the ``description``
5235attribute is mandatory. The explicit attributes for this type are:
5236
5237assert
5238    The attribute value shall be a :ref:`SpecTypeSpecificationIntegerAssert`.
5239    This optional attribute defines the value constraints of the specified
5240    integer value.  In case the assert attribute is not present, then the value
5241    of the specified integer value may be every valid integer number.
5242
5243description
5244    The attribute value shall be an optional string. It shall be the
5245    description of the specified integer value.
5246
5247This type is used by the following types:
5248
5249* :ref:`SpecTypeSpecificationInformation`
5250
5251.. _SpecTypeSpecificationList:
5252
5253Specification List
5254^^^^^^^^^^^^^^^^^^
5255
5256This set of attributes specifies a list of attributes or values. All explicit
5257attributes shall be specified. The explicit attributes for this type are:
5258
5259description
5260    The attribute value shall be an optional string. It shall be the
5261    description of the list.
5262
5263spec-type
5264    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
5265    specification type of elements of the list.
5266
5267This type is used by the following types:
5268
5269* :ref:`SpecTypeSpecificationInformation`
5270
5271.. _SpecTypeSpecificationMandatoryAttributes:
5272
5273Specification Mandatory Attributes
5274^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5275
5276It defines which explicit attributes are mandatory.
5277
5278A value of this type shall be of one of the following variants:
5279
5280* The value may be a list. Each list element shall be a :ref:`SpecTypeName`.
5281  The list defines the mandatory attributes through their key names.
5282
5283* The value may be a string. It defines how many explicit attributes are
5284  mandatory.  If `none` is used, then none of the explicit attributes is
5285  mandatory, they are all optional. The value shall be an element of
5286
5287  * "``all``",
5288
5289  * "``at-least-one``",
5290
5291  * "``at-most-one``",
5292
5293  * "``exactly-one``", and
5294
5295  * "``none``".
5296
5297This type is used by the following types:
5298
5299* :ref:`SpecTypeSpecificationAttributeSet`
5300
5301.. _SpecTypeSpecificationMemberLinkRole:
5302
5303Specification Member Link Role
5304^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5305
5306This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
5307value is ``spec-member``. It defines the specification membership role of
5308links.
5309
5310.. _SpecTypeSpecificationRefinementLinkRole:
5311
5312Specification Refinement Link Role
5313^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5314
5315This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
5316value is ``spec-refinement``. It defines the specification refinement role of
5317links. All explicit attributes shall be specified. The explicit attributes for
5318this type are:
5319
5320spec-key
5321    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
5322    specification type refinement attribute key of the specification
5323    refinement.
5324
5325spec-value
5326    The attribute value shall be a :ref:`SpecTypeName`. It shall be the
5327    specification type refinement attribute value of the specification
5328    refinement.
5329
5330.. _SpecTypeSpecificationStringAssert:
5331
5332Specification String Assert
5333^^^^^^^^^^^^^^^^^^^^^^^^^^^
5334
5335A value of this type shall be an expression which asserts that the string of
5336the specified attribute satisfies the required constraints.
5337
5338A value of this type shall be of one of the following variants:
5339
5340* The value may be a set of attributes. Each attribute defines an operator.
5341  Exactly one of the explicit attributes shall be specified. The explicit
5342  attributes for this type are:
5343
5344  and
5345      The attribute value shall be a list. Each list element shall be a
5346      :ref:`SpecTypeSpecificationStringAssert`. The *and* operator evaluates to
5347      the *logical and* of the evaluation results of the expressions in the
5348      list.
5349
5350  contains
5351      The attribute value shall be a list of strings. The *contains* operator
5352      evaluates to true, if the string to check converted to lower case with
5353      all white space characters converted to a single space character contains
5354      a string of the list of strings of this attribute, otherwise to false.
5355
5356  eq
5357      The attribute value shall be a string. The *eq* operator evaluates to
5358      true, if the string to check is equal to the value of this attribute,
5359      otherwise to false.
5360
5361  ge
5362      The attribute value shall be a string. The *ge* operator evaluates to
5363      true, if the string to check is greater than or equal to the value of
5364      this attribute, otherwise to false.
5365
5366  gt
5367      The attribute value shall be a string. The *gt* operator evaluates to
5368      true, if the string to check is greater than the value of this attribute,
5369      otherwise to false.
5370
5371  in
5372      The attribute value shall be a list of strings. The *in* operator
5373      evaluates to true, if the string to check is contained in the list of
5374      strings of this attribute, otherwise to false.
5375
5376  le
5377      The attribute value shall be a string. The *le* operator evaluates to
5378      true, if the string to check is less than or equal to the value of this
5379      attribute, otherwise to false.
5380
5381  lt
5382      The attribute value shall be a string. The *lt* operator evaluates to
5383      true, if the string to check is less than the value of this attribute,
5384      otherwise to false.
5385
5386  ne
5387      The attribute value shall be a string. The *ne* operator evaluates to
5388      true, if the string to check is not equal to the value of this attribute,
5389      otherwise to false.
5390
5391  not
5392      The attribute value shall be a :ref:`SpecTypeSpecificationStringAssert`.
5393      The *not* operator evaluates to the *logical not* of the evaluation
5394      results of the expression.
5395
5396  or
5397      The attribute value shall be a list. Each list element shall be a
5398      :ref:`SpecTypeSpecificationStringAssert`. The *or* operator evaluates to
5399      the *logical or* of the evaluation results of the expressions in the
5400      list.
5401
5402  re
5403      The attribute value shall be a string. The *re* operator evaluates to
5404      true, if the string to check matches with the regular expression of this
5405      attribute, otherwise to false.
5406
5407  uid
5408      The attribute shall have no value. The *uid* operator evaluates to true,
5409      if the string is a valid UID, otherwise to false.
5410
5411* The value may be a list. Each list element shall be a
5412  :ref:`SpecTypeSpecificationStringAssert`. This list of expressions evaluates
5413  to the *logical or* of the evaluation results of the expressions in the list.
5414
5415This type is used by the following types:
5416
5417* :ref:`SpecTypeSpecificationStringAssert`
5418
5419* :ref:`SpecTypeSpecificationStringValue`
5420
5421.. _SpecTypeSpecificationStringValue:
5422
5423Specification String Value
5424^^^^^^^^^^^^^^^^^^^^^^^^^^
5425
5426This set of attributes specifies a string. Only the ``description`` attribute
5427is mandatory. The explicit attributes for this type are:
5428
5429assert
5430    The attribute value shall be a :ref:`SpecTypeSpecificationStringAssert`.
5431    This optional attribute defines the constraints of the specified string.
5432    In case the assert attribute is not present, then the specified string may
5433    be every valid string.
5434
5435description
5436    The attribute value shall be an optional string. It shall be the
5437    description of the specified string attribute.
5438
5439This type is used by the following types:
5440
5441* :ref:`SpecTypeSpecificationInformation`
5442
5443.. _SpecTypeTestCaseAction:
5444
5445Test Case Action
5446^^^^^^^^^^^^^^^^
5447
5448This set of attributes specifies a test case action. All explicit attributes
5449shall be specified. The explicit attributes for this type are:
5450
5451action-brief
5452    The attribute value shall be an optional string. It shall be the test case
5453    action brief description.
5454
5455action-code
5456    The attribute value shall be a string. It shall be the test case action
5457    code.
5458
5459checks
5460    The attribute value shall be a list. Each list element shall be a
5461    :ref:`SpecTypeTestCaseCheck`.
5462
5463links
5464    The attribute value shall be a list. Each list element shall be a
5465    :ref:`SpecTypeLink`. The links should use the
5466    :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the
5467    :ref:`SpecTypeUnitTestLinkRole` for unit tests.
5468
5469This type is used by the following types:
5470
5471* :ref:`SpecTypeTestCaseItemType`
5472
5473.. _SpecTypeTestCaseCheck:
5474
5475Test Case Check
5476^^^^^^^^^^^^^^^
5477
5478This set of attributes specifies a test case check. All explicit attributes
5479shall be specified. The explicit attributes for this type are:
5480
5481brief
5482    The attribute value shall be an optional string. It shall be the test case
5483    check brief description.
5484
5485code
5486    The attribute value shall be a string. It shall be the test case check
5487    code.
5488
5489links
5490    The attribute value shall be a list. Each list element shall be a
5491    :ref:`SpecTypeLink`. The links should use the
5492    :ref:`SpecTypeRequirementValidationLinkRole` for validation tests and the
5493    :ref:`SpecTypeUnitTestLinkRole` for unit tests.
5494
5495This type is used by the following types:
5496
5497* :ref:`SpecTypeTestCaseAction`
5498
5499.. _SpecTypeTestContextMember:
5500
5501Test Context Member
5502^^^^^^^^^^^^^^^^^^^
5503
5504A value of this type shall be of one of the following variants:
5505
5506* The value may be a set of attributes. This set of attributes defines an
5507  action requirement test context member. All explicit attributes shall be
5508  specified. The explicit attributes for this type are:
5509
5510  brief
5511      The attribute value shall be an optional string. It shall be the test
5512      context member brief description.
5513
5514  description
5515      The attribute value shall be an optional string. It shall be the test
5516      context member description.
5517
5518  member
5519      The attribute value shall be a string. It shall be the test context
5520      member definition.  It shall be a valid C structure member definition
5521      without a trailing ``;``.
5522
5523* There may be no value (null).
5524
5525This type is used by the following types:
5526
5527* :ref:`SpecTypeActionRequirementItemType`
5528
5529* :ref:`SpecTypeRuntimeMeasurementTestItemType`
5530
5531* :ref:`SpecTypeTestCaseItemType`
5532
5533.. _SpecTypeTestHeader:
5534
5535Test Header
5536^^^^^^^^^^^
5537
5538A value of this type shall be of one of the following variants:
5539
5540* The value may be a set of attributes. This set of attributes specifies a test
5541  header.  In case a test header is specified, then instead of a test case a
5542  test run function will be generated.  The test run function will be declared
5543  in the test header target file and defined in the test source target file.
5544  The test run function can be used to compose test cases.  The test header
5545  file is not automatically included in the test source file.  It should be
5546  added to the includes or local includes of the test. All explicit attributes
5547  shall be specified. The explicit attributes for this type are:
5548
5549  code
5550      The attribute value shall be an optional string. If the value is present,
5551      then it shall be the test header code.  The header code is placed at file
5552      scope after the general test declarations and before the test run
5553      function declaration.
5554
5555  freestanding
5556      The attribute value shall be a boolean. The value shall be ``true``, if
5557      the test case is freestanding, otherwise ``false``.  Freestanding test
5558      cases are not statically registered.  Instead the generated test runner
5559      uses :c:func:`T_case_begin` and :c:func:`T_case_end`.
5560
5561  includes
5562      The attribute value shall be a list of strings. It shall be a list of
5563      header files included by the header file via ``#include <...>``.
5564
5565  local-includes
5566      The attribute value shall be a list of strings. It shall be a list of
5567      header files included by the header file via ``#include "..."``.
5568
5569  run-params
5570      The attribute value shall be a list. Each list element shall be a
5571      :ref:`SpecTypeTestRunParameter`.
5572
5573  target
5574      The attribute value shall be a string. It shall be the path to the
5575      generated test header file.
5576
5577* There may be no value (null).
5578
5579This type is used by the following types:
5580
5581* :ref:`SpecTypeActionRequirementItemType`
5582
5583* :ref:`SpecTypeTestCaseItemType`
5584
5585.. _SpecTypeTestRunParameter:
5586
5587Test Run Parameter
5588^^^^^^^^^^^^^^^^^^
5589
5590This set of attributes specifies a parameter for the test run function. In case
5591this parameter is used in an :ref:`SpecTypeActionRequirementItemType` item,
5592then the parameter is also added as a member to the test context, see
5593:ref:`SpecTypeTestContextMember`. All explicit attributes shall be specified.
5594The explicit attributes for this type are:
5595
5596description
5597    The attribute value shall be a string. It shall be the description of the
5598    parameter.
5599
5600dir
5601    The attribute value shall be an :ref:`SpecTypeInterfaceParameterDirection`.
5602
5603name
5604    The attribute value shall be a string. It shall be the parameter name.
5605
5606specifier
5607    The attribute value shall be a string. It shall be the complete function
5608    parameter specifier.  Use ``${.:name}`` for the parameter name, for example
5609    ``"int ${.:name}"``.
5610
5611This type is used by the following types:
5612
5613* :ref:`SpecTypeTestHeader`
5614
5615.. _SpecTypeTestSupportMethod:
5616
5617Test Support Method
5618^^^^^^^^^^^^^^^^^^^
5619
5620A value of this type shall be of one of the following variants:
5621
5622* The value may be a set of attributes. This set of attributes defines an
5623  action requirement test support method. All explicit attributes shall be
5624  specified. The explicit attributes for this type are:
5625
5626  brief
5627      The attribute value shall be an optional string. It shall be the test
5628      support method brief description.
5629
5630  code
5631      The attribute value shall be a string. It shall be the test support
5632      method code.  The code may use a local variable ``ctx`` which points to
5633      the test context, see :ref:`SpecTypeTestContextMember`.
5634
5635  description
5636      The attribute value shall be an optional string. It shall be the test
5637      support method description.
5638
5639* There may be no value (null).
5640
5641This type is used by the following types:
5642
5643* :ref:`SpecTypeActionRequirementItemType`
5644
5645* :ref:`SpecTypeRuntimeMeasurementTestItemType`
5646
5647* :ref:`SpecTypeRuntimePerformanceRequirementItemType`
5648
5649* :ref:`SpecTypeTestCaseItemType`
5650
5651.. _SpecTypeUID:
5652
5653UID
5654^^^
5655
5656The value shall be a string. The string shall be a valid absolute or relative
5657item UID.
5658
5659This type is used by the following types:
5660
5661* :ref:`SpecTypeLink`
5662
5663.. _SpecTypeUnitTestLinkRole:
5664
5665Unit Test Link Role
5666^^^^^^^^^^^^^^^^^^^
5667
5668This type refines the :ref:`SpecTypeLink` through the ``role`` attribute if the
5669value is ``unit-test``. It defines the unit test role of links.  For unit tests
5670the link target should be the :ref:`SpecTypeInterfaceDomainItemType` containing
5671the software unit. All explicit attributes shall be specified. The explicit
5672attributes for this type are:
5673
5674name
5675    The attribute value shall be a string. It shall be the name of the tested
5676    software unit.
Note: See TracBrowser for help on using the repository browser.