<?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-821C254A-40C6-45F9-B2F9-2CF28CAEB8CC" xml:lang="en"><title>Interrupt
Handling</title><shortdesc>Describes how interrupts are handled in the SMP environment.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>An interrupt is a signal from a hardware device or from an executable which
causes a CPU to suspend normal execution, enter the interrupt handling state
and jump to an interrupt handler. An interrupt handler, or ISR (interrupt
service routine), schedules a DFC (delayed function call) on a DFC queue.</p>
<section id="GUID-71D802FC-9A50-4BEB-8F21-497A7D04C814"><title>SMP-Safe Interrupt
Handling</title><p>Interrupt handlers are used to implement the functionality
of device drivers.</p><p>When a DFC executes on a unicore system, it disables
interrupts to avoid clashing with its own ISR. </p><p>On a multicore system
this is not sufficient to maintain data integrity. To maintain data integrity
on an SMP system the code must:</p><ol>
<li id="GUID-9A9C8A79-D53C-4B39-B108-86A0B04FCBE9"><p> acquire a spin lock
on any data to be written, to block other cores from accessing the data.</p></li>
<li id="GUID-87F5A9E5-2932-4BE8-8126-ECC1D4458476"><p>Interrupts must be disabled,
as on unicore, before the spin lock is acquired.</p></li>
</ol><p> Although these are conceptually two separate tasks, you use the spin
lock API <xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref> in <filepath>nkern.h</filepath> to perform
both tasks at the same time.</p><p>The following macros provide SMP-safe interrupt
handling in most situations.</p><ul>
<li><p><xref href="GUID-DBC27EF9-9C56-3FE8-B93C-BA2A74E1E6E6.dita"><apiname>__SPIN_LOCK_IRQSAVE</apiname></xref></p></li>
<li><p><xref href="GUID-04EEFC44-C7FF-37D2-A8F1-7FBCDBAF9EE2.dita"><apiname>__SPIN_LOCK_IRQRESTORE</apiname></xref></p></li>
</ul><p>If code using these macros is executed on a unicore system, they will
disable interrupts in the normal way.</p><p>There are several other macros
that can be used in the non standard situations or when you require greater
control over the ordering of the delayed function call.</p><ul>
<li><p><xref href="GUID-A6C6CADA-1552-3873-89BA-6DBDC6402FF2.dita"><apiname>__SPIN_LOCK_IRQSAVE(lock)</apiname></xref></p><p>Standard SMP-safe
macro</p></li>
<li><p><xref href="GUID-E7AB9188-3C0C-3267-96CF-751FD7C778EF.dita"><apiname> __SPIN_UNLOCK_IRQRESTORE(lock,irq)</apiname></xref></p><p>Standard
SMP-safe macro</p></li>
<li><p> <xref href="GUID-8E0151AC-1F70-35BE-9DBA-659C3054C8FA.dita"><apiname>__SPIN_FLASH_IRQRESTORE(lock,irq)</apiname></xref></p></li>
<li><p><xref href="GUID-33E2A493-8F2F-32C1-A93C-A50F358C8126.dita"><apiname> __SPIN_LOCK(lock) __SPIN_UNLOCK(lock)</apiname></xref></p></li>
<li><p><xref href="GUID-A9CDB15E-D435-3043-B9CA-265CC5C598DA.dita"><apiname> __SPIN_FLASH_PREEMPT(lock)</apiname></xref></p></li>
<li><p> <xref href="GUID-5EF6D33D-998F-3BFD-95F1-478541221B35.dita"><apiname>__SPIN_LOCK_IRQ(lock)</apiname></xref></p></li>
<li><p><xref href="GUID-F8FA6FEA-56A2-3924-BA59-8DF4B0546AC9.dita"><apiname> __SPIN_UNLOCK_IRQ(lock)</apiname></xref></p></li>
<li><p> <xref href="GUID-E474AC45-13AE-3DE5-857C-7BE76EE084E3.dita"><apiname>__SPIN_FLASH_IRQ(lock)</apiname></xref></p></li>
</ul><note><p> To ensure SMP Safety in Symbian^3, the kernel ensures that
device driver, ISR and DFC are all tied to the same CPU. CPU0 has been stipulated
for this purpose.</p></note></section>
<section id="GUID-8BF9726E-B8E4-4558-98A4-7163CD13774A"><title>Making your
device driver SMP safe</title><p>Once a device driver has been migrated to
be SMP Safe using the advice above, the mmp file of each driver's binaries
must be updated with the keyword <keyword>SMPSAFE</keyword>. As stated earlier,
all kernel side threads and associated interrupts are locked to CPU0 for Symbian^3.
Starting in Symbian^4 any binaries with <keyword>SMPSAFE</keyword> will be
unlocked from CPU0 so they can be executed on any core. </p><p> <keyword>SMPSAFE</keyword> only
has any effect when Compatibility Mode (see general impacts page) is being
used. For interim testing of device driver migration, the CPU affinity API’s
may be used to test driver thread migration. For example, </p><codeblock xml:space="preserve">NKern::ThreadSetCpuAffinity(NKern::CurrentThread(),KCpuAffinityAny);</codeblock></section>
<example><p>In the following example, a spin lock protects memory being written
by <codeph>DfcFun()</codeph> on CPU0 from corruption by <codeph>ISRFun()</codeph> running
on a different core.</p><p>This code runs on CPU0:<codeblock xml:space="preserve">void DfcFun(TAny* aPtr)
	{
	…
   irq = __SPIN_LOCK_IRQSAVE(iLock);
   iState = EProcessed;
   __SPIN_UNLOCK_IRQRESTORE(iLock,irq);

	...
	}
</codeblock></p><p>This code runs on a different core:<codeblock xml:space="preserve">void ISRFun(TAny* aPtr)
	{
   __SPIN_LOCK(iLock);	
	iState = EProcessing;
	__SPIN_UNLOCK(iLock);
	}
</codeblock></p></example>
</conbody><related-links>
<link href="GUID-387E98B0-568D-4DBB-9A9E-616E41E96B58.dita"><linktext>SMP Overview</linktext>
</link>
</related-links></concept>