Initial commit
[ipc/ipcdev.git] / packages / ti / ipc / NameServer.h
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)
643 #endif /* defined (__cplusplus) */
645 #endif /* ti_ipc_NameServer__include */