= Create a POSIX Timing Test =

[[TOC(GCI/Coding/POSIXTimingTest , depth=2)]]

== Directions for Students ==

**Pre-Requisite**: You '''must''' have completed the "Getting Started: Hello World" task or equivalently done the [wiki:GSoC/GettingStarted GSoC Getting Started Guide] before attempting this task.
This task consists of adding a benchmark test to the RTEMS POSIX Timing Test Suite.  There are templates for each benchmark pattern we have identified.  The task consists of identifying the correct pattern, instantiating it using the "mktest" script, and then filling that in with the appropriate calls.

===  Invoking rtems-testing/rtems-test-template/mktest  ===

First of all you will need the [https://git.rtems.org/rtems-testing/ rtems-testing] repository .

{{{
 cd development
 git git://git.rtems.org/rtems-testing.git
}}}

**NOTE** : Which contains different **templates** for tests ,**Templates**  are generalized benchmark skeleton tests given for making the work of making specific test cases easier . You will have to follow the same format as of the template while calling functions in the test. 

Second ,instantiating the mktest script ,
for this you must be in rtems tree and inside the rtems/testsuites/psxtmtests , here is where you will find all the benchmark tests for POSIX API.
This folder also contains the [https://git.rtems.org/rtems/tree/testsuites/psxtmtests/psxtmtests_plan.csv psxtmtests_plan.csv] file which is the plan for making all tests,
you will identify the name of template , test case ,test name and status of test ('Yes' means it exists).
Search for the test case name of which you have to generate the benchmark test. Identify the name of the corresponding template .
Take the test psxtmcond04 , so you will give the following attributes to the script.   


{{{
 ~development/rtems-testing/rtems-test-template/mktest \
 -t ~/rtems-testing/rtems-test-template/psxtmtest_unblocking_preempt \
 -s ~/rtems-testing/rtems-test-template \
 -d psxtmcond04 \
 -n 4
}}}

You'll need to specify the source (-s),location/path of template (-t), the destination directory (-d),(-D)Discription, and the test number (-n). Change the location to match where you put rtems-testing.

This step will generate the required test , here (psxtmcond04)


===  Adding the Test to the Build System  ===

To add a test to the build system, you'll need to add it to configure.ac and Makefile.am.  Then you'll need to ./bootstrap it.
bootstrap will include these changes in Makefile.in also

Changes to Makefile.am
                           rtems/testsuites/psxtmtests/Makefile.am
{{{
  SUBDIRS += psxtmthread01
  SUBDIRS += psxtmthread03
  SUBDIRS += psxtmcond04 # Add a SUBDIRS entry to the bottom
 endif
}}}
Changes to configure.ac
                           rtems/testsuites/psxtmtests/configure.ac
{{{
  psxtmthread01/Makefile
  psxtmthread03/Makefile
  psxtmcond04/Makefile
 ])
 AC_OUTPUT
}}}
Now bootstrap it
{{{
 cd ~/rtems
 ~/rtems> ./bootstrap
}}}
Now build the any bsp belonging to the architecture installed , here is the build of erc32 bsp 
    
{{{
$ cd development
$ mkdir erc32
$ cd erc32
$ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/5 \
> --target=sparc-rtems5 --enable-rtemsbsp=erc32 --enable-posix --enable-tests
  ...
  ...
$ make -j 2
  ...
  ...
$ make install
  ...
  ...
}}}

This will take some time



===  Finding an Example  ===

Now that the test has been added to the build system, find working examples of the functions to call.  One way to do that is to use grep -r.  From the terminal, there may be characters that have to be "escaped" \. For example to create a test of pthread_cond_init() put the following in the command line:
{{{
 grep -r pthread\_cond\_init ~/rtems/testsuites/
}}}
===  !Simulator/Emulator  ===

Finally use a simulator/emulator
See http://www.rtems.org/wiki/index.php/Quick_Start
===  Lather, Rinse, Repeat  ===

Add all the #includes, at the top, compare the macros at the bottom, cut-and-paste from working example of the source code into the generated test, see what happens. 

After each change, clean the build directory, rebuild the source, and try again, depending on the simulator something like:

{{{
 $ cd ~/development/erc32/sparc-rtems5/c/erc32/testsuites/psxtmtests/ 
 $ make clean
  ...
 $ make
  ...
}}}


This is a particularly challenging task, so asking questions, and making suggestions for improving the directions on this task would be greatly appreciated.
===  Posix Time Test Plan (for generating more GCI tasks)  ===


This task can be instantiated for multiple areas in POSIX but the following is a typical set for communications and synchronization objects.  A GSOC 2011 project implemented many tests for semaphores, message queues, etc., but there are still many left to implement. Following is a link to the Comma Separated Value (e.g., .csv) file which is exported from the spreadsheet used to track the status of this effort.

 *  http://git.rtems.org/rtems/tree/testsuites/psxtmtests/psxtmtests_plan.csv
There are likely 50-100 instances of this task possible.

== Directions for Mentors == 
This should be evaluated as a normal code submission. You need to review and run the test to ensure it is correct. It should be based on the templates in rtems-testing. The student should provide a name and email for proper attribution. If you have write permission, commit it. Otherwise, send it to rtems-devel for another developer to commit with commentary indicating it is acceptable and from GCI.