module ti.sdo.utils.NameServer
index URL

Manages and serves names to remote/local processor

This module has a common header that can be found in the ti.ipc package. Application code should include the common header file (not the RTSC-generated one): 
#include <ti/ipc/NameServer.h>
The RTSC module must be used in the application's RTSC configuration file (.cfg) if runtime APIs will be used in the application: 
NameServer = xdc.useModule('ti.sdo.ipc.NameServer');
Documentation for all runtime APIs, instance configuration parameters, error codes macros and type definitions available to the application integrator can be found in the Doxygen documenation for the IPC product. However, the documentation presented on this page should be referred to for information specific to the RTSC module, such as module configuration, Errors, and Asserts.
C synopsis target-domain sourced in ti/sdo/utils/NameServer.xdc
#include <ti/sdo/utils/NameServer.h>
Functions
Bool 
NameServer_isRegistered// Determines if a remote driver is registered for the specified id(UInt16 procId);
Void
NameServer_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(NameServer_Params *params);
Int 
NameServer_registerRemoteDriver// Register the NameServer remote handle for the specified processor id(INameServerRemote_Handle handle, UInt16 procId);
Void 
NameServer_unregisterRemoteDriver// Unregister the NameServer remote handle for the specified processor id(UInt16 procId);
Functions common to all target instances
NameServer_handle// Convert this instance structure pointer into an instance handle, NameServer_Handle_label// The label associated with this instance object, NameServer_Handle_name// The name of this instance object, NameServer_Object_count// The number of statically-created instance objects, NameServer_Object_first// The handle of the first dynamically-created instance object, or NULL, NameServer_Object_get// The handle of the i-th statically-created instance object (array == NULL), NameServer_Object_heap// The heap used to allocate dynamically-created instance objects, NameServer_Object_next// The handle of the next dynamically-created instance object, or NULL, NameServer_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
NameServer_Module_getMask// Returns the diagnostics mask for this module, NameServer_Module_hasMask// Test whether this module has a diagnostics mask, NameServer_Module_heap// The heap from which this module allocates memory, NameServer_Module_id// Get this module's unique id, NameServer_Module_setMask// Set the diagnostics mask for this module, NameServer_Module_startupDone// Test if this module has completed startup
Defines
#define
NameServer_ALLOWGROWTH// Allow dynamic growth of the NameServer instance table (UInt)(~0)
Typedefs
typedef NameServer_Object *
NameServer_Handle// Client reference to an instance object;
typedef struct
NameServer_Object// Opaque internal representation of an instance object NameServer_Object;
typedef struct
NameServer_Params// Instance config-params structure ...
typedef struct
NameServer_Struct// Opaque client structure large enough to hold an instance object NameServer_Struct;
Constants
extern const Assert_Id 
NameServer_A_invalidLen// Assert raised when the name or value is too long;
extern const Assert_Id 
NameServer_A_invArgument// Assert raised when an argument is invalid;
extern const Error_Id 
NameServer_E_entryExists// Error raised when the name already exists in the instance Name/Value table;
extern const Error_Id 
NameServer_E_maxReached// Error raised if all the entries in the instance Name/Value table are taken;
 
 
const NameServer_ALLOWGROWTH
index URL

Allow dynamic growth of the NameServer instance table

C synopsis target-domain
#define NameServer_ALLOWGROWTH (UInt)(~0)
 
DETAILS
This value can be used to set the maxRuntimeEntries. This flag tells NameServer to allow dynamic growth of the table.
 
config NameServer_A_invArgument  // module-wide
index URL

Assert raised when an argument is invalid

C synopsis target-domain
extern const Assert_Id NameServer_A_invArgument;
 
 
config NameServer_A_invalidLen  // module-wide
index URL

Assert raised when the name or value is too long

C synopsis target-domain
extern const Assert_Id NameServer_A_invalidLen;
 
 
config NameServer_E_entryExists  // module-wide
index URL

Error raised when the name already exists in the instance Name/Value table

