VxWorks API Reference : OS Libraries
smObjLib - shared memory objects library (VxMP Option)
smObjLibInit( ) - install the shared memory objects facility (VxMP Option)
smObjSetup( ) - initialize the shared memory objects facility (VxMP Option)
smObjInit( ) - initialize a shared memory objects descriptor (VxMP Option)
smObjAttach( ) - attach the calling CPU to the shared memory objects facility (VxMP Option)
smObjLocalToGlobal( ) - convert a local address to a global address (VxMP Option)
smObjGlobalToLocal( ) - convert a global address to a local address (VxMP Option)
smObjTimeoutLogEnable( ) - control logging of failed attempts to take a spin-lock (VxMP Option)
This library contains miscellaneous functions used by the shared memory objects facility (VxMP). Shared memory objects provide high-speed synchronization and communication among tasks running on separate CPUs that have access to a common shared memory. Shared memory objects are system objects (e.g., semaphores and message queues) that can be used across processors.
The main uses of shared memory objects are interprocessor synchronization, mutual exclusion on multiprocessor shared data structures, and high-speed data exchange.
Routines for displaying shared memory objects statistics are provided by the smObjShow module.
One CPU node acts as the shared memory objects master. This CPU initializes the shared memory area and sets up the shared memory anchor. These steps are performed by the master calling smObjSetup( ). This routine should be called only once by the master CPU. Usually smObjSetup( ) is called from usrSmObjInit( ). (See "Configuration" below.)
Once smObjSetup( ) has completed successfully, there is little functional difference between the master CPU and other CPUs using shared memory objects, except that the master is responsible for maintaining the heartbeat in the shared memory objects header.
Each CPU, master or non-master, that will use shared memory objects must attach itself to the shared memory objects facility, which must already be initialized.
Before it can attach to a shared memory region, each CPU must allocate and initialize a shared memory descriptor (SM_DESC), which describes the individual CPU's attachment to the shared memory objects facility. Since the shared memory descriptor is used only by the local CPU, it is not necessary for the descriptor itself to be located in shared memory. In fact, it is preferable for the descriptor to be allocated from the CPU's local memory, since local memory is usually more efficiently accessed.
The shared memory descriptor is initialized by calling smObjInit( ). This routine takes a number of parameters which specify the characteristics of the calling CPU and its access to shared memory.
Once the shared memory descriptor has been initialized, the CPU can attach itself to the shared memory region. This is done by calling smObjAttach( ).
When smObjAttach( ) is called, it verifies that the shared memory anchor contains the value SM_READY and that the heartbeat located in the shared memory objects header is incrementing. If either of these conditions is not met, the routine will check periodically until either SM_READY or an incrementing heartbeat is recognized or a time limit is reached. The limit is expressed in seconds, and 600 seconds (10 minutes) is the default. If the time limit is reached before SM_READY or a heartbeat is found, ERROR is returned and errno is set to S_smLib_DOWN .
This library also provides routines for converting between local and global shared memory addresses, smObjLocalToGlobal( ) and smObjGlobalToLocal( ). A local shared memory address is the address required by the local CPU to reach a location in shared memory. A global shared memory address is a value common to all CPUs in the system used to reference a shared memory location. A global shared memory address is always an offset from the shared memory anchor.
The shared memory objects facilities use a spin-lock mechanism based on an indivisible read-modify-write (RMW) operation on a shared memory location which acts as a low-level mutual exclusion device. The spin-lock mechanism is called with a system-wide configuration parameter, SM_OBJ_MAX_TRIES, which specifies the maximum number of RMW tries on a spin-lock location.
Care must be taken that the number of RMW tries on a spin-lock on a particular CPU never reaches SM_OBJ_MAX_TRIES, otherwise system behavior becomes unpredictable. The default value should be sufficient for reliable operation.
The routine smObjTimeoutLogEnable( ) can be used to enable or disable the printing of a message should a shared memory object call fail while trying to take a spin-lock.
Shared memory objects and the shared memory network (backplane) driver use common underlying shared memory utilities. They also use the same anchor, the same shared memory header, and the same interrupt when they are used at the same time.
A maximum of twenty CPUs can be used concurrently with shared memory objects. Each CPU in the system must have a hardware test-and-set (TAS) mechanism, which is called via the system-dependent routine sysBusTas( ).
The use of shared memory objects raises interrupt latency, because internal mechanisms lock interrupts while manipulating critical shared data structures. Interrupt latency does not depend on the number of objects or CPUs used.
The routine smObjShow( ) displays useful information regarding the current status of shared memory objects, including the number of tasks using shared objects, shared semaphores, and shared message queues, the number of names in the database, and also the maximum number of tries to get spin-lock access for the calling CPU.
When the component INCLUDE_SM_OBJ is included, the init and setup routines in this library are called automatically during VxWorks initialization.
This module is distributed as a component of the unbundled shared memory objects support option, VxMP.
smObjLib.h
smObjShow, semSmLib, msgQSmLib, smMemLib, smNameLib, usrSmObjInit( ), VxWorks Programmer's Guide: Shared Memory Objects
smObjLibInit( ) - install the shared memory objects facility (VxMP Option)
STATUS smObjLibInit (void)
This routine installs the shared memory objects facility. It is called automatically when the component INCLUDE_SM_OBJ is included.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if the shared memory objects facility has already been installed.
smObjSetup( ) - initialize the shared memory objects facility (VxMP Option)
STATUS smObjSetup ( SM_OBJ_PARAMS * smObjParams /* setup parameters */ )
This routine initializes the shared memory objects facility by filling the shared memory header. It must be called only once by the shared memory master CPU. It is called automatically only by the master CPU, when the component INCLUDE_SM_OBJ is included.
Any CPU on the system backplane can use the shared memory objects facility; however, the facility must first be initialized on the master CPU. Then before other CPUs are attached to the shared memory area by smObjAttach( ), each must initialize its own shared memory objects descriptor using smObjInit( ). This mechanism is similar to the one used by the shared memory network driver.
The smObjParams parameter is a pointer to a structure containing the values used to describe the shared memory objects setup. This structure is defined as follows in smObjLib.h:
typedef struct sm_obj_params /* setup parameters */ { BOOL allocatedPool; /* TRUE if shared memory pool is malloced */ SM_ANCHOR * pAnchor; /* shared memory anchor */ char * smObjFreeAdrs; /* start address of shared memory pool */ int smObjMemSize; /* memory size reserved for shared memory */ int maxCpus; /* max number of CPUs in the system */ int maxTasks; /* max number of tasks using smObj */ int maxSems; /* max number of shared semaphores */ int maxMsgQueues; /* max number of shared message queues */ int maxMemParts; /* max number of shared memory partitions */ int maxNames; /* max number of names of shared objects */ } SM_OBJ_PARAMS;
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if the shared memory pool cannot hold all the requested objects or the number of CPUs exceeds the maximum.
S_smObjLib_TOO_MANY_CPU
S_smObjLib_SHARED_MEM_TOO_SMALL
smObjLib, smObjInit( ), smObjAttach( )
smObjInit( ) - initialize a shared memory objects descriptor (VxMP Option)
void smObjInit ( SM_OBJ_DESC * pSmObjDesc, /* ptr to shared memory descriptor */ SM_ANCHOR * anchorLocalAdrs, /* shared memory anchor local adrs */ int ticksPerBeat, /* cpu ticks per heartbeat */ int smObjMaxTries, /* max no. of tries to obtain spinLock */ int intType, /* interrupt method */ int intArg1, /* interrupt argument #1 */ int intArg2, /* interrupt argument #2 */ int intArg3 /* interrupt argument #3 */ )
This routine initializes a shared memory descriptor. The descriptor must already be allocated in the CPU's local memory. Once the descriptor has been initialized by this routine, the CPU may attach itself to the shared memory area by calling smObjAttach( ).
This routine is called automatically when the component INCLUDE_SM_OBJ is included.
Only the shared memory descriptor itself is modified by this routine. No structures in shared memory are affected.
Parameters:
- pSmObjDesc
- The address of the shared memory descriptor to be initialized; this structure must be allocated before smObjInit( ) is called.
- anchorLocalAdrs
- The memory address by which the local CPU may access the shared memory anchor. This address may vary among CPUs in the system because of address offsets (particularly if the anchor is located in one CPU's dual-ported memory).
- ticksPerBeat
- Specifies the frequency of the shared memory anchor's heartbeat. The frequency is expressed in terms of how many CPU ticks on the local CPU correspond to one heartbeat period.
- smObjMaxTries
- Specifies the maximum number of tries to obtain access to an internal mutually exclusive data structure.
- intType, intArg1, intArg2, intArg3
- Allow a CPU to announce the method by which it is to be notified of shared memory events. See the manual entry for if_sm for a discussion about interrupt types and their associated parameters.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
N/A
smObjLib, smObjSetup( ), smObjAttach( )
smObjAttach( ) - attach the calling CPU to the shared memory objects facility (VxMP Option)
STATUS smObjAttach ( SM_OBJ_DESC * pSmObjDesc /* pointer to shared memory descriptor */ )
This routine "attaches" the calling CPU to the shared memory objects facility. The shared memory area is identified by the shared memory descriptor with an address specified by pSmObjDesc. The descriptor must already have been initialized by calling smObjInit( ).
This routine is called automatically when the component INCLUDE_SM_OBJ is included.
This routine will complete the attach process only if and when the shared memory has been initialized by the master CPU. If the shared memory is not recognized as active within the timeout period (10 minutes), this routine returns ERROR.
The smObjAttach( ) routine connects the shared memory objects handler to the shared memory interrupt. Note that this interrupt may be shared between the shared memory network driver and the shared memory objects facility when both are used at the same time.
Once a CPU has attached itself to the shared memory objects facility, it cannot be detached. Since the shared memory network driver and the shared memory objects facility use the same low-level attaching mechanism, a CPU cannot be detached from a shared memory network driver if the CPU also uses shared memory objects.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if the shared memory objects facility is not active or the number of CPUs exceeds the maximum.
S_smLib_INVALID_CPU_NUMBER
smObjLib, smObjSetup( ), smObjInit( )
smObjLocalToGlobal( ) - convert a local address to a global address (VxMP Option)
void * smObjLocalToGlobal ( void * localAdrs /* local address to convert */ )
This routine converts a local shared memory address localAdrs to its corresponding global value. This routine does not verify that localAdrs is really a valid local shared memory address.
All addresses stored in shared memory are global. Any access made to shared memory by the local CPU must be done using local addresses. This routine and smObjGlobalToLocal( ) are used to convert between these address types.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
The global shared memory address pointed to by localAdrs.
smObjLib, smObjGlobalToLocal( )
smObjGlobalToLocal( ) - convert a global address to a local address (VxMP Option)
void * smObjGlobalToLocal ( void * globalAdrs /* global address to convert */ )
This routine converts a global shared memory address globalAdrs to its corresponding local value. This routine does not verify that globalAdrs is really a valid global shared memory address.
All addresses stored in shared memory are global. Any access made to shared memory by the local CPU must be done using local addresses. This routine and smObjLocalToGlobal( ) are used to convert between these address types.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
The local shared memory address pointed to by globalAdrs.
smObjLib, smObjLocalToGlobal( )
smObjTimeoutLogEnable( ) - control logging of failed attempts to take a spin-lock (VxMP Option)
void smObjTimeoutLogEnable ( BOOL timeoutLogEnable /* TRUE to enable, FALSE to disable */ )
This routine enables or disables the printing of a message when an attempt to take a shared memory spin-lock fails.
By default, message logging is enabled.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
N/A