Add POSIX Method Signature Compliance Tests

Directions for Students

Prerequisite: You must have completed the "Getting Started: Hello World" task or equivalently done the GSoC Getting Started Guide before attempting this task.

Creating a Test

First, verify this is header file available in the RTEMS environment. If not, please contact your mentors.

To create a test, you'll need to be in the rtems/testsuite/psxtests/psxheader/@your_header@ directory. Note that the @your_header@ directory will be the name of the header file without the .h. For example, stdio.h related tests will be in psxtests/psxhdr/stdio and those for sys/mman.h are in sys/mman.

For the header file you have been given, you will be creating a simple test case that verifies that RTEMS matches the POSIX defined signature of the method as defined at ​http://pubs.opengroup.org/onlinepubs/9699919799/. Search for the header file you have been assigned and check every method that is in it. For each method, its specification page will have something like this (from time()):

The test for time() is in psxtests/psxhdr/time/time.c and (ignoring comments and boilerplate) is as follows:

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif

#include <time.h>

int test( void );

int test( void )
{
  time_t    new_time;

  new_time = time( &new_time );

  return (new_time != -1);
}

Note that a variable of each time passed in and returned is declared. The POSIX standard told us that time() could be invoked by including only the <time.h> header file and this test verifies that RTEMS follows the standard.

Each header file has multiple methods. Each goes in a separate file.

Use other existing tests as guides but note that some do not follow the proper Doxygen style expected now in RTEMS. Please use current style like pthread/pthread_getconcurrency.c:

/**
 *  @file
 *  @brief pthread_getconcurrency() API Conformance Test
 */

Also some use the RTEMS GPL v2 with exception license. Use the BSD style license found here: ​https://git.rtems.org/rtems-testing/tree/rtems-test-template/psxtest/init.c.

/*
 *  COPYRIGHT (c) <YYYY>.
 *  <author goes here>
 *
 *  Permission to use, copy, modify, and/or distribute this software
 *  for any purpose with or without fee is hereby granted.
 * 
 *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
 *  WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
 *  WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR
 *  BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
 *  OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 *  WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
 *  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

Adding the Test to the Build System

To add a test to the build system, you'll need to add it to psxtests/Makefile.am. Search for psxhdrs in the Makefile.am and then just add your new files to the list.

Then you'll need to "bootstrap" from the psxtests directory.

Now bootstrap it

 cd ~/rtems/testsuites/psxtests
 ~/rtems> ../../bootstrap

Now build...

 cd ../b-erc32
 ../rtems/configure --options --used --to --configure

Be sure to include --enable-tests on the configure command.

These tests are compile only and are not intended to be executed.

Directions for Mentors

This should be evaluated as a normal code submission. You need to review and verify the tests compile warning free to ensure it is correct. These are compile-only tests. 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 devel@… for another developer to commit with commentary indicating it is acceptable and from GCI.

Ensure the license and Doxygen file headers are correct.

Ensure it is using a BSD-0 style license.