1 /* --COPYRIGHT--,BSD
2 * Copyright (c) $(CPYYEAR), Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 * --/COPYRIGHT--*/
32 /*
33 * ======== MultiProc.xdc ========
34 *
35 *! Revision History
36 *! ================
37 *! 07-May-2010 skp Removed MultiProc_getSlot()
38 *! 23-Oct-2009 skp Many cdoc changes
39 *! 10-Oct-2009 skp Changes to support new Notify
40 *! 16-Apr-2009 toddm Code review comments
41 *! 16-May-2008 jv Made modifications per review.
42 */
43
44 import xdc.rov.ViewInfo;
45
46 import xdc.runtime.Assert;
47
48 /*!
49 * ======== MultiProc ========
50 * Processor Id Module Manager
51 *
52 * Many IPC modules require identifying processors in a
53 * multi-processor environment. The MultiProc module centralizes
54 * processor id management into one module. Since this configuration
55 * is almost always universally required, most IPC applications
56 * require supplying configuration of this module.
57 *
58 * Each processor in the MultiProc module may be uniquely identified by
59 * either a name string or an integer ranging from 0 to MAXPROCESSORS - 1.
60 * Configuration is supplied using the {@link #setConfig} meta function,
61 * the {@link #numProcessors} and {@link #baseIdOfCluster}.
62 *
63 * The setConfig function tells the MultiProc module:
64 * @p(blist) 65 * - The specific processor for which the application is being built
66 * - The number of processors in the cluster
67 * @p 68 *
69 * A cluster is a set of processors within a system which share some share
70 * shared memory and supports notifications. Typically most systems contain
71 * one cluster. When there are multiple clusters in the system, the
72 * {@link #numProcessors} and {@link #baseIdOfCluster} configuration
73 * paramaters are required to be set before calling {@link #setConfig}
74 *
75 * For examle in a system with 2 C6678 devices [each C6678 contains 8
76 * homogeneuous cores]. For first C6678 device:
77 * @p(code) 78 * var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
79 * MultiProc.baseIdOfCluster = 0;
80 * MultiProc.numProcessors = 16;
81 * MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2", "CORE3",
82 * "CORE4", "CORE5", "CORE6", "CORE7"]);
83 * @p 84 *
85 * For second C6678 device:
86 * @p(code) 87 * var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc');
88 * MultiProc.baseIdOfCluster = 8;
89 * MultiProc.numProcessors = 16;
90 * MultiProc.setConfig(null, ["CORE0", "CORE1", "CORE2", "CORE3",
91 * "CORE4", "CORE5", "CORE6", "CORE7"]);
92 * @p 93 *
94 * Using the information supplied using the {@link #setConfig} meta function
95 * and the {@link #baseIdOfCluster} module configuration, the processor IDs
96 * are internally set. Please refer to the documentation for
97 * {@link #setConfig} and {@link #baseIdOfCluster} for more details.
98 *
99 * At runtime, the {@link #getId} call returns the MultiProc id of those
100 * processors within its cluster. At config-time, the {@link #getIdMeta}
101 * call returns the the same value.
102 *
103 */
104
105 module MultiProc
106 {
107 metaonlystruct ModuleView {
108 UInt16 id; /* Own ID */
109 UInt16 numProcessors; /* # of processors */
110 String nameList[]; /* Proc names ordered by procId */
111 }
112
113 @Facet
114 metaonlyconfig ViewInfo.Instance rovViewInfo =
115 ViewInfo.create({
116 viewMap: [
117 [
118 'Module',
119 {
120 type: ViewInfo.MODULE,
121 viewInitFxn: 'viewInitModule',
122 structName: 'ModuleView'
123 }
124 ],
125 ]
126 });
127
128 /*!
129 * Assert raised when an invalid processor id is used
130 */
131 config Assert.Id A_invalidMultiProcId = {
132 msg: "A_invalidMultiProcId: Invalid MultiProc id"
133 };
134
135 /*!
136 * Assert raised when a NULL processor name is encountered
137 */
138 config Assert.Id A_invalidProcName = {
139 msg: "A_invalidProcName: NULL MultiProc name encountered"
140 };
141
142 /*!
143 * Invalid processor id constant
144 *
145 * This constant denotes that the processor id is not valid.
146 */
147 const UInt16 INVALIDID = 0xFFFF;
148
149 /*! @_nodoc 150 * ======== nameList ========
151 * Unique name for the each processor used in a multi-processor app
152 *
153 * This array should never be set or read directly by the MultiProc user.
154 * The nameList is used to store names configuration supplied via the
155 * {@link #setConfig} static function.
156 *
157 * At runtime, the {@link #getName} function may be used to retrieve
158 * the name of any processor given it's MultiProc id.
159 */
160 config String nameList[];
161
162 /*! @_nodoc 163 * ======== id ========
164 * Unique software id number for the processor
165 *
166 * This value should never be set or read directly by the MultiProc user.
167 * Instead, the {@link #getId}, {@link #getIdMeta}, and
168 * {@link #setLocalId} calls should be used to respectively retrieve any
169 * processors' MultiProc ids or set the local processor's MultiProc id.
170 */
171 metaonlyconfig UInt16 id = 0;
172
173 /*! @_nodoc 174 * ======== numProcsInCluster ========
175 * Number of processors in a cluster
176 *
177 * This parameter should never be set: numProcsInCluster is
178 * internally set by the {@link #setConfig} meta function.
179 * setConfig statically sets the value of this configuration to the
180 * length of the supplied nameList array.
181 */
182 config UInt16 numProcsInCluster = 1;
183
184 /*!
185 * ======== baseIdOfCluster ========
186 * The base id of the cluster.
187 *
188 * Using this base id, the id of each processor in the cluster
189 * is set based up its position in {@link #setConfig}. When more
190 * more than one cluster exists in the system, this parameter must
191 * be set before calling {@link #setConfig}.
192 */
193 metaonlyconfig UInt16 baseIdOfCluster = 0;
194
195 /*!
196 * ======== numProcessors ========
197 * Number of processors in the system
198 *
199 * This configuration should only be set when there is more than one
200 * cluster in the system. It must be set before calling
201 * {@link #setConfig}. If the system contains only one cluster,
202 * it is internally set by the {@link #setConfig} meta function to the
203 * length of the supplied nameList array.
204 * After {@link #setConfig} has been called, it is possible to
205 * retrive the maximum # of processors by reading this module config
206 * either at run-time or at config time.
207 */
208 config UInt16 numProcessors = 1;
209
210 /*! @_nodoc 211 * ======== getClusterId ========
212 */
213 UInt16 getClusterId(UInt16 procId);
214
215 /*!
216 * ======== getIdMeta ========
217 * Meta version of {@link #getId}
218 *
219 * Statically returns the internally set ID based on configuration
220 * supplied via {@link #setConfig}.
221 *
222 * @param(name) MultiProc procName
223 */
224 metaonly UInt16 getIdMeta(String name);
225
226 /*!
227 * ======== getDeviceProcNames ========
228 * Returns an array of all possible processor names on the build device
229 *
230 * @(return) Array of valid MultiProc processor names
231 */
232 metaonly Any getDeviceProcNames();
233
234 /*!
235 * ======== setConfig ========
236 * Configure the MultiProc module
237 *
238 * Configuration of the MultiProc module is primarily accomplished using
239 * the setConfig API at config time. The setConfig API allows the
240 * MultiProc module to identify:
241 * @p(blist) 242 * - Which is the local processor
243 * - Which processors are being used
244 * - Which processors can synchronize
245 * @p 246 * The second of these two pieces of information is supplied via the
247 * nameList argument. The nameList is a non-empty set of distinct
248 * processors valid for the particular device. For a list of valid
249 * processor names for a given device, please refer to the :
250 * {@link ./../ipc/family/doc-files/procNames.html Table of
251 * Valid Names for Each Device}.
252 *
253 * The local processor is identified by using a single name from
254 * nameList. A MultiProc id is internally set to the index of
255 * 'name' in the supplied 'nameList'. I.e. in the example:
256 *
257 * @p(code) 258 * MultiProc.setConfig("DSP", ["HOST", "DSP", "OTHERCORE"]);
259 * @p 260 *
261 * The processors, "HOST", "DSP" and "OTHERCORE" get assigned MultiProc
262 * IDs 0, 1, and 2, respectively. The local processor, "DSP" is assigned
263 * an ID of '1'.
264 *
265 * If the local processor is not known at static time, it is possible to
266 * supply a null name. MultiProc will set the local id to
267 * {@link #INVALIDID} until it is set at runtime using
268 * MultiProc_setLocalId.
269 *
270 * @param(name) MultiProc name for the local processor
271 * @param(nameList) Array of all processors used by the application
272 */
273 metaonly Void setConfig(String name, String nameList[]);
274
275 /*! @_nodoc 276 * ======== getName$view ========
277 * ROV-time version of {@link #getName}
278 */
279 metaonly String getName$view(UInt id);
280
281 /*! @_nodoc 282 * ======== self$view ========
283 * ROV-time version of {@link #self}
284 */
285 metaonly UInt self$view();
286
287 /*! @_nodoc 288 * This is needed to prevent the MultiProc module from being optimized away
289 * during the whole_program[_debug] partial link.
290 */
291 Void dummy();
292
293 internal:
294
295 /* list of processor id's in cluster */
296 config UInt16 procIdList[];
297
298 /* id is in Module_State to support the changing of it via setLocalId */
299 struct Module_State {
300 UInt16 id;
301 UInt16 baseIdOfCluster;
302 };
303 }
304