[frescor/fosa.git] / src_marte / fosa_threads_and_signals.c

//----------------------------------------------------------------------
//  Copyright (C) 2006 - 2007 by the FRESCOR consortium:
//
//    Universidad de Cantabria,              SPAIN
//    University of York,                    UK
//    Scuola Superiore Sant'Anna,            ITALY
//    Kaiserslautern University,             GERMANY
//    Univ. Politecnica  Valencia,           SPAIN
//    Czech Technical University in Prague,  CZECH REPUBLIC
//    ENEA                                   SWEDEN
//    Thales Communication S.A.              FRANCE
//    Visual Tools S.A.                      SPAIN
//    Rapita Systems Ltd                     UK
//    Evidence                               ITALY
//
//    See http://www.frescor.org
//
//        The FRESCOR project (FP6/2005/IST/5-034026) is funded
//        in part by the European Union Sixth Framework Programme
//        The European Union is not liable of any use that may be
//        made of this code.
//
//
//  based on previous work (FSF) done in the FIRST project
//
//   Copyright (C) 2005  Mälardalen University, SWEDEN
//                       Scuola Superiore S.Anna, ITALY
//                       Universidad de Cantabria, SPAIN
//                       University of York, UK
//
// This file is part of FOSA (Frsh Operating System Abstraction)
//
// FOSA is free software; you can redistribute it and/or modify it
// under terms of the GNU General Public License as published by the
// Free Software Foundation; either version 2, or (at your option) any
// later version.  FOSA is distributed in the hope that it will be
// useful, but WITHOUT ANY WARRANTY; without even the implied warranty
// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// General Public License for more details. You should have received a
// copy of the GNU General Public License along with FOSA; see file
// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
// Cambridge, MA 02139, USA.
//
// As a special exception, including FOSA header files in a file,
// instantiating FOSA generics or templates, or linking other files
// with FOSA objects to produce an executable application, does not
// by itself cause the resulting executable application to be covered
// by the GNU General Public License. This exception does not
// however invalidate any other reasons why the executable file might be
// covered by the GNU Public License.
// -----------------------------------------------------------------------
//fosa_threads_and_signals.c
//==============================================
//  ********  ******    ********  **********
//  **///// /**    **  **//////  /**     /**
//  **      /**    ** /**        /**     /**
//  ******* /**    ** /********* /**********
//  **////  /**    ** ////////** /**//////**
//  **      /**    **        /** /**     /**
//  **      /**    **  ********  /**     /**
//  //       /******/  ////////   //      // 
//
// FOSA(Frescor Operating System Adaptation layer)
//================================================

#include "fosa_threads_and_signals.h"
#include "fosa_configuration_parameters.h"

#include <pthread.h>
#include <stdio.h>
#include <sched.h>

#include <misc/error_checks.h>

/**
 * @defgroup threadandsignals Thread and Signals
 * @ingroup fosa
 *
 * This module defines the functions that manipulate frsh_threads and
 * frsh_signals inside FRSH implementation.
 *
 * Applications can refer to FRSH threads but they cannot create them
 * directly, instead they must use frsh_thread_create*() which in turn
 * use fosa_thread_create().
 *
 * For signals, we assume that the OS provides a direct mapping
 * for frsh_signal_t and frsh_signal_info_t in the native interface.
 *
 * @{
 **/

//////////////////////////////////////////////////////////////////
// Storage of thread-specific keys
//   - key_list is an array containing the keys
//   - key_in_use is an array of booleans 
//   - key_lock is a mutex that locks the data structure 
//        while creating a new key
//   - keys_initialized indicates whether the key_in_use array and 
//        the key_lock mutex are initialized or not; it is declared
//        volatile as it may be accessed concurrently
//////////////////////////////////////////////////////////////////

static pthread_key_t key_list[FOSA_MAX_KEYS];
static bool key_in_use[FOSA_MAX_KEYS];
static pthread_once_t keys_initialized=PTHREAD_ONCE_INIT;
static pthread_mutex_t key_lock;


// Initialize the keys data structure
// This function should be called from pthread_once() to ensure
// one single initialization

void init_keys() {
  pthread_mutexattr_t attr;
  int i;

  // initialize the key_in_use array and the mutex
  for(i=0; i<FOSA_MAX_KEYS;i++) {
    key_in_use[i]=false;
  }
  // Initialize the mutex
  CHK(pthread_mutexattr_init(&attr));
  // we use the priority inheritance protocol because we don't know which
  // tasks will be using the mutex
  CHK(pthread_mutexattr_setprotocol(&attr,PTHREAD_PRIO_INHERIT));
  CHK(pthread_mutex_init(&key_lock,&attr));
  CHK(pthread_mutexattr_destroy(&attr));
}

/*************************
 * Thread identification
 *************************/ 

