1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2008 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. Politécnica 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
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 // FSF API web pages: http://marte.unican.es/fsf/docs
32 // http://shark.sssup.it/contrib/first/docs/
34 // This file is part of FOSA (Frsh Operating System Adaption)
36 // FOSA is free software; you can redistribute it and/or modify it
37 // under terms of the GNU General Public License as published by the
38 // Free Software Foundation; either version 2, or (at your option) any
39 // later version. FOSA is distributed in the hope that it will be
40 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
41 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
42 // General Public License for more details. You should have received a
43 // copy of the GNU General Public License along with FOSA; see file
44 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
45 // Cambridge, MA 02139, USA.
47 // As a special exception, including FOSA header files in a file,
48 // instantiating FOSA generics or templates, or linking other files
49 // with FOSA objects to produce an executable application, does not
50 // by itself cause the resulting executable application to be covered
51 // by the GNU General Public License. This exception does not
52 // however invalidate any other reasons why the executable file might be
53 // covered by the GNU Public License.
54 // -----------------------------------------------------------------------
55 //fosa_clocks_and_timers.h
56 //==============================================
57 // ******** ****** ******** **********
58 // **///// /** ** **////// /** /**
59 // ** /** ** /** /** /**
60 // ******* /** ** /********* /**********
61 // **//// /** ** ////////** /**//////**
62 // ** /** ** /** /** /**
63 // ** /** ** ******** /** /**
64 // // /******/ //////// // //
66 // FOSA(Frescor Operating System Adaptation layer)
67 //================================================
70 #ifndef FOSA_CLOCKS_AND_TIMERS_H_
71 #define FOSA_CLOCKS_AND_TIMERS_H_
73 #include "fosa_types.h"
74 #include "fosa_configuration_parameters.h"
79 * @defgroup clocksandtimers Clocks and Timers
82 * This module defines the types and functions to abstract clocks and
83 * timers for the FRSH implementation.
90 /*************************
92 *************************/
97 * Get the time from a clock
99 * This function sets the variable pointed to by current_time to the
100 * current value of the clock specified by clockid, which may be the
101 * FOSA_CLOCK_REALTIME constant or a value obtained with
102 * fosa_get_cputime_clock()
104 * Returns 0 if successful; otherwise it returns an error code:
105 * FOSA_EINVAL: the value of clockid is invalid
107 * Alternatively, in case of error the implementation is allowed to
108 * notify it to the system console and then terminate the FRSH
109 * implementation and dependant applications
111 int fosa_clock_get_time(fosa_clock_id_t clockid, fosa_abs_time_t *current_time);
115 * fosa_get_cputime_clock()
117 * Get the identifier of a cpu-time clock
119 * This function stores in the variable pointed to by clockid the
120 * identifier of a cpu-time clock for the thread specified by tid.
122 * Returns 0 if successful; otherwise it returns an error code:
123 * FOSA_EINVAL: the value of tid is invalid
125 * Alternatively, in case of error the implementation is allowed to
126 * notify it to the system console and then terminate the FRSH
127 * implementation and dependant applications
129 int fosa_thread_get_cputime_clock(fosa_thread_id_t tid, fosa_clock_id_t *clockid);
132 /*************************
134 *************************/
137 * fosa_timer_create()
139 * Create a one-shot timer
141 * This function creates a timer based on the clock specified by clock,
142 * and associates to this timer a notification mechanism consisting of
143 * a signal and associated information. Initially, the timer is in the
144 * disarmed state, i.e., not counting time. It can be armed to start
145 * counting time with fosa_timer_arm().
147 * The function stores the identifier of the newly created timer in the
148 * variable pointed to by timerid.
150 * When the timer expires, the signal number specified by signal will be
151 * sent together with the information specified by info, to the thread
152 * that armed the timer (@see fosa_timer_arm()).
154 * In those implementations that do not support queueing a
155 * signal with information to a thread (such as POSIX), the signal may
156 * be sent to any thread that is waiting for this signal via
157 * fosa_signal_wait(). Portability can be ensured by having the receiver
158 * thread be the one who is waiting for the signal.
160 * Returns 0 if successful; otherwise it returns an error code:
161 * FOSA_EINVAL: the value of clockid or signal is invalid
163 * FOSA_EAGAIN: the system lacks enough resources to create the timer
165 * Alternatively, in case of error the implementation is allowed to
166 * notify it to the system console and then terminate the FRSH
167 * implementation and dependant applications
169 int fosa_timer_create
170 (fosa_clock_id_t clockid, fosa_signal_t signal, fosa_signal_info_t info,
171 fosa_timer_id_t *timerid);
174 * fosa_timer_create_with_receiver()
176 * Create a one-shot timer with a specific signal receiver thread
178 * This function creates a timer in the same way as fosa_timer_create,
179 * except that the signal generated when the timer expires is sent to
180 * the thread specified by receiver
182 * Returns 0 if successful; otherwise it returns an error code:
183 * FOSA_EINVAL: the value of clockid or signal is invalid
185 * FOSA_EAGAIN: the system lacks enough resources to create the timer
187 * Alternatively, in case of error the implementation is allowed to
188 * notify it to the system console and then terminate the FRSH
189 * implementation and dependant applications
191 int fosa_timer_create_with_receiver
192 (fosa_clock_id_t clockid, fosa_signal_t signal, fosa_signal_info_t info,
193 fosa_timer_id_t *timerid, fosa_thread_id_t receiver);
196 * fosa_timer_delete()
200 * The function deletes the timer specified by timerid, which becomes
201 * unusable. If the timer was armed, it is automatically disarmed before
204 * Returns 0 if successful; otherwise it returns an error code:
205 * FOSA_EINVAL: the value of timerid is not valid
207 * Alternatively, in case of error the implementation is allowed to
208 * notify it to the system console and then terminate the FRSH
209 * implementation and dependant applications
211 int fosa_timer_delete(fosa_timer_id_t timerid);
214 * fosa_rel_timer_arm()
216 * Arm a timer with a relative time interval
218 * The timer specified by timer is armed and starts counting time.
220 * The value pointed to by value is the relative interval that must
221 * elapse for the timer to expire. Negative values cause the timer to
222 * expire immediately.
224 * The time is measured with the clock associated with the timer when
227 * If the timer was already armed, the previous time or interval is discarded
228 * and the timer is rearmed with the new value.
230 * When the timer expires, it is disarmed.
232 * Returns 0 if successful; otherwise it returns an error code:
233 * FOSA_EINVAL: the value of timerid or value is invalid
235 * Alternatively, in case of error the implementation is allowed to
236 * notify it to the system console and then terminate the FRSH
237 * implementation and dependant applications
239 int fosa_rel_timer_arm
240 (fosa_timer_id_t timerid, const fosa_rel_time_t *value);
243 * fosa_abs_timer_arm()
245 * Arm a timer that will expire in an absolute time instant.
247 * The timer specified by timer is armed and starts counting time.
249 * The value pointed to by value is the absolute time at which the
250 * timer will expire. If value specifies a time instant in the past,
251 * the timer expires immediately.
253 * The time is measured with the clock associated with the timer when
256 * If the timer was already armed, the previous time or interval is discarded
257 * and the timer is rearmed with the new value.
259 * When the timer expires, it is disarmed.
261 * Returns 0 if successful; otherwise it returns an error code:
262 * FOSA_EINVAL: the value of timerid or value is invalid
264 * Alternatively, in case of error the implementation is allowed to
265 * notify it to the system console and then terminate the FRSH
266 * implementation and dependant applications
268 int fosa_abs_timer_arm
269 (fosa_timer_id_t timerid, const fosa_abs_time_t *value);
275 * fosa_timer_get_remaining_time()
277 * Get the remaining time for timer expiration
279 * Returns the relative remaining time for timer expiration. If the
280 * clock is a CPU clock it returns the time as if the thread was
281 * executing constantly.
283 * If the timer is disarmed it returns 0.
285 * Returns 0 if successful; otherwise it returns an error code:
286 * FOSA_EINVAL: the value of timerid or value is invalid
288 * Alternatively, in case of error the implementation is allowed to
289 * notify it to the system console and then terminate the FRSH
290 * implementation and dependant applications
292 int fosa_timer_get_remaining_time
293 (fosa_timer_id_t timerid, fosa_rel_time_t *remaining_time);
296 * fosa_timer_disarm()
298 * Disarm a timer and optionally obtain remaining time before expiration
300 * The timer specified by timer is disarmed, and will not expire unless
301 * it is rearmed. If the timer was already disramed, the function has
304 * If the pointer remaining_time is != NULL, the remaining time before
305 * expiration will be returned in that pointer. If the timer was
306 * disarmed a 0 value will be set.
308 * Returns 0 if successful; otherwise it returns an error code:
309 * FOSA_EINVAL: the value of timerid or value is invalid
311 * Alternatively, in case of error the implementation is allowed to
312 * notify it to the system console and then terminate the FRSH
313 * implementation and dependant applications
315 int fosa_timer_disarm(fosa_timer_id_t timerid,
316 fosa_rel_time_t *remaining_time);
323 #endif /* !FOSA_CLOCKS_AND_TIMERS_H_ */