<?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-F09740DA-015B-449D-A124-0BEABBDDCB52" xml:lang="en"><title>Enabling

and Disabling</title><shortdesc>This document describes how device drivers enable and disable interrupts.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Drivers can enable and disable the interrupts on the relevant interrupt

sources while handling the interrupts using the <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita"><apiname>Interrupt</apiname></xref> class.

Typically, handling an interrupt is done with disabled interrupts. The interrupt

is then enabled after the completion of interrupt handling. </p>

<codeblock id="GUID-7805933A-51F6-5169-81D0-C1A8E9647C0D" xml:space="preserve">Interrupt::Disable(aIntId);

...

// handle interrupt

...

Interrupt::Enable(aIntId);

</codeblock>

<codeblock id="GUID-87C0A4CF-BA67-58DE-A180-EA30189BEDF4" xml:space="preserve">/**

 Interrupt Service Routine (ISR) for the UART driver. This function

 is associated with the UART interrupt, EUartIrq (value obtained from 

 TRM). This function is called whenever there is an interrupt on this 

 interrupt line and the interrupt source is enabled. The ISR must be a 

 static void function, taking a single TAny* parameter, which is an 

 object passed at the time of binding, usually a pointer to the owning

 class. Interrupt::Enable() must be called to start receiving 

 interrupts.

 The ISR implementation is hardware and driver specific. The ISR must

 be self-contained as the state of the system is indeterminate. It

 should not signal threads, allocate or de-allocate memory, copy

 memory to or from user processes, or call most Kernel functions.

 Also the whole system is blocked while the ISR is running, so it must be

 kept as short as possible. Any lengthy processing must be done in a

 delayed function call (DFC).

 A typical ISR would,

   Clear the interrupt in the peripheral.

   Disable the interrupt.

   Read or write peripheral registers, e.g. to determine errors, or 

   to start a new task.

   Read data from, or write data to, the peripheral.

   Start or stop NTimers or DMA transfer operations.

   Queue DFCs.

 @param     aParam

         pointer to object passed as parameter while binding

 */    

void DExUartPhysicalChannelH4::UartIsr(TAny* aParam)

    {

    // Do the high priority device specific interrupt handling

    // i.e. read the interrupt type from device, clear the 

    // interrupt.

    ...

    // Defer the remaining processing by queuing the respective 

    // DFC based on the interrupt type

    ...

    }</codeblock>

<p>Some operations may need to be performed with all the interrupts, not just

the particular interrupt source, disabled. In this case, the <xref href="GUID-3A3C08F3-3D33-3D9E-80E7-7855C7B21E02.dita"><apiname>NKern</apiname></xref> class

must be used to disable and enable all interrupts globally at the Interrupt

controller. <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> can disable all

IRQs, or IRQs and FIQs. <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> can

restore the interrupts to their state before disabling. </p>

<codeblock id="GUID-A34A1AEB-9B00-556D-A280-9BFF7A6BAA8C" xml:space="preserve">alevel = 1; // 1 to disable IRQs and 2 to disable IRQs and FIQs

state = NKern::DisableAllInterrupts(aLevel);

...

// perform the required operations

...

NKern::RestoreInterrupts(state);

</codeblock>

</conbody></concept>