Detailed Description

Multi-processor fixed-size buffer heap implementation.

============================================================================

Heap implementation that manages fixed size buffers that can be used in a multiprocessor system with shared memory.

The HeapBufMP manager provides functions to allocate and free storage from a heap of type HeapBufMP which inherits from IHeap. HeapBufMP manages a single fixed-size buffer, split into equally sized allocatable blocks.

The HeapBufMP manager is intended as a very fast memory manager which can only allocate blocks of a single size. It is ideal for managing a heap that is only used for allocating a single type of object, or for objects that have very similar sizes.

The HeapBufMP module uses a NameServer instance to store instance information when an instance is created. The name supplied must be unique for all HeapBufMP instances.

The HeapBufMP_create call initializes the shared memory as needed. Once an instance is created, a HeapBufMP_open can be performed. The open is used to gain access to the same HeapBufMP instance. Generally an instance is created on one processor and opened on the other processor(s).

The open returns a HeapBufMP instance handle like the create, however the open does not modify the shared memory.

The HeapBufMP header should be included in an application as follows:

  #include <ti/ipc/HeapBufMP.h>

Version:: 0.00.01

#include <ti/ipc/GateMP.h>

Include dependency graph for HeapBufMP.h:

Go to the source code of this file.

Data Structures
struct	HeapBufMP_Params
	Structure defining parameters for the HeapBufMP module. More...
struct	HeapBufMP_ExtendedStats
	Stats structure for the HeapBufMP_getExtendedStats API. More...
Defines
#define	HeapBufMP_S_BUSY 2
	The resource is still in use.
#define	HeapBufMP_S_ALREADYSETUP 1
	The module has been already setup.
#define	HeapBufMP_S_SUCCESS 0
	Operation is successful.
#define	HeapBufMP_E_FAIL -1
	Generic failure.
#define	HeapBufMP_E_INVALIDARG -2
	Argument passed to function is invalid.
#define	HeapBufMP_E_MEMORY -3
	Operation resulted in memory failure.
#define	HeapBufMP_E_ALREADYEXISTS -4
	The specified entity already exists.
#define	HeapBufMP_E_NOTFOUND -5
	Unable to find the specified entity.
#define	HeapBufMP_E_TIMEOUT -6
	Operation timed out.
#define	HeapBufMP_E_INVALIDSTATE -7
	Module is not initialized.
#define	HeapBufMP_E_OSFAILURE -8
	A failure occurred in an OS-specific call.
#define	HeapBufMP_E_RESOURCE -9
	Specified resource is not available.
#define	HeapBufMP_E_RESTART -10
	Operation was interrupted. Please restart the operation.
Typedefs
typedef struct HeapBufMP_Object *	HeapBufMP_Handle
	HeapBufMP_Handle type.
typedef struct HeapBufMP_Params	HeapBufMP_Params
	Structure defining parameters for the HeapBufMP module.
typedef struct HeapBufMP_ExtendedStats	HeapBufMP_ExtendedStats
	Stats structure for the HeapBufMP_getExtendedStats API.
Functions
Int	HeapBufMP_close (HeapBufMP_Handle *handlePtr)
	Close a HeapBufMP instance.
HeapBufMP_Handle	HeapBufMP_create (const HeapBufMP_Params *params)
	Create a HeapBufMP instance.
Int	HeapBufMP_delete (HeapBufMP_Handle *handlePtr)
	Delete a created HeapBufMP instance.
Int	HeapBufMP_open (String name, HeapBufMP_Handle *handlePtr)
	Open a created HeapBufMP instance.
Void	HeapBufMP_Params_init (HeapBufMP_Params *params)
	Initialize a HeapBufMP parameters struct.
Void *	HeapBufMP_alloc (HeapBufMP_Handle handle, SizeT size, SizeT align)
	Allocate a block of memory of specified size and alignment.
Void	HeapBufMP_free (HeapBufMP_Handle handle, Ptr block, SizeT size)
	Frees a block of memory.
Void	HeapBufMP_getExtendedStats (HeapBufMP_Handle handle, HeapBufMP_ExtendedStats *stats)
	Get extended memory statistics.
Void	HeapBufMP_getStats (HeapBufMP_Handle handle, Ptr stats)
	Get memory statistics.

Define Documentation

#define HeapBufMP_S_BUSY 2

The resource is still in use.

#define HeapBufMP_S_ALREADYSETUP 1

The module has been already setup.

#define HeapBufMP_S_SUCCESS 0

Operation is successful.

#define HeapBufMP_E_FAIL -1

Generic failure.

#define HeapBufMP_E_INVALIDARG -2

Argument passed to function is invalid.

#define HeapBufMP_E_MEMORY -3

Operation resulted in memory failure.

#define HeapBufMP_E_ALREADYEXISTS -4

The specified entity already exists.

#define HeapBufMP_E_NOTFOUND -5

Unable to find the specified entity.

