Subversion Repositories shark

/*
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program 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 this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

/**
   @file Shared Objects
 */

//fsf_shared_objects.h
//==================================================
//       FFFFFFIII   RRRRR      SSTTTTTTT
//      FF         IIR   RR    SS
//     FF           IR        SS
//    FFFFFF         RRRR    SSSSST
//   FF       FI       RRR  SS
//  FF         II     RRR  SS
// FF           IIIIIR    RS
//
// FSF(FIRST Scheduling Framework)
// shared objects functionality
//====================================================

#include <pthread.h>
#include "fsf_basic_types.h"
#include "fsf_core.h"

#ifndef _FSF_SHARED_OBJECTS_H_
#define _FSF_SHARED_OBJECTS_H_

#define FSF_SHARED_OBJECTS_MODULE_SUPPORTED       1


// These constants are defined in the fsf_configuration_parameters.h
// file:

//#define FSF_MAX_N_SHARED_OBJECTS    100
//#define FSF_MAX_N_CRITICAL_SECTIONS 20


//// The definition of this types is in fsf_basic_types.h
//
//// Shared object identifier (null character terminated string)
//typedef char  * fsf_shared_obj_id_t;    
//
//// Shared object handle (opaque type)
//typedef FSF_SHARED_OBJ_HANDLE_T_OPAQUE  fsf_shared_obj_handle_t;
//
//// Critical section data
//typedef struct {
//   fsf_shared_obj_handle_t obj_handle;
//   struct timespec         wcet;  //Execution time
//} fsf_critical_section_data_t;
//
//// List of critical sections
//typedef struct {
//  int size; // = 0
//  fsf_critical_section_data_t  
//      section[FSF_MAX_N_CRITICAL_SECTIONS];
//} fsf_critical_sections_t;
//

/////////////////////////////////////////////////////
//           SHARED OBJECTS & OPERATIONS MANAGEMENT
/////////////////////////////////////////////////////

/**
   \ingroup shobjmodule

   Initialization of shared objects. If the object identified by
   obj_id does not yet exist it is created, a handle to the object is
   returned in the variable pointed to by obj_handle, and the
   specified mutex is initialized with the appropriate attributes
   necessary for the current implementation.  If the object already
   exists, the function fails.

   @param [in] obj_id shared object id
   @param [out] obj_handle pointer to a shared object handle
   @param [out] mutex pointer to a mutex variable

   @retval 0 if the operation is succesful
   @retval FSF_ERR_BAD_ARGUMENT if obj_id, obj_handle, or mutex are NULL
   @retval FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED if the object identified
       by obj_id already exists
   @retval others It may also return any of the error codes that are
       returned by the pthread_mutex_init() POSIX function call
*/
int fsf_init_shared_object
   (fsf_shared_obj_id_t      obj_id,
    fsf_shared_obj_handle_t *obj_handle,
    pthread_mutex_t         *mutex);


/**
   \ingroup shobjmodule

   Getting the handle of shared
   objects. If the object already exists a handle to the object is
   returned in the variable pointed to by obj_handle. Otherwise, an
   error code is returned by the function.

   @param [in] obj_id shared object id
   @param [out] obj_handle pointer to a shared object handle

   @retval 0 if the operation is succesful
   @retval FSF_ERR_BAD_ARGUMENT if obj_id or obj_handle are NULL
   @retval FSF_ERR_SHARED_OBJ_NOT_INITIALIZED if the shared object identified
       by obj_id does not exist
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
       running
   @retval FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling
       thread has been cancelled or it is not valid
*/
int fsf_get_shared_object_handle
   (fsf_shared_obj_id_t      obj_id,
    fsf_shared_obj_handle_t *obj_handle);

/**
   \ingroup shobjmodule
   
   Getting the mutex of shared objects. If the object exists, a
   pointer to its associated mutex is returned in the variable pointed
   to by mutex. Otherwise, an error code is returned by the function.

   @param [in] obj_handle  shared object handle
   @param [out] mutex pointer to a pointer to a mutex variable,
        (remember that the function give back a pointer to a mutex!)

   @retval 0 if the operation is succesful
   @retval FSF_ERR_BAD_ARGUMENT if obj_handle or mutex are NULL  or obj_handle
       is not correct or reference a wrong shared object
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
       running
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
       has been cancelled or it is not valid
*/
int fsf_get_shared_object_mutex
   (fsf_shared_obj_handle_t  obj_handle,
    pthread_mutex_t          **mutex);


/////////////////////////////////////////////////////
//                       CONTRACT PARAMETERS
/////////////////////////////////////////////////////

/**
   \ingroup shobjmodule
   
   The operation updates the specified contract parameters object by
   setting its critical sections to the specified input parameter.


   @param[in] contract the service contract
   @param[in] critical_sections list of critical sections accessed by tasks
       belonging to the contract

   @retval 0 if the operation is succesful
   @retval FSF_ERR_BAD_ARGUMENT :if any of the pointers is NULL or
       the size of the critical_sections structure is less than zero
       or grater than FSF_MAX_N_CRITICAL_SECTIONS
*/
int
fsf_set_contract_synchronization_parameters
  (fsf_contract_parameters_t     *contract,
   const fsf_critical_sections_t *critical_sections);


/**
   \ingroup shobjmodule

   The operation obtains from the specified contract parameters object
   its critical sections, and copies them to the places pointed to by
   the specified input parameter.  Only those critical_section_data
   records that are in use in the critical_sections structure are
   copied (according to its size field).

   @param[in] contract pointer to a contract
   @param[out] critical_sections list of critical sections to be filled

   @retval 0 if the operation is succesful
   @retval FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL
*/
int
fsf_get_contract_synchronization_parameters
  (const fsf_contract_parameters_t *contract,
   fsf_critical_sections_t         *critical_sections);


#endif // _FSF_SHARED_OBJECTS_H_