<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-F54BB3B5-D069-4524-A215-6F2CCA372666" xml:lang="en"><title>Nanokernel

Timer</title><shortdesc>This document describes nanokernel timers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-2788AEE3-FF4A-49CD-9093-00D28EEA49A6"><title>Creation</title> <p> <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> is

a basic relative timer provided by the nanokernel. It can generate either

a single interrupt or periodic interrupts. A timeout handler is called when

the timer expires, either from the timer ISR or from the nanokernel timer

thread. These timer objects can manipulated from any context. The timers are

driven from a periodic system tick interrupt, usually a 1ms period. The use

of <codeph>NTimer</codeph> is as follows: </p></section>

<section id="GUID-AA99FC77-5D00-41C5-A000-A2692DB32B10"><title>Start</title> <p>The

nanokernel timer can be used in either single mode or in periodic mode. Typically,

the timer is started with <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita#GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2/GUID-0491D2BD-CF23-33A0-8531-28DD41AABE44"><apiname>NTimer::OneShot()</apiname></xref> for a timeout

period and then is made periodic by calling <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita#GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2/GUID-F544F71E-3BB8-3570-A8DE-44009BBFFD3D"><apiname>NTimer::Again()</apiname></xref>.

The timeout value specified for the timer is in nanokernel ticks. The time

out callback function can be chosen to be called in either an ISR context

or a DFC context (running in the kernel's nanokernel timer thread, called <codeph>DfcThread1</codeph>). </p> <codeblock id="GUID-680FD449-139A-57D2-AEC1-527E44ABC3AC" xml:space="preserve">TInt NTimer::OneShot(TInt aTime, TBool aDfc);

// If aDfc is TRUE then, the timeout function is called in a DFC context; 

// if aDfc is FALSE, the timeout function is called in a ISR context.

// Starts timer in zero-drift mode, to avoid delays in re-queuing

// the timer

TInt NTimer::Again(TInt aTime); 

// NTimer::OneShot() starts a nanokernel timer in one-shot mode with 

// ISR callback. It queues the timer to expire in the specified number 

// of nanokernel ticks. The actual wait time will be at least that 

// much and may be up to one tick more. The expiry handler will be 

// called in ISR context.

//

iRxPollTimer.OneShot(KRxTimeout);</codeblock></section>

<section id="GUID-96D4B91A-580A-4D0C-BFA5-2FFDDA8DF12A"><title>Callback function </title> <p>The

timeout callback function is called when a timer started with <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita#GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2/GUID-0491D2BD-CF23-33A0-8531-28DD41AABE44"><apiname>NTimer::OneShot()</apiname></xref> or <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita#GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2/GUID-F544F71E-3BB8-3570-A8DE-44009BBFFD3D"><apiname>NTimer::Again()</apiname></xref> expires.

A driver should implement the function to process the timeout event as appropriate

for the situation. </p> <codeblock id="GUID-68C267FE-87B0-5B68-AB6B-69BEBB77B1D9" xml:space="preserve">/**

 Timer callback function. Called when the NTimer expires

 typedef void(* NTimerFn)(TAny*); is the nanokernel timer callback

 function. This is used for Rx timeout.

 @params    aPtr

         pointer refernce passed during timer initialization

 */

void DExUartPhysicalChannelH4::RxPollTimerCallback(TAny* aPtr)

    {

    ... // design specific

    }</codeblock></section>

<section id="GUID-3D2ED5C0-35AD-4695-8945-256B5866BF61"><title>Cancellation</title> <p>A

timer can be cancelled using <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita#GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2/GUID-F03A72CF-AD7F-363E-A351-8DA50416D949"><apiname>NTimer::Cancel()</apiname></xref>. It removes

the timer object from the nanokernel timer queue. If the timer has already

expired, or is inactive, then it does nothing. </p> <p>If a timer was queued

and a DFC callback was requested, then the expiry handler might run even after <codeph>Cancel()</codeph> has

been called. This occurs when the <codeph>DfcThread1</codeph> is preempted

just before calling the expiry handler for this timer, and the preempting

thread/ISR/IDFC calls <codeph>Cancel()</codeph> on the timer. </p></section>