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 frequency_in_hz, uint32_t timecounter_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 );
}

References _Timecounter_Install().

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.

References _Timecounter_Acquire, _Timecounter_Tick_simple(), and rtems_timecounter_simple_scale().

rtems_timecounter_simple_install()

void rtems_timecounter_simple_install	(	rtems_timecounter_simple *	tc,
		uint32_t	frequency_in_hz,
		uint32_t	timecounter_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 or only the module used for the clock tick is available. The period of the simple timecounter equals the clock tick interval. The interval is scaled up to the next power of two.

Parameters

[in]	tc	Zero initialized simple timecounter.
[in]	frequency_in_hz	The timecounter frequency in Hz.
[in]	timecounter_ticks_per_clock_tick	The timecounter 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 install( void )
{
  uint32_t frequency = 123456;
  uint64_t us_per_tick = rtems_configuration_get_microseconds_per_tick();
  uint32_t timecounter_ticks_per_clock_tick =
    ( frequency * us_per_tick ) / 1000000;

  rtems_timecounter_simple_install(
    &some_tc,
    frequency,
    timecounter_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.

Referenced by rtems_timecounter_simple_downcounter_tick(), and rtems_timecounter_simple_upcounter_tick().

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.

References _Timecounter_Acquire, _Timecounter_Tick_simple(), and rtems_timecounter_simple_scale().

rtems_timecounter_tick()

RTEMS_INLINE_ROUTINE void rtems_timecounter_tick

(

void

)

Performs a timecounter tick.

References _Timecounter_Tick().