VxWorks Reference Manual : Libraries
memLib - full-featured memory partition manager
memPartOptionsSet( ) - set the debug options for a memory partition
memalign( ) - allocate aligned memory
valloc( ) - allocate memory on a page boundary
memPartRealloc( ) - reallocate a block of memory in a specified partition
memPartFindMax( ) - find the size of the largest available free block
memOptionsSet( ) - set the debug options for the system memory partition
calloc( ) - allocate space for an array (ANSI)
realloc( ) - reallocate a block of memory (ANSI)
cfree( ) - free a block of memory
memFindMax( ) - find the largest free block in the system memory partition
This library provides full-featured facilities for managing the allocation of blocks of memory from ranges of memory called memory partitions. The library is an extension of memPartLib and provides enhanced memory management features, including error handling, aligned allocation, and ANSI allocation routines. For more information about the core memory partition management facility, see the manual entry for memPartLib.
The system memory partition is created when the kernel is initialized by kernelInit( ), which is called by the root task, usrRoot( ), in usrConfig.c. The ID of the system memory partition is stored in the global variable memSysPartId; its declaration is included in memLib.h.
The memalign( ) routine is provided for allocating memory aligned to a specified boundary.
This library includes three ANSI-compatible routines: calloc( ) allocates a block of memory for an array; realloc( ) changes the size of a specified block of memory; and cfree( ) returns to the free memory pool a block of memory that was previously allocated with calloc( ).
Various debug options can be selected for each partition using memPartOptionsSet( ) and memOptionsSet( ). 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, the error status is returned. There are four error-handling options that can be individually selected:
- MEM_ALLOC_ERROR_LOG_FLAG
- Log a message when there is an error in allocating memory.
- MEM_ALLOC_ERROR_SUSPEND_FLAG
- Suspend the task when there is an error in allocating memory (unless the task was spawned with the VX_UNBREAKABLE option, in which case it cannot be suspended).
- MEM_BLOCK_ERROR_LOG_FLAG
- Log a message when there is an error in freeing memory.
- MEM_BLOCK_ERROR_SUSPEND_FLAG
- Suspend the task when there is an error in freeing memory (unless the task was spawned with the VX_UNBREAKABLE option, in which case it cannot be suspended).
When the following option is specified to check every block freed to the partition, memPartFree( ) and free( ) in memPartLib run consistency checks of various pointers and values in the header of the block being freed. If this flag is not specified, no check will be performed when memory is freed.
- MEM_BLOCK_CHECK
- Check each block freed.
Setting either of the MEM_BLOCK_ERROR options automatically sets MEM_BLOCK_CHECK.
The default options when a partition is created are:
MEM_ALLOC_ERROR_LOG_FLAG
MEM_BLOCK_CHECK
MEM_BLOCK_ERROR_LOG_FLAG
MEM_BLOCK_ERROR_SUSPEND_FLAGWhen setting options for a partition with memPartOptionsSet( ) or memOptionsSet( ), use the logical OR operator between each specified option to construct the options parameter. For example:
memPartOptionsSet (myPartId, MEM_ALLOC_ERROR_LOG_FLAG | MEM_BLOCK_CHECK | MEM_BLOCK_ERROR_LOG_FLAG);
memLib.h
memPartOptionsSet( ) - set the debug options for a memory partition
STATUS memPartOptionsSet ( PART_ID partId, /* partition to set option for */ unsigned options /* memory management options */ )
This routine sets the debug options for a specified memory partition. 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, the error status is returned. There are four error-handling options that can be individually selected:
- MEM_ALLOC_ERROR_LOG_FLAG
- Log a message when there is an error in allocating memory.
- MEM_ALLOC_ERROR_SUSPEND_FLAG
- Suspend the task when there is an error in allocating memory (unless the task was spawned with the VX_UNBREAKABLE option, in which case it cannot be suspended).
- MEM_BLOCK_ERROR_LOG_FLAG
- Log a message when there is an error in freeing memory.
- MEM_BLOCK_ERROR_SUSPEND_FLAG
- Suspend the task when there is an error in freeing memory (unless the task was spawned with the VX_UNBREAKABLE option, in which case it cannot be suspended).
These options are discussed in detail in the library manual entry for memLib.
OK or ERROR.
S_smObjLib_NOT_INITIALIZED
memalign( ) - allocate aligned memory
void *memalign ( unsigned alignment, /* boundary to align to (power of 2) */ unsigned size /* number of bytes to allocate */ )
This routine allocates a buffer of size size from the system memory partition. Additionally, it insures that the allocated buffer begins on a memory address evenly divisible by the specified alignment parameter. The alignment parameter must be a power of 2.
A pointer to the newly allocated block, or NULL if the buffer could not be allocated.
valloc( ) - allocate memory on a page boundary
void * valloc ( unsigned size /* number of bytes to allocate */ )
This routine allocates a buffer of size bytes from the system memory partition. Additionally, it insures that the allocated buffer begins on a page boundary. Page sizes are architecture-dependent.
A pointer to the newly allocated block, or NULL if the buffer could not be allocated or the memory management unit (MMU) support library has not been initialized.
S_memLib_PAGE_SIZE_UNAVAILABLE
memPartRealloc( ) - reallocate a block of memory in a specified partition
void *memPartRealloc ( PART_ID partId, /* partition ID */ char * pBlock, /* block to be reallocated */ unsigned nBytes /* new block size in bytes */ )
This routine changes the size of a specified block of memory and returns a pointer to the new block. The contents that fit inside the new size (or old size if smaller) remain unchanged. The memory alignment of the new block is not guaranteed to be the same as the original block.
If pBlock is NULL, this call is equivalent to memPartAlloc( ).
A pointer to the new block of memory, or NULL if the call fails.
S_smObjLib_NOT_INITIALIZED
memPartFindMax( ) - find the size of the largest available free block
int memPartFindMax ( PART_ID partId /* partition ID */ )
This routine searches for the largest block in the memory partition free list and returns its size.
The size, in bytes, of the largest available block.
S_smObjLib_NOT_INITIALIZED
memOptionsSet( ) - set the debug options for the system memory partition
void memOptionsSet ( unsigned options /* options for system partition */ )
This routine sets the debug options for the 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. In both cases, the following options can be selected for actions to be taken 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.
These options are discussed in detail in the library manual entry for memLib.
N/A
calloc( ) - allocate space for an array (ANSI)
void *calloc ( size_t elemNum, /* number of elements */ size_t elemSize /* size of elements */ )
This routine allocates a block of memory for an array that contains elemNum elements of size elemSize. This space is initialized to zeros.
A pointer to the block, or NULL if the call fails.
memLib, American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: General Utilities (stdlib.h)
realloc( ) - reallocate a block of memory (ANSI)
void *realloc ( void * pBlock, /* block to reallocate */ size_t newSize /* new block size */ )
This routine changes the size of a specified block of memory and returns a pointer to the new block of memory. The contents that fit inside the new size (or old size if smaller) remain unchanged. The memory alignment of the new block is not guaranteed to be the same as the original block.
A pointer to the new block of memory, or NULL if the call fails.
memLib, American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: General Utilities (stdlib.h)
cfree( ) - free a block of memory
STATUS cfree ( char * pBlock /* pointer to block of memory to free */ )
This routine returns to the free memory pool a block of memory previously allocated with calloc( ).
It is an error to free a memory block that was not previously allocated.
OK, or ERROR if the the block is invalid.
memFindMax( ) - find the largest free block in the system memory partition
int memFindMax (void)
This routine searches for the largest block in the system memory partition free list and returns its size.
The size, in bytes, of the largest available block.
memLib, memPartFindMax( )