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