1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<TITLE>VAlarm: Overview</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">V Count Alarm: Overview <IMG src="../../image/NTR.gif" align="middle"><IMG src="../../image/TWL.gif" align="middle"></H1> 12<P>The V count alarm allows you to set calls to specified handlers at arbitrary V counts, done using the value of the V count register (which holds the LCD's scanning status) and V counter match interrupt. Its mechanism is completely different from the alarm that uses ticks (which uses an internal hardware timer).</P> 13<H2>Initialization</H2> 14<P>To use the V count alarm system, begin by calling <nobr><A href="OS_InitVAlarm.html"><CODE>OS_InitVAlarm()</CODE></A></nobr>.</P> 15<P>You can use <CODE><A href="OS_IsVAlarmAvailable.html">OS_IsVAlarmAvailable()</A></CODE> to check whether or not the V count alarm system is available.</P> 16<P>Call <CODE><A href="OS_EndVAlarm.html">OS_EndVAlarm()</A></CODE> to terminate the V count alarm system.</P> 17<H2>Setting Up a V Count Alarm</H2> 18<P>To set up a V count alarm, prepare an OSVAlarm structure object. You can set up one V count alarm for each of these objects. Initialize the object using <nobr><CODE><A href="OS_CreateVAlarm.html">OS_CreateVAlarm()</A></CODE></nobr>.</P> 19<P>The V count alarm is configured using <CODE><A href="OS_SetVAlarm.html">OS_SetVAlarm()</A></CODE>. To set a periodic V count alarm to be called by the handler, use <CODE><A href="OS_SetPeriodicVAlarm.html">OS_SetPeriodicVAlarm()</A></CODE>.</P> 20<H2>Canceling a V Count Alarm</H2> 21<P>To cancel a V count alarm, call <CODE><A href="OS_CancelVAlarm.html">OS_CancelVAlarm()</A></CODE>. This function cancels the specified V count alarm.</P> 22<P>The <CODE><A href="OS_CancelAllVAlarms.html">OS_CancelAllVAlarms</A></CODE> function cancels all V count alarms.</P> 23<P>Another method (described below) uses tag values to cancel groups of alarms. </P> 24<H2>V Count Alarm Tags</H2> 25<P>You can give V count alarms a tag value in the range of 1-255. This is used to cancel all V count alarms that have the specified tag value.</P> 26<P><CODE><A href="OS_SetVAlarmTag.html">OS_SetVAlarmTag()</A></CODE> sets tag values for V count alarms that have already been set.</P> 27<P>To cancel all alarms with a given tag value, use <nobr><code><A href="OS_CancelVAlarms.html">OS_CancelVAlarms()</a></code></nobr>. (Note that the function name is plural.) </P> 28<H2>Internal Data Structure</H2> 29<P>The V count alarm structure OSVAlarm is linked in a list in the order that V count alarms are generated.</P> 30<P>If a given alarm structure is still connected to the list, that means its alarm has not yet gone off. Do not use this structure to set another alarm, because that will corrupt the link structure. If a structural corruption is detected, <a href="../debug/OS_Panic.html"><code>OS_Panic</code></a> stops the library, regardless of the build.</P> 31<P><IMG src="image_valarmLink.gif" border="0"></P> 32<P>Using <CODE><A href="OS_CreateVAlarm.html">OS_CreateAlarm()</A></CODE> to initialize an alarm structure that is still connected to the list is also prohibited, since this can corrupt the link structure and cause unstable behavior. </P> 33<H2>V Count Alarm Delays</H2> 34<P>The V count alarm is configured using <CODE><A href="OS_SetVAlarm.html">OS_SetVAlarm()</A></CODE>. These settings specify the V count timing with which you want to 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 count alarm handler when the handler cannot be called at the specified timing because of some other interrupt process or a system stall.</P> 35<P>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 <CODE>OS_VALARM_DELAY_MAX</CODE> means the V count alarm can be generated at any time at or after the specified time. Set the delay somewhere between these two values.</P> 36<P>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.</P> 37<BLOCKQUOTE><IMG src="image_valarm1.gif" border="0"></BLOCKQUOTE> 38<P>The V count alarm is also available as a periodic alarm. In such cases, a V count alarm is generated at the specified V count in every frame. The settings are configured using <A href="OS_SetPeriodicVAlarm.html"><CODE>OS_SetPeriodicVAlarm()</CODE></A>.</P> 39<BLOCKQUOTE><IMG src="image_valarm2.gif" border="0"></BLOCKQUOTE> 40<P>It is all right to configure a number of V count alarms with the same V count timing, and it is all right for the timing and delay ranges to overlap.</P> 41<H2>Example</H2> 42<P>The example below shows three V count alarms.</P> 43<BLOCKQUOTE><IMG src="image_valarm_ex1.gif" border="0"></BLOCKQUOTE> 44<P>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 count alarms are generated at the places indicated by the red downward arrows.</P> 45<BLOCKQUOTE><IMG src="image_valarm_ex2.gif" border="0"></BLOCKQUOTE> 46<P>If an interrupt is inserted after the first V count alarm and the process must deal with a slight prolongation past the timing of the second V count alarm, that second V count alarm will be generated within the delay range if possible, as shown below.</P> 47<BLOCKQUOTE><IMG src="image_valarm_ex3.gif" border="0"></BLOCKQUOTE> 48<P>If the process is further drawn out and the V count alarm cannot be generated within the delay range, that V count alarm comes up in the next frame. (If this V count alarm is a periodic alarm, the process in that frame is not carried out.))</P> 49<BLOCKQUOTE><IMG src="image_valarm_ex4.gif" border="0"></BLOCKQUOTE> 50<P>This situation, where the V count alarm is postponed until the next frame, 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 orange arrows pointing to the right ( —> ) 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 count alarm.</P> 51<BLOCKQUOTE><IMG src="image_valarm_ex5.gif" border="0"></BLOCKQUOTE> 52<P>In the next example, in contrast, the process for the first V count alarm is extremely heavy and extends beyond the delay range for the second V count alarm. As a result, this second V count alarm shows up in the next frame.</P> 53<BLOCKQUOTE><IMG src="image_valarm_ex6.gif" border="0"></BLOCKQUOTE> 54<P>We recommend that your processes generally end the interrupt handler quickly.</P> 55<H2>Changes to the V-Counter Register Value Due to MP Communications V-Blank Synchronization</H2> 56<P>During MP communications, V-blank synchronization between parent and child can cause the V-counter register value to vary over the range of 202 to 210. Change always involves the value being set to something smaller than its original value. (For example, the value 208 is changed to a smaller value 205.) Take note of this if you are going to set a V count alarm in this range.</P> 57<H2>See Also</H2> 58<P><CODE><A href="../list_os.html#VAlarm">OS Function List (V counter alarm)</A><BR></CODE></P> 59<H2>Revision History</H2> 60<P> 612007/10/16 Standardized terminology, changing "wireless synchronization" to "MP communications V-blank synchronization."<br>2005/03/08 Standardized terminology in Japanese text for "interrupt."<br>2004/12/13 Corrected terms and suffixes.<BR>2004/11/24 Added text about <CODE>vcount</CODE> changes due to wireless synchronization.<BR>2004/10/25 Initial version (Separated from <CODE>OS_InitVAlarm()</CODE>).</P> 62<hr><p>CONFIDENTIAL</p></body> 63</HTML>
