Interface to the timer module in the MIPS r4300 processor. More...

Files
file	timer.c
	Timer Subsystem.

file	timer.h
	Timer Subsystem.

Data Structures
struct	timer_link_t
	Timer structure. More...

union	timer_link_t.__unnamed25__
	Callback function to call when timer fires. More...

Macros
#define	TF_CONTEXT 0x20
	Timer callback expects a context parameter.

#define	TF_OVERFLOW 0x40
	Timer is the special overflow timer.

#define	TF_CALLED 0x80
	Timer has been called once in this interrupt.

#define	TF_ONE_SHOT 0
	Timer should fire only once.

#define	TF_CONTINUOUS 1
	Timer should fire at a regular interval.

#define	TF_DISABLED 2
	Timer is enabled or not. Can be used to get a new timer that's not started.

#define	TIMER_TICKS(us) ((int)TIMER_TICKS_LL(us))
	Calculate timer ticks based on microseconds. More...

#define	TIMER_MICROS(tk) ((int)TIMER_MICROS_LL(tk))
	Calculate microseconds based on timer ticks. More...

#define	TIMER_TICKS_LL(us) ((long long)(us) * TICKS_PER_SECOND / 1000000)
	Calculate timer ticks based on microseconds. More...

#define	TIMER_MICROS_LL(tk) ((long long)(tk) * 1000000 / TICKS_PER_SECOND)
	Calculate microseconds based on timer ticks. More...

Typedefs
typedef void(*	timer_callback1_t) (int ovfl)
	Timer callback function without context.

typedef void(*	timer_callback2_t) (int ovfl, void *ctx)
	Timer callback function with context.

Functions
void	timer_init (void)
	Initialize the timer subsystem. More...

timer_link_t *	new_timer (int ticks, int flags, timer_callback1_t callback)
	Create a new timer and add to list. More...

timer_link_t *	new_timer_context (int ticks, int flags, timer_callback2_t callback, void *ctx)
	Create a new timer with context and add to list. More...

void	start_timer (timer_link_t *timer, int ticks, int flags, timer_callback1_t callback)
	Start a timer (not currently in the list) More...

void	start_timer_context (timer_link_t timer, int ticks, int flags, timer_callback2_t callback, void ctx)
	Start a timer (not currently in the list) with context. More...

void	restart_timer (timer_link_t *timer)
	Reset a timer and add to list. More...

void	stop_timer (timer_link_t *timer)
	Stop a timer and remove it from the list. More...

void	delete_timer (timer_link_t *timer)
	Remove a timer from the list and delete it. More...

void	timer_close (void)
	Free and close the timer subsystem. More...

long long	timer_ticks (void)
	Return total ticks since timer was initialized, as a 64-bit counter. More...

Variables
volatile uint32_t	ticks64_high
	Higher-part of 64-bit tick counter.

volatile uint32_t	interrupt_disabled_tick
	Time at which interrupts were disabled. More...

Detailed Description

Interface to the timer module in the MIPS r4300 processor.

The timer subsystem allows code to receive a callback after a specified number of ticks or microseconds. It interfaces with the MIPS coprocessor 0 to handle the timer interrupt and provide useful timing services.

Before attempting to use the timer subsystem, code should call timer_init. After the timer subsystem has been initialized, a new one-shot or continuous timer can be created with new_timer. To remove an expired one-shot timer or a recurring timer, use delete_timer. To temporarily stop a timer, use stop_timer. To restart a stopped timer or an expired one-shot timer, use start_timer. Once code no longer needs the timer subsystem, a call to timer_close will free all continuous timers and shut down the timer subsystem. Note that timers removed with stop_timer or expired one-short timers will not be removed automatically and are the responsibility of the calling code to be freed, regardless of a call to timer_close.

Because the MIPS internal counter wraps around after ~90 seconds (see TICKS_READ), it's not possible to schedule a timer more than 90 seconds in the future.

Data Structure Documentation

◆ timer_link_t

struct timer_link_t

Timer structure.

Data Fields
uint32_t	left	Absolute ticks value at which the timer expires.
uint32_t	set	Ticks to set if continuous.
int	ovfl	To correct for drift.
int	flags	Timer flags. See TF_ONE_SHOT, TF_CONTINUOUS, and TF_DISABLED.
union timer_link_t.__unnamed25__	__unnamed__	Callback function to call when timer fires.
void *	ctx	Callback context parameter.
struct timer_link *	next	Link to next timer.

◆ timer_link_t.unnamed25

union timer_link_t.__unnamed25__

Callback function to call when timer fires.

Data Fields
timer_callback1_t	callback
timer_callback2_t	callback_with_context

Macro Definition Documentation

◆ TIMER_TICKS

#define TIMER_TICKS ( us ) ((int)TIMER_TICKS_LL(us))

Calculate timer ticks based on microseconds.

Parameters

[in] us Microseconds to convert to ticks

Returns: Timer ticks

◆ TIMER_MICROS

#define TIMER_MICROS ( tk ) ((int)TIMER_MICROS_LL(tk))

Calculate microseconds based on timer ticks.

Parameters

[in] tk Ticks to convert to microseconds

Returns: Microseconds

