VxWorks Reference Manual : Libraries
smMemLib - shared memory management library (VxMP Option)
memPartSmCreate( ) - create a shared memory partition (VxMP Option)
smMemAddToPool( ) - add memory to the shared memory system partition (VxMP Option)
smMemOptionsSet( ) - set the debug options for the shared memory system partition (VxMP Option)
smMemMalloc( ) - allocate a block of memory from the shared memory system partition (VxMP Option)
smMemCalloc( ) - allocate memory for an array from the shared memory system partition (VxMP Option)
smMemRealloc( ) - reallocate a block of memory from the shared memory system partition (VxMP Option)
smMemFree( ) - free a shared memory system partition block of memory (VxMP Option)
smMemFindMax( ) - find the largest free block in the shared memory system partition (VxMP Option)
This library provides facilities for managing the allocation of blocks of shared memory from ranges of memory called shared memory partitions. The routine memPartSmCreate( ) is used to create shared memory partitions in the shared memory pool. The created partition can be manipulated using the generic memory partition calls, memPartAlloc( ), memPartFree( ), etc. (for a complete list of these routines, see the manual entry for memPartLib). The maximum number of partitions that can be created is SM_OBJ_MAX_MEM_PART, defined in the configuration header file.
The smMem...( ) routines provide an easy-to-use interface to the shared memory system partition. The shared memory system partition is created when the shared memory object facility is initialized.
Shared memory management information and statistics display routines are provided by smMemShow.
The allocation of memory, using memPartAlloc( ) in the general case and smMemMalloc( ) for the shared memory system partition, is done with a first-fit algorithm. Adjacent blocks of memory are coalesced when freed using memPartFree( ) and smMemFree( ).
There is a 28-byte overhead per allocated block, and allocated blocks are aligned on a 16-byte boundary.
All memory used by the shared memory facility must be in the same address space, that is, it must be reachable from all the CPUs with the same offset as the one used for the shared memory anchor.
Before routines in this library can be called, the shared memory objects facility must be initialized by a call to 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.
Various debug options can be selected for each partition using memPartOptionsSet( ) and smMemOptionsSet( ). Two kinds of errors are detected: attempts to allocate more memory than is available, and bad blocks found when memory is freed. In both cases, options can be selected for system actions to take place when the error is detected: (1) return the error status, (2) log an error message and return the error status, or (3) log an error message and suspend the calling task.
One of the following options can be specified to determine the action to be taken when there is an attempt to allocate more memory than is available in the partition:
- MEM_ALLOC_ERROR_RETURN
- just return the error status to the calling task.
- MEM_ALLOC_ERROR_LOG_MSG
- log an error message and return the status to the calling task.
- MEM_ALLOC_ERROR_LOG_AND_SUSPEND
- log an error message and suspend the calling task.
The following option can be specified to check every block freed to the partition. If this option is specified, memPartFree( ) and smMemFree( ) will make a consistency check of various pointers and values in the header of the block being freed.
- MEM_BLOCK_CHECK
- check each block freed.
One of the following options can be specified to determine the action to be taken when a bad block is detected when freed. These options apply only if the MEM_BLOCK_CHECK option is selected.
- MEM_BLOCK_ERROR_RETURN
- just return the status to the calling task.
- MEM_BLOCK_ERROR_LOG_MSG
- log an error message and return the status to the calling task.
- MEM_BLOCK_ERROR_LOG_AND_SUSPEND
- log an error message and suspend the calling task.
The default option when a shared partition is created is MEM_ALLOC_ERROR_LOG_MSG.
When setting options for a partition with memPartOptionsSet( ) or smMemOptionsSet( ), use the logical OR operator between each specified option to construct the options parameter. For example:
memPartOptionsSet (myPartId, MEM_ALLOC_ERROR_LOG_MSG | MEM_BLOCK_CHECK | MEM_BLOCK_ERROR_LOG_MSG);
This module is distributed as a component of the unbundled shared memory objects support option, VxMP.
smMemLib.h
smMemShow, memLib, memPartLib, smObjLib, usrSmObjInit( ), VxWorks Programmer's Guide: Shared Memory Objects
memPartSmCreate( ) - create a shared memory partition (VxMP Option)
PART_ID memPartSmCreate ( char * pPool, /* global address of shared memory area */ unsigned poolSize /* size in bytes */ )
This routine creates a shared memory partition that can be used by tasks on all CPUs in the system. It returns a partition ID which can then be passed to generic memPartLib routines to manage the partition (i.e., to allocate and free memory blocks in the partition).
pPool is the global address of shared memory dedicated to the partition. The memory area pointed to by pPool must be in the same address space as the shared memory anchor and shared memory pool.
poolSize is the size in bytes of shared memory dedicated to the partition.
Before this routine can be called, the shared memory objects facility must be initialized (see smMemLib).
The descriptor for the new partition is allocated out of an internal dedicated shared memory partition. The maximum number of partitions that can be created is SM_OBJ_MAX_MEM_PART.
Memory pool size is rounded down to a 16-byte boundary.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
The partition ID, or NULL if there is insufficient memory in the dedicated partition for a new partition descriptor.
S_memLib_NOT_ENOUGH_MEMORY
S_smObjLib_LOCK_TIMEOUT
smMemAddToPool( ) - add memory to the shared memory system partition (VxMP Option)
STATUS smMemAddToPool ( char * pPool, /* pointer to memory pool */ unsigned poolSize /* block size in bytes */ )
This routine adds memory to the shared memory system partition after the initial allocation of memory. The memory added need not be contiguous with memory previously assigned, but it must be in the same address space.
pPool is the global address of shared memory added to the partition. The memory area pointed to by pPool must be in the same address space as the shared memory anchor and shared memory pool.
poolSize is the size in bytes of shared memory added to the partition.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if access to the shared memory system partition fails.
S_smObjLib_LOCK_TIMEOUT
smMemOptionsSet( ) - set the debug options for the shared memory system partition (VxMP Option)
STATUS smMemOptionsSet ( unsigned options /* options for system partition */ )
This routine sets the debug options for the shared system memory partition. Two kinds of errors are detected: attempts to allocate more memory than is available, and bad blocks found when memory is freed or reallocated. In both cases, the following options can be selected for actions to be taken when an error is detected: (1) return the error status, (2) log an error message and return the error status, or (3) log an error message and suspend the calling task. These options are discussed in detail in the library manual entry for smMemLib.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK or ERROR.
S_smObjLib_LOCK_TIMEOUT
smMemMalloc( ) - allocate a block of memory from the shared memory system partition (VxMP Option)
void * smMemMalloc ( unsigned nBytes /* number of bytes to allocate */ )
This routine allocates a block of memory from the shared memory system partition whose size is equal to or greater than nBytes. The return value is the local address of the allocated shared memory block.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
A pointer to the block, or NULL if the memory cannot be allocated.
S_memLib_NOT_ENOUGH_MEMORY
S_smObjLib_LOCK_TIMEOUT
smMemCalloc( ) - allocate memory for an array from the shared memory system partition (VxMP Option)
void * smMemCalloc ( int elemNum, /* number of elements */ int elemSize /* size of elements */ )
This routine allocates a block of memory for an array that contains elemNum elements of size elemSize from the shared memory system partition. The return value is the local address of the allocated shared memory block.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
A pointer to the block, or NULL if the memory cannot be allocated.
S_memLib_NOT_ENOUGH_MEMORY
S_smObjLib_LOCK_TIMEOUT
smMemRealloc( ) - reallocate a block of memory from the shared memory system partition (VxMP Option)
void * smMemRealloc ( void * pBlock, /* block to be reallocated */ unsigned newSize /* new block size */ )
This routine changes the size of a specified block and returns a pointer to the new block of shared memory. The contents that fit inside the new size (or old size, if smaller) remain unchanged. The return value is the local address of the reallocated shared memory block.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
A pointer to the new block of memory, or NULL if the reallocation cannot be completed.
S_memLib_NOT_ENOUGH_MEMORY
S_memLib_BLOCK_ERROR
S_smObjLib_LOCK_TIMEOUT
smMemFree( ) - free a shared memory system partition block of memory (VxMP Option)
STATUS smMemFree ( void * ptr /* pointer to block of memory to be freed */ )
This routine takes a block of memory previously allocated with smMemMalloc( ) or smMemCalloc( ) and returns it to the free shared memory system pool.
It is an error to free a block of memory that was not previously allocated.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
OK, or ERROR if the block is invalid.
S_memLib_BLOCK_ERROR
S_smObjLib_LOCK_TIMEOUT
smMemLib, smMemMalloc( ), smMemCalloc( )
smMemFindMax( ) - find the largest free block in the shared memory system partition (VxMP Option)
int smMemFindMax (void)
This routine searches for the largest block in the shared memory system partition free list and returns its size.
This routine is distributed as a component of the unbundled shared memory objects support option, VxMP.
The size (in bytes) of the largest available block, or ERROR if the attempt to access the partition fails.
S_smObjLib_LOCK_TIMEOUT