frsh_fosa.h

   1 // -----------------------------------------------------------------------
   2 //   Copyright (C) 2005  Mälardalen University, SWEDEN
   3 //                       Scuola Superiore S.Anna, ITALY
   4 //                       Universidad de Cantabria, SPAIN
   5 //                       University of York, UK
   6 //
   7 //   FRSH API web pages: http://marte.unican.es/frsh/docs/
   8 //                      http://shark.sssup.it/contrib/first/docs/
   9 //
  10 //  This file is part of FRSH API
  11 //
  12 //  FRSH API is free software; you can  redistribute it and/or  modify
  13 //  it under the terms of  the GNU General Public License as published by
  14 //  the Free Software Foundation;  either  version 2, or (at  your option)
  15 //  any later version.
  16 //
  17 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  18 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  19 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  20 //  General Public License for more details.
  21 //
  22 //  You should have  received a  copy of  the  GNU  General Public License
  23 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  24 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  25 //  02111-1307, USA.
  26 //
  27 //  As a special exception, if you include this header file into source
  28 //  files to be compiled, this header file does not by itself cause
  29 //  the resulting executable to be covered by the GNU General Public
  30 //  License.  This exception does not however invalidate any other
  31 //  reasons why the executable file might be covered by the GNU General
  32 //  Public License.
  33 // -----------------------------------------------------------------------
  34 // frsh_fosa.h
  35 //========================================================================================
  36 //  ******** *******    ********  **      **    ********  ******    ********  **********
  37 //  **///// /**////**  **//////  /**     /**    **///// /**    **  **//////  /**     /**
  38 //  **      /**   /** /**        /**     /**    **      /**    ** /**        /**     /**
  39 //  ******* /*******  /********* /**********    ******* /**    ** /********* /**********
  40 //  **////  /**///**  ////////** /**//////**    **////  /**    ** ////////** /**//////**
  41 //  **      /**  //**        /** /**     /**    **      /**    **        /** /**     /**
  42 //  **      /**   //** ********  /**     /**    **      /**    **  ********  /**     /**
  43 //  //       //     // ////////   //      //    //       /******/  ////////   //      //
  44 //
  45 // FRSH(FRescor ScHeduler), pronounced "fresh" FOSA(Frescor Oper System Adaptation layer)
  46 //========================================================================================
  47 #ifndef         FRSH_FOSA_H_
  48 #define         FRSH_FOSA_H_
  49
  50 #include "frsh_fosa_opaque.h"
  51
  52 /**
  53  * @file frsh_fosa.h
  54  **/
  55
  56
  57 /**
  58  * @defgroup frshfosa FRSH FOSA public interfaces
  59  *
  60  * FOSA is an OS adaption layer that encapsulates all POSIX types and
  61  * functions into neutral names so that FRSH can compile and be used in
  62  * non-POSIX operating systems such as OSE.
  63  *
  64  * It is divided in two parts:
  65  *  - FRSH_FOSA:  Types visibles to the application via FRSH_API
  66  *                (thread, signal, mutexes).
  67  *  - FOSA:  Types and functions only used within FRSH.
  68  *
  69  * The former reside in the FRSH subversion directory and the latter
  70  * have their own.  They need to be separated because the application
  71  * must not see FOSA itself.
  72  *
  73  * For simplicity, we have chosen to hide the operation function on
  74  * signals and mutexes with the assumption that a direct mapping
  75  * exists for frsh_signal_t, frsh_signal_info_t and frsh_mutext_t in
  76  * the native OS.
  77  *
  78  * Since there are some parts which are platform dependent a define
  79  * has been introduced for each platform.  Currently the supported
  80  * defines are:
  81  *
  82  *         -DRT_LINUX
  83  *         -DOSE
  84  *         -DMARTE_OS
  85  *         -DAQuoSA
  86  *                 -DVIRTUAL_TIME
  87  *
  88  * This module contains the FOSA part exposed by the FRSH_API and
  89  * visible for the application.
  90  *
  91  * On the other hand, there was another file in the API which was also
  92  * OS-dependent:  frsh_os_compatibility.h.  However this dependency
  93  * relates more to the implementation of FRSH and therefore it has
  94  * been moved to the src directory.   It may be integrated in FOSA
  95  * during the implementation.
  96  *
  97  * @{
  98  **/
  99
 100 /**
 101  * Bool as a byte value (char)
 102  *
 103  * We will revisit this if we have a problem with bool in C++
 104  **/
 105
 106
 107 /** identifier of a frsh thread **/
 108 typedef FOSA_THREAD_ID_T_OPAQUE frsh_thread_id_t;
 109
 110
 111 /** thread attributes object **/
 112 typedef FOSA_THREAD_ATTR_T_OPAQUE frsh_thread_attr_t;
 113
 114 /**
 115  *  The type references a function that may become a thread's
 116  *  code
 117  **/
 118 typedef void * (*frsh_thread_code_t) (void *);
 119
 120
 121 /** signal number; it is an integer type **/
 122 typedef FOSA_SIGNAL_T_OPAQUE frsh_signal_t;
 123 #define FRSH_NULL_SIGNAL       FOSA_NULL_SIGNAL
 124
 125
 126 #define FRSH_SIGNAL_MIN       FOSA_SIGNAL_MIN
 127 #define FRSH_SIGNAL_MAX       FOSA_SIGNAL_MAX
 128
 129
 130
 131 /** information associated to a signal **/
 132 #if defined(VIRTUAL_TIME)
 133
 134 #include <vt_ose.h>
 135 typedef vt_posix_signal_info_t frsh_signal_info_t;
 136
 137 #else
 138
 139 typedef union {int sival_int; void * sival_ptr; } frsh_signal_info_t;
 140 /* typedef FRSH_SIGNAL_INFO_T_OPAQUE frsh_signal_info_t; */
 141
 142 #endif
 143
 144
 145
 146
 147 /** Mutex object.  Attributes are handled by FOSA **/
 148 typedef FOSA_MUTEX_T_OPAQUE frsh_mutex_t;
 149
 150
 151
 152 /*************************
 153  * Thread attributes
 154  *************************/
 155
 156 /**
 157  * frsh_thread_attr_init()
 158  *
 159  * Initialize a thread attributes object
 160  *
 161  * This function initializes the object pointed to by attr to all
 162  * the default values defined by FRSH
 163  *
 164  * @return 0 if successful; otherwise it returns \n
 165  *   FOSA_ENOMEM: insufficient memory exists to initialize the thread
 166  *           attributes object
 167  **/
 168 int frsh_thread_attr_init(frsh_thread_attr_t *attr);
 169
 170 /**
 171  * frsh_thread_attr_destroy()
 172  *
 173  * Destroy a thread attributes object
 174  *
 175  * This function is used to destroy the thread attributes object,
 176  * pointed to by attr, and deallocate any system resources allocated for it
 177  *
 178  * Returns 0
 179  */
 180 int frsh_thread_attr_destroy(frsh_thread_attr_t *attr);
 181
 182 /**
 183  * frsh_thread_attr_set_stacksize()
 184  *
 185  * Set the thread minimum stack size in a thread attributes object
 186  *
 187  * This function sets the minimum stack size of the thread attributes
 188  * object attr to the value given by stacksize, in bytes. This
 189  * function has no runtime effect on the stack size, except when the
 190  * attributes object is used to create a thread, when it will be
 191  * created with the specified minimum stack size
 192  *
 193  * @return 0 if successful, or the following error code:
 194  *    FOSA_EINVAL: the specified stacksize  value is not supported in
 195  *            this implementation
 196  */
 197 int frsh_thread_attr_set_stacksize(frsh_thread_attr_t *attr, size_t stacksize);
 198
 199 /**
 200  * frsh_thread_attr_get_stacksize()
 201  *
 202  * Get the thread minimum stack size from a thread attributes object
 203  *
 204  * This function sets the variable pointed to by stacksize to the
 205  * minimum stack size stored in the thread attributes object attr.
 206  *
 207  * @return 0
 208  */
 209 int frsh_thread_attr_get_stacksize
 210       (const frsh_thread_attr_t *attr, size_t *stacksize);
 211
 212 /*@}*/
 213
 214
 215 #endif      /* !FRSH_ADAPTION_H_ */