VxWorks API Reference : OS Libraries

memPartLib

NAME

memPartLib - core memory partition manager

ROUTINES

memPartCreate( ) - create a memory partition
memPartAddToPool( ) - add memory to a memory partition
memPartAlignedAlloc( ) - allocate aligned memory from a partition
memPartAlloc( ) - allocate a block of memory from a partition
memPartFree( ) - free a block of memory in a partition
memAddToPool( ) - add memory to the system memory partition
malloc( ) - allocate a block of memory from the system memory partition (ANSI)
free( ) - free a block of memory (ANSI)

DESCRIPTION

This library provides core facilities for managing the allocation of blocks of memory from ranges of memory called memory partitions. The library was designed to provide a compact implementation; full-featured functionality is available with memLib, which provides enhanced memory management features built as an extension of memPartLib. (For more information about enhanced memory partition management options, see the manual entry for memLib.) This library consists of two sets of routines. The first set, memPart...( ), comprises a general facility for the creation and management of memory partitions, and for the allocation and deallocation of blocks from those partitions. The second set provides a traditional ANSI-compatible malloc( )/free( ) interface to the system memory partition.

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 allocation of memory, using malloc( ) in the typical case and memPartAlloc( ) for a specific memory partition, is done with a first-fit algorithm. Adjacent blocks of memory are coalesced when they are freed with memPartFree( ) and free( ). There is also a routine provided for allocating memory aligned to a specified boundary from a specific memory partition, memPartAlignedAlloc( ).

CAVEATS

Architectures have various alignment constraints. To provide optimal performance, malloc( ) returns a pointer to a buffer having the appropriate alignment for the architecture in use. The portion of the allocated buffer reserved for system bookkeeping, known as the overhead, may vary depending on the architecture.

Architecture Boundary Overhead

ARM 4 8
COLDFIRE 4 8
I86 4 8
M68K 4 8
MCORE 8 8
MIPS 16 16
PPC * 8/16 8/16
SH 4 8
SIMNT 8 8
SIMSOLARIS 8 8
SPARC 8 8
* On PowerPC, the boundary and overhead values are 16 bytes for system based on the PPC604 CPU type (including ALTIVEC). For all other PowerPC CPU types (PPC403, PPC405, PPC440, PPC860, PPC603, etc...), the boundary and overhead are 8 bytes.

INCLUDE FILES

memLib.h, stdlib.h

SEE ALSO

memLib, smMemLib


OS Libraries : Routines

memPartCreate( )

NAME

memPartCreate( ) - create a memory partition

SYNOPSIS

PART_ID memPartCreate
    (
    char *   pPool,           /* pointer to memory area */
    unsigned poolSize         /* size in bytes */
    )

DESCRIPTION

This routine creates a new memory partition containing a specified memory pool. It returns a partition ID, which can then be passed to other routines to manage the partition (i.e., to allocate and free memory blocks in the partition). Partitions can be created to manage any number of separate memory pools.

NOTE

The descriptor for the new partition is allocated out of the system memory partition (i.e., with malloc( )).

RETURNS

The partition ID, or NULL if there is insufficient memory in the system memory partition for a new partition descriptor.

SEE ALSO

memPartLib, smMemLib


OS Libraries : Routines

memPartAddToPool( )

NAME

memPartAddToPool( ) - add memory to a memory partition

SYNOPSIS

STATUS memPartAddToPool
    (
    PART_ID  partId,          /* partition to initialize */
    char *   pPool,           /* pointer to memory block */
    unsigned poolSize         /* block size in bytes */
    )

DESCRIPTION

This routine adds memory to a specified memory partition already created with memPartCreate( ). The memory added need not be contiguous with memory previously assigned to the partition.

RETURNS

OK or ERROR.

ERRNO

S_smObjLib_NOT_INITIALIZED, S_memLib_INVALID_NBYTES

SEE ALSO

memPartLib, smMemLib, memPartCreate( )


OS Libraries : Routines

memPartAlignedAlloc( )

NAME

memPartAlignedAlloc( ) - allocate aligned memory from a partition

SYNOPSIS

void *memPartAlignedAlloc
    (
    PART_ID  partId,          /* memory partition to allocate from */
    unsigned nBytes,          /* number of bytes to allocate */
    unsigned alignment        /* boundary to align to */
    )

DESCRIPTION

This routine allocates a buffer of size nBytes from a specified partition. Additionally, it insures that the allocated buffer begins on a memory address evenly divisible by alignment. 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

memPartLib


OS Libraries : Routines

memPartAlloc( )

NAME

memPartAlloc( ) - allocate a block of memory from a partition

SYNOPSIS

void *memPartAlloc
    (
    PART_ID  partId,          /* memory partition to allocate from */
    unsigned nBytes           /* number of bytes to allocate */
    )

DESCRIPTION

This routine allocates a block of memory from a specified partition. The size of the block will be equal to or greater than nBytes. The partition must already be created with memPartCreate( ).

RETURNS

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

ERRNO

S_smObjLib_NOT_INITIALIZED

SEE ALSO

memPartLib, smMemLib, memPartCreate( )


OS Libraries : Routines

memPartFree( )

NAME

memPartFree( ) - free a block of memory in a partition

SYNOPSIS

STATUS memPartFree
    (
    PART_ID partId,           /* memory partition to add block to */
    char *  pBlock            /* pointer to block of memory to free */
    )

DESCRIPTION

This routine returns to a partition's free memory list a block of memory previously allocated with memPartAlloc( ).

RETURNS

OK, or ERROR if the block is invalid.

ERRNO

S_smObjLib_NOT_INITIALIZED

SEE ALSO

memPartLib, smMemLib, memPartAlloc( )


OS Libraries : Routines

memAddToPool( )

NAME

memAddToPool( ) - add memory to the system memory partition

SYNOPSIS

void memAddToPool
    (
    char *   pPool,           /* pointer to memory block */
    unsigned poolSize         /* block size in bytes */
    )

DESCRIPTION

This routine adds memory to the system memory partition, after the initial allocation of memory to the system memory partition.

RETURNS

N/A

SEE ALSO

memPartLib, memPartAddToPool( )


OS Libraries : Routines

malloc( )

NAME

malloc( ) - allocate a block of memory from the system memory partition (ANSI)

SYNOPSIS

void *malloc
    (
    size_t nBytes             /* number of bytes to allocate */
    )

DESCRIPTION

This routine allocates a block of memory from the free list. The size of the block will be equal to or greater than nBytes.

RETURNS

A pointer to the allocated block of memory, or a null pointer if there is an error.

SEE ALSO

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


OS Libraries : Routines

free( )

NAME

free( ) - free a block of memory (ANSI)

SYNOPSIS

void free
    (
    void * ptr                /* pointer to block of memory to free */
    )

DESCRIPTION

This routine returns to the free memory pool a block of memory previously allocated with malloc( ) or calloc( ).

RETURNS

N/A

SEE ALSO

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