KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Macros | Typedefs | Functions
timer.h File Reference

Low-level timer functionality. More...

#include <sys/cdefs.h>
#include <arch/types.h>
#include <arch/irq.h>

Go to the source code of this file.

Macros

#define TMU0   0
 SH4 Timer 0. More...
 
#define TMU1   1
 SH4 Timer 1. More...
 
#define TMU2   2
 SH4 Timer 2. More...
 
#define WDT   3
 SH4 Watchdog Timer. More...
 
#define TIMER_ID   TMU0
 Which timer does the thread system use? More...
 

Typedefs

typedef void(* timer_primary_callback_t )(irq_context_t *)
 Primary timer callback type. More...
 

Functions

int timer_prime (int which, uint32 speed, int interrupts)
 Pre-initialize a timer, but do not start it. More...
 
int timer_start (int which)
 Start a timer. More...
 
int timer_stop (int which)
 Stop a timer. More...
 
uint32 timer_count (int which)
 Obtain the count of a timer. More...
 
int timer_clear (int which)
 Clear the underflow bit of a timer. More...
 
void timer_spin_sleep (int ms)
 Spin-loop sleep function. More...
 
void timer_enable_ints (int which)
 Enable high-priority timer interrupts. More...
 
void timer_disable_ints (int which)
 Disable timer interrupts. More...
 
int timer_ints_enabled (int which)
 Check whether interrupts are enabled on a timer. More...
 
void timer_ms_enable ()
 Enable the millisecond timer. More...
 
void timer_ms_disable ()
 Disable the millisecond timer. More...
 
void timer_ms_gettime (uint32 *secs, uint32 *msecs)
 Get the current uptime of the system. More...
 
uint64 timer_ms_gettime64 ()
 Get the current uptime of the system (in milliseconds). More...
 
uint64 timer_us_gettime64 ()
 Get the current uptime of the system (in microseconds). More...
 
timer_primary_callback_t timer_primary_set_callback (timer_primary_callback_t callback)
 Set the primary timer callback. More...
 
void timer_primary_wakeup (uint32 millis)
 Request a primary timer wakeup. More...
 

Detailed Description

Low-level timer functionality.

This file contains functions for interacting with the timer sources on the SH4. Many of these functions may interfere with thread operation or other such things, and should thus be used with caution. Basically, the only functionality that you might use in practice in here in normal programs is the gettime functions.

Author
Dan Potter

Macro Definition Documentation

#define TIMER_ID   TMU0

Which timer does the thread system use?

#define TMU0   0

SH4 Timer 0.

This timer is used for thread operation, and thus is off limits if you want that to work properly.

#define TMU1   1

SH4 Timer 1.

This timer is used for the timer_spin_sleep() function.

#define TMU2   2

SH4 Timer 2.

This timer is used by the various gettime functions in this header.

#define WDT   3

SH4 Watchdog Timer.

KallistiOS does not currently support using this timer.

Typedef Documentation

typedef void(* timer_primary_callback_t)(irq_context_t *)

Primary timer callback type.

Function Documentation

int timer_clear ( int  which)

Clear the underflow bit of a timer.

This function clears the underflow bit of a timer if it was set.

Parameters
whichThe timer to inspect (i.e, TMU0).
Return values
0If the underflow bit was clear (prior to calling).
1If the underflow bit was set (prior to calling).
uint32 timer_count ( int  which)

Obtain the count of a timer.

This function simply returns the count of the timer.

Parameters
whichThe timer to inspect (i.e, TMU0).
Returns
The timer's count.
void timer_disable_ints ( int  which)

Disable timer interrupts.

This function disables interrupts on the specified timer.

Parameters
whichThe timer to disable interrupts on (i.e, TMU0).
void timer_enable_ints ( int  which)

Enable high-priority timer interrupts.

This function enables interrupts on the specified timer.

Parameters
whichThe timer to enable interrupts on (i.e, TMU0).
int timer_ints_enabled ( int  which)

Check whether interrupts are enabled on a timer.

This function checks whether or not interrupts are enabled on the specified timer.

Parameters
whichThe timer to inspect (i.e, TMU0).
Return values
0If interrupts are disabled on the timer.
1If interrupts are enabled on the timer.
void timer_ms_disable ( )

Disable the millisecond timer.

This function disables the timer used for the gettime functions. Generally, you will not want to do this, unless you have some need to use the timer TMU2 for something else.

void timer_ms_enable ( )

Enable the millisecond timer.

This function enables the timer used for the gettime functions. This is on by default. These functions use TMU2 to do their work.

void timer_ms_gettime ( uint32 secs,
uint32 msecs 
)

Get the current uptime of the system.

This function retrieves the number of seconds and milliseconds since KOS was started.

Parameters
secsA pointer to store the number of seconds since boot into.
msecsA pointer to store the number of milliseconds past a second since boot.
Note
To get the total number of milliseconds since boot, calculate (*secs * 1000) + *msecs, or use the timer_ms_gettime64() function.
uint64 timer_ms_gettime64 ( )

Get the current uptime of the system (in milliseconds).

This function retrieves the number of milliseconds since KOS was started. It is equivalent to calling timer_ms_gettime() and combining the number of seconds and milliseconds into one 64-bit value.

Returns
The number of milliseconds since KOS started.
timer_primary_callback_t timer_primary_set_callback ( timer_primary_callback_t  callback)

Set the primary timer callback.

This function sets the primary timer callback to the specified function pointer. Generally, you should not do this, as the threading system relies on the primary timer to work.

Parameters
callbackThe new timer callback (set to NULL to disable).
Returns
The old timer callback.
void timer_primary_wakeup ( uint32  millis)

Request a primary timer wakeup.

This function will wake the caller (by calling the primary timer callback) in approximately the number of milliseconds specified. You can only have one timer wakeup scheduled at a time. Any subsequently scheduled wakeups will replace any existing one.

Parameters
millisThe number of milliseconds to schedule for.
int timer_prime ( int  which,
uint32  speed,
int  interrupts 
)

Pre-initialize a timer, but do not start it.

This function sets up a timer for use, but does not start it.

Parameters
whichThe timer to set up (i.e, TMU0).
speedThe number of ticks per second.
interruptsSet to 1 to receive interrupts when the timer ticks.
Return values
0On success.
void timer_spin_sleep ( int  ms)

Spin-loop sleep function.

This function is meant as a very accurate delay function, even if threading and interrupts are disabled. It uses TMU1 to sleep.

Parameters
msThe number of milliseconds to sleep.
int timer_start ( int  which)

Start a timer.

This function starts a timer that has been initialized with timer_prime(), starting raising interrupts if applicable.

Parameters
whichThe timer to start (i.e, TMU0).
Return values
0On success.
int timer_stop ( int  which)

Stop a timer.

This function stops a timer that was started with timer_start(), and as a result stops interrupts coming in from the timer.

Parameters
whichThe timer to stop (i.e, TMU0).
Return values
0On success.
uint64 timer_us_gettime64 ( )

Get the current uptime of the system (in microseconds).

This function retrieves the number of microseconds since KOS was started. It should be more precise, in theory, than timer_ms_gettime64(), but the exact amount of preciseness is undetermined.

Returns
The number of microseconds since KOS started.