packages » ti » sdo » linuxutils » cmem » include

cmem.h File Reference

Detailed Description

Describes the interface to the contiguous memory allocator.

The cmem user interface library wraps file system calls to an associated kernel module (cmemk.ko), which needs to be loaded in order for calls to this library to succeed.

The following is an example of installing the cmem kernel module:

/sbin/insmod cmemk.ko pools=4x30000,2x500000 phys_start=0x0 phys_end=0x3000000

phys_start and phys_end must be specified in hexadecimal format
pools must be specified using decimal format (for both number and size), since using hexadecimal format would visually clutter the specification due to the use of "x" as a token separator

This particular command creates 2 pools. The first pool is created with 4 buffers of size 30000 bytes and the second pool is created with 2 buffers of size 500000 bytes. The CMEM pool buffers start at 0x0 and end at 0x3000000 (max).

Pool buffers are aligned on a module-dependent boundary, and their sizes are rounded up to this same boundary. This applies to each buffer within a pool. The total space used by an individual pool will therefore be greater than (or equal to) the exact amount requested in the installation of the module.

The poolid used in the driver calls would be 0 for the first pool and 1 for the second pool.

Pool allocations can be requested explicitly by pool number, or more generally by just a size. For size-based allocations, the pool which best fits the requested size is automatically chosen.

There is also support for a general purpose heap. In addition to the 2 pools described above, a general purpose heap block is created from which allocations of any size can be requested. Internally, allocation sizes are rounded up to a module-dependent boundary and allocation addresses are aligned either to this same boundary or to the requested alignment (whichever is greater).

The size of the heap block is the amount of CMEM memory remaining after all pool allocations. If more heap space is needed than is available after pool allocations, you must reduce the amount of CMEM memory granted to the pools.

Go to the source code of this file.

Data Structures

struct CMEM_AllocParams

Parameters for CMEM_alloc(), CMEM_free(), and CMEM_allocPool(). More...

Defines

#define CMEM_VERSION   0x02000000

#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_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.

void * CMEM_allocPool (int poolid, CMEM_AllocParams *params)

Allocate memory from a specified pool.

void * CMEM_alloc (size_t size, CMEM_AllocParams *params)

Allocate memory of a specified size.

int CMEM_free (void *ptr, CMEM_AllocParams *params)

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

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_exit (void)

Finalize the CMEM module.

Variables

CMEM_AllocParams CMEM_DEFAULTPARAMS

Define Documentation

#define CMEM_VERSION 0x02000000

#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_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_free()

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_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_free()

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

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_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


Data Structures
struct	CMEM_AllocParams
	Parameters for CMEM_alloc(), CMEM_free(), and CMEM_allocPool(). More...
Defines
#define	CMEM_VERSION 0x02000000
#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_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.
void *	CMEM_allocPool (int poolid, CMEM_AllocParams *params)
	Allocate memory from a specified pool.
void *	CMEM_alloc (size_t size, CMEM_AllocParams *params)
	Allocate memory of a specified size.
int	CMEM_free (void ptr, CMEM_AllocParams params)
	Free a buffer previously allocated with CMEM_alloc()/ CMEM_allocPool().
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_exit (void)
	Finalize the CMEM module.
Variables
CMEM_AllocParams	CMEM_DEFAULTPARAMS