LXR 6.1/​cpukit/​include/​rtems/​timecounter.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:14

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSAPIClassicTimecounter
  *
  * @brief This header file provides the Timecounter Support API.
  */
 
 /*
  * Copyright (c) 2015 embedded brains GmbH & Co. KG
  *
  * 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.
  */
 
 #ifndef _RTEMS_TIMECOUNTER_H
 #define _RTEMS_TIMECOUNTER_H
 
 #include <rtems/score/timecounter.h>
 #include <rtems/score/basedefs.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
 
 /**
  * @defgroup RTEMSAPIClassicTimecounter Timecounter Support
  *
  * @ingroup RTEMSAPIClassic
  *
  * @brief The timecounter support provides directives to implement clock device
  *   drivers.
  *
  * @{
  */
 
 /**
  * @brief Timecounter quality for the clock drivers.
  *
  * Timecounter with higher quality value are used in favour of those with lower
  * quality value.
  */
 #define RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER 100
 
 /**
  * @copydoc _Timecounter_Install()
  *
  * Below is an exemplary code snippet that shows the adjustable parameters and
  * the following call of the install routine.
  *
  * @code
  * struct timecounter tc;
  *
  * uint32_t get_timecount( struct timecounter *tc )
  * {
  *   return some_free_running_counter;
  * }
  *
  * void install( void )
  * {
  *   tc.tc_get_timecount = get_timecount;
  *   tc.tc_counter_mask = 0xffffffff;
  *   tc.tc_frequency = 123456;
  *   tc.tc_quality = RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER;
  *   rtems_timecounter_install( &tc );
  * }
  * @endcode
  */
 static inline void rtems_timecounter_install(
   struct timecounter *tc
 )
 {
   _Timecounter_Install( tc );
 }
 
 /**
  * @copydoc _Timecounter_Tick()
  */
 static inline void rtems_timecounter_tick(void)
 {
   _Timecounter_Tick();
 }
 
 /**
  * @brief Simple timecounter to support legacy clock drivers.
  */
 typedef struct {
   struct timecounter tc;
   uint64_t scaler;
   uint32_t real_interval;
   uint32_t binary_interval;
 } rtems_timecounter_simple;
 
 /**
  * @brief At tick handling done under protection of the timecounter lock.
  */
 typedef void rtems_timecounter_simple_at_tick(
   rtems_timecounter_simple *tc
 );
 
 /**
  * @brief Returns the current value of a simple timecounter.
  */
 typedef uint32_t rtems_timecounter_simple_get(
   rtems_timecounter_simple *tc
 );
 
 /**
  * @brief Returns true if the interrupt of a simple timecounter is pending, and
  * false otherwise.
  */
 typedef bool rtems_timecounter_simple_is_pending(
   rtems_timecounter_simple *tc
 );
 
 /**
  * @brief Initializes and installs a simple timecounter.
  *
  * A simple timecounter can be used if the hardware provides no free running
  * counter.  A periodic hardware counter must be provided.  The counter period
  * must be synchronous to the clock tick.  The counter ticks per clock tick is
  * scaled up to the next power of two.
  *
  * @param[in] tc Zero initialized simple timecounter.
  * @param[in] counter_frequency_in_hz The hardware counter frequency in Hz.
  * @param[in] counter_ticks_per_clock_tick The hardware counter ticks per clock
  *   tick.
  * @param[in] get_timecount The method to get the current time count.
  *
  * @code
  * #include <rtems/timecounter.h>
  *
  * static rtems_timecounter_simple some_tc;
  *
  * static uint32_t some_tc_get( rtems_timecounter_simple *tc )
  * {
  *   return some.value;
  * }
  *
  * static bool some_tc_is_pending( rtems_timecounter_simple *tc )
  * {
  *   return some.is_pending;
  * }
  *
  * static uint32_t some_tc_get_timecount( struct timecounter *tc )
  * {
  *   return rtems_timecounter_simple_downcounter_get(
  *     tc,
  *     some_tc_get,
  *     some_tc_is_pending
  *   );
  * }
  *
  * static void some_tc_tick( void )
  * {
  *   rtems_timecounter_simple_downcounter_tick( &some_tc, some_tc_get );
  * }
  *
  * void some_tc_init( void )
  * {
  *   uint64_t us_per_tick;
  *   uint32_t counter_frequency_in_hz;
  *   uint32_t counter_ticks_per_clock_tick;
  *
  *   us_per_tick = rtems_configuration_get_microseconds_per_tick();
  *   counter_frequency_in_hz = some_tc_get_frequency();
  *   counter_ticks_per_clock_tick =
  *     (uint32_t) ( counter_frequency_in_hz * us_per_tick ) / 1000000;
  *
  *   some_tc_init_hardware( counter_ticks_per_clock_tick );
  *   some_tc_init_clock_tick_interrupt( some_tc_tick );
  *
  *   rtems_timecounter_simple_install(
  *     &some_tc,
  *     counter_frequency_in_hz,
  *     counter_ticks_per_clock_tick,
  *     some_tc_get_timecount
  *   );
  * }
  * @endcode
  *
  * @see rtems_timecounter_simple_downcounter_get(),
  * rtems_timecounter_simple_downcounter_tick(),
  * rtems_timecounter_simple_upcounter_get() and
  * rtems_timecounter_simple_upcounter_tick().
  */
 void rtems_timecounter_simple_install(
   rtems_timecounter_simple *tc,
   uint32_t                  counter_frequency_in_hz,
   uint32_t                  counter_ticks_per_clock_tick,
   timecounter_get_t        *get_timecount
 );
 
 /**
  * @brief Maps a simple timecounter value into its binary frequency domain.
  *
  * @param[in] tc The simple timecounter.
  * @param[in] value The value of the simple timecounter.
  *
  * @return The scaled value.
  */
 static inline uint32_t rtems_timecounter_simple_scale(
   const rtems_timecounter_simple *tc,
   uint32_t value
 )
 {
   return (uint32_t) ( ( value * tc->scaler ) >> 32 );
 }
 
 /**
  * @brief Performs a simple timecounter tick for downcounters.
  *
  * @param[in] tc The simple timecounter.
  * @param[in] get The method to get the value of the simple timecounter.
  * @param[in] at_tick The method to perform work under timecounter lock
  * protection at this tick, e.g. clear a pending flag.
  */
 static inline void rtems_timecounter_simple_downcounter_tick(
   rtems_timecounter_simple         *tc,
   rtems_timecounter_simple_get      get,
   rtems_timecounter_simple_at_tick  at_tick
 )
 {
   ISR_lock_Context lock_context;
   uint32_t current;
 
   _Timecounter_Acquire( &lock_context );
 
   ( *at_tick )( tc );
 
   current = rtems_timecounter_simple_scale(
     tc,
     tc->real_interval - ( *get )( tc )
   );
 
   _Timecounter_Tick_simple( tc->binary_interval, current, &lock_context );
 }
 
 /**
  * @brief Performs a simple timecounter tick for upcounters.
  *
  * @param[in] tc The simple timecounter.
  * @param[in] get The method to get the value of the simple timecounter.
  * @param[in] at_tick The method to perform work under timecounter lock
  * protection at this tick, e.g. clear a pending flag.
  */
 static inline void rtems_timecounter_simple_upcounter_tick(
   rtems_timecounter_simple         *tc,
   rtems_timecounter_simple_get      get,
   rtems_timecounter_simple_at_tick  at_tick
 )
 {
   ISR_lock_Context lock_context;
   uint32_t current;
 
   _Timecounter_Acquire( &lock_context );
 
   ( *at_tick )( tc );
 
   current = rtems_timecounter_simple_scale( tc, ( *get )( tc ) );
 
   _Timecounter_Tick_simple( tc->binary_interval, current, &lock_context );
 }
 
 /**
  * @brief Gets the simple timecounter value mapped to its binary frequency
  * domain for downcounters.
  *
  * @param[in] tc The simple timecounter.
  * @param[in] get The method to get the value of the simple timecounter.
  * @param[in] is_pending The method which indicates if the interrupt of the
  * simple timecounter is pending.
  */
 static inline uint32_t rtems_timecounter_simple_downcounter_get(
   struct timecounter                  *tc_base,
   rtems_timecounter_simple_get         get,
   rtems_timecounter_simple_is_pending  is_pending
 )
 {
   rtems_timecounter_simple *tc;
   uint32_t counter;
   uint32_t interval;
 
   tc = (rtems_timecounter_simple *) tc_base;
   counter = ( *get )( tc );
   interval = tc->real_interval;
 
   if ( ( *is_pending )( tc ) ) {
     counter = ( *get )( tc );
     interval *= 2;
   }
 
   return rtems_timecounter_simple_scale( tc, interval - counter );
 }
 
 /**
  * @brief Gets the simple timecounter value mapped to its binary frequency
  * domain for upcounters.
  *
  * @param[in] tc The simple timecounter.
  * @param[in] get The method to get the value of the simple timecounter.
  * @param[in] is_pending The method which indicates if the interrupt of the
  * simple timecounter is pending.
  */
 static inline uint32_t rtems_timecounter_simple_upcounter_get(
   struct timecounter                  *tc_base,
   rtems_timecounter_simple_get         get,
   rtems_timecounter_simple_is_pending  is_pending
 )
 {
   rtems_timecounter_simple *tc;
   uint32_t counter;
   uint32_t interval;
 
   tc = (rtems_timecounter_simple *) tc_base;
   counter = ( *get )( tc );
   interval = 0;
 
   if ( ( *is_pending )( tc ) ) {
     counter = ( *get )( tc );
     interval = tc->real_interval;
   }
 
   return rtems_timecounter_simple_scale( tc, interval + counter );
 }
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
 #endif /* _RTEMS_TIMECOUNTER_H */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team