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

## See Also

`OS_StopTimer*`

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

CONFIDENTIAL