source: rtems/cpukit/score/include/rtems/score/timestamp64.h @ d4dc7c8

4.115
Last change on this file since d4dc7c8 was 48e77eb9, checked in by Ralf Corsepius <ralf.corsepius@…>, on 06/12/10 at 05:56:26

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: 10.0 KB
Line 
1/**
2 *  @file  rtems/score/timestamp64.h
3 *
4 *  This include file contains helpers for manipulating
5 *  64-bit integer timestamps.
6 */
7
8/*
9 *  COPYRIGHT (c) 1989-2008.
10 *  On-Line Applications Research Corporation (OAR).
11 *
12 *  The license and distribution terms for this file may be
13 *  found in the file LICENSE in this distribution or at
14 *  http://www.rtems.com/license/LICENSE.
15 *
16 *  $Id$
17 */
18
19#ifndef _RTEMS_SCORE_TIMESTAMP64_H
20#define _RTEMS_SCORE_TIMESTAMP64_H
21
22/**
23 *  @defgroup SuperCore Timestamp64
24 *
25 *  This handler encapsulates functionality related to manipulating
26 *  the 64 bit integer implementation of SuperCore Timestamps.
27 */
28/**@{*/
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34/*
35 *  This .h file is not for general use.  It is an alternative
36 *  implementation of Timestamps and should only be used that way.
37 */
38#ifndef _RTEMS_SCORE_TIMESTAMP_H
39  #error "Should only be included by rtems/score/timestamp.h"
40#endif
41
42/*
43 *  Verify something is defined.
44 */
45#if !defined(CPU_RTEMS_SCORE_TIMESTAMP_IS_INT64)
46  #error "SuperCore Timestamp64 implementation included but not defined."
47#endif
48
49/**
50 *   Define the Timestamp control type.
51 */
52typedef int64_t Timestamp64_Control;
53
54/** @brief Set Timestamp to Seconds Nanosecond
55 *
56 *  This method sets the timestamp to the specified seconds and nanoseconds
57 *  value.
58 *
59 *  @param[in] _time points to the timestamp instance to validate.
60 *  @param[in] _seconds is the seconds portion of the timestamp
61 *  @param[in] _nanoseconds is the nanoseconds portion of the timestamp
62 */
63#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
64  #define _Timestamp64_Set( _time, _seconds, _nanoseconds ) \
65          do { \
66            *(_time) = ((int64_t)_seconds * 1000000000); \
67            *(_time) += (int64_t)(_nanoseconds); \
68          } while (0)
69#else
70  void _Timestamp64_Set(
71    Timestamp64_Control *_time,
72    long                _seconds,
73    long                _nanoseconds
74  );
75#endif
76
77/** @brief Zero Timestamp
78 *
79 *  This method sets the timestamp to zero.
80 *  value.
81 *
82 *  @param[in] _time points to the timestamp instance to zero.
83 */
84#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
85  #define _Timestamp64_Set_to_zero( _time ) \
86          *(_time) = 0
87#else
88  void _Timestamp64_Set_to_zero(
89    Timestamp64_Control *_time
90  );
91#endif
92
93/** @brief Is Timestamp Valid
94 *
95 *  This method determines the validity of a timestamp.
96 *
97 *  @param[in] _time points to the timestamp instance to validate.
98 *
99 *  @return This method returns true if @a time is valid and
100 *          false otherwise.
101 */
102#define _Timestamp64_Is_valid( _time ) \
103        (1)
104
105/** @brief Timestamp Less Than Operator
106 *
107 *  This method is the less than operator for timestamps.
108 *
109 *  @param[in] _lhs points to the left hand side timestamp
110 *  @param[in] _rhs points to the right hand side timestamp
111 *
112 *  @return This method returns true if @a _lhs is less than the @a _rhs and
113 *          false otherwise.
114 */
115#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
116  #define _Timestamp64_Less_than( _lhs, _rhs ) \
117          (*(_lhs) < *(_rhs))
118#else
119  bool _Timestamp64_Less_than(
120    Timestamp64_Control *_lhs,
121    Timestamp64_Control *_rhs
122  );
123#endif
124
125/** @brief Timestamp Greater Than Operator
126 *
127 *  This method is the greater than operator for timestamps.
128 *
129 *  @param[in] _lhs points to the left hand side timestamp
130 *  @param[in] _rhs points to the right hand side timestamp
131 *
132 *  @return This method returns true if @a _lhs is greater than the @a _rhs and
133 *          false otherwise.
134 */
135#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
136  #define _Timestamp64_Greater_than( _lhs, _rhs ) \
137          (*(_lhs) > *(_rhs))
138#else
139  bool _Timestamp64_Greater_than(
140    Timestamp64_Control *_lhs,
141    Timestamp64_Control *_rhs
142  );
143#endif
144
145/** @brief Timestamp equal to Operator
146 *
147 *  This method is the is equal to than operator for timestamps.
148 *
149 *  @param[in] _lhs points to the left hand side timestamp
150 *  @param[in] _rhs points to the right hand side timestamp
151 *
152 *  @return This method returns true if @a _lhs is equal to  @a _rhs and
153 *          false otherwise.
154 */
155#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
156  #define _Timestamp64_Equal_to( _lhs, _rhs ) \
157          (*(_lhs) == *(_rhs))
158#else
159  bool _Timestamp64_Equal_to(
160    Timestamp64_Control *_lhs,
161    Timestamp64_Control *_rhs
162  );
163#endif
164
165/** @brief Add to a Timestamp
166 *
167 *  This routine adds two timestamps.  The second argument is added
168 *  to the first.
169 *
170 *  @param[in] _time points to the base time to be added to
171 *  @param[in] _add points to the timestamp to add to the first argument
172 *
173 *  @return This method returns the number of seconds @a time increased by.
174 */
175#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
176  #define _Timestamp64_Add_to( _time, _add ) \
177          *(_time) += *(_add)
178#else
179  void _Timestamp64_Add_to(
180    Timestamp64_Control *_time,
181    Timestamp64_Control *_add
182  );
183#endif
184
185/** @brief Add to a Timestamp (At Clock Tick)
186 *
187 *  This routine adds two timestamps.  The second argument is added
188 *  to the first.
189 *
190 *  @node This routine places a special requirement on the addition
191 *        operation.  It must return the number of units that the
192 *        seconds field changed as the result of the addition.  Since this
193 *        operation is ONLY used as part of processing a clock tick,
194 *        it is generally safe to assume that only one second changed.
195 *
196 *  @param[in] _time points to the base time to be added to
197 *  @param[in] _add points to the timestamp to add to the first argument
198 *
199 *  @return This method returns the number of seconds @a time increased by.
200 */
201static inline uint32_t _Timestamp64_Add_to_at_tick(
202  Timestamp64_Control *_time,
203  Timestamp64_Control *_add
204)
205{
206  Timestamp64_Control start = *_time / 1000000000;
207  *_time += *_add;
208  if ( ((*_time) / 1000000000) != start ) {
209    return 1;
210  }
211  return 0;
212}
213
214/** @brief Convert Timestamp to Number of Ticks
215 *
216 *  This routine convert the @a time timestamp to the corresponding number
217 *  of clock ticks.
218 *
219 *  @param[in] _time points to the time to be converted
220 *
221 *  @return This method returns the number of ticks computed.
222 */
223uint32_t _Timestamp64_To_ticks(
224  const Timestamp64_Control *_time
225);
226
227/** @brief Convert Ticks to Timestamp
228 *
229 *  This routine converts the @a _ticks value to the corresponding
230 *  timestamp format @a _time.
231 *
232 *  @param[in] _time points to the timestamp format time result
233 *  @param[in] _ticks points to the number of ticks to be filled in
234 */
235void _Timestamp64_From_ticks(
236  uint32_t             _ticks,
237  Timestamp64_Control *_time
238);
239
240/** @brief Subtract Two Timestamp
241 *
242 *  This routine subtracts two timestamps.  @a result is set to
243 *  @a end - @a start.
244 *
245 *  @param[in] _start points to the starting time
246 *  @param[in] _end points to the ending time
247 *  @param[in] _result points to the difference between
248 *             starting and ending time.
249 *
250 *  @return This method fills in @a _result.
251 */
252#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
253  #define _Timestamp64_Subtract( _start, _end, _result ) \
254          do { \
255             *(_result) = *(_end) - *(_start); \
256          } while (0)
257#else
258  void _Timestamp64_Subtract(
259    Timestamp64_Control *_start,
260    Timestamp64_Control *_end,
261    Timestamp64_Control *_result
262  );
263#endif
264
265/** @brief Divide Timestamp By Integer
266 *
267 *  This routine divides a timestamp by an integer value.  The expected
268 *  use is to assist in benchmark calculations where you typically
269 *  divide a duration by a number of iterations.
270 *
271 *  @param[in] _time points to the total
272 *  @param[in] _iterations is the number of iterations
273 *  @param[in] _result points to the average time.
274 *
275 *  @return This method fills in @a result.
276 */
277#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
278  #define _Timestamp64_Divide_by_integer( _time, _iterations, _result ) \
279          do { \
280             *(_result) = *(_time) / (_iterations); \
281          } while (0)
282#else
283  void _Timestamp64_Divide_by_integer(
284    Timestamp64_Control *_time,
285    uint32_t             _iterations,
286    Timestamp64_Control *_result
287  );
288#endif
289
290/** @brief Divide Timestamp
291 *
292 *  This routine divides a timestamp by another timestamp.  The
293 *  intended use is for calculating percentages to three decimal points.
294 *
295 *  @param[in] _lhs points to the left hand number
296 *  @param[in] _rhs points to the right hand number
297 *  @param[in] _ival_percentage points to the integer portion of the average
298 *  @param[in] _fval_percentage points to the thousandths of percentage
299 *
300 *  @return This method fills in @a result.
301 */
302void _Timestamp64_Divide(
303  const Timestamp64_Control *_lhs,
304  const Timestamp64_Control *_rhs,
305  uint32_t                  *_ival_percentage,
306  uint32_t                  *_fval_percentage
307);
308
309/** @brief Get Seconds Portion of Timestamp
310 *
311 *  This method returns the seconds portion of the specified timestamp
312 *
313 *  @param[in] _time points to the timestamp
314 *
315 *  @return The seconds portion of @a _time.
316 */
317#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
318  #define _Timestamp64_Get_seconds( _time ) \
319          (*(_time) / 1000000000)
320#else
321  uint32_t _Timestamp64_Get_seconds(
322    Timestamp64_Control *_time
323  );
324#endif
325
326/** @brief Get Nanoseconds Portion of Timestamp
327 *
328 *  This method returns the nanoseconds portion of the specified timestamp
329 *
330 *  @param[in] _time points to the timestamp
331 *
332 *  @return The nanoseconds portion of @a _time.
333 */
334#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
335  #define _Timestamp64_Get_nanoseconds( _time ) \
336          (*(_time) % 1000000000)
337#else
338  uint32_t _Timestamp64_Get_nanoseconds(
339    Timestamp64_Control *_time
340  );
341#endif
342
343/** @brief Convert Timestamp to struct timespec
344 *
345 *  This method returns the seconds portion of the specified timestamp
346 *
347 *  @param[in] _timestamp points to the timestamp
348 *  @param[in] _timespec points to the timespec
349 */
350#if defined(CPU_RTEMS_SCORE_TIMESTAMP_INT64_INLINE)
351  #define _Timestamp64_To_timespec( _timestamp, _timespec  ) \
352        do { \
353          (_timespec)->tv_sec = *(_timestamp) / 1000000000; \
354          (_timespec)->tv_nsec = *(_timestamp) % 1000000000; \
355        } while (0)
356#else
357  void _Timestamp64_To_timespec(
358    Timestamp64_Control *_timestamp,
359    struct timespec     *_timespec
360  );
361#endif
362
363#ifdef __cplusplus
364}
365#endif
366
367/**@}*/
368
369#endif
370/* end of include file */
Note: See TracBrowser for help on using the repository browser.