C synopsis target-domain
extern const Error_Id NameServer_E_entryExists;
 
 
config NameServer_E_maxReached  // module-wide
index URL

Error raised if all the entries in the instance Name/Value table are taken

C synopsis target-domain
extern const Error_Id NameServer_E_maxReached;
 
 
NameServer_isRegistered()  // module-wide
index URL

Determines if a remote driver is registered for the specified id

C synopsis target-domain
Bool NameServer_isRegistered(UInt16 procId);
 
ARGUMENTS
procId — The remote processor id.
 
NameServer_registerRemoteDriver()  // module-wide
index URL

Register the NameServer remote handle for the specified processor id

C synopsis target-domain
Int NameServer_registerRemoteDriver(INameServerRemote_Handle handle, UInt16 procId);
 
ARGUMENTS
handle — The handle for a NameServer remote driver instance.
procId — The remote processor id.
RETURNS
Returns Status_SUCCESS if successful or Status_FAIL if the processor id has already been set.
DETAILS
This function is used by NameServer remote driver to register themselves with NameServer. Only one remote driver can be registered with a remote processor. The API returns Status_FAIL if there is already a registered remote driver for the processor id.
 
NameServer_unregisterRemoteDriver()  // module-wide
index URL

Unregister the NameServer remote handle for the specified processor id

C synopsis target-domain
Void NameServer_unregisterRemoteDriver(UInt16 procId);
 
ARGUMENTS
procId — The remote processor id to unregister.
DETAILS
This function is used by NameServer Remote implementations to unregister themselves with NameServer.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId NameServer_Module_id();
// Get this module's unique id
 
Bool NameServer_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle NameServer_Module_heap();
// The heap from which this module allocates memory
 
Bool NameServer_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 NameServer_Module_getMask();
// Returns the diagnostics mask for this module
 
Void NameServer_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct NameServer_Object NameServer_Object;
// Opaque internal representation of an instance object
 
typedef NameServer_Object *NameServer_Handle;
// Client reference to an instance object
 
typedef struct NameServer_Struct NameServer_Struct;
// Opaque client structure large enough to hold an instance object
 
