Changeset 9b53679 in rtems-docs for develenv/sample.rst


Ignore:
Timestamp:
Oct 27, 2016, 11:12:50 PM (4 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.11, master
Children:
8e59c99
Parents:
be428d1
git-author:
Chris Johns <chrisj@…> (10/27/16 23:12:50)
git-committer:
Chris Johns <chrisj@…> (10/27/16 23:13:03)
Message:

Fix develenv. Needs more fixes.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • develenv/sample.rst

    rbe428d1 r9b53679  
    77============
    88
    9 The RTEMS source distribution includes a set of sample applications
    10 that are located in the ``${RTEMS_ROOT}/testsuites/samples/``
    11 directory.  These applications are intended to illustrate the
    12 basic format of RTEMS single and multiple processor
    13 applications and the use of some features.  In addition, these
    14 relatively simple applications can be used to test locally
    15 developed board support packages and device drivers as they
    16 exercise a critical subset of RTEMS functionality that is often
    17 broken in new BSPs.
    18 
    19 Some of the following sample applications will be covered in
    20 more detail in subsequent sections:
     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:
    2119
    2220*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.
     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.
    2624
    2725*Clock Tick*
    28     The ``${RTEMS_ROOT}/testsuites/samples/ticker/``
    29     subdirectory provides a test for verification of clock chip
    30     device drivers of BSPs.
     26    The ``${RTEMS_ROOT}/testsuites/samples/ticker/`` subdirectory provides a
     27    test for verification of clock chip device drivers of BSPs.
    3128
    3229*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/``.
     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/``.
    3532
    3633*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/``.
     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/``.
    3936
    4037*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``
     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``
    4743    for a sample session.
    4844
    4945*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.
     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.
    5751
    5852*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.
     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.
    6559
    6660*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.
     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.
    7366
    7467*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.
     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.
    8072
    8173*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.
     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.
    8678
    8779*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.
     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.
    9587
    9688*Paranoia Floating Point Test*
    97     The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/``
    98     contains the public domain floating point and math library test.
     89    The directory ``${RTEMS_ROOT}/testsuites/samples/paranoia/`` contains the
     90    public domain floating point and math library test.
    9991
    10092*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.
     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.
    10597
    10698*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 
    110 The sample tests are written using the Classic API so the reader
    111 should be familiar with the terms used and
    112 material presented in the *RTEMS Applications Users Guide*.
     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.
     102
     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*.
    113106
    114107Hello World
     
    116109
    117110This sample application is in the following directory:
    118 .. code:: c
     111
     112.. code-block:: c
    119113
    120114    ${RTEMS_ROOT}/testsuites/samples/hello/
    121115
    122 It provides a rudimentary test of the BSP start up
    123 code and the console output routine.  The C version of this
    124 sample application uses the printf function from the RTEMS
    125 Standard C Library to output messages.   The Ada version of this
    126 sample uses the TEXT_IO package to output the hello messages.
    127 The following messages are printed:
    128 .. code:: c
    129 
    130     *** HELLO WORLD TEST \***
     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:
     121
     122.. code-block:: c
     123
     124    *** HELLO WORLD TEST ***
    131125    Hello World
    132     \*** END OF HELLO WORLD TEST \***
    133 
    134 These messages are printed from the application's
    135 single initialization task.  If the above messages are not
    136 printed correctly, then either the BSP start up code or the
    137 console output routine is not operating properly.
     126    *** END OF HELLO WORLD TEST ***
     127
     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.
    138131
    139132Clock Tick
     
    141134
    142135This sample application is in the following directory:
    143 .. code:: c
     136
     137.. code-block:: c
    144138
    145139    ${RTEMS_ROOT}/testsuites/samples/ticker/
    146140
    147 This application is designed as a simple test of the
    148 clock tick device driver.  In addition, this application also
    149 tests the printf function from the RTEMS Standard C Library by
    150 using it to output the following messages:
    151 .. code:: c
    152 
    153     *** CLOCK TICK TEST \***
     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
     145.. code-block:: c
     146
     147    *** CLOCK TICK TEST ***
    154148    TA1 - tm_get - 09:00:00   12/31/1988
    155149    TA2 - tm_get - 09:00:00   12/31/1988
     
    166160    TA2 - tm_get - 09:00:30   12/31/1988
    167161    TA3 - tm_get - 09:00:30   12/31/1988
    168     \*** END OF CLOCK TICK TEST \***
    169 
    170 The clock tick sample application utilizes a single
    171 initialization task and three copies of the single application
    172 task.  The initialization task prints the test herald, sets the
    173 time and date, and creates and starts the three application
    174 tasks before deleting itself.  The three application tasks
    175 generate the rest of the output.  Every five seconds, one or
    176 more of the tasks will print the current time obtained via the
    177 tm_get directive.  The first task, TA1, executes every five
    178 seconds, the second task, TA2, every ten seconds, and the third
    179 task, TA3, every fifteen seconds. If the time printed does not
    180 match the above output, then the clock device driver is not
    181 operating properly.
     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.
    182173
    183174Base Single Processor Application
     
    185176
    186177This sample application is in the following directory:
    187 .. code:: c
     178
     179.. code-block:: c
    188180
    189181    ${RTEMS_ROOT}/testsuites/samples/base_sp/
    190182
    191 It provides a framework from which a single processor
    192 RTEMS application can be developed. The use of the task argument
    193 is illustrated.  This sample application uses the printf
    194 function from the RTEMS Standard C Library or TEXT_IO functions
    195 when using the Ada version to output the following messages:
    196 .. code:: c
    197 
    198     *** SAMPLE SINGLE PROCESSOR APPLICATION \***
     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
     188.. code-block:: c
     189
     190    *** SAMPLE SINGLE PROCESSOR APPLICATION ***
    199191    Creating and starting an application task
    200192    Application task was invoked with argument (0) and has id of 0x10002
    201     \*** END OF SAMPLE SINGLE PROCESSOR APPLICATION \***
    202 
    203 The first two messages are printed from the
    204 application's single initialization task.  The final messages
    205 are printed from the single application task.
     193    *** END OF SAMPLE SINGLE PROCESSOR APPLICATION ***
     194
     195The first two messages are printed from the application's single initialization
     196task.  The final messages are printed from the single application task.
    206197
    207198Base Multiple Processor Application
     
    209200
    210201This sample application is in the following directory:
    211 .. code:: c
     202
     203.. code-block:: c
    212204
    213205    ${RTEMS_ROOT}/testsuites/samples/base_mp/
    214206
    215 It provides a framework from which a multiprocessor
    216 RTEMS application can be developed. This directory has a
    217 subdirectory for each node in the multiprocessor system.  The
    218 task argument is used to distinguish the node on which the
    219 application task is executed.  The first node will print the
     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
    220211following messages:
    221 .. code:: c
    222 
    223     *** SAMPLE MULTIPROCESSOR APPLICATION \***
     212
     213.. code-block:: c
     214
     215    *** SAMPLE MULTIPROCESSOR APPLICATION ***
    224216    Creating and starting an application task
    225217    This task was invoked with the node argument (1)
    226218    This task has the id of 0x10002
    227     \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
     219    *** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
    228220
    229221The second node will print the following messages:
    230 .. code:: c
    231 
    232     *** SAMPLE MULTIPROCESSOR APPLICATION \***
     222
     223.. code-block:: c
     224
     225    *** SAMPLE MULTIPROCESSOR APPLICATION ***
    233226    Creating and starting an application task
    234227    This task was invoked with the node argument (2)
    235228    This task has the id of 0x20002
    236     \*** END OF SAMPLE MULTIPROCESSOR APPLICATION \***
    237 
    238 The herald is printed from the application's single
    239 initialization task on each node.  The final messages are
    240 printed from the single application task on each node.
    241 
    242 In this sample application, all source code is shared
    243 between the nodes except for the node dependent configuration
    244 files.  These files contains the definition of the node number
    245 used in the initialization of the  RTEMS Multiprocessor
    246 Configuration Table. This file is not shared because the node
    247 number field in the RTEMS Multiprocessor Configuration Table
    248 must be unique on each node.
     229    *** END OF SAMPLE MULTIPROCESSOR APPLICATION ***
     230
     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.
     234
     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.
    249241
    250242Constructor/Destructor C++ Application
     
    252244
    253245This sample application is in the following directory:
    254 .. code:: c
     246
     247.. code-block:: c
    255248
    256249    ${RTEMS_ROOT}/testsuites/samples/cdtest/
    257250
    258 This sample application demonstrates that RTEMS is
    259 compatible with C++ applications.  It uses constructors,
    260 destructor, and I/O stream output in testing these various
    261 capabilities.  The board support package responsible for this
    262 application must support a C++ environment.
    263 
    264 This sample application uses the printf function from
    265 the RTEMS Standard C Library to output the following messages:
    266 .. code:: c
     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:
     258
     259.. code-block:: c
    267260
    268261    Hey I'M in base class constructor number 1 for 0x400010cc.
    269262    Hey I'M in base class constructor number 2 for 0x400010d4.
    270263    Hey I'M in derived class constructor number 3 for 0x400010d4.
    271     \*** CONSTRUCTOR/DESTRUCTOR TEST \***
     264    *** CONSTRUCTOR/DESTRUCTOR TEST ***
    272265    Hey I'M in base class constructor number 4 for 0x4009ee08.
    273266    Hey I'M in base class constructor number 5 for 0x4009ee10.
     
    286279    Hey I'M in base class constructor number 4 for 0x4009ee08.
    287280    Instantiation order 5
    288     \*** END OF CONSTRUCTOR/DESTRUCTOR TEST \***
     281    *** END OF CONSTRUCTOR/DESTRUCTOR TEST ***
    289282    Hey I'M in base class constructor number 3 for 0x400010d4.
    290283    Hey I'M in base class constructor number 2 for 0x400010d4.
     
    295288
    296289This sample application is in the following directory:
    297 .. code:: c
     290
     291.. code-block:: c
    298292
    299293    ${RTEMS_ROOT}/testsuites/samples/minimum/
    300294
    301 This sample application is designed to produce the
    302 minimum code space required for any RTEMS application
    303 based upon the current RTEMS configuration and
    304 BSP.  In many situations, the bulk of this executable
    305 consists of hardware and RTEMS initialization, basic
    306 infrastructure such as malloc(), and RTEMS and
    307 hardware shutdown support.
     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.
    308300
    309301Nanosecond Granularity Application
     
    311303
    312304This sample application is in the following directory:
    313 .. code:: c
     305
     306.. code-block:: c
    314307
    315308    ${RTEMS_ROOT}/testsuites/samples/nsecs/
    316309
    317 This sample application exercises the Clock Driver
    318 for this BSP and demonstrates its ability to generate
    319 accurate timestamps.  This application does this by
    320 exercising the time subsystem in three ways:
     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:
    321313
    322314- Obtain Time of Day Twice Back to Back
     
    326318- Use System Up Time to Measure Loops
    327319
    328 The following is an example of what the output of this
    329 test may appear like:
    330 .. code:: c
    331 
    332     *** NANOSECOND CLOCK TEST \***
     320The following is an example of what the output of this test may appear like:
     321
     322.. code-block:: c
     323
     324    *** NANOSECOND CLOCK TEST ***
    333325    10 iterations of getting TOD
    334326    Start: Sat Mar 24 11:15:00 2007:540000
     
    374366    loop of 90000 0:156145000 0:158099000 --> 0:1954000
    375367    loop of 100000 0:160770000 0:162942000 --> 0:2172000
    376     \*** END OF NANOSECOND CLOCK TEST \***
     368    *** END OF NANOSECOND CLOCK TEST ***
    377369
    378370Paranoia Floating Point Application
     
    380372
    381373This sample application is in the following directory:
    382 .. code:: c
     374
     375.. code-block:: c
    383376
    384377    ${RTEMS_ROOT}/testsuites/samples/paranoia/
    385378
    386 This sample application uses a public domain floating
    387 point and math library test to verify these capabilities of the
    388 RTEMS executive.  Deviations between actual and expected results
    389 are reported to the screen.  This is a very extensive test which
    390 tests all mathematical and number conversion functions.
    391 Paranoia is also very large and requires a long period of time
    392 to run.   Problems which commonly prevent this test from
    393 executing to completion include stack overflow and FPU exception
    394 handlers not installed.
     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.
    395386
    396387Network Loopback Test
     
    398389
    399390This sample application is in the following directory:
    400 .. code:: c
     391
     392.. code-block:: c
    401393
    402394    ${RTEMS_ROOT}/testsuites/samples/loopback/
    403395
    404 This sample application uses the network loopback device to
    405 demonstrate the use of the RTEMS TCP/IP stack.  This sample
    406 test illustrates the basic configuration and initialization
    407 of 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 
     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 TracChangeset for help on using the changeset viewer.