1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) |
---|
4 | |
---|
5 | How-To |
---|
6 | ====== |
---|
7 | |
---|
8 | Getting Started |
---|
9 | --------------- |
---|
10 | |
---|
11 | The RTEMS specification items and qualification tools are work in progress. The |
---|
12 | first step to work with the RTEMS specification and the corresponding tools is a |
---|
13 | clone of the following repository: |
---|
14 | |
---|
15 | .. code-block:: none |
---|
16 | |
---|
17 | git clone git://git.rtems.org/rtems-central.git |
---|
18 | git submodule init |
---|
19 | git submodule update |
---|
20 | |
---|
21 | The tools need a virtual Python 3 environment. To set it up use: |
---|
22 | |
---|
23 | .. code-block:: none |
---|
24 | |
---|
25 | cd rtems-central |
---|
26 | make env |
---|
27 | |
---|
28 | Each time you want to use one of the tools, you have to activate the |
---|
29 | environment in your shell: |
---|
30 | |
---|
31 | .. code-block:: none |
---|
32 | |
---|
33 | cd rtems-central |
---|
34 | . env/bin/activate |
---|
35 | |
---|
36 | Application Configuration Options |
---|
37 | --------------------------------- |
---|
38 | |
---|
39 | The application configuration options and groups are maintained by |
---|
40 | specification items in the directory :file:`spec/if/acfg`. Application |
---|
41 | configuration options are grouped by |
---|
42 | :ref:`SpecTypeApplicationConfigurationGroupItemType` items which should be |
---|
43 | stored in files using the :file:`spec/if/acfg/group-*.yml` pattern. Each |
---|
44 | application configuration option shall link to exactly one group item with the |
---|
45 | :ref:`SpecTypeApplicationConfigurationGroupMemberLinkRole`. There are four |
---|
46 | application option item types available which cover all existing options: |
---|
47 | |
---|
48 | * The *feature enable options* let the application enable a feature option. If |
---|
49 | the option is not defined, then the feature is simply not available or |
---|
50 | active. There should be no feature-specific code linked to the application |
---|
51 | if the option is not defined. Examples are options which enable a device |
---|
52 | driver like ``CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER``. These options are |
---|
53 | specified by |
---|
54 | :ref:`SpecTypeApplicationConfigurationFeatureEnableOptionItemType` items. |
---|
55 | |
---|
56 | * The *feature options* let the application enable a specific feature option. |
---|
57 | If the option is not defined, then a default feature option is used. |
---|
58 | Regardless whether the option is defined or not defined, feature-specific |
---|
59 | code may be linked to the application. Examples are options which disable a |
---|
60 | feature if the option is defined such as |
---|
61 | ``CONFIGURE_APPLICATION_DISABLE_FILESYSTEM`` and options which provide a stub |
---|
62 | implementation of a feature by default and a full implementation if the |
---|
63 | option is defined such as ``CONFIGURE_IMFS_ENABLE_MKFIFO``. These options |
---|
64 | are specified by :ref:`SpecTypeApplicationConfigurationFeatureOptionItemType` |
---|
65 | items. |
---|
66 | |
---|
67 | * The *integer value options* let the application define a specific value for a |
---|
68 | system parameter. If the option is not defined, then a default value is used |
---|
69 | for the system parameter. Examples are options which define the maximum |
---|
70 | count of objects available for application use such as |
---|
71 | ``CONFIGURE_MAXIMUM_TASKS``. These options are specified by |
---|
72 | :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. |
---|
73 | |
---|
74 | * The *initializer options* let the application define a specific initializer |
---|
75 | for a system parameter. If the option is not defined, then a default setting |
---|
76 | is used for the system parameter. An example option of this type is |
---|
77 | ``CONFIGURE_INITIAL_EXTENSIONS``. These options are specified by |
---|
78 | :ref:`SpecTypeApplicationConfigurationValueOptionItemType` items. |
---|
79 | |
---|
80 | Sphinx documentation sources and header files with Doxygen markup are generated |
---|
81 | from the specification items. The descriptions in the items shall use a |
---|
82 | restricted Sphinx formatting. Emphasis via one asterisk ("*"), strong emphasis |
---|
83 | via two asterisk ("**"), code samples via blockquotes ("``"), code blocks (".. |
---|
84 | code-block:: c") and lists are allowed. References to interface items are also |
---|
85 | allowed, for example "${appl-needs-clock-driver:/name}" and |
---|
86 | "${../rtems/tasks/create:/name}". References to other parts of the |
---|
87 | documentation are possible, however, they are currently provided by hard-coded |
---|
88 | tables in :file:`rtemsspec/applconfig.py`. |
---|
89 | |
---|
90 | Modify an Existing Group |
---|
91 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
92 | |
---|
93 | Search for the group by its section header and edit the specification item |
---|
94 | file. For example: |
---|
95 | |
---|
96 | .. code-block:: none |
---|
97 | |
---|
98 | $ grep -rl "name: General System Configuration" spec/if/acfg |
---|
99 | spec/if/acfg/group-general.yml |
---|
100 | $ vi spec/if/acfg/group-general.yml |
---|
101 | |
---|
102 | Modify an Existing Option |
---|
103 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
104 | |
---|
105 | Search for the option by its C preprocessor define name and edit the |
---|
106 | specification item file. For example: |
---|
107 | |
---|
108 | .. code-block:: none |
---|
109 | |
---|
110 | $ grep -rl CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER spec/if/acfg |
---|
111 | spec/if/acfg/appl-needs-clock-driver.yml |
---|
112 | $ vi spec/if/acfg/appl-needs-clock-driver.yml |
---|
113 | |
---|
114 | Add a New Group |
---|
115 | ^^^^^^^^^^^^^^^ |
---|
116 | |
---|
117 | Let ``new`` be the UID name part of the new group. Create the file |
---|
118 | :file:`spec/if/acfg/group-new.yml` and provide all attributes for an |
---|
119 | :ref:`SpecTypeApplicationConfigurationGroupItemType` item. For example: |
---|
120 | |
---|
121 | .. code-block:: none |
---|
122 | |
---|
123 | $ vi spec/if/acfg/group-new.yml |
---|
124 | |
---|
125 | Add a New Option |
---|
126 | ^^^^^^^^^^^^^^^^ |
---|
127 | |
---|
128 | Let ``my-new-option`` be the UID name of the option. Create the file |
---|
129 | :file:`if/acfg/my-new-option.yml` and provide all attributes for an appropriate |
---|
130 | refinement of :ref:`SpecTypeApplicationConfigurationOptionItemType`. For |
---|
131 | example: |
---|
132 | |
---|
133 | .. code-block:: none |
---|
134 | |
---|
135 | $ vi spec/if/acfg/my-new-option.yml |
---|
136 | |
---|
137 | Generate Content after Changes |
---|
138 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
139 | |
---|
140 | Once you are done with the modifications of an existing item or the creation of |
---|
141 | a new item, the changes need to be propagated to generated source files. This |
---|
142 | is done by the :file:`spec2modules.py` script. Before you call this script, |
---|
143 | make sure the Git submodules are up-to-date. |
---|
144 | |
---|
145 | .. code-block:: none |
---|
146 | |
---|
147 | $ ./spec2dmodules.py |
---|
148 | |
---|
149 | The script modifies or creates source files in :file:`modules/rtems` and |
---|
150 | :file:`modules/rtems-docs`. Create patch sets for these changes just as if |
---|
151 | these were work done by a human and follow the normal patch review process |
---|
152 | described in the *RTEMS User Manual*. When the changes are integrated, update |
---|
153 | the Git submodules and check in the changed items. |
---|
154 | |
---|
155 | Glossary Specification |
---|
156 | ---------------------- |
---|
157 | |
---|
158 | The glossary of terms for the RTEMS Project is defined by |
---|
159 | :ref:`SpecTypeGlossaryTermItemType` items in the :file:`spec/glossary` |
---|
160 | directory. For a new glossary term add a glossary item to this directory. As |
---|
161 | the file name use the term in lower case with all white space and special |
---|
162 | characters removed or replaced by alphanumeric characters, for example |
---|
163 | :file:`spec/glossary/magicpower.yml` for the term `magic power`. |
---|
164 | |
---|
165 | Use ``${uid:/attribute}`` substitutions to reference other parts of the |
---|
166 | specification. |
---|
167 | |
---|
168 | .. code-block:: yaml |
---|
169 | |
---|
170 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
171 | copyrights: |
---|
172 | - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) |
---|
173 | enabled-by: true |
---|
174 | glossary-type: term |
---|
175 | links: |
---|
176 | - role: glossary-member |
---|
177 | uid: ../glossary-general |
---|
178 | term: magic power |
---|
179 | text: | |
---|
180 | Magic power enables a caller to create magic objects using a |
---|
181 | ${magicwand:/term}. |
---|
182 | type: glossary |
---|
183 | |
---|
184 | Define acronyms with the phrase `This term is an acronym for *.` in the |
---|
185 | ``text`` attribute: |
---|
186 | |
---|
187 | .. code-block:: yaml |
---|
188 | |
---|
189 | ... |
---|
190 | term: MP |
---|
191 | ... |
---|
192 | text: | |
---|
193 | This term is an acronym for Magic Power. |
---|
194 | ... |
---|
195 | |
---|
196 | Once you are done with the glossary items, run the script |
---|
197 | :file:`spec2modules.py` to generate the derived documentation content. Send |
---|
198 | patches for the generated documentation and the specification to the |
---|
199 | :r:list:`devel` and follow the normal patch review process. |
---|
200 | |
---|
201 | Interface Specification |
---|
202 | ----------------------- |
---|
203 | |
---|
204 | .. _ReqEngAddAPIHeaderFile: |
---|
205 | |
---|
206 | Specify an API Header File |
---|
207 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
208 | |
---|
209 | The RTEMS :term:`API` header files are specified under ``spec:/if/rtems/*``. |
---|
210 | Create a subdirectory with a corresponding name for the API, for example in |
---|
211 | :file:`spec/if/rtems/foo` for the `foo` API. In this new subdirectory place an |
---|
212 | :ref:`SpecTypeInterfaceHeaderFileItemType` item named :file:`header.yml` |
---|
213 | (:file:`spec/if/rtems/foo/header.yml`) and populate it with the required |
---|
214 | attributes. |
---|
215 | |
---|
216 | .. code-block:: yaml |
---|
217 | |
---|
218 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
219 | copyrights: |
---|
220 | - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) |
---|
221 | enabled-by: true |
---|
222 | interface-type: header-file |
---|
223 | links: |
---|
224 | - role: interface-placement |
---|
225 | uid: /if/domains/api |
---|
226 | path: rtems/rtems/foo.h |
---|
227 | prefix: cpukit/include |
---|
228 | type: interface |
---|
229 | |
---|
230 | Specify an API Element |
---|
231 | ^^^^^^^^^^^^^^^^^^^^^^ |
---|
232 | |
---|
233 | Figure out the corresponding header file item. If it does not exist, see |
---|
234 | :ref:`ReqEngAddAPIHeaderFile`. Place a specialization of an |
---|
235 | :ref:`SpecTypeInterfaceItemType` item into the directory of the header file |
---|
236 | item, for example :file:`spec/if/rtems/foo/bar.yml` for the :c:func:`bar` |
---|
237 | function. Add the required attributes for the new interface item. Do not hard |
---|
238 | code interface names which are used to define the new interface. Use |
---|
239 | ``${uid-of-interface-item:/name}`` instead. If the referenced interface is |
---|
240 | specified in the same directory, then use a relative UID. Using interface |
---|
241 | references creates implicit dependencies and helps the header file generator to |
---|
242 | resolve the interface dependencies and header file includes for you. Use |
---|
243 | :ref:`SpecTypeInterfaceUnspecifiedItemType` items for interface dependencies to |
---|
244 | other domains such as the C language, the compiler, the implementation, or |
---|
245 | user-provided defines. To avoid cyclic dependencies between types you may use |
---|
246 | an :ref:`SpecTypeInterfaceForwardDeclarationItemType` item. |
---|
247 | |
---|
248 | .. code-block:: yaml |
---|
249 | |
---|
250 | SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause |
---|
251 | brief: Tries to create a magic object and returns it. |
---|
252 | copyrights: |
---|
253 | - Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) |
---|
254 | definition: |
---|
255 | default: |
---|
256 | body: null |
---|
257 | params: |
---|
258 | - ${magic-wand:/name} ${.:/params[0]/name} |
---|
259 | return: ${magic-type:/name} * |
---|
260 | variants: [] |
---|
261 | description: | |
---|
262 | The magic object is created out of nothing with the help of a magic wand. |
---|
263 | enabled-by: true |
---|
264 | interface-type: function |
---|
265 | links: |
---|
266 | - role: interface-placement |
---|
267 | uid: header |
---|
268 | - role: interface-ingroup |
---|
269 | uid: /groups/api/classic/foo |
---|
270 | name: bar |
---|
271 | notes: null |
---|
272 | params: |
---|
273 | - description: is the magic wand. |
---|
274 | dir: null |
---|
275 | name: magic_wand |
---|
276 | return: |
---|
277 | return: Otherwise, the magic object is returned. |
---|
278 | return-values: |
---|
279 | - description: The caller did not have enough magic power. |
---|
280 | value: ${/if/c/null} |
---|
281 | type: interface |
---|