source: rtems/cpukit/score/include/rtems/score/timestamp.h @ 7e119990

4.115
Last change on this file since 7e119990 was c499856, checked in by Chris Johns <chrisj@…>, on 03/20/14 at 21:10:47

Change all references of rtems.com to rtems.org.

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