source: rtems/cpukit/include/rtems/rtems/clock.h @ ccc6695

Last change on this file since ccc6695 was ccc6695, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 10:50:24 AM

score: Introduce <rtems/score/watchdogticks.h>

Separate the definitions related to watchdog ticks from the watchdog
structures.

Update #3598.

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