Contiguous Memory Manager

---

Detailed Description

This is the API for the Contiguous Memory Manager.

Data Structures
struct	CMEM_AllocParams
	Parameters for CMEM_alloc(), CMEM_alloc2(), CMEM_allocPool(), CMEM_allocPool2(), CMEM_free(). More...
struct	CMEM_BlockAttrs
Defines
#define	CMEM_VERSION   0x02300000U
#define	CMEM_WB   0x0100
#define	CMEM_INV   0x0200
#define	CMEM_HEAP   0x0400
#define	CMEM_POOL   0x0000
#define	CMEM_CACHED   0x0800
#define	CMEM_NONCACHED   0x0000
#define	CMEM_PHYS   0x1000
#define	CMEM_IOCALLOC   1
#define	CMEM_IOCALLOCHEAP   2
#define	CMEM_IOCFREE   3
#define	CMEM_IOCGETPHYS   4
#define	CMEM_IOCGETSIZE   5
#define	CMEM_IOCGETPOOL   6
#define	CMEM_IOCCACHE   7
#define	CMEM_IOCGETVERSION   8
#define	CMEM_IOCGETBLOCK   9
#define	CMEM_IOCREGUSER   10
#define	CMEM_IOCCACHEWBINV   CMEM_IOCCACHE | CMEM_WB | CMEM_INV
#define	CMEM_IOCCACHEWB   CMEM_IOCCACHE | CMEM_WB
#define	CMEM_IOCCACHEINV   CMEM_IOCCACHE | CMEM_INV
#define	CMEM_IOCALLOCCACHED   CMEM_IOCALLOC | CMEM_CACHED
#define	CMEM_IOCALLOCHEAPCACHED   CMEM_IOCALLOCHEAP | CMEM_CACHED
#define	CMEM_IOCFREEHEAP   CMEM_IOCFREE | CMEM_HEAP
#define	CMEM_IOCFREEPHYS   CMEM_IOCFREE | CMEM_PHYS
#define	CMEM_IOCFREEHEAPPHYS   CMEM_IOCFREE | CMEM_HEAP | CMEM_PHYS
#define	CMEM_IOCCMDMASK   0x000000ff
Functions
int	CMEM_init (void)
	Initialize the CMEM module. Must be called before other API calls.
int	CMEM_getPool (size_t size)
	Find the pool that best fits a given buffer size and has a buffer available.
int	CMEM_getPool2 (int blockid, size_t size)
	Find the pool in memory block blockid that best fits a given buffer size and has a buffer available.
void *	CMEM_allocPool (int poolid, CMEM_AllocParams *params)
	Allocate memory from a specified pool.
void *	CMEM_allocPool2 (int blockid, int poolid, CMEM_AllocParams *params)
	Allocate memory from a specified pool in a specified memory block.
void *	CMEM_alloc (size_t size, CMEM_AllocParams *params)
	Allocate memory of a specified size.
void *	CMEM_alloc2 (int blockid, size_t size, CMEM_AllocParams *params)
	Allocate memory of a specified size from a specified memory block.
void *	CMEM_registerAlloc (unsigned long physp)
	Register shared usage of an already-allocated buffer.
int	CMEM_free (void *ptr, CMEM_AllocParams *params)
	Free a buffer previously allocated with CMEM_alloc()/CMEM_allocPool().
int	CMEM_unregister (void *ptr, CMEM_AllocParams *params)
	Unregister use of a buffer previously registered with CMEM_registerAlloc().
unsigned long	CMEM_getPhys (void *ptr)
	Get the physical address of a contiguous buffer.
int	CMEM_cacheWb (void *ptr, size_t size)
	Do a cache writeback of the block pointed to by ptr/size.
int	CMEM_cacheInv (void *ptr, size_t size)
	Do a cache invalidate of the block pointed to by ptr/size.
int	CMEM_cacheWbInv (void *ptr, size_t size)
	Do a cache writeback/invalidate of the block pointed to by ptr/size.
int	CMEM_getVersion (void)
	Retrieve version from CMEM driver.
int	CMEM_getBlock (unsigned long *pphys_base, size_t *psize)
	Retrieve memory block bounds from CMEM driver.
int	CMEM_getBlockAttrs (int blockid, CMEM_BlockAttrs *pattrs)
	Retrieve extended memory block attributes from CMEM driver.
int	CMEM_exit (void)
	Finalize the CMEM module.
Variables
CMEM_AllocParams	CMEM_DEFAULTPARAMS

---

Define Documentation

#define CMEM_VERSION   0x02300000U

#define CMEM_WB   0x0100

#define CMEM_INV   0x0200

#define CMEM_HEAP   0x0400

operation applies to heap

#define CMEM_POOL   0x0000

operation applies to a pool

#define CMEM_CACHED   0x0800

allocated buffer is cached

#define CMEM_NONCACHED   0x0000

allocated buffer is not cached

#define CMEM_PHYS   0x1000

#define CMEM_IOCALLOC   1

#define CMEM_IOCALLOCHEAP   2

#define CMEM_IOCFREE   3

#define CMEM_IOCGETPHYS   4

