1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 FRESCOR consortium partners:
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 for a link to partners' websites
18 // 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
23 // This file is part of the FRSH implementation
25 // FRSH is free software; you can redistribute it and/or modify
26 // it under the terms of the GNU General Public License as published by
27 // the Free Software Foundation; either version 2, or (at your option)
30 // FRSH is distributed in the hope that it will be useful, but
31 // WITHOUT ANY WARRANTY; without even the implied warranty of
32 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
33 // General Public License for more details.
35 // You should have received a copy of the GNU General Public License
36 // distributed with FRSH; see file COPYING. If not, write to the
37 // Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
40 // As a special exception, if you include this header file into source
41 // files to be compiled, this header file does not by itself cause
42 // the resulting executable to be covered by the GNU General Public
43 // License. This exception does not however invalidate any other
44 // reasons why the executable file might be covered by the GNU General
46 // -----------------------------------------------------------------------
47 //fosa_thread_and_signals.h
48 //==============================================
49 // ******** ****** ******** **********
50 // **///// /** ** **////// /** /**
51 // ** /** ** /** /** /**
52 // ******* /** ** /********* /**********
53 // **//// /** ** ////////** /**//////**
54 // ** /** ** /** /** /**
55 // ** /** ** ******** /** /**
56 // // /******/ //////// // //
58 // FOSA(Frescor Operating System Adaptation layer)
59 //================================================
62 #ifndef FOSA_THREAD_AND_SIGNALS_H_
63 #define FOSA_THREAD_AND_SIGNALS_H_
65 #include "fosa_types.h"
68 * @defgroup threadandsignals Thread and Signals
71 * This module defines the functions that manipulate frsh_threads and
72 * frsh_signals inside FRSH implementation.
74 * Applications can refer to FRSH threads but they cannot create them
75 * directly, instead they must use frsh_thread_create*() which in turn
76 * use fosa_thread_create().
78 * For signals, we assume that the OS provides a direct mapping
79 * for frsh_signal_t and frsh_signal_info_t in the native interface.
86 /*************************
87 * Thread identification
88 *************************/
93 * Compare two thread identifiers to determine if they refer to the
96 bool fosa_thread_equal(frsh_thread_id_t t1, frsh_thread_id_t t2);
102 * Return the thread id of the calling thread
104 frsh_thread_id_t fosa_thread_self();
107 /*************************
108 * Thread creation and termination
109 *************************/
112 * fosa_thread_create()
114 * This function creates a new thread using the attributes specified
115 * in attr. If attr is NULL, default attributes are used. The new
116 * thread starts running immediately, executing the function specified
117 * by code, with an argument equal to arg. Upon successful return, the
118 * variable pointed to by tid will contain the identifier of the newly
119 * created thread. The set of signals that may be synchronously
120 * accepted is inherited from the parent thread.
122 * Returns 0 if successful; otherwise it returs a code error:
124 * FOSA_EAGAIN: the system lacks the necessary resources to create a
125 * new thread or the maximum number of threads has been
128 * FOSA_EINVAL: the value specified by attr is invalid (for instance,
129 * it has not been correctly initialized)
131 * FOSA_EREJECT: the cretion of the thread was rejected by the frsh scheduler
132 * possibly because of incorrect attributes, or because the
133 * requested minimum capacity cannot be guaranteed
136 int fosa_thread_create
137 (frsh_thread_id_t *tid, const frsh_thread_attr_t *attr,
138 frsh_thread_code_t code, void * arg);
142 * Note: no thread termination primitive is provided. The termination
143 * of a thread will be notified by the system to the FRSH scheduler
144 * through the scheduler API
148 /**************************************************
149 * Thread-specific data
150 * (extended with access from a different thread)
152 * Several data items (pointers) may be associated with each thread
153 * Each item is identified through a key, an integer value between 0
154 * and FOSA_MAX_KEYS-1. The caller is responsible of allocating and
155 * deallocating the memory area pointed to by the pointer
156 **************************************************/
161 * Create a new key for thread specific data.
163 * Prior to setting data in a key, we need ask the system to create
166 * @return 0 if successful \n
167 * FOSA_EINVAL If we already have reached the FOSA_MAX_KEYS limit.
168 * FOSA_ENOMEM If there are no enough memory resources to
171 int fosa_key_create(int *key);
178 * This destroys the key and isables its use in the system
180 * @return 0 if successful \n
181 * FOSA_EINVAL The key is not initialised or is not in FOSA key range.
183 int fosa_key_destroy(int key);
187 * fosa_thread_set_specific_data()
189 * Set thread-specific data
191 * For the thread identified by tid, the thread-specifid data field
192 * identified by key will be set to the value specified by value
194 * Returns 0 if successful; otherwise, an error code is returned
195 * FOSA_EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
197 * Alternatively, in case of error the implementation is allowed to
198 * notify it to the system console and then terminate the FRSH
199 * implementation and dependant applications
201 int fosa_thread_set_specific_data
202 (int key, frsh_thread_id_t tid, const void * value);
205 * fosa_thread_get_specific_data()
207 * Get thread-specific data
209 * For the thread identified by tid, the thread-specifid data field
210 * identified by key will be copied to the variable pointed to by value
212 * Returns 0 if successful; otherwise, an error code is returned
213 * FOSA_EINVAL: the value of key is not between 0 and FOSA_MAX_KEYS-1
215 * Alternatively, in case of error the implementation is allowed to
216 * notify it to the system console and then terminate the FRSH
217 * implementation and dependant applications
219 int fosa_thread_get_specific_data(int key, frsh_thread_id_t tid,
223 /******************************************************************
226 * This implementation of FRSH assumes an underlying fixed priority
227 * scheduler with priorities in a range, with a minimum and a
228 * maximumm, a number of priority levels with at least 31
229 * priorities. A larger number implies a larger priority. In systems
230 * in which the underlying scheduler uses the opposite convention, a
231 * mapping is automatically provided by the OS adaptation layer.
232 *******************************************************************/
235 * fosa_get_priority_max()
237 * Return the maximum priority value used in this implementation
239 int fosa_get_priority_max();
242 * fosa_get_priority_min()
244 * Return the minimum priority value used in this implementation
246 int fosa_get_priority_min();
249 * fosa_thread_attr_set_prio()
251 * Change the priority of a thread attributes object
253 * The priority of the thread attriutes object specified by attr is
254 * set to the value specified by prio. This function has no runtime
255 * effect on the priority, except when the attributes object is used
256 * to create a thread, when it will be created with the specified
259 * Returns 0 if successful, or the following error code:
260 * FOSA_EINVAL: the specified priority value is not between the
261 * minimum and the maximum priorities defined in this
262 * FRSH implementation
263 * Alternatively, in case of error the implementation is allowed to
264 * notify it to the system console and then terminate the FRSH
265 * implementation and dependant applications
267 int fosa_thread_attr_set_prio(frsh_thread_attr_t *attr, int prio);
270 * fosa_thread_attr_get_prio()
272 * Get the priority from a thread attributes object
274 * This function sets the variable pointed to by prio to the
275 * priority stored in the thread attributes object attr.
279 int fosa_thread_attr_get_prio
280 (const frsh_thread_attr_t *attr, int *prio);
283 * fosa_thread_set_prio()
285 * Dynamically change the priority of a thread
287 * The priority of the thread identified by tid is
288 * set to the value specified by prio.
290 * Returns 0 if successful, or the following error code:
291 * FOSA_EINVAL: the specified priority value is not between the
292 * minimum and the maximum priorities defined in this
293 * FRSH implementation
294 * Alternatively, in case of error the implementation is allowed to
295 * notify it to the system console and then terminate the FRSH
296 * implementation and dependant applications
298 int fosa_thread_set_prio(frsh_thread_id_t tid, int prio);
301 * fosa_thread_get_prio()
303 * Dynamically get the priority of a thread
305 * This function sets the variable pointed to by prio to the
306 * priority of the thread identified by tid
310 int fosa_thread_get_prio (frsh_thread_id_t tid, int *prio);
314 /*******************************************************************
317 * Signals represent events that may be notified by the system, or
318 * sent explicitly by the application, and for which a thread may
319 * synchronously wait. Signals carry an associated piece of
320 * information (an integer or a pointer) and are queued until they are
321 * accepted. Signals are identified by an integer signal number (of
322 * the type frsh_signal_t) in the range FOSA_SIGNAL_MIN,
323 * FOSA_SIGNAL_MAX. This range is required to have at least <tbd>
325 *******************************************************************/
328 * fosa_set_accepted_signals()
330 * Establish the set of signals that may be synchronously accepted
331 * by the calling thread
333 * The function uses the array of signal numbers specified by set,
334 * which must be of size equal to size
336 * Returns 0 if successful; otherwise it returns an error code:
337 * FOSA_EINVAL: the array contains one or more values which are not
338 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
341 * Alternatively, in case of error the implementation is allowed to
342 * notify it to the system console and then terminate the FRSH
343 * implementation and dependant applications
345 int fosa_set_accepted_signals(frsh_signal_t set[], int size);
348 * fosa_signal_queue()
352 * This function is used to explicitly send a signal with a specified
355 * The signal number specified by signal is sent together with the
356 * information specified by info, to the thread identified by
357 * receiver. In those implementations that do not support queueing a
358 * signal with information to a thread (such as POSIX), the signal may
359 * be sent to any thread that is waiting for this signal via
360 * fosa_signal_wait(). Portability can be ensured by having the receiver
361 * thread be the one who is waiting for the signal.
363 * Returns 0 if successful; otherwise it returns an error code:
364 * FOSA_EINVAL: the signal specified by signal is not
365 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
367 * FOSA_EAGAIN: no resources are available to queue the signal; the
368 * maximum number of queued signals has been reached, or a
369 * systemwide resource limit has been exceeded
371 * Alternatively, in case of error the implementation is allowed to
372 * notify it to the system console and then terminate the FRSH
373 * implementation and dependant applications
375 int fosa_signal_queue
376 (frsh_signal_t signal, frsh_signal_info_t info,
377 frsh_thread_id_t receiver);
387 * The function waits for the arrival of one of the signals in the
388 * array of signal numbers specified by set, which must be of size
389 * equal to size. If there is a signal already queued, the function
390 * returns immediately. If there is no signal of the specified set
391 * queued, the calling thread is suspended until a signal from that
392 * set arrives. Upon return, if signal_received is not NULL the number
393 * of the signal received is stored in the variable pointed to by
394 * signal_received; and if info is not NULL the associated information
395 * is stored in the variable pointed to by info.
397 * Returns 0 if successful; otherwise it returns an error code:
398 * FOSA_EINVAL: the array contains one or more values which are not
399 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
402 * Alternatively, in case of error the implementation is allowed to
403 * notify it to the system console and then terminate the FRSH
404 * implementation and dependant applications
407 (frsh_signal_t set[], int size, frsh_signal_t *signal_received,
408 frsh_signal_info_t *info);
411 * fosa_signal_timedwait()
413 * Timed wait for a signal
415 * This function behaves the same as fosa_signal_wait(), except that
416 * the suspension time is limited to the time interval specified in
417 * the timespec structure referenced by timeout.
419 * Returns 0 if successful; otherwise it returns an error code:
420 * FOSA_EINVAL: the array contains one or more values which are not
421 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX, or size
422 * is less than 0, or timeout is invalid
423 * FOSA_EAGAIN: The timeout expired
425 * Alternatively, in case of the FOSA_EINVAL error the implementation is
426 * allowed to notify it to the system console and then terminate the
427 * FRSH implementation and dependant applications
429 int fosa_signal_timedwait
430 (frsh_signal_t set[], int size, frsh_signal_t *signal_received,
431 frsh_signal_info_t *info, const struct timespec *timeout);
436 #endif /* !FOSA_THREAD_AND_SIGNALS_H_ */