More minor coding convention fixes
[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       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  *  Macros
161  * =============================================================================
162  */
164 /*!
165  *  @brief  Allow dynamic growth of the NameServer instance table
166  */
167 #define NameServer_ALLOWGROWTH          (~0)
169 /*!
170  *  @brief  The default maximum length of the name for the name/value pair
171  */
172 #define NameServer_Params_MAXNAMELEN    (16)
174 /* =============================================================================
175  *  Structures & Enums
176  * =============================================================================
177  */
179 /*!
180  *  @brief      NameServer handle type
181  */
182 typedef struct NameServer_Object *NameServer_Handle;
184 /*!
185  *  @brief      NameServer_Handle type
186  */
187 typedef struct NameServer_Params {
188     UInt maxRuntimeEntries;
189     /*!< @brief Maximum name/value pairs that can be dynamically created.
190      *
191      *  This parameter allows NameServer to pre-allocate memory.
192      *  When NameServer_add() or NameServer_addUInt32() is
193      *  called, no memory allocation occurs.
194      *
195      *  If the number of pairs is not known at configuration time, set this
196      *  value to #NameServer_ALLOWGROWTH. This instructs NameServer
197      *  to grow the table as needed. NameServer will allocate memory from the
198      *  #NameServer_Params.tableHeap when a name/value pair is added.
199      *
200      *  The default is #NameServer_ALLOWGROWTH.
201      */
203     Ptr  tableHeap;
204     /*!< @brief Name/value table is allocated from this heap.
205      *
206      *  The instance table and related buffers are allocated out of this heap
207      *  during the dynamic create. This heap is also used to allocate new
208      *  name/value pairs when #NameServer_ALLOWGROWTH for
209      *  #NameServer_Params.maxRuntimeEntries
210      *
211      *  The default is to use the same heap that instances are allocated
212      *  from which can be configured via the
213      *  NameServer.common$.instanceHeap configuration parameter.
214      */
216     Bool checkExisting;
217     /*!< @brief Check if a name already exists in the name/value table.
218      *
219      *  When a name/value pair is added during runtime, if this boolean is
220      *  true, the table is searched to see if the name already exists. If
221      *  it does, the name is not added and the
222      *  #NameServer_E_ALREADYEXISTS error is returned.
223      *
224      *  If this flag is false, the table will not be checked to see if the
225      *  name already exists. It will simply be added. This mode has better
226      *  performance at the expense of potentially having non-unique names
227      *  in the table.
228      *
229      *  This flag is used for runtime adds only. Adding non-unique names during
230      *  configuration results in a build error.
231      */
233     UInt maxValueLen;
234     /*!< @brief Length, in MAUs, of the value field in the table.
235      *
236      *  Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32)
237      */
239     UInt maxNameLen;
240     /*!< @brief Length, in MAUs, of the name field in the table.
241      *
242      *  The maximum length of the name portion of the name/value
243      *  pair.  The length includes the null terminator ('\\0').
244      */
246 } NameServer_Params;
249 /* =============================================================================
250  *  NameServer Module-wide Functions
251  * =============================================================================
252  */
254 /*!
255  *  @brief      Initializes parameter structure
256  *
257  *  @param      params  Instance param structure
258  *
259  *  @sa         NameServer_create()
260  */
261 Void NameServer_Params_init(NameServer_Params *params);
263 /*!
264  *  @brief      Creates a NameServer instance
265  *
266  *  @param      name    Instance name
267  *  @param      params  Instance param structure
268  *
269  *  @return     NameServer handle
270  *
271  *  @sa         NameServer_delete()
272  */
273 NameServer_Handle NameServer_create(String name,
274                                     const NameServer_Params *params);
276 /*!
277  *  @brief      Deletes a NameServer instance
278  *
279  *  If the instance is not empty, the contents is freed back to the
280  *  heap it was allocated from.
281  *
282  *  @param      handlePtr  Pointer to a NameServer handle
283  *
284  *  @return     Status
285  *              - #NameServer_S_SUCCESS:  Instance successfully deleted
286  *              - #NameServer_E_FAIL:  Instance delete failed
287  *
288  *  @sa         NameServer_create()
289  */
290 Int NameServer_delete(NameServer_Handle *handlePtr);
292 /*!
293  *  @brief      Gets the NameServer handle given the name
294  *
295  *  Each NameServer instance has a name. The name and this function can be
296  *  used by the remote driver module to aid in queries to remote
297  *  processors. This function allows the caller to get the local handle
298  *  based on the instance name.
299  *
300  *  For example, when a remote driver sends a request to the remote
301  *  processor, it probably contains the name of the instance to query.
302  *  The receiving remote driver uses that name to obtain the handle for
303  *  the local NameServer instance in question. Then that instance
304  *  can be queried for the name/value pair.
305  *
306  *  This function does not query remote processors.
307  *
308  *  @param      name  Name of instance
309  *
310  *  @return     NameServer handle
311  */
312 NameServer_Handle NameServer_getHandle(String name);
314 /* =============================================================================
315  *  NameServer Per-instance Functions
316  * =============================================================================
317  */
319 /*!
320  *  @brief  Adds a variable length value into the local NameServer table
321  *
322  *  This function adds a variable length value into the local table.
323  *  If the #NameServer_Params.checkExisting flag was true on
324  *  creation, this function searches the table to make sure the name
325  *  does not already exist.  If it does, the name/value pair is not
326  *  added and the #NameServer_E_ALREADYEXISTS error is returned.
327  *
328  *  There is memory allocation during this function if
329  *  #NameServer_Params.maxRuntimeEntries is set to
330  *  #NameServer_ALLOWGROWTH.
331  *
332  *  This function copies the name and buffer into the name/value table,
333  *  so they do not need to be persistent after the call.
334  *
335  *  The function does not query remote processors to make sure the
336  *  name is unique.
337  *
338  *  @param      handle  Instance handle
339  *  @param      name    Name for the name/value pair
340  *  @param      buf     Pointer to value for the name/value pair
341  *  @param      len     length of the value
342  *
343  *  @return     Unique entry identifier
344  *
345  *  @sa         NameServer_addUInt32()
346  *  @sa         NameServer_get()
347  */
348 Ptr NameServer_add(NameServer_Handle handle, String name, Ptr buf, UInt32 len);
350 /*!
351  *  @brief      Adds a 32-bit value into the local NameServer table
352  *
353  *  This function adds a 32-bit value into the local table. This
354  *  function is simply a specialized NameServer_add() function
355  *  that allows a convenient way to add UInt32 bit values without needing
356  *  to specify the address of a UInt32 local variable.
357  *
358  *  If the #NameServer_Params.checkExisting flag was true on
359  *  creation, this function searches the table to make sure the name does
360  *  not already exist.  If it does, the name/value pair is not added and the
361  *  #NameServer_E_ALREADYEXISTS error is returned.
362  *
363  *  This function copies the name into the name/value table.
364  *
365  *  There is memory allocation during this function if
366  *  #NameServer_Params.maxRuntimeEntries is set to
367  *  #NameServer_ALLOWGROWTH.
368  *
369  *  The function does not query remote processors to make sure the
370  *  name is unique.
371  *
372  *  @param      handle  Instance handle
373  *  @param      name    Name for the name/value pair
374  *  @param      value   Value for the name/value pair
375  *
376  *  @return     Unique entry identifier
377  *
378  *  @sa         NameServer_add()
379  *  @sa         NameServer_getUInt32()
380  */
381 Ptr NameServer_addUInt32(NameServer_Handle handle, String name, UInt32 value);
383 /*!
384  *  @brief      Gets the variable value length by name
385  *
386  *  If the name is found, the value is copied into the value
387  *  argument, the number of MAUs copied is returned in len, and
388  *  a success status is returned.
389  *
390  *  If the name is not found, zero is returned in len, the contents
391  *  of value are not modified.  Not finding a name is not considered
392  *  an error.
393  *
394  *  For NameServer to work across processors, each processor must
395  *  must be assigned a unique id.  Because remote NameServer requests
396  *  usually employ the use of notifications, it is good practice to
397  *  sleep/wait between successive NameServer_get[UInt32] operations if polling
398  *  on the success of this call.  This helps ensure that remote cores
399  *  are not inundated by a flood of incoming notifications and helps
400  *  reduce the possibility of deadlocks.
401  *
402  *  The processors to query is determined by the procId array.
403  *  The array is used to specify which processors to query and the order.
404  *  The processor ids are determined via the MultiProc module.
405  *  The following are the valid settings for the procId array:
406  *  @li <b>NULL:</b> denotes that the local table is searched first, then
407  *  all remote processors in ascending order by MultiProc id.
408  *  @li <b>Filled in array:</b> The NameServer will search the processors
409  *  in the order given in the array. The end of the list must be denoted
410  *  by the #MultiProc_INVALIDID value.
411  *
412  *  @code
413  *  UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
414  *  count = NameServer_get(handle, "foo", &value, &len, queryList);
415  *  @endcode
416  *
417  *  The NameServer_getLocal() call can be used for searching
418  *  the local table only.
419  *
420  *  @param      handle          Instance handle
421  *  @param      name            Name to query
422  *  @param      buf             Pointer where the value is returned
423  *  @param      len             Pointer for input/output length.
424  *  @param      procId          Array of processor(s) to query
425  *
426  *  @return     NameServer status:
427  *              - #NameServer_S_SUCCESS:  Successfully found entry
428  *              - #NameServer_E_NOTFOUND: Entry was not found, len unchanged
429  *              - #NameServer_E_FAIL: Error searching for entry
430  *
431  *  @sa         NameServer_add()
432  *  @sa         NameServer_getLocal()
433  */
434 Int NameServer_get(NameServer_Handle handle,
435                    String name,
436                    Ptr buf,
437                    UInt32 *len,
438                    UInt16 procId[]);
440 /*!
441  *  @brief      Gets a 32-bit value by name
442  *
443  *  If the name is found, the value is copied into the value
444  *  argument, and a success status is returned.
445  *
446  *  If the name is not found, the contents of value are not modified.
447  *  Not finding a name is not considered an error.
448  *
449  *  For NameServer to work across processors, each processor must
450  *  must be assigned a unique id.  Because remote NameServer requests
451  *  usually employ the use of notifications, it is good practice to
452  *  sleep/wait between successive NameServer_get[UInt32] operations if polling
453  *  on the success of this call.  This helps ensure that remote cores
454  *  are not inundated by a flood of incoming notifications and helps
455  *  reduce the possibility of deadlocks.
456  *
457  *  The processors to query is determined by the procId array.
458  *  The array is used to specify which processors to query and the order.
459  *  The processor ids are determined via the MultiProc module.
460  *  The following are the valid settings for the procId array:
461  *  @li <b>NULL:</b> denotes that the local table is searched first, then
462  *  all remote processors in ascending order by MultiProc id.
463  *  @li <b>Filled in array:</b> The NameServer will search the processors
464  *  in the order given in the array. The end of the list must be denoted
465  *  by the #MultiProc_INVALIDID value.
466  *
467  *  @code
468  *  UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
469  *  count = NameServer_getUInt32(handle, "foo", &value, queryList);
470  *  @endcode
471  *
472  *  The NameServer_getLocal() call can be used for searching
473  *  the local table only.
474  *  @param      handle          Instance handle
475  *  @param      name            Name to query
476  *  @param      buf             Pointer where the value is returned
477  *  @param      procId          Array of processor(s) to query
478  *
479  *  @return     Status
480  *              - #NameServer_S_SUCCESS:  Successfully found entry
481  *              - #NameServer_E_NOTFOUND: Entry was not found
482  *              - #NameServer_E_FAIL: Error searching for entry
483  *
484  *  @sa         NameServer_addUInt32()
485  *  @sa         NameServer_getLocalUInt32()
486  */
487 Int NameServer_getUInt32(NameServer_Handle handle,
488                          String name,
489                          Ptr buf,
490                          UInt16 procId[]);
492 /*!
493  *  @brief      Gets the variable value length by name from the local table
494  *
495  *  If the name is found, the value is copied into the value
496  *  argument, the number of MAUs copied is returned in len, and
497  *  a success status is returned.
498  *
499  *  If the name is not found, zero is returned in len, a fail status is
500  *  returned and the contents of value are not modified.
501  *  Not finding a name is not considered an error.
502  *
503  *  This function only searches the local name/value table.
504  *
505  *  @param      handle  Instance handle
506  *  @param      name    Name to query
507  *  @param      buf     Pointer where the value is returned
508  *  @param      len     Length of the value
509  *
510  *  @return     Status
511  *              - #NameServer_S_SUCCESS:  Successfully found entry, len
512  *                                        holds amount of data retrieved.
513  *              - #NameServer_E_NOTFOUND:  Entry was not found, len remains
514  *                                     unchanged.
515  *
516  *  @sa         NameServer_add()
517  *  @sa         NameServer_get()
518  */
519 Int NameServer_getLocal(NameServer_Handle handle,
520                         String name,
521                         Ptr buf,
522                         UInt32 *len);
524 /*!
525  *  @brief      Gets a 32-bit value by name from the local table
526  *
527  *  If the name is found, the 32-bit value is copied into buf
528  *  and NameServer_S_SUCCESS is returned.
529  *
530  *  If the name is not found, zero is copied into buf and
531  *  NameServer_E_NOTFOUND is returned.
532  *
533  *  This function only searches the local name/value table.
534  *
535  *  @param      handle  Instance handle
536  *  @param      name    Name to query
537  *  @param      buf     Pointer where the value is returned
538  *
539  *  @return     Status
540  *              - #NameServer_S_SUCCESS:  Successfully found entry
541  *              - #NameServer_E_NOTFOUND:  Entry was not found
542  *
543  *  @sa         NameServer_addUInt32()
544  *  @sa         NameServer_getUInt32()
545  */
546 Int NameServer_getLocalUInt32(NameServer_Handle handle,
547                               String name,
548                               Ptr buf);
550 /*!  @cond
551   *  @brief      Match the name with the longest entry
552   *
553   *  Returns the number of characters that matched with an entry.
554   *  So if "abc" and "ab" was an entry and you called match with "abcd",
555   *  this function will match the "abc" entry. The return would be 3 since
556   *  three characters matched.
557   *
558   *  Currently only 32-bit values are supported.
559   *
560   *  @param     handle  Instance handle
561   *  @param     name    Name in question
562   *  @param     value   Pointer in which the value is returned
563   *
564   *  @return    Number of matching characters
565   */
566 Int NameServer_match(NameServer_Handle handle, String name, UInt32 *value);
568 /*! @endcond */
570 /*!
571  *  @brief        Remove a name/value pair from the table
572  *
573  *  This function removes a name/value pair from the table.
574  *
575  *  If #NameServer_Params.maxRuntimeEntries is set to
576  *  #NameServer_ALLOWGROWTH,
577  *  memory will be freed which was allocated in NameServer_add().
578  *  Otherwise, no memory is freed during this call.
579  *  The entry in the table is simply emptied.
580  *  When another NameServer_add() occurs, it will reuse the empty
581  *  entry.
582  *
583  *  @param      handle  Instance handle
584  *  @param      name    Name to remove
585  *
586  *  @return     Status
587  *              - #NameServer_S_SUCCESS:  Successfully removed entry or
588  *                                        entry does not exists
589  *              - #NameServer_E_FAIL:  Operation failed
590  *
591  *  @sa         NameServer_add
592  */
593 Int NameServer_remove(NameServer_Handle handle, String name);
595 /*!
596  *  @brief        Remove a name/value pair from the table
597  *
598  *  This function removes an entry from the table based on the
599  *  unique identifier returned from NameServer_add() or
600  *  NameServer_addUInt32().
601  *
602  *  If #NameServer_Params#maxRuntimeEntries is set to
603  *  #NameServer_ALLOWGROWTH,
604  *  memory will be freed which was allocated in NameServer_add().
605  *  Otherwise, no memory is freed during this call.
606  *  The entry in the table is simply emptied.
607  *  When another NameServer_add() occurs, it will reuse the
608  *  empty entry.
609  *
610  *  Once an entry is removed from the NameServer table, it cannot be
611  *  removed again (just like you cannot free the same block of memory
612  *  twice).
613  *
614  *  @param      handle  Instance handle
615  *  @param      entry   Pointer to entry to be removed
616  *
617  *  @return     Status
618  *              - #NameServer_S_SUCCESS:  Successfully removed entry or
619  *                                        entry does not exists
620  *              - #NameServer_E_FAIL:  Operation failed
621  *
622  *  @sa         NameServer_add()
623  */
624 Int NameServer_removeEntry(NameServer_Handle handle, Ptr entry);
626 #if defined (__cplusplus)
628 #endif /* defined (__cplusplus) */
630 #endif /* ti_ipc_NameServer__include */