<?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 interaction of interrupt disabling and spin locks. </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>
<example><title>Using a spin lock</title><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>
<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>. </p><p>This indicates
to the scheduler that the kernel side threads and associated interrupts can
be can be run and executed according to the kernel SMP policies.</p></section>
<section id="GUID-6B58F8D8-2776-4301-8914-96F4ABECE7C8"><title>SMP Safe</title><draft-comment time="2010-01-20T13:49" translate="no">This information will be moved to a new topic dealing
with SMP safety during 10T10. -RF</draft-comment><p>The <keyword>SMPSAFE</keyword> keyword
should only be used if the code is proven to be SMP-Safe.</p><p>Impact of
using the <keyword>SMPSAFE</keyword> keyword:</p><ul>
<li><p>If your code is proven to be SMP-Safe you can identify it is such by
inserting the <keyword>SMPSAFE</keyword> keyword into your mmp file. The kernel
will mark your application or service as SMP-safe and use whatever processors
are available according to the policies of that baseport.</p></li>
<li><p>If the code is not SMP-Safe do not use the keyword. The kernel will
run your code using the behaviours defined by the appropriate compatibility
mode, ensuring that all threads are run on a single CPU.</p></li>
</ul><p>There are two <i>SMP compatibility modes</i>: basic and enhanced.</p><ul>
<li><p>In basic mode all threads in unsafe processes are set to CPU0. There
is no chance these threads will run concurrently and therefore they are executed
in priority order, as on a single processor system.</p></li>
<li><p>In enhanced mode all the threads of a process are tied together in
a thread group. Only one thread of a thread group can be run at any time,
meaning they are executed in priority order. The benefit of the enhanced mode
is that the entire thread group may be moved from one CPU to another as system
resources and kernel policy demands. The default SMP compatibility mode is
enhanced.</p></li>
</ul><p>The decision to use basic or enhanced SMP-Safe compatibility mode
is made at design time and assigned to the kernel iby/oby file as part of
the baseport. Once set this can not be changed. This is an either or choice
and therefore mutually exclusive.</p></section>
</conbody><related-links>
<link href="GUID-387E98B0-568D-4DBB-9A9E-616E41E96B58.dita"><linktext>SMP Overview</linktext>
</link>
<link href="GUID-16AB388A-ED3E-4901-857D-834072437D25.dita"><linktext>Spin Locks</linktext>
</link>
</related-links></concept>