<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-68446E8E-129C-444A-836A-EF8F56BFE0BC" xml:lang="en"><title>Handling Interrupts</title><shortdesc>Describes how a device driver can use interrupts.</shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<prereq id="GUID-FCD339E1-54B6-4F3F-9DF0-1C920667001C"><p>The clients
of the Interrupt platform service must know the following:<ul>
<li><p>ISR function</p></li>
<li><p>Interrupt ID</p></li>
</ul></p></prereq>
<context id="GUID-3EB0898F-D1ED-47D4-B675-3B8627909384"><p>Interrupts
are sent by hardware to indicate an event has occurred. Interrupts
typically cause an Interrupt Service Routine (ISR) to be executed.
The Interrupt platform service specifies the interface APIs for setting
up the ISRs and connecting them to specific Interrupt IDs. Interrupt
handling is a blocking high priority task and needs to take a minimal
amount of time. While the ISR is executed the kernel will be in an
indeterminate state and this puts restrictions on doing various operations,
such as allocating heap storage. </p><p>The device driver provides
an ISR to handle an interrupt and perform the required response to
the events. Symbian platform provides an <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita"><apiname>Interrupt</apiname></xref> class (implemented by the ASSP) with an API to bind and unbind an
Interrupt ID with an ISR. </p><p>An Interrupt ID is identified by
number, defined as a <codeph>TInt</codeph> type. Typically, the ASSP
layer may define this number for each interrupt in a header file and
export it so that it can be included and used by device drivers. Alternatively,
device drivers may be required to retrieve the appropriate Interrupt
ID from the Hardware Configuration Repository (HCR). The scheme used
is implementation dependent.</p></context>
<steps id="GUID-4DD07DEC-6017-4237-BE46-1D69E5FBD744-GENID-1-2-1-10-1-5-1-7-1-1-8-1-6-1-3-3">
<step id="GUID-0CFB6DD5-2309-40EE-84F5-4BC4449BE5BB"><cmd>Call <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-1D846CC9-843D-363B-A0F2-5719B18C0854"><apiname>Interrupt::Bind(TInt, TIsr, TAny*)</apiname></xref> with appropriate Interrupt
ID, ISR and argument to be passed to the ISR. This function binds
the interrupt to the ISR.</cmd>
</step>
<step id="GUID-94DAD86A-0721-4663-A992-8FA001864B5F"><cmd>Assign the
priority to the Interrupt if needed using the <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-975988C3-B9B0-3B82-8CE8-9691E8C54515"><apiname>Interrupt::SetPriority(TInt,
TInt)</apiname></xref> function.</cmd>
</step>
<step id="GUID-E731F5A3-B31F-43A5-BE61-81AA25DCCE3F"><cmd>Enable the
interrupt by calling the <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-23BE001A-205A-33AE-9533-8D50C494211F"><apiname>Interrupt::Enable(TInt)</apiname></xref> function. This function is called when the device driver is ready
to  handle hardware events.</cmd>
<info><p>An ISR is a static function that will be executed when an
interrupt is received by the interrupt handler. The interrupt handler
executes the ISR that is bound to the received Interrupt ID. It performs
the actions necessary to service the event of the peripheral that
generated the interrupt. The ISR must either remove the condition
that caused the interrupt or call  <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-2D14E023-E6ED-39BF-8B31-6FA510957A8A"><apiname>Interrupt::Disable()</apiname></xref> otherwise the machine will hang. The device driver may queue a DFC
within the ISR to perform deferred processing.</p></info>
</step>
<step id="GUID-A088A6FD-67B5-4112-894E-5CE1A2A3BAE6"><cmd>Once the
DFC processing is completed, it is a good practice to enable the interrupt
if it is disabled, using <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-23BE001A-205A-33AE-9533-8D50C494211F"><apiname>Interrupt::Enable(TInt)</apiname></xref> function. </cmd>
</step>
<step id="GUID-611D449F-C0EB-4027-8E4C-D5CC5D44A29D"><cmd>At the point
when the PDD of the device driver gets unloaded, unbind the ISR from
the specified Interrupt Id using <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-4980B3FF-0C14-3E64-8BB3-E8431CB649F9"><apiname>Interrupt::Unbind(TInt)</apiname></xref> function by passing Interrupt ID as the parameter.</cmd>
</step>
</steps>
<result id="GUID-286F666E-B037-4C0E-9A87-02A3CBAB9B8A"><p>The device
driver is able to handle interrupts.</p></result>
</taskbody><related-links>
<link href="GUID-D0F5D40A-28D2-4A2E-9B40-180537E60F56.dita"><linktext>Interrupt
Client Interface Guide</linktext></link>
<link href="GUID-654A788A-526A-4C3F-838C-05B09F0D5445.dita"><linktext>Interrupt
Technology Guide</linktext></link>
</related-links></task>