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 "frsh_fosa_opaque.h"
58 * @defgroup frshfosa FRSH FOSA public interfaces
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.
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.
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.
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
78 * Since there are some parts which are platform dependent a define
79 * has been introduced for each platform. Currently the supported
86 * This module contains the FOSA part exposed by the FRSH_API and
87 * visible for the application.
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.
99 * Bool as a byte value (char)
101 * We will revisit this if we have a problem with bool in C++
109 /** identifier of a frsh thread **/
110 typedef FOSA_THREAD_ID_T_OPAQUE frsh_thread_id_t;
113 /** thread attributes object **/
114 typedef FOSA_THREAD_ATTR_T_OPAQUE frsh_thread_attr_t;
117 * The type references a function that may become a thread's
120 typedef void * (*frsh_thread_code_t) (void *);
123 /** signal number; it is an integer type **/
124 typedef FOSA_SIGNAL_T_OPAQUE frsh_signal_t;
125 #define FRSH_NULL_SIGNAL FOSA_NULL_SIGNAL
128 #define FRSH_SIGNAL_MIN FOSA_SIGNAL_MIN
129 #define FRSH_SIGNAL_MAX FOSA_SIGNAL_MAX
133 /** information associated to a signal **/
134 typedef union {int value; void * area; } frsh_signal_info_t;
135 /* typedef FRSH_SIGNAL_INFO_T_OPAQUE frsh_signal_info_t; */
139 /** Mutex object. Attributes are handled by FOSA **/
140 typedef FOSA_MUTEX_T_OPAQUE frsh_mutex_t;
144 /*************************
146 *************************/
149 * frsh_thread_attr_init()
151 * Initialize a thread attributes object
153 * This function initializes the object pointed to by attr to all
154 * the default values defined by FRSH
156 * @return 0 if successful; otherwise it returns \n
157 * FOSA_ENOMEM: insufficient memory exists to initialize the thread
160 int frsh_thread_attr_init(frsh_thread_attr_t *attr);
163 * frsh_thread_attr_destroy()
165 * Destroy a thread attributes object
167 * This function is used to destroy the thread attributes object,
168 * pointed to by attr, and deallocate any system resources allocated for it
172 int frsh_thread_attr_destroy(frsh_thread_attr_t *attr);
175 * frsh_thread_attr_set_stacksize()
177 * Set the thread minimum stack size in a thread attributes object
179 * This function sets the minimum stack size of the thread attributes
180 * object attr to the value given by stacksize, in bytes. This
181 * function has no runtime effect on the stack size, except when the
182 * attributes object is used to create a thread, when it will be
183 * created with the specified minimum stack size
185 * @return 0 if successful, or the following error code:
186 * FOSA_EINVAL: the specified stacksize value is not supported in
187 * this implementation
189 int frsh_thread_attr_set_stacksize(frsh_thread_attr_t *attr, size_t stacksize);
192 * frsh_thread_attr_get_stacksize()
194 * Get the thread minimum stack size from a thread attributes object
196 * This function sets the variable pointed to by stacksize to the
197 * minimum stack size stored in the thread attributes object attr.
201 int frsh_thread_attr_get_stacksize
202 (const frsh_thread_attr_t *attr, size_t *stacksize);
207 #endif /* !FRSH_ADAPTION_H_ */