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.__unnamed38__
	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...

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.__unnamed38__	__unnamed__	Callback function to call when timer fires.
void *	ctx	Callback context parameter.
struct timer_link *	next	Link to next timer.

◆ timer_link_t.unnamed38

union timer_link_t.__unnamed38__

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.

The timer subsystem tracks the number of times timer_init is called and will only initialize the subsystem on the first call. This reference count also applies to timer_close, which will only close the subsystem if it is called the same number of times as timer_init.

◆ 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.

The timer subsystem tracks the number of times timer_init is called and will only close the subsystem if timer_close is called the same number of times.

◆ 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

Files

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ timer_link_t

◆ timer_link_t.__unnamed38__

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()

◆ timer_link_t.unnamed38