#define CMEM_IOCGETSIZE   5

#define CMEM_IOCGETPOOL   6

#define CMEM_IOCCACHE   7

#define CMEM_IOCGETVERSION   8

#define CMEM_IOCGETBLOCK   9

#define CMEM_IOCREGUSER   10

#define CMEM_IOCCACHEWBINV   CMEM_IOCCACHE | CMEM_WB | CMEM_INV

#define CMEM_IOCCACHEWB   CMEM_IOCCACHE | CMEM_WB

#define CMEM_IOCCACHEINV   CMEM_IOCCACHE | CMEM_INV

#define CMEM_IOCALLOCCACHED   CMEM_IOCALLOC | CMEM_CACHED

#define CMEM_IOCALLOCHEAPCACHED   CMEM_IOCALLOCHEAP | CMEM_CACHED

#define CMEM_IOCFREEHEAP   CMEM_IOCFREE | CMEM_HEAP

#define CMEM_IOCFREEPHYS   CMEM_IOCFREE | CMEM_PHYS

#define CMEM_IOCFREEHEAPPHYS   CMEM_IOCFREE | CMEM_HEAP | CMEM_PHYS

#define CMEM_IOCCMDMASK   0x000000ff

---

Function Documentation

int CMEM_init

(

void

)

Initialize the CMEM module. Must be called before other API calls.

Returns:

0 for success or -1 for failure.

See also:

CMEM_exit

int CMEM_getPool

(

size_t

size

)

Find the pool that best fits a given buffer size and has a buffer available.

Parameters:

size

The buffer size for which a pool is needed.

Returns:

A poolid that can be passed to CMEM_allocPool(), or -1 for error.

Precondition:

Must have called CMEM_init()

See also:

CMEM_allocPool()

CMEM_allocPool2()

CMEM_free()

CMEM_getPool2()

int CMEM_getPool2	(	int	blockid,
		size_t	size
	)

Find the pool in memory block blockid that best fits a given buffer size and has a buffer available.

Parameters:

	blockid	Block number
	size	The buffer size for which a pool is needed.

Returns:

A poolid that can be passed to CMEM_allocPool2(), or -1 for error.

Precondition:

Must have called CMEM_init()

See also:

CMEM_allocPool()

CMEM_allocPool2()

CMEM_free()

CMEM_getPool()

void* CMEM_allocPool	(	int	poolid,
		CMEM_AllocParams *	params
	)

Allocate memory from a specified pool.

Parameters:

	poolid	The pool from which to allocate memory.
	params	Allocation parameters.

Remarks:

params->type is ignored - a pool will always be used.

params->alignment is unused, since pool buffers are already aligned to specific boundaries.

Returns:

A pointer to the allocated buffer, or NULL for failure.

Precondition:

Must have called CMEM_init()

See also:

CMEM_alloc()

CMEM_alloc2()

CMEM_allocPool2()

CMEM_registerAlloc()

CMEM_unregister()

CMEM_free()

void* CMEM_allocPool2	(	int	blockid,
		int	poolid,
		CMEM_AllocParams *	params
	)

Allocate memory from a specified pool in a specified memory block.

Parameters:

	blockid	The memory block from which to allocate.
	poolid	The pool from which to allocate memory.
	params	Allocation parameters.

Remarks:

params->type is ignored - a pool will always be used.

params->alignment is unused, since pool buffers are already aligned to specific boundaries.

Returns:

A pointer to the allocated buffer, or NULL for failure.

Precondition:

Must have called CMEM_init()

See also:

CMEM_alloc()

CMEM_alloc2()

CMEM_allocPool()

CMEM_registerAlloc()

CMEM_unregister()

CMEM_free()

void* CMEM_alloc	(	size_t	size,
		CMEM_AllocParams *	params
	)

Allocate memory of a specified size.

Parameters:

	size	The size of the buffer to allocate.
	params	Allocation parameters.

Remarks:

Used to allocate memory from either a pool or the heap. If doing a pool allocation, the pool that best fits the requested size will be selected. Use CMEM_allocPool() to allocate from a specific pool. Allocation will be cached or noncached, as specified by params. params->alignment valid only for heap allocation.

Returns:

A pointer to the allocated buffer, or NULL for failure.

Precondition:

Must have called CMEM_init()

See also:

CMEM_allocPool()

CMEM_allocPool2()

CMEM_alloc2()

CMEM_registerAlloc()

CMEM_unregister()

CMEM_free()

void* CMEM_alloc2	(	int	blockid,
		size_t	size,
		CMEM_AllocParams *	params
	)

Allocate memory of a specified size from a specified memory block.

Parameters:

	blockid	The memory block from which to allocate.
	size	The size of the buffer to allocate.
	params	Allocation parameters.

Remarks:

Used to allocate memory from either a pool or the heap. If doing a pool allocation, the pool that best fits the requested size will be selected. Use CMEM_allocPool() to allocate from a specific pool.

Allocation will be cached or noncached, as specified by params. params->alignment valid only for heap allocation.

Returns:

A pointer to the allocated buffer, or NULL for failure.

Precondition:

Must have called CMEM_init()

