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 import xdc.runtime.Error;
27 import xdc.runtime.Assert;
28 import xdc.runtime.IHeap;
29 import ti.sysbios.gates.GateSwi;
30 import xdc.rov.ViewInfo;
31
32 /*!
33 * ======== NameServer ========
34 * Manages and serves names to remote/local processor
35 *
36 * @p(html)
37 * This module has a common header that can be found in the {@link ti.ipc}
38 * package. Application code should include the common header file (not the
39 * RTSC-generated one):
40 *
41 * <PRE>#include <ti/ipc/NameServer.h></PRE>
42 *
43 * The RTSC module must be used in the application's RTSC configuration file
44 * (.cfg) if runtime APIs will be used in the application:
45 *
46 * <PRE>NameServer = xdc.useModule('ti.sdo.ipc.NameServer');</PRE>
47 *
48 * Documentation for all runtime APIs, instance configuration parameters,
49 * error codes macros and type definitions available to the application
50 * integrator can be found in the
51 * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
52 * for the IPC product. However, the documentation presented on this page
53 * should be referred to for information specific to the RTSC module, such as
54 * module configuration, Errors, and Asserts.
55 * @p
56 *
57 */
58
59 @ModuleStartup
60 @InstanceInitError
61 @InstanceFinalize
62
63 module NameServer
64 {
65 /*!
66 * ======== BasicView ========
67 * @_nodoc
68 */
69 metaonly struct BasicView {
70 String name;
71 Bool checkExisting;
72 UInt maxNameLen;
73 UInt maxValueLen;
74 UInt numStatic;
75 String numDynamic;
76 }
77
78 /*!
79 * ======== NamesListView ========
80 * @_nodoc
81 */
82 metaonly struct NamesListView {
83 String name;
84 String value;
85 UInt len;
86 Ptr nsKey;
87 }
88
89 /*!
90 * ======== rovViewInfo ========
91 * @_nodoc
92 */
93 @Facet
94 metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
95 xdc.rov.ViewInfo.create({
96 viewMap: [
97 ['Basic',
98 {
99 type: xdc.rov.ViewInfo.INSTANCE,
100 viewInitFxn: 'viewInitBasic',
101 structName: 'BasicView'
102 }
103 ],
104 ['NamesValues',
105 {
106 type: xdc.rov.ViewInfo.INSTANCE_DATA,
107 viewInitFxn: 'viewInitData',
108 structName: 'NamesListView'
109 }
110 ]
111 ]
112 });
113
114 /*!
115 * Assert raised when the name or value is too long
116 */
117 config Assert.Id A_invalidLen = {
118 msg: "A_invalidLen: Invalid length"
119 };
120
121 /*!
122 * Error raised if all the entries in the instance Name/Value table
123 * are taken
124 */
125 config Error.Id E_maxReached = {
126 msg: "E_maxReached: All entries in use. NameServer.maxRuntimeEntries is %d"
127 };
128
129 /*!
130 * Error raised when the name already exists in the instance
131 * Name/Value table
132 */
133 config Error.Id E_entryExists = {
134 msg: "E_entryExists: %s name already in table "
135 };
136
137 /*!
138 * Allow dynamic growth of the NameServer instance table
139 *
140 * This value can be used to set the {@link #maxRuntimeEntries}.
141 * This flag tells NameServer to allow dynamic growth
142 * of the table.
143 */
144 const UInt ALLOWGROWTH = (~0);
145
146 /*!
147 * Structure of entry in Name/Value table
148 *
149 * This structure is returned from the {@link #getMeta}
150 * API.
151 *
152 * @field(name) Name portion of the name/value pair.
153 * @field(len) Length of the value field.
154 * @field(value) Value portion of the name/value entry.
155 */
156 metaonly struct Entry {
157 String name;
158 UInt len;
159 UArg value;
160 };
161
162 /*!
163 * ======== isRegistered ========
164 * Determines if a remote driver is registered for the specified id.
165 *
166 * @param(procId) The remote processor id.
167 */
168 Bool isRegistered(UInt16 procId);
169
170 /*!
171 * ======== registerRemoteDriver ========
172 * Register the NameServer remote handle for the specified processor id.
173 *
174 * This function is used by NameServer remote driver to register
175 * themselves with NameServer. Only one remote driver can be registered
176 * with a remote processor. The API returns {@link #Status_FAIL} if there
177 * is already a registered remote driver for the processor id.
178 *
179 * @param(handle) The handle for a NameServer remote driver instance.
180 * @param(procId) The remote processor id.
181 *
182 * @b(returns) Returns {@link #Status_SUCCESS} if successful or
183 * {@link #Status_FAIL} if the processor id has already
184 * been set.
185 */
186 Int registerRemoteDriver(INameServerRemote.Handle handle, UInt16 procId);
187
188 /*!
189 * ======== unregisterRemoteDriver ========
190 * Unregister the NameServer remote handle for the specified processor id.
191 *
192 * This function is used by NameServer Remote implementations to unregister
193 * themselves with NameServer.
194 *
195 * @param(procId) The remote processor id to unregister.
196 */
197 Void unregisterRemoteDriver(UInt16 procId);
198
199 /*!
200 * ======== modAddMeta ========
201 * Add a name/value pair into the specified instance's table during
202 * configuration
203 *
204 * This function adds any length value into the local table. The function
205 * makes sure the name does not already exist in the local table.
206 *
207 * This function should be used by modules when adding into a NameServer
208 * instance. The application configuration file, should
209 * use {@link #addMeta}.
210 *
211 * The function does not query remote processors to make sure the
212 * name is unique.
213 *
214 * @param(instName) NameServer instance name
215 * @param(name) Name portion of the name/value pair
216 * @param(value) Value portion of the name/value pair
217 * @param(len) Length of the value buffer
218 */
219 metaonly Void modAddMeta(String instName, String name, Any value, UInt len);
220
221 /*!
222 * ======== getName$view ========
223 * @_nodoc
224 * Used at ROV time to display reverse-lookup name from 32-bit value and
225 * tableName
226 */
227 metaonly String getName$view(String tableName, UInt32 value);
228
229 /*!
230 * ======== getNameByKey$view ========
231 * @_nodoc
232 * ROV function for retrieving an entry by its address. Throws an exception
233 * if the name was not found
234 */
235 metaonly String getNameByKey$view(Ptr addr);
236
237
238 instance:
239
240 /*!
241 * Maximum number of name/value pairs that can be dynamically created.
242 *
243 * This parameter allows NameServer to pre-allocate memory.
244 * When NameServer_add or NameServer_addUInt32 is called, no memory
245 * allocation occurs.
246 *
247 * If the number of pairs is not known at configuration time, set this
248 * value to {@link #ALLOWGROWTH}. This instructs NameServer to grow the
249 * table as needed. NameServer will allocate memory from the
250 * {@link #tableHeap} when a name/value pair is added.
251 *
252 * The default is {@link #ALLOWGROWTH}.
253 */
254 config UInt maxRuntimeEntries = ALLOWGROWTH;
255
256 /*!
257 * Name/value table is allocated from this heap.
258 *
259 * The instance table and related buffers are allocated out of this heap
260 * during the dynamic create. This heap is also used to allocate new
261 * name/value pairs when {@link #ALLOWGROWTH} for
262 * {@link #maxRuntimeEntries}
263 *
264 * The default is to use the same heap that instances are allocated
265 * from which can be configured via the
266 * NameServer.common$.instanceHeap configuration parameter.
267 */
268 config IHeap.Handle tableHeap = null;
269
270 /*!
271 * Name/value table is placed into this section on static creates.
272 *
273 * The instance table and related buffers are placed into this section
274 * during the static create.
275 *
276 * The default is no explicit section placement.
277 */
278 metaonly config String tableSection = null;
279
280 /*!
281 * Check if a name already exists in the name/value table.
282 *
283 * When a name/value pair is added during runtime, if this boolean is true,
284 * the table is searched to see if the name already exists. If it does,
285 * the name is not added and the {@link #E_entryExists} error is raised.
286 *
287 * If this flag is false, the table will not be checked to see if the name
288 * already exists. It will simply be added. This mode has better
289 * performance at the expense of potentially having non-unique names in the
290 * table.
291 *
292 * This flag is used for runtime adds only. Adding non-unique names during
293 * configuration results in a build error.
294 */
295 config Bool checkExisting = true;
296
297 /*!
298 * Length, in MAUs, of the value field in the table.
299 *
300 * Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32).
301 */
302 config UInt maxValueLen = 0;
303
304 /*!
305 * Length, in MAUs, of the name field in the table.
306 *
307 * The maximum length of the name portion of the name/value
308 * pair. The length includes the null terminator ('\0').
309 */
310 config UInt maxNameLen = 16;
311
312 /*!
313 * ======== metaTable ========
314 * @_nodoc
315 * Table to hold the statically added name/value pairs until
316 * they ready to be added to the object.
317 */
318 metaonly config Entry metaTable[];
319
320 /*!
321 * ======== create ========
322 * @_nodoc (Refer to doxygen for ti/ipc/NameServer.h)
323 * Create a NameServer instance
324 *
325 * This function creates a NameServer instance. The name is
326 * used for remote processor queries and diagnostic tools. For
327 * single processor system (e.g. no remote queries), the name
328 * can be NULL.
329 *
330 * @param(name) Name of the instance
331 */
332 create(String name);
333
334 /*!
335 * ======== addUInt32Meta ========
336 * Add a name/value pair into the instance's table during configuration
337 *
338 * This function adds a UInt32 value into the local table. The function
339 * makes sure the name does not already exist in the local table.
340 *
341 * The function does not query remote processors to make sure the
342 * name is unique.
343 *
344 * @param(name) Name portion of the name/value pair
345 * @param(value) Value portion of the name/value pair
346 */
347 metaonly Void addUInt32Meta(String name, any value);
348
349 /*!
350 * ======== addMeta ========
351 * Add a name/value pair into the instance's table during configuration
352 *
353 * This function adds any length value into the local table. The function
354 * makes sure the name does not already exist in the local table.
355 *
356 * This function should be used by within the application configuration
357 * file. XDC modules should use {@link #modAddMeta}.
358 *
359 * The function does not query remote processors to make sure the
360 * name is unique.
361 *
362 * @param(name) Name portion of the name/value pair
363 * @param(value) Value portion of the name/value pair
364 * @param(len) Length of the value buffer
365 */
366 metaonly Void addMeta(String name, Any value, UInt len);
367
368 /*!
369 * ======== getMeta ========
370 * Retrieves the name/value entry
371 *
372 * If the name is found, the entry is returned. The caller can parse the
373 * entry as needed. If the name is not found, null is returned.
374 *
375 * The search only occurs on the local table.
376 *
377 * @param(name) Name in question
378 *
379 * @b(returns) Name/value entry
380 */
381 metaonly Entry getMeta(String name);
382
383 /*!
384 * ======== getKey ========
385 * @_nodoc
386 * Returns a pointer to the TableEntry containing the argument 'val'.
387 * This should only be used internally by Ipc modules during their
388 * initialization process.
389 *
390 * This function can only be used when maxValueLen = sizeof(UInt32)
391 */
392 Ptr getKey(UInt32 val);
393
394 internal:
395
396
397 config Bool singleProcessor = true;
398
399 metaonly typedef Entry EntryMap[];
400
401 /*! Structure of entry in Name/Value table */
402 struct TableEntry {
403 List.Elem elem;
404 String name;
405 UInt len;
406 UArg value;
407 };
408
409 /*!
410 * ======== metaModTable ========
411 * Table to hold the static added name/value pairs until
412 * they ready to be added to the object.
413 */
414 metaonly config EntryMap metaModTable[string];
415
416 417 418 419
420 Int postInit(Object *obj);
421
422 423 424 425 426 427
428 TableEntry *findLocal(Object *obj, String name);
429
430 431 432 433
434 Void removeLocal(Object *obj, TableEntry *entry);
435
436 437 438 439
440 Void editLocal(Object *obj, TableEntry *entry, Ptr newValue);
441
442
443 struct Instance_State {
444 String name;
445 List.Object freeList;
446 List.Object nameList;
447 UInt maxNameLen;
448 UInt maxValueLen;
449 UInt numStatic;
450 UInt numDynamic;
451 TableEntry table[];
452 Char names[];
453 UInt8 values[];
454 IHeap.Handle tableHeap;
455 Bool checkExisting;
456 };
457
458 struct Module_State {
459 INameServerRemote.Handle nsRemoteHandle[];
460 GateSwi.Handle gate;
461 };
462 }