◆ TIMER_TICKS_LL

#define TIMER_TICKS_LL ( us ) ((long long)(us) * TICKS_PER_SECOND / 1000000)

Calculate timer ticks based on microseconds.

Parameters

[in] us Microseconds to convert to ticks

Returns: Timer ticks as a long long

◆ TIMER_MICROS_LL

#define TIMER_MICROS_LL ( tk ) ((long long)(tk) * 1000000 / TICKS_PER_SECOND)

Calculate microseconds based on timer ticks.

Parameters

[in] tk Ticks to convert to microseconds

Returns: Microseconds as a long long

Function Documentation

◆ timer_init()

void timer_init ( void )

Initialize the timer subsystem.

This function will reset the COP0 ticks counter to 0. Even if you later access the hardware counter directly (via TICKS_READ()), it should not be a problem if you call timer_init() early in the application main.

Do not modify the COP0 ticks counter after calling this function. Doing so will impede functionality of the timer module.

◆ new_timer()

timer_link_t * new_timer	(	int	ticks,
		int	flags,
		timer_callback1_t	callback
	)

Create a new timer and add to list.

If you need to associate some data with the timer, consider using new_timer_context to include a pointer in the callback.

Parameters

[in]	ticks	Number of ticks before the timer should fire
[in]	flags	Timer flags. See TF_ONE_SHOT, TF_CONTINUOUS and TF_DISABLED
[in]	callback	Callback function to call when the timer expires

Returns: A pointer to the timer structure created

◆ new_timer_context()

timer_link_t * new_timer_context	(	int	ticks,
		int	flags,
		timer_callback2_t	callback,
		void *	ctx
	)

Create a new timer with context and add to list.

If you don't need the context, consider using new_timer instead.

Parameters

[in]	ticks	Number of ticks before the timer should fire
[in]	flags	Timer flags. See TF_ONE_SHOT, TF_CONTINUOUS and TF_DISABLED
[in]	callback	Callback function to call when the timer expires
[in]	ctx	Opaque pointer to pass as an argument to callback

Returns: A pointer to the timer structure created

◆ start_timer()

void start_timer	(	timer_link_t *	timer,
		int	ticks,
		int	flags,
		timer_callback1_t	callback
	)

Start a timer (not currently in the list)

If you need to associate some data with the timer, consider using start_timer_context to include a pointer in the callback.

Parameters

[in]	timer	Pointer to timer structure to reinsert and start
[in]	ticks	Number of ticks before the timer should fire
[in]	flags	Timer flags. See TF_ONE_SHOT, TF_CONTINUOUS, and TF_DISABLED
[in]	callback	Callback function to call when the timer expires

◆ start_timer_context()

void start_timer_context	(	timer_link_t *	timer,
		int	ticks,
		int	flags,
		timer_callback2_t	callback,
		void *	ctx
	)

Start a timer (not currently in the list) with context.

If you don't need the context, consider using start_timer instead.

Parameters

[in]	timer	Pointer to timer structure to reinsert and start
[in]	ticks	Number of ticks before the timer should fire
[in]	flags	Timer flags. See TF_ONE_SHOT, TF_CONTINUOUS, and TF_DISABLED
[in]	callback	Callback function to call when the timer expires
[in]	ctx	Opaque pointer to pass as an argument to callback

◆ restart_timer()

void restart_timer ( timer_link_t * timer )

Reset a timer and add to list.

Parameters

[in] timer Pointer to timer structure to reinsert and start

◆ stop_timer()

void stop_timer ( timer_link_t * timer )

Stop a timer and remove it from the list.

Note: This function does not free a timer structure, use delete_timer to do this.; It is safe to call this function from a timer callback, including to stop a timer from its own callback.

Parameters

[in] timer Timer structure to stop and remove

◆ delete_timer()

void delete_timer ( timer_link_t * timer )

Remove a timer from the list and delete it.

Note: It is not safe to call this function from a timer callback.

Parameters

[in] timer Timer structure to stop, remove and free

◆ timer_close()

void timer_close ( void )

Free and close the timer subsystem.

This function will ensure all recurring timers are deleted from the list before closing. One-shot timers that have expired will need to be manually deleted with delete_timer.

◆ timer_ticks()

long long timer_ticks ( void )

Return total ticks since timer was initialized, as a 64-bit counter.

Returns: Then number of ticks since the timer was initialized

Variable Documentation

◆ interrupt_disabled_tick

volatile uint32_t interrupt_disabled_tick

extern

Time at which interrupts were disabled.

Files

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Data Structure Documentation

◆ timer_link_t

◆ timer_link_t.__unnamed25__

Macro Definition Documentation

◆ TIMER_TICKS

◆ TIMER_MICROS

◆ TIMER_TICKS_LL

◆ TIMER_MICROS_LL

Function Documentation

◆ timer_init()

◆ new_timer()

◆ new_timer_context()

◆ start_timer()

◆ start_timer_context()

◆ restart_timer()

◆ stop_timer()

◆ delete_timer()

◆ timer_close()

◆ timer_ticks()

Variable Documentation

◆ interrupt_disabled_tick

◆ timer_link_t.unnamed25