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 task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <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>

    13 <prereq id="GUID-FCD339E1-54B6-4F3F-9DF0-1C920667001C"><p>The clients

    14 of the Interrupt platform service must know the following:<ul>

    15 <li><p>ISR function</p></li>

    16 <li><p>Interrupt ID</p></li>

    17 </ul></p></prereq>

    18 <context id="GUID-3EB0898F-D1ED-47D4-B675-3B8627909384"><p>Interrupts

    19 are sent by hardware to indicate an event has occurred. Interrupts

    20 typically cause an Interrupt Service Routine (ISR) to be executed.

    21 The Interrupt platform service specifies the interface APIs for setting

    22 up the ISRs and connecting them to specific Interrupt IDs. Interrupt

    23 handling is a blocking high priority task and needs to take a minimal

    24 amount of time. While the ISR is executed the kernel will be in an

    25 indeterminate state and this puts restrictions on doing various operations,

    26 such as allocating heap storage. </p><p>The device driver provides

    27 an ISR to handle an interrupt and perform the required response to

    28 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

    29 Interrupt ID with an ISR. </p><p>An Interrupt ID is identified by

    30 number, defined as a <codeph>TInt</codeph> type. Typically, the ASSP

    31 layer may define this number for each interrupt in a header file and

    32 export it so that it can be included and used by device drivers. Alternatively,

    33 device drivers may be required to retrieve the appropriate Interrupt

    34 ID from the Hardware Configuration Repository (HCR). The scheme used

    35 is implementation dependent.</p></context>

    36 <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">

    37 <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

    38 ID, ISR and argument to be passed to the ISR. This function binds

    39 the interrupt to the ISR.</cmd>

    40 </step>

    41 <step id="GUID-94DAD86A-0721-4663-A992-8FA001864B5F"><cmd>Assign the

    42 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,

    43 TInt)</apiname></xref> function.</cmd>

    44 </step>

    45 <step id="GUID-E731F5A3-B31F-43A5-BE61-81AA25DCCE3F"><cmd>Enable the

    46 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

    47 to  handle hardware events.</cmd>

    48 <info><p>An ISR is a static function that will be executed when an

    49 interrupt is received by the interrupt handler. The interrupt handler

    50 executes the ISR that is bound to the received Interrupt ID. It performs

    51 the actions necessary to service the event of the peripheral that

    52 generated the interrupt. The ISR must either remove the condition

    53 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

    54 within the ISR to perform deferred processing.</p></info>

    55 </step>

    56 <step id="GUID-A088A6FD-67B5-4112-894E-5CE1A2A3BAE6"><cmd>Once the

    57 DFC processing is completed, it is a good practice to enable the interrupt

    58 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>

    59 </step>

    60 <step id="GUID-611D449F-C0EB-4027-8E4C-D5CC5D44A29D"><cmd>At the point

    61 when the PDD of the device driver gets unloaded, unbind the ISR from

    62 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>

    63 </step>

    64 </steps>

    65 <result id="GUID-286F666E-B037-4C0E-9A87-02A3CBAB9B8A"><p>The device

    66 driver is able to handle interrupts.</p></result>

    67 </taskbody><related-links>

    68 <link href="GUID-D0F5D40A-28D2-4A2E-9B40-180537E60F56.dita"><linktext>Interrupt

    69 Client Interface Guide</linktext></link>

    70 <link href="GUID-654A788A-526A-4C3F-838C-05B09F0D5445.dita"><linktext>Interrupt

    71 Technology Guide</linktext></link>

    72 </related-links></task>