IPC API  3.40.00.06
Data Structures | Macros | Typedefs | Functions
NameServer.h File Reference

Detailed Description

NameServer Manager.

The NameServer module manages local name/value pairs that enables an application and other modules to store and retrieve values based on a name. The module supports different lengths of values. The NameServer_add() and NameServer_get() functions are for variable length values. The NameServer_addUInt32() and NameServer_getUInt32() functions are optimized for UInt32 variables and constants.

The NameServer module maintains thread-safety for the APIs. However, the NameServer APIs cannot be called from an interrupt (i.e. Hwi) context. However, it is safe to use the APIs in Swi's and Tasks.

Each NameServer instance manages a different name/value table. This allows each table to be customized to meet the requirements of user:

When adding a name/value pair, the name and value are copied into internal buffers in NameServer. To minimize runtime memory allocation these buffers can be allocated at creation time.

NameServer maintains the name/values table in local memory (e.g. not shared memory). However the NameServer module can be used in a multiprocessor system.

The NameServer module uses the MultiProc module for identifying the different processors. Which remote processors and the order they are queried is determined by the procId array in the NameServer_get() function.

Currently there is no endian or wordsize conversion performed by the NameServer module. Also there is no asynchronous support at this time.

The NameServer header should be included in an application as follows:

Go to the source code of this file.

Data Structures

struct  NameServer_Params
 NameServer_Handle type. More...
 

Macros

#define NameServer_S_BUSY   (2)
 The resource is still in use. More...
 
#define NameServer_S_ALREADYSETUP   (1)
 The module has been already setup. More...
 
#define NameServer_S_SUCCESS   (0)
 Operation is successful. More...
 
#define NameServer_E_FAIL   (-1)
 Generic failure. More...
 
#define NameServer_E_INVALIDARG   (-2)
 Argument passed to function is invalid. More...
 
#define NameServer_E_MEMORY   (-3)
 Operation resulted in memory failure. More...
 
#define NameServer_E_ALREADYEXISTS   (-4)
 The specified entity already exists. More...
 
#define NameServer_E_NOTFOUND   (-5)
 Unable to find the specified entity. More...
 
#define NameServer_E_TIMEOUT   (-6)
 Operation timed out. More...
 
#define NameServer_E_INVALIDSTATE   (-7)
 Module is not initialized. More...
 
#define NameServer_E_OSFAILURE   (-8)
 A failure occurred in an OS-specific call. More...
 
#define NameServer_E_RESOURCE   (-9)
 Specified resource is not available. More...
 
#define NameServer_E_RESTART   (-10)
 Operation was interrupted. Please restart the operation. More...
 
#define NameServer_E_NAMETOOLONG   (-11)
 Name is too long. More...
 
#define NameServer_ALLOWGROWTH   (~0)
 Allow dynamic growth of the NameServer instance table. More...
 
#define NameServer_Params_MAXNAMELEN   (16)
 The default maximum length of the name for the name/value pair. More...
 

Typedefs

typedef struct NameServer_Object * NameServer_Handle
 NameServer handle type. More...
 
typedef struct NameServer_Params NameServer_Params
 NameServer_Handle type. More...
 

Functions

Void NameServer_Params_init (NameServer_Params *params)
 Initializes parameter structure. More...
 
NameServer_Handle NameServer_create (String name, const NameServer_Params *params)
 Creates a NameServer instance. More...
 
Int NameServer_delete (NameServer_Handle *handlePtr)
 Deletes a NameServer instance. More...
 
NameServer_Handle NameServer_getHandle (String name)
 Gets the NameServer handle given the name. More...
 
Ptr NameServer_add (NameServer_Handle handle, String name, Ptr buf, UInt32 len)
 Adds a variable length value into the local NameServer table. More...
 
Ptr NameServer_addUInt32 (NameServer_Handle handle, String name, UInt32 value)
 Adds a 32-bit value into the local NameServer table. More...
 
Int NameServer_get (NameServer_Handle handle, String name, Ptr buf, UInt32 *len, UInt16 procId[])
 Gets the variable value length by name. More...
 
Int NameServer_getUInt32 (NameServer_Handle handle, String name, Ptr buf, UInt16 procId[])
 Gets a 32-bit value by name. More...
 
Int NameServer_getLocal (NameServer_Handle handle, String name, Ptr buf, UInt32 *len)
 Gets the variable value length by name from the local table. More...
 
Int NameServer_getLocalUInt32 (NameServer_Handle handle, String name, Ptr buf)
 Gets a 32-bit value by name from the local table. More...
 
Int NameServer_remove (NameServer_Handle handle, String name)
 Remove a name/value pair from the table. More...
 
Int NameServer_removeEntry (NameServer_Handle handle, Ptr entry)
 Remove a name/value pair from the table. More...
 

Macro Definition Documentation

#define NameServer_S_BUSY   (2)

The resource is still in use.

#define NameServer_S_ALREADYSETUP   (1)

The module has been already setup.

#define NameServer_S_SUCCESS   (0)

Operation is successful.

#define NameServer_E_FAIL   (-1)

Generic failure.

