<?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-8B7E2A72-B793-5E70-87F0-92AA0A482F23" xml:lang="en"><title>Interrupt::Bind()

and Interrupt::Unbind() </title><shortdesc>Describes two types of configuration used in the implementation

of bind and unbind functions.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The functions <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-4E3CB472-3525-32F8-9BC4-8ECFEE931E7B"><apiname>Interrupt::Bind()</apiname></xref> and <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-CCC9A397-608C-3EAF-830F-A59800C2E8E5"><apiname>Interrupt::Unbind()</apiname></xref> provide

device drivers with a way of binding ISRs to interrupt sources, and unbinding

ISRs from interrupt sources. The implementation of these functions follows

a standard pattern that can be re-used in most cases. </p>

<p>The implementation can be different if there is a single Variant DLL, or

if there is also an ASSP extension. </p>

<section id="GUID-D6F47DE3-7320-4C3A-A7BB-96B57DFF40DA"><title>Variant DLL only configuration</title> <p>The following example

implementation of <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-4E3CB472-3525-32F8-9BC4-8ECFEE931E7B"><apiname>Interrupt::Bind()</apiname></xref> assumes that all ISRs

in the ISR table have been bound, by default, to the <xref href="GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita#GUID-76A30EC4-4B99-5471-9E80-F853C91485BC/GUID-9D98586F-AD1D-5C50-9AD8-F81D72135382">spurious interrupts</xref> handler function as done in <xref href="GUID-423537D5-2C8A-5C26-8D7B-60446E95F681.dita">initialising

the table</xref>. To bind an interrupt source, the spurious interrupts handler

is replaced with the provided ISR. The implementation prevents an ISR from

being bound to an interrupt source that is already bound, by assuming that

an unbound interrupt source is bound to the spurious interrupts handler. </p> <p>The

implementation shows the basic idea but may need to be extended, especially

where <xref href="GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita#GUID-76A30EC4-4B99-5471-9E80-F853C91485BC/GUID-9026A4AC-57AF-545D-887C-AF43E0B37EDC">chained

interrupts</xref> and/or <xref href="GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita#GUID-76A30EC4-4B99-5471-9E80-F853C91485BC/GUID-ED6F2F47-7A16-5AE6-8E5B-B2475F6EDEAA">multiple

interrupt sources and pseudo interrupt sources</xref> are involved. </p> <codeblock id="GUID-EF5B6524-6070-5563-919B-881039629E2B" xml:space="preserve">EXPORT_C TInt Interrupt::Bind(TInt aId, TIsr aIsr, TAny* aPtr)

    {

       TInt r = KErrNone;

    If(TUint(aId)>=TUint(KInterruptSourceCount))

        {

        r = KErrArgument; // Illegal interrupt number

        }

       else 

        {

           SInterruptHandler& h = IsrHandlers[aId];

        TInt irq = NKern::DisableAllInterrupts();

        if (h.iIsr != &SpuriousHandler)

            {

            r = KErrInUse; // Already bound to an ISR

            }

           else

            {

            h.iPtr = aPtr; // The ISR parameter

            h.iIsr = aIsr; // Pointer to the ISR

            }

        NKern::RestoreInterrupts(irq);

        }

    return r;

    }

</codeblock> <p> <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-CCC9A397-608C-3EAF-830F-A59800C2E8E5"><apiname>Interrupt::Unbind()</apiname></xref> is the logical opposite

of <codeph>Bind()</codeph>, replacing the ISR with the spurious handler function.

The following code is the matching example implementation. </p> <codeblock id="GUID-B3240465-BF03-5977-B73C-9FF61B209F5C" xml:space="preserve">EXPORT_C TInt Interrupt::Unbind(TInt aId)

    {

       TInt r = KErrNone;

       if (TUint(aId) >= TUint(KInterruptSourceCount))

        {

        r = KErrArgument;    // Illegal interrupt number

        }

       else

        {

        SInterruptHandler& h = IsrHandlers[aId];

        TInt irq = NKern::DisableAllInterrupts();

        if (h.iIsr == &SpuriousHandler)

            {

            r = KErrGeneral; // Already unbound

            }

        else

            {

            h.iPtr =(TAny*)aId;

            h.iIsr = SpuriousHandler;  // Replace with spurious handler

            // NOTE: at this point it may be wise to

            // force the hardware interrupt source to disabled.

            }

        NKern::RestoreInterrupts(irq);

        }

    return r;

       }

</codeblock> <p>Note that functions in the <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita"><apiname>Interrupt</apiname></xref> class

can be called from anywhere in kernel-side code, including ISRs, DFCs and

IDFCs, and kernel threads. You need to ensure that if you are manipulating

the ISR table, or any other structure that is shared, you need to <i>disable</i> interrupts

to prevent corruption of the data. Interrupts are disabled and re-enabled

