1 //----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 by the FRESCOR consortium:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politecnica Valencia, SPAIN
9 // Czech Technical University in Prague, CZECH REPUBLIC
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org
18 // The FRESCOR project (FP6/2005/IST/5-034026) is funded
19 // in part by the European Union Sixth Framework Programme
20 // The European Union is not liable of any use that may be
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // This file is part of FOSA (Frsh Operating System Abstraction)
33 // FOSA is free software; you can redistribute it and/or modify it
34 // under terms of the GNU General Public License as published by the
35 // Free Software Foundation; either version 2, or (at your option) any
36 // later version. FOSA is distributed in the hope that it will be
37 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
38 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
39 // General Public License for more details. You should have received a
40 // copy of the GNU General Public License along with FOSA; see file
41 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
42 // Cambridge, MA 02139, USA.
44 // As a special exception, including FOSA header files in a file,
45 // instantiating FOSA generics or templates, or linking other files
46 // with FOSA objects to produce an executable application, does not
47 // by itself cause the resulting executable application to be covered
48 // by the GNU General Public License. This exception does not
49 // however invalidate any other reasons why the executable file might be
50 // covered by the GNU Public License.
51 // -----------------------------------------------------------------------
53 //==============================================
54 // ******** ****** ******** **********
55 // **///// /** ** **////// /** /**
56 // ** /** ** /** /** /**
57 // ******* /** ** /********* /**********
58 // **//// /** ** ////////** /**//////**
59 // ** /** ** /** /** /**
60 // ** /** ** ******** /** /**
61 // // /******/ //////// // //
63 // FOSA(Frescor Operating System Adaptation layer)
64 //================================================
67 #ifndef _FOSA_TYPES_H_
68 #define _FOSA_TYPES_H_
70 #include "fosa_opaque_types.h"
71 #include "frsh_fosa.h"
73 * @addtogroup clocksandtimers
77 // identifier of a clock
78 // either a real-time clock or a cpu-time clock
79 typedef FOSA_CLOCK_ID_T_OPAQUE fosa_clock_id_t;
81 #define FOSA_SYSTEM_CLOCK FOSA_SYSTEM_CLOCK_OPAQUE
83 // identifier of a one-shot timer
84 typedef FOSA_TIMER_ID_T_OPAQUE fosa_timer_id_t;
89 * @addtrogroup mutexesandcondvars
93 // a condition variable
94 typedef FOSA_COND_T_OPAQUE fosa_cond_t;
98 * @addtogroup appdefsched
110 * This type is used to represent a list of scheduling actions that the
111 * scheduler will later request to be executed by the system. The pos-
112 * sible actions are of the following kinds:
113 * - reject a thread that has requested attachment to this scheduler
114 * - activate an application-scheduled thread with the desired value
116 * - suspend an application-scheduled thread
117 * - program a timeout
118 * - program a timed notification associated to a particular
119 * application-scheduled thread.
121 * No comparison or assignment operators are defined for this type
123 typedef FOSA_ADS_ACTIONS_T_OPAQUE fosa_ads_actions_t;
125 /* FOSA_ADS_ACTIONS_T_OPAQUE */
128 * Causes of error in the appsched_error primitive operation
130 typedef enum {FOSA_ADS_THREAD_NOT_ATTACHED, FOSA_ADS_INVALID_ACTION}
131 fosa_ads_error_cause_t;
135 * The urgency used to orde the threads of the same priority in the
136 * underlying scheduler. Support for urgency scheduling is required
137 * for supporting the hierarchhical scheduling module
139 typedef int fosa_ads_urgency_t;
143 * Scheduler primitive operations
145 * This structure is used to create application schedulers. It
146 * contains pointers to the primitive operations that are invoked by
147 * the system when a scheduling event occurs:
149 * - The \b init() primitive operation is invoked by the system just after
150 * the scheduler has been created using fosa_ads_scheduler_create().
152 * - The \b new_thread() primitive operation is invoked by the system when
153 * a thread has requested attachment to this scheduler; this can be a
154 * newly created thread (via fosa_thread_create()), or an existing thread
155 * that was not running under ads scheduler (via
156 * fosa_ads_set_appscheduled()).\n \n
158 * The thread can be rejected by the scheduler adding a
159 * reject-thread action to the actions parameter using
160 * fosa_ads_actions_add_reject(). If no reject-thread action is
161 * added, the thread is accepted.\n \n
163 * Newly created threads shall be activated by the system after the
164 * execution of the new_thread() primitive operation. The urgency of
165 * an accepted thread (either newly created or existing) shall be set
166 * to a value of zero, unless an activate-thread action with a
167 * different value of urgency is added via
168 * fosa_ads_actions_add_activate().\n \n
170 * If a request to attach a thread to this scheduler was made via
171 * fosa_ads_set_appscheduled(), at the finalization of the new_thread()
172 * primitive operation if the newly attached thread is blocked by the
173 * system (not by the scheduler itself via a suspend scheduling
174 * action), a thread-block event shall be generated for the scheduler
175 * immediately and, consequently, the thread_block() primitive
176 * operation shall be invoked by the system.
178 * - The \b thread_terminate() primitive operation is invoked by the system
179 * when a thread attached to this scheduler is terminating (via an
180 * explicit or implicit thread termination, or cancellation, or when
181 * it is no longer sceduled by the ads scheduler (via
182 * fosa_ads_setappscheduled()). \n\n
184 * Before the thread_terminate() primitive operation is invoked by
185 * the system, all the thread-notification events programmed for that
186 * thread are cancelled. \n\n
188 * In the case of a thread that is terminating, the
189 * thread_terminate() primitive operation is executed before the
190 * execution of the cleanup handlers and of the thread-specific data
191 * destructor functions. In that way, the thread parameter corresponds
192 * to a valid thread Id and the thread-specific data is valid and can
193 * be accessed from the thread_terminate() primitive operation. \n\n
195 * Also for terminating threads, after the thread_terminate() primitive
196 * operation finishes, the system shall lower the urgency of the
197 * thread identified by thread to a value of zero, and shall deattach
198 * it from the ads scheduler. Then, the thread shall execute the
199 * cleanup handlers and the thread-specific data destructor functions
200 * outside the management of its former scheduler. Notice that in a
201 * multiprocessor system this may imply the suspension of the thread
202 * identified by parameter thread during the execution of the
203 * thread_terminate() primitive operation.
205 * - The \b thread_ready() primitive operation is invoked by the system
206 * when a thread attached to this scheduler that was blocked has
207 * become unblocked by the system.
209 * - The \b thread_block() primitive operation is invoked by the system
210 * when a thread attached to this scheduler has blocked.
212 * - The \b change_sched_param_thread() primitive operation is invoked
213 * by the system when the scheduling parameters of a thread attached
214 * to this scheduler have been changed OUTSIDE OF AN SCHEDULER
215 * CALLBACK, and the thread continues to run under this scheduler.
217 * The change includes either the regular scheduling parameters
218 * (fosa_thread_set_prio() or the application-defined scheduling
219 * parameters, via fosa_ads_set_appsched_param().
221 * - The \b explicit_call_with_data() primitive operation is invoked by the
222 * system when a thread (identified by the thread parameter) has
223 * explicitly invoked the scheduler with a message containing
224 * scheduling information, and possibly requesting a reply message,
225 * via fosa_ads_invoke_withdata().
227 * - The \b notification_for_thread() primitive operation is invoked by the
228 * system when the time for a thread-notification previously programed
229 * by the scheduler via fosa_ads_actions_add_thread_notification()
230 * is reached. Parameter clock identifies the clock for which the
231 * thread-notification was programmed.
233 * - The \b timeout() primitive operation is invoked by the system when a
234 * timeout requested by the scheduler (via
235 * fosa_ads_actions_add_timeout()) has expired.
237 * - The \b signal() primitive operation is invoked by the system when a
238 * signal belonging to the set of signals for which the scheduler is
239 * waiting (via fosa_ads_set_handled_signal_set()) has been
242 * The signal number and its associated information (if any) are
243 * passed in the arguments signal and siginfo.\n\n
245 * The signal is consumed with the invocation of this primitive
246 * operation, which implies that it will not cause the execution of
247 * any signal handler, nor it may be accepted by any thread waiting
248 * for this signal number.
250 * - The \b appsched_error() primitive operation is invoked by the system
251 * when an error in the scheduling actions list specified in a
252 * previous primitive operation is detected. The cause of the error is
253 * notified in the parameter cause. The defined causes of error are
254 * described fosa_ads_error_cause_t
256 * Every primitive operation receives the argument sched_data. It is a
257 * pointer to a memory area containing information shared by all the
258 * scheduler operations. It can be used to store the data structures
259 * required by the scheduler (for example, a ready queue and a delay
260 * queue). Scheduler operations should not use any other global data out
261 * of this memory area.
263 * The actions argument is used by the scheduler to request the operating
264 * system to execute a set of scheduling actions at the end of the
265 * primitive operation. It is passed empty by the system, and the
266 * scheduler may add multiple scheduling actions.
268 * The current_time argument contains the system time
269 * measured immediately before the invocation of the primitive operation
270 * using the FOSA_CLOCK_REALTIME clock
272 * In addition to these common parameters, most of the primitive
273 * operations receive a thread argument. This argument allows the
274 * primitive operations to know which is the thread that has produced or
275 * is related to the event.
278 void (*init) (void * sched_data, void * arg);
279 void (*new_thread) (void * sched_data,
280 frsh_thread_id_t thread,
281 fosa_ads_actions_t * actions,
282 struct timespec *current_time);
283 void (*thread_terminate) (void * sched_data,
284 frsh_thread_id_t thread,
285 fosa_ads_actions_t * actions,
286 struct timespec *current_time);
287 void (*thread_ready) (void * sched_data,
288 frsh_thread_id_t thread,
289 fosa_ads_actions_t * actions,
290 struct timespec *current_time);
291 void (*thread_block) (void * sched_data,
292 frsh_thread_id_t thread,
293 fosa_ads_actions_t * actions,
294 struct timespec *current_time);
295 //void (*thread_yield) (void * sched_data,
296 // frsh_thread_id_t thread,
297 // fosa_ads_actions_t * actions,
298 // struct timespec *current_time);
299 void (*change_sched_param_thread) (void * sched_data,
300 frsh_thread_id_t thread,
301 fosa_ads_actions_t * actions,
302 struct timespec *current_time);
303 //void msg_from_scheduler(void * sched_data,
304 // fosa_ads_scheduler_id_t scheduler_id,
305 // const void * msg, size_t msg_size,
306 // fosa_ads_actions_t * actions,
307 // struct timespec *current_time);
308 //void (*explicit_call) (void * sched_data,
309 // frsh_thread_id_t thread,
310 // int user_event_code,
311 // fosa_ads_actions_t * actions,
312 // struct timespec *current_time);
313 void (*explicit_call_with_data) (void * sched_data,
314 frsh_thread_id_t thread,
315 const void * msg, size_t msg_size,
316 void *reply, size_t *reply_size,
317 fosa_ads_actions_t * actions,
318 struct timespec *current_time);
319 void (*notification_for_thread) (void * sched_data,
320 frsh_thread_id_t thread,
321 fosa_clock_id_t clock,
322 fosa_ads_actions_t * actions,
323 struct timespec *current_time);
324 void (*timeout) (void * sched_data,
325 fosa_ads_actions_t * actions,
326 struct timespec *current_time);
327 void (*signal) (void * sched_data,
328 frsh_signal_t signal,
329 frsh_signal_info_t siginfo,
330 fosa_ads_actions_t * actions,
331 struct timespec *current_time);
332 //void (*priority_inherit) (void * sched_data,
333 // frsh_thread_id_t thread,
334 // int sched_priority,
335 // fosa_ads_actions_t * actions,
336 // struct timespec *current_time);
337 //void (*priority_uninherit) (void * sched_data,
338 // frsh_thread_id_t thread,
339 // int sched_priority,
340 // fosa_ads_actions_t * actions,
341 // struct timespec *current_time);
342 void (*appsched_error) (void * sched_data,
343 frsh_thread_id_t thread,
344 fosa_ads_error_cause_t cause,
345 fosa_ads_actions_t * actions);
346 } fosa_ads_scheduler_ops_t;
351 /*********************
353 *********************/
356 * The fosa_jump_context_t type defines a data area where the context
357 * of a thread can be saved, so that a long jump to recover that context
358 * may be executed in the future, from a long jump handler.
361 typedef FOSA_LONG_JUMP_CONTEXT_T_OPAQUE fosa_long_jump_context_t;
366 #endif // _FOSA_TYPES_H_