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 // -----------------------------------------------------------------------
52 //fosa_thread_and_signals.h
53 //==============================================
54 // ******** ****** ******** **********
55 // **///// /** ** **////// /** /**
56 // ** /** ** /** /** /**
57 // ******* /** ** /********* /**********
58 // **//// /** ** ////////** /**//////**
59 // ** /** ** /** /** /**
60 // ** /** ** ******** /** /**
61 // // /******/ //////// // //
63 // FOSA(Frescor Operating System Adaptation layer)
64 //================================================
67 #ifndef FOSA_THREAD_AND_SIGNALS_H_
68 #define FOSA_THREAD_AND_SIGNALS_H_
70 #include "fosa_types.h"
77 * @defgroup threadandsignals Thread and Signals
80 * This module defines the functions that manipulate fosa_threads and
81 * fosa_signals inside FRSH implementation.
83 * Applications can refer to FRSH threads but they cannot create them
84 * directly, instead they must use frsh_thread_create*() which in turn
85 * use fosa_thread_create().
87 * For signals, we assume that the OS provides a direct mapping
88 * for fosa_signal_t and fosa_signal_info_t in the native interface.
95 /*************************
96 * Thread identification
97 *************************/
100 * fosa_thread_equal()
102 * Compare two thread identifiers to determine if they refer to the
105 bool fosa_thread_equal(fosa_thread_id_t t1, fosa_thread_id_t t2);
111 * Return the thread id of the calling thread
113 fosa_thread_id_t fosa_thread_self();
116 /*************************
118 *************************/
121 * fosa_thread_attr_init()
123 * Initialize a thread attributes object
125 * This function initializes the object pointed to by attr to all
126 * the default values defined by FRSH
128 * @return 0 if successful; otherwise it returns \n
129 * FOSA_ENOMEM: insufficient memory exists to initialize the thread
132 int fosa_thread_attr_init(fosa_thread_attr_t *attr);
136 * fosa_thread_attr_destroy()
138 * Destroy a thread attributes object
140 * This function is used to destroy the thread attributes object,
141 * pointed to by attr, and deallocate any system resources allocated for it
145 int fosa_thread_attr_destroy(fosa_thread_attr_t *attr);
149 * fosa_thread_attr_set_stacksize()
151 * Set the thread minimum stack size in a thread attributes object
153 * This function sets the minimum stack size of the thread attributes
154 * object attr to the value given by stacksize, in bytes. This
155 * function has no runtime effect on the stack size, except when the
156 * attributes object is used to create a thread, when it will be
157 * created with the specified minimum stack size
159 * @return 0 if successful, or the following error code:
160 * FOSA_EINVAL: the specified stacksize value is not supported in
161 * this implementation
163 int fosa_thread_attr_set_stacksize(fosa_thread_attr_t *attr,
167 * fosa_thread_attr_get_stacksize()
169 * Get the thread minimum stack size from a thread attributes object
171 * This function sets the variable pointed to by stacksize to the
172 * minimum stack size stored in the thread attributes object attr.
176 int fosa_thread_attr_get_stacksize(const fosa_thread_attr_t *attr,
180 /*************************
181 * Thread creation and termination
182 *************************/
185 * fosa_thread_create()
187 * This function creates a new thread using the attributes specified
188 * in attr. If attr is NULL, default attributes are used. The new
189 * thread starts running immediately, executing the function specified
190 * by code, with an argument equal to arg. Upon successful return, the
191 * variable pointed to by tid will contain the identifier of the newly
192 * created thread. The set of signals that may be synchronously
193 * accepted is inherited from the parent thread.
195 * Returns 0 if successful; otherwise it returs a code error:
197 * FOSA_EAGAIN: the system lacks the necessary resources to create a
198 * new thread or the maximum number of threads has been
201 * FOSA_EINVAL: the value specified by attr is invalid (for instance,
202 * it has not been correctly initialized)
204 * FOSA_EREJECT: the cretion of the thread was rejected by the frsh scheduler
205 * possibly because of incorrect attributes, or because the
206 * requested minimum capacity cannot be guaranteed
209 int fosa_thread_create
210 (fosa_thread_id_t *tid, const fosa_thread_attr_t *attr,
211 fosa_thread_code_t code, void * arg);
215 * Note: no thread termination primitive is provided. The termination
216 * of a thread will be notified by the system to the FRSH scheduler
217 * through the scheduler API
221 /**************************************************
222 * Thread-specific data
223 * (extended with access from a different thread)
225 * Several data items (pointers) may be associated with each thread
226 * Each item is identified through a key, an integer value between 0
227 * and FOSA_MAX_KEYS-1. The caller is responsible of allocating and
228 * deallocating the memory area pointed to by the pointer
229 **************************************************/
234 * Create a new key for thread specific data.
236 * Prior to setting data in a key, we need ask the system to create
237 * one for us. The thread specific data of all the threads is set to
238 * the value NULL until changed to a different value via
239 * fosa_thread_set_specific_data().
241 * @return 0 if successful \n
242 * FOSA_EINVAL If we already have reached the FOSA_MAX_KEYS limit.
243 * FOSA_ENOMEM If there are no enough memory resources to
246 int fosa_key_create(int *key);
253 * This destroys the key and disables its use in the system
255 * @return 0 if successful \n
256 * FOSA_EINVAL The key is not initialised or is not in FOSA key range.
258 int fosa_key_destroy(int key);
262 * fosa_thread_set_specific_data()
264 * Set thread-specific data
266 * For the thread identified by tid, the thread-specifid data field
267 * identified by key will be set to the value specified by value
269 * Returns 0 if successful; otherwise, an error code is returned
270 * FOSA_EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
272 * Alternatively, in case of error the implementation is allowed to
273 * notify it to the system console and then terminate the FRSH
274 * implementation and dependant applications
276 int fosa_thread_set_specific_data
277 (int key, fosa_thread_id_t tid, const void * value);
280 * fosa_thread_get_specific_data()
282 * Get thread-specific data
284 * For the thread identified by tid, the thread-specifid data field
285 * identified by key will be copied to the variable pointed to by value
287 * Returns 0 if successful; otherwise, an error code is returned
288 * FOSA_EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
290 * Alternatively, in case of error the implementation is allowed to
291 * notify it to the system console and then terminate the FRSH
292 * implementation and dependant applications
294 int fosa_thread_get_specific_data(int key, fosa_thread_id_t tid,
298 /******************************************************************
301 * This implementation of FRSH assumes an underlying fixed priority
302 * scheduler with priorities in a range, with a minimum and a
303 * maximumm, a number of priority levels with at least 31
304 * priorities. A larger number implies a larger priority. In systems
305 * in which the underlying scheduler uses the opposite convention, a
306 * mapping is automatically provided by the OS adaptation layer.
307 *******************************************************************/
310 * fosa_get_priority_max()
312 * Return the maximum priority value used in this implementation
314 int fosa_get_priority_max();
317 * fosa_get_priority_min()
319 * Return the minimum priority value used in this implementation
321 int fosa_get_priority_min();
324 * fosa_thread_attr_set_prio()
326 * Change the priority of a thread attributes object
328 * The priority of the thread attriutes object specified by attr is
329 * set to the value specified by prio. This function has no runtime
330 * effect on the priority, except when the attributes object is used
331 * to create a thread, when it will be created with the specified
334 * Returns 0 if successful, or the following error code:
335 * FOSA_EINVAL: the specified priority value is not between the
336 * minimum and the maximum priorities defined in this
337 * FRSH implementation
338 * Alternatively, in case of error the implementation is allowed to
339 * notify it to the system console and then terminate the FRSH
340 * implementation and dependant applications
342 int fosa_thread_attr_set_prio(fosa_thread_attr_t *attr, int prio);
345 * fosa_thread_attr_get_prio()
347 * Get the priority from a thread attributes object
349 * This function sets the variable pointed to by prio to the
350 * priority stored in the thread attributes object attr.
354 int fosa_thread_attr_get_prio
355 (const fosa_thread_attr_t *attr, int *prio);
358 * fosa_thread_set_prio()
360 * Dynamically change the priority of a thread
362 * The priority of the thread identified by tid is
363 * set to the value specified by prio.
365 * Returns 0 if successful, or the following error code:
366 * FOSA_EINVAL: the specified priority value is not between the
367 * minimum and the maximum priorities defined in this
368 * FRSH implementation
369 * Alternatively, in case of error the implementation is allowed to
370 * notify it to the system console and then terminate the FRSH
371 * implementation and dependant applications
373 int fosa_thread_set_prio(fosa_thread_id_t tid, int prio);
376 * fosa_thread_get_prio()
378 * Dynamically get the priority of a thread
380 * This function sets the variable pointed to by prio to the
381 * priority of the thread identified by tid
385 int fosa_thread_get_prio (fosa_thread_id_t tid, int *prio);
389 /*******************************************************************
392 * Signals represent events that may be notified by the system, or
393 * sent explicitly by the application, and for which a thread may
394 * synchronously wait. Signals carry an associated piece of
395 * information (an integer or a pointer) and are queued until they are
396 * accepted. Signals are identified by an integer signal number (of
397 * the type fosa_signal_t) in the range FOSA_SIGNAL_MIN,
398 * FOSA_SIGNAL_MAX. This range is required to have at least <tbd>
400 *******************************************************************/
403 * fosa_set_accepted_signals()
405 * Establish the set of signals that may be synchronously accepted
406 * by the calling thread
408 * The function uses the array of signal numbers specified by set,
409 * which must be of size equal to size
411 * Returns 0 if successful; otherwise it returns an error code:
412 * FOSA_EINVAL: the array contains one or more values which are not
413 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
416 * Alternatively, in case of error the implementation is allowed to
417 * notify it to the system console and then terminate the FRSH
418 * implementation and dependant applications
420 int fosa_set_accepted_signals(fosa_signal_t set[], int size);
423 * fosa_signal_queue()
427 * This function is used to explicitly send a signal with a specified
430 * The signal number specified by signal is sent together with the
431 * information specified by info, to the thread identified by
432 * receiver. In those implementations that do not support queueing a
433 * signal with information to a thread (such as POSIX), the signal may
434 * be sent to any thread that is waiting for this signal via
435 * fosa_signal_wait(). Portability can be ensured by having the receiver
436 * thread be the one who is waiting for the signal.
438 * Returns 0 if successful; otherwise it returns an error code:
439 * FOSA_EINVAL: the signal specified by signal is not
440 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
442 * FOSA_EAGAIN: no resources are available to queue the signal; the
443 * maximum number of queued signals has been reached, or a
444 * systemwide resource limit has been exceeded
446 * Alternatively, in case of error the implementation is allowed to
447 * notify it to the system console and then terminate the FRSH
448 * implementation and dependant applications
450 int fosa_signal_queue
451 (fosa_signal_t signal, fosa_signal_info_t info,
452 fosa_thread_id_t receiver);
462 * The function waits for the arrival of one of the signals in the
463 * array of signal numbers specified by set, which must be of size
464 * equal to size. If there is a signal already queued, the function
465 * returns immediately. If there is no signal of the specified set
466 * queued, the calling thread is suspended until a signal from that
467 * set arrives. Upon return, if signal_received is not NULL the number
468 * of the signal received is stored in the variable pointed to by
469 * signal_received; and if info is not NULL the associated information
470 * is stored in the variable pointed to by info.
472 * Returns 0 if successful; otherwise it returns an error code:
473 * FOSA_EINVAL: the array contains one or more values which are not
474 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
477 * Alternatively, in case of error the implementation is allowed to
478 * notify it to the system console and then terminate the FRSH
479 * implementation and dependant applications
482 (fosa_signal_t set[], int size, fosa_signal_t *signal_received,
483 fosa_signal_info_t *info);
486 * fosa_signal_timedwait()
488 * Timed wait for a signal
490 * This function behaves the same as fosa_signal_wait(), except that
491 * the suspension time is limited to the time interval specified in
492 * the fosa_rel_time_t value referenced by timeout.
494 * Returns 0 if successful; otherwise it returns an error code:
495 * FOSA_EINVAL: the array contains one or more values which are not
496 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
497 * is less than 0, or timeout is invalid
498 * FOSA_EAGAIN: The timeout expired
500 * Alternatively, in case of the FOSA_EINVAL error the implementation is
501 * allowed to notify it to the system console and then terminate the
502 * FRSH implementation and dependant applications
504 int fosa_signal_timedwait
505 (fosa_signal_t set[], int size, fosa_signal_t *signal_received,
506 fosa_signal_info_t *info, const fosa_rel_time_t *timeout);
512 #endif /* !FOSA_THREAD_AND_SIGNALS_H_ */