#define HeapBufMP_E_TIMEOUT -6

Operation timed out.

#define HeapBufMP_E_INVALIDSTATE -7

Module is not initialized.

#define HeapBufMP_E_OSFAILURE -8

A failure occurred in an OS-specific call.

#define HeapBufMP_E_RESOURCE -9

Specified resource is not available.

#define HeapBufMP_E_RESTART -10

Operation was interrupted. Please restart the operation.

Typedef Documentation

typedef struct HeapBufMP_Object* HeapBufMP_Handle

HeapBufMP_Handle type.

typedef struct HeapBufMP_Params HeapBufMP_Params

Structure defining parameters for the HeapBufMP module.

typedef struct HeapBufMP_ExtendedStats HeapBufMP_ExtendedStats

Stats structure for the HeapBufMP_getExtendedStats API.

Function Documentation

Int HeapBufMP_close ( HeapBufMP_Handle * handlePtr )

Close a HeapBufMP instance.

Closing an instance will free local memory consumed by the opened instance. All opened instances should be closed before the instance is deleted.

Parameters:

handlePtr Pointer to handle returned from HeapBufMP_open

See also:: HeapBufMP_open

HeapBufMP_Handle HeapBufMP_create ( const HeapBufMP_Params * params )

Create a HeapBufMP instance.

Parameters:

params HeapBufMP parameters

Returns:: HeapBufMP Handle

Int HeapBufMP_delete ( HeapBufMP_Handle * handlePtr )

Delete a created HeapBufMP instance.

Parameters:

handlePtr Pointer to handle to delete.

Int HeapBufMP_open	(	String	name,
		HeapBufMP_Handle *	handlePtr
	)

Open a created HeapBufMP instance.

Once an instance is created, an open can be performed. The open is used to gain access to the same HeapBufMP instance. Generally an instance is created on one processor and opened on the other processor.

The open returns a HeapBufMP instance handle like the create, however the open does not initialize the shared memory. The supplied name is used to identify the created instance.

Call HeapBufMP_close when the opened instance is not longer needed.

Parameters:

name	Name of created HeapBufMP instance
handlePtr	Pointer to HeapBufMP handle to be opened

Returns:

HeapBufMP status:

HeapBufMP_S_SUCCESS: Heap successfully opened
HeapBufMP_E_NOTFOUND: Heap is not yet ready to be opened.
HeapBufMP_E_FAIL: A general failure has occurred

See also:: HeapBufMP_close

Void HeapBufMP_Params_init ( HeapBufMP_Params * params )

Initialize a HeapBufMP parameters struct.

Parameters:

[out] params Pointer to GateMP parameters

Void* HeapBufMP_alloc	(	HeapBufMP_Handle	handle,
		SizeT	size,
		SizeT	align
	)

Allocate a block of memory of specified size and alignment.

The actual block returned may be larger than requested to satisfy alignment requirements.

HeapBufMP_alloc will lock the heap using the HeapBufMP gate while it traverses the list of free blocks to find a large enough block for the request.

Guidelines for using large heaps and multiple alloc() calls.

If possible, allocate larger blocks first. Previous allocations of small memory blocks can reduce the size of the blocks available for larger memory allocations.
Realize that alloc() can fail even if the heap contains a sufficient absolute amount of unalloccated space. This is because the largest free memory block may be smaller than total amount of unallocated memory.

Parameters:

handle	Handle to previously created/opened instance.
size	Size to be allocated (in MADUs)
align	Alignment for allocation (power of 2)

See also:: HeapBufMP_free

Void HeapBufMP_free	(	HeapBufMP_Handle	handle,
		Ptr	block,
		SizeT	size
	)

Frees a block of memory.

free() places the memory block specified by addr and size back into the free pool of the heap specified. The newly freed block is combined with any adjacent free blocks. The space is then available for further allocation by alloc().

HeapBufMP_free will lock the heap using the HeapBufMP gate if one is specified or the system GateMP if not.

Parameters:

handle	Handle to previously created/opened instance.
block	Block of memory to be freed.
size	Size to be freed (in MADUs)

See also:: HeapBufMP_alloc

Void HeapBufMP_getExtendedStats	(	HeapBufMP_Handle	handle,
		HeapBufMP_ExtendedStats *	stats
	)

Get extended memory statistics.

This function retrieves the extended statistics for a HeapBufMP instance. It does not retrieve the standard Memory_Stats information. Refer to HeapBufMP_ExtendedStats for more information regarding what information is returned.

Parameters:

	handle	Handle to previously created/opened instance.
[out]	stats	ExtendedStats structure

See also:

Void HeapBufMP_getStats	(	HeapBufMP_Handle	handle,
		Ptr	stats
	)

Get memory statistics.

Parameters:

[in]	handle	Handle to previously created/opened instance.
[out]	stats	Memory statistics structure

See also:

HeapBufMP.h File Reference

Detailed Description

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation