source: rtems/cpukit/score/include/rtems/score/timestamp.h @ 04286374

4.10
Last change on this file since 04286374 was 04286374, checked in by Ralf Corsepius <ralf.corsepius@…>, on 06/12/10 at 05:56:33

2010-06-12 Ralf Corsépius <ralf.corsepius@…>

  • score/include/rtems/score/timestamp.h, score/include/rtems/score/timestamp64.h, score/include/rtems/score/watchdog.h: Misc. doxygen fixes.
  • Property mode set to 100644
File size: 13.7 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-2008.
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 *  $Id$
16 */
17
18#ifndef _RTEMS_SCORE_TIMESTAMP_H
19#define _RTEMS_SCORE_TIMESTAMP_H
20
21/**
22 *  @defgroup SuperCore Timestamp
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#ifdef __cplusplus
42extern "C" {
43#endif
44
45#include <rtems/score/timespec.h>
46
47/*
48 *  NOTE: Eventually each port should select what it should use!!!
49 *
50 *  These control which implementation of SuperCore Timestamp is used.
51 *
52 *  if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
53 *     struct timespec is used
54 *  else if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_INT64)
55 *     int64_t is used
56 *
57 *  When int64_t is used, then
58 *     if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
59 *        the methods are inlined
60 *     else
61 *        the methods are NOT inlined
62 *
63 *  Performance of int64_t versus struct timespec
64 *  =============================================
65 *
66 *  On PowerPC/psim, inlined int64_t saves ~50 instructions on each
67 *    _Thread_Dispatch operation which results in a context switch.
68 *    This works out to be about 10% faster dispatches and 7.5% faster
69 *    blocking semaphore obtains.  The following numbers are in instructions
70 *    and from tm02 and tm26.
71 *
72 *                         timespec  int64  inlined int64
73 *    dispatch:              446      446      400
74 *    blocking sem obtain:   627      626      581
75 *
76 *  On SPARC/sis, inlined int64_t shows the same percentage gains.
77 *    The following numbers are in microseconds and from tm02 and tm26.
78 *
79 *                         timespec  int64  inlined int64
80 *    dispatch:               59       61       53
81 *    blocking sem obtain:    98      100       92
82 *
83 *  Inlining appears to have a tendency to increase the size of
84 *    some executables.
85 *  Not inlining reduces the execution improvement but does not seem to
86 *    be an improvement on the PowerPC and SPARC. The struct timespec
87 *    and the executables with int64 not inlined are about the same size.
88 *
89 *  Once there has some analysis of which algorithm and configuration
90 *  is best suited to each target, these defines should be moved to
91 *  the appropriate score/cpu cpu.h file.  In the meantime, it is
92 *  appropriate to select an implementation here using CPU macros.
93 */
94
95#define CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC
96/*
97#define CPU_RTEMS_SCORE_TIMESTAMP_IS_INT64
98#define CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE
99*/
100
101/*
102 *  Verify something is defined.
103 */
104#if !defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC) && \
105    !defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_INT64)
106  #error "No SuperCore Timestamp implementation selected."
107#endif
108
109/*
110 * Verify that more than one is not defined.
111 */
112#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC) && \
113    defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_INT64)
114  #error "Too many SuperCore Timestamp implementations selected."
115#endif
116
117/**
118 *   Include any implementation specific header files
119 */
120#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_INT64)
121  #include <rtems/score/timestamp64.h>
122#endif
123
124/**
125 *   Define the Timestamp control type.
126 */
127#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
128  typedef struct timespec Timestamp_Control;
129#else
130  typedef Timestamp64_Control Timestamp_Control;
131#endif
132
133/** @brief Set Timestamp to Seconds Nanosecond
134 *
135 *  This method sets the timestamp to the specified seconds and nanoseconds
136 *  value.
137 *
138 *  @param[in] _time points to the timestamp instance to validate.
139 *  @param[in] _seconds is the seconds portion of the timestamp
140 *  @param[in] _nanoseconds is the nanoseconds portion of the timestamp
141 */
142#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
143  #define _Timestamp_Set( _time, _seconds, _nanoseconds ) \
144          _Timespec_Set( _time, _seconds, _nanoseconds )
145#else
146  #define _Timestamp_Set( _time, _seconds, _nanoseconds ) \
147          _Timestamp64_Set( _time, _seconds, _nanoseconds )
148#endif
149
150/** @brief Zero Timestamp
151 *
152 *  This method sets the timestamp to zero.
153 *  value.
154 *
155 *  @param[in] _time points to the timestamp instance to zero.
156 */
157#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
158  #define _Timestamp_Set_to_zero( _time ) \
159          _Timespec_Set_to_zero( _time )
160#else
161  #define _Timestamp_Set_to_zero( _time ) \
162          _Timestamp64_Set_to_zero( _time )
163#endif
164
165/** @brief Is Timestamp Valid
166 *
167 *  This method determines the validity of a timestamp.
168 *
169 *  @param[in] _time points to the timestamp instance to validate.
170 *
171 *  @return This method returns true if @a time is valid and
172 *          false otherwise.
173 */
174#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
175  #define _Timestamp_Is_valid( _time ) \
176          _Timespec_Is_valid( _time )
177#else
178  #define _Timestamp_Is_valid( _time ) \
179          _Timestamp64_Is_valid( _time )
180#endif
181
182/** @brief Timestamp Less Than Operator
183 *
184 *  This method is the less than operator for timestamps.
185 *
186 *  @param[in] _lhs points to the left hand side timestamp
187 *  @param[in] _rhs points to the right hand side timestamp
188 *
189 *  @return This method returns true if @a _lhs is less than the @a _rhs and
190 *          false otherwise.
191 */
192#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
193  #define _Timestamp_Less_than( _lhs, _rhs ) \
194          _Timespec_Less_than( _lhs, _rhs )
195#else
196  #define _Timestamp_Less_than( _lhs, _rhs ) \
197          _Timestamp64_Less_than( _lhs, _rhs )
198#endif
199
200/** @brief Timestamp Greater Than Operator
201 *
202 *  This method is the greater than operator for timestamps.
203 *
204 *  @param[in] _lhs points to the left hand side timestamp
205 *  @param[in] _rhs points to the right hand side timestamp
206 *
207 *  @return This method returns true if @a _lhs is greater than the @a _rhs and
208 *          false otherwise.
209 */
210#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
211  #define _Timestamp_Greater_than( _lhs, _rhs ) \
212          _Timespec_Greater_than( _lhs, _rhs )
213#else
214  #define _Timestamp_Greater_than( _lhs, _rhs ) \
215          _Timestamp64_Greater_than( _lhs, _rhs )
216#endif
217
218/** @brief Timestamp equal to Operator
219 *
220 *  This method is the is equal to than operator for timestamps.
221 *
222 *  @param[in] _lhs points to the left hand side timestamp
223 *  @param[in] _rhs points to the right hand side timestamp
224 *
225 *  @return This method returns true if @a _lhs is equal to  @a _rhs and
226 *          false otherwise.
227 */
228#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
229  #define _Timestamp_Equal_to( _lhs, _rhs ) \
230          _Timespec_Equal_to( _lhs, _rhs )
231#else
232  #define _Timestamp_Equal_to( _lhs, _rhs ) \
233          _Timestamp64_Equal_to( _lhs, _rhs )
234#endif
235
236/** @brief Add to a Timestamp
237 *
238 *  This routine adds two timestamps.  The second argument is added
239 *  to the first.
240 *
241 *  @param[in] _time points to the base time to be added to
242 *  @param[in] _add points to the timestamp to add to the first argument
243 *
244 *  @return This method returns the number of seconds @a time increased by.
245 */
246#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
247  #define _Timestamp_Add_to( _time, _add ) \
248          _Timespec_Add_to( _time, _add )
249#else
250  #define _Timestamp_Add_to( _time, _add ) \
251          _Timestamp64_Add_to( _time, _add )
252#endif
253
254/** @brief Add to a Timestamp (At Clock Tick)
255 *
256 *  This routine adds two timestamps.  The second argument is added
257 *  to the first.
258 *
259 *  @node This routine places a special requirement on the addition
260 *        operation.  It must return the number of units that the
261 *        seconds field changed as the result of the addition.  Since this
262 *        operation is ONLY used as part of processing a clock tick,
263 *        it is generally safe to assume that only one second changed.
264 *
265 *  @param[in] _time points to the base time to be added to
266 *  @param[in] _add points to the timestamp to add to the first argument
267 *
268 *  @return This method returns the number of seconds @a time increased by.
269 */
270#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
271  #define _Timestamp_Add_to_at_tick( _time, _add ) \
272          _Timespec_Add_to( _time, _add )
273#else
274  #define _Timestamp_Add_to_at_tick( _time, _add ) \
275          _Timestamp64_Add_to_at_tick( _time, _add )
276#endif
277
278/** @brief Convert Timestamp to Number of Ticks
279 *
280 *  This routine convert the @a time timestamp to the corresponding number
281 *  of clock ticks.
282 *
283 *  @param[in] _time points to the time to be converted
284 *
285 *  @return This method returns the number of ticks computed.
286 */
287#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
288  #define _Timestamp_To_ticks( _time ) \
289          _Timespec_To_ticks( _time )
290#else
291  #define _Timestamp_To_ticks( _time ) \
292          _Timestamp64_To_ticks( _time )
293#endif
294
295/** @brief Convert Ticks to Timestamp
296 *
297 *  This routine converts the @a _ticks value to the corresponding
298 *  timestamp format @a _time.
299 *
300 *  @param[in] _time points to the timestamp format time result
301 *  @param[in] _ticks points to the number of ticks to be filled in
302 */
303#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
304  #define _Timestamp_From_ticks( _ticks, _time ) \
305          _Timespec_From_ticks( _ticks, _time )
306#else
307  #define _Timestamp_From_ticks( _ticks, _time ) \
308          _Timestamp64_From_ticks( _ticks, _time )
309#endif
310
311/** @brief Subtract Two Timestamp
312 *
313 *  This routine subtracts two timestamps.  @a result is set to
314 *  @a end - @a start.
315 *
316 *  @param[in] _start points to the starting time
317 *  @param[in] _end points to the ending time
318 *  @param[in] _result points to the difference between
319 *             starting and ending time.
320 *
321 *  @return This method fills in @a _result.
322 */
323#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
324  #define _Timestamp_Subtract( _start, _end, _result ) \
325          _Timespec_Subtract( _start, _end, _result )
326#else
327  #define _Timestamp_Subtract( _start, _end, _result ) \
328          _Timestamp64_Subtract( _start, _end, _result )
329#endif
330
331/** @brief Divide Timestamp By Integer
332 *
333 *  This routine divides a timestamp by an integer value.  The expected
334 *  use is to assist in benchmark calculations where you typically
335 *  divide a duration by a number of iterations.
336 *
337 *  @param[in] _time points to the total
338 *  @param[in] _iterations is the number of iterations
339 *  @param[in] _result points to the average time.
340 *
341 *  @return This method fills in @a result.
342 */
343#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
344  #define _Timestamp_Divide_by_integer( _time, _iterations, _result ) \
345          _Timespec_Divide_by_integer(_time, _iterations, _result )
346#else
347  #define _Timestamp_Divide_by_integer( _time, _iterations, _result ) \
348          _Timestamp64_Divide_by_integer( _time, _iterations, _result )
349#endif
350
351/** @brief Divide Timestamp
352 *
353 *  This routine divides a timestamp by another timestamp.  The
354 *  intended use is for calculating percentages to three decimal points.
355 *
356 *  @param[in] _lhs points to the left hand number
357 *  @param[in] _rhs points to the right hand number
358 *  @param[in] _ival_percentage points to the integer portion of the average
359 *  @param[in] _fval_percentage points to the thousandths of percentage
360 *
361 *  @return This method fills in @a result.
362 */
363#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
364  #define _Timestamp_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage ) \
365          _Timespec_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage )
366#else
367  #define _Timestamp_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage ) \
368          _Timestamp64_Divide( _lhs, _rhs, _ival_percentage, _fval_percentage )
369#endif
370
371/** @brief Get Seconds Portion of Timestamp
372 *
373 *  This method returns the seconds portion of the specified timestamp
374 *
375 *  @param[in] _time points to the timestamp
376 *
377 *  @return The seconds portion of @a _time.
378 */
379#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
380  #define _Timestamp_Get_seconds( _time ) \
381          _Timespec_Get_seconds( _time )
382#else
383  #define _Timestamp_Get_seconds( _time ) \
384          _Timestamp64_Get_seconds( _time )
385#endif
386
387/** @brief Get Nanoseconds Portion of Timestamp
388 *
389 *  This method returns the nanoseconds portion of the specified timestamp
390 *
391 *  @param[in] _time points to the timestamp
392 *
393 *  @return The nanoseconds portion of @a _time.
394 */
395#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
396  #define _Timestamp_Get_nanoseconds( _time ) \
397          _Timespec_Get_nanoseconds( _time )
398#else
399  #define _Timestamp_Get_nanoseconds( _time ) \
400          _Timestamp64_Get_nanoseconds( _time )
401#endif
402
403/** @brief Convert Timestamp to struct timespec
404 *
405 *  This method returns the seconds portion of the specified timestamp
406 *
407 *  @param[in] _timestamp points to the timestamp
408 *  @param[in] _timespec points to the timespec
409 */
410#if defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_STRUCT_SPEC)
411  /* in this case we know they are the same type so use simple assignment */
412  #define _Timestamp_To_timespec( _timestamp, _timespec  ) \
413          *(_timespec) = *(_timestamp)
414#else
415  #define _Timestamp_To_timespec( _timestamp, _timespec  ) \
416          _Timestamp64_To_timespec( _timestamp, _timespec  )
417#endif
418
419#ifdef __cplusplus
420}
421#endif
422
423/**@}*/
424
425#endif
426/* end of include file */
Note: See TracBrowser for help on using the repository browser.