1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | :orphan: |
---|
4 | |
---|
5 | |
---|
6 | |
---|
7 | .. COMMENT: %**end of header |
---|
8 | |
---|
9 | .. COMMENT: COPYRIGHT (c) 1989-2013. |
---|
10 | |
---|
11 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
12 | |
---|
13 | .. COMMENT: All rights reserved. |
---|
14 | |
---|
15 | .. COMMENT: Master file |
---|
16 | |
---|
17 | .. COMMENT: Joel's Questions |
---|
18 | |
---|
19 | .. COMMENT: 1. Why does paragraphindent only impact makeinfo? |
---|
20 | |
---|
21 | .. COMMENT: 2. Why does paragraphindent show up in HTML? |
---|
22 | |
---|
23 | .. COMMENT: COPYRIGHT (c) 1988-2002. |
---|
24 | |
---|
25 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
26 | |
---|
27 | .. COMMENT: All rights reserved. |
---|
28 | |
---|
29 | .. COMMENT: The following determines which set of the tables and figures we will use. |
---|
30 | |
---|
31 | .. COMMENT: We default to ASCII but if available TeX or HTML versions will |
---|
32 | |
---|
33 | .. COMMENT: be used instead. |
---|
34 | |
---|
35 | .. COMMENT: @clear use-html |
---|
36 | |
---|
37 | .. COMMENT: @clear use-tex |
---|
38 | |
---|
39 | .. COMMENT: The following variable says to use texinfo or html for the two column |
---|
40 | |
---|
41 | .. COMMENT: texinfo tables. For somethings the format does not look good in html. |
---|
42 | |
---|
43 | .. COMMENT: With our adjustment to the left column in TeX, it nearly always looks |
---|
44 | |
---|
45 | .. COMMENT: good printed. |
---|
46 | |
---|
47 | .. COMMENT: Custom whitespace adjustments. We could fiddle a bit more. |
---|
48 | |
---|
49 | .. COMMENT: variable substitution info: |
---|
50 | |
---|
51 | .. COMMENT: @set LANGUAGE C |
---|
52 | |
---|
53 | .. COMMENT: the language is @value{LANGUAGE} |
---|
54 | |
---|
55 | .. COMMENT: NOTE: don't use underscore in the name |
---|
56 | |
---|
57 | .. COMMENT: Title Page Stuff |
---|
58 | |
---|
59 | .. COMMENT: I don't really like having a short title page. -joel |
---|
60 | |
---|
61 | .. COMMENT: @shorttitlepage RTEMS Development Environment Guide |
---|
62 | |
---|
63 | =================================== |
---|
64 | RTEMS Development Environment Guide |
---|
65 | =================================== |
---|
66 | |
---|
67 | .. COMMENT: COPYRIGHT (c) 1988-2015. |
---|
68 | |
---|
69 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
70 | |
---|
71 | .. COMMENT: All rights reserved. |
---|
72 | |
---|
73 | .. COMMENT: The following puts a space somewhere on an otherwise empty page so we |
---|
74 | |
---|
75 | .. COMMENT: can force the copyright description onto a left hand page. |
---|
76 | |
---|
77 | COPYRIGHT © 1988 - 2015. |
---|
78 | |
---|
79 | On-Line Applications Research Corporation (OAR). |
---|
80 | |
---|
81 | The authors have used their best efforts in preparing |
---|
82 | this material. These efforts include the development, research, |
---|
83 | and testing of the theories and programs to determine their |
---|
84 | effectiveness. No warranty of any kind, expressed or implied, |
---|
85 | with regard to the software or the material contained in this |
---|
86 | document is provided. No liability arising out of the |
---|
87 | application or use of any product described in this document is |
---|
88 | assumed. The authors reserve the right to revise this material |
---|
89 | and to make changes from time to time in the content hereof |
---|
90 | without obligation to notify anyone of such revision or changes. |
---|
91 | |
---|
92 | The RTEMS Project is hosted at http://www.rtems.org. Any |
---|
93 | inquiries concerning RTEMS, its related support components, or its |
---|
94 | documentation should be directed to the Community Project hosted athttp://www.rtems.org. |
---|
95 | |
---|
96 | Any inquiries for commercial services including training, support, custom |
---|
97 | development, application development assistance should be directed tohttp://www.rtems.com. |
---|
98 | |
---|
99 | .. COMMENT: This prevents a black box from being printed on "overflow" lines. |
---|
100 | |
---|
101 | .. COMMENT: The alternative is to rework a sentence to avoid this problem. |
---|
102 | |
---|
103 | RTEMS Development Environment Guide |
---|
104 | ################################### |
---|
105 | |
---|
106 | .. COMMENT: COPYRIGHT (c) 1989-2011. |
---|
107 | |
---|
108 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
109 | |
---|
110 | .. COMMENT: All rights reserved. |
---|
111 | |
---|
112 | Introduction |
---|
113 | ############ |
---|
114 | |
---|
115 | This document describes the RTEMS development |
---|
116 | environment. Discussions are provided for the following topics: |
---|
117 | |
---|
118 | - the directory structure used by RTEMS, |
---|
119 | |
---|
120 | - usage of the GNU Make utility within the RTEMS |
---|
121 | development environment, |
---|
122 | |
---|
123 | - sample applications, and |
---|
124 | |
---|
125 | - the RTEMS specific utilities. |
---|
126 | |
---|
127 | RTEMS was designed as a reusable software component. |
---|
128 | Highly reusable software such as RTEMS is typically distributed |
---|
129 | in the form of source code without providing any support tools. |
---|
130 | RTEMS is the foundation for a complex family of facilities |
---|
131 | including board support packages, device drivers, and support |
---|
132 | libraries. The RTEMS Development Environment is not a CASE |
---|
133 | tool. It is a collection of tools designed to reduce the |
---|
134 | complexity of using and enhancing the RTEMS family. Tools are |
---|
135 | provided which aid in the management of the development, |
---|
136 | maintenance, and usage of RTEMS, its run-time support |
---|
137 | facilities, and applications which utilize the executive. |
---|
138 | |
---|
139 | A key component of the RTEMS development environment |
---|
140 | is the GNU family of free tools. This is robust set of |
---|
141 | development and POSIX compatible tools for which source code is |
---|
142 | freely available. The primary compilers, assemblers, linkers, |
---|
143 | and make utility used by the RTEMS development team are the GNU |
---|
144 | tools. They are highly portable supporting a wide variety of |
---|
145 | host computers and, in the case of the development tools, a wide |
---|
146 | variety of target processors. |
---|
147 | |
---|
148 | It is recommended that the RTEMS developer become |
---|
149 | familiar with the RTEMS Development Environment before |
---|
150 | proceeding with any modifications to the executive source tree. |
---|
151 | The source code for the executive is very modular and source |
---|
152 | code is divided amongst directories based upon functionality as |
---|
153 | well as dependencies on CPU and target board. This organization |
---|
154 | is aimed at isolating and minimizing non-portable code. This |
---|
155 | has the immediate result that adding support for a new CPU or |
---|
156 | target board requires very little "wandering" around the source |
---|
157 | tree. |
---|
158 | |
---|
159 | .. COMMENT: COPYRIGHT (c) 1989-2010. |
---|
160 | |
---|
161 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
162 | |
---|
163 | .. COMMENT: All rights reserved. |
---|
164 | |
---|
165 | Directory Structure |
---|
166 | ################### |
---|
167 | |
---|
168 | The RTEMS directory structure is designed to meet |
---|
169 | the following requirements: |
---|
170 | |
---|
171 | - encourage development of modular components. |
---|
172 | |
---|
173 | - isolate processor and target dependent code, while |
---|
174 | allowing as much common source code as possible to be shared |
---|
175 | across multiple processors and target boards. |
---|
176 | |
---|
177 | - allow multiple RTEMS users to perform simultaneous |
---|
178 | compilation of RTEMS and its support facilities for different |
---|
179 | processors and targets. |
---|
180 | |
---|
181 | The resulting directory structure has processor and |
---|
182 | board dependent source files isolated from generic files. When |
---|
183 | RTEMS is configured and built, object directories and |
---|
184 | an install point will be automatically created based upon |
---|
185 | the target CPU family and BSP selected. |
---|
186 | |
---|
187 | The placement of object files based upon the selected BSP name |
---|
188 | ensures that object files are not mixed across CPUs or targets. |
---|
189 | This in combination with the makefiles allows the specific |
---|
190 | compilation options to be tailored for a particular target |
---|
191 | board. For example, the efficiency of the memory subsystem for |
---|
192 | a particular target board may be sensitive to the alignment of |
---|
193 | data structures, while on another target board with the same |
---|
194 | processor memory may be very limited. For the first target, the |
---|
195 | options could specify very strict alignment requirements, while |
---|
196 | on the second the data structures could be *packed* to conserve |
---|
197 | memory. It is impossible to achieve this degree of flexibility |
---|
198 | without providing source code. |
---|
199 | |
---|
200 | The RTEMS source tree is organized based on the following variables: |
---|
201 | |
---|
202 | - functionality, |
---|
203 | |
---|
204 | - target processor family, |
---|
205 | |
---|
206 | - target processor model, |
---|
207 | |
---|
208 | - peripherals, and |
---|
209 | |
---|
210 | - target board. |
---|
211 | |
---|
212 | Each of the following sections will describe the |
---|
213 | contents of the directories in the RTEMS source |
---|
214 | tree. The top of the tree will be referenced |
---|
215 | as ``${RTEMS_ROOT}`` in this discussion. |
---|
216 | |
---|
217 | .. COMMENT: Top Level Tree |
---|
218 | |
---|
219 | .. COMMENT: @ifset use-ascii |
---|
220 | .. code:: c |
---|
221 | |
---|
222 | rtems-VERSION |
---|
223 | | |
---|
224 | +--------+----+----+----+--+-----+---+-------+--------+ |
---|
225 | | | | | | | | | | |
---|
226 | aclocal automake c contrib cpukit doc make testsuites tools |
---|
227 | |
---|
228 | .. COMMENT: @end ifset |
---|
229 | |
---|
230 | ``${RTEMS_ROOT}/aclocal/`` |
---|
231 | This directory contains the custom M4 macros which are available to |
---|
232 | the various GNU autoconf ``configure.ac`` scripts throughout |
---|
233 | the RTEMS source tree. GNU autoconf interprets ``configure.ac`` |
---|
234 | files to produce the ``configure`` files used to tailor |
---|
235 | RTEMS build for a particular host and target environment. The |
---|
236 | contents of this directory will not be discussed further in this |
---|
237 | document. |
---|
238 | |
---|
239 | ``${RTEMS_ROOT}/automake/`` |
---|
240 | This directory contains the custom GNU automake fragments |
---|
241 | which are used to support the various ``Makefile.am`` |
---|
242 | files throughout the RTEMS source tree. The |
---|
243 | contents of this directory will not be discussed |
---|
244 | further in this document. |
---|
245 | |
---|
246 | ``${RTEMS_ROOT}/c/`` |
---|
247 | This directory is the root of the portions of the RTEMS source |
---|
248 | tree which must be built tailored for a particular CPU model |
---|
249 | or BSP. The contents of this directory will be discussed |
---|
250 | in the `c/ Directory`_ section. |
---|
251 | |
---|
252 | ``${RTEMS_ROOT}/contrib/`` |
---|
253 | This directory contains contributed support software. Currently |
---|
254 | this directory contains the RPM specifications for cross-compilers |
---|
255 | hosted on GNU/Linux that target various operating systems |
---|
256 | including MinGW, Cygwin, FreeBSD, and Solaris. The |
---|
257 | cross-compilers produced using these specifications are then |
---|
258 | used in a Canadian cross build procedure to produce the various |
---|
259 | RTEMS toolsets on a GNU/Linux host. |
---|
260 | This directory also contains RPM specifications for the |
---|
261 | prebuilt cross-compilation toolsets provided by the |
---|
262 | RTEMS project. There are separate subdirectories |
---|
263 | for each of the components in the RTEMS Cross Compilation |
---|
264 | Environment unde the ``contrib/crossrpms/`` directory. |
---|
265 | This directory is configured, built, and installed separately |
---|
266 | from the RTEMS executive and tests. This directory will not |
---|
267 | be discussed further in this document. |
---|
268 | |
---|
269 | ``${RTEMS_ROOT}/cpukit/`` |
---|
270 | This directory is the root for all of the "multilibâable" |
---|
271 | portions of RTEMS. This is a GNU way of saying the |
---|
272 | contents of this directory can be compiled like the |
---|
273 | C Library (``libc.a``) and the functionality is |
---|
274 | neither CPU model nor BSP specific. The source code |
---|
275 | for most RTEMS services reside under this directory. |
---|
276 | The contents of this directory will be discussed |
---|
277 | in the `CPU Kit Directory`_ section. |
---|
278 | |
---|
279 | ``${RTEMS_ROOT}/doc/`` |
---|
280 | This directory is the root for all RTEMS documentation. |
---|
281 | The source for RTEMS is written in GNU TeXinfo and |
---|
282 | used to produce HTML, PDF, and "info" files. |
---|
283 | The RTEMS documentation is configured, built, |
---|
284 | and installed separately from the RTEMS executive and tests. |
---|
285 | The contents of this directory will be discussed |
---|
286 | in the `Documentation Directory`_ section. |
---|
287 | |
---|
288 | ``${RTEMS_ROOT}/make/`` |
---|
289 | This directory contains files which support the |
---|
290 | RTEMS Makefileâs. From a userâs perspective, the |
---|
291 | most important parts are found in the ``custom/`` |
---|
292 | subdirectory. Each ".cfg" file in this directory |
---|
293 | is associated with a specific BSP and describes |
---|
294 | the CPU model, compiler flags, and procedure to |
---|
295 | produce an executable for the target board. |
---|
296 | These files are described in detail in the*RTEMS BSP and Device Driver Development Guide* |
---|
297 | and will not be discussed further in this document. |
---|
298 | |
---|
299 | ``${RTEMS_ROOT}/testsuites/`` |
---|
300 | This directory contains the test suites for the |
---|
301 | various RTEMS APIs and support libraries. The |
---|
302 | contents of this directory are discussed in the `testsuites/ Test Suites`_ section. |
---|
303 | |
---|
304 | ``${RTEMS_ROOT}/tools/`` |
---|
305 | This directory contains RTEMS specific support utilities which |
---|
306 | execute on the development host. These utilities are divided |
---|
307 | into subdirectories based upon whether they are used in the process |
---|
308 | of building RTEMS and applications, are CPU specific, or are |
---|
309 | used to assist in updating the RTEMS source tree and applications. |
---|
310 | The support utilities used in the process of building RTEMS are |
---|
311 | described in `RTEMS Specific Utilities`_. These are the |
---|
312 | only components of this subtree that will be discussed in this |
---|
313 | document. |
---|
314 | |
---|
315 | .. COMMENT: c/ Directions |
---|
316 | |
---|
317 | c/ Directory |
---|
318 | ============ |
---|
319 | |
---|
320 | The ``${RTEMS_ROOT}/c/`` directory was formerly |
---|
321 | the root directory of all RTEMS source code. At this time, it contains |
---|
322 | the root directory for only those RTEMS components |
---|
323 | which must be compiled or linked in a way that is specific to a |
---|
324 | particular CPU model or board. This directory contains the |
---|
325 | following subdirectories: |
---|
326 | |
---|
327 | ``${RTEMS_ROOT}/c/src/`` |
---|
328 | This directory is logically the root for the RTEMS components |
---|
329 | which are CPU model or board dependent. Thus this directory |
---|
330 | is the root for the BSPs and the Ada Test Suites as well |
---|
331 | as CPU model and BSP dependent libraries. The contents of |
---|
332 | this directory are discussed in the `c/src/ Directory`_ section. |
---|
333 | |
---|
334 | .. COMMENT: c/src/ Directory |
---|
335 | |
---|
336 | c/src/ Directory |
---|
337 | ---------------- |
---|
338 | |
---|
339 | As mentioned previously, this directory is logically |
---|
340 | the root for the RTEMS components |
---|
341 | which are CPU model or board dependent. The |
---|
342 | following is a list of the subdirectories in this |
---|
343 | directory and a description of each. |
---|
344 | |
---|
345 | ``${RTEMS_ROOT}/c/src/aclocal/`` |
---|
346 | This directory contains the custom M4 macros which are available to |
---|
347 | the various GNU autoconf ``configure.ac`` scripts throughout |
---|
348 | this portion of the RTEMS source tree. GNU autoconf interprets``configure.ac`` files to produce the ``configure`` files used |
---|
349 | to tailor RTEMS build for a particular host and target environment. The |
---|
350 | contents of this directory will not be discussed further in this |
---|
351 | document. |
---|
352 | |
---|
353 | ``${RTEMS_ROOT}/c/src/ada/`` |
---|
354 | This directory contains the Ada95 language bindings to the |
---|
355 | RTEMS Classic API. |
---|
356 | |
---|
357 | ``${RTEMS_ROOT}/c/src/ada-tests/`` |
---|
358 | This directory contains the test suite for the Ada |
---|
359 | language bindings to the Classic API. |
---|
360 | |
---|
361 | ``${RTEMS_ROOT}/c/src/automake/`` |
---|
362 | This directory contains files which are "Makefile fragments." |
---|
363 | They are included as required by the various ``Makefile.am`` |
---|
364 | files throughout this portion of the RTEMS source tree. |
---|
365 | |
---|
366 | ``${RTEMS_ROOT}/c/src/lib/`` |
---|
367 | This directory contains the directories ``libbsp/`` |
---|
368 | and ``libcpu/`` which contain the source code for |
---|
369 | the Board Support Packages (BSPs) and CPU Model |
---|
370 | specific source code for RTEMS. |
---|
371 | The ``libbsp/`` is organized based upon the CPU |
---|
372 | family and boards BSPs. The contents of ``libbsp/`` |
---|
373 | are discussed briefly in `c/src/lib/libbsp BSP Directory`_ |
---|
374 | and presented in detail in the*RTEMS BSP and Device Driver Development Guide*. |
---|
375 | The ``libcpu/`` directory is also organized by |
---|
376 | CPU family with further divisions based upon CPU |
---|
377 | model and features that are shared across CPU models |
---|
378 | such as caching and DMA. |
---|
379 | |
---|
380 | ``${RTEMS_ROOT}/c/src/libchip/`` |
---|
381 | This directory contains device drivers for various |
---|
382 | peripheral chips which are designed to be CPU and |
---|
383 | board dependent. This directory contains a variety |
---|
384 | of drivers for serial devices, network interface |
---|
385 | controllers, shared memory and real-time clocks. |
---|
386 | |
---|
387 | ``${RTEMS_ROOT}/c/src/librtems++/`` |
---|
388 | This directory contains C++ classes which map to the RTEMS |
---|
389 | Classic API. |
---|
390 | |
---|
391 | ``${RTEMS_ROOT}/c/src/make/`` |
---|
392 | This directory is used to generate the bulk of the supporting |
---|
393 | rules files which are installed as part of the Application Makefiles. |
---|
394 | This file contains settings for various Makefile variables to |
---|
395 | tailor them to the particular CPU model and BSP configured. |
---|
396 | |
---|
397 | ``${RTEMS_ROOT}/c/src/nfsclient/`` |
---|
398 | This directory contains a Network File System (NFS) client |
---|
399 | for RTEMS. With this file system, a userâs application can |
---|
400 | access files on a remote computer. |
---|
401 | |
---|
402 | ``${RTEMS_ROOT}/c/src/optman/`` |
---|
403 | This directory contains stubs for the RTEMS Classic API |
---|
404 | Managers which are considered optional and whose use |
---|
405 | may be explicitly forbidden by an application. All of the |
---|
406 | directive implementations in this Optional Managers |
---|
407 | return ``E_NOTCONFIGURED``. |
---|
408 | |
---|
409 | ``${RTEMS_ROOT}/c/src/support/`` |
---|
410 | This directory exists solely to generate the RTEMS |
---|
411 | version string which includes the RTEMS version, |
---|
412 | CPU architecture, CPU model, and BSP name. |
---|
413 | |
---|
414 | ``${RTEMS_ROOT}/c/src/wrapup/`` |
---|
415 | This directory is responsible for taking the individual |
---|
416 | libraries and objects built in each of the components |
---|
417 | in the RTEMS source tree and bundling them together to form |
---|
418 | the single RTEMS library ``librtemsbsp.a``. This |
---|
419 | library contains all BSP and CPU model specific software. |
---|
420 | |
---|
421 | .. COMMENT: c/src/lib/libbsp BSP Directory |
---|
422 | |
---|
423 | c/src/lib/libbsp BSP Directory |
---|
424 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
425 | |
---|
426 | The "libbsp" directory contains a directory for each CPU family supported |
---|
427 | by RTEMS. Beneath each CPU directory is a directory for each BSP for that |
---|
428 | processor family. |
---|
429 | |
---|
430 | .. COMMENT: Tree 7 - C BSP Library |
---|
431 | |
---|
432 | The "libbsp" directory provides all the BSPs provided with this |
---|
433 | release of the RTEMS executive. The subdirectories are |
---|
434 | divided, as discussed previously, based on specific processor |
---|
435 | family, then further broken down into specific target board |
---|
436 | environments. The "no_cpu" subdirectory provides a starting point |
---|
437 | template BSP which can be used to develop a specific BSP for an |
---|
438 | unsupported target board. The files in this subdirectory may aid |
---|
439 | in preliminary testing of the RTEMS development environment that has |
---|
440 | been built for no particular target in mind. |
---|
441 | |
---|
442 | Below each CPU dependent directory is a directory for each target BSP |
---|
443 | supported in this release. |
---|
444 | |
---|
445 | Each BSP provides the modules which comprise an RTEMS BSP. The |
---|
446 | modules are separated into the subdirectories "clock", "console", |
---|
447 | "include", "shmsupp", "startup", and "timer" as shown in the following |
---|
448 | figure: |
---|
449 | |
---|
450 | .. COMMENT: Tree 8 - Each BSP |
---|
451 | |
---|
452 | .. COMMENT: @ifset use-ascii |
---|
453 | .. code:: c |
---|
454 | |
---|
455 | Each BSP |
---|
456 | | |
---|
457 | +-----------+----------+-----+-----+----------+----------+ |
---|
458 | | | | | | | |
---|
459 | clock console include shmsupp startup timer |
---|
460 | |
---|
461 | .. COMMENT: @end ifset |
---|
462 | |
---|
463 | .. COMMENT: CPU Kit Directory |
---|
464 | |
---|
465 | CPU Kit Directory |
---|
466 | ================= |
---|
467 | |
---|
468 | .. COMMENT: The @code{cpukit/} directory structure is as follows: |
---|
469 | |
---|
470 | .. COMMENT: CPU Kit Tree |
---|
471 | |
---|
472 | .. COMMENT: @ifset use-ascii |
---|
473 | |
---|
474 | .. COMMENT: @example |
---|
475 | |
---|
476 | .. COMMENT: @group |
---|
477 | |
---|
478 | .. COMMENT: cpukit |
---|
479 | |
---|
480 | .. COMMENT: | |
---|
481 | |
---|
482 | .. COMMENT: +-+-+-+-+ |
---|
483 | |
---|
484 | .. COMMENT: | | | | | |
---|
485 | |
---|
486 | .. COMMENT: posix rtems sapi score wrapup |
---|
487 | |
---|
488 | .. COMMENT: @end group |
---|
489 | |
---|
490 | .. COMMENT: @end example |
---|
491 | |
---|
492 | .. COMMENT: @end ifset |
---|
493 | |
---|
494 | The ``cpukit/`` directory contains a set of subdirectories which |
---|
495 | contains the source files comprising the executive portion of |
---|
496 | the RTEMS development environment as well as portable support |
---|
497 | libraries such as support for the C Library and filesystems. |
---|
498 | The API specific and "SuperCore" (e.g. ``score/`` directory) |
---|
499 | source code files are separated into distinct directory trees. |
---|
500 | |
---|
501 | The following is a description of each of the subdirectories |
---|
502 | under ``cpukit/``: |
---|
503 | |
---|
504 | ``${RTEMS_ROOT}/cpukit/aclocal/`` |
---|
505 | This directory contains the custom M4 macros which are available to |
---|
506 | the various GNU autoconf ``configure.ac`` scripts throughout |
---|
507 | the CPU Kit portion of the RTEMS source tree. |
---|
508 | GNU autoconf interprets ``configure.ac`` |
---|
509 | files to produce the ``configure`` files used to tailor |
---|
510 | RTEMS build for a particular host and target environment. The |
---|
511 | contents of this directory will not be discussed further in this |
---|
512 | document. |
---|
513 | |
---|
514 | ``${RTEMS_ROOT}/cpukit/automake/`` |
---|
515 | This directory contains files which are "Makefile fragments." |
---|
516 | They are included as required by the various ``Makefile.am`` |
---|
517 | files throughout the CPU Kit portion of the RTEMS source tree. |
---|
518 | |
---|
519 | ``${RTEMS_ROOT}/cpukit/ftpd/`` |
---|
520 | This directory contains the RTEMS ftpd server. |
---|
521 | |
---|
522 | ``${RTEMS_ROOT}/cpukit/httpd/`` |
---|
523 | This directory contains the port of the GoAhead |
---|
524 | web server to RTEMS. |
---|
525 | |
---|
526 | ``${RTEMS_ROOT}/cpukit/include/`` |
---|
527 | This directory contains header files which are private to |
---|
528 | RTEMS and not considered to be owned by any other component |
---|
529 | in the CPU Kit. |
---|
530 | |
---|
531 | ``${RTEMS_ROOT}/cpukit/libblock/`` |
---|
532 | This directory contains support code for using |
---|
533 | Block Devices such as hard drives, floppies, and |
---|
534 | CD-ROMs. It includes the generic IO primitives |
---|
535 | for block device drivers, disk caching support, |
---|
536 | and a RAM disk block device driver. |
---|
537 | |
---|
538 | ``${RTEMS_ROOT}/cpukit/libcsupport/`` |
---|
539 | This directory contains the RTEMS specific support routines |
---|
540 | for the Newlib C Library. This includes what are referred |
---|
541 | to as system calls and found in section 2 of the traditional |
---|
542 | UNIX manual. In addition, it contains a thread-safe |
---|
543 | implementation of the Malloc family of routines as well |
---|
544 | as BSD and POSIX services not found in Newlib. |
---|
545 | |
---|
546 | ``${RTEMS_ROOT}/cpukit/libfs/`` |
---|
547 | This directory contains the various non-networked |
---|
548 | filesystem implementations for RTEMS. It includes |
---|
549 | the In-Memory FileSystem (IMFS), the mini-IMFS, |
---|
550 | and FAT filesystems. |
---|
551 | |
---|
552 | ``${RTEMS_ROOT}/cpukit/libi2c/`` |
---|
553 | This directory contains the RTEMS I2C framework. |
---|
554 | |
---|
555 | ``${RTEMS_ROOT}/cpukit/libmd/`` |
---|
556 | This directory contains a port of the standard MD5 |
---|
557 | checksum code. |
---|
558 | |
---|
559 | ``${RTEMS_ROOT}/c/src/libmisc/`` |
---|
560 | This directory contains support facilities which |
---|
561 | are RTEMS specific but otherwise unclassified. In |
---|
562 | general, they do not adhere to a standard API. |
---|
563 | Among the support facilities in this directory are |
---|
564 | a ``/dev/null`` device driver, the Stack |
---|
565 | Overflow Checker, a mini-shell, the CPU and |
---|
566 | rate monotonic period usage monitoring libraries, |
---|
567 | and a utility to "dump a buffer" in a nicely |
---|
568 | formatted way similar to many ROM monitors. |
---|
569 | |
---|
570 | ``${RTEMS_ROOT}/cpukit/libnetworking/`` |
---|
571 | This directory contains the port of the FreeBSD |
---|
572 | TCP/IP stack to RTEMS. |
---|
573 | |
---|
574 | ``${RTEMS_ROOT}/cpukit/librpc/`` |
---|
575 | This directory contains the port of the FreeBSD |
---|
576 | RPC/XDR source to RTEMS. |
---|
577 | |
---|
578 | ``${RTEMS_ROOT}/cpukit/libpci/`` |
---|
579 | This directory contains RTEMS PCI Library. |
---|
580 | |
---|
581 | ``${RTEMS_ROOT}/cpukit/posix/`` |
---|
582 | This directory contains the RTEMS implementation |
---|
583 | of the threading portions of the POSIX API. |
---|
584 | |
---|
585 | ``${RTEMS_ROOT}/cpukit/pppd/`` |
---|
586 | This directory contains a port of the free implementation |
---|
587 | of the PPPD network protocol. |
---|
588 | |
---|
589 | ``${RTEMS_ROOT}/cpukit/rtems/`` |
---|
590 | This directory contains the implementation of the |
---|
591 | Classic API. |
---|
592 | |
---|
593 | ``${RTEMS_ROOT}/cpukit/sapi/`` |
---|
594 | This directory contains the implementation of RTEMS |
---|
595 | services which are required but beyond the realm |
---|
596 | of any standardization efforts. It includes |
---|
597 | initialization, shutdown, and IO services. |
---|
598 | |
---|
599 | ``${RTEMS_ROOT}/cpukit/score/`` |
---|
600 | This directory contains the "SuperCore" of RTEMS. |
---|
601 | All APIs are implemented in terms of SuperCore services. |
---|
602 | For example, Classic API tasks and POSIX threads |
---|
603 | are all implemented in terms of SuperCore threads. |
---|
604 | This provides a common infrastructure and a high degree |
---|
605 | of interoperability between the APIs. For example, |
---|
606 | services from all APIs may be used by any task/thread |
---|
607 | independent of the API used to create it. |
---|
608 | Within the ``score/`` directory the CPU dependent modules are found. |
---|
609 | The ``score/cpu/`` subdirectory contains a subdirectory for each |
---|
610 | target CPU supported by this release of the RTEMS |
---|
611 | executive. Each processor directory contains the CPU dependent |
---|
612 | code necessary to host RTEMS. The ``no_cpu`` directory provides a |
---|
613 | starting point for developing a new port to an unsupported |
---|
614 | processor. The files contained within the ``no_cpu`` directory |
---|
615 | may also be used as a reference for the other ports to specific |
---|
616 | processors. |
---|
617 | |
---|
618 | ``${RTEMS_ROOT}/cpukit/shttpd/`` |
---|
619 | This directory contains the port of the Simple HTTPD |
---|
620 | web server to RTEMS. |
---|
621 | |
---|
622 | ``${RTEMS_ROOT}/cpukit/telnetd/`` |
---|
623 | This directory contains the RTEMS telnetd server. |
---|
624 | |
---|
625 | ``${RTEMS_ROOT}/cpukit/wrapup/`` |
---|
626 | This directory is responsible for taking the individual |
---|
627 | libraries and objects built in each of the components |
---|
628 | in the RTEMS CPU Kit source tree and bundling them |
---|
629 | together to form the single RTEMS library ``librtemscpu.a``. This |
---|
630 | library contains all BSP and CPU model specific software. |
---|
631 | |
---|
632 | ``${RTEMS_ROOT}/cpukit/zlib/`` |
---|
633 | This directory contains a port of the GNU Zlib compression |
---|
634 | library to RTEMS. |
---|
635 | |
---|
636 | .. COMMENT: testsuites/ Test Suites |
---|
637 | |
---|
638 | testsuites/ Test Suites |
---|
639 | ======================= |
---|
640 | |
---|
641 | This directory provides all of the RTEMS Test Suite |
---|
642 | except those for the Classic API Ada95 binding |
---|
643 | This includes the single processor tests, multiprocessor tests, |
---|
644 | timing tests, library tests, and sample tests. Additionally, |
---|
645 | subdirectories for support functions and test related header |
---|
646 | files are provided. The following table lists the test suites |
---|
647 | currently included with the RTEMS and the directory in which |
---|
648 | they may be located: |
---|
649 | |
---|
650 | ``${RTEMS_ROOT}/testsuites/libtests/`` |
---|
651 | This directory contains the test suite for the |
---|
652 | various RTEMS support components. |
---|
653 | |
---|
654 | ``${RTEMS_ROOT}/testsuites/mptests/`` |
---|
655 | This directory contains the test suite for the |
---|
656 | multiprocessor support in the Classic API. |
---|
657 | The tests provided address two node configurations |
---|
658 | and provide coverage for the multiprocessor code found |
---|
659 | in RTEMS. |
---|
660 | |
---|
661 | ``${RTEMS_ROOT}/testsuites/psxtests/`` |
---|
662 | This directory contains the test suite for the |
---|
663 | RTEMS POSIX API. |
---|
664 | |
---|
665 | ``${RTEMS_ROOT}/testsuites/samples/`` |
---|
666 | This directory provides sample application tests |
---|
667 | which aid in the testing a newly built RTEMS environment, a new |
---|
668 | BSP, or as starting points for the development of an application |
---|
669 | using the RTEMS executive. They are discussed in `Sample Applications`_. |
---|
670 | |
---|
671 | ``${RTEMS_ROOT}/testsuites/sptests/`` |
---|
672 | This directory contains the test suite for the RTEMS |
---|
673 | Classic API when executing on a single processor. |
---|
674 | The tests were originally designed to provide |
---|
675 | near complete test coverage for the entire |
---|
676 | executive code. With the addition of multiple APIs, |
---|
677 | this is no longer the case as some SuperCore functionality |
---|
678 | is not available through the Classic API. Thus |
---|
679 | some functionality in the SuperCore is only covered |
---|
680 | by tests in the POSIX API Test Suites. |
---|
681 | |
---|
682 | ``${RTEMS_ROOT}/testsuites/support/`` |
---|
683 | This directory contains support software and header files |
---|
684 | for the various test suites. |
---|
685 | |
---|
686 | ``${RTEMS_ROOT}/testsuites/tmtests/`` |
---|
687 | This directory contains the timing test suite for |
---|
688 | the RTEMS Classic API. This include tests that |
---|
689 | benchmark each directive in the Classic API |
---|
690 | as well as a set of critical SuperCore functions. |
---|
691 | These tests are important for helping to verify |
---|
692 | that RTEMS performs as expected on your target hardware. |
---|
693 | It is not uncommon to discover mistakes in board |
---|
694 | initialization such as caching being disabled as |
---|
695 | a side-effect of analyzing the results of these tests. |
---|
696 | |
---|
697 | ``${RTEMS_ROOT}/testsuites/tools/`` |
---|
698 | This directory contains tools which execute on |
---|
699 | the development host and aid in executing and |
---|
700 | evaluating the results of the test suite. The |
---|
701 | tools ``difftest`` compares the output of one |
---|
702 | or more tests with the expected output. If you |
---|
703 | place the output of all the ``tmtests/`` in |
---|
704 | a single file, then the utility ``sorttimes`` |
---|
705 | will be able to produce a report organizing the |
---|
706 | execution times by manager. |
---|
707 | |
---|
708 | .. COMMENT: Documentation Directory |
---|
709 | |
---|
710 | Documentation Directory |
---|
711 | ======================= |
---|
712 | |
---|
713 | This directory contains the source code for all RTEMS documentation |
---|
714 | in ``TexInfo`` format as well as utilities used in the generation |
---|
715 | of the RTEMS documentation set. This source code is used to produce |
---|
716 | the RTEMS documentation in various formats including PDF, HTML, |
---|
717 | and PostScript. |
---|
718 | |
---|
719 | ``${RTEMS_ROOT}/doc/ada_user/`` |
---|
720 | This directory contains the source code for the *RTEMS |
---|
721 | Applications Ada Userâs Guide* which documents the Ada95 |
---|
722 | binding to the Classic API. This manual is produced from |
---|
723 | from the same source base as the *RTEMS Application |
---|
724 | C Userâs Guide*. |
---|
725 | |
---|
726 | ``${RTEMS_ROOT}/doc/bsp_howto/`` |
---|
727 | This directory contains the source code for the*RTEMS BSP and Device Driver Development Guide*. |
---|
728 | |
---|
729 | ``${RTEMS_ROOT}/doc/common/`` |
---|
730 | This directory contains the source code for the files which |
---|
731 | are shared across multiple manuals in the RTEMS Documentation Set. |
---|
732 | This includes the copyright page as well as the timing |
---|
733 | tables which can be filled in on a per BSP basis in the |
---|
734 | CPU supplements. |
---|
735 | |
---|
736 | ``${RTEMS_ROOT}/doc/cpu_supplement/`` |
---|
737 | This directory contains the source code for the |
---|
738 | RTEMS CPU Supplement. |
---|
739 | |
---|
740 | ``${RTEMS_ROOT}/doc/develenv/`` |
---|
741 | This directory contains the source code for the*RTEMS Development Environment Guide*. This is |
---|
742 | the document you are currently reading. |
---|
743 | |
---|
744 | ``${RTEMS_ROOT}/doc/filesystem/`` |
---|
745 | This directory contains the source code for the*RTEMS Filesystem Design Guide*. This manual |
---|
746 | is a continuous work in process as it attempts to |
---|
747 | capture the design of the interface between system |
---|
748 | calls and filesystem implementations as well as the |
---|
749 | information required by those implementing filesystems. |
---|
750 | |
---|
751 | ``${RTEMS_ROOT}/doc/images/`` |
---|
752 | This directory contains the source code for the graphics |
---|
753 | used in the HTML version of the RTEMS Documentation. |
---|
754 | |
---|
755 | ``${RTEMS_ROOT}/doc/networking/`` |
---|
756 | This directory contains the source code for the*RTEMS Network Supplement*. |
---|
757 | |
---|
758 | ``${RTEMS_ROOT}/doc/new_chapters/`` |
---|
759 | This directory contains the source code for the new documentation |
---|
760 | components which have not yet been collected into a new manual or |
---|
761 | merged into an existing document. Currently, this primarily |
---|
762 | contains draft documentation for some portions of |
---|
763 | the facilities implemented in ``${RTEMS_ROOT}/c/src/libmisc/``. |
---|
764 | |
---|
765 | ``${RTEMS_ROOT}/doc/porting/`` |
---|
766 | This directory contains the source code for the*RTEMS Porting Guide*. |
---|
767 | |
---|
768 | ``${RTEMS_ROOT}/doc/posix1003.1/`` |
---|
769 | This directory contains the source code for the*RTEMS POSIX 1003.1 Compliance Guide*. |
---|
770 | |
---|
771 | ``${RTEMS_ROOT}/doc/posix_users/`` |
---|
772 | This directory contains the source code for the*RTEMS POSIX API Userâs Guide*. It is important to |
---|
773 | note that RTEMSâ support for POSIX is a combination of |
---|
774 | functionality provided by RTEMS and the Newlib C Library |
---|
775 | so some functionality is documented by Newlib. |
---|
776 | |
---|
777 | ``${RTEMS_ROOT}/doc/relnotes/`` |
---|
778 | This directory contains the source code for a formally |
---|
779 | release notes document. This has not been used for |
---|
780 | recent RTEMS releases. |
---|
781 | |
---|
782 | ``${RTEMS_ROOT}/doc/started/`` |
---|
783 | This directory contains the source code for the*Getting Started with RTEMS for C/C++ Users* manual. |
---|
784 | |
---|
785 | ``${RTEMS_ROOT}/doc/tools/`` |
---|
786 | This directory contains the source code for the tools |
---|
787 | used on the development host to assist in producing the |
---|
788 | RTEMS Documentation. The most important of these tools |
---|
789 | is ``bmenu`` which generates the hierarchical node |
---|
790 | linking commands based upon chapter, section, and |
---|
791 | subsection organization. |
---|
792 | |
---|
793 | ``${RTEMS_ROOT}/doc/user/`` |
---|
794 | This directory contains the source code for the *RTEMS |
---|
795 | Applications C Userâs Guide* which documents the Classic API. |
---|
796 | |
---|
797 | .. COMMENT: COPYRIGHT (c) 1989-2007. |
---|
798 | |
---|
799 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
800 | |
---|
801 | .. COMMENT: All rights reserved. |
---|
802 | |
---|
803 | |
---|
804 | Sample Applications |
---|
805 | ################### |
---|
806 | |
---|
807 | Introduction |
---|
808 | ============ |
---|
809 | |
---|
810 | The RTEMS source distribution includes a set of sample applications |
---|
811 | that are located in the ``${RTEMS_ROOT}/testsuites/samples/`` |
---|
812 | directory. These applications are intended to illustrate the |
---|
813 | basic format of RTEMS single and multiple processor |
---|
814 | applications and the use of some features. In addition, these |
---|
815 | relatively simple applications can be used to test locally |
---|
816 | developed board support packages and device drivers as they |
---|
817 | exercise a critical subset of RTEMS functionality that is often |
---|
818 | broken in new BSPs. |
---|
819 | |
---|
820 | Some of the following sample applications will be covered in |
---|
821 | more detail in subsequent sections: |
---|
822 | |
---|
823 | *Hello World* |
---|
824 | The RTEMS Hello World test is provided in |
---|
825 | the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``. |
---|
826 | This test is helpful when testing new RTEMS development environment. |
---|
827 | |
---|
828 | *Clock Tick* |
---|
829 | The ``${RTEMS_ROOT}/testsuites/samples/ticker/`` |
---|
830 | subdirectory provides a test for verification of clock chip |
---|
831 | device drivers of BSPs. |
---|
832 | |
---|
833 | *Base Single Processor* |
---|
834 | A simple single processor test similar to those in the |
---|
835 | single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``. |
---|
836 | |
---|
837 | *Base Multiple Processor* |
---|
838 | A simple two node multiprocessor test capable of testing an newly |
---|
839 | developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``. |
---|
840 | |
---|
841 | *Capture* |
---|
842 | The RTEMS Capture test is provided in |
---|
843 | the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``. |
---|
844 | This is an interactive test which demonstrates the capabilities |
---|
845 | of the RTEMS Capture Engine. It includes a few test threads |
---|
846 | which generate interesting execution patterns. Look at the |
---|
847 | file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn`` |
---|
848 | for a sample session. |
---|
849 | |
---|
850 | *Constructor/Destructor C++ Test* |
---|
851 | The ``${RTEMS_ROOT}/testsuites/samples/cdtest/`` |
---|
852 | subdirectory provides a simple C++ application using |
---|
853 | constructors and destructors. It is only built when |
---|
854 | C++ is enabled and its primary purpose is to demonstrate |
---|
855 | that global constructors and destructors work. Since this |
---|
856 | requires that the linker script for your BSP be correct, this is |
---|
857 | an important test. |
---|
858 | |
---|
859 | *File IO* |
---|
860 | The RTEMS File IO test is provided in |
---|
861 | the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``. |
---|
862 | This is an interactive test which allows the user to interact with |
---|
863 | an ATA/IDE device. It will read the partition table and allow the |
---|
864 | user to dynamically mount one of the FAT32 partitions it finds. |
---|
865 | Commands are also provided to write and read files on the disk. |
---|
866 | |
---|
867 | *IO Stream* |
---|
868 | The RTEMS IO Stream test is provided in |
---|
869 | the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``. |
---|
870 | This test is a simple C++ application which demonstrates that |
---|
871 | C++ iostreams are functional. This requires that the RTEMS C++ |
---|
872 | run-time support is functioning properly. This test is only |
---|
873 | build when C++ is enabled. |
---|
874 | |
---|
875 | *Network Loopback Test* |
---|
876 | The ``${RTEMS_ROOT}/testsuites/samples/loopback/`` |
---|
877 | directory contains a sample test that demonstrates the use of |
---|
878 | sockets and the loopback network device. It does not require |
---|
879 | the presence of network hardware in order to run. |
---|
880 | It is only built if RTEMS was configured with networking enabled. |
---|
881 | |
---|
882 | *Minimum Size Test* |
---|
883 | The directory``${RTEMS_ROOT}/testsuites/samples/minimum/`` |
---|
884 | contains a simple RTEMS program that results in a non-functional |
---|
885 | executable. It is intended to show the size of a minimum footprint |
---|
886 | application based upon the current RTEMS configuration. |
---|
887 | |
---|
888 | *Nanoseconds* |
---|
889 | The RTEMS Nanoseconds test is provided in |
---|
890 | the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``. |
---|
891 | This test demonstrates that the BSP has support for nanosecond |
---|
892 | timestamp granularity. It prints the time of day and uptime multiple |
---|
893 | times as quickly as possible. It should be possible from the output |
---|
894 | to determine if your BSP has nanosecond accurate clock support |
---|
895 | and it is functional. |
---|
896 | |
---|
897 | *Paranoia Floating Point Test* |
---|
898 | The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/`` |
---|
899 | contains the public domain floating point and math library test. |
---|
900 | |
---|
901 | *Point-to-Point Protocol Daemon* |
---|
902 | The RTEMS Point-to-Point Protocol Daemon test is provided in |
---|
903 | the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``. |
---|
904 | This test primarily serves as the baseline for a user application |
---|
905 | using the PPP protocol. |
---|
906 | |
---|
907 | *Unlimited Object Allocation* |
---|
908 | The ``${RTEMS_ROOT}/testsuites/samples/unlimited/`` |
---|
909 | directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS. |
---|
910 | |
---|
911 | The sample tests are written using the Classic API so the reader |
---|
912 | should be familiar with the terms used and |
---|
913 | material presented in the *RTEMS Applications Users Guide*. |
---|
914 | |
---|
915 | Hello World |
---|
916 | =========== |
---|
917 | |
---|
918 | This sample application is in the following directory: |
---|
919 | .. code:: c |
---|
920 | |
---|
921 | ${RTEMS_ROOT}/testsuites/samples/hello/ |
---|
922 | |
---|
923 | It provides a rudimentary test of the BSP start up |
---|
924 | code and the console output routine. The C version of this |
---|
925 | sample application uses the printf function from the RTEMS |
---|
926 | Standard C Library to output messages. The Ada version of this |
---|
927 | sample uses the TEXT_IO package to output the hello messages. |
---|
928 | The following messages are printed: |
---|
929 | .. code:: c |
---|
930 | |
---|
931 | *** HELLO WORLD TEST \*** |
---|
932 | Hello World |
---|
933 | \*** END OF HELLO WORLD TEST \*** |
---|
934 | |
---|
935 | These messages are printed from the applicationâs |
---|
936 | single initialization task. If the above messages are not |
---|
937 | printed correctly, then either the BSP start up code or the |
---|
938 | console output routine is not operating properly. |
---|
939 | |
---|
940 | Clock Tick |
---|
941 | ========== |
---|
942 | |
---|
943 | This sample application is in the following directory: |
---|
944 | .. code:: c |
---|
945 | |
---|
946 | ${RTEMS_ROOT}/testsuites/samples/ticker/ |
---|
947 | |
---|
948 | This application is designed as a simple test of the |
---|
949 | clock tick device driver. In addition, this application also |
---|
950 | tests the printf function from the RTEMS Standard C Library by |
---|
951 | using it to output the following messages: |
---|
952 | .. code:: c |
---|
953 | |
---|
954 | *** CLOCK TICK TEST \*** |
---|
955 | TA1 - tm_get - 09:00:00 12/31/1988 |
---|
956 | TA2 - tm_get - 09:00:00 12/31/1988 |
---|
957 | TA3 - tm_get - 09:00:00 12/31/1988 |
---|
958 | TA1 - tm_get - 09:00:05 12/31/1988 |
---|
959 | TA1 - tm_get - 09:00:10 12/31/1988 |
---|
960 | TA2 - tm_get - 09:00:10 12/31/1988 |
---|
961 | TA1 - tm_get - 09:00:15 12/31/1988 |
---|
962 | TA3 - tm_get - 09:00:15 12/31/1988 |
---|
963 | TA1 - tm_get - 09:00:20 12/31/1988 |
---|
964 | TA2 - tm_get - 09:00:20 12/31/1988 |
---|
965 | TA1 - tm_get - 09:00:25 12/31/1988 |
---|
966 | TA1 - tm_get - 09:00:30 12/31/1988 |
---|
967 | TA2 - tm_get - 09:00:30 12/31/1988 |
---|
968 | TA3 - tm_get - 09:00:30 12/31/1988 |
---|
969 | \*** END OF CLOCK TICK TEST \*** |
---|
970 | |
---|
971 | The clock tick sample application utilizes a single |
---|
972 | initialization task and three copies of the single application |
---|
973 | task. The initialization task prints the test herald, sets the |
---|
974 | time and date, and creates and starts the three application |
---|
975 | tasks before deleting itself. The three application tasks |
---|
976 | generate the rest of the output. Every five seconds, one or |
---|
977 | more of the tasks will print the current time obtained via the |
---|
978 | tm_get directive. The first task, TA1, executes every five |
---|
979 | seconds, the second task, TA2, every ten seconds, and the third |
---|
980 | task, TA3, every fifteen seconds. If the time printed does not |
---|
981 | match the above output, then the clock device driver is not |
---|
982 | operating properly. |
---|
983 | |
---|
984 | Base Single Processor Application |
---|
985 | ================================= |
---|
986 | |
---|
987 | This sample application is in the following directory: |
---|
988 | .. code:: c |
---|
989 | |
---|
990 | ${RTEMS_ROOT}/testsuites/samples/base_sp/ |
---|
991 | |
---|
992 | It provides a framework from which a single processor |
---|
993 | RTEMS application can be developed. The use of the task argument |
---|
994 | is illustrated. This sample application uses the printf |
---|
995 | function from the RTEMS Standard C Library or TEXT_IO functions |
---|
996 | when using the Ada version to output the following messages: |
---|
997 | .. code:: c |
---|
998 | |
---|
999 | *** SAMPLE SINGLE PROCESSOR APPLICATION \*** |
---|
1000 | Creating and starting an application task |
---|
1001 | Application task was invoked with argument (0) and has id of 0x10002 |
---|
1002 | \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \*** |
---|
1003 | |
---|
1004 | The first two messages are printed from the |
---|
1005 | applicationâs single initialization task. The final messages |
---|
1006 | are printed from the single application task. |
---|
1007 | |
---|
1008 | Base Multiple Processor Application |
---|
1009 | =================================== |
---|
1010 | |
---|
1011 | This sample application is in the following directory: |
---|
1012 | .. code:: c |
---|
1013 | |
---|
1014 | ${RTEMS_ROOT}/testsuites/samples/base_mp/ |
---|
1015 | |
---|
1016 | It provides a framework from which a multiprocessor |
---|
1017 | RTEMS application can be developed. This directory has a |
---|
1018 | subdirectory for each node in the multiprocessor system. The |
---|
1019 | task argument is used to distinguish the node on which the |
---|
1020 | application task is executed. The first node will print the |
---|
1021 | following messages: |
---|
1022 | .. code:: c |
---|
1023 | |
---|
1024 | *** SAMPLE MULTIPROCESSOR APPLICATION \*** |
---|
1025 | Creating and starting an application task |
---|
1026 | This task was invoked with the node argument (1) |
---|
1027 | This task has the id of 0x10002 |
---|
1028 | \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \*** |
---|
1029 | |
---|
1030 | The second node will print the following messages: |
---|
1031 | .. code:: c |
---|
1032 | |
---|
1033 | *** SAMPLE MULTIPROCESSOR APPLICATION \*** |
---|
1034 | Creating and starting an application task |
---|
1035 | This task was invoked with the node argument (2) |
---|
1036 | This task has the id of 0x20002 |
---|
1037 | \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \*** |
---|
1038 | |
---|
1039 | The herald is printed from the applicationâs single |
---|
1040 | initialization task on each node. The final messages are |
---|
1041 | printed from the single application task on each node. |
---|
1042 | |
---|
1043 | In this sample application, all source code is shared |
---|
1044 | between the nodes except for the node dependent configuration |
---|
1045 | files. These files contains the definition of the node number |
---|
1046 | used in the initialization of the RTEMS Multiprocessor |
---|
1047 | Configuration Table. This file is not shared because the node |
---|
1048 | number field in the RTEMS Multiprocessor Configuration Table |
---|
1049 | must be unique on each node. |
---|
1050 | |
---|
1051 | Constructor/Destructor C++ Application |
---|
1052 | ====================================== |
---|
1053 | |
---|
1054 | This sample application is in the following directory: |
---|
1055 | .. code:: c |
---|
1056 | |
---|
1057 | ${RTEMS_ROOT}/testsuites/samples/cdtest/ |
---|
1058 | |
---|
1059 | This sample application demonstrates that RTEMS is |
---|
1060 | compatible with C++ applications. It uses constructors, |
---|
1061 | destructor, and I/O stream output in testing these various |
---|
1062 | capabilities. The board support package responsible for this |
---|
1063 | application must support a C++ environment. |
---|
1064 | |
---|
1065 | This sample application uses the printf function from |
---|
1066 | the RTEMS Standard C Library to output the following messages: |
---|
1067 | .. code:: c |
---|
1068 | |
---|
1069 | Hey I'M in base class constructor number 1 for 0x400010cc. |
---|
1070 | Hey I'M in base class constructor number 2 for 0x400010d4. |
---|
1071 | Hey I'M in derived class constructor number 3 for 0x400010d4. |
---|
1072 | \*** CONSTRUCTOR/DESTRUCTOR TEST \*** |
---|
1073 | Hey I'M in base class constructor number 4 for 0x4009ee08. |
---|
1074 | Hey I'M in base class constructor number 5 for 0x4009ee10. |
---|
1075 | Hey I'M in base class constructor number 6 for 0x4009ee18. |
---|
1076 | Hey I'M in base class constructor number 7 for 0x4009ee20. |
---|
1077 | Hey I'M in derived class constructor number 8 for 0x4009ee20. |
---|
1078 | Testing a C++ I/O stream |
---|
1079 | Hey I'M in derived class constructor number 8 for 0x4009ee20. |
---|
1080 | Derived class - Instantiation order 8 |
---|
1081 | Hey I'M in base class constructor number 7 for 0x4009ee20. |
---|
1082 | Instantiation order 8 |
---|
1083 | Hey I'M in base class constructor number 6 for 0x4009ee18. |
---|
1084 | Instantiation order 6 |
---|
1085 | Hey I'M in base class constructor number 5 for 0x4009ee10. |
---|
1086 | Instantiation order 5 |
---|
1087 | Hey I'M in base class constructor number 4 for 0x4009ee08. |
---|
1088 | Instantiation order 5 |
---|
1089 | \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \*** |
---|
1090 | Hey I'M in base class constructor number 3 for 0x400010d4. |
---|
1091 | Hey I'M in base class constructor number 2 for 0x400010d4. |
---|
1092 | Hey I'M in base class constructor number 1 for 0x400010cc. |
---|
1093 | |
---|
1094 | Minimum Size Test |
---|
1095 | ================= |
---|
1096 | |
---|
1097 | This sample application is in the following directory: |
---|
1098 | .. code:: c |
---|
1099 | |
---|
1100 | ${RTEMS_ROOT}/testsuites/samples/minimum/ |
---|
1101 | |
---|
1102 | This sample application is designed to produce the |
---|
1103 | minimum code space required for any RTEMS application |
---|
1104 | based upon the current RTEMS configuration and |
---|
1105 | BSP. In many situations, the bulk of this executable |
---|
1106 | consists of hardware and RTEMS initialization, basic |
---|
1107 | infrastructure such as malloc(), and RTEMS and |
---|
1108 | hardware shutdown support. |
---|
1109 | |
---|
1110 | Nanosecond Granularity Application |
---|
1111 | ================================== |
---|
1112 | |
---|
1113 | This sample application is in the following directory: |
---|
1114 | .. code:: c |
---|
1115 | |
---|
1116 | ${RTEMS_ROOT}/testsuites/samples/nsecs/ |
---|
1117 | |
---|
1118 | This sample application exercises the Clock Driver |
---|
1119 | for this BSP and demonstrates its ability to generate |
---|
1120 | accurate timestamps. This application does this by |
---|
1121 | exercising the time subsystem in three ways: |
---|
1122 | |
---|
1123 | - Obtain Time of Day Twice Back to Back |
---|
1124 | |
---|
1125 | - Obtain System Up Time Twice Back to Back |
---|
1126 | |
---|
1127 | - Use System Up Time to Measure Loops |
---|
1128 | |
---|
1129 | The following is an example of what the output of this |
---|
1130 | test may appear like: |
---|
1131 | .. code:: c |
---|
1132 | |
---|
1133 | *** NANOSECOND CLOCK TEST \*** |
---|
1134 | 10 iterations of getting TOD |
---|
1135 | Start: Sat Mar 24 11:15:00 2007:540000 |
---|
1136 | Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000 |
---|
1137 | Start: Sat Mar 24 11:15:00 2007:3974000 |
---|
1138 | Stop : Sat Mar 24 11:15:00 2007:3983000 --> 0:9000 |
---|
1139 | Start: Sat Mar 24 11:15:00 2007:7510000 |
---|
1140 | Stop : Sat Mar 24 11:15:00 2007:7519000 --> 0:9000 |
---|
1141 | Start: Sat Mar 24 11:15:00 2007:11054000 |
---|
1142 | Stop : Sat Mar 24 11:15:00 2007:11063000 --> 0:9000 |
---|
1143 | Start: Sat Mar 24 11:15:00 2007:14638000 |
---|
1144 | Stop : Sat Mar 24 11:15:00 2007:14647000 --> 0:9000 |
---|
1145 | Start: Sat Mar 24 11:15:00 2007:18301000 |
---|
1146 | Stop : Sat Mar 24 11:15:00 2007:18310000 --> 0:9000 |
---|
1147 | Start: Sat Mar 24 11:15:00 2007:21901000 |
---|
1148 | Stop : Sat Mar 24 11:15:00 2007:21910000 --> 0:9000 |
---|
1149 | Start: Sat Mar 24 11:15:00 2007:25526000 |
---|
1150 | Stop : Sat Mar 24 11:15:00 2007:25535000 --> 0:9000 |
---|
1151 | Start: Sat Mar 24 11:15:00 2007:29196000 |
---|
1152 | Stop : Sat Mar 24 11:15:00 2007:29206000 --> 0:10000 |
---|
1153 | Start: Sat Mar 24 11:15:00 2007:32826000 |
---|
1154 | Stop : Sat Mar 24 11:15:00 2007:32835000 --> 0:9000 |
---|
1155 | 10 iterations of getting Uptime |
---|
1156 | 0:38977000 0:38986000 --> 0:9000 |
---|
1157 | 0:40324000 0:40332000 --> 0:8000 |
---|
1158 | 0:41636000 0:41645000 --> 0:9000 |
---|
1159 | 0:42949000 0:42958000 --> 0:9000 |
---|
1160 | 0:44295000 0:44304000 --> 0:9000 |
---|
1161 | 0:45608000 0:45617000 --> 0:9000 |
---|
1162 | 0:46921000 0:46930000 --> 0:9000 |
---|
1163 | 0:48282000 0:48291000 --> 0:9000 |
---|
1164 | 0:49595000 0:49603000 --> 0:8000 |
---|
1165 | 0:50908000 0:50917000 --> 0:9000 |
---|
1166 | 10 iterations of getting Uptime with different loop values |
---|
1167 | loop of 10000 0:119488000 0:119704000 --> 0:216000 |
---|
1168 | loop of 20000 0:124028000 0:124463000 --> 0:435000 |
---|
1169 | loop of 30000 0:128567000 0:129220000 --> 0:653000 |
---|
1170 | loop of 40000 0:133097000 0:133964000 --> 0:867000 |
---|
1171 | loop of 50000 0:137643000 0:138728000 --> 0:1085000 |
---|
1172 | loop of 60000 0:142265000 0:143572000 --> 0:1307000 |
---|
1173 | loop of 70000 0:146894000 0:148416000 --> 0:1522000 |
---|
1174 | loop of 80000 0:151519000 0:153260000 --> 0:1741000 |
---|
1175 | loop of 90000 0:156145000 0:158099000 --> 0:1954000 |
---|
1176 | loop of 100000 0:160770000 0:162942000 --> 0:2172000 |
---|
1177 | \*** END OF NANOSECOND CLOCK TEST \*** |
---|
1178 | |
---|
1179 | Paranoia Floating Point Application |
---|
1180 | =================================== |
---|
1181 | |
---|
1182 | This sample application is in the following directory: |
---|
1183 | .. code:: c |
---|
1184 | |
---|
1185 | ${RTEMS_ROOT}/testsuites/samples/paranoia/ |
---|
1186 | |
---|
1187 | This sample application uses a public domain floating |
---|
1188 | point and math library test to verify these capabilities of the |
---|
1189 | RTEMS executive. Deviations between actual and expected results |
---|
1190 | are reported to the screen. This is a very extensive test which |
---|
1191 | tests all mathematical and number conversion functions. |
---|
1192 | Paranoia is also very large and requires a long period of time |
---|
1193 | to run. Problems which commonly prevent this test from |
---|
1194 | executing to completion include stack overflow and FPU exception |
---|
1195 | handlers not installed. |
---|
1196 | |
---|
1197 | Network Loopback Test |
---|
1198 | ===================== |
---|
1199 | |
---|
1200 | This sample application is in the following directory: |
---|
1201 | .. code:: c |
---|
1202 | |
---|
1203 | ${RTEMS_ROOT}/testsuites/samples/loopback/ |
---|
1204 | |
---|
1205 | This sample application uses the network loopback device to |
---|
1206 | demonstrate the use of the RTEMS TCP/IP stack. This sample |
---|
1207 | test illustrates the basic configuration and initialization |
---|
1208 | of the TCP/IP stack as well as simple socket usage. |
---|
1209 | |
---|
1210 | .. COMMENT: COPYRIGHT (c) 1989-2007. |
---|
1211 | |
---|
1212 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
1213 | |
---|
1214 | .. COMMENT: All rights reserved. |
---|
1215 | |
---|
1216 | RTEMS Specific Utilities |
---|
1217 | ######################## |
---|
1218 | |
---|
1219 | This section describes the additional commands |
---|
1220 | available within the *RTEMS Development Environment*. Although |
---|
1221 | some of these commands are of general use, most are included to |
---|
1222 | provide some capability necessary to perform a required function |
---|
1223 | in the development of the RTEMS executive, one of its support |
---|
1224 | components, or an RTEMS based application. |
---|
1225 | |
---|
1226 | Some of the commands are implemented as C programs. |
---|
1227 | However, most commands are implemented as Bourne shell scripts. |
---|
1228 | Even if the current user has selected a different shell, the |
---|
1229 | scripts will automatically invoke the Bourne shell during their |
---|
1230 | execution lifetime. |
---|
1231 | |
---|
1232 | The commands are presented in UNIX manual page style |
---|
1233 | for compatibility and convenience. A standard set of paragraph |
---|
1234 | headers were used for all of the command descriptions. If a |
---|
1235 | section contained no data, the paragraph header was omitted to |
---|
1236 | conserve space. Each of the permissible paragraph headers and |
---|
1237 | their contents are described below: |
---|
1238 | |
---|
1239 | ``SYNOPSIS`` |
---|
1240 | describes the command syntax |
---|
1241 | |
---|
1242 | ``DESCRIPTION`` |
---|
1243 | a full description of the command |
---|
1244 | |
---|
1245 | ``OPTIONS`` |
---|
1246 | describes each of the permissible options for the command |
---|
1247 | |
---|
1248 | ``NOTES`` |
---|
1249 | lists any special noteworthy comments about the command |
---|
1250 | |
---|
1251 | ``ENVIRONMENT`` |
---|
1252 | describes all environment variables utilized by the command |
---|
1253 | |
---|
1254 | ``EXAMPLES`` |
---|
1255 | illustrates the use of the command with specific examples |
---|
1256 | |
---|
1257 | ``FILES`` |
---|
1258 | provides a list of major files that the command references |
---|
1259 | |
---|
1260 | ``SEE ALSO`` |
---|
1261 | lists any relevant commands which can be consulted |
---|
1262 | |
---|
1263 | Most environment variables referenced by the commands |
---|
1264 | are defined for the RTEMS Development Environment during the |
---|
1265 | login procedure. During login, the user selects a default RTEMS |
---|
1266 | environment through the use of the Modules package. This tool |
---|
1267 | effectively sets the environment variables to provide a |
---|
1268 | consistent development environment for a specific user. |
---|
1269 | Additional environment variables within the RTEMS environment |
---|
1270 | were set by the system administrator during installation. When |
---|
1271 | specifying paths, a command description makes use of these |
---|
1272 | environment variables. |
---|
1273 | |
---|
1274 | When referencing other commands in the SEE ALSO |
---|
1275 | paragraph, the following notation is used: command(code). |
---|
1276 | Where command is the name of a related command, and code is a |
---|
1277 | section number. Valid section numbers are as follows: |
---|
1278 | |
---|
1279 | ``1`` |
---|
1280 | Section 1 of the standard UNIX documentation |
---|
1281 | |
---|
1282 | ``1G`` |
---|
1283 | Section 1 of the GNU documentation |
---|
1284 | |
---|
1285 | ``1R`` |
---|
1286 | a manual page from this document, the RTEMS Development Environment Guide |
---|
1287 | |
---|
1288 | For example, ls(1) means see the standard ls command |
---|
1289 | in section 1 of the UNIX documentation. gcc020(1G) means see |
---|
1290 | the description of gcc020 in section 1 of the GNU documentation. |
---|
1291 | |
---|
1292 | .. COMMENT: packhex |
---|
1293 | |
---|
1294 | packhex - Compress Hexadecimal File |
---|
1295 | =================================== |
---|
1296 | |
---|
1297 | **SYNOPSIS** |
---|
1298 | |
---|
1299 | .. code:: c |
---|
1300 | |
---|
1301 | packhex <source >destination |
---|
1302 | |
---|
1303 | **DESCRIPTION** |
---|
1304 | |
---|
1305 | packhex accepts Intel Hexadecimal or Motorola Srecord |
---|
1306 | on its standard input and attempts to pack as many contiguous |
---|
1307 | bytes as possible into a single hexadecimal record. Many |
---|
1308 | programs output hexadecimal records which are less than 80 bytes |
---|
1309 | long (for human viewing). The overhead required by each |
---|
1310 | unnecessary record is significant and packhex can often reduce |
---|
1311 | the size of the download image by 20%. packhex attempts to |
---|
1312 | output records which are as long as the hexadecimal format |
---|
1313 | allows. |
---|
1314 | |
---|
1315 | **OPTIONS** |
---|
1316 | |
---|
1317 | This command has no options. |
---|
1318 | |
---|
1319 | **EXAMPLES** |
---|
1320 | |
---|
1321 | Assume the current directory contains the Motorola |
---|
1322 | Srecord file download.sr. Then executing the command: |
---|
1323 | .. code:: c |
---|
1324 | |
---|
1325 | packhex <download.sr >packed.sr |
---|
1326 | |
---|
1327 | will generate the file packed.sr which is usually |
---|
1328 | smaller than download.sr. |
---|
1329 | |
---|
1330 | **CREDITS** |
---|
1331 | |
---|
1332 | The source for packhex first appeared in the May 1993 |
---|
1333 | issue of Embedded Systems magazine. The code was downloaded |
---|
1334 | from their BBS. Unfortunately, the authorâs name was not |
---|
1335 | provided in the listing. |
---|
1336 | |
---|
1337 | .. COMMENT: unhex |
---|
1338 | |
---|
1339 | unhex - Convert Hexadecimal File into Binary Equivalent |
---|
1340 | ======================================================= |
---|
1341 | |
---|
1342 | **SYNOPSIS** |
---|
1343 | |
---|
1344 | .. code:: c |
---|
1345 | |
---|
1346 | unhex \[-valF] \[-o file] \[file \[file ...] ] |
---|
1347 | |
---|
1348 | **DESCRIPTION** |
---|
1349 | |
---|
1350 | unhex accepts Intel Hexadecimal, Motorola Srecord, or |
---|
1351 | TI âBâ records and converts them to their binary equivalent. |
---|
1352 | The output may sent to standout or may be placed in a specified |
---|
1353 | file with the -o option. The designated output file may not be |
---|
1354 | an input file. Multiple input files may be specified with their |
---|
1355 | outputs logically concatenated into the output file. |
---|
1356 | |
---|
1357 | **OPTIONS** |
---|
1358 | |
---|
1359 | This command has the following options: |
---|
1360 | |
---|
1361 | ``v`` |
---|
1362 | Verbose |
---|
1363 | |
---|
1364 | ``a base`` |
---|
1365 | First byte of output corresponds with base |
---|
1366 | address |
---|
1367 | |
---|
1368 | ``l`` |
---|
1369 | Linear Output |
---|
1370 | |
---|
1371 | ``o file`` |
---|
1372 | Output File |
---|
1373 | |
---|
1374 | ``F k_bits`` |
---|
1375 | Fill holes in input with 0xFFs up to k_bits * 1024 bits |
---|
1376 | |
---|
1377 | **EXAMPLES** |
---|
1378 | |
---|
1379 | The following command will create a binary equivalent |
---|
1380 | file for the two Motorola S record files in the specified output |
---|
1381 | file binary.bin: |
---|
1382 | .. code:: c |
---|
1383 | |
---|
1384 | unhex -o binary.bin downloadA.sr downloadB.sr |
---|
1385 | |
---|
1386 | Command and Variable Index |
---|
1387 | ########################## |
---|
1388 | |
---|
1389 | There are currently no Command and Variable Index entries. |
---|
1390 | |
---|
1391 | .. COMMENT: @printindex fn |
---|
1392 | |
---|
1393 | Concept Index |
---|
1394 | ############# |
---|
1395 | |
---|
1396 | There are currently no Concept Index entries. |
---|
1397 | |
---|
1398 | .. COMMENT: @printindex cp |
---|