libdragon
Files | Data Structures | Macros | Typedefs | Functions | Variables
Timer Subsystem

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

Files

file  timer.c
 Timer Subsystem.
 
file  timer.h
 Timer Subsystem.
 

Data Structures

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_tnew_timer (int ticks, int flags, timer_callback1_t callback)
 Create a new timer and add to list. More...
 
timer_link_tnew_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.__unnamed19__ __unnamed__ Callback function to call when timer fires.
void * ctx Callback context parameter.
struct timer_link * next Link to next timer.

◆ timer_link_t.__unnamed19__

union timer_link_t.__unnamed19__

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]usMicroseconds 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]tkTicks 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]usMicroseconds 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]tkTicks 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]ticksNumber of ticks before the timer should fire
[in]flagsTimer flags. See TF_ONE_SHOT, TF_CONTINUOUS and TF_DISABLED
[in]callbackCallback 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]ticksNumber of ticks before the timer should fire
[in]flagsTimer flags. See TF_ONE_SHOT, TF_CONTINUOUS and TF_DISABLED
[in]callbackCallback function to call when the timer expires
[in]ctxOpaque 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]timerPointer to timer structure to reinsert and start
[in]ticksNumber of ticks before the timer should fire
[in]flagsTimer flags. See TF_ONE_SHOT, TF_CONTINUOUS, and TF_DISABLED
[in]callbackCallback 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]timerPointer to timer structure to reinsert and start
[in]ticksNumber of ticks before the timer should fire
[in]flagsTimer flags. See TF_ONE_SHOT, TF_CONTINUOUS, and TF_DISABLED
[in]callbackCallback function to call when the timer expires
[in]ctxOpaque 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]timerPointer 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.
Parameters
[in]timerTimer structure to stop and remove

◆ delete_timer()

void delete_timer ( timer_link_t timer)

Remove a timer from the list and delete it.

Parameters
[in]timerTimer 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.

Time at which interrupts were disabled.