source: rtems/cpukit/include/rtems/rtems/clock.h @ 742d6db

Last change on this file since 742d6db was 742d6db, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 10:14:04 AM

score: Remove empty <rtems/score/tod.h>

Update #3598.

  • Property mode set to 100644
File size: 8.3 KB
Line 
1/**
2 * @file rtems/rtems/clock.h
3 *
4 * @defgroup ClassicClock Clocks
5 *
6 * @ingroup ClassicRTEMS
7 * @brief Clock Manager API
8 *
9 * This include file contains all the constants and structures associated
10 * with the Clock Manager. This manager provides facilities to set, obtain,
11 * and continually update the current date and time.
12 *
13 * This manager provides directives to:
14 *
15 * - set the current date and time
16 * - obtain the current date and time
17 * - announce a clock tick
18 * - obtain the system uptime
19 */
20
21/* COPYRIGHT (c) 1989-2013.
22 * On-Line Applications Research Corporation (OAR).
23 *
24 * The license and distribution terms for this file may be
25 * found in the file LICENSE in this distribution or at
26 * http://www.rtems.org/license/LICENSE.
27 */
28
29#ifndef _RTEMS_RTEMS_CLOCK_H
30#define _RTEMS_RTEMS_CLOCK_H
31
32#include <rtems/score/watchdog.h>
33#include <rtems/rtems/status.h>
34#include <rtems/rtems/types.h>
35#include <rtems/config.h>
36#include <rtems/score/timecounterimpl.h>
37
38#include <sys/time.h> /* struct timeval */
39
40/**
41 *  @defgroup ClassicClock Clocks
42 *
43 *  @ingroup ClassicRTEMS
44 *
45 *  This encapsulates functionality related to the Classic API Clock
46 *  Manager.
47 */
48/**@{*/
49
50#ifdef __cplusplus
51extern "C" {
52#endif
53
54/**
55 * @brief Obtain Current Time of Day (Classic TOD)
56 *
57 * This routine implements the rtems_clock_get_tod directive. It returns
58 * the current time of day in the format defined by RTEID.
59 *
60 * Clock Manager - rtems_clock_get_tod
61 *
62 * @param[in] time_buffer points to the time of day structure
63 *
64 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
65 *         error. Otherwise, a status code is returned indicating the
66 *         source of the error. If successful, the time_buffer will
67 *         be filled in with the current time of day.
68 */
69rtems_status_code rtems_clock_get_tod(
70  rtems_time_of_day *time_buffer
71);
72
73/**
74 * @brief Obtain TOD in struct timeval Format
75 *
76 * This routine implements the rtems_clock_get_tod_timeval
77 * directive.
78 *
79 * @param[in] time points to the struct timeval variable to fill in
80 *
81 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
82 *         error. Otherwise, a status code is returned indicating the
83 *         source of the error. If successful, the time will
84 *         be filled in with the current time of day.
85 */
86rtems_status_code rtems_clock_get_tod_timeval(
87  struct timeval *time
88);
89
90/**
91 * @brief Obtain Seconds Since Epoch
92 *
93 * This routine implements the rtems_clock_get_seconds_since_epoch
94 * directive.
95 *
96 * @param[in] the_interval points to the interval variable to fill in
97 *
98 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
99 *         error. Otherwise, a status code is returned indicating the
100 *         source of the error. If successful, the time_buffer will
101 *         be filled in with the current time of day.
102 */
103rtems_status_code rtems_clock_get_seconds_since_epoch(
104  rtems_interval *the_interval
105);
106
107/**
108 * @brief Gets the current ticks counter value.
109 *
110 * @return The current tick counter value.  With a 1ms clock tick, this counter
111 * overflows after 50 days since boot.
112 */
113RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_get_ticks_since_boot(void)
114{
115  return _Watchdog_Ticks_since_boot;
116}
117
118/**
119 * @brief Returns the ticks counter value delta ticks in the future.
120 *
121 * @param[in] delta The ticks delta value.
122 *
123 * @return The tick counter value delta ticks in the future.
124 */
125RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_tick_later(
126  rtems_interval delta
127)
128{
129  return _Watchdog_Ticks_since_boot + delta;
130}
131
132/**
133 * @brief Returns the ticks counter value at least delta microseconds in the
134 * future.
135 *
136 * @param[in] delta_in_usec The delta value in microseconds.
137 *
138 * @return The tick counter value at least delta microseconds in the future.
139 */
140RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_tick_later_usec(
141  rtems_interval delta_in_usec
142)
143{
144  rtems_interval us_per_tick = rtems_configuration_get_microseconds_per_tick();
145
146  /*
147   * Add one additional tick, since we don't know the time to the clock next
148   * tick.
149   */
150  return _Watchdog_Ticks_since_boot
151    + (delta_in_usec + us_per_tick - 1) / us_per_tick + 1;
152}
153
154/**
155 * @brief Returns true if the current ticks counter value indicates a time
156 * before the time specified by the tick value and false otherwise.
157 *
158 * @param[in] tick The tick value.
159 *
160 * This can be used to write busy loops with a timeout.
161 *
162 * @code
163 * status busy( void )
164 * {
165 *   rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
166 *
167 *   do {
168 *     if ( ok() ) {
169 *       return success;
170 *     }
171 *   } while ( rtems_clock_tick_before( timeout ) );
172 *
173 *   return timeout;
174 * }
175 * @endcode
176 *
177 * @retval true The current ticks counter value indicates a time before the
178 * time specified by the tick value.
179 * @retval false Otherwise.
180 */
181RTEMS_INLINE_ROUTINE bool rtems_clock_tick_before(
182  rtems_interval tick
183)
184{
185  return (int32_t) ( tick - _Watchdog_Ticks_since_boot ) > 0;
186}
187
188/**
189 * @brief Obtain Ticks Per Seconds
190 *
191 * This routine implements the rtems_clock_get_ticks_per_second
192 * directive.
193 *
194 * @retval This method returns the number of ticks per second. It cannot
195 *         fail since RTEMS is always configured to know the number of
196 *         ticks per second.
197 */
198rtems_interval rtems_clock_get_ticks_per_second(void);
199
200/* Optimized variant for C/C++ without function call overhead */
201#define rtems_clock_get_ticks_per_second() ( _Watchdog_Ticks_per_second )
202
203/**
204 * @brief Set the Current TOD
205 *
206 * This routine implements the rtems_clock_set directive. It sets
207 * the current time of day to that in the time_buffer record.
208 *
209 * @param[in] time_buffer points to the new TOD
210 *
211 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
212 *         error. Otherwise, a status code is returned indicating the
213 *         source of the error.
214 *
215 * @note Activities scheduled based upon the current time of day
216 *       may be executed immediately if the time is moved forward.
217 */
218rtems_status_code rtems_clock_set(
219  const rtems_time_of_day *time_buffer
220);
221
222/**
223 * @brief Announce a Clock Tick
224 *
225 * This routine implements the rtems_clock_tick directive. It is invoked
226 * to inform RTEMS of the occurrence of a clock tick.
227 *
228 * @retval This directive always returns RTEMS_SUCCESSFUL.
229 *
230 * @note This method is typically called from an ISR and is the basis
231 *       for all timeouts and delays. This routine only works for leap-years
232 *       through 2099.
233 */
234rtems_status_code rtems_clock_tick( void );
235
236/**
237 * @brief Obtain the System Uptime
238 *
239 * This directive returns the system uptime.
240 *
241 * @param[in] uptime is a pointer to the time structure
242 *
243 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
244 *         error. Otherwise, a status code is returned indicating the
245 *         source of the error. If successful, the @a uptime will be
246 *         filled in.
247 */
248rtems_status_code rtems_clock_get_uptime(
249  struct timespec *uptime
250);
251
252/**
253 * @brief Gets the System Uptime in the Struct Timeval Format
254 *
255 * @param[out] uptime is a pointer to a struct timeval structure.
256 *
257 * @retval This methods returns the system uptime.
258 *
259 * @note Pointer must not be NULL.
260 */
261void rtems_clock_get_uptime_timeval( struct timeval *uptime );
262
263/**
264 * @brief Returns the system uptime in seconds.
265 *
266 * @retval The system uptime in seconds.
267 */
268RTEMS_INLINE_ROUTINE time_t rtems_clock_get_uptime_seconds( void )
269{
270  return _Timecounter_Time_uptime - 1;
271}
272
273/**
274 * @brief Returns the system uptime in nanoseconds.
275 *
276 * @retval The system uptime in nanoseconds.
277 */
278uint64_t rtems_clock_get_uptime_nanoseconds( void );
279
280/**
281 * @brief TOD Validate
282 *
283 * This support function returns true if @a the_tod contains
284 * a valid time of day, and false otherwise.
285 *
286 * @param[in] the_tod is the TOD structure to validate
287 *
288 * @retval This method returns true if the TOD is valid and false otherwise.
289 *
290 * @note This routine only works for leap-years through 2099.
291 */
292bool _TOD_Validate(
293  const rtems_time_of_day *the_tod
294);
295
296/**
297 * @brief TOD to Seconds
298 *
299 * This function returns the number seconds between the epoch and @a the_tod.
300 *
301 * @param[in] the_tod is the TOD structure to convert to seconds
302 *
303 * @retval This method returns the number of seconds since epoch represented
304 *         by @a the_tod
305 */
306Watchdog_Interval _TOD_To_seconds(
307  const rtems_time_of_day *the_tod
308);
309
310#ifdef __cplusplus
311}
312#endif
313
314/**@}*/
315
316#endif
317/* end of include file */
Note: See TracBrowser for help on using the repository browser.