# VAlarm (overview)

## Introduction

The V-count alarm (also referred to as V-alarm) allows you to set calls to specified handlers at arbitrary V-counts, done using V-count interrupts and the value of the V-count register (which holds the LCD's scanning status). Its mechanism is completely different from the alarm for ticks (which uses internal handler alarms).

### Initialization

To use the V-count alarm system, begin by calling `OS_InitVAlarm()`.

You can use `OS_IsVAlarmAvailable()` to check whether or not the V-count alarm system is available.

Call `OS_EndVAlarm()` to terminate the V-count alarm system.

### Setting up a V-alarm

To set up a V-alarm, prepare an `OSVAlarm` structure object. You can set up one V-alarm for each of these objects. Initialize the object with `OS_CreateVAlarm()`.

The V-alarm is configured using `OS_SetVAlarm()`.
To set a periodic V-alarm to be called by the handler, use `OS_SetPeriodicVAlarm()`

### Canceling a V-alarm

To cancel a V-alarm, call `OS_CancelVAlarm()`. This function cancels the specified V-alarm.

`OS_CancelAllVAlarm()` cancels all V-alarms.

There is also a way to cancel by specifying tags which is discussed later.

### V-alarm Tags

You can give V-alarms a tag value in the range of 1-255. This is used to cancel all V-alarms that have the specified tag value.

`OS_SetVAlarmTag()` sets tag values for V-alarms that have already been set.

Use `OS_CancelVAlarms()` to cancel using the specified tag value. (Notice that the function name is plural.)

### Internal Data Structure

The V-alarm structure `OSVAlarm` is linked in a list in the order that V-alarms are generated.

Thus, if the V-counter structure is still connected to the list (i.e., a V-alarm has not yet been generated) and you attempt to use the structure to set other V-alarms, the list structure will be destroyed. Do not do this. If such an action is detected in the library, it will stop via `OS_Panic()`, regardless of the build.

Also, using `OS_CreateVAlarm()` to initialize a V-alarm structure that is still linked to the list (the V-alarm has not yet been generated) will destroy the list structure. Therefore, this is prohibited. In such a case behavior is indeterminate.

### V-alarm Delays

As stated previously, the `OS_SetVAlarm()` function configures the V-alarm settings. These settings specify the V-count timing with which you want to trigger the alarm (i.e., call the specified handler) and the V-count difference, which defines the tolerated delay range. This specifies how much time can pass before calling the V-alarm handler when the handler cannot be called at the specified timing because of some other interrupt process or a system stall.

If you want to call the handler with the specifically specified timing, this delay tolerance value should be set to `0`. Setting the value to `OS_VALARM_DELAY_MAX` means the V-alarm can be generated at any time at or after the specified time. Set the delay somewhere between these two values.

In the command shown below, the alarm is set with V-count = `100` and delay = `30`. The system will try to call the handler at V-count = `100`, but if it cannot do it at that time, it will make the call whenever possible up to V-count = `130`.

The V-alarm is also available as a periodic alarm. In such cases, a V-alarm is generated at the specified V-count in every frame. The settings are configured using `OS_SetPeriodicVAlarm()`.

It is all right to configure a number of V-alarms with the same V-count timing, and it is all right for the timing and delay ranges to overlap. The example below shows three alarms.

As long as the processing burden does not interfere with the alarms, the individual alarm handlers get called with the specified timing (V-count = `50`, = `60`, = `130`). In the figure below, the V-alarms are generated at the places indicated by the red triangles.

If an interrupt is inserted after the first V-alarm and the process must deal with a slight delay past the timing of the second V-alarm, that second V-alarm will be generated within the delay range if possible, as shown below.

If the process is further drawn out and the V-alarm cannot be generated within the delay range, that V-alarm comes up in the next frame. (If this V-alarm is a periodic alarm, the process in that frame is not carried out.)

This situation can arise for other than outside factors, such as when the handler process itself is too much of a load. In the figure below, the red arrows show the course of the alarm handler process. In this example, each handler process ends in a short time and does not affect another V-alarm.

In the next example, in contrast, the process for the first V-alarm is extremely heavy and extends beyond the delay range for the second V-alarm. As a result, this second V-alarm shows up in the next frame.

It is recommended that you only implement processes in which the interrupt handler ends quickly.

### Changing VCount After Wireless Synchronization

When performing wireless communications, as the result of synching parent and child, it is possible that V-count is set to a value between 202 and 210. Take note of this if you are going to set a V-alarm in this region.

## See Also

`OS Function List (V-counter alarm)`

## Revision History

11/24/2004 Described V-count changes due to wireless synchronization.
10/25/2004 Initial version (spun off of `OS_InitVAlarm()`)