source: rtems/cpukit/score/include/rtems/score/todimpl.h @ 2256946

Last change on this file since 2256946 was 2256946, checked in by Sebastian Huber <sebastian.huber@…>, on Oct 6, 2017 at 1:30:47 PM

score: Use struct timespec for TOD

Use the timestamps only for uptime based values. Use struct timespec
for the absolute time values (TOD).

Update #2740.

  • Property mode set to 100644
File size: 8.4 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup ScoreTOD
5 *
6 * @brief Time of Day Handler API
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_TODIMPL_H
19#define _RTEMS_SCORE_TODIMPL_H
20
21#include <rtems/score/tod.h>
22#include <rtems/score/apimutex.h>
23#include <rtems/score/timestamp.h>
24#include <rtems/score/timecounterimpl.h>
25#include <rtems/score/watchdog.h>
26
27#include <sys/time.h>
28#include <time.h>
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34/**
35 *  @defgroup ScoreTOD Time of Day Handler
36 *
37 *  @ingroup Score
38 *
39 *  The following constants are related to the time of day and are
40 *  independent of RTEMS.
41 */
42/**@{*/
43
44/**
45 *  This constant represents the number of seconds in a minute.
46 */
47#define TOD_SECONDS_PER_MINUTE (uint32_t)60
48
49/**
50 *  This constant represents the number of minutes per hour.
51 */
52#define TOD_MINUTES_PER_HOUR   (uint32_t)60
53
54/**
55 *  This constant represents the number of months in a year.
56 */
57#define TOD_MONTHS_PER_YEAR    (uint32_t)12
58
59/**
60 *  This constant represents the number of days in a non-leap year.
61 */
62#define TOD_DAYS_PER_YEAR      (uint32_t)365
63
64/**
65 *  This constant represents the number of hours per day.
66 */
67#define TOD_HOURS_PER_DAY      (uint32_t)24
68
69/**
70 *  This constant represents the number of seconds in a day which does
71 *  not include a leap second.
72 */
73#define TOD_SECONDS_PER_DAY    (uint32_t) (TOD_SECONDS_PER_MINUTE * \
74                                TOD_MINUTES_PER_HOUR   * \
75                                TOD_HOURS_PER_DAY)
76
77/**
78 *  This constant represents the number of seconds in a non-leap year.
79 */
80#define TOD_SECONDS_PER_NON_LEAP_YEAR (365 * TOD_SECONDS_PER_DAY)
81
82/**
83 *  This constant represents the number of millisecond in a second.
84 */
85#define TOD_MILLISECONDS_PER_SECOND     (uint32_t)1000
86
87/**
88 *  This constant represents the number of microseconds in a second.
89 */
90#define TOD_MICROSECONDS_PER_SECOND     (uint32_t)1000000
91
92/**
93 *  This constant represents the number of nanoseconds in a second.
94 */
95#define TOD_NANOSECONDS_PER_SECOND      (uint32_t)1000000000
96
97/**
98 *  This constant represents the number of nanoseconds in a mircosecond.
99 */
100#define TOD_NANOSECONDS_PER_MICROSECOND (uint32_t)1000
101
102/**@}*/
103
104/**
105 *  Seconds from January 1, 1970 to January 1, 1988.  Used to account for
106 *  differences between POSIX API and RTEMS core. The timespec format time
107 *  is kept in POSIX compliant form.
108 */
109#define TOD_SECONDS_1970_THROUGH_1988 \
110  (((1987 - 1970 + 1)  * TOD_SECONDS_PER_NON_LEAP_YEAR) + \
111  (4 * TOD_SECONDS_PER_DAY))
112
113/**
114 *  @brief Earliest year to which an time of day can be initialized.
115 *
116 *  The following constant define the earliest year to which an
117 *  time of day can be initialized.  This is considered the
118 *  epoch.
119 */
120#define TOD_BASE_YEAR 1988
121
122/**
123 *  @defgroup ScoreTOD Time Of Day (TOD) Handler
124 *
125 *  @ingroup Score
126 *
127 *  This handler encapsulates functionality used to manage time of day.
128 */
129/**@{*/
130
131/**
132 *  @brief TOD control.
133 */
134typedef struct {
135  /**
136   *  @brief Indicates if the time of day is set.
137   *
138   *  This is true if the application has set the current
139   *  time of day, and false otherwise.
140   */
141  bool is_set;
142} TOD_Control;
143
144extern TOD_Control _TOD;
145
146static inline void _TOD_Lock( void )
147{
148  /* FIXME: https://devel.rtems.org/ticket/2630 */
149  _API_Mutex_Lock( _Once_Mutex );
150}
151
152static inline void _TOD_Unlock( void )
153{
154  _API_Mutex_Unlock( _Once_Mutex );
155}
156
157static inline void _TOD_Acquire( ISR_lock_Context *lock_context )
158{
159  _Timecounter_Acquire( lock_context );
160}
161
162/**
163 * @brief Sets the time of day.
164 *
165 * The caller must be the owner of the TOD lock.
166 *
167 * @param tod The new time of day in timespec format representing
168 *   the time since UNIX Epoch.
169 * @param lock_context The ISR lock context used for the corresponding
170 *   _TOD_Acquire().  The caller must be the owner of the TOD lock.  This
171 *   function will release the TOD lock.
172 */
173void _TOD_Set(
174  const struct timespec *tod,
175  ISR_lock_Context      *lock_context
176);
177
178/**
179 *  @brief Gets the current time in the timespec format.
180 *
181 *  @param[out] time is the value gathered by the request
182 */
183static inline void _TOD_Get(
184  struct timespec *tod
185)
186{
187  _Timecounter_Nanotime( tod );
188}
189
190/**
191 *  @brief Gets the system uptime with potential accuracy to the nanosecond.
192 *
193 *  This routine returns the system uptime with potential accuracy
194 *  to the nanosecond.
195 *
196 *  The initial uptime value is undefined.
197 *
198 *  @param[in] time is a pointer to the uptime to be returned
199 */
200static inline void _TOD_Get_uptime(
201  Timestamp_Control *time
202)
203{
204  _Timecounter_Binuptime( time );
205}
206
207/**
208 *  @brief Gets the system uptime with potential accuracy to the nanosecond.
209 *  to the nanosecond.
210 *
211 *  The initial uptime value is zero.
212 *
213 *  @param[in] time is a pointer to the uptime to be returned
214 */
215static inline void _TOD_Get_zero_based_uptime(
216  Timestamp_Control *time
217)
218{
219  _Timecounter_Binuptime( time );
220  --time->sec;
221}
222
223/**
224 *  @brief Gets the system uptime with potential accuracy to the nanosecond.
225 *
226 *  The initial uptime value is zero.
227 *
228 *  @param[in] time is a pointer to the uptime to be returned
229 */
230static inline void _TOD_Get_zero_based_uptime_as_timespec(
231  struct timespec *time
232)
233{
234  _Timecounter_Nanouptime( time );
235  --time->tv_sec;
236}
237
238/**
239 *  @brief Number of seconds Since RTEMS epoch.
240 *
241 *  The following contains the number of seconds from 00:00:00
242 *  January 1, TOD_BASE_YEAR until the current time of day.
243 */
244static inline uint32_t _TOD_Seconds_since_epoch( void )
245{
246  return (uint32_t) _Timecounter_Time_second;
247}
248
249/**
250 *  @brief Gets number of ticks in a second.
251 *
252 *  This method returns the number of ticks in a second.
253 *
254 *  @note If the clock tick value does not multiply evenly into a second
255 *        then this number of ticks will be slightly shorter than a second.
256 */
257uint32_t TOD_TICKS_PER_SECOND_method(void);
258
259/**
260 *  @brief Gets number of ticks in a second.
261 *
262 *  This method exists to hide the fact that TOD_TICKS_PER_SECOND can not
263 *  be implemented as a macro in a .h file due to visibility issues.
264 *  The Configuration Table is not available to SuperCore .h files but
265 *  is available to their .c files.
266 */
267#define TOD_TICKS_PER_SECOND TOD_TICKS_PER_SECOND_method()
268
269/**
270 * This routine returns a timeval based upon the internal timespec format TOD.
271 */
272
273RTEMS_INLINE_ROUTINE void _TOD_Get_timeval(
274  struct timeval *time
275)
276{
277  _Timecounter_Microtime( time );
278}
279
280/**
281 * @brief Adjust the Time of Time
282 *
283 * This method is used to adjust the current time of day by the
284 * specified amount.
285 *
286 * @param[in] delta is the amount to adjust
287 */
288void _TOD_Adjust(
289  const struct timespec *delta
290);
291
292/**
293 * @brief Check if the TOD is Set
294 *
295 * @return TRUE is the time is set. FALSE otherwise.
296 */
297RTEMS_INLINE_ROUTINE bool _TOD_Is_set( void )
298{
299  return _TOD.is_set;
300}
301
302/**
303 * @brief Absolute timeout conversion results.
304 *
305 * This enumeration defines the possible results of converting
306 * an absolute time used for timeouts to POSIX blocking calls to
307 * a number of ticks for example.
308 */
309typedef enum {
310  /** The timeout is invalid. */
311  TOD_ABSOLUTE_TIMEOUT_INVALID,
312  /** The timeout represents a time that is in the past. */
313  TOD_ABSOLUTE_TIMEOUT_IS_IN_PAST,
314  /** The timeout represents a time that is equal to the current time. */
315  TOD_ABSOLUTE_TIMEOUT_IS_NOW,
316  /** The timeout represents a time that is in the future. */
317  TOD_ABSOLUTE_TIMEOUT_IS_IN_FUTURE,
318} TOD_Absolute_timeout_conversion_results;
319
320/**
321 * @brief Convert absolute timeout to ticks.
322 *
323 * This method takes an absolute time being used as a timeout
324 * to a blocking directive, validates it and returns the number
325 * of corresponding clock ticks for use by the SuperCore.
326 *
327 * @param[in] abstime is a pointer to the timeout
328 * @param[in] clock is the time source to use for the timeout
329 * @param[out] ticks_out will contain the number of ticks
330 *
331 * @return This method returns the number of ticks in @a ticks_out
332 *         and a status value indicating whether the absolute time
333 *         is valid, in the past, equal to the current time or in
334 *         the future as it should be.
335 */
336TOD_Absolute_timeout_conversion_results _TOD_Absolute_timeout_to_ticks(
337  const struct timespec *abstime,
338  clockid_t              clock,
339  Watchdog_Interval     *ticks_out
340);
341
342/**@}*/
343
344#ifdef __cplusplus
345}
346#endif
347
348#endif
349/* end of include file */
Note: See TracBrowser for help on using the repository browser.