VxWorks Reference Manual : Libraries
smNameLib - shared memory objects name database library (VxMP Option)
smNameAdd( ) - add a name to the shared memory name database (VxMP Option)
smNameFind( ) - look up a shared memory object by name (VxMP Option)
smNameFindByValue( ) - look up a shared memory object by value (VxMP Option)
smNameRemove( ) - remove an object from the shared memory objects name database (VxMP Option)
This library provides facilities for managing the shared memory objects name database. The shared memory objects name database associates a name and object type with a value and makes that information available to all CPUs. A name is an arbitrary, null-terminated string. An object type is a small integer, and its value is a global (shared) ID or a global shared memory address.
Names are added to the shared memory name database with smNameAdd( ). They are removed by smNameRemove( ).
Objects in the database can be accessed by either name or value. The routine smNameFind( ) searches the shared memory name database for an object of a specified name. The routine smNameFindByValue( ) searches the shared memory name database for an object of a specified identifier or address.
Name database contents can be viewed using smNameShow( ).
The maximum number of names to be entered in the database is SM_OBJ_MAX_NAME, defined in the configuration header file. This value is used to determine the size of a dedicated shared memory partition from which name database fields are allocated.
The estimated memory size required for the name database can be calculated as follows:
name database pool size = SM_OBJ_MAX_NAME * 40 (bytes)The display facility for the shared memory objects name database is provided by smNameShow.
The following code fragment allows a task on one CPU to enter the name, associated ID, and type of a created shared semaphore into the name database. Note that CPU numbers can belong to any CPU using the shared memory objects facility.
On CPU 1 :
#include "vxWorks.h" #include "semLib.h" #include "smNameLib.h" #include "semSmLib.h" #include "stdio.h" testSmSem1 (void) { SEM_ID smSemId; /* create a shared semaphore */ if ((smSemId = semBSmCreate(SEM_Q_FIFO, SEM_EMPTY)) == NULL) { printf ("Shared semaphore creation error."); return (ERROR); } /* * make created semaphore Id available to all CPUs in * the system by entering its name in shared name database. */ if (smNameAdd ("smSem", smSemId, T_SM_SEM_B) != OK ) { printf ("Cannot add smSem into shared database."); return (ERROR); } ... /* now use the semaphore */ semGive (smSemId); ... }On CPU 2 :#include "vxWorks.h" #include "semLib.h" #include "smNameLib.h" #include "stdio.h" testSmSem2 (void) { SEM_ID smSemId; int objType; /* place holder for smNameFind() object type */ /* get semaphore ID from name database */ smNameFind ("smSem", (void **) &smSemId, &objType, WAIT_FOREVER); ... /* now that we have the shared semaphore ID, take it */ semTake (smSemId, WAIT_FOREVER); ... }
Before routines in this library can be called, the shared memory object facility must be initialized by calling usrSmObjInit( ), which is found in src/config/usrSmObj.c. This is done automatically from the root task, usrRoot( ), in usrConfig.c when the configuration macro INCLUDE_SM_OBJ is defined.
This module is distributed as a component of the unbundled shared memory objects support option, VxMP.
smNameLib.h
smNameLib, smNameShow, smObjLib, smObjShow, usrSmObjInit( ), VxWorks Programmer's Guide: Shared Memory Objects
smNameAdd( ) - add a name to the shared memory name database (VxMP Option)
STATUS smNameAdd ( char * name, /* name string to enter in database */ void * value, /* value associated with name */ int type /* type associated with name */ )
This routine adds a name of specified object type and value to the shared memory objects name database.
The name parameter is an arbitrary null-terminated string with a maximum of 20 characters, including EOS.
By convention, type values of less than 0x1000 are reserved by VxWorks; all other values are user definable. The following types are predefined in smNameLib.h :
A name can be entered only once in the database, but there can be more than one name associated with an object ID.
T_SM_SEM_B 0 shared binary semaphore T_SM_SEM_C 1 shared counting semaphore T_SM_MSG_Q 2 shared message queue T_SM_PART_ID 3 shared memory Partition T_SM_BLOCK 4 shared memory allocated block
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if there is insufficient memory for name to be allocated, if name is already in the database, or if the database is already full.
S_smNameLib_NOT_INITIALIZED
S_smNameLib_NAME_TOO_LONG
S_smNameLib_NAME_ALREADY_EXIST
S_smNameLib_DATABASE_FULL
S_smObjLib_LOCK_TIMEOUT
smNameFind( ) - look up a shared memory object by name (VxMP Option)
STATUS smNameFind ( char * name, /* name to search for */ void * * pValue, /* pointer where to return value */ int * pType, /* pointer where to return object type */ int waitType /* NO_WAIT or WAIT_FOREVER */ )
This routine searches the shared memory objects name database for an object matching a specified name. If the object is found, its value and type are copied to the addresses pointed to by pValue and pType. The value of waitType can be one of the following:
- NO_WAIT (0)
- The call returns immediately, even if name is not in the database.
- WAIT_FOREVER (-1)
- The call returns only when name is available in the database. If name is not already in, the database is scanned periodically as the routine waits for name to be entered.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if the object is not found, if name is too long, or the wait type is invalid.
S_smNameLib_NOT_INITIALIZED
S_smNameLib_NAME_TOO_LONG
S_smNameLib_NAME_NOT_FOUND
S_smNameLib_INVALID_WAIT_TYPE
S_smObjLib_LOCK_TIMEOUT
smNameFindByValue( ) - look up a shared memory object by value (VxMP Option)
STATUS smNameFindByValue ( void * value, /* value to search for */ char * name, /* pointer where to return name */ int * pType, /* pointer where to return object type */ int waitType /* NO_WAIT or WAIT_FOREVER */ )
This routine searches the shared memory name database for an object matching a specified value. If the object is found, its name and type are copied to the addresses pointed to by name and pType. The value of waitType can be one of the following:
- NO_WAIT (0)
- The call returns immediately, even if the object value is not in the database.
- WAIT_FOREVER (-1)
- The call returns only when the object value is available in the database.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if value is not found or if the wait type is invalid.
S_smNameLib_NOT_INITIALIZED
S_smNameLib_VALUE_NOT_FOUND
S_smNameLib_INVALID_WAIT_TYPE
S_smObjLib_LOCK_TIMEOUT
smNameRemove( ) - remove an object from the shared memory objects name database (VxMP Option)
STATUS smNameRemove ( char * name /* name of object to remove */ )
This routine removes an object called name from the shared memory objects name database.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if the object name is not in the database or if name is too long.
S_smNameLib_NOT_INITIALIZED
S_smNameLib_NAME_TOO_LONG
S_smNameLib_NAME_NOT_FOUND
S_smObjLib_LOCK_TIMEOUT