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