--- a/Symbian3/PDK/Source/GUID-821C254A-40C6-45F9-B2F9-2CF28CAEB8CC.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-821C254A-40C6-45F9-B2F9-2CF28CAEB8CC.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,82 +1,82 @@
-<?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>
+<?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>
\ No newline at end of file