using <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-8C251C65-FDE7-3161-8D2B-61401FB6487F"><apiname>NKern::DisableAllInterrupts()</apiname></xref> and <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita#GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02/GUID-2D328082-3A9F-3467-81CF-B1C68866E163"><apiname>NKern::RestoreInterrupts()</apiname></xref>. </p> </section>

<section id="GUID-883CCAD1-8339-4D95-A05C-AC2AFA2786F7"><title>ASSP Extension and Variant DLL configuration</title> <p>When

a common ASSP extension is used, the Variant DLL may have to implement extra

interrupt binding and dispatch functions for the device-specific interrupts. </p> <p>The

following code is an example of an implementation of <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-4E3CB472-3525-32F8-9BC4-8ECFEE931E7B"><apiname>Interrupt::Bind()</apiname></xref> in

the ASSP layer, where negative Interrupt IDs represent device specific interrupts. </p> <codeblock id="GUID-B1FF5AEC-30D2-5A4F-8677-5757906C629B" xml:space="preserve">EXPORT_C TInt Interrupt::Bind(TInt aId, TIsr aIsr, TAny* aPtr)

    {

    TInt r = KErrNone;

    if(aId < 0 )

        {

        return MyAsic->VariantBind( aId, aIsr, aPtr ); // Device specific ID, call variant

        }

    else if (aId >= KInterruptSourceCount)

            {

            r = KErrArgument; // Illegal interrupt number

            }

        else

            {

            SInterruptHandler& h = IsrHandlers[aId];

            TInt irq = NKern::DisableAllInterrupts();

            if (h.iIsr != SpuriousHandler)

                {

                r = KErrInUse; // Already bound to an ISR

                }

            else

                {

                h.iPtr = aPtr;

                h.iIsr = anIsr;

                }

            NKern::RestoreInterrupts(irq);

            }

    return r;

    }</codeblock> <p>The default device specific implementation of the <codeph>VariantBind()</codeph> function

might be as follows: </p> <codeblock id="GUID-99850E43-605F-5FA0-95B3-3E472CA6FD56" xml:space="preserve">TInt TMyAsic::VariantBind( TInt aId, TIsr aIsr, TAny* aPtr )

    // Default implementation when device specific layer does not override

    // and this is therefore an illegal aId.

    {

    return KErrArgument;

    }

</codeblock> <p>The device specific implementation of <codeph>VariantBind()</codeph> would

follow the same general pattern as for the <codeph>Interrupt::Bind()</codeph> function

in the ASSP layer. The main difference is that the code refers to the device

specific ISR table, <codeph>VariantHandlers[]</codeph>, defined within the

device specific layer, and the interrupt ID is converted to a positive number

so that it can be used as an index into this table: </p> <codeblock id="GUID-547FA8BB-F5BB-56A4-AC8F-7FCA07C7BD9A" xml:space="preserve">SInterruptHandler VariantHandlers[KNumVariantInts];</codeblock> <codeblock id="GUID-7D86B6BA-6FED-52F7-9DB8-4EF21A734CE1" xml:space="preserve">EXPORT_C TInt TMyVariant::VariantBind(TInt aId, TIsr aIsr, TAny* aPtr)

    {

    TInt r = KErrNone;

    aId = (-aId)-1;    // convert to positive number >=0

    If (aId >= KInterruptSourceCount || aId < 0)

        {

        r = KErrArgument; // Illegal interrupt number

        }

    else

        {

        SInterruptHandler& h = VariantHandlers[aId];

        TInt irq = NKern::DisableAllInterrupts();

        if (h.iIsr != VariantSpuriousHandler)

            {

            r = KErrInUse; // Already bound to an ISR

            }

        else

            {

            h.iPtr = aPtr;

            h.iIsr = anIsr;

            }

        NKern::RestoreInterrupts(irq);

        }

    return r;

    }</codeblock> <p>Now you need a way of dispatching the interrupts and

since this is really a chained interrupt, the dispatch function can be packaged

as an ISR and bound to the core interrupt source it chains from. See <xref href="GUID-8B8CAEED-A89D-53B3-A311-51CF45B334B1.dita">IRQ and FIQ Dispatchers</xref> in

general and <xref href="GUID-8B8CAEED-A89D-53B3-A311-51CF45B334B1.dita#GUID-8B8CAEED-A89D-53B3-A311-51CF45B334B1/GUID-3F0D4E4E-8D9C-51FD-A701-65C29D54AB94">Dealing

with chained interrupts</xref> in particular. </p> </section>

</conbody><related-links>

<link href="GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita#GUID-76A30EC4-4B99-5471-9E80-F853C91485BC/GUID-A87DE0F9-2095-5CA6-BE88-3A2EAABB0D33">

<linktext>Interrupts in the                 split ASSP/Variant Configuration</linktext>

</link>