1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-821C254A-40C6-45F9-B2F9-2CF28CAEB8CC" xml:lang="en"><title>Interrupt

    13 Handling</title><shortdesc>Describes how interrupts are handled in the SMP environment.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>An interrupt is a signal from a hardware device or from an executable which

    15 causes a CPU to suspend normal execution, enter the interrupt handling state

    16 and jump to an interrupt handler. An interrupt handler, or ISR (interrupt

    17 service routine), schedules a DFC (delayed function call) on a DFC queue.</p>

    18 <section id="GUID-71D802FC-9A50-4BEB-8F21-497A7D04C814"><title>SMP-Safe Interrupt

    19 Handling</title><p>Interrupt handlers are used to implement the functionality

    20 of device drivers.</p><p>When a DFC executes on a unicore system, it disables

    21 interrupts to avoid clashing with its own ISR. </p><p>On a multicore system

    22 this is not sufficient to maintain data integrity. To maintain data integrity

    23 on an SMP system the code must:</p><ol>

    24 <li id="GUID-9A9C8A79-D53C-4B39-B108-86A0B04FCBE9"><p> acquire a spin lock

    25 on any data to be written, to block other cores from accessing the data.</p></li>

    26 <li id="GUID-87F5A9E5-2932-4BE8-8126-ECC1D4458476"><p>Interrupts must be disabled,

    27 as on unicore, before the spin lock is acquired.</p></li>

    28 </ol><p> Although these are conceptually two separate tasks, you use the spin

    29 lock API <xref href="GUID-FB1605A8-9946-364C-A649-DEF60E1F761B.dita"><apiname>TSpinLock</apiname></xref> in <filepath>nkern.h</filepath> to perform

    30 both tasks at the same time.</p><p>The following macros provide SMP-safe interrupt

    31 handling in most situations.</p><ul>

    32 <li><p><xref href="GUID-DBC27EF9-9C56-3FE8-B93C-BA2A74E1E6E6.dita"><apiname>__SPIN_LOCK_IRQSAVE</apiname></xref></p></li>

    33 <li><p><xref href="GUID-04EEFC44-C7FF-37D2-A8F1-7FBCDBAF9EE2.dita"><apiname>__SPIN_LOCK_IRQRESTORE</apiname></xref></p></li>

    34 </ul><p>If code using these macros is executed on a unicore system, they will

    35 disable interrupts in the normal way.</p><p>There are several other macros

    36 that can be used in the non standard situations or when you require greater

    37 control over the ordering of the delayed function call.</p><ul>

    38 <li><p><xref href="GUID-A6C6CADA-1552-3873-89BA-6DBDC6402FF2.dita"><apiname>__SPIN_LOCK_IRQSAVE(lock)</apiname></xref></p><p>Standard SMP-safe

    39 macro</p></li>

    40 <li><p><xref href="GUID-E7AB9188-3C0C-3267-96CF-751FD7C778EF.dita"><apiname> __SPIN_UNLOCK_IRQRESTORE(lock,irq)</apiname></xref></p><p>Standard

    41 SMP-safe macro</p></li>

    42 <li><p> <xref href="GUID-8E0151AC-1F70-35BE-9DBA-659C3054C8FA.dita"><apiname>__SPIN_FLASH_IRQRESTORE(lock,irq)</apiname></xref></p></li>

    43 <li><p><xref href="GUID-33E2A493-8F2F-32C1-A93C-A50F358C8126.dita"><apiname> __SPIN_LOCK(lock) __SPIN_UNLOCK(lock)</apiname></xref></p></li>

    44 <li><p><xref href="GUID-A9CDB15E-D435-3043-B9CA-265CC5C598DA.dita"><apiname> __SPIN_FLASH_PREEMPT(lock)</apiname></xref></p></li>

    45 <li><p> <xref href="GUID-5EF6D33D-998F-3BFD-95F1-478541221B35.dita"><apiname>__SPIN_LOCK_IRQ(lock)</apiname></xref></p></li>

    46 <li><p><xref href="GUID-F8FA6FEA-56A2-3924-BA59-8DF4B0546AC9.dita"><apiname> __SPIN_UNLOCK_IRQ(lock)</apiname></xref></p></li>

    47 <li><p> <xref href="GUID-E474AC45-13AE-3DE5-857C-7BE76EE084E3.dita"><apiname>__SPIN_FLASH_IRQ(lock)</apiname></xref></p></li>

    48 </ul><note><p> To ensure SMP Safety in Symbian^3, the kernel ensures that

    49 device driver, ISR and DFC are all tied to the same CPU. CPU0 has been stipulated

    50 for this purpose.</p></note></section>

    51 <section id="GUID-8BF9726E-B8E4-4558-98A4-7163CD13774A"><title>Making your

    52 device driver SMP safe</title><p>Once a device driver has been migrated to

    53 be SMP Safe using the advice above, the mmp file of each driver's binaries

    54 must be updated with the keyword <keyword>SMPSAFE</keyword>. As stated earlier,

    55 all kernel side threads and associated interrupts are locked to CPU0 for Symbian^3.

    56 Starting in Symbian^4 any binaries with <keyword>SMPSAFE</keyword> will be

    57 unlocked from CPU0 so they can be executed on any core. </p><p> <keyword>SMPSAFE</keyword> only

    58 has any effect when Compatibility Mode (see general impacts page) is being

    59 used. For interim testing of device driver migration, the CPU affinity API’s

    60 may be used to test driver thread migration. For example, </p><codeblock xml:space="preserve">NKern::ThreadSetCpuAffinity(NKern::CurrentThread(),KCpuAffinityAny);</codeblock></section>

    61 <example><p>In the following example, a spin lock protects memory being written

    62 by <codeph>DfcFun()</codeph> on CPU0 from corruption by <codeph>ISRFun()</codeph> running

    63 on a different core.</p><p>This code runs on CPU0:<codeblock xml:space="preserve">void DfcFun(TAny* aPtr)

    64 	{

    65 	…

    66    irq = __SPIN_LOCK_IRQSAVE(iLock);

    67    iState = EProcessed;

    68    __SPIN_UNLOCK_IRQRESTORE(iLock,irq);

    69 

    70 	...

    71 	}

    72 </codeblock></p><p>This code runs on a different core:<codeblock xml:space="preserve">void ISRFun(TAny* aPtr)

    73 	{

    74    __SPIN_LOCK(iLock);	

    75 	iState = EProcessing;

    76 	__SPIN_UNLOCK(iLock);

    77 	}

    78 </codeblock></p></example>

    79 </conbody><related-links>

    80 <link href="GUID-387E98B0-568D-4DBB-9A9E-616E41E96B58.dita"><linktext>SMP Overview</linktext>

    81 </link>

    82 </related-links></concept>