[PATCH 2/2] rtems: Add more clock tick functions

[Chris Johns]

On 23/08/2014 1:12 am, Sebastian Huber wrote:
> Add rtems_clock_ticks_later(), rtems_clock_ticks_later_us() and
> rtems_clock_ticks_later_us().
>
> FIXME: Patch is incomplete.  Documentation and tests are missing.  Just
> for API review.
> ---
>   cpukit/rtems/include/rtems/rtems/clock.h | 66 ++++++++++++++++++++++++++++++++
>   1 file changed, 66 insertions(+)
>
> diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h
> index ff71665..cee930e 100644
> --- a/cpukit/rtems/include/rtems/rtems/clock.h
> +++ b/cpukit/rtems/include/rtems/rtems/clock.h
> @@ -34,6 +34,7 @@
>   #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 */
>
> @@ -160,6 +161,71 @@ RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_get_ticks_since_boot(void)
>   }
>
>   /**
> + * @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_ticks_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 The delta value in microseconds.
> + *
> + * @return The tick counter value at least delta microseconds in the future.
> + */
> +RTEMS_INLINE_ROUTINE rtems_interval rtems_clock_ticks_later_us(

This should be rtems_clock_ticks_later_usec. When I first saw this I 
though it meant 'us' as in 'you and me'.

The calls names make sense from a programming point of view but from a 
user point of view they are sort of forwards and backwards. For example 
rtems_clock_ticks_later_us is the "the clock tick so many micro-seconds 
later where later implies now" or 'rtems_clock_tick_usecs_later' and 
following this I suppose 'rtems_clock_ticks_later' becomes 
'rtems_clock_tick_ticks_later' ?

> +  rtems_interval delta
> +)
> +{
> +  rtems_interval us_per_tick = rtems_configuration_get_microseconds_per_tick();
> +
> +  return _Watchdog_Ticks_since_boot + (delta + us_per_tick - 1) / us_per_tick;
> +}
> +
> +/**
> + * @brief Returns true if the current ticks counter value indicates a time
> + * before the time specified by the ticks value and false otherwise.
> + *
> + * @param[in] ticks The ticks value.
> + *
> + * This can be used to write busy loops with a timeout.
> + *
> + * @code
> + * status busy( void )
> + * {
> + *   rtems_interval timeout = rtems_clock_ticks_later_us( 10000 );
> + *
> + *   do {
> + *     if ( ok() ) {
> + *       return success;
> + *     }
> + *   } while ( rtems_clock_ticks_before( timeout ) );
> + *
> + *   return timeout;
> + * }
> + * @endcode
> + *
> + * @retval true The current ticks counter value indicates a time before the
> + * time specified by the ticks value.
> + * @retval false Otherwise.
> + */
> +RTEMS_INLINE_ROUTINE bool rtems_clock_ticks_before(

And so should this become 'rtems_clock_tick_ticks_before' ?

Which then makes be wonder if 'rtems_clock_tick_ticks_later' becomes 
''rtems_clock_tick_ticks_after' and finally 
''rtems_clock_tick_usecs_after', or does 'rtems_clock_tick_ticks_before' 
become 'rtems_clock_tick_ticks_earlier' ?

Is there a rtems_clock_tick_usecs_earlier ?

Chris

> +  rtems_interval ticks
> +)
> +{
> +  return ( (int32_t) ticks - (int32_t) _Watchdog_Ticks_since_boot ) > 0;
> +}
> +
> +/**
>    * @brief Obtain Ticks Per Seconds
>    *
>    * This routine implements the rtems_clock_get_ticks_per_second
>