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