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 the ability to uniquely specify and identify
53 * processors in a multi-processor environment. The MultiProc module
54 * centeralizes processor id management into one module. Since this
55 * configuration 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 *
62 * The setConfig function tells the MultiProc module:
63 * @p(blist) 64 * - The specific processor for which the application is being built
65 * - Which processors out of a set of possible processors on a device are
66 * being used by the multi-processor application
67 * @p 68 *
69 * Using the information supplied using the {@link #setConfig} meta function,
70 * The {@link #numProcessors} module configuration and the processor IDs are
71 * internally set. Please refer to the documentation for {@link #setConfig}
72 * for more details.
73 *
74 * At runtime, the {@link #getId} call returns the MultiProc id
75 * for any processor. At config-time, the {@link #getIdMeta} call returns the
76 * the same value. At both run time and static time, the
77 * {@link #numProcessors} module config is equal to the length of the
78 * procNames array supplied in {@link #setConfig}.
79 *
80 */
81
82 module MultiProc
83 {
84 metaonlystruct ModuleView {
85 UInt16 id; /* Own ID */
86 UInt16 numProcessors; /* # of processors */
87 String nameList[]; /* Proc names ordered by procId */
88 }
89
90 @Facet
91 metaonlyconfig ViewInfo.Instance rovViewInfo =
92 ViewInfo.create({
93 viewMap: [
94 [
95 'Module',
96 {
97 type: ViewInfo.MODULE,
98 viewInitFxn: 'viewInitModule',
99 structName: 'ModuleView'
100 }
101 ],
102 ]
103 });
104
105 /*!
106 * Assert raised when an invalid processor id is used
107 */
108 config Assert.Id A_invalidMultiProcId = {
109 msg: "A_invalidMultiProcId: Invalid MultiProc id"
110 };
111
112 /*!
113 * Assert raised when a NULL processor name is encountered
114 */
115 config Assert.Id A_invalidProcName = {
116 msg: "A_invalidProcName: NULL MultiProc name encountered"
117 };
118
119 /*!
120 * Invalid processor id constant
121 *
122 * This constant denotes that the processor id is not valid.
123 */
124 const UInt16 INVALIDID = 0xFFFF;
125
126 /*! @_nodoc 127 * ======== nameList ========
128 * Unique name for the each processor used in a multi-processor app
129 *
130 * This array should never be set or read directly by the MultiProc user.
131 * The nameList is used to store names configuration supplied via the
132 * {@link #setConfig} static function.
133 *
134 * At runtime, the {@link #getName} function may be used to retrieve
135 * the name of any processor given it's MultiProc id.
136 */
137 config String nameList[];
138
139 /*! @_nodoc 140 * ======== id ========
141 * Unique software id number for the processor
142 *
143 * This value should never be set or read directly by the MultiProc user.
144 * Instead, the {@link #getId}, {@link #getIdMeta}, and
145 * {@link #setLocalId} calls should be used to respectively retrieve any
146 * processors' MultiProc ids or set the local processor's MultiProc id.
147 */
148 config UInt16 id = 0;
149
150 /*!
151 * ======== numProcessors ========
152 * Number of processors in the system
153 *
154 * This configuration should only be read from and should never be set:
155 * numProcessors is internally set by the {@link #setConfig} meta function.
156 * setConfig statically sets the value of this configuration to the length
157 * of the supplied nameList array. After {@link #setConfig} has been
158 * called, it is possible to retrive the maximum # of processors by
159 * reading this module config either at run-time or at config time.
160 */
161 config UInt16 numProcessors = 1;
162
163 /*!
164 * ======== getIdMeta ========
165 * Meta version of {@link #getId}
166 *
167 * Statically returns the internally set ID based on configuration
168 * supplied via {@link #setConfig}.
169 *
170 * @param(name) MultiProc procName
171 */
172 metaonly UInt16 getIdMeta(String name);
173
174 /*!
175 * ======== getDeviceProcNames ========
176 * Returns an array of all possible processor names on the build device
177 *
178 * @(return) Array of valid MultiProc processor names
179 */
180 metaonly Any getDeviceProcNames();
181
182 /*!
183 * ======== setConfig ========
184 * Configure the MultiProc module
185 *
186 * Configuration of the MultiProc module is primarily accomplished using
187 * the setConfig API at config time. The setConfig API allows the
188 * MultiProc module to identify:
189 * @p(blist) 190 * - Which is the local processor
191 * - Which processors are being used
192 * @p 193 * The second of these two pieces of information is supplied via the
194 * nameList argument. The nameList is a non-empty set of distinct
195 * processors valid for the particular device. For a list of valid
196 * processor names for a given device, please refer to the :
197 * {@link ./../ipc/family/doc-files/procNames.html Table of
198 * Valid Names for Each Device}.
199 *
200 * The local processor is identified by using a single name from
201 * nameList. A MultiProc id is internally set to the index of
202 * 'name' in the supplied 'nameList'. I.e. in the example:
203 *
204 * @p(code) 205 * MultiProc.setConfig("DSP", ["HOST", "DSP", "OTHERCORE"]);
206 * @p 207 *
208 * The processors, "HOST", "DSP" and "OTHERCORE" get assigned MultiProc
209 * IDs 0, 1, and 2, respectively. The local processor, "DSP" is assigned
210 * an ID of '1'.
211 *
212 * If the local processor is not known at static time, it is possible to
213 * supply a null name. MultiProc will set the local id to
214 * {@link #INVALIDID} until it is set at runtime using
215 * MultiProc_setLocalId.
216 *
217 * @param(name) MultiProc name for the local processor
218 * @param(nameList) Array of all processors used by the application
219 */
220 metaonly Void setConfig(String name, String nameList[]);
221
222 /*! @_nodoc 223 * ======== getName$view ========
224 * ROV-time version of {@link #getName}
225 */
226 metaonly String getName$view(UInt id);
227
228 /*! @_nodoc 229 * ======== self$view ========
230 * ROV-time version of {@link #self}
231 */
232 metaonly UInt self$view();
233
234 /*! @_nodoc 235 * This is needed to prevent the MultiProc module from being optimized away
236 * during the whole_program[_debug] partial link.
237 */
238 Void dummy();
239
240 internal:
241
242 /* id is in Module_State to support the changing of it via setLocalId */
243 struct Module_State {
244 UInt16 id;
245 };
246 }
247