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 * @file NameServer.h
34 *
35 * @brief NameServer Manager
36 *
37 * The NameServer module manages local name/value pairs that
38 * enables an application and other modules to store and
39 * retrieve values based on a name. The module supports different
40 * lengths of values. The #NameServer_add and #NameServer_get
41 * functions are for variable length values. The #NameServer_addUInt32 and
42 * #NameServer_getUInt32 functions are optimized for UInt32 variables
43 * and constants.
44 *
45 * The NameServer module maintains thread-safety for the APIs. However,
46 * the NameServer APIs cannot be called from an interrupt (i.e. Hwi) context.
47 * However, it is safe to use the APIs in Swi's and Tasks.
48 *
49 * Each NameServer instance manages a different name/value table.
50 * This allows each table to be customized to meet the requirements
51 * of user:
52 * @li <b>Size differences:</b> one table could allow long values
53 * (e.g. > 32 bits) while another table could be used to store integers.
54 * This customization enables better memory usage.
55 * @li <b>Performance:</b> improves search time when retrieving
56 * a name/value pair.
57 * @li <b>Relax name uniqueness:</b> names in a specific table must
58 * be unique, but the same name can be used in different tables.
59 *
60 * When adding a name/value pair, the name and value are copied into
61 * internal buffers in NameServer. To minimize runtime memory allocation
62 * these buffers can be allocated at creation time.
63 *
64 * NameServer maintains the name/values table in local memory (e.g.
65 * not shared memory). However the NameServer module can be
66 * used in a multiprocessor system.
67 *
68 * The NameServer module uses the MultiProc module for
69 * identifying the different processors. Which remote processors and
70 * the order they are queried is determined by the procId array in the
71 * #NameServer_get function.
72 *
73 * Currently there is no endian or wordsize conversion performed by the
74 * NameServer module. Also there is no asynchronous support at this time.
75 *
76 * The NameServer header should be included in an application as follows:
77 * @code
78 * #include <ti/ipc/NameServer.h>
79 * @endcode
80 */
82 #ifndef ti_ipc_NameServer__include
83 #define ti_ipc_NameServer__include
85 #if defined (__cplusplus)
86 extern "C" {
87 #endif
89 /* =============================================================================
90 * All success and failure codes for the module
91 * =============================================================================
92 */
94 /*!
95 * @def NameServer_S_BUSY
96 * @brief The resource is still in use
97 */
98 #define NameServer_S_BUSY 2
100 /*!
101 * @def NameServer_S_ALREADYSETUP
102 * @brief The module has been already setup
103 */
104 #define NameServer_S_ALREADYSETUP 1
106 /*!
107 * @def NameServer_S_SUCCESS
108 * @brief Operation is successful.
109 */
110 #define NameServer_S_SUCCESS 0
112 /*!
113 * @def NameServer_E_FAIL
114 * @brief Generic failure.
115 */
116 #define NameServer_E_FAIL -1
118 /*!
119 * @def NameServer_E_INVALIDARG
120 * @brief Argument passed to function is invalid.
121 */
122 #define NameServer_E_INVALIDARG -2
124 /*!
125 * @def NameServer_E_MEMORY
126 * @brief Operation resulted in memory failure.
127 */
128 #define NameServer_E_MEMORY -3
130 /*!
131 * @def NameServer_E_ALREADYEXISTS
132 * @brief The specified entity already exists.
133 */
134 #define NameServer_E_ALREADYEXISTS -4
136 /*!
137 * @def NameServer_E_NOTFOUND
138 * @brief Unable to find the specified entity.
139 */
140 #define NameServer_E_NOTFOUND -5
142 /*!
143 * @def NameServer_E_TIMEOUT
144 * @brief Operation timed out.
145 */
146 #define NameServer_E_TIMEOUT -6
148 /*!
149 * @def NameServer_E_INVALIDSTATE
150 * @brief Module is not initialized.
151 */
152 #define NameServer_E_INVALIDSTATE -7
154 /*!
155 * @def NameServer_E_OSFAILURE
156 * @brief A failure occurred in an OS-specific call
157 */
158 #define NameServer_E_OSFAILURE -8
160 /*!
161 * @def NameServer_E_RESOURCE
162 * @brief Specified resource is not available
163 */
164 #define NameServer_E_RESOURCE -9
166 /*!
167 * @def NameServer_E_RESTART
168 * @brief Operation was interrupted. Please restart the operation
169 */
170 #define NameServer_E_RESTART -10
172 /* =============================================================================
173 * Macros
174 * =============================================================================
175 */
177 /*!
178 * @def NameServer_ALLOWGROWTH
179 * @brief Allow dynamic growth of the NameServer instance table
180 */
181 #define NameServer_ALLOWGROWTH (~0)
183 /*!
184 * @def NameServer_Params_MAXNAMELEN
185 * @brief The default maximum length of the name for the name/value pair
186 */
187 #define NameServer_Params_MAXNAMELEN 16
189 /* =============================================================================
190 * Structures & Enums
191 * =============================================================================
192 */
194 /*!
195 * @brief NameServer handle type
196 */
197 typedef struct NameServer_Object *NameServer_Handle;
199 /*!
200 * @brief NameServer_Handle type
201 */
202 typedef struct NameServer_Params {
203 UInt maxRuntimeEntries;
204 /*!< Maximum number of name/value pairs that can be dynamically created.
205 *
206 * This parameter allows NameServer to pre-allocate memory.
207 * When NameServer_add() or NameServer_addUInt32() is
208 * called, no memory allocation occurs.
209 *
210 * If the number of pairs is not known at configuration time, set this
211 * value to #NameServer_ALLOWGROWTH. This instructs NameServer
212 * to grow the table as needed. NameServer will allocate memory from the
213 * #NameServer_Params#tableHeap when a name/value pair is added.
214 *
215 * The default is #NameServer_ALLOWGROWTH.
216 */
218 Ptr tableHeap;
219 /*!< Name/value table is allocated from this heap.
220 *
221 * The instance table and related buffers are allocated out of this heap
222 * during the dynamic create. This heap is also used to allocate new
223 * name/value pairs when #NameServer_ALLOWGROWTH for
224 * #NameServer_Params#maxRuntimeEntries
225 *
226 * The default is to use the same heap that instances are allocated
227 * from which can be configured via the
228 * NameServer.common$.instanceHeap configuration parameter.
229 */
231 Bool checkExisting;
232 /*!< Check if a name already exists in the name/value table.
233 *
234 * When a name/value pair is added during runtime, if this boolean is
235 * true, the table is searched to see if the name already exists. If
236 * it does, the name is not added and the
237 * #NameServer_E_ALREADYEXISTS error is returned.
238 *
239 * If this flag is false, the table will not be checked to see if the
240 * name already exists. It will simply be added. This mode has better
241 * performance at the expense of potentially having non-unique names
242 * in the table.
243 *
244 * This flag is used for runtime adds only. Adding non-unique names during
245 * configuration results in a build error.
246 */
248 UInt maxValueLen;
249 /*!< Length, in MAUs, of the value field in the table.
250 *
251 * Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32)
252 */
254 UInt maxNameLen;
255 /*!< Length, in MAUs, of the name field in the table.
256 *
257 * The maximum length of the name portion of the name/value
258 * pair. The length includes the null terminator ('\\0').
259 */
261 } NameServer_Params;
264 /* =============================================================================
265 * NameServer Module-wide Functions
266 * =============================================================================
267 */
269 /*!
270 * @brief Initializes parameter structure
271 *
272 * @param params Instance param structure
273 *
274 * @sa NameServer_create
275 */
276 Void NameServer_Params_init(NameServer_Params *params);
278 /*!
279 * @brief Creates a NameServer instance
280 *
281 * @param name Instance name
282 * @param params Instance param structure
283 *
284 * @return NameServer handle
285 *
286 * @sa NameServer_delete
287 */
288 NameServer_Handle NameServer_create(String name,
289 const NameServer_Params *params);
291 /*!
292 * @brief Deletes a NameServer instance
293 *
294 * If the instance is not empty, the contents is freed back to the
295 * heap it was allocated from.
296 *
297 * @param handlePtr Pointer to a NameServer handle
298 *
299 * @return Status
300 * - #NameServer_S_SUCCESS: Instance successfully deleted
301 * - #NameServer_E_FAIL: Instance delete failed
302 *
303 * @sa NameServer_create
304 */
305 Int NameServer_delete(NameServer_Handle *handlePtr);
307 /*!
308 * @brief Gets the NameServer handle given the name
309 *
310 * Each NameServer instance has a name. The name and this function can be
311 * used by the remote driver module to aid in queries to remote
312 * processors. This function allows the caller to get the local handle
313 * based on the instance name.
314 *
315 * For example, when a remote driver sends a request to the remote
316 * processor, it probably contains the name of the instance to query.
317 * The receiving remote driver uses that name to obtain the handle for
318 * the local NameServer instance in question. Then that instance
319 * can be queried for the name/value pair.
320 *
321 * This function does not query remote processors.
322 *
323 * @param name Name of instance
324 *
325 * @return NameServer handle
326 */
327 NameServer_Handle NameServer_getHandle(String name);
329 /* =============================================================================
330 * NameServer Per-instance Functions
331 * =============================================================================
332 */
334 /*!
335 * @brief Adds a variable length value into the local NameServer table
336 *
337 * This function adds a variable length value into the local table.
338 * If the #NameServer_Params#checkExisting flag was true on
339 * creation, this function searches the table to make sure the name
340 * does not already exist. If it does, the name/value pair is not
341 * added and the #NameServer_E_ALREADYEXISTS error is returned.
342 *
343 * There is memory allocation during this function if
344 * #NameServer_Params#maxRuntimeEntries is set to
345 * #NameServer_ALLOWGROWTH.
346 *
347 * This function copies the name and buffer into the name/value table,
348 * so they do not need to be persistent after the call.
349 *
350 * The function does not query remote processors to make sure the
351 * name is unique.
352 *
353 * @param handle Instance handle
354 * @param name Name for the name/value pair
355 * @param buf Pointer to value for the name/value pair
356 * @param len length of the value
357 *
358 * @return Unique entry identifier
359 *
360 * @sa NameServer_addUInt32,
361 * NameServer_get,
362 */
363 Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
365 /*!
366 * @brief Adds a 32-bit value into the local NameServer table
367 *
368 * This function adds a 32-bit value into the local table. This
369 * function is simply a specialized NameServer_add() function
370 * that allows a convenient way to add UInt32 bit values without needing
371 * to specify the address of a UInt32 local variable.
372 *
373 * If the #NameServer_Params#checkExisting flag was true on
374 * creation, this function searches the table to make sure the name does
375 * not already exist. If it does, the name/value pair is not added and the
376 * #NameServer_E_ALREADYEXISTS error is returned.
377 *
378 * This function copies the name into the name/value table.
379 *
380 * There is memory allocation during this function if
381 * #NameServer_Params#maxRuntimeEntries is set to
382 * #NameServer_ALLOWGROWTH.
383 *
384 * The function does not query remote processors to make sure the
385 * name is unique.
386 *
387 * @param handle Instance handle
388 * @param name Name for the name/value pair
389 * @param value Value for the name/value pair
390 *
391 * @return Unique entry identifier
392 *
393 * @sa NameServer_add,
394 * NameServer_getUInt32
395 */
396 Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
398 /*!
399 * @brief Gets the variable value length by name
400 *
401 * If the name is found, the value is copied into the value
402 * argument, the number of MAUs copied is returned in len, and
403 * a success status is returned.
404 *
405 * If the name is not found, zero is returned in len, the contents
406 * of value are not modified. Not finding a name is not considered
407 * an error.
408 *
409 * For NameServer to work across processors, each processor must
410 * must be assigned a unique id. Because remote NameServer requests
411 * usually employ the use of notifications, it is good practice to
412 * sleep/wait between successive NameServer_get[UInt32] operations if polling
413 * on the success of this call. This helps ensure that remote cores
414 * are not inundated by a flood of incoming notifications and helps
415 * reduce the possiblity of deadlocks.
416 *
417 * The processors to query is determined by the procId array.
418 * The array is used to specify which processors to query and the order.
419 * The processor ids are determined via the MultiProc module.
420 * The following are the valid settings for the procId array:
421 * @li <b>NULL:</b> denotes that the local table is searched first, then
422 * all remote processors in ascending order by MultiProc id.
423 * @li <b>Filled in array:</b> The NameServer will search the processors
424 * in the order given in the array. The end of the list must be denoted
425 * by the #MultiProc_INVALIDID value.
426 *
427 * @code
428 * UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
429 * count = NameServer_get(handle, "foo", &value, &len, queryList);
430 * @endcode
431 *
432 * The NameServer_getLocal() call can be used for searching
433 * the local table only.
434 *
435 * @param handle Instance handle
436 * @param name Name to query
437 * @param buf Pointer where the value is returned
438 * @param len Pointer for input/output length.
439 * @param procId Array of processor(s) to query
440 *
441 * @return NameServer status:
442 * - #NameServer_S_SUCCESS: Successfully found entry
443 * - #NameServer_E_NOTFOUND: Entry was not found, len unchanged
444 * - #NameServer_E_FAIL: Error searching for entry
445 *
446 * @sa NameServer_add,
447 * NameServer_getLocal
448 */
449 Int NameServer_get(NameServer_Handle handle,
450 String name,
451 Ptr buf,
452 UInt32 *len,
453 UInt16 procId[]);
455 /*!
456 * @brief Gets a 32-bit value by name
457 *
458 * If the name is found, the value is copied into the value
459 * argument, and a success status is returned.
460 *
461 * If the name is not found, the contents of value are not modified.
462 * Not finding a name is not considered an error.
463 *
464 * For NameServer to work across processors, each processor must
465 * must be assigned a unique id. Because remote NameServer requests
466 * usually employ the use of notifications, it is good practice to
467 * sleep/wait between successive NameServer_get[UInt32] operations if polling
468 * on the success of this call. This helps ensure that remote cores
469 * are not inundated by a flood of incoming notifications and helps
470 * reduce the possiblity of deadlocks.
471 *
472 * The processors to query is determined by the procId array.
473 * The array is used to specify which processors to query and the order.
474 * The processor ids are determined via the MultiProc module.
475 * The following are the valid settings for the procId array:
476 * @li <b>NULL:</b> denotes that the local table is searched first, then
477 * all remote processors in ascending order by MultiProc id.
478 * @li <b>Filled in array:</b> The NameServer will search the processors
479 * in the order given in the array. The end of the list must be denoted
480 * by the #MultiProc_INVALIDID value.
481 *
482 * @code
483 * UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
484 * count = NameServer_getUInt32(handle, "foo", &value, queryList);
485 * @endcode
486 *
487 * The NameServer_getLocal() call can be used for searching
488 * the local table only.
489 * @param handle Instance handle
490 * @param name Name to query
491 * @param buf Pointer where the value is returned
492 * @param procId Array of processor(s) to query
493 *
494 * @return Status
495 * - #NameServer_S_SUCCESS: Successfully found entry
496 * - #NameServer_E_NOTFOUND: Entry was not found
497 * - #NameServer_E_FAIL: Error searching for entry
498 *
499 * @sa NameServer_addUInt32,
500 * NameServer_getLocalUInt32
501 */
502 Int NameServer_getUInt32(NameServer_Handle handle,
503 String name,
504 Ptr buf,
505 UInt16 procId[]);
507 /*!
508 * @brief Gets the variable value length by name from the local table
509 *
510 * If the name is found, the value is copied into the value
511 * argument, the number of MAUs copied is returned in len, and
512 * a success status is returned.
513 *
514 * If the name is not found, zero is returned in len, a fail status is
515 * returned and the contents of value are not modified.
516 * Not finding a name is not considered an error.
517 *
518 * This function only searches the local name/value table.
519 *
520 * @param handle Instance handle
521 * @param name Name to query
522 * @param buf Pointer where the value is returned
523 * @param len Length of the value
524 *
525 * @return Status
526 * - #NameServer_S_SUCCESS: Successfully found entry, len
527 * holds amount of data retrieved.
528 * - #NameServer_E_NOTFOUND: Entry was not found, len remains
529 * unchanged.
530 *
531 * @sa NameServer_add,
532 * NameServer_get
533 */
534 Int NameServer_getLocal(NameServer_Handle handle,
535 String name,
536 Ptr buf,
537 UInt32 *len);
539 /*!
540 * @brief Gets a 32-bit value by name from the local table
541 *
542 * If the name is found, the 32-bit value is copied into buf
543 * and NameServer_S_SUCCESS is returned.
544 *
545 * If the name is not found, zero is copied into buf and
546 * NameServer_E_NOTFOUND is returned.
547 *
548 * This function only searches the local name/value table.
549 *
550 * @param handle Instance handle
551 * @param name Name to query
552 * @param buf Pointer where the value is returned
553 *
554 * @return Status
555 * - #NameServer_S_SUCCESS: Successfully found entry
556 * - #NameServer_E_NOTFOUND: Entry was not found
557 *
558 * @sa NameServer_addUInt32,
559 * NameServer_getUInt32
560 */
561 Int NameServer_getLocalUInt32(NameServer_Handle handle,
562 String name,
563 Ptr buf);
565 /*! @cond
566 * @brief Match the name with the longest entry
567 *
568 * Returns the number of characters that matched with an entry.
569 * So if "abc" and "ab" was an entry and you called match with "abcd",
570 * this function will match the "abc" entry. The return would be 3 since
571 * three characters matched.
572 *
573 * Currently only 32-bit values are supported.
574 *
575 * @param handle Instance handle
576 * @param name Name in question
577 * @param value Pointer in which the value is returned
578 *
579 * @return Number of matching characters
580 */
581 Int NameServer_match(NameServer_Handle handle, String name, UInt32 *value);
583 /*! @endcond */
585 /*!
586 * @brief Remove a name/value pair from the table
587 *
588 * This function removes a name/value pair from the table.
589 *
590 * If #NameServer_Params#maxRuntimeEntries is set to
591 * #NameServer_ALLOWGROWTH,
592 * memory will be freed which was allocated in NameServer_add().
593 * Otherwise, no memory is freed during this call.
594 * The entry in the table is simply emptied.
595 * When another NameServer_add() occurs, it will reuse the empty
596 * entry.
597 *
598 * @param handle Instance handle
599 * @param name Name to remove
600 *
601 * @return Status
602 * - #NameServer_S_SUCCESS: Successfully removed entry or
603 * entry does not exists
604 * - #NameServer_E_FAIL: Operation failed
605 *
606 * @sa NameServer_add
607 */
608 Int NameServer_remove(NameServer_Handle handle, String name);
610 /*!
611 * @brief Remove a name/value pair from the table
612 *
613 * This function removes an entry from the table based on the
614 * unique identifier returned from NameServer_add() or
615 * NameServer_addUInt32().
616 *
617 * If #NameServer_Params#maxRuntimeEntries is set to
618 * #NameServer_ALLOWGROWTH,
619 * memory will be freed which was allocated in NameServer_add().
620 * Otherwise, no memory is freed during this call.
621 * The entry in the table is simply emptied.
622 * When another NameServer_add() occurs, it will reuse the
623 * empty entry.
624 *
625 * Once an Entry is removed from the NameServer table, it cannot be
626 * removed again (just like you cannot free the same block of memory
627 * twice).
628 *
629 * @param handle Instance handle
630 * @param entry Pointer to entry to be removed
631 *
632 * @return Status
633 * - #NameServer_S_SUCCESS: Successfully removed entry or
634 * entry does not exists
635 * - #NameServer_E_FAIL: Operation failed
636 *
637 * @sa NameServer_add
638 */
639 Int NameServer_removeEntry(NameServer_Handle handle, Ptr entry);
641 #if defined (__cplusplus)
642 }
643 #endif /* defined (__cplusplus) */
645 #endif /* ti_ipc_NameServer__include */