From d7d785916619f752ecf7e67e82055fb1cb9216ba Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 11 Mar 2008 20:07:49 +0000 Subject: 2008-03-11 Joel Sherrill * rtems/Makefile.am, rtems/include/rtems/rtems/clock.h, rtems/src/clockget.c: * rtems/src/clockgetsecondssinceepoch.c, rtems/src/clockgettickspersecond.c, rtems/src/clockgettickssinceboot.c, rtems/src/clockgettod.c, rtems/src/clockgettodtimeval.c: New files. Refactored rtems_clock_get into 5 methods which are single purpose and more strongly typed. They are: rtems_clock_get_tod - Get TOD in Classic API structure rtems_clock_get_tod_timeval - Get TOD in struct timeval rtems_clock_get_seconds_since_epoch - Get TOD as seconds since 1988 rtems_clock_get_ticks_since_boot - Get ticks since boot rtems_clock_get_ticks_per_second - Get ticks per second --- cpukit/rtems/include/rtems/rtems/clock.h | 182 +++++++++++++++++++++++-------- 1 file changed, 139 insertions(+), 43 deletions(-) (limited to 'cpukit/rtems/include') diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h index a6f7de5dce..d467f353fd 100644 --- a/cpukit/rtems/include/rtems/rtems/clock.h +++ b/cpukit/rtems/include/rtems/rtems/clock.h @@ -13,8 +13,9 @@ * + 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-2007. + * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -36,37 +37,38 @@ extern "C" { #include #include -/* +/** * 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; -/* +/** * Standard flavor style to return TOD in for a rtems_clock_get option. */ - typedef struct { uint32_t seconds; uint32_t microseconds; } rtems_clock_time_value; -/* +/** * Type for the nanoseconds since last tick BSP extension. */ typedef Watchdog_Nanoseconds_since_last_tick_routine rtems_nanoseconds_extension_routine; -/* - * rtems_clock_get - * - * DESCRIPTION: +/** + * @brief Obtain Current Time of Day * * This routine implements the rtems_clock_get directive. It returns * one of the following: @@ -74,86 +76,180 @@ typedef Watchdog_Nanoseconds_since_last_tick_routine * + 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 + * + * @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_get( rtems_clock_get_options option, - void *time_buffer + void *time_buffer ); -/* - * rtems_clock_set +/** + * @brief Obtain Current Time of Day (Classic TOD) * - * DESCRIPTION: + * This routine implements the rtems_clock_get_tod directive. It returns + * the current time of day in the format defined by RTEID. + * + * @param[in] time_buffer points to the time of day structure + * + * @return 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 + * + * @return 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 + * + * @return 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 Obtain Ticks Since Boot + * + * This routine implements the rtems_clock_get_ticks_since_boot + * directive. + * + * @return This method returns the number of ticks since boot. It cannot + * fail since RTEMS always keeps a running count of ticks since boot. + */ +rtems_interval rtems_clock_get_ticks_since_boot(void); + +/** + * @brief Obtain Ticks Per Seconds + * + * This routine implements the rtems_clock_get_ticks_per_second + * directive. + * + * @return 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 + * + * @return 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( rtems_time_of_day *time_buffer ); -/* - * rtems_clock_tick - * - * DESCRIPTION: +/** + * @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. + * + * @return This directive always returns RTEMS_SUCCESSFUL. + * + * @note This method is typically called from an ISR and is the basis + * for all timeouts and delays. */ - rtems_status_code rtems_clock_tick( void ); -/* - * rtems_clock_set_nanoseconds_extension - * - * DESCRIPTION: +/** + * @brief Set the BSP specific Nanoseconds Extension * * This directive sets the BSP provided nanoseconds since last tick * extension. * - * Input parameters: - * routine - pointer to the extension routine + * @param[in] routine is a pointer to the extension routine * - * Output parameters: - * RTEMS_SUCCESSFUL - if successful - * error code - if unsuccessful + * @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 ); -/* - * rtems_clock_get_uptime - * - * DESCRIPTION: +/** + * @brief Obtain the System Uptime * * This directive returns the system uptime. * - * Input parameters: - * routine - pointer to the time structure + * @param[in] uptime is a pointer to the time structure * - * Output parameters: - * RTEMS_SUCCESSFUL - if successful - * error code - if unsuccessful + * @return 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 uptime will be + * filled in. */ rtems_status_code rtems_clock_get_uptime( struct timespec *uptime ); -/** @brief _TOD_Validate +/** + * @brief _TOD_Validate * - * This function returns TRUE if THE_TOD contains + * 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 + * + * @return This method returns TRUE if the TOD is valid and FALSE otherwise. */ boolean _TOD_Validate( rtems_time_of_day *the_tod ); -/** @brief _TOD_To_seconds +/** + * @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 * - * This function returns the number seconds between the epoch and THE_TOD. + * @return This method returns the number of seconds since epoch represented + * by @a the_tod */ Watchdog_Interval _TOD_To_seconds( rtems_time_of_day *the_tod -- cgit v1.2.3