OS_StartTimer*

Syntax

#include <nitro/os.h>

void OS_StartTimer( OS_TimerId id, u16 count, OS_TimerPrescaler preScale );

void OS_StartTimer32( OS_Timer32Id id, u32 count, OS_TimerPrescaler preScale );

void OS_StartTimer48( OS_Timer48Id id, u64 count, OS_TimerPrescaler preScale );

void OS_StartTimer64( u64 count, OS_TimerPrescaler preScale );

Arguments

`id`	Timer ID of the timer to use (differs according to number of timers used)
`count`	Timer count
`preScale`	Timer scale

Return Values

None.

Description

Sets and starts the internal timer.

There are four 16-bit counter timers available with both NITRO and TWL. The timers are count-up timers, so an interrupt will occur when they go from 0xFFFF to 0.

Each of the four timers can be used independently, or two or more timers can be connected to create a 32-bit, 48-bit, or 64-bit count timer. However, caution must be exercised because there are also timers used by the system.

Call an OS_StopTimer* function if one of the timers you have set is no longer needed.

The OS_StartTimer function uses 16-bit timers individually.

The OS_StartTimer32 function uses two consecutive timers as a timer with a 32-bit count maximum.

The OS_StartTimer48 function uses three consecutive timers as a timer with a 48-bit count maximum.

The OS_StartTimer64 function uses four consecutive timers as a timer with a 64-bit count maximum.

The id argument specifies the Timer ID of the timer to use, as shown below.

For 16-bit timers (id specification for the OS_StartTimer and OS_StopTimer functions)

id	Timer to use
`OS_TIMER_0`	Timer 0
`OS_TIMER_1`	Timer 1
`OS_TIMER_2`	Timer 2
`OS_TIMER_3`	Timer 3

For 32-bit timers (id specification for the OS_StartTimer32 and OS_StopTimer32 functions)

id	Timer to Use
`OS_TIMER32_01`	Timer 0, Timer 1
`OS_TIMER32_12`	Timer 1, Timer 2
`OS_TIMER32_23`	Timer 2, Timer 3

For 48-bit timers (id specification for the OS_StartTimer48 and OS_StopTimer48 functions)

id	Timer to Use
`OS_TIMER48_012`	Timer 0, Timer 1, Timer 2
`OS_TIMER48_123`	Timer 1, Timer 2, Timer 3

The count argument is the count given to the timer: 16-bit timers take values from 0 to 0xFFFF, 32-bit timers take values from 0 to 0xFFFFFFFF, 48-bit timers take values from 0 to 0xFFFFFFFFFFFF, and 64-bit timers take values from 0 to 0xFFFFFFFFFFFFFFFF.

The preScale argument is the parameter that sets the scale for the counting on the timer. See the table below.

Set Value	Prescaler (Count Interval)
`OS_TIMER_PRESCALER_1`	System Clock
`OS_TIMER_PRESCALER_64`	1/64th of the System Clock
`OS_TIMER_PRESCALER_256`	1/256th of the System Clock
`OS_TIMER_PRESCALER_1024`	1/1024th of the System Clock

When using a timer that uses multiple timers, timer interrupts will be for the the timer that has the highest number. However, make sure to grant interrupt permission for all timers that you will be using.In this case, a system-internal interrupt handler will be assigned for all timers used except for the one with the highest number.

Example: Use timers 0, 1, and 2 [together] as a 48-bit timer

#define count 0x100000000

//---- set timer 2 interrupt handler
OS_SetIrqFunction( OS_IE_TIMER2, TimerIntr );

//---- enable timer 0-2
(void)OS_EnableIrqMask( OS_IE_TIMER0 | OS_IE_TIMER_1 | OS_IE_TIMER2 );

//---- start timer 0-2 (as 48bit timer)
OS_StartTimer48( OS_TIMER48_012, count, OS_TIMER_PRESCALER_64 );


//
// interrupt handler
//
void TimerIntr(void)
{
  OS_Printf("TIMER INTERRUPT!\n");
  OS_StopTimer48( OS_TIMER48_012 );
}

Note:

Based on the hardware timer specifications, set timer interrupts occur repeatedly. However, the OS releases timer settings when the first interrupt occurs so only the first timer interrupt takes place. To generate repeated timer interrupts, processing to carry out settings needs to be done again in the interrupt handler.

Revision History

2008/02/05 Added a description of the multi-timer.
2005/03/08 Standardized the Japanese term for "interrupt."
2004/11/24 Corrected a mistake in timer ID.
2004/06/03 Added a caution about timer interrupts.
2003/12/01 Initial version.