source: rtems/cpukit/include/rtems/rtems/clock.h @ 55c6cb1d

Last change on this file since 55c6cb1d was 55c6cb1d, checked in by Sebastian Huber <sebastian.huber@…>, on Apr 22, 2021 at 1:57:19 PM

rtems: Clarify constraints in documentation

  • Property mode set to 100644
File size: 16.8 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
6 * @brief This header file defines the Clock Manager API.
7 */
8
9/*
10 * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
11 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
12 *
13 * Redistribution and use in source and binary forms, with or without
14 * modification, are permitted provided that the following conditions
15 * are met:
16 * 1. Redistributions of source code must retain the above copyright
17 *    notice, this list of conditions and the following disclaimer.
18 * 2. Redistributions in binary form must reproduce the above copyright
19 *    notice, this list of conditions and the following disclaimer in the
20 *    documentation and/or other materials provided with the distribution.
21 *
22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32 * POSSIBILITY OF SUCH DAMAGE.
33 */
34
35/*
36 * This file is part of the RTEMS quality process and was automatically
37 * generated.  If you find something that needs to be fixed or
38 * worded better please post a report or patch to an RTEMS mailing list
39 * or raise a bug report:
40 *
41 * https://www.rtems.org/bugs.html
42 *
43 * For information on updating and regenerating please refer to the How-To
44 * section in the Software Requirements Engineering chapter of the
45 * RTEMS Software Engineering manual.  The manual is provided as a part of
46 * a release.  For development sources please refer to the online
47 * documentation at:
48 *
49 * https://docs.rtems.org
50 */
51
52/* Generated from spec:/rtems/clock/if/header */
53
54#ifndef _RTEMS_RTEMS_CLOCK_H
55#define _RTEMS_RTEMS_CLOCK_H
56
57#include <stdbool.h>
58#include <stdint.h>
59#include <time.h>
60#include <rtems/config.h>
61#include <sys/_timespec.h>
62#include <sys/_timeval.h>
63#include <rtems/rtems/status.h>
64#include <rtems/rtems/types.h>
65#include <rtems/score/watchdogticks.h>
66
67#ifdef __cplusplus
68extern "C" {
69#endif
70
71/* Generated from spec:/rtems/clock/if/group */
72
73/**
74 * @defgroup RTEMSAPIClassicClock Clock Manager
75 *
76 * @ingroup RTEMSAPIClassic
77 *
78 * @brief The Clock Manager provides support for time of day and other time
79 *   related capabilities.
80 */
81
82/* Generated from spec:/rtems/clock/if/set */
83
84/**
85 * @ingroup RTEMSAPIClassicClock
86 *
87 * @brief Sets the CLOCK_REALTIME to the time of day.
88 *
89 * @param time_of_day is the time of day to set the clock.
90 *
91 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
92 *
93 * @retval ::RTEMS_INVALID_ADDRESS The ``time_of_day`` parameter was NULL.
94 *
95 * @retval ::RTEMS_INVALID_CLOCK The time of day specified by ``time_of_day``
96 *   was invalid.
97 *
98 * @par Notes
99 * @parblock
100 * The date, time, and ticks specified by ``time_of_day`` are all
101 * range-checked, and an error is returned if any one is out of its valid
102 * range.
103 *
104 * RTEMS can represent time points of this clock in nanoseconds ranging from
105 * 1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z.  The
106 * future uptime of the system shall be in this range, otherwise the system
107 * behaviour is undefined.
108 *
109 * The specified time is based on the configured clock tick rate, see the
110 * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option.
111 *
112 * Setting the time forward will fire all CLOCK_REALTIME timers which are
113 * scheduled at a time point before or at the time set by the directive.  This
114 * may unblock tasks, which may preempt the calling task. User-provided timer
115 * routines will execute in the context of the caller.
116 *
117 * It is allowed to call this directive from within interrupt context, however,
118 * this is not recommended since an arbitrary number of timers may fire.
119 *
120 * The directive shall be called at least once to enable the service of
121 * CLOCK_REALTIME related directives.  If the clock is not set at least once,
122 * they may return an error status.
123 * @endparblock
124 *
125 * @par Constraints
126 * @parblock
127 * The following constraints apply to this directive:
128 *
129 * * The directive may be called from within any runtime context.
130 *
131 * * The directive may change the priority of a task.  This may cause the
132 *   calling task to be preempted.
133 *
134 * * The directive may unblock a task.  This may cause the calling task to be
135 *   preempted.
136 * @endparblock
137 */
138rtems_status_code rtems_clock_set( const rtems_time_of_day *time_of_day );
139
140/* Generated from spec:/rtems/clock/if/get-tod */
141
142/**
143 * @ingroup RTEMSAPIClassicClock
144 *
145 * @brief Gets the time of day associated with the current CLOCK_REALTIME.
146 *
147 * @param time_of_day is the pointer to a RTEMS time of day variable.  When the
148 *   directive call is successful, the time of day associated with the
149 *   CLOCK_REALTIME at some point during the directive call will be stored in
150 *   this variable.
151 *
152 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
153 *
154 * @retval ::RTEMS_INVALID_ADDRESS The ``time_of_day`` parameter was NULL.
155 *
156 * @retval ::RTEMS_NOT_DEFINED The CLOCK_REALTIME was not set.  It can be set
157 *   with rtems_clock_set().
158 *
159 * @par Constraints
160 * @parblock
161 * The following constraints apply to this directive:
162 *
163 * * The directive may be called from within any runtime context.
164 *
165 * * The directive will not cause the calling task to be preempted.
166 *
167 * * The directive requires a Clock Driver.
168 * @endparblock
169 */
170rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_of_day );
171
172/* Generated from spec:/rtems/clock/if/get-tod-timeval */
173
174/**
175 * @ingroup RTEMSAPIClassicClock
176 *
177 * @brief Gets the seconds and microseconds elapsed since the Unix epoch and
178 *   the current CLOCK_REALTIME.
179 *
180 * @param[out] time_of_day is the pointer to a timeval structure variable.
181 *   When the directive call is successful, the seconds and microseconds
182 *   elapsed since the Unix epoch and the CLOCK_REALTIME at some point during
183 *   the directive call will be stored in this variable.
184 *
185 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
186 *
187 * @retval ::RTEMS_INVALID_ADDRESS The ``time_of_day`` parameter was NULL.
188 *
189 * @retval ::RTEMS_NOT_DEFINED The CLOCK_REALTIME was not set.  It can be set
190 *   with rtems_clock_set().
191 *
192 * @par Constraints
193 * @parblock
194 * The following constraints apply to this directive:
195 *
196 * * The directive may be called from within any runtime context.
197 *
198 * * The directive will not cause the calling task to be preempted.
199 *
200 * * The directive requires a Clock Driver.
201 * @endparblock
202 */
203rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time_of_day );
204
205/* Generated from spec:/rtems/clock/if/get-seconds-since-epoch */
206
207/**
208 * @ingroup RTEMSAPIClassicClock
209 *
210 * @brief Gets the seconds elapsed since the RTEMS epoch and the current
211 *   CLOCK_REALTIME.
212 *
213 * @param[out] seconds_since_rtems_epoch is the pointer to an interval
214 *   variable.  When the directive call is successful, the seconds elapsed
215 *   since the RTEMS epoch and the CLOCK_REALTIME at some point during the
216 *   directive call will be stored in this variable.
217 *
218 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
219 *
220 * @retval ::RTEMS_INVALID_ADDRESS The ``seconds_since_rtems_epoch`` parameter
221 *   was NULL.
222 *
223 * @retval ::RTEMS_NOT_DEFINED The CLOCK_REALTIME was not set.  It can be set
224 *   with rtems_clock_set().
225 *
226 * @par Constraints
227 * @parblock
228 * The following constraints apply to this directive:
229 *
230 * * The directive may be called from within any runtime context.
231 *
232 * * The directive will not cause the calling task to be preempted.
233 *
234 * * The directive requires a Clock Driver.
235 * @endparblock
236 */
237rtems_status_code rtems_clock_get_seconds_since_epoch(
238  rtems_interval *seconds_since_rtems_epoch
239);
240
241/* Generated from spec:/rtems/clock/if/get-ticks-per-second */
242
243/**
244 * @ingroup RTEMSAPIClassicClock
245 *
246 * @brief Gets the number of clock ticks per second configured for the
247 *   application.
248 *
249 * @return Returns the number of clock ticks per second configured for this
250 *   application.
251 *
252 * @par Notes
253 * The number of clock ticks per second is defined indirectly by the
254 * #CONFIGURE_MICROSECONDS_PER_TICK configuration option.
255 *
256 * @par Constraints
257 * @parblock
258 * The following constraints apply to this directive:
259 *
260 * * The directive may be called from within any runtime context.
261 *
262 * * The directive will not cause the calling task to be preempted.
263 * @endparblock
264 */
265rtems_interval rtems_clock_get_ticks_per_second( void );
266
267/* Generated from spec:/rtems/clock/if/get-ticks-per-second-macro */
268#define rtems_clock_get_ticks_per_second() _Watchdog_Ticks_per_second
269
270/* Generated from spec:/rtems/clock/if/get-ticks-since-boot */
271
272/**
273 * @ingroup RTEMSAPIClassicClock
274 *
275 * @brief Gets the number of clock ticks since some time point during the
276 *   system initialization or the last overflow of the clock tick counter.
277 *
278 * @return Returns the number of clock ticks since some time point during the
279 *   system initialization or the last overflow of the clock tick counter.
280 *
281 * @par Notes
282 * With a 1ms clock tick, this counter overflows after 50 days since boot.
283 * This is the historical measure of uptime in an RTEMS system.  The newer
284 * service rtems_clock_get_uptime() is another and potentially more accurate
285 * way of obtaining similar information.
286 *
287 * @par Constraints
288 * @parblock
289 * The following constraints apply to this directive:
290 *
291 * * The directive may be called from within any runtime context.
292 *
293 * * The directive will not cause the calling task to be preempted.
294 * @endparblock
295 */
296rtems_interval rtems_clock_get_ticks_since_boot( void );
297
298/* Generated from spec:/rtems/clock/if/get-ticks-since-boot-macro */
299#define rtems_clock_get_ticks_since_boot() _Watchdog_Ticks_since_boot
300
301/* Generated from spec:/rtems/clock/if/get-uptime */
302
303/**
304 * @ingroup RTEMSAPIClassicClock
305 *
306 * @brief Gets the seconds and nanoseconds elapsed since some time point during
307 *   the system initialization using CLOCK_MONOTONIC.
308 *
309 * @param[out] uptime is the pointer to a timeval structure variable.  When the
310 *   directive call is successful, the seconds and nanoseconds elapsed since
311 *   some time point during the system initialization and some point during the
312 *   directive call using CLOCK_MONOTONIC will be stored in this variable.
313 *
314 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
315 *
316 * @retval ::RTEMS_INVALID_ADDRESS The ``uptime`` parameter was NULL.
317 *
318 * @par Constraints
319 * @parblock
320 * The following constraints apply to this directive:
321 *
322 * * The directive may be called from within any runtime context.
323 *
324 * * The directive will not cause the calling task to be preempted.
325 *
326 * * The directive requires a Clock Driver.
327 * @endparblock
328 */
329rtems_status_code rtems_clock_get_uptime( struct timespec *uptime );
330
331/* Generated from spec:/rtems/clock/if/get-uptime-timeval */
332
333/**
334 * @ingroup RTEMSAPIClassicClock
335 *
336 * @brief Gets the seconds and microseconds elapsed since some time point
337 *   during the system initialization using CLOCK_MONOTONIC.
338 *
339 * @param[out] uptime is the pointer to a timeval structure variable.  The
340 *   seconds and microseconds elapsed since some time point during the system
341 *   initialization and some point during the directive call using
342 *   CLOCK_MONOTONIC will be stored in this variable.  The pointer shall be
343 *   valid, otherwise the behaviour is undefined.
344 *
345 * @par Constraints
346 * @parblock
347 * The following constraints apply to this directive:
348 *
349 * * The directive may be called from within any runtime context.
350 *
351 * * The directive will not cause the calling task to be preempted.
352 *
353 * * The directive requires a Clock Driver.
354 * @endparblock
355 */
356void rtems_clock_get_uptime_timeval( struct timeval *uptime );
357
358/* Generated from spec:/rtems/clock/if/get-uptime-seconds */
359
360/**
361 * @ingroup RTEMSAPIClassicClock
362 *
363 * @brief Gets the seconds elapsed since some time point during the system
364 *   initialization using CLOCK_MONOTONIC.
365 *
366 * @return Returns the seconds elapsed since some time point during the system
367 *   initialization and some point during the directive call using
368 *   CLOCK_MONOTONIC.
369 *
370 * @par Constraints
371 * @parblock
372 * The following constraints apply to this directive:
373 *
374 * * The directive may be called from within any runtime context.
375 *
376 * * The directive will not cause the calling task to be preempted.
377 *
378 * * The directive requires a Clock Driver.
379 * @endparblock
380 */
381time_t rtems_clock_get_uptime_seconds( void );
382
383/* Generated from spec:/rtems/clock/if/get-uptime-nanoseconds */
384
385/**
386 * @ingroup RTEMSAPIClassicClock
387 *
388 * @brief Gets the nanoseconds elapsed since some time point during the system
389 *   initialization using CLOCK_MONOTONIC.
390 *
391 * @return Returns the nanoseconds elapsed since some time point during the
392 *   system initialization and some point during the directive call using
393 *   CLOCK_MONOTONIC.
394 *
395 * @par Constraints
396 * @parblock
397 * The following constraints apply to this directive:
398 *
399 * * The directive may be called from within any runtime context.
400 *
401 * * The directive will not cause the calling task to be preempted.
402 *
403 * * The directive requires a Clock Driver.
404 * @endparblock
405 */
406uint64_t rtems_clock_get_uptime_nanoseconds( void );
407
408/* Generated from spec:/rtems/clock/if/tick-later */
409
410/**
411 * @ingroup RTEMSAPIClassicClock
412 *
413 * @brief Gets a clock tick value which is at least delta clock ticks in the
414 *   future.
415 *
416 * @param delta is the delta value in clock ticks.
417 *
418 * @return Returns a clock tick counter value which is at least ``delta`` clock
419 *   ticks in the future.
420 *
421 * @par Constraints
422 * @parblock
423 * The following constraints apply to this directive:
424 *
425 * * The directive may be called from within any runtime context.
426 *
427 * * The directive will not cause the calling task to be preempted.
428 *
429 * * The directive requires a Clock Driver.
430 * @endparblock
431 */
432static inline rtems_interval rtems_clock_tick_later( rtems_interval delta )
433{
434  return _Watchdog_Ticks_since_boot + delta;
435}
436
437/* Generated from spec:/rtems/clock/if/tick-later-usec */
438
439/**
440 * @ingroup RTEMSAPIClassicClock
441 *
442 * @brief Gets a clock tick value which is at least delta microseconds in the
443 *   future.
444 *
445 * @param delta_in_usec is the delta value in microseconds.
446 *
447 * @return Returns a clock tick counter value which is at least
448 *   ``delta_in_usec`` microseconds in the future.
449 *
450 * @par Constraints
451 * @parblock
452 * The following constraints apply to this directive:
453 *
454 * * The directive may be called from within any runtime context.
455 *
456 * * The directive will not cause the calling task to be preempted.
457 *
458 * * The directive requires a Clock Driver.
459 * @endparblock
460 */
461static inline rtems_interval rtems_clock_tick_later_usec(
462  rtems_interval delta_in_usec
463)
464{
465  rtems_interval us_per_tick;
466
467  us_per_tick = rtems_configuration_get_microseconds_per_tick();
468
469  /*
470   * Add one additional tick, since we do not know the time to the clock
471   * next tick.
472   */
473  return _Watchdog_Ticks_since_boot + 1
474    + ( delta_in_usec + us_per_tick - 1 ) / us_per_tick;
475}
476
477/* Generated from spec:/rtems/clock/if/tick-before */
478
479/**
480 * @ingroup RTEMSAPIClassicClock
481 *
482 * @brief Indicates if the current clock tick counter is before the ticks.
483 *
484 * @param ticks is the ticks value to check.
485 *
486 * @return Returns true, if current clock tick counter indicates a time before
487 *   the time in ticks, otherwise returns false.
488 *
489 * @par Notes
490 * @parblock
491 * This directive can be used to write busy loops with a timeout.
492 *
493 * @code
494 * status busy( void )
495 * {
496 *   rtems_interval timeout;
497 *
498 *   timeout = rtems_clock_tick_later_usec( 10000 );
499 *
500 *   do {
501 *     if ( ok() ) {
502 *       return success;
503 *     }
504 *   } while ( rtems_clock_tick_before( timeout ) );
505 *
506 *   return timeout;
507 * }
508 * @endcode
509 * @endparblock
510 *
511 * @par Constraints
512 * @parblock
513 * The following constraints apply to this directive:
514 *
515 * * The directive may be called from within any runtime context.
516 *
517 * * The directive will not cause the calling task to be preempted.
518 *
519 * * The directive requires a Clock Driver.
520 * @endparblock
521 */
522static inline bool rtems_clock_tick_before( rtems_interval ticks )
523{
524  return (int32_t) ( ticks - _Watchdog_Ticks_since_boot ) > 0;
525}
526
527/* Generated from spec:/rtems/clock/if/tick */
528
529/**
530 * @brief Announces a clock tick.
531 *
532 * @par Notes
533 * The directive is a legacy interface.  It should not be called by
534 * applications directly.  A Clock Driver may call this directive.
535 */
536rtems_status_code rtems_clock_tick( void );
537
538#ifdef __cplusplus
539}
540#endif
541
542#endif /* _RTEMS_RTEMS_CLOCK_H */
Note: See TracBrowser for help on using the repository browser.