NameServer_Handle NameServer_handle(NameServer_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
NameServer_Struct *NameServer_struct(NameServer_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct NameServer_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Bool checkExisting;
    // Check if a name already exists in the name/value table
    UInt maxNameLen;
    // Length, in MAUs, of the name field in the table
    UInt maxRuntimeEntries;
    // Maximum number of name/value pairs that can be dynamically created
    UInt maxValueLen;
    // Length, in MAUs, of the value field in the table
    IHeap_Handle tableHeap;
    // Name/value table is allocated from this heap
} NameServer_Params;
 
Void NameServer_Params_init(NameServer_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config NameServer_checkExisting  // instance
index URL

Check if a name already exists in the name/value table

C synopsis target-domain
struct NameServer_Params {
      ...
    Bool checkExisting;
 
DETAILS
When a name/value pair is added during runtime, if this boolean is true, the table is searched to see if the name already exists. If it does, the name is not added and the E_entryExists error is raised.
If this flag is false, the table will not be checked to see if the name already exists. It will simply be added. This mode has better performance at the expense of potentially having non-unique names in the table.
This flag is used for runtime adds only. Adding non-unique names during configuration results in a build error.
 
config NameServer_maxNameLen  // instance
index URL

Length, in MAUs, of the name field in the table

C synopsis target-domain
struct NameServer_Params {
      ...
    UInt maxNameLen;
 
DETAILS
The maximum length of the name portion of the name/value pair. The length includes the null terminator ('\0').
 
config NameServer_maxRuntimeEntries  // instance
index URL

Maximum number of name/value pairs that can be dynamically created

C synopsis target-domain
struct NameServer_Params {
      ...
    UInt maxRuntimeEntries;
 
DETAILS
This parameter allows NameServer to pre-allocate memory. When NameServer_add or NameServer_addUInt32 is called, no memory allocation occurs.
If the number of pairs is not known at configuration time, set this value to ALLOWGROWTH. This instructs NameServer to grow the table as needed. NameServer will allocate memory from the tableHeap when a name/value pair is added.
The default is ALLOWGROWTH.
 
config NameServer_maxValueLen  // instance
index URL

Length, in MAUs, of the value field in the table

C synopsis target-domain
struct NameServer_Params {
      ...
    UInt maxValueLen;
 
DETAILS
Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32).
 
config NameServer_tableHeap  // instance
index URL

Name/value table is allocated from this heap

C synopsis target-domain
struct NameServer_Params {
      ...
    IHeap_Handle tableHeap;
 
DETAILS
The instance table and related buffers are allocated out of this heap during the dynamic create. This heap is also used to allocate new name/value pairs when ALLOWGROWTH for maxRuntimeEntries
The default is to use the same heap that instances are allocated from which can be configured via the NameServer.common$.instanceHeap configuration parameter.
Instance Built-Ins
index URL

C synopsis target-domain
Int NameServer_Object_count();
// The number of statically-created instance objects
 
NameServer_Handle NameServer_Object_get(NameServer_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
NameServer_Handle NameServer_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
NameServer_Handle NameServer_Object_next(NameServer_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle NameServer_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *NameServer_Handle_label(NameServer_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String NameServer_Handle_name(NameServer_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/utils/NameServer.xdc
var NameServer = xdc.useModule('ti.sdo.utils.NameServer');
local proxy modules
    NameServer.SetupProxy// NameServer setup proxy = INameServerRemote.Module null
        NameServer.SetupProxy.delegate$ = INameServerRemote.Module null
        NameServer.SetupProxy.abstractInstances$ = false
module-wide constants & types
    const NameServer.ALLOWGROWTH// Allow dynamic growth of the NameServer instance table = (~0);
 
    var obj = new NameServer.Entry// Structure of entry in Name/Value table;
        obj.name = String  ...
        obj.len = UInt  ...
        obj.value = UArg  ...
module-wide config parameters
    NameServer.A_invArgument// Assert raised when an argument is invalid = Assert.Desc {
        msg: "A_invArgument: Invalid argument supplied"
    };
    NameServer.A_invalidLen// Assert raised when the name or value is too long = Assert.Desc {
        msg: "A_invalidLen: Invalid length"
    };
    NameServer.E_entryExists// Error raised when the name already exists in the instance Name/Value table = Error.Desc {
        msg: "E_entryExists: %s name already in table "
    };
    NameServer.E_maxReached// Error raised if all the entries in the instance Name/Value table are taken = Error.Desc {
        msg: "E_maxReached: All entries in use. NameServer.maxRuntimeEntries is %d"
    };
 
    NameServer.common$// Common module configuration parameters = Types.Common$ undefined;
module-wide functions
    NameServer.modAddMeta// Add a name/value pair into the specified instance's table during configuration(String instName, String name, Any value, UInt len) returns Void
per-instance config parameters
    var params = new NameServer.Params// Instance config-params object;
        params.checkExisting// Check if a name already exists in the name/value table = Bool true;
        params.maxNameLen// Length, in MAUs, of the name field in the table = UInt 16;
        params.maxRuntimeEntries// Maximum number of name/value pairs that can be dynamically created = UInt NameServer.ALLOWGROWTH;
        params.maxValueLen// Length, in MAUs, of the value field in the table = UInt 0;
        params.tableHeap// Name/value table is allocated from this heap = IHeap.Handle null;
        params.tableSection// Name/value table is placed into this section on static creates = String null;
per-instance functions
    inst.addMeta// Add a name/value pair into the instance's table during configuration(String name, Any value, UInt len) returns Void
    inst.addUInt32Meta// Add a name/value pair into the instance's table during configuration(String name, Any value) returns Void
    inst.getMeta// Retrieves the name/value entry(String name) returns NameServer.Entry
 
 
proxy NameServer.SetupProxy
index URL

NameServer setup proxy

XDCscript usage meta-domain
NameServer.SetupProxy = INameServerRemote.Module null
// some delegate module inheriting the INameServerRemote interface
    NameServer.SetupProxy.delegate$ = INameServerRemote.Module null
    // explicit access to the currently bound delegate module
    NameServer.SetupProxy.abstractInstances$ = false
    // use indirect runtime function calls if true
 
 
const NameServer.ALLOWGROWTH
index URL

Allow dynamic growth of the NameServer instance table

XDCscript usage meta-domain
const NameServer.ALLOWGROWTH = (~0);
 
DETAILS
This value can be used to set the maxRuntimeEntries. This flag tells NameServer to allow dynamic growth of the table.
C SYNOPSIS
NameServer_ALLOWGROWTH
 
metaonly struct NameServer.Entry
index URL

Structure of entry in Name/Value table

XDCscript usage meta-domain
var obj = new NameServer.Entry;
 
    obj.name = String  ...
    obj.len = UInt  ...
    obj.value = UArg  ...
 
FIELDS
name — Name portion of the name/value pair.
len — Length of the value field.
value — Value portion of the name/value entry.
DETAILS
This structure is returned from the getMeta API.
 
config NameServer.A_invArgument  // module-wide
index URL

Assert raised when an argument is invalid

XDCscript usage meta-domain
NameServer.A_invArgument = Assert.Desc {
    msg: "A_invArgument: Invalid argument supplied"
};
 
C SYNOPSIS
NameServer_A_invArgument
 
config NameServer.A_invalidLen  // module-wide
index URL

Assert raised when the name or value is too long

XDCscript usage meta-domain
NameServer.A_invalidLen = Assert.Desc {
    msg: "A_invalidLen: Invalid length"
};
 
C SYNOPSIS
NameServer_A_invalidLen
 
config NameServer.E_entryExists  // module-wide
index URL

Error raised when the name already exists in the instance Name/Value table

XDCscript usage meta-domain
NameServer.E_entryExists = Error.Desc {
    msg: "E_entryExists: %s name already in table "
};
 
C SYNOPSIS
NameServer_E_entryExists
 
config NameServer.E_maxReached  // module-wide
index URL

Error raised if all the entries in the instance Name/Value table are taken

XDCscript usage meta-domain
NameServer.E_maxReached = Error.Desc {
    msg: "E_maxReached: All entries in use. NameServer.maxRuntimeEntries is %d"
};
 
C SYNOPSIS
NameServer_E_maxReached
 
metaonly config NameServer.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
NameServer.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
 
metaonly NameServer.modAddMeta()  // module-wide
index URL

Add a name/value pair into the specified instance's table during configuration

XDCscript usage meta-domain
NameServer.modAddMeta(String instName, String name, Any value, UInt len) returns Void
 
ARGUMENTS
instName — NameServer instance name
name — Name portion of the name/value pair
value — Value portion of the name/value pair
len — Length of the value buffer
DETAILS
This function adds any length value into the local table. The function makes sure the name does not already exist in the local table.
This function should be used by modules when adding into a NameServer instance. The application configuration file, should use addMeta.
The function does not query remote processors to make sure the name is unique.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new NameServer.Params;
// Instance config-params object
    params.checkExisting = Bool true;
    // Check if a name already exists in the name/value table
    params.maxNameLen = UInt 16;
    // Length, in MAUs, of the name field in the table
    params.maxRuntimeEntries = UInt NameServer.ALLOWGROWTH;
    // Maximum number of name/value pairs that can be dynamically created
    params.maxValueLen = UInt 0;
    // Length, in MAUs, of the value field in the table
    params.tableHeap = IHeap.Handle null;
    // Name/value table is allocated from this heap
    params.tableSection = String null;
    // Name/value table is placed into this section on static creates
 
config NameServer.checkExisting  // instance
index URL

Check if a name already exists in the name/value table

XDCscript usage meta-domain
var params = new NameServer.Params;
  ...
params.checkExisting = Bool true;
 
DETAILS
When a name/value pair is added during runtime, if this boolean is true, the table is searched to see if the name already exists. If it does, the name is not added and the E_entryExists error is raised.
If this flag is false, the table will not be checked to see if the name already exists. It will simply be added. This mode has better performance at the expense of potentially having non-unique names in the table.
This flag is used for runtime adds only. Adding non-unique names during configuration results in a build error.
C SYNOPSIS
null
 
config NameServer.maxNameLen  // instance
index URL

Length, in MAUs, of the name field in the table

XDCscript usage meta-domain
var params = new NameServer.Params;
  ...
params.maxNameLen = UInt 16;
 
DETAILS
The maximum length of the name portion of the name/value pair. The length includes the null terminator ('\0').
C SYNOPSIS
null
 
config NameServer.maxRuntimeEntries  // instance
index URL

Maximum number of name/value pairs that can be dynamically created

XDCscript usage meta-domain
var params = new NameServer.Params;
  ...
params.maxRuntimeEntries = UInt NameServer.ALLOWGROWTH;
 
DETAILS
This parameter allows NameServer to pre-allocate memory. When NameServer_add or NameServer_addUInt32 is called, no memory allocation occurs.
If the number of pairs is not known at configuration time, set this value to ALLOWGROWTH. This instructs NameServer to grow the table as needed. NameServer will allocate memory from the tableHeap when a name/value pair is added.
The default is ALLOWGROWTH.
C SYNOPSIS
null
 
config NameServer.maxValueLen  // instance
index URL

Length, in MAUs, of the value field in the table

XDCscript usage meta-domain
var params = new NameServer.Params;
  ...
params.maxValueLen = UInt 0;
 
DETAILS
Any value less than sizeof(UInt32) will be rounded up to sizeof(UInt32).
C SYNOPSIS
null
 
config NameServer.tableHeap  // instance
index URL

Name/value table is allocated from this heap

XDCscript usage meta-domain
var params = new NameServer.Params;
  ...
params.tableHeap = IHeap.Handle null;
 
DETAILS
The instance table and related buffers are allocated out of this heap during the dynamic create. This heap is also used to allocate new name/value pairs when ALLOWGROWTH for maxRuntimeEntries
The default is to use the same heap that instances are allocated from which can be configured via the NameServer.common$.instanceHeap configuration parameter.
C SYNOPSIS
null
 
metaonly config NameServer.tableSection  // instance
index URL

Name/value table is placed into this section on static creates

XDCscript usage meta-domain
var params = new NameServer.Params;
  ...
params.tableSection = String null;
 
DETAILS
The instance table and related buffers are placed into this section during the static create.
The default is no explicit section placement.
 
metaonly NameServer.addMeta()  // instance
index URL

Add a name/value pair into the instance's table during configuration

XDCscript usage meta-domain
inst.addMeta(String name, Any value, UInt len) returns Void
 
ARGUMENTS
name — Name portion of the name/value pair
value — Value portion of the name/value pair
len — Length of the value buffer
DETAILS
This function adds any length value into the local table. The function makes sure the name does not already exist in the local table.
This function should be used by within the application configuration file. XDC modules should use modAddMeta.
The function does not query remote processors to make sure the name is unique.
 
metaonly NameServer.addUInt32Meta()  // instance
index URL

Add a name/value pair into the instance's table during configuration

XDCscript usage meta-domain
inst.addUInt32Meta(String name, Any value) returns Void
 
ARGUMENTS
name — Name portion of the name/value pair
value — Value portion of the name/value pair
DETAILS
This function adds a UInt32 value into the local table. The function makes sure the name does not already exist in the local table.
The function does not query remote processors to make sure the name is unique.
 
metaonly NameServer.getMeta()  // instance
index URL

Retrieves the name/value entry

XDCscript usage meta-domain
inst.getMeta(String name) returns NameServer.Entry
 
ARGUMENTS
name — Name in question
RETURNS
Name/value entry
DETAILS
If the name is found, the entry is returned. The caller can parse the entry as needed. If the name is not found, null is returned.
The search only occurs on the local table.
generated on Sat, 11 Feb 2012 00:38:14 GMT