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  *
  86  * This module contains the FOSA part exposed by the FRSH_API and
  87  * visible for the application.
  88  *
  89  * On the other hand, there was another file in the API which was also
  90  * OS-dependent:  frsh_os_compatibility.h.  However this dependency
  91  * relates more to the implementation of FRSH and therefore it has
  92  * been moved to the src directory.   It may be integrated in FOSA
  93  * during the implementation.
  94  *
  95  * @{
  96  **/
  97
  98
  99
 100 /** identifier of a frsh thread **/
 101 typedef FOSA_THREAD_ID_T_OPAQUE frsh_thread_id_t;
 102
 103
 104 /** thread attributes object **/
 105 typedef FOSA_THREAD_ATTR_T_OPAQUE frsh_thread_attr_t;
 106
 107 /**
 108  *  The type references a function that may become a thread's
 109  *  code
 110  **/
 111 typedef void * (*frsh_thread_code_t) (void *);
 112
 113
 114 /** signal number; it is an integer type **/
 115 typedef FOSA_SIGNAL_T_OPAQUE frsh_signal_t;
 116 #define FRSH_NULL_SIGNAL       FOSA_NULL_SIGNAL
 117
 118
 119 #define FRSH_SIGNAL_MIN       FOSA_SIGNAL_MIN
 120 #define FRSH_SIGNAL_MAX       FOSA_SIGNAL_MAX
 121
 122
 123
 124 /** information associated to a signal **/
 125 typedef union {int value; void * area; } frsh_signal_info_t;
 126
 127 /** Mutex object.  Attributes are handled by FOSA **/
 128 typedef FOSA_MUTEX_T_OPAQUE frsh_mutex_t;
 129
 130
 131
 132 /*************************
 133  * Thread attributes
 134  *************************/
 135
 136 /**
 137  * frsh_thread_attr_init()
 138  *
 139  * Initialize a thread attributes object
 140  *
 141  * This function initializes the object pointed to by attr to all
 142  * the default values defined by FRSH
 143  *
 144  * @return 0 if successful; otherwise it returns \n
 145  *   FOSA_ENOMEM: insufficient memory exists to initialize the thread
 146  *           attributes object
 147  **/
 148 int frsh_thread_attr_init(frsh_thread_attr_t *attr);
 149
 150 /**
 151  * frsh_thread_attr_destroy()
 152  *
 153  * Destroy a thread attributes object
 154  *
 155  * This function is used to destroy the thread attributes object,
 156  * pointed to by attr, and deallocate any system resources allocated for it
 157  *
 158  * Returns 0
 159  */
 160 int frsh_thread_attr_destroy(frsh_thread_attr_t *attr);
 161
 162 /**
 163  * frsh_thread_attr_set_stacksize()
 164  *
 165  * Set the thread minimum stack size in a thread attributes object
 166  *
 167  * This function sets the minimum stack size of the thread attributes
 168  * object attr to the value given by stacksize, in bytes. This
 169  * function has no runtime effect on the stack size, except when the
 170  * attributes object is used to create a thread, when it will be
 171  * created with the specified minimum stack size
 172  *
 173  * @return 0 if successful, or the following error code:
 174  *    FOSA_EINVAL: the specified stacksize  value is not supported in
 175  *            this implementation
 176  */
 177 int frsh_thread_attr_set_stacksize(frsh_thread_attr_t *attr, size_t stacksize);
 178
 179 /**
 180  * frsh_thread_attr_get_stacksize()
 181  *
 182  * Get the thread minimum stack size from a thread attributes object
 183  *
 184  * This function sets the variable pointed to by stacksize to the
 185  * minimum stack size stored in the thread attributes object attr.
 186  *
 187  * @return 0
 188  */
 189 int frsh_thread_attr_get_stacksize
 190       (const frsh_thread_attr_t *attr, size_t *stacksize);
 191
 192 /*@}*/
 193
 194
 195 #endif      /* !FRSH_ADAPTION_H_ */