source: rtems/doc/develenv/sample.t @ d9779bd

4.8
Last change on this file since d9779bd was d9779bd, checked in by Joel Sherrill <joel.sherrill@…>, on 11/27/07 at 19:30:59

2007-11-27 Joel Sherrill <joel.sherrill@…>

  • develenv/develenv.texi, develenv/direct.t, develenv/intro.texi, develenv/sample.t, develenv/utils.t: Update directory tree.
  • Property mode set to 100644
File size: 11.0 KB
Line 
1@c
2@c  COPYRIGHT (c) 1989-2007.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Sample Applications
10
11@section Introduction
12
13The RTEMS source distribution includes a set of sample applications
14that are located in the @code{$@{RTEMS_ROOT@}/testsuites/samples/}
15directory.  These applications are intended to illustrate the
16basic format of RTEMS single and multiple processor
17applications and the use of some features.  In addition, these
18relatively simple applications can be used to test locally
19developed board support packages and device drivers as they
20exercise a critical subset of RTEMS functionality that is often
21broken in new BSPs.
22
23Each of the following sample applications will be listed in
24more detail in the following sections:
25
26@table @b
27@item Hello World
28The RTEMS Hello World test is provided in
29the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/hello/}.
30This test is helpful when testing new
31versions of RTEMS, BSPs, or modifications to any portion of the
32RTEMS development environment. 
33
34@item Clock Tick
35The @code{$@{RTEMS_ROOT@}/testsuites/samples/ticker/}
36subdirectory provides a test for verification of clock chip
37device drivers of BSPs. 
38
39@item Base Single Processor
40A simple single processor test similar to those in the
41single processor test suite is provided in
42@code{$@{RTEMS_ROOT@}/testsuites/samples/base_sp/}.
43
44@item Base Multiple Processor
45A simple two node multiprocessor test capable of testing an newly
46developed MPCI layer is provided in
47@code{$@{RTEMS_ROOT@}/testsuites/samples/base_mp/}.
48
49@item Constructor/Destructor C++ Test
50The @code{$@{RTEMS_ROOT@}/testsuites/samples/cdtest/}
51subdirectory provides a simple C++ application using
52constructors and destructors.  It is only built when
53C++ is enabled. 
54
55
56@item Paranoia Floating Point Test
57The directory @code{$@{RTEMS_ROOT@}/testsuites/samples/paranoia/}
58contains the public domain floating point and math library test.
59
60@item Minimum Size Test
61The directory
62@code{$@{RTEMS_ROOT@}/testsuites/samples/minimum/}
63contains a simple RTEMS program that results in a non-functional
64executable.  It is intended to show the size of a minimum footprint
65application based upon the current RTEMS configuration. 
66
67@item Unlimited Object Allocation
68The @code{$@{RTEMS_ROOT@}/testsuites/samples/unlimited/}
69directory contains a sample test that demonstrates the use of the
70@i{unlimited} object allocation configuration option to RTEMS.
71
72@item Network Loopback Test
73The @code{$@{RTEMS_ROOT@}/testsuites/samples/loopback/}
74directory contains a sample test that demonstrates the use of
75sockets and the loopback network device.  It does not require
76the presence of network hardware in order to run.
77It is only built if RTEMS was configured with networking enabled.
78
79@end table
80
81The sample tests are written using the Classic API so the reader
82should be familiar with the terms used and
83material presented in the @b{RTEMS Applications Users Guide}.
84
85@section Hello World
86
87This sample application is in the following directory:
88
89@example
90$@{RTEMS_ROOT@}/testsuites/samples/hello/
91@end example
92
93It provides a rudimentary test of the BSP start up
94code and the console output routine.  The C version of this
95sample application uses the printf function from the RTEMS
96Standard C Library to output messages.   The Ada version of this
97sample use the TEXT_IO package to output the hello messages.
98The following messages are printed:
99
100@example
101@group
102*** HELLO WORLD TEST ***
103Hello World
104*** END OF HELLO WORLD TEST ***
105@end group
106@end example
107
108These messages are printed from the application's
109single initialization task.  If the above messages are not
110printed correctly, then either the BSP start up code or the
111console output routine is not operating properly.
112
113@section Clock Tick
114
115This sample application is in the following directory:
116
117@example
118$@{RTEMS_ROOT@}/testsuites/samples/ticker/
119@end example
120
121This application is designed as a simple test of the
122clock tick device driver.  In addition, this application also
123tests the printf function from the RTEMS Standard C Library by
124using it to output the following messages:
125
126@example
127@group
128*** CLOCK TICK TEST ***
129TA1 - tm_get - 09:00:00   12/31/1988
130TA2 - tm_get - 09:00:00   12/31/1988
131TA3 - tm_get - 09:00:00   12/31/1988
132TA1 - tm_get - 09:00:05   12/31/1988
133TA1 - tm_get - 09:00:10   12/31/1988
134TA2 - tm_get - 09:00:10   12/31/1988
135TA1 - tm_get - 09:00:15   12/31/1988
136TA3 - tm_get - 09:00:15   12/31/1988
137TA1 - tm_get - 09:00:20   12/31/1988
138TA2 - tm_get - 09:00:20   12/31/1988
139TA1 - tm_get - 09:00:25   12/31/1988
140TA1 - tm_get - 09:00:30   12/31/1988
141TA2 - tm_get - 09:00:30   12/31/1988
142TA3 - tm_get - 09:00:30   12/31/1988
143*** END OF CLOCK TICK TEST ***
144@end group
145@end example
146
147The clock tick sample application utilizes a single
148initialization task and three copies of the single application
149task.  The initialization task prints the test herald, sets the
150time and date, and creates and starts the three application
151tasks before deleting itself.  The three application tasks
152generate the rest of the output.  Every five seconds, one or
153more of the tasks will print the current time obtained via the
154tm_get directive.  The first task, TA1, executes every five
155seconds, the second task, TA2, every ten seconds, and the third
156task, TA3, every fifteen seconds. If the time printed does not
157match the above output, then the clock device driver is not
158operating properly.
159
160@section Base Single Processor Application
161
162This sample application is in the following directory:
163
164@example
165$@{RTEMS_ROOT@}/testsuites/samples/base_sp/
166@end example
167
168It provides a framework from which a single processor
169RTEMS application can be developed. The use of the task argument
170is illustrated.  This sample application uses the printf
171function from the RTEMS Standard C Library or TEXT_IO functions
172when using the Ada version to output the following messages:
173
174@example
175@group
176*** SAMPLE SINGLE PROCESSOR APPLICATION ***
177Creating and starting an application task
178Application task was invoked with argument (0) and has id of 0x10002
179*** END OF SAMPLE SINGLE PROCESSOR APPLICATION ***
180@end group
181@end example
182
183The first two messages are printed from the
184application's single initialization task.  The final messages
185are printed from the single application task.
186
187@section Base Multiple Processor Application
188
189This sample application is in the following directory:
190
191@example
192$@{RTEMS_ROOT@}/testsuites/samples/base_mp/
193@end example
194
195It provides a framework from which a multiprocessor
196RTEMS application can be developed. This directory has a
197subdirectory for each node in the multiprocessor system.  The
198task argument is used to distinguish the node on which the
199application task is executed.  The first node will print the
200following messages:
201
202@example
203@group
204*** SAMPLE MULTIPROCESSOR APPLICATION ***
205Creating and starting an application task
206This task was invoked with the node argument (1)
207This task has the id of 0x10002
208*** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
209@end group
210@end example
211
212The second node will print the following messages:
213
214@example
215@group
216*** SAMPLE MULTIPROCESSOR APPLICATION ***
217Creating and starting an application task
218This task was invoked with the node argument (2)
219This task has the id of 0x20002
220*** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
221@end group
222@end example
223
224The herald is printed from the application's single
225initialization task on each node.  The final messages are
226printed from the single application task on each node.
227
228In this sample application, all source code is shared
229between the nodes except for the node dependent configuration
230files.  These files contains the definition of the node number
231used in the initialization of the  RTEMS Multiprocessor
232Configuration Table. This file is not shared because the node
233number field in the RTEMS Multiprocessor Configuration Table
234must be unique on each node.
235
236@section Constructor/Destructor C++ Application
237
238This sample application is in the following directory:
239
240@example
241$@{RTEMS_ROOT@}/testsuites/samples/cdtest/
242@end example
243
244This sample application demonstrates that RTEMS is
245compatible with C++ applications.  It uses constructors,
246destructor, and I/O stream output in testing these various
247capabilities.  The board support package responsible for this
248application must support a C++ environment.
249
250This sample application uses the printf function from
251the RTEMS Standard C Library to output the following messages:
252
253@example
254@group
255Hey I'M in base class constructor number 1 for 0x400010cc.
256Hey I'M in base class constructor number 2 for 0x400010d4.
257Hey I'M in derived class constructor number 3 for 0x400010d4.
258*** CONSTRUCTOR/DESTRUCTOR TEST ***
259Hey I'M in base class constructor number 4 for 0x4009ee08.
260Hey I'M in base class constructor number 5 for 0x4009ee10.
261Hey I'M in base class constructor number 6 for 0x4009ee18.
262Hey I'M in base class constructor number 7 for 0x4009ee20.
263Hey I'M in derived class constructor number 8 for 0x4009ee20.
264Testing a C++ I/O stream
265Hey I'M in derived class constructor number 8 for 0x4009ee20.
266Derived class - Instantiation order 8
267Hey I'M in base class constructor number 7 for 0x4009ee20.
268Instantiation order 8
269Hey I'M in base class constructor number 6 for 0x4009ee18.
270Instantiation order 6
271Hey I'M in base class constructor number 5 for 0x4009ee10.
272Instantiation order 5
273Hey I'M in base class constructor number 4 for 0x4009ee08.
274Instantiation order 5
275*** END OF CONSTRUCTOR/DESTRUCTOR TEST ***
276Hey I'M in base class constructor number 3 for 0x400010d4.
277Hey I'M in base class constructor number 2 for 0x400010d4.
278Hey I'M in base class constructor number 1 for 0x400010cc.
279@end group
280@end example
281
282@section Minimum Size Test
283
284This sample application is in the following directory:
285
286@example
287$@{RTEMS_ROOT@}/testsuites/samples/minimum/
288@end example
289
290This sample application is designed to produce the
291minimum code space required for any RTEMS application
292based upon the current RTEMS configuration and
293BSP.  In many situations, the bulk of this executable
294consists of hardware and RTEMS initialization, basic
295infrastructure such as malloc(), and RTEMS and
296hardware shutdown support.
297
298@section Paranoia Floating Point Application
299
300This sample application is in the following directory:
301
302@example
303$@{RTEMS_ROOT@}/testsuites/samples/paranoia/
304@end example
305
306This sample application uses a public domain floating
307point and math library test to verify these capabilities of the
308RTEMS executive.  Deviations between actual and expected results
309are reported to the screen.  This is a very extensive test which
310tests all mathematical and number conversion functions.
311Paranoia is also very large and requires a long period of time
312to run.   Problems which commonly prevent this test from
313executing to completion include stack overflow and FPU exception
314handlers not installed.
315
316@section Network Loopback Test
317
318This sample application is in the following directory:
319
320@example
321$@{RTEMS_ROOT@}/testsuites/samples/loopback/
322@end example
323
324This sample application uses the network loopback device to
325demonstrate the use of the RTEMS TCP/IP stack.  This sample
326test illustrates the basic configuration and initialization
327of the TCP/IP stack as well as simple socket usage.
328
Note: See TracBrowser for help on using the repository browser.