source: rtems-docs/develenv/sample.rst @ 8c75d59

4.11
Last change on this file since 8c75d59 was 8c75d59, checked in by Joel Sherrill <joel@…>, on Oct 27, 2016 at 11:26:57 PM

develenv: Fix build errors

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