1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 34 35 36 37 38 39 40 41 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 metaonly struct ModuleView {
108 UInt16 id;
109 UInt16 numProcessors;
110 String nameList[];
111 }
112
113 @Facet
114 metaonly config 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 metaonly config 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 metaonly config 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
296 config UInt16 procIdList[];
297
298
299 struct Module_State {
300 UInt16 id;
301 UInt16 baseIdOfCluster;
302 };
303 }
304