source: rtems/cpukit/include/rtems/rtems/clock.h @ 98c01a5

Last change on this file since 98c01a5 was 98c01a5, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 10:32:13 AM

rtems: Avoid <rtems/score/timecounter.h> in API

Use a real function for rtems_clock_get_uptime_seconds().

Update #3598.

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