# SND_SetupAlarm

## Syntax

      #include <nitro/snd.h>

      typedef void (*SNDAlarmHandler)( void* arg );

      void SND_SetupAlarm(
              int alarmNo,
              u32 tick,
              u32 period,
              SNDAlarmHandler handler,
              void* arg );

## Arguments

`alarmNo` | The alarm number. Takes a value between 0 and 7.
`tick` | The tick count until the first sound of the alarm.
`period` | The periodic spacing for sounding the alarm.
`handler` | The alarm handler called when alarm is invoked. This callback is called from within the interrupt handler.
`arg` | The value passed to the alarm handler's argument.

## Return Values

None.

## Description

This function sets up the sound alarm.

Use the Sound alarm to conduct processes accurately synchronized with channel sounds and captures. Start alarms with the `SND_StartTimer` function.

The alarm will sound `tick` tick-counts after the alarm has been started. It will sound with a periodicity specified by `period`. If 0 is specified for `period`, the alarm will sound once and then stop automatically.

When the alarm sounds, the alarm handler `handler` gets called and `arg` gets passed to the alarm handler's argument. `arg` is passed to the alarm handler argument.

The values for the tick-count `tick` and the alarm period `period` are expressed in units of 1/32 of the sound timer clock `SND_TIMER_CLOCK`. Thus, if a channel has the channel timer value `timer` and you want to completely synchronize with that channel, you would set `timer`/32. For this, `timer` must be divided by 32.

### Note

This function is an ARM7 reserved function. After this function is called, its processing will occur only after the command is issued with the `SND_FlushCommand` function.

If program execution must be synchronized with process completion, first use the `SND_GetCurrentCommandTag` function to obtain the command tag immediately after calling this function. Then, after the command is issued, use the command tag and call either the `SND_IsFinishedCommandTag` or `SND_WaitForCommandProc` function to confirm that processing has finished or to wait for it to complete.

## See Also

`SND_StartTimer, SND_FlushCommand, SND_GetCurrentCommandTag, SND_IsFinishedCommandTag, SND_WaitForCommandProc`

## Revision History

2005/06/01 Added statement about callbacks being called from the interrupt handler.
2005/02/17 Added cautions for ARM7 command processing.
2004/10/21 Standardized terminology so handler argument is referred to as alarm handler.
2004/07/20 Initial version

CONFIDENTIAL