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 <stdlib.h> /* For size_t */
  51 #include "frsh_fosa_opaque.h"
  52
  53 /**
  54  * @file frsh_fosa.h
  55  **/
  56
  57
  58 /**
  59  * @defgroup frshfosa FRSH FOSA public interfaces
  60  *
  61  * FOSA is an OS adaption layer that encapsulates all POSIX types and
  62  * functions into neutral names so that FRSH can compile and be used in
  63  * non-POSIX operating systems such as OSE.
  64  *
  65  * It is divided in two parts:
  66  *  - FRSH_FOSA:  Types visibles to the application via FRSH_API
  67  *                (thread, signal, mutexes).
  68  *  - FOSA:  Types and functions only used within FRSH.
  69  *
  70  * The former reside in the FRSH subversion directory and the latter
  71  * have their own.  They need to be separated because the application
  72  * must not see FOSA itself.
  73  *
  74  * For simplicity, we have chosen to hide the operation function on
  75  * signals and mutexes with the assumption that a direct mapping
  76  * exists for frsh_signal_t, frsh_signal_info_t and frsh_mutext_t in
  77  * the native OS.
  78  *
  79  * Since there are some parts which are platform dependent a define
  80  * has been introduced for each platform.  Currently the supported
  81  * defines are:
  82  *
  83  *         -DRT_LINUX
  84  *         -DOSE
  85  *         -DMARTE_OS
  86  *         -DAQuoSA
  87  *                 -DVIRTUAL_TIME
  88  *
  89  * This module contains the FOSA part exposed by the FRSH_API and
  90  * visible for the application.
  91  *
  92  * On the other hand, there was another file in the API which was also
  93  * OS-dependent:  frsh_os_compatibility.h.  However this dependency
  94  * relates more to the implementation of FRSH and therefore it has
  95  * been moved to the src directory.   It may be integrated in FOSA
  96  * during the implementation.
  97  *
  98  * @{
  99  **/
 100
 101 /**
 102  * Bool as a byte value (char)
 103  *
 104  * We will revisit this if we have a problem with bool in C++
 105  **/
 106
 107
 108 /** identifier of a frsh thread **/
 109 typedef FOSA_THREAD_ID_T_OPAQUE frsh_thread_id_t;
 110
 111
 112 /** thread attributes object **/
 113 typedef FOSA_THREAD_ATTR_T_OPAQUE frsh_thread_attr_t;
 114
 115 /**
 116  *  The type references a function that may become a thread's
 117  *  code
 118  **/
 119 typedef void * (*frsh_thread_code_t) (void *);
 120
 121
 122 /** signal number; it is an integer type **/
 123 typedef FOSA_SIGNAL_T_OPAQUE frsh_signal_t;
 124 #define FRSH_NULL_SIGNAL       FOSA_NULL_SIGNAL
 125
 126
 127 #define FRSH_SIGNAL_MIN       FOSA_SIGNAL_MIN
 128 #define FRSH_SIGNAL_MAX       FOSA_SIGNAL_MAX
 129
 130
 131
 132 /** information associated to a signal **/
 133 #if defined(VIRTUAL_TIME)
 134
 135 #include <vt_ose.h>
 136 typedef vt_posix_signal_info_t frsh_signal_info_t;
 137
 138 #else
 139
 140 typedef union {int sival_int; void * sival_ptr; } frsh_signal_info_t;
 141 /* typedef FRSH_SIGNAL_INFO_T_OPAQUE frsh_signal_info_t; */
 142
 143 #endif
 144
 145
 146
 147
 148 /** Mutex object.  Attributes are handled by FOSA **/
 149 typedef FOSA_MUTEX_T_OPAQUE frsh_mutex_t;
 150
 151
 152
 153 /*************************
 154  * Thread attributes
 155  *************************/
 156
 157 /**
 158  * frsh_thread_attr_init()
 159  *
 160  * Initialize a thread attributes object
 161  *
 162  * This function initializes the object pointed to by attr to all
 163  * the default values defined by FRSH
 164  *
 165  * @return 0 if successful; otherwise it returns \n
 166  *   FOSA_ENOMEM: insufficient memory exists to initialize the thread
 167  *           attributes object
 168  **/
 169 int frsh_thread_attr_init(frsh_thread_attr_t *attr);
 170
 171 /**
 172  * frsh_thread_attr_destroy()
 173  *
 174  * Destroy a thread attributes object
 175  *
 176  * This function is used to destroy the thread attributes object,
 177  * pointed to by attr, and deallocate any system resources allocated for it
 178  *
 179  * Returns 0
 180  */
 181 int frsh_thread_attr_destroy(frsh_thread_attr_t *attr);
 182
 183 /**
 184  * frsh_thread_attr_set_stacksize()
 185  *
 186  * Set the thread minimum stack size in a thread attributes object
 187  *
 188  * This function sets the minimum stack size of the thread attributes
 189  * object attr to the value given by stacksize, in bytes. This
 190  * function has no runtime effect on the stack size, except when the
 191  * attributes object is used to create a thread, when it will be
 192  * created with the specified minimum stack size
 193  *
 194  * @return 0 if successful, or the following error code:
 195  *    FOSA_EINVAL: the specified stacksize  value is not supported in
 196  *            this implementation
 197  */
 198 int frsh_thread_attr_set_stacksize(frsh_thread_attr_t *attr, size_t stacksize);
 199
 200 /**
 201  * frsh_thread_attr_get_stacksize()
 202  *
 203  * Get the thread minimum stack size from a thread attributes object
 204  *
 205  * This function sets the variable pointed to by stacksize to the
 206  * minimum stack size stored in the thread attributes object attr.
 207  *
 208  * @return 0
 209  */
 210 int frsh_thread_attr_get_stacksize
 211       (const frsh_thread_attr_t *attr, size_t *stacksize);
 212
 213 /*@}*/
 214
 215
 216 #endif      /* !FRSH_ADAPTION_H_ */