From 276828053ef00406b6d24bafc5b0b9da12068bf0 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 22 Jun 2020 09:06:51 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/clock.h | 604 ++++++++++++++++++++++++++----------- 1 file changed, 434 insertions(+), 170 deletions(-) (limited to 'cpukit') diff --git a/cpukit/include/rtems/rtems/clock.h b/cpukit/include/rtems/rtems/clock.h index c3eea7d254..f4c50f2043 100644 --- a/cpukit/include/rtems/rtems/clock.h +++ b/cpukit/include/rtems/rtems/clock.h @@ -1,277 +1,541 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicClock + * @brief This header file defines the Clock Manager API. + */ + +/* + * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/* + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: * - * This include file contains all the constants and structures associated - * with the Clock Manager. This manager provides facilities to set, obtain, - * and continually update the current date and time. + * https://www.rtems.org/bugs.html * - * This manager provides directives to: + * For information on updating and regenerating please refer to the How-To + * section in the Software Requirements Engineering chapter of the + * RTEMS Software Engineering manual. The manual is provided as a part of + * a release. For development sources please refer to the online + * documentation at: * - * - set the current date and time - * - obtain the current date and time - * - announce a clock tick - * - obtain the system uptime + * https://docs.rtems.org */ -/* COPYRIGHT (c) 1989-2013. - * On-Line Applications Research Corporation (OAR). - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. - */ +/* Generated from spec:/rtems/clock/if/header */ #ifndef _RTEMS_RTEMS_CLOCK_H #define _RTEMS_RTEMS_CLOCK_H +#include +#include +#include +#include +#include +#include #include #include -#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* Generated from spec:/rtems/clock/if/group */ /** - * @defgroup ClassicClock Clocks + * @defgroup RTEMSAPIClassicClock Clock Manager * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * This encapsulates functionality related to the Classic API Clock - * Manager. + * @brief The Clock Manager provides support for time of day and other time + * related capabilities. */ -/**@{*/ -#ifdef __cplusplus -extern "C" { -#endif +/* Generated from spec:/rtems/clock/if/set */ /** - * @brief Obtain Current Time of Day (Classic TOD) + * @ingroup RTEMSAPIClassicClock + * + * @brief Sets the CLOCK_REALTIME to the time of day. + * + * @param time_of_day is the time of day to set the clock. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``time_of_day`` parameter was NULL. * - * This routine implements the rtems_clock_get_tod directive. It returns - * the current time of day in the format defined by RTEID. + * @retval ::RTEMS_INVALID_CLOCK The time of day specified by ``time_of_day`` + * was invalid. * - * Clock Manager - rtems_clock_get_tod + * @par Notes + * @parblock + * The date, time, and ticks specified by ``time_of_day`` are all + * range-checked, and an error is returned if any one is out of its valid + * range. * - * @param[in] time_buffer points to the time of day structure + * RTEMS can represent time points of this clock in nanoseconds ranging from + * 1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z. The + * future uptime of the system shall be in this range, otherwise the system + * behaviour is undefined. * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the time_buffer will - * be filled in with the current time of day. + * The specified time is based on the configured clock tick rate, see the + * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * + * Setting the time forward will fire all CLOCK_REALTIME timers which are + * scheduled at a time point before or at the time set by the directive. This + * may unblock tasks, which may preempt the calling task. User-provided timer + * routines will execute in the context of the caller. + * + * It is allowed to call this directive from within interrupt context, however, + * this is not recommended since an arbitrary number of timers may fire. + * + * The directive shall be called at least once to enable the service of + * CLOCK_REALTIME related directives. If the clock is not set at least once, + * they may return an error status. + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive may change the priority of another task which may preempt + * the calling task. + * + * * The directive may unblock another task which may preempt the calling task. + * @endparblock */ -rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer -); +rtems_status_code rtems_clock_set( const rtems_time_of_day *time_of_day ); + +/* Generated from spec:/rtems/clock/if/get-tod */ /** - * @brief Obtain TOD in struct timeval Format + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the time of day associated with the current CLOCK_REALTIME. + * + * @param time_of_day is the pointer to a RTEMS time of day variable. When the + * directive call is successful, the time of day associated with the + * CLOCK_REALTIME at some point during the directive call will be stored in + * this variable. * - * This routine implements the rtems_clock_get_tod_timeval - * directive. + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * @param[in] time points to the struct timeval variable to fill in + * @retval ::RTEMS_INVALID_ADDRESS The ``time_of_day`` parameter was NULL. * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the time will - * be filled in with the current time of day. + * @retval ::RTEMS_NOT_DEFINED The CLOCK_REALTIME was not set. It can be set + * with rtems_clock_set(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -rtems_status_code rtems_clock_get_tod_timeval( - struct timeval *time -); +rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_of_day ); + +/* Generated from spec:/rtems/clock/if/get-tod-timeval */ /** - * @brief Obtain Seconds Since Epoch + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the seconds and microseconds elapsed since the Unix epoch and + * the current CLOCK_REALTIME. + * + * @param[out] time_of_day is the pointer to a timeval structure variable. + * When the directive call is successful, the seconds and microseconds + * elapsed since the Unix epoch and the CLOCK_REALTIME at some point during + * the directive call will be stored in this variable. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``time_of_day`` parameter was NULL. * - * This routine implements the rtems_clock_get_seconds_since_epoch - * directive. + * @retval ::RTEMS_NOT_DEFINED The CLOCK_REALTIME was not set. It can be set + * with rtems_clock_set(). * - * @param[in] the_interval points to the interval variable to fill in + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the time_buffer will - * be filled in with the current time of day. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval *the_interval -); +rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time_of_day ); + +/* Generated from spec:/rtems/clock/if/get-seconds-since-epoch */ /** - * @brief Gets the current ticks counter value. + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the seconds elapsed since the RTEMS epoch and the current + * CLOCK_REALTIME. + * + * @param[out] seconds_since_rtems_epoch is the pointer to an interval + * variable. When the directive call is successful, the seconds elapsed + * since the RTEMS epoch and the CLOCK_REALTIME at some point during the + * directive call will be stored in this variable. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``seconds_since_rtems_epoch`` parameter + * was NULL. + * + * @retval ::RTEMS_NOT_DEFINED The CLOCK_REALTIME was not set. It can be set + * with rtems_clock_set(). + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @return The current tick counter value. With a 1ms clock tick, this counter - * overflows after 50 days since boot. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_get_ticks_since_boot(void) -{ - return _Watchdog_Ticks_since_boot; -} +rtems_status_code rtems_clock_get_seconds_since_epoch( + rtems_interval *seconds_since_rtems_epoch +); + +/* Generated from spec:/rtems/clock/if/get-ticks-per-second */ /** - * @brief Returns the ticks counter value delta ticks in the future. + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the number of clock ticks per second configured for the + * application. + * + * @return Returns the number of clock ticks per second configured for this + * application. + * + * @par Notes + * The number of clock ticks per second is defined indirectly by the + * #CONFIGURE_MICROSECONDS_PER_TICK configuration option. * - * @param[in] delta The ticks delta value. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @return The tick counter value delta ticks in the future. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_tick_later( - rtems_interval delta -) -{ - return _Watchdog_Ticks_since_boot + delta; -} +rtems_interval rtems_clock_get_ticks_per_second( void ); + +/* Generated from spec:/rtems/clock/if/get-ticks-per-second-macro */ +#define rtems_clock_get_ticks_per_second() _Watchdog_Ticks_per_second + +/* Generated from spec:/rtems/clock/if/get-ticks-since-boot */ /** - * @brief Returns the ticks counter value at least delta microseconds in the - * future. + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the number of clock ticks since some time point during the + * system initialization or the last overflow of the clock tick counter. + * + * @return Returns the number of clock ticks since some time point during the + * system initialization or the last overflow of the clock tick counter. + * + * @par Notes + * With a 1ms clock tick, this counter overflows after 50 days since boot. + * This is the historical measure of uptime in an RTEMS system. The newer + * service rtems_clock_get_uptime() is another and potentially more accurate + * way of obtaining similar information. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] delta_in_usec The delta value in microseconds. + * * The directive may be called from within any runtime context. * - * @return The tick counter value at least delta microseconds in the future. + * * The directive will not cause the calling task to be preempted. + * @endparblock */ -RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_tick_later_usec( - rtems_interval delta_in_usec -) -{ - rtems_interval us_per_tick = rtems_configuration_get_microseconds_per_tick(); +rtems_interval rtems_clock_get_ticks_since_boot( void ); - /* - * Add one additional tick, since we don't know the time to the clock next - * tick. - */ - return _Watchdog_Ticks_since_boot - + (delta_in_usec + us_per_tick - 1) / us_per_tick + 1; -} +/* Generated from spec:/rtems/clock/if/get-ticks-since-boot-macro */ +#define rtems_clock_get_ticks_since_boot() _Watchdog_Ticks_since_boot + +/* Generated from spec:/rtems/clock/if/get-uptime */ /** - * @brief Returns true if the current ticks counter value indicates a time - * before the time specified by the tick value and false otherwise. + * @ingroup RTEMSAPIClassicClock * - * @param[in] tick The tick value. + * @brief Gets the seconds and nanoseconds elapsed since some time point during + * the system initialization using CLOCK_MONOTONIC. * - * This can be used to write busy loops with a timeout. + * @param[out] uptime is the pointer to a timeval structure variable. When the + * directive call is successful, the seconds and nanoseconds elapsed since + * some time point during the system initialization and some point during the + * directive call using CLOCK_MONOTONIC will be stored in this variable. * - * @code - * status busy( void ) - * { - * rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * do { - * if ( ok() ) { - * return success; - * } - * } while ( rtems_clock_tick_before( timeout ) ); + * @retval ::RTEMS_INVALID_ADDRESS The ``uptime`` parameter was NULL. * - * return timeout; - * } - * @endcode + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. * - * @retval true The current ticks counter value indicates a time before the - * time specified by the tick value. - * @retval false Otherwise. + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -RTEMS_INLINE_ROUTINE bool rtems_clock_tick_before( - rtems_interval tick -) -{ - return (int32_t) ( tick - _Watchdog_Ticks_since_boot ) > 0; -} +rtems_status_code rtems_clock_get_uptime( struct timespec *uptime ); + +/* Generated from spec:/rtems/clock/if/get-uptime-timeval */ /** - * @brief Obtain Ticks Per Seconds + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the seconds and microseconds elapsed since some time point + * during the system initialization using CLOCK_MONOTONIC. + * + * @param[out] uptime is the pointer to a timeval structure variable. The + * seconds and microseconds elapsed since some time point during the system + * initialization and some point during the directive call using + * CLOCK_MONOTONIC will be stored in this variable. The pointer shall be + * valid, otherwise the behaviour is undefined. * - * This routine implements the rtems_clock_get_ticks_per_second - * directive. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval This method returns the number of ticks per second. It cannot - * fail since RTEMS is always configured to know the number of - * ticks per second. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -rtems_interval rtems_clock_get_ticks_per_second(void); +void rtems_clock_get_uptime_timeval( struct timeval *uptime ); -/* Optimized variant for C/C++ without function call overhead */ -#define rtems_clock_get_ticks_per_second() ( _Watchdog_Ticks_per_second ) +/* Generated from spec:/rtems/clock/if/get-uptime-seconds */ /** - * @brief Set the Current TOD + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the seconds elapsed since some time point during the system + * initialization using CLOCK_MONOTONIC. + * + * @return Returns the seconds elapsed since some time point during the system + * initialization and some point during the directive call using + * CLOCK_MONOTONIC. * - * This routine implements the rtems_clock_set directive. It sets - * the current time of day to that in the time_buffer record. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @param[in] time_buffer points to the new TOD + * * The directive may be called from within any runtime context. * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. + * * The directive will not cause the calling task to be preempted. * - * @note Activities scheduled based upon the current time of day - * may be executed immediately if the time is moved forward. + * * The directive requires a Clock Driver. + * @endparblock */ -rtems_status_code rtems_clock_set( - const rtems_time_of_day *time_buffer -); +time_t rtems_clock_get_uptime_seconds( void ); + +/* Generated from spec:/rtems/clock/if/get-uptime-nanoseconds */ /** - * @brief Announce a Clock Tick + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets the nanoseconds elapsed since some time point during the system + * initialization using CLOCK_MONOTONIC. + * + * @return Returns the nanoseconds elapsed since some time point during the + * system initialization and some point during the directive call using + * CLOCK_MONOTONIC. + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * This routine implements the rtems_clock_tick directive. It is invoked - * to inform RTEMS of the occurrence of a clock tick. + * * The directive may be called from within any runtime context. * - * @retval This directive always returns RTEMS_SUCCESSFUL. + * * The directive will not cause the calling task to be preempted. * - * @note This method is typically called from an ISR and is the basis - * for all timeouts and delays. This routine only works for leap-years - * through 2099. + * * The directive requires a Clock Driver. + * @endparblock */ -rtems_status_code rtems_clock_tick( void ); +uint64_t rtems_clock_get_uptime_nanoseconds( void ); + +/* Generated from spec:/rtems/clock/if/tick-later */ /** - * @brief Obtain the System Uptime + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets a clock tick value which is at least delta clock ticks in the + * future. + * + * @param delta is the delta value in clock ticks. * - * This directive returns the system uptime. + * @return Returns a clock tick counter value which is at least ``delta`` clock + * ticks in the future. * - * @param[in] uptime is a pointer to the time structure + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. If successful, the @a uptime will be - * filled in. + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -rtems_status_code rtems_clock_get_uptime( - struct timespec *uptime -); +static inline rtems_interval rtems_clock_tick_later( rtems_interval delta ) +{ + return _Watchdog_Ticks_since_boot + delta; +} + +/* Generated from spec:/rtems/clock/if/tick-later-usec */ /** - * @brief Gets the System Uptime in the Struct Timeval Format + * @ingroup RTEMSAPIClassicClock + * + * @brief Gets a clock tick value which is at least delta microseconds in the + * future. + * + * @param delta_in_usec is the delta value in microseconds. + * + * @return Returns a clock tick counter value which is at least + * ``delta_in_usec`` microseconds in the future. * - * @param[out] uptime is a pointer to a struct timeval structure. + * @par Constraints + * @parblock + * The following constraints apply to this directive: * - * @retval This methods returns the system uptime. + * * The directive may be called from within any runtime context. * - * @note Pointer must not be NULL. + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -void rtems_clock_get_uptime_timeval( struct timeval *uptime ); +static inline rtems_interval rtems_clock_tick_later_usec( + rtems_interval delta_in_usec +) +{ + rtems_interval us_per_tick; + + us_per_tick = rtems_configuration_get_microseconds_per_tick(); + + /* + * Add one additional tick, since we do not know the time to the clock + * next tick. + */ + return _Watchdog_Ticks_since_boot + 1 + + ( delta_in_usec + us_per_tick - 1 ) / us_per_tick; +} + +/* Generated from spec:/rtems/clock/if/tick-before */ /** - * @brief Returns the system uptime in seconds. + * @ingroup RTEMSAPIClassicClock * - * @retval The system uptime in seconds. + * @brief Indicates if the current clock tick counter is before the ticks. + * + * @param ticks is the ticks value to check. + * + * @return Returns true, if current clock tick counter indicates a time before + * the time in ticks, otherwise returns false. + * + * @par Notes + * @parblock + * This directive can be used to write busy loops with a timeout. + * + * @code + * status busy( void ) + * { + * rtems_interval timeout; + * + * timeout = rtems_clock_tick_later_usec( 10000 ); + * + * do { + * if ( ok() ) { + * return success; + * } + * } while ( rtems_clock_tick_before( timeout ) ); + * + * return timeout; + * } + * @endcode + * @endparblock + * + * @par Constraints + * @parblock + * The following constraints apply to this directive: + * + * * The directive may be called from within any runtime context. + * + * * The directive will not cause the calling task to be preempted. + * + * * The directive requires a Clock Driver. + * @endparblock */ -time_t rtems_clock_get_uptime_seconds( void ); +static inline bool rtems_clock_tick_before( rtems_interval ticks ) +{ + return (int32_t) ( ticks - _Watchdog_Ticks_since_boot ) > 0; +} + +/* Generated from spec:/rtems/clock/if/tick */ /** - * @brief Returns the system uptime in nanoseconds. + * @brief Announces a clock tick. * - * @retval The system uptime in nanoseconds. + * @par Notes + * The directive is a legacy interface. It should not be called by + * applications directly. A Clock Driver may call this directive. */ -uint64_t rtems_clock_get_uptime_nanoseconds( void ); +rtems_status_code rtems_clock_tick( void ); #ifdef __cplusplus } #endif -/**@}*/ - -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_CLOCK_H */ -- cgit v1.2.3