/**
 * fosa_thread_equal()
 *
 * Compare two thread identifiers to determine if they refer to the 
 * same thread
 **/
bool fosa_thread_equal(frsh_thread_id_t t1, frsh_thread_id_t t2)
{
  return pthread_equal(t1,t2);
}


/**
 * fosa_thread_self()
 *
 * Return the thread id of the calling thread
 **/
frsh_thread_id_t fosa_thread_self()
{
  return pthread_self();
}


/*************************
 * Thread creation and termination
 *************************/ 

/**
 * fosa_thread_create()
 *
 * This function creates a new thread using the attributes specified
 * in attr. If attr is NULL, default attributes are used. The new
 * thread starts running immediately, executing the function specified
 * by code, with an argument equal to arg. Upon successful return, the
 * variable pointed to by tid will contain the identifier of the newly
 * created thread. The set of signals that may be synchronously
 * accepted is inherited from the parent thread.
 *
 * Returns 0 if successful; otherwise it returs a code error:
 *
 *     EAGAIN: the system lacks the necessary resources to create a
 *             new thread or the maximum number of threads has been
 *             reached
 *
 *     EINVAL: the value specified by attr is invalid (for instance,
 *              it has not been correctly initialized)
 *
 *     EREJECT: the cretion of the thread was rejected by the frsh scheduler
 *               possibly because of incorrect attributes, or because the 
 *               requested minimum capacity cannot be guaranteed
 *
 **/
 int fosa_thread_create
    (frsh_thread_id_t *tid, const frsh_thread_attr_t *attr, 
     frsh_thread_code_t code, void * arg)
{
  return pthread_create(tid,attr,code,arg);
}


/**
 * Note: no thread termination primitive is provided. The termination
 * of a thread will be notified by the system to the FRSH scheduler
 * through the scheduler API
 **/


/**************************************************
 * Thread-specific data
 *  (extended with access from a different thread)
 *
 * Several data items (pointers) may be associated with each thread
 * Each item is identified through a key, an integer value between 0
 * and FOSA_MAX_KEYS-1. The caller is responsible of allocating and
 * deallocating the memory area pointed to by the pointer
 **************************************************/ 

/**
 * fosa_key_create()
 *
 * Create a new key for thread specific data.
 *
 * Prior to setting data in a key, we need ask the system to create
 * one for us.
 *
 * @return 0 if successful \n
 *   FOSA_EINVAL If we already have reached the FOSA_MAX_KEYS limit.
 *   FOSA_ENOMEM If there are no enough memory resources to 
 *               create the key.
 **/
int fosa_key_create(int *key)
{
  int i,ret_value;
  bool found=false;

  // initialize the keys data structure if needed
  CHK(pthread_once(&keys_initialized, init_keys));

  // lock the mutex
  CHK(pthread_mutex_lock(&key_lock));

  // find an unused key
  for(i=0; i<FOSA_MAX_KEYS;i++) {
    if (!key_in_use[i]) {
      *key=i;
      key_in_use[i]=true;
      ret_value=pthread_key_create(&(key_list[i]),NULL);
      found=true;
      break;
    }
  }
  // unlock the mutex before returning
  CHK(pthread_mutex_unlock(&key_lock));
  if (!found) {
    // all keys are in use; max keys reached
    ret_value=FOSA_EINVAL;
  }
  return ret_value;
}

/**
 * fosa_key_destroy()
 *
 * Destroy a key
 *
 * This destroys the key and isables its use in the system
 *
 * @return 0 if successful \n
 *   FOSA_EINVAL The key is not initialised or is not in FOSA key range.
 **/
int fosa_key_destroy(int key)
{
  int ret_value;

  // lock the mutex
  CHK(pthread_mutex_lock(&key_lock));

  // destroy the key and mark it as available
  ret_value=pthread_key_delete(key_list[key]);
  if (ret_value==0) {
    key_in_use[key]=false;
  }

  // unlock the mutex before returning
  CHK(pthread_mutex_unlock(&key_lock));
  return ret_value;
}


/**
 * fosa_thread_set_specific_data()
 *
 * Set thread-specific data
 *
 * For the thread identified by tid, the thread-specifid data field
 * identified by key will be set to the value specified by value
 *
 * Returns 0 if successful; otherwise, an error code is returned
 *     EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
 *
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
 int fosa_thread_set_specific_data
       (int key, frsh_thread_id_t tid, const void * value)
{
  return pthread_setspecific_for(key_list[key],tid,value);
}

/**
 * fosa_thread_get_specific_data()
 *
 * Get thread-specific data
 *
 * For the thread identified by tid, the thread-specifid data field
 * identified by key will be copied to the variable pointed to by value
 *
 * Returns 0 if successful; otherwise, an error code is returned
 *     EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
 *
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
int fosa_thread_get_specific_data(int key, frsh_thread_id_t tid, 
                                  void ** value)
{
  return pthread_getspecific_from(key_list[key],tid,value);
}


/******************************************************************
 * Thread scheduling
 * 
 * This implementation of FRSH assumes an underlying fixed priority
 * scheduler with priorities in a range, with a minimum and a
 * maximumm, a number of priority levels with at least 31
 * priorities. A larger number implies a larger priority. In systems
 * in which the underlying scheduler uses the opposite convention, a
 * mapping is automatically provided by the OS adaptation layer.
 *******************************************************************/

