blob: 9a28427623b673f6b955fddada2b7c71d373eab5 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
How-To
======
Getting Started
---------------
The RTEMS specification items and qualification tools are work in progress and
not fully integrated in the RTEMS Project. The first step to work with the
RTEMS specification and the corresponding tools is a clone of the following
repository:
.. code-block:: none
git clone git://git.rtems.org/sebh/rtems-qual.git
git submodule init
git submodule update
The tools need a virtual Python 3 environment. To set it up use:
.. code-block:: none
cd rtems-qual
make env
Each time you want to use one of the tools, you have to activate the
environment in your shell:
.. code-block:: none
cd rtems-qual
. env/bin/activate
Glossary Specification
----------------------
The glossary of terms for the RTEMS Project is defined by
:ref:`SpecTypeGlossaryTermItemType` items in the :file:`spec/glossary`
directory. For a new glossary term add a glossary item to this directory. As
the file name use the term in lower case with all white space and special
characters removed or replaced by alphanumeric characters, for example
:file:`spec/glossary/magicpower.yml` for the term `magic power`.
Use ``${uid:/attribute}`` substitutions to reference other parts of the
specification.
.. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
glossary-type: term
links:
- role: glossary-member
uid: ../glossary-general
term: magic power
text: |
Magic power enables a caller to create magic objects using a
${magicwand:/term}.
type: glossary
Define acronyms with the phrase `This term is an acronym for *.` in the
``text`` attribute:
.. code-block:: yaml
...
term: MP
...
text: |
This term is an acronym for Magic Power.
...
Once you are done with the glossary items, run the script :file:`spec2doc.py`
to generate the derived documentation content. Send patches for the generated
documentation and the specification to the :r:list:`devel` and follow the
normal patch review process.
Interface Specification
-----------------------
.. _ReqEngAddAPIHeaderFile:
Specify an API Header File
^^^^^^^^^^^^^^^^^^^^^^^^^^
The RTEMS :term:`API` header files are specified under ``spec:/if/rtems/*``.
Create a subdirectory with a corresponding name for the API, for example in
:file:`spec/if/rtems/foo` for the `foo` API. In this new subdirectory place an
:ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml`
(:file:`spec/if/rtems/foo/header.yml`) and populate it with the required
attributes.
.. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
interface-type: header-file
links:
- role: interface-placement
uid: /if/domains/api
path: rtems/rtems/foo.h
prefix: cpukit/include
type: interface
Specify an API Element
^^^^^^^^^^^^^^^^^^^^^^
Figure out the corresponding header file item. If it does not exist, see
:ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an
:ref:`SpecTypeInterfaceItemType` item into the directory of the header file
item, for example :file:`spec/if/rtems/foo/bar.yml` for the :c:func:`bar`
function. Add the required attributes for the new interface item. Do not hard
code interface names which are used to define the new interface. Use
``${uid-of-interface-item:/name}`` instead. If the referenced interface is
specified in the same directory, then use a relative UID. Using interface
references creates implicit dependencies and helps the header file generator to
resolve the interface dependencies and header file includes for you. Use
:ref:`SpecTypeInterfaceUnspecifiedItemType` items for interface dependencies to
other domains such as the C language, the compiler, the implementation, or
user-provided defines. To avoid cyclic dependencies between types you may use
an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item.
.. code-block:: yaml
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: Tries to create a magic object and returns it.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
default:
body: null
params:
- ${magic-wand:/name} ${.:/params[0]/name}
return: ${magic-type:/name} *
variants: []
description: |
The magic object is created out of nothing with the help of a magic wand.
enabled-by: true
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: /groups/api/classic/foo
name: bar
notes: null
params:
- description: is the magic wand.
dir: null
name: magic_wand
return:
return: Otherwise, the magic object is returned.
return-values:
- description: The caller did not have enough magic power.
value: ${/if/c/null}
type: interface
|
