Create a POSIX Timing Test

Directions for Students

Pre-Requisite: You must have completed the "Getting Started: Hello World" task or equivalently done the 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 ​rtems-testing repository .

 cd development
 git clone 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 ​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

Calling Functions in the test

Now that the test has been added to the build system, find working examples of the functions to call.Look into init.c files of different tests made through the same template For example consider the test psxtmcond04 in you need to call functions. Note that this test belongs to psxtmtest_unblocking_preempt , look into tests belonging to the same template like psxtmcond07 , these will differ in their tests but will have the same common skeleton that will give you an idea for what functions to call.

Use grep -r to search for the uses of a pirticular function that you would like to call in the test . For this open the terminal and cd into the rtems tree and testsuites , then for a function "name_of_function()" use

  grep -r name\_of\_function 

For example to create a test of pthread_cond_init() put the following in the command line:

 grep -r pthread\_cond\_init 

Use the man command to load an manual for a specific function , this manual will give you a detailed description of what is the use of this function , arguments of this function and how to use them. If you cannot find the manual for a particular function , ping a mentor . Now that you have made the desired changes in the test/init.c file , go ahead and rebuild the psxtmtests module of your BSP

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

If you find errors while compiling ,search for their location in the init.c file and debug them , after debugging them run the above script again to record the changes in the bsp. You will have to repeat this after every change you make in the init.c file

Once you compile without getting any error , Run the simulator using the following steps

Simulator/Emulator

The use of simulator is pretty much the same as you did while running the Hello.exe

     cd ~/development/erc32/sparc-rtems5/c/erc32/testsuites/psxtmtests/
     sparc-rtems5-gdb "nameoftest.exe"
....
(gdb)tar sim
....
(gdb)load 
....
(gdb)r
....

See http://www.rtems.org/wiki/index.php/Quick_Start for more help

Lather, Rinse, Repeat

After each change, clean the build directory, rebuild the source, and try again.

SUGGESTIONS

• run other test to see what output they give and compare it with yours
• This Task will test your knowledge regarding code (mostly C/C++). Try to use the man command as much as possible to know more about necessary functions.

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.