source: rtems-docs/develenv/sample.rst @ be428d1

4.115
Last change on this file since be428d1 was 489740f, checked in by Chris Johns <chrisj@…>, on May 20, 2016 at 2:47:09 AM

Set SPDX License Identifier in each source file.

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