diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-06-22 09:06:51 +0200 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-09-22 10:06:05 +0200 |
commit | d9e8b1ebff9610456976b3f395878603e500dad9 (patch) | |
tree | bd30466eeb3cf10299836610277cd641df9e87ba | |
parent | 69564bd8e2736ee149d42e2fb2db466c151d1613 (diff) |
Generate <rtems/rtems/clock.h>
-rw-r--r-- | cpukit/include/rtems/rtems/clock.h | 346 |
1 files changed, 140 insertions, 206 deletions
diff --git a/cpukit/include/rtems/rtems/clock.h b/cpukit/include/rtems/rtems/clock.h index 7f2887fb03..27657624a6 100644 --- a/cpukit/include/rtems/rtems/clock.h +++ b/cpukit/include/rtems/rtems/clock.h @@ -1,307 +1,241 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicClock + * @ingroup RTEMSAPIClassicClock * - * 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. + * @brief This header file defines the Clock Manager API. + */ + +/* + * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * - * This manager provides directives to: + * 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. * - * - set the current date and time - * - obtain the current date and time - * - announce a clock tick - * - obtain the system uptime + * 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. */ -/* COPYRIGHT (c) 1989-2013. - * On-Line Applications Research Corporation (OAR). +/* + * This file was automatically generated. Do not edit it manually. + * Please have a look at + * + * https://docs.rtems.org/branches/master/eng/req/howto.html * - * 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. + * for information how to maintain and re-generate this file. */ #ifndef _RTEMS_RTEMS_CLOCK_H #define _RTEMS_RTEMS_CLOCK_H +#include <stdbool.h> +#include <stdint.h> +#include <time.h> +#include <rtems/config.h> +#include <sys/_timespec.h> +#include <sys/_timeval.h> #include <rtems/rtems/status.h> #include <rtems/rtems/types.h> -#include <rtems/config.h> - -/** - * @defgroup ClassicClock Clocks - * - * @ingroup RTEMSAPIClassic - * - * This encapsulates functionality related to the Classic API Clock - * Manager. - */ -/**@{*/ +#include <rtems/score/watchdogticks.h> #ifdef __cplusplus extern "C" { #endif /** - * @brief Obtain Current Time of Day (Classic TOD) - * - * This routine implements the rtems_clock_get_tod directive. It returns - * the current time of day in the format defined by RTEID. - * - * Clock Manager - rtems_clock_get_tod + * @defgroup RTEMSAPIClassicClock Clock Manager * - * @param[in] time_buffer points to the time of day structure + * @ingroup RTEMSAPIClassic * - * @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. + * @brief The Clock Manager provides support for time of day and other time + * related capabilities. */ -rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer -); /** - * @brief Obtain TOD in struct timeval Format - * - * This routine implements the rtems_clock_get_tod_timeval - * directive. + * @ingroup RTEMSAPIClassicClock * - * @param[in] time points to the struct timeval variable to fill in + * @brief % * - * @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. + * @param the_interval % */ -rtems_status_code rtems_clock_get_tod_timeval( - struct timeval *time +rtems_status_code rtems_clock_get_seconds_since_epoch( + rtems_interval *the_interval ); /** - * @brief Obtain Seconds Since Epoch - * - * This routine implements the rtems_clock_get_seconds_since_epoch - * directive. - * - * @param[in] the_interval points to the interval variable to fill in + * @ingroup RTEMSAPIClassicClock * - * @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. + * @brief % */ -rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval *the_interval -); +#define rtems_clock_get_ticks_per_second() _Watchdog_Ticks_per_second /** - * @brief Gets the current ticks counter value. + * @ingroup RTEMSAPIClassicClock * - * @return The current tick counter value. With a 1ms clock tick, this counter - * overflows after 50 days since boot. + * @brief % */ -RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_get_ticks_since_boot(void) -{ - return _Watchdog_Ticks_since_boot; -} +#define rtems_clock_get_ticks_since_boot() _Watchdog_Ticks_since_boot /** - * @brief Returns the ticks counter value delta ticks in the future. + * @ingroup RTEMSAPIClassicClock * - * @param[in] delta The ticks delta value. + * @brief % * - * @return The tick counter value delta ticks in the future. + * @param time_buffer % */ -RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_tick_later( - rtems_interval delta -) -{ - return _Watchdog_Ticks_since_boot + delta; -} +rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_buffer ); /** - * @brief Returns the ticks counter value at least delta microseconds in the - * future. + * @ingroup RTEMSAPIClassicClock * - * @param[in] delta_in_usec The delta value in microseconds. + * @brief % * - * @return The tick counter value at least delta microseconds in the future. + * @param time % */ -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(); - - /* - * 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; -} +rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time ); /** - * @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 % * - * This can be used to write busy loops with a timeout. - * - * @code - * status busy( void ) - * { - * rtems_interval timeout = rtems_clock_tick_later_usec( 10000 ); - * - * do { - * if ( ok() ) { - * return success; - * } - * } while ( rtems_clock_tick_before( timeout ) ); - * - * return timeout; - * } - * @endcode - * - * @retval true The current ticks counter value indicates a time before the - * time specified by the tick value. - * @retval false Otherwise. + * @param uptime % */ -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 ); /** - * @brief Obtain Ticks Per Seconds - * - * This routine implements the rtems_clock_get_ticks_per_second - * directive. + * @ingroup RTEMSAPIClassicClock * - * @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. + * @brief % */ -rtems_interval rtems_clock_get_ticks_per_second(void); - -/* Optimized variant for C/C++ without function call overhead */ -#define rtems_clock_get_ticks_per_second() ( _Watchdog_Ticks_per_second ) +uint64_t rtems_clock_get_uptime_nanoseconds( void ); /** - * @brief Set the Current TOD - * - * This routine implements the rtems_clock_set directive. It sets - * the current time of day to that in the time_buffer record. + * @ingroup RTEMSAPIClassicClock * - * @param[in] time_buffer points to the new TOD + * @brief % + */ +time_t rtems_clock_get_uptime_seconds( void ); + +/** + * @ingroup RTEMSAPIClassicClock * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. + * @brief % * - * @note Activities scheduled based upon the current time of day - * may be executed immediately if the time is moved forward. + * @param uptime % */ -rtems_status_code rtems_clock_set( - const rtems_time_of_day *time_buffer -); +void rtems_clock_get_uptime_timeval( struct timeval *uptime ); /** - * @brief Announce a Clock Tick + * @ingroup RTEMSAPIClassicClock * - * This routine implements the rtems_clock_tick directive. It is invoked - * to inform RTEMS of the occurrence of a clock tick. + * @brief % * - * @retval This directive always returns RTEMS_SUCCESSFUL. + * @param time_buffer % + */ +rtems_status_code rtems_clock_set( const rtems_time_of_day *time_buffer ); + +/** + * @ingroup RTEMSAPIClassicClock * - * @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. + * @brief % */ rtems_status_code rtems_clock_tick( void ); /** - * @brief Obtain the System Uptime + * @ingroup RTEMSAPIClassicClock + * + * @brief Returns true if the current ticks counter value indicates a time + * before the time specified by the tick value and false otherwise. * - * This directive returns the system uptime. + * This directive can be used to write busy loops with a timeout. * - * @param[in] uptime is a pointer to the time structure + * @param tick is the tick value. * - * @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. + * @retval true The current ticks counter value indicates a time before the + * time specified by the tick value. + * + * @retval false Otherwise. */ -rtems_status_code rtems_clock_get_uptime( - struct timespec *uptime -); +static inline bool rtems_clock_tick_before( rtems_interval tick ) +{ + return (int32_t) ( tick - _Watchdog_Ticks_since_boot ) > 0; +} /** - * @brief Gets the System Uptime in the Struct Timeval Format + * @ingroup RTEMSAPIClassicClock * - * @param[out] uptime is a pointer to a struct timeval structure. + * @brief Returns the ticks counter value delta ticks in the future. * - * @retval This methods returns the system uptime. + * @param delta is the ticks delta value. * - * @note Pointer must not be NULL. + * @return The tick counter value delta ticks in the future is returned. */ -void rtems_clock_get_uptime_timeval( struct timeval *uptime ); +static inline rtems_interval rtems_clock_tick_later( rtems_interval delta ) +{ + return _Watchdog_Ticks_since_boot + delta; +} /** - * @brief Returns the system uptime in seconds. + * @ingroup RTEMSAPIClassicClock * - * @retval The system uptime in seconds. - */ -time_t rtems_clock_get_uptime_seconds( void ); - -/** - * @brief Returns the system uptime in nanoseconds. + * @brief Returns the ticks counter value at least delta microseconds in the + * future. + * + * @param delta_in_usec is the delta value in microseconds. * - * @retval The system uptime in nanoseconds. + * @return The tick counter value delta ticks in the future is returned. */ -uint64_t rtems_clock_get_uptime_nanoseconds( void ); +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; +} /** - * @brief TOD Validate - * - * This support function returns true if @a the_tod contains - * a valid time of day, and false otherwise. - * - * @param[in] the_tod is the TOD structure to validate - * - * @retval This method returns true if the TOD is valid and false otherwise. + * @brief % * - * @note This routine only works for leap-years through 2099. + * @param the_tod % */ -bool _TOD_Validate( - const rtems_time_of_day *the_tod -); +Watchdog_Interval _TOD_To_seconds( const rtems_time_of_day *the_tod ); /** - * @brief TOD to Seconds - * - * This function returns the number seconds between the epoch and @a the_tod. - * - * @param[in] the_tod is the TOD structure to convert to seconds + * @brief % * - * @retval This method returns the number of seconds since epoch represented - * by @a the_tod + * @param the_tod % */ -Watchdog_Interval _TOD_To_seconds( - const rtems_time_of_day *the_tod -); +bool _TOD_Validate( const rtems_time_of_day *the_tod ); #ifdef __cplusplus } #endif -/**@}*/ - -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_CLOCK_H */ |