1f8192ac793653e8c82e05a8e2cd750bea6bb90e
1 /*
2 * Copyright (c) 2012-2015, 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 ti/ipc/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 * @brief The resource is still in use
96 */
97 #define NameServer_S_BUSY (2)
99 /*!
100 * @brief The module has been already setup
101 */
102 #define NameServer_S_ALREADYSETUP (1)
104 /*!
105 * @brief Operation is successful.
106 */
107 #define NameServer_S_SUCCESS (0)
109 /*!
110 * @brief Generic failure.
111 */
112 #define NameServer_E_FAIL (-1)
114 /*!
115 * @brief Argument passed to function is invalid.
116 */
117 #define NameServer_E_INVALIDARG (-2)
119 /*!
120 * @brief Operation resulted in memory failure.
121 */
122 #define NameServer_E_MEMORY (-3)
124 /*!
125 * @brief The specified entity already exists.
126 */
127 #define NameServer_E_ALREADYEXISTS (-4)
129 /*!
130 * @brief Unable to find the specified entity.
131 */
132 #define NameServer_E_NOTFOUND (-5)
134 /*!
135 * @brief Operation timed out.
136 */
137 #define NameServer_E_TIMEOUT (-6)
139 /*!
140 * @brief Module is not initialized.
141 */
142 #define NameServer_E_INVALIDSTATE (-7)
144 /*!
145 * @brief A failure occurred in an OS-specific call
146 */
147 #define NameServer_E_OSFAILURE (-8)
149 /*!
150 * @brief Specified resource is not available
151 */
152 #define NameServer_E_RESOURCE (-9)
154 /*!
155 * @brief Operation was interrupted. Please restart the operation
156 */
157 #define NameServer_E_RESTART (-10)
159 /*!
160 * @brief Name is too long.
161 *
162 * The underlying remote implementation was unable to handle such a long
163 * instance or entry name.
164 * See these files for the maximum number of characters that can be specified
165 * in a name for common NameServer remote implementations:
166 *
167 * - NameServerRemoteRpmsg:
168 * packages/ti/ipc/namesrv/_NameServerRemoteRpmsg.h
169 *
170 */
171 #define NameServer_E_NAMETOOLONG (-11)
173 /* =============================================================================
174 * Macros
175 * =============================================================================
176 */
178 /*!
179 * @brief Allow dynamic growth of the NameServer instance table
180 */
181 #define NameServer_ALLOWGROWTH (~0)
183 /*!
184 * @brief The default maximum length of the name for the name/value pair
185 */
186 #define NameServer_Params_MAXNAMELEN (16)
188 /* =============================================================================
189 * Structures & Enums
190 * =============================================================================
191 */
193 /*!
194 * @brief NameServer handle type
195 */
196 typedef struct NameServer_Object *NameServer_Handle;
198 /*!
199 * @brief NameServer_Handle type
200 */
201 typedef struct NameServer_Params {
202 UInt maxRuntimeEntries;
203 /*!< @brief Maximum name/value pairs that can be dynamically created.
204 *
205 * This parameter allows NameServer to pre-allocate memory.
206 * When NameServer_add() or NameServer_addUInt32() is
207 * called, no memory allocation occurs.
208 *
209 * If the number of pairs is not known at configuration time, set this
210 * value to #NameServer_ALLOWGROWTH. This instructs NameServer
211 * to grow the table as needed. NameServer will allocate memory from the
212 * #NameServer_Params.tableHeap when a name/value pair is added.
213 *
214 * The default is #NameServer_ALLOWGROWTH.
215 */
217 Ptr tableHeap;
218 /*!< @brief Name/value table is allocated from this heap.
219 *
220 * The instance table and related buffers are allocated out of this heap
221 * during the dynamic create. This heap is also used to allocate new
222 * name/value pairs when #NameServer_ALLOWGROWTH for
223 * #NameServer_Params.maxRuntimeEntries
224 *
225 * The default is to use the same heap that instances are allocated
226 * from which can be configured via the
227 * NameServer.common$.instanceHeap configuration parameter.
228 */
230 Bool checkExisting;
231 /*!< @brief Check if a name already exists in the name/value table.
232 *
233 * When a name/value pair is added during runtime, if this boolean is
234 * true, the table is searched to see if the name already exists. If
235 * it does, the name is not added and the
236 * #NameServer_E_ALREADYEXISTS error is returned.
237 *
238 * If this flag is false, the table will not be checked to see if the
239 * name already exists. It will simply be added. This mode has better
240 * performance at the expense of potentially having non-unique names
241 * in the table.
242 *
243 * This flag is used for runtime adds only. Adding non-unique names during
244 * configuration results in a build error.
245 */
247 UInt maxValueLen;
248 /*!< @brief Length, in MAUs, of the value field in the table.
249 *
250 * Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32)
251 */
253 UInt maxNameLen;
254 /*!< @brief Length, in MAUs, of the name field in the table.
255 *
256 * The maximum length of the name portion of the name/value
257 * pair. The length includes the null terminator ('\\0').
258 */
260 } NameServer_Params;
263 /* =============================================================================
264 * NameServer Module-wide Functions
265 * =============================================================================
266 */
268 /*!
269 * @brief Initializes parameter structure
270 *
271 * @param params Instance param structure
272 *
273 * @sa NameServer_create()
274 */
275 Void NameServer_Params_init(NameServer_Params *params);
277 /*!
278 * @brief Creates a NameServer instance
279 *
280 * If NameServer_create() was previously called to create an instance with the
281 * same name, subsequent calls to NameServer_create() on the same name will
282 * simply return a valid handle to the existing NameServer instance, similar
283 * to what is done by NameServer_getHandle().
284 *
285 * @param name Instance name
286 * @param params Instance param structure
287 *
288 * @return NameServer handle
289 *
290 * @sa NameServer_delete()
291 */
292 NameServer_Handle NameServer_create(String name,
293 const NameServer_Params *params);
295 /*!
296 * @brief Deletes a NameServer instance
297 *
298 * If the instance is not empty, the contents is freed back to the
299 * heap it was allocated from.
300 *
301 * If NameServer_create() was called multiple times on the same name,
302 * a matching number of calls to NameServer_delete() is necessary in
303 * order to fully deallocate the instance.
304 *
305 * @param handlePtr Pointer to a NameServer handle
306 *
307 * @return Status
308 * - #NameServer_S_SUCCESS: Instance successfully deleted
309 * - #NameServer_E_FAIL: Instance delete failed
310 *
311 * @sa NameServer_create()
312 */
313 Int NameServer_delete(NameServer_Handle *handlePtr);
315 /*!
316 * @brief Gets the NameServer handle given the name
317 *
318 * Each NameServer instance has a name. The name and this function can be
319 * used by the remote driver module to aid in queries to remote
320 * processors. This function allows the caller to get the local handle
321 * based on the instance name.
322 *
323 * For example, when a remote driver sends a request to the remote
324 * processor, it probably contains the name of the instance to query.
325 * The receiving remote driver uses that name to obtain the handle for
326 * the local NameServer instance in question. Then that instance
327 * can be queried for the name/value pair.
328 *
329 * This function does not query remote processors.
330 *
331 * @param name Name of instance
332 *
333 * @return NameServer handle
334 */
335 NameServer_Handle NameServer_getHandle(String name);
337 /* =============================================================================
338 * NameServer Per-instance Functions
339 * =============================================================================
340 */
342 /*!
343 * @brief Adds a variable length value into the local NameServer table
344 *
345 * This function adds a variable length value into the local table.
346 * If the #NameServer_Params.checkExisting flag was true on
347 * creation, this function searches the table to make sure the name
348 * does not already exist. If it does, the name/value pair is not
349 * added and the #NameServer_E_ALREADYEXISTS error is returned.
350 *
351 * There is memory allocation during this function if
352 * #NameServer_Params.maxRuntimeEntries is set to
353 * #NameServer_ALLOWGROWTH.
354 *
355 * This function copies the name and buffer into the name/value table,
356 * so they do not need to be persistent after the call.
357 *
358 * The function does not query remote processors to make sure the
359 * name is unique.
360 *
361 * @param handle Instance handle
362 * @param name Name for the name/value pair
363 * @param buf Pointer to value for the name/value pair
364 * @param len length of the value
365 *
366 * @return Unique entry identifier, or NULL if unsuccessful
367 *
368 * @sa NameServer_addUInt32()
369 * @sa NameServer_get()
370 */
371 Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
373 /*!
374 * @brief Adds a 32-bit value into the local NameServer table
375 *
376 * This function adds a 32-bit value into the local table. This
377 * function is simply a specialized NameServer_add() function
378 * that allows a convenient way to add UInt32 bit values without needing
379 * to specify the address of a UInt32 local variable.
380 *
381 * If the #NameServer_Params.checkExisting flag was true on
382 * creation, this function searches the table to make sure the name does
383 * not already exist. If it does, the name/value pair is not added and the
384 * #NameServer_E_ALREADYEXISTS error is returned.
385 *
386 * This function copies the name into the name/value table.
387 *
388 * There is memory allocation during this function if
389 * #NameServer_Params.maxRuntimeEntries is set to
390 * #NameServer_ALLOWGROWTH.
391 *
392 * The function does not query remote processors to make sure the
393 * name is unique.
394 *
395 * @param handle Instance handle
396 * @param name Name for the name/value pair
397 * @param value Value for the name/value pair
398 *
399 * @return Unique entry identifier, or NULL if unsuccessful
400 *
401 * @sa NameServer_add()
402 * @sa NameServer_getUInt32()
403 */
404 Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
406 /*!
407 * @brief Gets the variable value length by name
408 *
409 * If the name is found, the value is copied into the value
410 * argument, the number of MAUs copied is returned in len, and
411 * a success status is returned.
412 *
413 * If the name is not found, zero is returned in len, the contents
414 * of value are not modified. Not finding a name is not considered
415 * an error.
416 *
417 * For NameServer to work across processors, each processor must
418 * must be assigned a unique id. Because remote NameServer requests
419 * usually employ the use of notifications, it is good practice to
420 * sleep/wait between successive NameServer_get[UInt32] operations if polling
421 * on the success of this call. This helps ensure that remote cores
422 * are not inundated by a flood of incoming notifications and helps
423 * reduce the possibility of deadlocks.
424 *
425 * The processors to query is determined by the procId array.
426 * The array is used to specify which processors to query and the order.
427 * The processor ids are determined via the MultiProc module.
428 * The following are the valid settings for the procId array:
429 * @li <b>NULL:</b> denotes that the local table is searched first, then
430 * all remote processors in ascending order by MultiProc id.
431 * @li <b>Filled in array:</b> The NameServer will search the processors
432 * in the order given in the array. The end of the list must be denoted
433 * by the #MultiProc_INVALIDID value.
434 *
435 * @code
436 * UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
437 * count = NameServer_get(handle, "foo", &value, &len, queryList);
438 * @endcode
439 *
440 * The NameServer_getLocal() call can be used for searching
441 * the local table only.
442 *
443 * @param handle Instance handle
444 * @param name Name to query
445 * @param buf Pointer where the value is returned
446 * @param len Pointer for input/output length.
447 * @param procId Array of processor(s) to query
448 *
449 * @return NameServer status:
450 * - #NameServer_S_SUCCESS: Successfully found entry
451 * - #NameServer_E_NOTFOUND: Entry was not found, len unchanged
452 * - #NameServer_E_FAIL: Error searching for entry
453 * - #NameServer_E_NAMETOOLONG: Instance name or query name is
454 * too long for NameServer remote to process
455 *
456 * @sa NameServer_add()
457 * @sa NameServer_getLocal()
458 */
459 Int NameServer_get(NameServer_Handle handle,
460 String name,
461 Ptr buf,
462 UInt32 *len,
463 UInt16 procId[]);
465 /*!
466 * @brief Gets a 32-bit value by name
467 *
468 * If the name is found, the value is copied into the value
469 * argument, and a success status is returned.
470 *
471 * If the name is not found, the contents of value are not modified.
472 * Not finding a name is not considered an error.
473 *
474 * For NameServer to work across processors, each processor must
475 * must be assigned a unique id. Because remote NameServer requests
476 * usually employ the use of notifications, it is good practice to
477 * sleep/wait between successive NameServer_get[UInt32] operations if polling
478 * on the success of this call. This helps ensure that remote cores
479 * are not inundated by a flood of incoming notifications and helps
480 * reduce the possibility of deadlocks.
481 *
482 * The processors to query is determined by the procId array.
483 * The array is used to specify which processors to query and the order.
484 * The processor ids are determined via the MultiProc module.
485 * The following are the valid settings for the procId array:
486 * @li <b>NULL:</b> denotes that the local table is searched first, then
487 * all remote processors in ascending order by MultiProc id.
488 * @li <b>Filled in array:</b> The NameServer will search the processors
489 * in the order given in the array. The end of the list must be denoted
490 * by the #MultiProc_INVALIDID value.
491 *
492 * @code
493 * UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
494 * count = NameServer_getUInt32(handle, "foo", &value, queryList);
495 * @endcode
496 *
497 * The NameServer_getLocal() call can be used for searching
498 * the local table only.
499 * @param handle Instance handle
500 * @param name Name to query
501 * @param buf Pointer where the value is returned
502 * @param procId Array of processor(s) to query
503 *
504 * @return Status
505 * - #NameServer_S_SUCCESS: Successfully found entry
506 * - #NameServer_E_NOTFOUND: Entry was not found
507 * - #NameServer_E_FAIL: Error searching for entry
508 *
509 * @sa NameServer_addUInt32()
510 * @sa NameServer_getLocalUInt32()
511 */
512 Int NameServer_getUInt32(NameServer_Handle handle,
513 String name,
514 Ptr buf,
515 UInt16 procId[]);
517 /*!
518 * @brief Gets the variable value length by name from the local table
519 *
520 * If the name is found, the value is copied into the value
521 * argument, the number of MAUs copied is returned in len, and
522 * a success status is returned.
523 *
524 * If the name is not found, zero is returned in len, a fail status is
525 * returned and the contents of value are not modified.
526 * Not finding a name is not considered an error.
527 *
528 * This function only searches the local name/value table.
529 *
530 * @param handle Instance handle
531 * @param name Name to query
532 * @param buf Pointer where the value is returned
533 * @param len Length of the value
534 *
535 * @return Status
536 * - #NameServer_S_SUCCESS: Successfully found entry, len
537 * holds amount of data retrieved.
538 * - #NameServer_E_NOTFOUND: Entry was not found, len remains
539 * unchanged.
540 *
541 * @sa NameServer_add()
542 * @sa NameServer_get()
543 */
544 Int NameServer_getLocal(NameServer_Handle handle,
545 String name,
546 Ptr buf,
547 UInt32 *len);
549 /*!
550 * @brief Gets a 32-bit value by name from the local table
551 *
552 * If the name is found, the 32-bit value is copied into buf
553 * and NameServer_S_SUCCESS is returned.
554 *
555 * If the name is not found, zero is copied into buf and
556 * NameServer_E_NOTFOUND is returned.
557 *
558 * This function only searches the local name/value table.
559 *
560 * @param handle Instance handle
561 * @param name Name to query
562 * @param buf Pointer where the value is returned
563 *
564 * @return Status
565 * - #NameServer_S_SUCCESS: Successfully found entry
566 * - #NameServer_E_NOTFOUND: Entry was not found
567 *
568 * @sa NameServer_addUInt32()
569 * @sa NameServer_getUInt32()
570 */
571 Int NameServer_getLocalUInt32(NameServer_Handle handle,
572 String name,
573 Ptr buf);
575 /*! @cond
576 * @brief Match the name with the longest entry
577 *
578 * Returns the number of characters that matched with an entry.
579 * So if "abc" and "ab" was an entry and you called match with "abcd",
580 * this function will match the "abc" entry. The return would be 3 since
581 * three characters matched.
582 *
583 * Currently only 32-bit values are supported.
584 *
585 * @param handle Instance handle
586 * @param name Name in question
587 * @param value Pointer in which the value is returned
588 *
589 * @return Number of matching characters
590 */
591 Int NameServer_match(NameServer_Handle handle, String name, UInt32 *value);
593 /*! @endcond */
595 /*!
596 * @brief Remove a name/value pair from the table
597 *
598 * This function removes a name/value pair from the table.
599 *
600 * If #NameServer_Params.maxRuntimeEntries is set to
601 * #NameServer_ALLOWGROWTH,
602 * memory will be freed which was allocated in NameServer_add().
603 * Otherwise, no memory is freed during this call.
604 * The entry in the table is simply emptied.
605 * When another NameServer_add() occurs, it will reuse the empty
606 * entry.
607 *
608 * @param handle Instance handle
609 * @param name Name to remove
610 *
611 * @return Status
612 * - #NameServer_S_SUCCESS: Successfully removed entry or
613 * entry does not exists
614 * - #NameServer_E_FAIL: Operation failed
615 *
616 * @sa NameServer_add
617 */
618 Int NameServer_remove(NameServer_Handle handle, String name);
620 /*!
621 * @brief Remove a name/value pair from the table
622 *
623 * This function removes an entry from the table based on the
624 * unique identifier returned from NameServer_add() or
625 * NameServer_addUInt32().
626 *
627 * If #NameServer_Params#maxRuntimeEntries is set to
628 * #NameServer_ALLOWGROWTH,
629 * memory will be freed which was allocated in NameServer_add().
630 * Otherwise, no memory is freed during this call.
631 * The entry in the table is simply emptied.
632 * When another NameServer_add() occurs, it will reuse the
633 * empty entry.
634 *
635 * Once an entry is removed from the NameServer table, it cannot be
636 * removed again (just like you cannot free the same block of memory
637 * twice).
638 *
639 * @param handle Instance handle
640 * @param entry Pointer to entry to be removed
641 *
642 * @return Status
643 * - #NameServer_S_SUCCESS: Successfully removed entry or
644 * entry does not exists
645 * - #NameServer_E_FAIL: Operation failed
646 *
647 * @sa NameServer_add()
648 */
649 Int NameServer_removeEntry(NameServer_Handle handle, Ptr entry);
651 #if defined (__cplusplus)
652 }
653 #endif /* defined (__cplusplus) */
655 #endif /* ti_ipc_NameServer__include */