See also:

CMEM_allocPool()

CMEM_allocPool2()

CMEM_alloc()

CMEM_registerAlloc()

CMEM_unregister()

CMEM_free()

void* CMEM_registerAlloc

(

unsigned long

physp

)

Register shared usage of an already-allocated buffer.

Parameters:

physp

Physical address of the already-allocated buffer.

Remarks:

Used to register the calling process for usage of an already-allocated buffer, for the purpose of shared usage of the buffer.

Allocation properties (such as cached/noncached or heap/pool) are inherited from original allocation call.

Returns:

A process-specific pointer to the allocated buffer, or NULL for failure.

Precondition:

Must have called some form of CMEM_alloc*()

See also:

CMEM_allocPool()

CMEM_allocPool2()

CMEM_alloc()

CMEM_free()

CMEM_unregister()

int CMEM_free	(	void *	ptr,
		CMEM_AllocParams *	params
	)

Free a buffer previously allocated with CMEM_alloc()/CMEM_allocPool().

Parameters:

	ptr	The pointer to the buffer.
	params	Allocation parameters.

Remarks:

Use the same CMEM_AllocParams as was used for the allocation. params->flags is "don't care". params->alignment is "don't care".

Returns:

0 for success or -1 for failure.

Precondition:

Must have called CMEM_init()

See also:

CMEM_alloc()

CMEM_alloc2()

CMEM_allocPool()

CMEM_allocPool2()

CMEM_registerAlloc()

CMEM_unregister()

int CMEM_unregister	(	void *	ptr,
		CMEM_AllocParams *	params
	)

Unregister use of a buffer previously registered with CMEM_registerAlloc().

Parameters:

	ptr	The pointer to the buffer.
	params	Allocation parameters.

Remarks:

Use the same CMEM_AllocParams as was used for the allocation. params->flags is "don't care". params->alignment is "don't care".

Returns:

0 for success or -1 for failure.

Precondition:

Must have called CMEM_init()

See also:

CMEM_alloc()

CMEM_alloc2()

CMEM_allocPool()

CMEM_allocPool2()

CMEM_registerAlloc()

CMEM_free()

unsigned long CMEM_getPhys

(

void *

ptr

)

Get the physical address of a contiguous buffer.

Parameters:

ptr

The pointer to the buffer.

Returns:

The physical address of the buffer or 0 for failure.

Precondition:

Must have called CMEM_init()

int CMEM_cacheWb	(	void *	ptr,
		size_t	size
	)

Do a cache writeback of the block pointed to by ptr/size.

Parameters:

	ptr	Pointer to block to writeback
	size	Size in bytes of block to writeback.

Returns:

Success/failure boolean value

Precondition:

Must have called CMEM_init()

See also:

CMEM_cacheInv()

CMEM_cacheWbInv()

int CMEM_cacheInv	(	void *	ptr,
		size_t	size
	)

Do a cache invalidate of the block pointed to by ptr/size.

Parameters:

	ptr	Pointer to block to invalidate
	size	Size in bytes of block to invalidate

Returns:

Success/failure boolean value

Precondition:

Must have called CMEM_init()

See also:

CMEM_cacheWb()

CMEM_cacheWbInv()

int CMEM_cacheWbInv	(	void *	ptr,
		size_t	size
	)

Do a cache writeback/invalidate of the block pointed to by ptr/size.

Parameters:

	ptr	Pointer to block to writeback/invalidate
	size	Size in bytes of block to writeback/invalidate

Returns:

Success/failure boolean value

Precondition:

Must have called CMEM_init()

See also:

CMEM_cacheInv()

CMEM_cacheWb()

int CMEM_getVersion

(

void

)

Retrieve version from CMEM driver.

Returns:

Installed CMEM driver's version number.

Precondition:

Must have called CMEM_init()

int CMEM_getBlock	(	unsigned long *	pphys_base,
		size_t *	psize
	)

Retrieve memory block bounds from CMEM driver.

Parameters:

	pphys_base	Pointer to storage for base physical address of CMEM's memory block
	psize	Pointer to storage for size of CMEM's memory block

Returns:

Success (0) or failure (-1).

Precondition:

Must have called CMEM_init()

See also:

CMEM_getBlockAttrs()

int CMEM_getBlockAttrs	(	int	blockid,
		CMEM_BlockAttrs *	pattrs
	)

Retrieve extended memory block attributes from CMEM driver.

Parameters:

	blockid	Block number
	pattrs	Pointer to CMEM_BlockAttrs struct

Returns:

Success (0) or failure (-1).

Remarks:

Currently this API returns the same values as CMEM_getBlock().

Precondition:

Must have called CMEM_init()

See also:

CMEM_getBlock()

int CMEM_exit

(

void

)

Finalize the CMEM module.

Returns:

0 for success or -1 for failure.

Remarks:

After this function has been called, no other CMEM function may be called (unless CMEM is reinitialized).

Precondition:

Must have called CMEM_init()

See also:

CMEM_init()

---

Variable Documentation

CMEM_AllocParams CMEM_DEFAULTPARAMS

---

Copyright 2009, Texas Instruments Incorporated