source: rtems/cpukit/score/include/rtems/score/timestamp.h @ 154721c4

4.11
Last change on this file since 154721c4 was 154721c4, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 16, 2012 at 12:39:55 PM

score: Add _Timestamp_To_timeval()

  • Property mode set to 100644
File size: 11.1 KB
Line 
1/**
2 *  @file  rtems/score/timestamp.h
3 *
4 *  This include file contains helpers for manipulating timestamps.
5 */
6
7/*
8 *  COPYRIGHT (c) 1989-2009.
9 *  On-Line Applications Research Corporation (OAR).
10 *
11 *  The license and distribution terms for this file may be
12 *  found in the file LICENSE in this distribution or at
13 *  http://www.rtems.com/license/LICENSE.
14 */
15
16#ifndef _RTEMS_SCORE_TIMESTAMP_H
17#define _RTEMS_SCORE_TIMESTAMP_H
18
19/**
20 *  @defgroup SuperCore Timestamp
21 *
22 *  @ingroup Score
23 *
24 *  This handler encapsulates functionality related to manipulating
25 *  SuperCore Timestamps.  SuperCore Timestamps may be used to
26 *  represent time of day, uptime, or intervals.
27 *
28 *  The key attribute of the SuperCore Timestamp handler is that it
29 *  is a completely opaque handler.  There can be multiple implementations
30 *  of the required functionality and with a recompile, RTEMS can use
31 *  any implementation.  It is intended to be a simple wrapper.
32 *
33 *  This handler can be implemented as either struct timespec or
34 *  unsigned64 bit numbers.  The use of a wrapper class allows the
35 *  the implementation of timestamps to change on a per architecture
36 *  basis.  This is an important option as the performance of this
37 *  handler is critical.
38 */
39/**@{*/
40
41#include <sys/time.h>
42
43#include <rtems/score/cpu.h>
44#include <rtems/score/timespec.h>
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50#if ! ( ( CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE \
51    && CPU_TIMESTAMP_USE_INT64 == FALSE \
52    && CPU_TIMESTAMP_USE_INT64_INLINE == FALSE ) \
53  || ( CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == FALSE \
54    && CPU_TIMESTAMP_USE_INT64 == TRUE \
55    && CPU_TIMESTAMP_USE_INT64_INLINE == FALSE ) \
56  || ( CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == FALSE \
57    && CPU_TIMESTAMP_USE_INT64 == FALSE \
58    && CPU_TIMESTAMP_USE_INT64_INLINE == TRUE ) )
59  #error "Invalid SuperCore Timestamp implementations selection."
60#endif
61
62#if CPU_TIMESTAMP_USE_INT64 == TRUE || CPU_TIMESTAMP_USE_INT64_INLINE == TRUE
63  #include <rtems/score/timestamp64.h>
64#endif
65
66/**
67 *   Define the Timestamp control type.
68 */
69#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
70  typedef struct timespec Timestamp_Control;
71#else
72  typedef Timestamp64_Control Timestamp_Control;
73#endif
74
75/**
76 *  @brief Set Timestamp to Seconds Nanosecond
77 *
78 *  This method sets the timestamp to the specified seconds and nanoseconds
79 *  value.
80 *
81 *  @param[in] _time points to the timestamp instance to validate.
82 *  @param[in] _seconds is the seconds portion of the timestamp
83 *  @param[in] _nanoseconds is the nanoseconds portion of the timestamp
84 */
85#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
86  #define _Timestamp_Set( _time, _seconds, _nanoseconds ) \
87          _Timespec_Set( _time, _seconds, _nanoseconds )
88#else
89  #define _Timestamp_Set( _time, _seconds, _nanoseconds ) \
90          _Timestamp64_Set( _time, _seconds, _nanoseconds )
91#endif
92
93/**
94 *  @brief Zero Timestamp
95 *
96 *  This method sets the timestamp to zero.
97 *  value.
98 *
99 *  @param[in] _time points to the timestamp instance to zero.
100 */
101#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
102  #define _Timestamp_Set_to_zero( _time ) \
103          _Timespec_Set_to_zero( _time )
104#else
105  #define _Timestamp_Set_to_zero( _time ) \
106          _Timestamp64_Set_to_zero( _time )
107#endif
108
109/**
110 *  @brief Is Timestamp Valid
111 *
112 *  This method determines the validity of a timestamp.
113 *
114 *  @param[in] _time points to the timestamp instance to validate.
115 *
116 *  @return This method returns true if @a time is valid and
117 *          false otherwise.
118 */
119#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
120  #define _Timestamp_Is_valid( _time ) \
121          _Timespec_Is_valid( _time )
122#else
123  #define _Timestamp_Is_valid( _time ) \
124          _Timestamp64_Is_valid( _time )
125#endif
126
127/**
128 *  @brief Timestamp Less Than Operator
129 *
130 *  This method is the less than operator for timestamps.
131 *
132 *  @param[in] _lhs points to the left hand side timestamp
133 *  @param[in] _rhs points to the right hand side timestamp
134 *
135 *  @return This method returns true if @a _lhs is less than the @a _rhs and
136 *          false otherwise.
137 */
138#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
139  #define _Timestamp_Less_than( _lhs, _rhs ) \
140          _Timespec_Less_than( _lhs, _rhs )
141#else
142  #define _Timestamp_Less_than( _lhs, _rhs ) \
143          _Timestamp64_Less_than( _lhs, _rhs )
144#endif
145
146/**
147 *  @brief Timestamp Greater Than Operator
148 *
149 *  This method is the greater than operator for timestamps.
150 *
151 *  @param[in] _lhs points to the left hand side timestamp
152 *  @param[in] _rhs points to the right hand side timestamp
153 *
154 *  @return This method returns true if @a _lhs is greater than the @a _rhs and
155 *          false otherwise.
156 */
157#define _Timestamp_Greater_than( _lhs, _rhs ) \
158  _Timestamp_Less_than( _rhs, _lhs )
159
160/**
161 *  @brief Timestamp equal to Operator
162 *
163 *  This method is the is equal to than operator for timestamps.
164 *
165 *  @param[in] _lhs points to the left hand side timestamp
166 *  @param[in] _rhs points to the right hand side timestamp
167 *
168 *  @return This method returns true if @a _lhs is equal to  @a _rhs and
169 *          false otherwise.
170 */
171#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
172  #define _Timestamp_Equal_to( _lhs, _rhs ) \
173          _Timespec_Equal_to( _lhs, _rhs )
174#else
175  #define _Timestamp_Equal_to( _lhs, _rhs ) \
176          _Timestamp64_Equal_to( _lhs, _rhs )
177#endif
178
179/**
180 *  @brief Add to a Timestamp
181 *
182 *  This routine adds two timestamps.  The second argument is added
183 *  to the first.
184 *
185 *  @param[in] _time points to the base time to be added to
186 *  @param[in] _add points to the timestamp to add to the first argument
187 *
188 *  @return This method returns the number of seconds @a time increased by.
189 */
190#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
191  #define _Timestamp_Add_to( _time, _add ) \
192          _Timespec_Add_to( _time, _add )
193#else
194  #define _Timestamp_Add_to( _time, _add ) \
195          _Timestamp64_Add_to( _time, _add )
196#endif
197
198/**
199 *  @brief Convert Timestamp to Number of Ticks
200 *
201 *  This routine convert the @a time timestamp to the corresponding number
202 *  of clock ticks.
203 *
204 *  @param[in] _time points to the time to be converted
205 *
206 *  @return This method returns the number of ticks computed.
207 */
208#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
209  #define _Timestamp_To_ticks( _time ) \
210          _Timespec_To_ticks( _time )
211#else
212  #define _Timestamp_To_ticks( _time ) \
213          _Timestamp64_To_ticks( _time )
214#endif
215
216/**
217 *  @brief Convert Ticks to Timestamp
218 *
219 *  This routine converts the @a _ticks value to the corresponding
220 *  timestamp format @a _time.
221 *
222 *  @param[in] _time points to the timestamp format time result
223 *  @param[in] _ticks points to the number of ticks to be filled in
224 */
225#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
226  #define _Timestamp_From_ticks( _ticks, _time ) \
227          _Timespec_From_ticks( _ticks, _time )
228#else
229  #define _Timestamp_From_ticks( _ticks, _time ) \
230          _Timestamp64_From_ticks( _ticks, _time )
231#endif
232
233/**
234 *  @brief Subtract Two Timestamp
235 *
236 *  This routine subtracts two timestamps.  @a result is set to
237 *  @a end - @a start.
238 *
239 *  @param[in] _start points to the starting time
240 *  @param[in] _end points to the ending time
241 *  @param[in] _result points to the difference between
242 *             starting and ending time.
243 *
244 *  @return This method fills in @a _result.
245 */
246#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
247  #define _Timestamp_Subtract( _start, _end, _result ) \
248          _Timespec_Subtract( _start, _end, _result )
249#else
250  #define _Timestamp_Subtract( _start, _end, _result ) \
251          _Timestamp64_Subtract( _start, _end, _result )
252#endif
253
254/**
255 *  @brief Divide Timestamp By Integer
256 *
257 *  This routine divides a timestamp by an integer value.  The expected
258 *  use is to assist in benchmark calculations where you typically
259 *  divide a duration by a number of iterations.
260 *
261 *  @param[in] _time points to the total
262 *  @param[in] _iterations is the number of iterations
263 *  @param[in] _result points to the average time.
264 *
265 *  @return This method fills in @a result.
266 */
267#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
268  #define _Timestamp_Divide_by_integer( _time, _iterations, _result ) \
269          _Timespec_Divide_by_integer(_time, _iterations, _result )
270#else
271  #define _Timestamp_Divide_by_integer( _time, _iterations, _result ) \
272          _Timestamp64_Divide_by_integer( _time, _iterations, _result )
273#endif
274
275/**
276 *  @brief Divide Timestamp
277 *
278 *  This routine divides a timestamp by another timestamp.  The
279 *  intended use is for calculating percentages to three decimal points.
280 *
281 *  @param[in] _lhs points to the left hand number
282 *  @param[in] _rhs points to the right hand number
283 *  @param[in] _ival_percentage points to the integer portion of the average
284 *  @param[in] _fval_percentage points to the thousandths of percentage
285 *
286 *  @return This method fills in @a result.
287 */
288#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
289  #define _Timestamp_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage ) \
290          _Timespec_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage )
291#else
292  #define _Timestamp_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage ) \
293          _Timestamp64_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage )
294#endif
295
296/**
297 *  @brief Get Seconds Portion of Timestamp
298 *
299 *  This method returns the seconds portion of the specified timestamp
300 *
301 *  @param[in] _time points to the timestamp
302 *
303 *  @return The seconds portion of @a _time.
304 */
305#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
306  #define _Timestamp_Get_seconds( _time ) \
307          _Timespec_Get_seconds( _time )
308#else
309  #define _Timestamp_Get_seconds( _time ) \
310          _Timestamp64_Get_seconds( _time )
311#endif
312
313/**
314 *  @brief Get Nanoseconds Portion of Timestamp
315 *
316 *  This method returns the nanoseconds portion of the specified timestamp
317 *
318 *  @param[in] _time points to the timestamp
319 *
320 *  @return The nanoseconds portion of @a _time.
321 */
322#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
323  #define _Timestamp_Get_nanoseconds( _time ) \
324          _Timespec_Get_nanoseconds( _time )
325#else
326  #define _Timestamp_Get_nanoseconds( _time ) \
327          _Timestamp64_Get_nanoseconds( _time )
328#endif
329
330/**
331 *  @brief Convert Timestamp to struct timespec
332 *
333 *  This method returns the seconds portion of the specified timestamp
334 *
335 *  @param[in] _timestamp points to the timestamp
336 *  @param[in] _timespec points to the timespec
337 */
338#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
339  /* in this case we know they are the same type so use simple assignment */
340  #define _Timestamp_To_timespec( _timestamp, _timespec  ) \
341          *(_timespec) = *(_timestamp)
342#else
343  #define _Timestamp_To_timespec( _timestamp, _timespec  ) \
344          _Timestamp64_To_timespec( _timestamp, _timespec  )
345#endif
346
347/**
348 *  @brief Convert Timestamp to struct timeval
349 *
350 *  @param[in] _timestamp points to the timestamp
351 *  @param[in] _timeval points to the timeval
352 */
353#if CPU_TIMESTAMP_USE_STRUCT_TIMESPEC == TRUE
354  #define _Timestamp_To_timeval( _timestamp, _timeval  ) \
355    do { \
356      (_timeval)->tv_sec = (_timestamp)->tv_sec; \
357      (_timeval)->tv_usec = (_timestamp)->tv_nsec / 1000; \
358    } while (0)
359#else
360  #define _Timestamp_To_timeval( _timestamp, _timeval  ) \
361          _Timestamp64_To_timeval( _timestamp, _timeval  )
362#endif
363
364#ifdef __cplusplus
365}
366#endif
367
368/**@}*/
369
370#endif
371/* end of include file */
Note: See TracBrowser for help on using the repository browser.