#define NameServer_E_INVALIDARG   (-2)

Argument passed to function is invalid.

#define NameServer_E_MEMORY   (-3)

Operation resulted in memory failure.

#define NameServer_E_ALREADYEXISTS   (-4)

The specified entity already exists.

#define NameServer_E_NOTFOUND   (-5)

Unable to find the specified entity.

#define NameServer_E_TIMEOUT   (-6)

Operation timed out.

#define NameServer_E_INVALIDSTATE   (-7)

Module is not initialized.

#define NameServer_E_OSFAILURE   (-8)

A failure occurred in an OS-specific call.

#define NameServer_E_RESOURCE   (-9)

Specified resource is not available.

#define NameServer_E_RESTART   (-10)

Operation was interrupted. Please restart the operation.

#define NameServer_E_NAMETOOLONG   (-11)

Name is too long.

The underlying remote implementation was unable to handle such a long instance or entry name. See these files for the maximum number of characters that can be specified in a name for common NameServer remote implementations:

  • NameServerRemoteRpmsg: packages/ti/ipc/namesrv/_NameServerRemoteRpmsg.h
#define NameServer_ALLOWGROWTH   (~0)

Allow dynamic growth of the NameServer instance table.

#define NameServer_Params_MAXNAMELEN   (16)

The default maximum length of the name for the name/value pair.

Typedef Documentation

typedef struct NameServer_Object* NameServer_Handle

NameServer handle type.

NameServer_Handle type.

Function Documentation

Void NameServer_Params_init ( NameServer_Params params)

Initializes parameter structure.

Parameters
paramsInstance param structure
See also
NameServer_create()
NameServer_Handle NameServer_create ( String  name,
const NameServer_Params params 
)

Creates a NameServer instance.

If NameServer_create() was previously called to create an instance with the same name, subsequent calls to NameServer_create() on the same name will simply return a valid handle to the existing NameServer instance, similar to what is done by NameServer_getHandle().

Parameters
nameInstance name
paramsInstance param structure
Returns
NameServer handle
See also
NameServer_delete()
Int NameServer_delete ( NameServer_Handle handlePtr)

Deletes a NameServer instance.

If the instance is not empty, the contents is freed back to the heap it was allocated from.

If NameServer_create() was called multiple times on the same name, a matching number of calls to NameServer_delete() is necessary in order to fully deallocate the instance.

Parameters
handlePtrPointer to a NameServer handle
Returns
Status
See also
NameServer_create()
NameServer_Handle NameServer_getHandle ( String  name)

Gets the NameServer handle given the name.

Each NameServer instance has a name. The name and this function can be used by the remote driver module to aid in queries to remote processors. This function allows the caller to get the local handle based on the instance name.

For example, when a remote driver sends a request to the remote processor, it probably contains the name of the instance to query. The receiving remote driver uses that name to obtain the handle for the local NameServer instance in question. Then that instance can be queried for the name/value pair.

This function does not query remote processors.

Parameters
nameName of instance
Returns
NameServer handle
Ptr NameServer_add ( NameServer_Handle  handle,
String  name,
Ptr  buf,
UInt32  len 
)

Adds a variable length value into the local NameServer table.

This function adds a variable length value into the local table. If the NameServer_Params.checkExisting flag was true on creation, this function searches the table to make sure the name does not already exist. If it does, the name/value pair is not added and the NameServer_E_ALREADYEXISTS error is returned.

There is memory allocation during this function if NameServer_Params.maxRuntimeEntries is set to NameServer_ALLOWGROWTH.

This function copies the name and buffer into the name/value table, so they do not need to be persistent after the call.

The function does not query remote processors to make sure the name is unique.

Parameters
handleInstance handle
nameName for the name/value pair
bufPointer to value for the name/value pair
lenlength of the value
Returns
Unique entry identifier, or NULL if unsuccessful
See also
NameServer_addUInt32()
NameServer_get()
Ptr NameServer_addUInt32 ( NameServer_Handle  handle,
String  name,
UInt32  value 
)

Adds a 32-bit value into the local NameServer table.

This function adds a 32-bit value into the local table. This function is simply a specialized NameServer_add() function that allows a convenient way to add UInt32 bit values without needing to specify the address of a UInt32 local variable.

If the NameServer_Params.checkExisting flag was true on creation, this function searches the table to make sure the name does not already exist. If it does, the name/value pair is not added and the NameServer_E_ALREADYEXISTS error is returned.

This function copies the name into the name/value table.

There is memory allocation during this function if NameServer_Params.maxRuntimeEntries is set to NameServer_ALLOWGROWTH.

The function does not query remote processors to make sure the name is unique.

Parameters
handleInstance handle
nameName for the name/value pair
valueValue for the name/value pair
Returns
Unique entry identifier, or NULL if unsuccessful
See also
NameServer_add()
NameServer_getUInt32()
Int NameServer_get ( NameServer_Handle  handle,
String  name,
Ptr  buf,
UInt32 *  len,
UInt16  procId[] 
)

Gets the variable value length by name.

If the name is found, the value is copied into the value argument, the number of MAUs copied is returned in len, and a success status is returned.

