source: rtems/cpukit/rtems/include/rtems/rtems/clock.h @ 23e43f6

/**
 * @file rtems/rtems/clock.h
 *
 * @defgroup ClassicClock Clocks
 *
 * @ingroup ClassicRTEMS
 * @brief Clock Manager API
 *
 * 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.
 *
 * This manager provides directives to:
 *
 * - set the current date and time
 * - obtain the current date and time
 * - set the nanoseconds since last clock tick handler
 * - announce a clock tick
 * - obtain the system uptime
 */

/* 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.
 */

#ifndef _RTEMS_RTEMS_CLOCK_H
#define _RTEMS_RTEMS_CLOCK_H

#include <rtems/score/watchdog.h>
#include <rtems/score/tod.h>
#include <rtems/rtems/status.h>
#include <rtems/rtems/types.h>
#include <rtems/config.h>

#include <sys/time.h> /* struct timeval */

/**
 *  @defgroup ClassicClock Clocks
 *
 *  @ingroup ClassicRTEMS
 *
 *  This encapsulates functionality related to the Classic API Clock
 *  Manager.
 */
/**@{*/

#ifdef __cplusplus
extern "C" {
#endif

/**
 *  List of things which can be returned by the rtems_clock_get directive.
 */
typedef enum {
  /** This value indicates obtain TOD in Classic API format. */
  RTEMS_CLOCK_GET_TOD,
  /** This value indicates obtain the number of seconds since the epoch. */
  RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH,
  /** This value indicates obtain the number of ticks since system boot. */
  RTEMS_CLOCK_GET_TICKS_SINCE_BOOT,
  /** This value indicates obtain the number of ticks per second. */
  RTEMS_CLOCK_GET_TICKS_PER_SECOND,
  /** This value indicates obtain the TOD in struct timeval format. */
  RTEMS_CLOCK_GET_TIME_VALUE
} rtems_clock_get_options;

/**
 *  Type for the nanoseconds since last tick BSP extension.
 */
typedef TOD_Nanoseconds_since_last_tick_routine
  rtems_nanoseconds_extension_routine;

/**
 * @brief Obtain Current Time of Day
 *
 * @deprecated rtems_clock_get() is deprecated. Use the more explicit
 * function calls rtems_clock_get_xxx().
 *
 * This routine implements the rtems_clock_get directive. It returns
 * one of the following:
 * + current time of day
 * + seconds since epoch
 * + ticks since boot
 * + ticks per second
 *
 * @param[in] option is the format of time to return
 * @param[in] time_buffer points to the output area
 *
 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
 *         error. Otherwise, a status code is returned indicating the
 *         source of the error.
 */
rtems_status_code rtems_clock_get(
  rtems_clock_get_options  option,
  void                    *time_buffer
) RTEMS_COMPILER_DEPRECATED_ATTRIBUTE;

/**
 * @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
 *
 * @param[in] time_buffer points to the time of day structure
 *
 * @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.
 */
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.
 *
 * @param[in] time points to the struct timeval variable to fill in
 *
 * @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.
 */
rtems_status_code rtems_clock_get_tod_timeval(
  struct timeval *time
);

/**
 * @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
 *
 * @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.
 */
rtems_status_code rtems_clock_get_seconds_since_epoch(
  rtems_interval *the_interval
);

/**
 * @brief Gets the current ticks counter value.
 *
 * @return The current tick counter value.  With a 1ms clock tick, this counter
 * overflows after 50 days since boot.
 */
RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_get_ticks_since_boot(void)
{
  return _Watchdog_Ticks_since_boot;
}

/**
 * @brief Returns the ticks counter value delta ticks in the future.
 *
 * @param[in] delta The ticks delta value.
 *
 * @return The tick counter value delta ticks in the future.
 */
RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_tick_later(
  rtems_interval delta
)
{
  return _Watchdog_Ticks_since_boot + delta;
}

/**
 * @brief Returns the ticks counter value at least delta microseconds in the
 * future.
 *
 * @param[in] delta_in_usec The delta value in microseconds.
 *
 * @return The tick counter value at least delta microseconds in the future.
 */
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;
}

/**
 * @brief Returns true if the current ticks counter value indicates a time
 * before the time specified by the tick value and false otherwise.
 *
 * @param[in] tick The tick value.
 *
 * 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.
 */
RTEMS_INLINE_ROUTINE bool rtems_clock_tick_before(
  rtems_interval tick
)
{
  return (int32_t) ( tick - _Watchdog_Ticks_since_boot ) > 0;
}

/**
 * @brief Obtain Ticks Per Seconds
 *
 * This routine implements the rtems_clock_get_ticks_per_second
 * directive.
 *
 * @retval This method returns the number of ticks since boot. It cannot
 *         fail since RTEMS is always configured to know the number of
 *         ticks per second.
 */
rtems_interval rtems_clock_get_ticks_per_second(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.
 *
 * @param[in] time_buffer points to the new TOD
 *
 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
 *         error. Otherwise, a status code is returned indicating the
 *         source of the error.
 *
 * @note Activities scheduled based upon the current time of day
 *       may be executed immediately if the time is moved forward.
 */
rtems_status_code rtems_clock_set(
  const rtems_time_of_day *time_buffer
);

/**
 * @brief Announce a Clock Tick
 *
 * This routine implements the rtems_clock_tick directive. It is invoked
 * to inform RTEMS of the occurrence of a clock tick.
 *
 * @retval This directive always returns RTEMS_SUCCESSFUL.
 *
 * @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.
 */
rtems_status_code rtems_clock_tick( void );

/**
 * @brief Set the BSP specific Nanoseconds Extension
 *
 * Clock Manager
 *
 * This directive sets the BSP provided nanoseconds since last tick
 * extension.
 *
 * @param[in] routine is a pointer to the extension routine
 *
 * @return This method returns RTEMS_SUCCESSFUL if there was not an
 *         error. Otherwise, a status code is returned indicating the
 *         source of the error.
 */
rtems_status_code rtems_clock_set_nanoseconds_extension(
  rtems_nanoseconds_extension_routine routine
);

/**
 * @brief Obtain the System Uptime
 *
 * This directive returns the system uptime.
 *
 * @param[in] uptime is a pointer to the time structure
 *
 * @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.
 */
rtems_status_code rtems_clock_get_uptime(
  struct timespec *uptime
);

/**
 * @brief Gets the System Uptime in the Struct Timeval Format
 *
 * @param[out] uptime is a pointer to a struct timeval structure.
 *
 * @retval This methods returns the system uptime.
 *
 * @note Pointer must not be NULL.
 */
void rtems_clock_get_uptime_timeval( struct timeval *uptime );

/**
 * @brief Returns the system uptime in seconds.
 *
 * @retval The system uptime in seconds.
 */
time_t rtems_clock_get_uptime_seconds( void );

/**
 * @brief Returns the system uptime in nanoseconds.
 *
 * @retval The system uptime in nanoseconds.
 */
uint64_t rtems_clock_get_uptime_nanoseconds( void );

/**
 * @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.
 *
 * @note This routine only works for leap-years through 2099.
 */
bool _TOD_Validate(
  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
 *
 * @retval This method returns the number of seconds since epoch represented
 *         by @a the_tod
 */
Watchdog_Interval _TOD_To_seconds(
  const rtems_time_of_day *the_tod
);

#ifdef __cplusplus
}
#endif

/**@}*/

#endif
/* end of include file */