1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 1989, 2007 On-Line Applications Research Corporation (OAR) |
---|
4 | |
---|
5 | Directory Structure |
---|
6 | ******************* |
---|
7 | |
---|
8 | The RTEMS directory structure is designed to meet the following requirements: |
---|
9 | |
---|
10 | - encourage development of modular components. |
---|
11 | |
---|
12 | - isolate processor and target dependent code, while allowing as much common |
---|
13 | source code as possible to be shared across multiple processors and target |
---|
14 | boards. |
---|
15 | |
---|
16 | - allow multiple RTEMS users to perform simultaneous compilation of RTEMS and |
---|
17 | its support facilities for different processors and targets. |
---|
18 | |
---|
19 | The resulting directory structure has processor and board dependent source |
---|
20 | files isolated from generic files. When RTEMS is configured and built, object |
---|
21 | directories and an install point will be automatically created based upon the |
---|
22 | target CPU family and BSP selected. |
---|
23 | |
---|
24 | The placement of object files based upon the selected BSP name ensures that |
---|
25 | object files are not mixed across CPUs or targets. This in combination with |
---|
26 | the makefiles allows the specific compilation options to be tailored for a |
---|
27 | particular target board. For example, the efficiency of the memory subsystem |
---|
28 | for a particular target board may be sensitive to the alignment of data |
---|
29 | structures, while on another target board with the same processor memory may be |
---|
30 | very limited. For the first target, the options could specify very strict |
---|
31 | alignment requirements, while on the second the data structures could be |
---|
32 | *packed* to conserve memory. It is impossible to achieve this degree of |
---|
33 | flexibility without providing source code. |
---|
34 | |
---|
35 | The RTEMS source tree is organized based on the following variables: |
---|
36 | |
---|
37 | - functionality, |
---|
38 | |
---|
39 | - target processor family, |
---|
40 | |
---|
41 | - target processor model, |
---|
42 | |
---|
43 | - peripherals, and |
---|
44 | |
---|
45 | - target board. |
---|
46 | |
---|
47 | Each of the following sections will describe the contents of the directories in |
---|
48 | the RTEMS source tree. The top of the tree will be referenced as |
---|
49 | ``${RTEMS_ROOT}`` in this discussion. |
---|
50 | |
---|
51 | .. code-block:: c |
---|
52 | |
---|
53 | rtems-VERSION |
---|
54 | | |
---|
55 | +----+----+----+--+-----+---+-------+--------+ |
---|
56 | | | | | | | | | |
---|
57 | c contrib cpukit doc make testsuites tools |
---|
58 | |
---|
59 | ``${RTEMS_ROOT}/c/`` |
---|
60 | Historically, this directory was the root of the portions of the |
---|
61 | RTEMS source tree which must be built tailored for a particular CPU |
---|
62 | model or BSP. In the current source, only the build support files for |
---|
63 | the autoconf/automake based build system remain in this subdirectory. |
---|
64 | |
---|
65 | ``${RTEMS_ROOT}/cpukit/`` |
---|
66 | This directory is the root for all of the "multilib'able" portions of |
---|
67 | RTEMS. This is a GNU way of saying the contents of this directory can be |
---|
68 | compiled like the C Library (``libc.a``) and the functionality is neither |
---|
69 | CPU model nor BSP specific. The source code for most RTEMS services reside |
---|
70 | under this directory. The contents of this directory will be discussed in |
---|
71 | the `CPU Kit Directory`_ section. |
---|
72 | |
---|
73 | ``${RTEMS_ROOT}/bsps`` |
---|
74 | This directory is the root for all of the BSP specific source in |
---|
75 | RTEMS. The contents of this directory are discussed in the `BSPs |
---|
76 | Directory`_ section. |
---|
77 | |
---|
78 | ``${RTEMS_ROOT}/make/`` |
---|
79 | This directory contains files which support RTEMS Makefile's. From a |
---|
80 | user's perspective, the most important part is the BSP specific |
---|
81 | information found in the ``config`` subdirectory of each BSP. |
---|
82 | Each ".cfg" file is associated with a specific BSP |
---|
83 | and describes the CPU model, and compiler flags used to produce |
---|
84 | an executable for the target board. These files are described in |
---|
85 | detail in the *RTEMS BSP and Driver Guide* and will not be discussed |
---|
86 | further in this document. |
---|
87 | |
---|
88 | ``${RTEMS_ROOT}/testsuites/`` |
---|
89 | This directory contains the test suites for the various RTEMS APIs and |
---|
90 | support libraries. The contents of this directory are discussed in the |
---|
91 | `testsuites/ Test Suites`_ section. |
---|
92 | |
---|
93 | BSPs Directory |
---|
94 | ~~~~~~~~~~~~~~ |
---|
95 | |
---|
96 | The "bsps" directory contains a directory for each CPU family supported by |
---|
97 | RTEMS. Beneath each CPU directory is a directory for each BSP for that |
---|
98 | processor family. |
---|
99 | |
---|
100 | The "bsps" directory provides all the BSPs provided with this release |
---|
101 | of RTEMS. The subdirectories are divided, as discussed previously, |
---|
102 | based on specific processor family, then further broken down into specific |
---|
103 | target board environments. The "no_cpu" subdirectory provides a starting |
---|
104 | point template BSP which can be used to develop a specific BSP for an |
---|
105 | unsupported target board. The files in this subdirectory may aid in |
---|
106 | preliminary testing of the RTEMS development environment that has been |
---|
107 | built for no particular target in mind. |
---|
108 | |
---|
109 | Below each CPU dependent directory is a directory for each target BSP supported |
---|
110 | in this release. |
---|
111 | |
---|
112 | Each BSP provides the modules which comprise an RTEMS BSP. The modules are |
---|
113 | separated into various subdirectories such as "clock", "console", |
---|
114 | "include", "shmsupp", "startup", and "timer" as shown in the following |
---|
115 | figure: |
---|
116 | |
---|
117 | .. code-block:: c |
---|
118 | |
---|
119 | Each BSP |
---|
120 | | |
---|
121 | +-----------+----------+-----+-----+----------+----------+ |
---|
122 | | | | | | | |
---|
123 | clock console include shmsupp startup timer |
---|
124 | |
---|
125 | CPU Kit Directory |
---|
126 | ================= |
---|
127 | |
---|
128 | The @code{cpukit/} directory contains many subdirectories with the |
---|
129 | most important ones being shown in the structure below: |
---|
130 | |
---|
131 | .. code-block:: c |
---|
132 | |
---|
133 | cpukit |
---|
134 | | |
---|
135 | +-----------+----------+-----------+ |
---|
136 | | | | | |
---|
137 | posix rtems sapi score |
---|
138 | |
---|
139 | The ``cpukit/`` directory contains a set of subdirectories which contains the |
---|
140 | source files comprising the executive portion of the RTEMS development |
---|
141 | environment as well as portable support libraries such as support for the C |
---|
142 | Library and filesystems. The API specific and "SuperCore" (e.g. ``score/`` |
---|
143 | directory) source code files are separated into distinct directory trees. |
---|
144 | |
---|
145 | The following is a description of each of the subdirectories under ``cpukit/``: |
---|
146 | |
---|
147 | ``${RTEMS_ROOT}/cpukit/ftpd/`` |
---|
148 | This directory contains the RTEMS ftpd server. |
---|
149 | |
---|
150 | ``${RTEMS_ROOT}/cpukit/mhttpd/`` |
---|
151 | This directory contains the port of the Mongoose web server to RTEMS. |
---|
152 | |
---|
153 | ``${RTEMS_ROOT}/cpukit/include/`` |
---|
154 | This directory contains header files which are private to RTEMS and not |
---|
155 | considered to be owned by any other component in the CPU Kit. |
---|
156 | |
---|
157 | ``${RTEMS_ROOT}/cpukit/libblock/`` |
---|
158 | This directory contains support code for using Block Devices such as hard |
---|
159 | drives, floppies, and CD-ROMs. It includes the generic IO primitives for |
---|
160 | block device drivers, disk caching support, and a RAM disk block device |
---|
161 | driver. |
---|
162 | |
---|
163 | ``${RTEMS_ROOT}/cpukit/libcsupport/`` |
---|
164 | This directory contains the RTEMS specific support routines for the Newlib |
---|
165 | C Library. This includes what are referred to as system calls and found in |
---|
166 | section 2 of the traditional UNIX manual. In addition, it contains a |
---|
167 | thread-safe implementation of the Malloc family of routines as well as BSD |
---|
168 | and POSIX services not found in Newlib. |
---|
169 | |
---|
170 | ``${RTEMS_ROOT}/cpukit/libfs/`` |
---|
171 | This directory contains the various non-networked filesystem |
---|
172 | implementations for RTEMS. It includes the In-Memory FileSystem (IMFS), |
---|
173 | the mini-IMFS, and FAT filesystems. |
---|
174 | |
---|
175 | ``${RTEMS_ROOT}/cpukit/libi2c/`` |
---|
176 | This directory contains the RTEMS I2C framework. |
---|
177 | |
---|
178 | ``${RTEMS_ROOT}/cpukit/libmd/`` |
---|
179 | This directory contains a port of the standard MD5 checksum code. |
---|
180 | |
---|
181 | ``${RTEMS_ROOT}/cpukit/libmisc/`` |
---|
182 | This directory contains support facilities which are RTEMS specific but |
---|
183 | otherwise unclassified. In general, they do not adhere to a standard API. |
---|
184 | Among the support facilities in this directory are a ``/dev/null`` device |
---|
185 | driver, the Stack Overflow Checker, a mini-shell, the CPU and rate |
---|
186 | monotonic period usage monitoring libraries, and a utility to "dump a |
---|
187 | buffer" in a nicely formatted way similar to many ROM monitors. |
---|
188 | |
---|
189 | ``${RTEMS_ROOT}/cpukit/libnetworking/`` |
---|
190 | This directory contains the port of the FreeBSD TCP/IP stack to RTEMS. |
---|
191 | |
---|
192 | ``${RTEMS_ROOT}/cpukit/librpc/`` |
---|
193 | This directory contains the port of the FreeBSD RPC/XDR source to RTEMS. |
---|
194 | |
---|
195 | ``${RTEMS_ROOT}/cpukit/libpci/`` |
---|
196 | This directory contains RTEMS PCI Library. |
---|
197 | |
---|
198 | ``${RTEMS_ROOT}/cpukit/posix/`` |
---|
199 | This directory contains the RTEMS implementation of the threading portions |
---|
200 | of the POSIX API. |
---|
201 | |
---|
202 | ``${RTEMS_ROOT}/cpukit/pppd/`` |
---|
203 | This directory contains a port of the free implementation of the PPPD |
---|
204 | network protocol. |
---|
205 | |
---|
206 | ``${RTEMS_ROOT}/cpukit/rtems/`` |
---|
207 | This directory contains the implementation of the Classic API. |
---|
208 | |
---|
209 | ``${RTEMS_ROOT}/cpukit/sapi/`` |
---|
210 | This directory contains the implementation of RTEMS services which are |
---|
211 | required but beyond the realm of any standardization efforts. It includes |
---|
212 | initialization, shutdown, and IO services. |
---|
213 | |
---|
214 | ``${RTEMS_ROOT}/cpukit/score/`` |
---|
215 | This directory contains the "SuperCore" of RTEMS. All APIs are implemented |
---|
216 | in terms of SuperCore services. For example, Classic API tasks and POSIX |
---|
217 | threads are all implemented in terms of SuperCore threads. This provides a |
---|
218 | common infrastructure and a high degree of interoperability between the |
---|
219 | APIs. For example, services from all APIs may be used by any task/thread |
---|
220 | independent of the API used to create it. Within the ``score/`` directory |
---|
221 | the CPU dependent modules are found. The ``score/cpu/`` subdirectory |
---|
222 | contains a subdirectory for each target CPU supported by this release of |
---|
223 | the RTEMS executive. Each processor directory contains the CPU dependent |
---|
224 | code necessary to host RTEMS. The ``no_cpu`` directory provides a starting |
---|
225 | point for developing a new port to an unsupported processor. The files |
---|
226 | contained within the ``no_cpu`` directory may also be used as a reference |
---|
227 | for the other ports to specific processors. |
---|
228 | |
---|
229 | ``${RTEMS_ROOT}/cpukit/telnetd/`` |
---|
230 | This directory contains the RTEMS telnetd server. |
---|
231 | |
---|
232 | ``${RTEMS_ROOT}/cpukit/wrapup/`` |
---|
233 | This directory is responsible for taking the individual libraries and |
---|
234 | objects built in each of the components in the RTEMS CPU Kit source tree |
---|
235 | and bundling them together to form the single RTEMS library |
---|
236 | ``librtemscpu.a``. This library contains all BSP and CPU model specific |
---|
237 | software. |
---|
238 | |
---|
239 | ``${RTEMS_ROOT}/cpukit/zlib/`` |
---|
240 | This directory contains a port of the GNU Zlib compression library to |
---|
241 | RTEMS. |
---|
242 | |
---|
243 | testsuites/ Test Suites |
---|
244 | ======================= |
---|
245 | |
---|
246 | This directory provides all of the RTEMS Test Suite except those for the |
---|
247 | Classic API Ada95 binding This includes the single processor tests, |
---|
248 | multiprocessor tests, timing tests, library tests, and sample tests. |
---|
249 | Additionally, subdirectories for support functions and test related header |
---|
250 | files are provided. The following table lists the test suites currently |
---|
251 | included with the RTEMS and the directory in which they may be located: |
---|
252 | |
---|
253 | ``${RTEMS_ROOT}/testsuites/libtests/`` |
---|
254 | This directory contains the test suite for the various RTEMS support |
---|
255 | components. |
---|
256 | |
---|
257 | ``${RTEMS_ROOT}/testsuites/mptests/`` |
---|
258 | This directory contains the test suite for the multiprocessor support in |
---|
259 | the Classic API. The tests provided address two node configurations and |
---|
260 | provide coverage for the multiprocessor code found in RTEMS. |
---|
261 | |
---|
262 | ``${RTEMS_ROOT}/testsuites/psxtests/`` |
---|
263 | This directory contains the test suite for the RTEMS POSIX API. |
---|
264 | |
---|
265 | ``${RTEMS_ROOT}/testsuites/samples/`` |
---|
266 | This directory provides sample application tests which aid in the testing a |
---|
267 | newly built RTEMS environment, a new BSP, or as starting points for the |
---|
268 | development of an application using the RTEMS executive. They are |
---|
269 | discussed in ::ref::`Sample Applications`. |
---|
270 | |
---|
271 | ``${RTEMS_ROOT}/testsuites/sptests/`` |
---|
272 | This directory contains the test suite for the RTEMS Classic API when |
---|
273 | executing on a single processor. The tests were originally designed to |
---|
274 | provide near complete test coverage for the entire executive code. With |
---|
275 | the addition of multiple APIs, this is no longer the case as some SuperCore |
---|
276 | functionality is not available through the Classic API. Thus some |
---|
277 | functionality in the SuperCore is only covered by tests in the POSIX API |
---|
278 | Test Suites. |
---|
279 | |
---|
280 | ``${RTEMS_ROOT}/testsuites/support/`` |
---|
281 | This directory contains support software and header files for the various |
---|
282 | test suites. |
---|
283 | |
---|
284 | ``${RTEMS_ROOT}/testsuites/tmtests/`` |
---|
285 | This directory contains the timing test suite for the RTEMS Classic API. |
---|
286 | This include tests that benchmark each directive in the Classic API as well |
---|
287 | as a set of critical SuperCore functions. These tests are important for |
---|
288 | helping to verify that RTEMS performs as expected on your target hardware. |
---|
289 | It is not uncommon to discover mistakes in board initialization such as |
---|
290 | caching being disabled as a side-effect of analyzing the results of these |
---|
291 | tests. |
---|
292 | |
---|
293 | ``${RTEMS_ROOT}/testsuites/tools/`` |
---|
294 | This directory contains tools which execute on the development host and aid |
---|
295 | in executing and evaluating the results of the test suite. The tools |
---|
296 | ``difftest`` compares the output of one or more tests with the expected |
---|
297 | output. If you place the output of all the ``tmtests/`` in a single file, |
---|
298 | then the utility ``sorttimes`` will be able to produce a report organizing |
---|
299 | the execution times by manager. |
---|