Timecounter Support

Files
file	timecounter.h
	Timecounter API.

Data Structures
struct	rtems_timecounter_simple
	Simple timecounter to support legacy clock drivers. More...

Macros
#define	RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER   100
	Timecounter quality for the clock drivers. More...

Typedefs
typedef void	rtems_timecounter_simple_at_tick(rtems_timecounter_simple *tc)
	At tick handling done under protection of the timecounter lock.
typedef uint32_t	rtems_timecounter_simple_get(rtems_timecounter_simple *tc)
	Returns the current value of a simple timecounter.
typedef bool	rtems_timecounter_simple_is_pending(rtems_timecounter_simple *tc)
	Returns true if the interrupt of a simple timecounter is pending, and false otherwise.

Functions
RTEMS_INLINE_ROUTINE void	rtems_timecounter_install (struct timecounter *tc)
	Installs the timecounter. More...
RTEMS_INLINE_ROUTINE void	rtems_timecounter_tick (void)
	Performs a timecounter tick. More...
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)
	Initializes and installs a simple timecounter. More...
RTEMS_INLINE_ROUTINE uint32_t	rtems_timecounter_simple_scale (const rtems_timecounter_simple *tc, uint32_t value)
	Maps a simple timecounter value into its binary frequency domain. More...
RTEMS_INLINE_ROUTINE void	rtems_timecounter_simple_downcounter_tick (rtems_timecounter_simple *tc, rtems_timecounter_simple_get get, rtems_timecounter_simple_at_tick at_tick)
	Performs a simple timecounter tick for downcounters. More...
RTEMS_INLINE_ROUTINE void	rtems_timecounter_simple_upcounter_tick (rtems_timecounter_simple *tc, rtems_timecounter_simple_get get, rtems_timecounter_simple_at_tick at_tick)
	Performs a simple timecounter tick for upcounters. More...
RTEMS_INLINE_ROUTINE uint32_t	rtems_timecounter_simple_downcounter_get (struct timecounter *tc_base, rtems_timecounter_simple_get get, rtems_timecounter_simple_is_pending is_pending)
	Gets the simple timecounter value mapped to its binary frequency domain for downcounters. More...
RTEMS_INLINE_ROUTINE uint32_t	rtems_timecounter_simple_upcounter_get (struct timecounter *tc_base, rtems_timecounter_simple_get get, rtems_timecounter_simple_is_pending is_pending)
	Gets the simple timecounter value mapped to its binary frequency domain for upcounters. More...

Detailed Description

Macro Definition Documentation

RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER

#define RTEMS_TIMECOUNTER_QUALITY_CLOCK_DRIVER   100

Timecounter quality for the clock drivers.

Timecounter with higher quality value are used in favour of those with lower quality value.

Function Documentation

rtems_timecounter_install()

RTEMS_INLINE_ROUTINE void rtems_timecounter_install

(

struct timecounter *

tc

)

Installs the timecounter.

The timecounter structure must contain valid values in the fields tc_get_timecount, tc_counter_mask, tc_frequency and tc_quality. All other fields must be zero initialized.

Parameters

[in]

tc

The timecounter.

Below is an exemplary code snippet that shows the adjustable parameters and the following call of the install routine.

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 );
}

rtems_timecounter_simple_downcounter_get()

RTEMS_INLINE_ROUTINE uint32_t rtems_timecounter_simple_downcounter_get	(	struct timecounter *	tc_base,
		rtems_timecounter_simple_get	get,
		rtems_timecounter_simple_is_pending	is_pending
	)

Gets the simple timecounter value mapped to its binary frequency domain for downcounters.

Parameters

[in]	tc	The simple timecounter.
[in]	get	The method to get the value of the simple timecounter.
[in]	is_pending	The method which indicates if the interrupt of the simple timecounter is pending.

rtems_timecounter_simple_downcounter_tick()

RTEMS_INLINE_ROUTINE void rtems_timecounter_simple_downcounter_tick	(	rtems_timecounter_simple *	tc,
		rtems_timecounter_simple_get	get,
		rtems_timecounter_simple_at_tick	at_tick
	)

Performs a simple timecounter tick for downcounters.

Parameters

[in]	tc	The simple timecounter.
[in]	get	The method to get the value of the simple timecounter.
[in]	at_tick	The method to perform work under timecounter lock protection at this tick, e.g. clear a pending flag.

rtems_timecounter_simple_install()

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
	)

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.

Parameters

[in]	tc	Zero initialized simple timecounter.
[in]	counter_frequency_in_hz	The hardware counter frequency in Hz.
[in]	counter_ticks_per_clock_tick	The hardware counter ticks per clock tick.
[in]	get_timecount	The method to get the current time count.

#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
  );
}

See also

rtems_timecounter_simple_downcounter_get(), rtems_timecounter_simple_downcounter_tick(), rtems_timecounter_simple_upcounter_get() and rtems_timecounter_simple_upcounter_tick().

rtems_timecounter_simple_scale()

RTEMS_INLINE_ROUTINE uint32_t rtems_timecounter_simple_scale	(	const rtems_timecounter_simple *	tc,
		uint32_t	value
	)

Maps a simple timecounter value into its binary frequency domain.

Parameters

[in]	tc	The simple timecounter.
[in]	value	The value of the simple timecounter.

Returns

The scaled value.

rtems_timecounter_simple_upcounter_get()

RTEMS_INLINE_ROUTINE uint32_t rtems_timecounter_simple_upcounter_get	(	struct timecounter *	tc_base,
		rtems_timecounter_simple_get	get,
		rtems_timecounter_simple_is_pending	is_pending
	)

Gets the simple timecounter value mapped to its binary frequency domain for upcounters.

Parameters

[in]	tc	The simple timecounter.
[in]	get	The method to get the value of the simple timecounter.
[in]	is_pending	The method which indicates if the interrupt of the simple timecounter is pending.

rtems_timecounter_simple_upcounter_tick()

RTEMS_INLINE_ROUTINE void rtems_timecounter_simple_upcounter_tick	(	rtems_timecounter_simple *	tc,
		rtems_timecounter_simple_get	get,
		rtems_timecounter_simple_at_tick	at_tick
	)

Performs a simple timecounter tick for upcounters.

Parameters

[in]	tc	The simple timecounter.
[in]	get	The method to get the value of the simple timecounter.
[in]	at_tick	The method to perform work under timecounter lock protection at this tick, e.g. clear a pending flag.

rtems_timecounter_tick()

RTEMS_INLINE_ROUTINE void rtems_timecounter_tick

(

void

)

Performs a timecounter tick.