summaryrefslogtreecommitdiffstats
path: root/develenv/sample.rst
diff options
context:
space:
mode:
authorAmar Takhar <verm@darkbeer.org>2016-01-16 14:53:40 -0500
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:22 -0400
commitc0d6eff67d896dbe0b73761d5dd9d59bd71ddfcd (patch)
treeca8641db1455b3727e843316373a93a5b84bb573 /develenv/sample.rst
parentFix warnings. (diff)
downloadrtems-docs-c0d6eff67d896dbe0b73761d5dd9d59bd71ddfcd.tar.bz2
Split document.
Diffstat (limited to 'develenv/sample.rst')
-rw-r--r--develenv/sample.rst412
1 files changed, 412 insertions, 0 deletions
diff --git a/develenv/sample.rst b/develenv/sample.rst
new file mode 100644
index 0000000..fa35f6a
--- /dev/null
+++ b/develenv/sample.rst
@@ -0,0 +1,412 @@
+Sample Applications
+###################
+
+Introduction
+============
+
+The RTEMS source distribution includes a set of sample applications
+that are located in the ``${RTEMS_ROOT}/testsuites/samples/``
+directory. These applications are intended to illustrate the
+basic format of RTEMS single and multiple processor
+applications and the use of some features. In addition, these
+relatively simple applications can be used to test locally
+developed board support packages and device drivers as they
+exercise a critical subset of RTEMS functionality that is often
+broken in new BSPs.
+
+Some of the following sample applications will be covered in
+more detail in subsequent sections:
+
+*Hello World*
+ The RTEMS Hello World test is provided in
+ the subdirectory ``${RTEMS_ROOT}/testsuites/samples/hello/``.
+ This test is helpful when testing new RTEMS development environment.
+
+*Clock Tick*
+ The ``${RTEMS_ROOT}/testsuites/samples/ticker/``
+ subdirectory provides a test for verification of clock chip
+ device drivers of BSPs.
+
+*Base Single Processor*
+ A simple single processor test similar to those in the
+ single processor test suite is provided in ``${RTEMS_ROOT}/testsuites/samples/base_sp/``.
+
+*Base Multiple Processor*
+ A simple two node multiprocessor test capable of testing an newly
+ developed MPCI layer is provided in ``${RTEMS_ROOT}/testsuites/samples/base_mp/``.
+
+*Capture*
+ The RTEMS Capture test is provided in
+ the subdirectory ``${RTEMS_ROOT}/testsuites/samples/capture/``.
+ This is an interactive test which demonstrates the capabilities
+ of the RTEMS Capture Engine. It includes a few test threads
+ which generate interesting execution patterns. Look at the
+ file ``${RTEMS_ROOT}/testsuites/samples/capture/capture.scn``
+ for a sample session.
+
+*Constructor/Destructor C++ Test*
+ The ``${RTEMS_ROOT}/testsuites/samples/cdtest/``
+ subdirectory provides a simple C++ application using
+ constructors and destructors. It is only built when
+ C++ is enabled and its primary purpose is to demonstrate
+ that global constructors and destructors work. Since this
+ requires that the linker script for your BSP be correct, this is
+ an important test.
+
+*File IO*
+ The RTEMS File IO test is provided in
+ the subdirectory ``${RTEMS_ROOT}/testsuites/samples/fileio/``.
+ This is an interactive test which allows the user to interact with
+ an ATA/IDE device. It will read the partition table and allow the
+ user to dynamically mount one of the FAT32 partitions it finds.
+ Commands are also provided to write and read files on the disk.
+
+*IO Stream*
+ The RTEMS IO Stream test is provided in
+ the subdirectory ``${RTEMS_ROOT}/testsuites/samples/iostream/``.
+ This test is a simple C++ application which demonstrates that
+ C++ iostreams are functional. This requires that the RTEMS C++
+ run-time support is functioning properly. This test is only
+ build when C++ is enabled.
+
+*Network Loopback Test*
+ The ``${RTEMS_ROOT}/testsuites/samples/loopback/``
+ directory contains a sample test that demonstrates the use of
+ sockets and the loopback network device. It does not require
+ the presence of network hardware in order to run.
+ It is only built if RTEMS was configured with networking enabled.
+
+*Minimum Size Test*
+ The directory``${RTEMS_ROOT}/testsuites/samples/minimum/``
+ contains a simple RTEMS program that results in a non-functional
+ executable. It is intended to show the size of a minimum footprint
+ application based upon the current RTEMS configuration.
+
+*Nanoseconds*
+ The RTEMS Nanoseconds test is provided in
+ the subdirectory ``${RTEMS_ROOT}/testsuites/samples/nsecs/``.
+ This test demonstrates that the BSP has support for nanosecond
+ timestamp granularity. It prints the time of day and uptime multiple
+ times as quickly as possible. It should be possible from the output
+ to determine if your BSP has nanosecond accurate clock support
+ and it is functional.
+
+*Paranoia Floating Point Test*
+ The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/``
+ contains the public domain floating point and math library test.
+
+*Point-to-Point Protocol Daemon*
+ The RTEMS Point-to-Point Protocol Daemon test is provided in
+ the subdirectory ``${RTEMS_ROOT}/testsuites/samples/pppd/``.
+ This test primarily serves as the baseline for a user application
+ using the PPP protocol.
+
+*Unlimited Object Allocation*
+ The ``${RTEMS_ROOT}/testsuites/samples/unlimited/``
+ directory contains a sample test that demonstrates the use of the*unlimited* object allocation configuration option to RTEMS.
+
+The sample tests are written using the Classic API so the reader
+should be familiar with the terms used and
+material presented in the *RTEMS Applications Users Guide*.
+
+Hello World
+===========
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/hello/
+
+It provides a rudimentary test of the BSP start up
+code and the console output routine. The C version of this
+sample application uses the printf function from the RTEMS
+Standard C Library to output messages. The Ada version of this
+sample uses the TEXT_IO package to output the hello messages.
+The following messages are printed:
+.. code:: c
+
+ *** HELLO WORLD TEST \***
+ Hello World
+ \*** END OF HELLO WORLD TEST \***
+
+These messages are printed from the application’s
+single initialization task. If the above messages are not
+printed correctly, then either the BSP start up code or the
+console output routine is not operating properly.
+
+Clock Tick
+==========
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/ticker/
+
+This application is designed as a simple test of the
+clock tick device driver. In addition, this application also
+tests the printf function from the RTEMS Standard C Library by
+using it to output the following messages:
+.. code:: c
+
+ *** CLOCK TICK TEST \***
+ TA1 - tm_get - 09:00:00 12/31/1988
+ TA2 - tm_get - 09:00:00 12/31/1988
+ TA3 - tm_get - 09:00:00 12/31/1988
+ TA1 - tm_get - 09:00:05 12/31/1988
+ TA1 - tm_get - 09:00:10 12/31/1988
+ TA2 - tm_get - 09:00:10 12/31/1988
+ TA1 - tm_get - 09:00:15 12/31/1988
+ TA3 - tm_get - 09:00:15 12/31/1988
+ TA1 - tm_get - 09:00:20 12/31/1988
+ TA2 - tm_get - 09:00:20 12/31/1988
+ TA1 - tm_get - 09:00:25 12/31/1988
+ TA1 - tm_get - 09:00:30 12/31/1988
+ TA2 - tm_get - 09:00:30 12/31/1988
+ TA3 - tm_get - 09:00:30 12/31/1988
+ \*** END OF CLOCK TICK TEST \***
+
+The clock tick sample application utilizes a single
+initialization task and three copies of the single application
+task. The initialization task prints the test herald, sets the
+time and date, and creates and starts the three application
+tasks before deleting itself. The three application tasks
+generate the rest of the output. Every five seconds, one or
+more of the tasks will print the current time obtained via the
+tm_get directive. The first task, TA1, executes every five
+seconds, the second task, TA2, every ten seconds, and the third
+task, TA3, every fifteen seconds. If the time printed does not
+match the above output, then the clock device driver is not
+operating properly.
+
+Base Single Processor Application
+=================================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/base_sp/
+
+It provides a framework from which a single processor
+RTEMS application can be developed. The use of the task argument
+is illustrated. This sample application uses the printf
+function from the RTEMS Standard C Library or TEXT_IO functions
+when using the Ada version to output the following messages:
+.. code:: c
+
+ *** SAMPLE SINGLE PROCESSOR APPLICATION \***
+ Creating and starting an application task
+ Application task was invoked with argument (0) and has id of 0x10002
+ \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \***
+
+The first two messages are printed from the
+application’s single initialization task. The final messages
+are printed from the single application task.
+
+Base Multiple Processor Application
+===================================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/base_mp/
+
+It provides a framework from which a multiprocessor
+RTEMS application can be developed. This directory has a
+subdirectory for each node in the multiprocessor system. The
+task argument is used to distinguish the node on which the
+application task is executed. The first node will print the
+following messages:
+.. code:: c
+
+ *** SAMPLE MULTIPROCESSOR APPLICATION \***
+ Creating and starting an application task
+ This task was invoked with the node argument (1)
+ This task has the id of 0x10002
+ \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
+
+The second node will print the following messages:
+.. code:: c
+
+ *** SAMPLE MULTIPROCESSOR APPLICATION \***
+ Creating and starting an application task
+ This task was invoked with the node argument (2)
+ This task has the id of 0x20002
+ \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
+
+The herald is printed from the application’s single
+initialization task on each node. The final messages are
+printed from the single application task on each node.
+
+In this sample application, all source code is shared
+between the nodes except for the node dependent configuration
+files. These files contains the definition of the node number
+used in the initialization of the RTEMS Multiprocessor
+Configuration Table. This file is not shared because the node
+number field in the RTEMS Multiprocessor Configuration Table
+must be unique on each node.
+
+Constructor/Destructor C++ Application
+======================================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/cdtest/
+
+This sample application demonstrates that RTEMS is
+compatible with C++ applications. It uses constructors,
+destructor, and I/O stream output in testing these various
+capabilities. The board support package responsible for this
+application must support a C++ environment.
+
+This sample application uses the printf function from
+the RTEMS Standard C Library to output the following messages:
+.. code:: c
+
+ Hey I'M in base class constructor number 1 for 0x400010cc.
+ Hey I'M in base class constructor number 2 for 0x400010d4.
+ Hey I'M in derived class constructor number 3 for 0x400010d4.
+ \*** CONSTRUCTOR/DESTRUCTOR TEST \***
+ Hey I'M in base class constructor number 4 for 0x4009ee08.
+ Hey I'M in base class constructor number 5 for 0x4009ee10.
+ Hey I'M in base class constructor number 6 for 0x4009ee18.
+ Hey I'M in base class constructor number 7 for 0x4009ee20.
+ Hey I'M in derived class constructor number 8 for 0x4009ee20.
+ Testing a C++ I/O stream
+ Hey I'M in derived class constructor number 8 for 0x4009ee20.
+ Derived class - Instantiation order 8
+ Hey I'M in base class constructor number 7 for 0x4009ee20.
+ Instantiation order 8
+ Hey I'M in base class constructor number 6 for 0x4009ee18.
+ Instantiation order 6
+ Hey I'M in base class constructor number 5 for 0x4009ee10.
+ Instantiation order 5
+ Hey I'M in base class constructor number 4 for 0x4009ee08.
+ Instantiation order 5
+ \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \***
+ Hey I'M in base class constructor number 3 for 0x400010d4.
+ Hey I'M in base class constructor number 2 for 0x400010d4.
+ Hey I'M in base class constructor number 1 for 0x400010cc.
+
+Minimum Size Test
+=================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/minimum/
+
+This sample application is designed to produce the
+minimum code space required for any RTEMS application
+based upon the current RTEMS configuration and
+BSP. In many situations, the bulk of this executable
+consists of hardware and RTEMS initialization, basic
+infrastructure such as malloc(), and RTEMS and
+hardware shutdown support.
+
+Nanosecond Granularity Application
+==================================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/nsecs/
+
+This sample application exercises the Clock Driver
+for this BSP and demonstrates its ability to generate
+accurate timestamps. This application does this by
+exercising the time subsystem in three ways:
+
+- Obtain Time of Day Twice Back to Back
+
+- Obtain System Up Time Twice Back to Back
+
+- Use System Up Time to Measure Loops
+
+The following is an example of what the output of this
+test may appear like:
+.. code:: c
+
+ *** NANOSECOND CLOCK TEST \***
+ 10 iterations of getting TOD
+ Start: Sat Mar 24 11:15:00 2007:540000
+ Stop : Sat Mar 24 11:15:00 2007:549000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:3974000
+ Stop : Sat Mar 24 11:15:00 2007:3983000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:7510000
+ Stop : Sat Mar 24 11:15:00 2007:7519000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:11054000
+ Stop : Sat Mar 24 11:15:00 2007:11063000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:14638000
+ Stop : Sat Mar 24 11:15:00 2007:14647000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:18301000
+ Stop : Sat Mar 24 11:15:00 2007:18310000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:21901000
+ Stop : Sat Mar 24 11:15:00 2007:21910000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:25526000
+ Stop : Sat Mar 24 11:15:00 2007:25535000 --> 0:9000
+ Start: Sat Mar 24 11:15:00 2007:29196000
+ Stop : Sat Mar 24 11:15:00 2007:29206000 --> 0:10000
+ Start: Sat Mar 24 11:15:00 2007:32826000
+ Stop : Sat Mar 24 11:15:00 2007:32835000 --> 0:9000
+ 10 iterations of getting Uptime
+ 0:38977000 0:38986000 --> 0:9000
+ 0:40324000 0:40332000 --> 0:8000
+ 0:41636000 0:41645000 --> 0:9000
+ 0:42949000 0:42958000 --> 0:9000
+ 0:44295000 0:44304000 --> 0:9000
+ 0:45608000 0:45617000 --> 0:9000
+ 0:46921000 0:46930000 --> 0:9000
+ 0:48282000 0:48291000 --> 0:9000
+ 0:49595000 0:49603000 --> 0:8000
+ 0:50908000 0:50917000 --> 0:9000
+ 10 iterations of getting Uptime with different loop values
+ loop of 10000 0:119488000 0:119704000 --> 0:216000
+ loop of 20000 0:124028000 0:124463000 --> 0:435000
+ loop of 30000 0:128567000 0:129220000 --> 0:653000
+ loop of 40000 0:133097000 0:133964000 --> 0:867000
+ loop of 50000 0:137643000 0:138728000 --> 0:1085000
+ loop of 60000 0:142265000 0:143572000 --> 0:1307000
+ loop of 70000 0:146894000 0:148416000 --> 0:1522000
+ loop of 80000 0:151519000 0:153260000 --> 0:1741000
+ loop of 90000 0:156145000 0:158099000 --> 0:1954000
+ loop of 100000 0:160770000 0:162942000 --> 0:2172000
+ \*** END OF NANOSECOND CLOCK TEST \***
+
+Paranoia Floating Point Application
+===================================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/paranoia/
+
+This sample application uses a public domain floating
+point and math library test to verify these capabilities of the
+RTEMS executive. Deviations between actual and expected results
+are reported to the screen. This is a very extensive test which
+tests all mathematical and number conversion functions.
+Paranoia is also very large and requires a long period of time
+to run. Problems which commonly prevent this test from
+executing to completion include stack overflow and FPU exception
+handlers not installed.
+
+Network Loopback Test
+=====================
+
+This sample application is in the following directory:
+.. code:: c
+
+ ${RTEMS_ROOT}/testsuites/samples/loopback/
+
+This sample application uses the network loopback device to
+demonstrate the use of the RTEMS TCP/IP stack. This sample
+test illustrates the basic configuration and initialization
+of the TCP/IP stack as well as simple socket usage.
+
+.. COMMENT: COPYRIGHT (c) 1989-2007.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+