|
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-860916D1-339F-4D4F-859D-DAE11F7C311E" xml:lang="en"><title>Building for an SMP Platform</title><shortdesc>This document describes the issues raised when building |
|
13 code for an SMP platform.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The only difference between building for an SMP and non-SMP system, |
|
15 is the inclusion of the <codeph>SMPSAFE</codeph> keyword in the mmp |
|
16 file.</p> |
|
17 <p>However, before the <codeph>SMPSAFE</codeph> keyword can be used, |
|
18 the ROM compatibility mode should be understood and enabled. It is |
|
19 described below.</p> |
|
20 <section id="GUID-1D9BD7C9-7CAA-47DC-BD4F-DC00C5F13C50"><title>ROM |
|
21 compatibility mode</title><p>This specifies how the resulting build |
|
22 will execute code that has not been marked as SMP safe, for example, |
|
23 existing applications produced by third party developers. However, |
|
24 ROM compatibility mode does not guarantee that non-SMP code will work. |
|
25 By default, ROM compatibility is turned off. It is expected that code |
|
26 will be tested on a SMP platform to verify that it is SMP safe. Which |
|
27 compatibility mode is to be used will be decided during the ROM integration |
|
28 stage.</p><p>The ROM compatibility mode takes the form of two new <codeph>rombuild</codeph> parameters (only one can be used at any one time).</p><p>There are two parts to using ROM compatibility mode:</p><ul> |
|
29 <li><p>Specifying that it is to be turned on and which type of ROM |
|
30 compatibility is to be used. This is done with a new parameter for |
|
31 the <codeph>rombuild</codeph> tool.</p></li> |
|
32 <li><p>Adding the appropriate macros in the baseport iby and oby files.</p></li> |
|
33 </ul><p>The arguments of <codeph>rombuild</codeph> that relate to |
|
34 ROM compatibility are:</p><table id="GUID-F8F1F2CF-94FB-4264-A9EF-6F29DC188207"> |
|
35 <tgroup cols="2"><colspec colname="col1" colwidth="0.42*"/><colspec colname="col2" colwidth="1.58*"/> |
|
36 <thead> |
|
37 <row> |
|
38 <entry align="center" valign="top"><p>rombuild argument</p></entry> |
|
39 <entry align="center" valign="top"><p>Description</p></entry> |
|
40 </row> |
|
41 </thead> |
|
42 <tbody> |
|
43 <row> |
|
44 <entry align="center"><p>-d SMPCOMPATMODE</p></entry> |
|
45 <entry><p>Enables regular compatibility mode. This means that all |
|
46 the threads in unsafe processes (non-SMP safe) are restricted, so |
|
47 that only the ready thread with the highest priority can run.</p><p>In regular compatibility mode, a thread group is created for each |
|
48 process. This thread group will have the same priority as the highest |
|
49 priority thread that it contains. These thread groups can be assigned |
|
50 to any of the available processors, not just CPU 0.</p></entry> |
|
51 </row> |
|
52 <row> |
|
53 <entry align="center"><p>-d SMPCOMPATCPU0</p></entry> |
|
54 <entry><p>Enables CPU 0 only mode. This means that all threads in |
|
55 unsafe processes (non-SMP safe) can only execute on CPU 0.</p></entry> |
|
56 </row> |
|
57 </tbody> |
|
58 </tgroup> |
|
59 </table><p>In order for the ROM compatibility mode arguments to work, |
|
60 changes have to be made to the iby and oby files of the baseport being |
|
61 used. This takes the form of setting the appropriate flags:</p><table id="GUID-7F082639-8BA4-45F0-BF59-32A2E1B8EF4D"> |
|
62 <tgroup cols="3"><colspec colname="col1" colwidth="0.48*"/><colspec colname="col2" colwidth="1.55*"/><colspec colname="COLSPEC1" colwidth="1.55*"/> |
|
63 <thead> |
|
64 <row> |
|
65 <entry align="center" valign="top"><p>Flag</p></entry> |
|
66 <entry align="center" valign="top"><p>Description</p></entry> |
|
67 <entry align="center" valign="top"><p>Default Value</p></entry> |
|
68 </row> |
|
69 </thead> |
|
70 <tbody> |
|
71 <row> |
|
72 <entry align="center"><p>SMPUNSAFECOMPAT</p></entry> |
|
73 <entry><p>Sets the state of the regular compatibility mode.</p></entry> |
|
74 <entry align="center"><p><codeph>off</codeph></p></entry> |
|
75 </row> |
|
76 <row> |
|
77 <entry align="center"><p>SMPUNSAFECPU0</p></entry> |
|
78 <entry><p>Sets the state of the CPU 0 mode.</p></entry> |
|
79 <entry align="center"><p><codeph>off</codeph></p></entry> |
|
80 </row> |
|
81 </tbody> |
|
82 </tgroup> |
|
83 </table><p>The only valid values for these flags are <codeph>on</codeph> or <codeph>off</codeph>.</p><p>The following line has to be added |
|
84 to the baseport iby and oby files:</p><p><codeblock xml:space="preserve">#include <rom/include/kernel.hby></codeblock></p><p>An example of the use of above flags is:</p><codeblock xml:space="preserve">#ifdef SMP |
|
85 #if defined(SMPCOMPATMODE) && defined(SMPCOMPATCPU0) |
|
86 #error "Can't have SMPCOMPATMODE and SMPCOMPATCPU0 at once!" |
|
87 #endif |
|
88 #ifdef SMPCOMPATMODE |
|
89 SMPUNSAFECOMPAT(on) |
|
90 #endif |
|
91 #ifdef SMPCOMPATCPU0 |
|
92 SMPUNSAFECPU0(on) |
|
93 #endif |
|
94 #endif //SMP |
|
95 </codeblock><p><note>There is no guarantee that the use of compatibility |
|
96 mode will make SMP unsafe code work correctly. The compatibility mode |
|
97 is only a temporary migration strategy.</note></p><p>Now that the |
|
98 build system has been set up to work with non-SMP safe code, the use |
|
99 of the <codeph>SMPSAFE</codeph> can be described.</p></section> |
|
100 <section id="GUID-DF199EB5-BAEF-4035-9F6A-4264DC5F5E3F"><title>The |
|
101 SMPSAFE keyword</title><p>The <codeph>SMPSAFE</codeph> keyword is |
|
102 used to tell the system that the project can work correctly in an |
|
103 SMP environment.</p><p>It is indicated by placing the word <codeph>SMPSAFE</codeph> on a single line of the project's mmp file.</p><p>An example of the use of the <codeph>SMPSAFE</codeph> keyword is |
|
104 given below:</p><codeblock xml:space="preserve">capability all |
|
105 |
|
106 VENDORID 0x70000001 |
|
107 |
|
108 SMPSAFE |
|
109 |
|
110 </codeblock><p>The effect of this keyword is as follows:</p><table id="GUID-F6787493-246D-40E1-A74F-1C88A808DD03"> |
|
111 <tgroup cols="3"><colspec colname="col1" colwidth="0.92*"/><colspec colname="col2" colwidth="0.92*"/><colspec colname="col3" colwidth="1.17*"/> |
|
112 <thead> |
|
113 <row> |
|
114 <entry align="center" valign="top"><p>Is the SMPSAFE keyword present?</p></entry> |
|
115 <entry align="center" valign="top"><p>State of ROM Compatibility Mode</p></entry> |
|
116 <entry align="center" valign="top"><p>Resulting Behavior</p></entry> |
|
117 </row> |
|
118 </thead> |
|
119 <tbody> |
|
120 <row> |
|
121 <entry align="center"><p>Yes</p></entry> |
|
122 <entry align="center"><p>N/A</p></entry> |
|
123 <entry><p>The code is assumed to be SMP safe and will be executed |
|
124 accordingly.</p></entry> |
|
125 </row> |
|
126 <row> |
|
127 <entry align="center"><p>No</p></entry> |
|
128 <entry align="center"><p>Disabled</p></entry> |
|
129 <entry><p>The code will be executed, but SMP related problems can |
|
130 occur.</p></entry> |
|
131 </row> |
|
132 <row> |
|
133 <entry align="center"><p>No</p></entry> |
|
134 <entry align="center"><p>Enabled</p></entry> |
|
135 <entry><p>The code will be executed. </p><p>How it is executed, depends |
|
136 on which ROM compatibility mode has been enabled.</p></entry> |
|
137 </row> |
|
138 </tbody> |
|
139 </tgroup> |
|
140 </table><p>The build process for an SMP platform will be described.</p></section> |
|
141 <section id="GUID-318B743D-3D7C-4773-8A15-E34E800C3911"><title>The |
|
142 build process for an SMP platform</title><p>The build process for |
|
143 an SMP platform is exactly the same as the build process for a non-SMP |
|
144 platform.</p><p><note>The target must be ARMV5SMP. This can be insured |
|
145 if the bld.inf files specify BASE_DEFAULT in the PRJ_PLATFORMS line.</note></p><p>For the description of this process, follow the <xref href="GUID-2EDB8C13-959F-590B-9C1D-67E09B7C8874.dita">Build Tool Guide</xref> link below.</p> </section> |
|
146 </conbody><related-links> |
|
147 <link href="GUID-2EDB8C13-959F-590B-9C1D-67E09B7C8874.dita"><linktext>Build |
|
148 Tools Guide</linktext></link> |
|
149 <link href="GUID-E55F9286-F586-4665-93D8-86F1E7BE2C7C.dita"><linktext>SMP |
|
150 Developer Tips</linktext></link> |
|
151 </related-links></concept> |