/**
 * fosa_get_priority_max()
 *
 * Return the maximum priority value used in this implementation
 **/
int fosa_get_priority_max()
{
  return sched_get_priority_max(SCHED_APP);
}

/**
 * fosa_get_priority_min()
 *
 * Return the minimum priority value used in this implementation
 **/
int fosa_get_priority_min()
{
  return sched_get_priority_min(SCHED_APP);
}

/**
 * fosa_thread_attr_set_prio()
 *
 * Change the priority of a thread attributes object
 *
 * The priority of the thread attriutes object specified by attr is
 * set to the value specified by prio. This function has no runtime
 * effect on the priority, except when the attributes object is used
 * to create a thread, when it will be created with the specified
 * priority
 * 
 * Returns 0 if successful, or the following error code:
 *    EINVAL: the specified priority value is not between the 
 *            minimum and the maximum priorities defined in this
 *            FRSH implementation
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
int fosa_thread_attr_set_prio(frsh_thread_attr_t *attr, int prio)
{
  struct sched_param param;

  param.sched_priority=prio;
  return pthread_attr_setschedparam(attr,&param);
}

/**
 * fosa_thread_attr_get_prio()
 *
 * Get the priority from a thread attributes object
 *
 * This function sets the variable pointed to by prio to the
 * priority stored in the thread attributes object attr.
 * 
 * Returns 0
 **/
int fosa_thread_attr_get_prio
          (const frsh_thread_attr_t *attr, int *prio)
{
  struct sched_param param;
  int ret_value;
  
  ret_value=pthread_attr_getschedparam(attr,&param);
  if (ret_value==0) {
    *prio=param.sched_priority;
  }
  return ret_value;
}

/**
 * fosa_thread_set_prio()
 *
 * Dynamically change the priority of a thread
 *
 * The priority of the thread identified by tid is
 * set to the value specified by prio. 
 * 
 * Returns 0 if successful, or the following error code:
 *    EINVAL: the specified priority value is not between the 
 *            minimum and the maximum priorities defined in this
 *            FRSH implementation
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
int fosa_thread_set_prio(frsh_thread_id_t tid, int prio)
{
  struct sched_param param;
  int policy, ret_value;

  ret_value=pthread_getschedparam(tid,&policy,&param);
  if (ret_value!=0) return ret_value;

  param.sched_priority=prio;
  return pthread_setschedparam(tid,policy,&param);
}

/**
 * fosa_thread_get_prio()
 *
 * Dynamically get the priority of a thread
 *
 * This function sets the variable pointed to by prio to the
 * priority of the thread identified by tid
 * 
 * Returns 0
 **/
int fosa_thread_get_prio (frsh_thread_id_t tid, int *prio)
{
  struct sched_param param;
  int policy, ret_value;

  ret_value=pthread_getschedparam(tid,&policy,&param);
  if (ret_value==0) {
    *prio=param.sched_priority;
  }
  return ret_value;
}



/*******************************************************************
 * Signals
 *
 * Signals represent events that may be notified by the system, or
 * sent explicitly by the application, and for which a thread may
 * synchronously wait. Signals carry an associated piece of
 * information (an integer or a pointer) and are queued until they are
 * accepted.  Signals are identified by an integer signal number (of
 * the type frsh_signal_t) in the range FOSA_SIGNAL_MIN,
 * FOSA_SIGNAL_MAX.  This range is required to have at least <tbd>
 * values.
 *******************************************************************/

