|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-F54BB3B5-D069-4524-A215-6F2CCA372666" xml:lang="en"><title>Nanokernel |
|
13 Timer</title><shortdesc>This document describes nanokernel timers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <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 |
|
15 a basic relative timer provided by the nanokernel. It can generate either |
|
16 a single interrupt or periodic interrupts. A timeout handler is called when |
|
17 the timer expires, either from the timer ISR or from the nanokernel timer |
|
18 thread. These timer objects can manipulated from any context. The timers are |
|
19 driven from a periodic system tick interrupt, usually a 1ms period. The use |
|
20 of <codeph>NTimer</codeph> is as follows: </p></section> |
|
21 <section id="GUID-AA99FC77-5D00-41C5-A000-A2692DB32B10"><title>Start</title> <p>The |
|
22 nanokernel timer can be used in either single mode or in periodic mode. Typically, |
|
23 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 |
|
24 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>. |
|
25 The timeout value specified for the timer is in nanokernel ticks. The time |
|
26 out callback function can be chosen to be called in either an ISR context |
|
27 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); |
|
28 // If aDfc is TRUE then, the timeout function is called in a DFC context; |
|
29 // if aDfc is FALSE, the timeout function is called in a ISR context. |
|
30 |
|
31 // Starts timer in zero-drift mode, to avoid delays in re-queuing |
|
32 // the timer |
|
33 TInt NTimer::Again(TInt aTime); |
|
34 |
|
35 // NTimer::OneShot() starts a nanokernel timer in one-shot mode with |
|
36 // ISR callback. It queues the timer to expire in the specified number |
|
37 // of nanokernel ticks. The actual wait time will be at least that |
|
38 // much and may be up to one tick more. The expiry handler will be |
|
39 // called in ISR context. |
|
40 // |
|
41 iRxPollTimer.OneShot(KRxTimeout);</codeblock></section> |
|
42 <section id="GUID-96D4B91A-580A-4D0C-BFA5-2FFDDA8DF12A"><title>Callback function </title> <p>The |
|
43 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. |
|
44 A driver should implement the function to process the timeout event as appropriate |
|
45 for the situation. </p> <codeblock id="GUID-68C267FE-87B0-5B68-AB6B-69BEBB77B1D9" xml:space="preserve">/** |
|
46 Timer callback function. Called when the NTimer expires |
|
47 typedef void(* NTimerFn)(TAny*); is the nanokernel timer callback |
|
48 function. This is used for Rx timeout. |
|
49 |
|
50 @params aPtr |
|
51 pointer refernce passed during timer initialization |
|
52 */ |
|
53 void DExUartPhysicalChannelH4::RxPollTimerCallback(TAny* aPtr) |
|
54 { |
|
55 ... // design specific |
|
56 }</codeblock></section> |
|
57 <section id="GUID-3D2ED5C0-35AD-4695-8945-256B5866BF61"><title>Cancellation</title> <p>A |
|
58 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 |
|
59 the timer object from the nanokernel timer queue. If the timer has already |
|
60 expired, or is inactive, then it does nothing. </p> <p>If a timer was queued |
|
61 and a DFC callback was requested, then the expiry handler might run even after <codeph>Cancel()</codeph> has |
|
62 been called. This occurs when the <codeph>DfcThread1</codeph> is preempted |
|
63 just before calling the expiry handler for this timer, and the preempting |
|
64 thread/ISR/IDFC calls <codeph>Cancel()</codeph> on the timer. </p></section> |
|
65 </conbody></concept> |