VxWorks API Reference : OS Libraries

memLib

NAME

memLib - full-featured memory partition manager

ROUTINES

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

DESCRIPTION

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( ).

ERROR OPTIONS

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_FLAG

When 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);

INCLUDE FILES

memLib.h

SEE ALSO

memPartLib, smMemLib


OS Libraries : Routines

memPartOptionsSet( )

NAME

memPartOptionsSet( ) - set the debug options for a memory partition

SYNOPSIS

STATUS memPartOptionsSet
    (
    PART_ID  partId,          /* partition to set option for */
    unsigned options          /* memory management options */
    )

DESCRIPTION

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.

RETURNS

OK or ERROR.

ERRNO

S_smObjLib_NOT_INITIALIZED

SEE ALSO

memLib, smMemLib


OS Libraries : Routines

memalign( )

NAME

memalign( ) - allocate aligned memory

SYNOPSIS

void *memalign
    (
    unsigned alignment,       /* boundary to align to (power of 2) */
    unsigned size             /* number of bytes to allocate */
    )

DESCRIPTION

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.

RETURNS

A pointer to the newly allocated block, or NULL if the buffer could not be allocated.

SEE ALSO

memLib


OS Libraries : Routines

valloc( )

NAME

valloc( ) - allocate memory on a page boundary

SYNOPSIS

void * valloc
    (
    unsigned size             /* number of bytes to allocate */
    )

DESCRIPTION

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.

RETURNS

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.

ERRNO

S_memLib_PAGE_SIZE_UNAVAILABLE

SEE ALSO

memLib


OS Libraries : Routines

memPartRealloc( )

NAME

memPartRealloc( ) - reallocate a block of memory in a specified partition

SYNOPSIS

void *memPartRealloc
    (
    PART_ID  partId,          /* partition ID */
    char *   pBlock,          /* block to be reallocated */
    unsigned nBytes           /* new block size in bytes */
    )

DESCRIPTION

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( ).

RETURNS

A pointer to the new block of memory, or NULL if the call fails.

ERRNO

S_smObjLib_NOT_INITIALIZED

SEE ALSO

memLib, smMemLib


OS Libraries : Routines

memPartFindMax( )

NAME

memPartFindMax( ) - find the size of the largest available free block

SYNOPSIS

int memPartFindMax
    (
    PART_ID partId            /* partition ID */
    )

DESCRIPTION

This routine searches for the largest block in the memory partition free list and returns its size.

RETURNS

The size, in bytes, of the largest available block.

ERRNO

S_smObjLib_NOT_INITIALIZED

SEE ALSO

memLib, smMemLib


OS Libraries : Routines

memOptionsSet( )

NAME

memOptionsSet( ) - set the debug options for the system memory partition

SYNOPSIS

void memOptionsSet
    (
    unsigned options          /* options for system partition */
    )

DESCRIPTION

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.

RETURNS

N/A

SEE ALSO

memLib, memPartOptionsSet( )


OS Libraries : Routines

calloc( )

NAME

calloc( ) - allocate space for an array (ANSI)

SYNOPSIS

void *calloc
    (
    size_t elemNum,           /* number of elements */
    size_t elemSize           /* size of elements */
    )

DESCRIPTION

This routine allocates a block of memory for an array that contains elemNum elements of size elemSize. This space is initialized to zeros.

RETURNS

A pointer to the block, or NULL if the call fails.

SEE ALSO

memLib, American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: General Utilities (stdlib.h)


OS Libraries : Routines

realloc( )

NAME

realloc( ) - reallocate a block of memory (ANSI)

SYNOPSIS

void *realloc
    (
    void * pBlock,            /* block to reallocate */
    size_t newSize            /* new block size */
    )

DESCRIPTION

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.

RETURNS

A pointer to the new block of memory, or NULL if the call fails.

SEE ALSO

memLib, American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989: General Utilities (stdlib.h)


OS Libraries : Routines

cfree( )

NAME

cfree( ) - free a block of memory

SYNOPSIS

STATUS cfree
    (
    char * pBlock             /* pointer to block of memory to free */
    )

DESCRIPTION

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.

RETURNS

OK, or ERROR if the the block is invalid.

SEE ALSO

memLib


OS Libraries : Routines

memFindMax( )

NAME

memFindMax( ) - find the largest free block in the system memory partition

SYNOPSIS

int memFindMax (void)

DESCRIPTION

This routine searches for the largest block in the system memory partition free list and returns its size.

RETURNS

The size, in bytes, of the largest available block.

SEE ALSO

memLib, memPartFindMax( )