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

4.104.114.95
Last change on this file since da8e974a was da8e974a, checked in by Glenn Humphrey <glenn.humphrey@…>, on 11/29/07 at 16:02:42

2007-11-29 Glenn Humphrey <glenn.humphrey@…>

  • develenv/direct.t, develenv/sample.t: Corrected various errors.
  • Property mode set to 100644
File size: 15.5 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
23Some of the following sample applications will be covered in
24more detail in subsequent 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 RTEMS development environment. 
31
32@item Clock Tick
33The @code{$@{RTEMS_ROOT@}/testsuites/samples/ticker/}
34subdirectory provides a test for verification of clock chip
35device drivers of BSPs. 
36
37@item Base Single Processor
38A simple single processor test similar to those in the
39single processor test suite is provided in
40@code{$@{RTEMS_ROOT@}/testsuites/samples/base_sp/}.
41
42@item Base Multiple Processor
43A simple two node multiprocessor test capable of testing an newly
44developed MPCI layer is provided in
45@code{$@{RTEMS_ROOT@}/testsuites/samples/base_mp/}.
46
47@item Capture
48The RTEMS Capture test is provided in
49the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/capture/}.
50This is an interactive test which demonstrates the capabilities
51of the RTEMS Capture Engine.  It includes a few test threads
52which generate interesting execution patterns.  Look at the
53file @code{$@{RTEMS_ROOT@}/testsuites/samples/capture/capture.scn}
54for a sample session.
55
56@item Constructor/Destructor C++ Test
57The @code{$@{RTEMS_ROOT@}/testsuites/samples/cdtest/}
58subdirectory provides a simple C++ application using
59constructors and destructors.  It is only built when
60C++ is enabled and its primary purpose is to demonstrate
61that global constructors and destructors work.  Since this
62requires that the linker script for your BSP be correct, this is
63an important test.
64
65@item File IO
66The RTEMS File IO test is provided in
67the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/fileio/}.
68This is an interactive test which allows the user to interact with
69an ATA/IDE device.  It will read the partition table and allow the
70user to dynamically mount one of the FAT32 partitions it finds.
71Commands are also provided to write and read files on the disk.
72
73@item IO Stream
74The RTEMS IO Stream test is provided in
75the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/iostream/}.
76This test is a simple C++ application which demonstrates that
77C++ iostreams are functional. This requires that the RTEMS C++
78run-time support is functioning properly.  This test is only
79build when C++ is enabled.
80
81@item Network Loopback Test
82The @code{$@{RTEMS_ROOT@}/testsuites/samples/loopback/}
83directory contains a sample test that demonstrates the use of
84sockets and the loopback network device.  It does not require
85the presence of network hardware in order to run.
86It is only built if RTEMS was configured with networking enabled.
87
88@item Minimum Size Test
89The directory
90@code{$@{RTEMS_ROOT@}/testsuites/samples/minimum/}
91contains a simple RTEMS program that results in a non-functional
92executable.  It is intended to show the size of a minimum footprint
93application based upon the current RTEMS configuration. 
94
95@item Nanoseconds
96The RTEMS Nanoseconds test is provided in
97the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/nsecs/}.
98This test demonstrates that the BSP has support for nanosecond
99timestamp granularity.  It prints the time of day and uptime multiple
100times as quickly as possible.  It should be possible from the output
101to determine if your BSP has nanosecond accurate clock support
102and it is functional.
103
104@item Paranoia Floating Point Test
105The directory @code{$@{RTEMS_ROOT@}/testsuites/samples/paranoia/}
106contains the public domain floating point and math library test.
107
108@item Point-to-Point Protocol Daemon
109The RTEMS Point-to-Point Protocol Daemon test is provided in
110the subdirectory @code{$@{RTEMS_ROOT@}/testsuites/samples/pppd/}.
111This test primarily serves as the baseline for a user application
112using the PPP protocol.
113
114@item Unlimited Object Allocation
115The @code{$@{RTEMS_ROOT@}/testsuites/samples/unlimited/}
116directory contains a sample test that demonstrates the use of the
117@i{unlimited} object allocation configuration option to RTEMS.
118
119@end table
120
121The sample tests are written using the Classic API so the reader
122should be familiar with the terms used and
123material presented in the @b{RTEMS Applications Users Guide}.
124
125@c
126@c
127@c
128@section Hello World
129
130This sample application is in the following directory:
131
132@example
133$@{RTEMS_ROOT@}/testsuites/samples/hello/
134@end example
135
136It provides a rudimentary test of the BSP start up
137code and the console output routine.  The C version of this
138sample application uses the printf function from the RTEMS
139Standard C Library to output messages.   The Ada version of this
140sample uses the TEXT_IO package to output the hello messages.
141The following messages are printed:
142
143@example
144@group
145*** HELLO WORLD TEST ***
146Hello World
147*** END OF HELLO WORLD TEST ***
148@end group
149@end example
150
151These messages are printed from the application's
152single initialization task.  If the above messages are not
153printed correctly, then either the BSP start up code or the
154console output routine is not operating properly.
155
156@c
157@c
158@c
159@section Clock Tick
160
161This sample application is in the following directory:
162
163@example
164$@{RTEMS_ROOT@}/testsuites/samples/ticker/
165@end example
166
167This application is designed as a simple test of the
168clock tick device driver.  In addition, this application also
169tests the printf function from the RTEMS Standard C Library by
170using it to output the following messages:
171
172@example
173@group
174*** CLOCK TICK TEST ***
175TA1 - tm_get - 09:00:00   12/31/1988
176TA2 - tm_get - 09:00:00   12/31/1988
177TA3 - tm_get - 09:00:00   12/31/1988
178TA1 - tm_get - 09:00:05   12/31/1988
179TA1 - tm_get - 09:00:10   12/31/1988
180TA2 - tm_get - 09:00:10   12/31/1988
181TA1 - tm_get - 09:00:15   12/31/1988
182TA3 - tm_get - 09:00:15   12/31/1988
183TA1 - tm_get - 09:00:20   12/31/1988
184TA2 - tm_get - 09:00:20   12/31/1988
185TA1 - tm_get - 09:00:25   12/31/1988
186TA1 - tm_get - 09:00:30   12/31/1988
187TA2 - tm_get - 09:00:30   12/31/1988
188TA3 - tm_get - 09:00:30   12/31/1988
189*** END OF CLOCK TICK TEST ***
190@end group
191@end example
192
193The clock tick sample application utilizes a single
194initialization task and three copies of the single application
195task.  The initialization task prints the test herald, sets the
196time and date, and creates and starts the three application
197tasks before deleting itself.  The three application tasks
198generate the rest of the output.  Every five seconds, one or
199more of the tasks will print the current time obtained via the
200tm_get directive.  The first task, TA1, executes every five
201seconds, the second task, TA2, every ten seconds, and the third
202task, TA3, every fifteen seconds. If the time printed does not
203match the above output, then the clock device driver is not
204operating properly.
205
206@c
207@c
208@c
209@section Base Single Processor Application
210
211This sample application is in the following directory:
212
213@example
214$@{RTEMS_ROOT@}/testsuites/samples/base_sp/
215@end example
216
217It provides a framework from which a single processor
218RTEMS application can be developed. The use of the task argument
219is illustrated.  This sample application uses the printf
220function from the RTEMS Standard C Library or TEXT_IO functions
221when using the Ada version to output the following messages:
222
223@example
224@group
225*** SAMPLE SINGLE PROCESSOR APPLICATION ***
226Creating and starting an application task
227Application task was invoked with argument (0) and has id of 0x10002
228*** END OF SAMPLE SINGLE PROCESSOR APPLICATION ***
229@end group
230@end example
231
232The first two messages are printed from the
233application's single initialization task.  The final messages
234are printed from the single application task.
235
236@c
237@c
238@c
239@section Base Multiple Processor Application
240
241This sample application is in the following directory:
242
243@example
244$@{RTEMS_ROOT@}/testsuites/samples/base_mp/
245@end example
246
247It provides a framework from which a multiprocessor
248RTEMS application can be developed. This directory has a
249subdirectory for each node in the multiprocessor system.  The
250task argument is used to distinguish the node on which the
251application task is executed.  The first node will print the
252following messages:
253
254@example
255@group
256*** SAMPLE MULTIPROCESSOR APPLICATION ***
257Creating and starting an application task
258This task was invoked with the node argument (1)
259This task has the id of 0x10002
260*** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
261@end group
262@end example
263
264The second node will print the following messages:
265
266@example
267@group
268*** SAMPLE MULTIPROCESSOR APPLICATION ***
269Creating and starting an application task
270This task was invoked with the node argument (2)
271This task has the id of 0x20002
272*** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
273@end group
274@end example
275
276The herald is printed from the application's single
277initialization task on each node.  The final messages are
278printed from the single application task on each node.
279
280In this sample application, all source code is shared
281between the nodes except for the node dependent configuration
282files.  These files contains the definition of the node number
283used in the initialization of the  RTEMS Multiprocessor
284Configuration Table. This file is not shared because the node
285number field in the RTEMS Multiprocessor Configuration Table
286must be unique on each node.
287
288@c
289@c
290@c
291@section Constructor/Destructor C++ Application
292
293This sample application is in the following directory:
294
295@example
296$@{RTEMS_ROOT@}/testsuites/samples/cdtest/
297@end example
298
299This sample application demonstrates that RTEMS is
300compatible with C++ applications.  It uses constructors,
301destructor, and I/O stream output in testing these various
302capabilities.  The board support package responsible for this
303application must support a C++ environment.
304
305This sample application uses the printf function from
306the RTEMS Standard C Library to output the following messages:
307
308@example
309@group
310Hey I'M in base class constructor number 1 for 0x400010cc.
311Hey I'M in base class constructor number 2 for 0x400010d4.
312Hey I'M in derived class constructor number 3 for 0x400010d4.
313*** CONSTRUCTOR/DESTRUCTOR TEST ***
314Hey I'M in base class constructor number 4 for 0x4009ee08.
315Hey I'M in base class constructor number 5 for 0x4009ee10.
316Hey I'M in base class constructor number 6 for 0x4009ee18.
317Hey I'M in base class constructor number 7 for 0x4009ee20.
318Hey I'M in derived class constructor number 8 for 0x4009ee20.
319Testing a C++ I/O stream
320Hey I'M in derived class constructor number 8 for 0x4009ee20.
321Derived class - Instantiation order 8
322Hey I'M in base class constructor number 7 for 0x4009ee20.
323Instantiation order 8
324Hey I'M in base class constructor number 6 for 0x4009ee18.
325Instantiation order 6
326Hey I'M in base class constructor number 5 for 0x4009ee10.
327Instantiation order 5
328Hey I'M in base class constructor number 4 for 0x4009ee08.
329Instantiation order 5
330*** END OF CONSTRUCTOR/DESTRUCTOR TEST ***
331Hey I'M in base class constructor number 3 for 0x400010d4.
332Hey I'M in base class constructor number 2 for 0x400010d4.
333Hey I'M in base class constructor number 1 for 0x400010cc.
334@end group
335@end example
336
337@c
338@c
339@c
340@section Minimum Size Test
341
342This sample application is in the following directory:
343
344@example
345$@{RTEMS_ROOT@}/testsuites/samples/minimum/
346@end example
347
348This sample application is designed to produce the
349minimum code space required for any RTEMS application
350based upon the current RTEMS configuration and
351BSP.  In many situations, the bulk of this executable
352consists of hardware and RTEMS initialization, basic
353infrastructure such as malloc(), and RTEMS and
354hardware shutdown support.
355
356@c
357@c
358@c
359@section Nanosecond Granularity Application
360
361This sample application is in the following directory:
362
363@example
364$@{RTEMS_ROOT@}/testsuites/samples/nsecs/
365@end example
366
367This sample application exercises the Clock Driver
368for this BSP and demonstrates its ability to generate
369accurate timestamps.  This application does this by
370exercising the time subsystem in three ways:
371
372@itemize @bullet
373@item Obtain Time of Day Twice Back to Back
374@item Obtain System Up Time Twice Back to Back
375@item Use System Up Time to Measure Loops
376@end itemize
377
378The following is an example of what the output of this
379test may appear like:
380
381@example
382*** NANOSECOND CLOCK TEST ***
38310 iterations of getting TOD
384Start: Sat Mar 24 11:15:00 2007:540000
385Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000
386Start: Sat Mar 24 11:15:00 2007:3974000
387Stop : Sat Mar 24 11:15:00 2007:3983000 --> 0:9000
388Start: Sat Mar 24 11:15:00 2007:7510000
389Stop : Sat Mar 24 11:15:00 2007:7519000 --> 0:9000
390Start: Sat Mar 24 11:15:00 2007:11054000
391Stop : Sat Mar 24 11:15:00 2007:11063000 --> 0:9000
392Start: Sat Mar 24 11:15:00 2007:14638000
393Stop : Sat Mar 24 11:15:00 2007:14647000 --> 0:9000
394Start: Sat Mar 24 11:15:00 2007:18301000
395Stop : Sat Mar 24 11:15:00 2007:18310000 --> 0:9000
396Start: Sat Mar 24 11:15:00 2007:21901000
397Stop : Sat Mar 24 11:15:00 2007:21910000 --> 0:9000
398Start: Sat Mar 24 11:15:00 2007:25526000
399Stop : Sat Mar 24 11:15:00 2007:25535000 --> 0:9000
400Start: Sat Mar 24 11:15:00 2007:29196000
401Stop : Sat Mar 24 11:15:00 2007:29206000 --> 0:10000
402Start: Sat Mar 24 11:15:00 2007:32826000
403Stop : Sat Mar 24 11:15:00 2007:32835000 --> 0:9000
404
40510 iterations of getting Uptime
4060:38977000 0:38986000 --> 0:9000
4070:40324000 0:40332000 --> 0:8000
4080:41636000 0:41645000 --> 0:9000
4090:42949000 0:42958000 --> 0:9000
4100:44295000 0:44304000 --> 0:9000
4110:45608000 0:45617000 --> 0:9000
4120:46921000 0:46930000 --> 0:9000
4130:48282000 0:48291000 --> 0:9000
4140:49595000 0:49603000 --> 0:8000
4150:50908000 0:50917000 --> 0:9000
416
41710 iterations of getting Uptime with different loop values
418loop of 10000 0:119488000 0:119704000 --> 0:216000
419loop of 20000 0:124028000 0:124463000 --> 0:435000
420loop of 30000 0:128567000 0:129220000 --> 0:653000
421loop of 40000 0:133097000 0:133964000 --> 0:867000
422loop of 50000 0:137643000 0:138728000 --> 0:1085000
423loop of 60000 0:142265000 0:143572000 --> 0:1307000
424loop of 70000 0:146894000 0:148416000 --> 0:1522000
425loop of 80000 0:151519000 0:153260000 --> 0:1741000
426loop of 90000 0:156145000 0:158099000 --> 0:1954000
427loop of 100000 0:160770000 0:162942000 --> 0:2172000
428*** END OF NANOSECOND CLOCK TEST ***
429@end example
430
431@c
432@c
433@c
434@section Paranoia Floating Point Application
435
436This sample application is in the following directory:
437
438@example
439$@{RTEMS_ROOT@}/testsuites/samples/paranoia/
440@end example
441
442This sample application uses a public domain floating
443point and math library test to verify these capabilities of the
444RTEMS executive.  Deviations between actual and expected results
445are reported to the screen.  This is a very extensive test which
446tests all mathematical and number conversion functions.
447Paranoia is also very large and requires a long period of time
448to run.   Problems which commonly prevent this test from
449executing to completion include stack overflow and FPU exception
450handlers not installed.
451
452@c
453@c
454@c
455@section Network Loopback Test
456
457This sample application is in the following directory:
458
459@example
460$@{RTEMS_ROOT@}/testsuites/samples/loopback/
461@end example
462
463This sample application uses the network loopback device to
464demonstrate the use of the RTEMS TCP/IP stack.  This sample
465test illustrates the basic configuration and initialization
466of the TCP/IP stack as well as simple socket usage.
467
Note: See TracBrowser for help on using the repository browser.