<?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-F4B2D20B-8F1D-4A4B-8ECB-65BE8E9824DD" xml:lang="en"><title>Interrupt Overview</title><shortdesc>Hardware or software uses interrupts to indicate an event

has occurred, such as a data buffer being ready or a key has been

pressed.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Interrupts are sent by hardware or software 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. </p>

<p>Interrupts can be managed using the <xref href="GUID-A5D862E4-3EC3-45C0-B635-23A02E5BB11F.dita">GPIO</xref> platform

service when an interrupt source is connected through GPIO pins. </p>

<p>The Interrupt platform service is used by the device drivers that

use an interrupt source routed directly to the interrupt controller

hardware. For more information on how to use GPIO to manage interrupts,

see <xref href="GUID-745273E3-BB3A-59BF-9C33-6C8BB3D850A9.dita">GPIO Design

Considerations</xref>.</p>

<p>Not all hardware events are indicated by interrupts; hardware may

indicate a status change by setting a value in a register or sending

a command/signal over a bus.</p>

<section id="GUID-DEAC516A-6147-5EFE-A6F9-5069F4B3310C"><title>What

is the Interrupt platform service</title> <p>The Interrupt platform

service specifies certain APIs for attaching an Interrupt Service

Routine to an API. It is the low level interface between hardware/software

interrupts, and the kernel and kernel level device drivers.</p> </section>

<section id="GUID-E075BEC5-7112-4280-A65D-67933977AE01"><title>Required

background</title> <p>You should be familiar with the following: </p> <ul>

<li id="GUID-D06AC743-F0CD-5EDB-807E-04498CC89C92"><p>Writing a C++

function that is either global or is in a static class so that the

function address can be used for the ISR.</p> </li>

<li id="GUID-C81342F9-001D-5E17-ABC2-A44D4A7837D2"><p>The specification

for your hardware, including determining interrupt IDs.</p> </li>

</ul> </section>

<section id="GUID-FE8CA9F1-F07D-4D41-B0BC-CE08FFA6C9C9"><title>Key

concepts and terms</title> <p>The following concepts are relevant

to this component: </p> <dl>

<dlentry>

<dt>Interrupt ID</dt>

<dd><p>An identifier which says which interrupt has occurred. Typically

an unsigned integer.</p> </dd>

</dlentry>

<dlentry>

<dt>Interrupt Service Routine (ISR)</dt>

<dd><p>An ISR is a static function which is called when an interrupt

is received. It should be very short, allocate no memory on the heap,

store any volatile information that needs to be captured for that

event, and, if required, queue a DFC for further processing.</p> </dd>

</dlentry>

<dlentry>

<dt>Bind</dt>

<dd><p>Connects an Interrupt ID to an Interrupt Service Routine. Unbind

removes the connection.</p> </dd>

</dlentry>

<dlentry>

<dt>Enable</dt>

<dd><p>When an interrupt occurs, execute the associated Interrupt

Service Routine.</p> </dd>

</dlentry>

</dl> </section>

<section id="GUID-FE6584D8-C6E9-43F4-AF97-0DBBA0240E88-GENID-1-2-1-10-1-5-1-7-1-1-4-1-3-8"><title>The

Interrupt class</title> <p>The interrupt interface is provided by

functions of the <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita"><apiname>Interrupt</apiname></xref> class. The class is

defined in the <filepath>os/kernelhwsrv/kernel/eka/include/kernel/arm/assp.h</filepath> file. </p> </section>

<section id="GUID-3D6816E8-2B1E-4709-81B5-D0A469A2A268"><title>Key

users</title> <p>The key users of the Interrupt platform service are

kernel and kernel-level device driver writers, and anyone who needs

to specify code to be run when a system event occurs. </p> </section>

<section id="GUID-FE6584D8-C6E9-43F4-AF97-0DBBA0240E88-GENID-1-2-1-10-1-5-1-7-1-1-4-1-3-10"><title>Limitations</title><ul>

<li><p>The ISR needs to complete in short and finite time to prevent

excessive interrupt latency.</p></li>

<li><p>To keep ISRs short, most of the event processing should be

delegated to a DFC. The DFC will execute in the context of a DFC thread

allocated to itself by the device driver.</p></li>

<li><p>It is safe to access the device driver objects using appropriate

synchronization techniques such as spin-locks.</p></li>

<li><p>The ISR should store critical data which may not be available

later. </p></li>

<li><p>Interrupts can happen in the middle of updating kernel heap

free list or other non-atomic actions. ISRs must be coded with that

in mind.</p></li>

</ul><p>This means that ISRs cannot:</p><ul>

<li><p>access user process memory.  This includes completing an asynchronous

request.</p></li>

<li><p>perform any allocation / de-allocation on heaps.  The current

interrupt might have occurred when a heap operation is already in

progress.</p></li>

</ul><p>It is therefore necessary that ISRs must only use pre-allocated

objects on the kernel heap.</p> </section>

</conbody><related-links>

<link href="GUID-862CA4C4-C6E8-4D60-8DD0-F3590C92E15D.dita"><linktext>Interrupt

Client Interface</linktext></link>

<link href="GUID-2E54DA7D-1094-41C6-AFB0-9999471991F8.dita"><linktext>Interrupt

Implementation Guide</linktext></link>

</related-links></concept>