If the name is not found, zero is returned in len, the contents of value are not modified. Not finding a name is not considered an error.

For NameServer to work across processors, each processor must must be assigned a unique id. Because remote NameServer requests usually employ the use of notifications, it is good practice to sleep/wait between successive NameServer_get[UInt32] operations if polling on the success of this call. This helps ensure that remote cores are not inundated by a flood of incoming notifications and helps reduce the possibility of deadlocks.

The processors to query is determined by the procId array. The array is used to specify which processors to query and the order. The processor ids are determined via the MultiProc module. The following are the valid settings for the procId array:

  • NULL: denotes that the local table is searched first, then all remote processors in ascending order by MultiProc id.
  • Filled in array: The NameServer will search the processors in the order given in the array. The end of the list must be denoted by the MultiProc_INVALIDID value.
1 UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
2 count = NameServer_get(handle, "foo", &value, &len, queryList);

The NameServer_getLocal() call can be used for searching the local table only.

Parameters
handleInstance handle
nameName to query
bufPointer where the value is returned
lenPointer for input/output length.
procIdArray of processor(s) to query
Returns
NameServer status:
See also
NameServer_add()
NameServer_getLocal()
Int NameServer_getUInt32 ( NameServer_Handle  handle,
String  name,
Ptr  buf,
UInt16  procId[] 
)

Gets a 32-bit value by name.

If the name is found, the value is copied into the value argument, and a success status is returned.

If the name is not found, the contents of value are not modified. Not finding a name is not considered an error.

For NameServer to work across processors, each processor must must be assigned a unique id. Because remote NameServer requests usually employ the use of notifications, it is good practice to sleep/wait between successive NameServer_get[UInt32] operations if polling on the success of this call. This helps ensure that remote cores are not inundated by a flood of incoming notifications and helps reduce the possibility of deadlocks.

The processors to query is determined by the procId array. The array is used to specify which processors to query and the order. The processor ids are determined via the MultiProc module. The following are the valid settings for the procId array:

  • NULL: denotes that the local table is searched first, then all remote processors in ascending order by MultiProc id.
  • Filled in array: The NameServer will search the processors in the order given in the array. The end of the list must be denoted by the MultiProc_INVALIDID value.
1 UInt16 queryList[4] = {3, 2, 4, MultiProc_INVALIDID};
2 count = NameServer_getUInt32(handle, "foo", &value, queryList);

The NameServer_getLocal() call can be used for searching the local table only.

Parameters
handleInstance handle
nameName to query
bufPointer where the value is returned
procIdArray of processor(s) to query
Returns
Status
See also
NameServer_addUInt32()
NameServer_getLocalUInt32()
Int NameServer_getLocal ( NameServer_Handle  handle,
String  name,
Ptr  buf,
UInt32 *  len 
)

Gets the variable value length by name from the local table.

If the name is found, the value is copied into the value argument, the number of MAUs copied is returned in len, and a success status is returned.

If the name is not found, zero is returned in len, a fail status is returned and the contents of value are not modified. Not finding a name is not considered an error.

This function only searches the local name/value table.

Parameters
handleInstance handle
nameName to query
bufPointer where the value is returned
lenLength of the value
Returns
Status
See also
NameServer_add()
NameServer_get()
Int NameServer_getLocalUInt32 ( NameServer_Handle  handle,
String  name,
Ptr  buf 
)

Gets a 32-bit value by name from the local table.

If the name is found, the 32-bit value is copied into buf and NameServer_S_SUCCESS is returned.

If the name is not found, zero is copied into buf and NameServer_E_NOTFOUND is returned.

This function only searches the local name/value table.

Parameters
handleInstance handle
nameName to query
bufPointer where the value is returned
Returns
Status
See also
NameServer_addUInt32()
NameServer_getUInt32()
Int NameServer_remove ( NameServer_Handle  handle,
String  name 
)

Remove a name/value pair from the table.

This function removes a name/value pair from the table.

If NameServer_Params.maxRuntimeEntries is set to NameServer_ALLOWGROWTH, memory will be freed which was allocated in NameServer_add(). Otherwise, no memory is freed during this call. The entry in the table is simply emptied. When another NameServer_add() occurs, it will reuse the empty entry.

Parameters
handleInstance handle
nameName to remove
Returns
Status
See also
NameServer_add
Int NameServer_removeEntry ( NameServer_Handle  handle,
Ptr  entry 
)

Remove a name/value pair from the table.

This function removes an entry from the table based on the unique identifier returned from NameServer_add() or NameServer_addUInt32().

If NameServer_Params::maxRuntimeEntries is set to NameServer_ALLOWGROWTH, memory will be freed which was allocated in NameServer_add(). Otherwise, no memory is freed during this call. The entry in the table is simply emptied. When another NameServer_add() occurs, it will reuse the empty entry.

Once an entry is removed from the NameServer table, it cannot be removed again (just like you cannot free the same block of memory twice).

Parameters
handleInstance handle
entryPointer to entry to be removed
Returns
Status
See also
NameServer_add()
Copyright 2015, Texas Instruments Incorporated