/**
 * fosa_set_accepted_signals()
 *
 * Establish the set of signals that may be synchronously accepted 
 * by the calling thread
 *
 * The function uses the array of signal numbers specified by set,
 * which must be of size equal to size
 *
 * Returns 0 if successful; otherwise it returns an error code:
 *     EINVAL: the array contains one or more values which are not
 *             between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
 *             is less than 0
 *
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
int fosa_set_accepted_signals(frsh_signal_t set[], int size)
{
  sigset_t signalset;
  int i;
  struct sigaction act;

  // empty the signal set
  CHKE(sigemptyset(&signalset));

  // configure the signal action to make the signal a real-time
  //   signal that can be queued
  act.sa_handler=SIG_DFL;
  act.sa_mask=signalset;
  act.sa_flags=SA_SIGINFO;
  act.sa_sigaction=NULL;

    // loop for all signals in set
  for(i=0;i<size;i++) {
    CHKE(sigaddset(&signalset,set[i]));
    // Configure the signal so that it can be queued with data
    CHKE(sigaction(set[i],&act,NULL));
  } 
  return pthread_sigmask(SIG_BLOCK,&signalset,NULL);
}

/**
 * fosa_signal_queue()
 *
 * Queue a signal
 *
 * This function is used to explicitly send a signal with a specified
 * value
 * 
 * The signal number specified by signal is sent together with the
 * information specified by info, to the thread identified by
 * receiver. In those implementations that do not support queueing a
 * signal with information to a thread (such as POSIX), the signal may
 * be sent to any thread that is waiting for this signal via
 * fosa_signal_wait(). Portability can be ensured by having the receiver
 * thread be the one who is waiting for the signal. 
 *
 * Returns 0 if successful; otherwise it returns an error code:
 *     EINVAL: the signal specified by signal is not
 *              between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
 *
 *     EAGAIN: no resources are available to queue the signal; the
 *             maximum number of queued signals has been reached, or a
 *             systemwide resource limit has been exceeded
 *
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
int fosa_signal_queue
       (frsh_signal_t signal, frsh_signal_info_t info,
        frsh_thread_id_t receiver)
{
  // note: in MaRTE OS the signal is sent to any interested thread
  pid_t pid=1; // dummy value; the pid is ignored in MaRTE OS
  int err;
  err=sigqueue(pid,signal,*((union sigval *)(&info)));
  // the above casting construct is used to overcome the compiler
  // restriction that does not allow casts between unions
  if (err==0) {
    return 0;
  } else {
    return errno;
  }
}


/**
 * fosa_signal_wait()
 *
 * Wait for a signal
 * 
 * The function waits for the arrival of one of the signals in the
 * array of signal numbers specified by set, which must be of size
 * equal to size. If there is a signal already queued, the function
 * returns immediately. If there is no signal of the specified set
 * queued, the calling thread is suspended until a signal from that
 * set arrives. Upon return, if signal_received is not NULL the number
 * of the signal received is stored in the variable pointed to by
 * signal_received; and if info is not NULL the associated information
 * is stored in the variable pointed to by info.
 *
 * Returns 0 if successful; otherwise it returns an error code:
 *     EINVAL: the array contains one or more values which are not
 *             between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
 *             is less than 0
 *
 * Alternatively, in case of error the implementation is allowed to
 * notify it to the system console and then terminate the FRSH
 * implementation and dependant applications
 **/
int fosa_signal_wait
      (frsh_signal_t set[], int size, frsh_signal_t *signal_received, 
       frsh_signal_info_t *info)
{
  int err,i;
  sigset_t signalset;
  siginfo_t siginfo;

  CHKE(sigemptyset(&signalset));
  for(i=0;i<size;i++) {
    CHKE(sigaddset(&signalset,set[i]));
  } 

  err=sigwaitinfo(&signalset,&siginfo);
  if (err!=-1) {
    *signal_received=siginfo.si_signo;
    *info=*((frsh_signal_info_t *)(&siginfo.si_value));
    return 0;
  } else {
    return errno;
  }
}

/**
 * fosa_signal_timedwait()
 *
 * Timed wait for a signal
 * 
 * This function behaves the same as fosa_signal_wait(), except that
 * the suspension time is limited to the time interval specified in
 * the timespec structure referenced by timeout.
 * 
 * Returns 0 if successful; otherwise it returns an error code:
 *     EINVAL: the array contains one or more values which are not
 *             between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
 *             is less than 0, or timeout is invalid
 *     EAGAIN: The timeout expired
 *
 * Alternatively, in case of the EINVAL error the implementation is
 * allowed to notify it to the system console and then terminate the
 * FRSH implementation and dependant applications
 **/
 int fosa_signal_timedwait
      (frsh_signal_t set[], int size, frsh_signal_t *signal_received, 
       frsh_signal_info_t *info, const struct timespec *timeout)
{

  // the implementation of sigtimedwait is not yet available in MaRTE OS
  return ENOSYS;

/*   int err,i; */
/*   sigset_t signalset; */
/*   siginfo_t siginfo; */

/*   CHKE(sigemptyset(&signalset)); */
/*   for(i=0;i<size;i++) { */
/*     CHKE(sigaddset(&signalset,set[i])); */
/*   }  */

/*   err=sigtimedwait(&signalset,&siginfo,timeout); */
/*   if (err==0) { */
/*     *signal_received=siginfo.si_signo; */
/*     *info=siginfo.si_value; */
/*     return 0; */
/*   } else { */
/*     return errno; */
/*   } */
}