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
7 // FRSH API web pages: http://marte.unican.es/frsh/docs/
8 // http://shark.sssup.it/contrib/first/docs/
10 // This file is part of FRSH API
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)
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.
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
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
33 // -----------------------------------------------------------------------
35 //========================================================================================
36 // ******** ******* ******** ** ** ******** ****** ******** **********
37 // **///// /**////** **////// /** /** **///// /** ** **////// /** /**
38 // ** /** /** /** /** /** ** /** ** /** /** /**
39 // ******* /******* /********* /********** ******* /** ** /********* /**********
40 // **//// /**///** ////////** /**//////** **//// /** ** ////////** /**//////**
41 // ** /** //** /** /** /** ** /** ** /** /** /**
42 // ** /** //** ******** /** /** ** /** ** ******** /** /**
43 // // // // //////// // // // /******/ //////// // //
45 // FRSH(FRescor ScHeduler), pronounced "fresh" FOSA(Frescor Oper System Adaptation layer)
46 //========================================================================================
50 #include <stdlib.h> /* For size_t */
51 #include "frsh_fosa_opaque.h"
59 * @defgroup frshfosa FRSH FOSA public interfaces
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.
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.
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.
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
79 * Since there are some parts which are platform dependent a define
80 * has been introduced for each platform. Currently the supported
89 * This module contains the FOSA part exposed by the FRSH_API and
90 * visible for the application.
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.
102 * Bool as a byte value (char)
104 * We will revisit this if we have a problem with bool in C++
108 /** identifier of a frsh thread **/
109 typedef FOSA_THREAD_ID_T_OPAQUE frsh_thread_id_t;
112 /** thread attributes object **/
113 typedef FOSA_THREAD_ATTR_T_OPAQUE frsh_thread_attr_t;
116 * The type references a function that may become a thread's
119 typedef void * (*frsh_thread_code_t) (void *);
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
127 #define FRSH_SIGNAL_MIN FOSA_SIGNAL_MIN
128 #define FRSH_SIGNAL_MAX FOSA_SIGNAL_MAX
132 /** information associated to a signal **/
133 #if defined(VIRTUAL_TIME)
136 typedef vt_posix_signal_info_t frsh_signal_info_t;
140 typedef union {int sival_int; void * sival_ptr; } frsh_signal_info_t;
141 /* typedef FRSH_SIGNAL_INFO_T_OPAQUE frsh_signal_info_t; */
148 /** Mutex object. Attributes are handled by FOSA **/
149 typedef FOSA_MUTEX_T_OPAQUE frsh_mutex_t;
153 /*************************
155 *************************/
158 * frsh_thread_attr_init()
160 * Initialize a thread attributes object
162 * This function initializes the object pointed to by attr to all
163 * the default values defined by FRSH
165 * @return 0 if successful; otherwise it returns \n
166 * FOSA_ENOMEM: insufficient memory exists to initialize the thread
169 int frsh_thread_attr_init(frsh_thread_attr_t *attr);
172 * frsh_thread_attr_destroy()
174 * Destroy a thread attributes object
176 * This function is used to destroy the thread attributes object,
177 * pointed to by attr, and deallocate any system resources allocated for it
181 int frsh_thread_attr_destroy(frsh_thread_attr_t *attr);
184 * frsh_thread_attr_set_stacksize()
186 * Set the thread minimum stack size in a thread attributes object
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
194 * @return 0 if successful, or the following error code:
195 * FOSA_EINVAL: the specified stacksize value is not supported in
196 * this implementation
198 int frsh_thread_attr_set_stacksize(frsh_thread_attr_t *attr, size_t stacksize);
201 * frsh_thread_attr_get_stacksize()
203 * Get the thread minimum stack size from a thread attributes object
205 * This function sets the variable pointed to by stacksize to the
206 * minimum stack size stored in the thread attributes object attr.
210 int frsh_thread_attr_get_stacksize
211 (const frsh_thread_attr_t *attr, size_t *stacksize);
216 #endif /* !FRSH_ADAPTION_H_ */