Data Structures | Defines | Typedefs | Functions

HeapMultiBufMP.h File Reference


Detailed Description

Multiple fixed size buffer heap implementation.

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

The HeapMultiBufMP manager provides functions to allocate and free storage from a shared memory heap of type HeapMultiBufMP which inherits from IHeap. HeapMultiBufMP manages multiple fixed-size memory buffers. Each buffer contains a fixed number of allocatable memory 'blocks' of the same size. HeapMultiBufMP is intended as a fast and deterministic memory manager which can service requests for blocks of arbitrary size.

An example HeapMultiBufMP instance might have sixteen 32-byte blocks in one buffer, and four 128-byte blocks in another buffer. A request for memory will be serviced by the smallest possible block, so a request for 100 bytes would receive a 128-byte block in our example.

Allocating from HeapMultiBufMP will try to return a block from the first buffer which has:

1. A block size that is >= to the requested size

AND

2. An alignment that is >= to the requested alignment

Buffer configuration for a new instance is primarily supplied via the HeapMultiBufMP_Params::bucketEntries instance configuration parameter. Once buckets are adjusted for size and alignment, buffers with equal sizes and alignments are combined.

Block Sizes and Alignment

In addition to the buffer configuration, a HeapMultiBufMP_Params::name and a HeapMultiBufMP_Params::regionId (from which shared memory is allocated) must be supplied when creating an instance.

Once an instance is created, an HeapMultiBufMP_open can be performed using the name that was supplied in the HeapMultiBufMP_create. The open is used to gain access to the same HeapMultiBufMP instance. Generally an instance is created on one processor and opened on the other processor(s). The open returns (by reference) a HeapMultiBufMP instance handle like the create, however the open does not modify the shared memory.

HeapMultiBufMP_open will return HeapMultiBufMP_E_FAIL if called before the instance is created.

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

  #include <ti/ipc/HeapMultiBufMP.h>
Version:
0.00.01

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

#include <ti/ipc/GateMP.h>
Include dependency graph for HeapMultiBufMP.h:

Go to the source code of this file.

Data Structures

struct  HeapMultiBufMP_Bucket
 Structure for bucket configuration. More...
struct  HeapMultiBufMP_Params
 Structure defining parameters for the HeapMultiBufMP module. More...
struct  HeapMultiBufMP_ExtendedStats
 Stats structure for the HeapMultiBufMP_getExtendedStats API. More...

Defines

#define HeapMultiBufMP_S_BUSY   2
 The resource is still in use.
#define HeapMultiBufMP_S_ALREADYSETUP   1
 The module has been already setup.
#define HeapMultiBufMP_S_SUCCESS   0
#define HeapMultiBufMP_E_FAIL   -1
#define HeapMultiBufMP_E_INVALIDARG   -2
 Argument passed to function is invalid.
#define HeapMultiBufMP_E_MEMORY   -3
 Operation resulted in memory failure.
#define HeapMultiBufMP_E_ALREADYEXISTS   -4
 The specified entity already exists.
#define HeapMultiBufMP_E_NOTFOUND   -5
 Unable to find the specified entity.
#define HeapMultiBufMP_E_TIMEOUT   -6
 Operation timed out.
#define HeapMultiBufMP_E_INVALIDSTATE   -7
 Module is not initialized.
#define HeapMultiBufMP_E_OSFAILURE   -8
 A failure occurred in an OS-specific call.
#define HeapMultiBufMP_E_RESOURCE   -9
 Specified resource is not available.
#define HeapMultiBufMP_E_RESTART   -10
 Operation was interrupted. Please restart the operation.
#define HeapMultiBufMP_MAXBUCKETS   ((UInt)8)
 Maximum number of buffer buckets supported.

Typedefs

typedef struct
HeapMultiBufMP_Object * 
HeapMultiBufMP_Handle
 HeapMultiBufMP_Handle type.
typedef struct
HeapMultiBufMP_Bucket 
HeapMultiBufMP_Bucket
 Structure for bucket configuration.
typedef struct
HeapMultiBufMP_Params 
HeapMultiBufMP_Params
 Structure defining parameters for the HeapMultiBufMP module.
typedef struct
HeapMultiBufMP_ExtendedStats 
HeapMultiBufMP_ExtendedStats
 Stats structure for the HeapMultiBufMP_getExtendedStats API.

Functions

Int HeapMultiBufMP_close (HeapMultiBufMP_Handle *handlePtr)
 Close a HeapMultiBufMP instance.
HeapMultiBufMP_Handle HeapMultiBufMP_create (const HeapMultiBufMP_Params *params)
 Create a HeapMultiBufMP instance.
Int HeapMultiBufMP_delete (HeapMultiBufMP_Handle *handlePtr)
 Delete a created HeapMultiBufMP instance.
Int HeapMultiBufMP_open (String name, HeapMultiBufMP_Handle *handlePtr)
 Open a created HeapMultiBufMP instance.
Void HeapMultiBufMP_Params_init (HeapMultiBufMP_Params *params)
 Initialize a HeapMultiBufMP parameters struct.
Void * HeapMultiBufMP_alloc (HeapMultiBufMP_Handle handle, SizeT size, SizeT align)
 Allocate a block of memory of specified size and alignment.
Void HeapMultiBufMP_free (HeapMultiBufMP_Handle handle, Ptr block, SizeT size)
 Frees a block of memory.
Void HeapMultiBufMP_getExtendedStats (HeapMultiBufMP_Handle handle, HeapMultiBufMP_ExtendedStats *stats)
 Get extended memory statistics.
Void HeapMultiBufMP_getStats (HeapMultiBufMP_Handle handle, Ptr stats)
 Get memory statistics.

Define Documentation

#define HeapMultiBufMP_S_BUSY   2

The resource is still in use.

#define HeapMultiBufMP_S_ALREADYSETUP   1

The module has been already setup.

#define HeapMultiBufMP_S_SUCCESS   0
#define HeapMultiBufMP_E_FAIL   -1
#define HeapMultiBufMP_E_INVALIDARG   -2

Argument passed to function is invalid.

#define HeapMultiBufMP_E_MEMORY   -3

Operation resulted in memory failure.

#define HeapMultiBufMP_E_ALREADYEXISTS   -4

The specified entity already exists.

#define HeapMultiBufMP_E_NOTFOUND   -5

Unable to find the specified entity.

#define HeapMultiBufMP_E_TIMEOUT   -6

Operation timed out.

#define HeapMultiBufMP_E_INVALIDSTATE   -7

Module is not initialized.

#define HeapMultiBufMP_E_OSFAILURE   -8

A failure occurred in an OS-specific call.

#define HeapMultiBufMP_E_RESOURCE   -9

Specified resource is not available.

#define HeapMultiBufMP_E_RESTART   -10

Operation was interrupted. Please restart the operation.

#define HeapMultiBufMP_MAXBUCKETS   ((UInt)8)

Maximum number of buffer buckets supported.


Typedef Documentation

typedef struct HeapMultiBufMP_Object* HeapMultiBufMP_Handle

HeapMultiBufMP_Handle type.

Structure for bucket configuration.

An array of buckets is a required parameter to create any HeapMultiBufMP instance. The fields of each bucket correspond to the attributes of each buffer in the HeapMultiBufMP. The actual block sizes and alignments may be adjusted per the process described at HeapMultiBufMP_Params::bucketEntries.

Structure defining parameters for the HeapMultiBufMP module.

Stats structure for the HeapMultiBufMP_getExtendedStats API.


Function Documentation

Int HeapMultiBufMP_close ( HeapMultiBufMP_Handle handlePtr )

Close a HeapMultiBufMP 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:
handlePtrPointer to handle returned from HeapMultiBufMP_open
See also:
HeapMultiBufMP_open
HeapMultiBufMP_Handle HeapMultiBufMP_create ( const HeapMultiBufMP_Params params )

Create a HeapMultiBufMP instance.

Parameters:
paramsHeapMultiBufMP parameters
Returns:
HeapMultiBufMP Handle
Int HeapMultiBufMP_delete ( HeapMultiBufMP_Handle handlePtr )

Delete a created HeapMultiBufMP instance.

Parameters:
handlePtrPointer to handle to delete.
Int HeapMultiBufMP_open ( String  name,
HeapMultiBufMP_Handle handlePtr 
)

Open a created HeapMultiBufMP instance.

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

The open returns a HeapMultiBufMP 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 HeapMultiBufMP_close when the opened instance is not longer needed.

Parameters:
nameName of created HeapMultiBufMP instance
handlePtrPointer to HeapMultiBufMP handle to be opened
Returns:
HeapMultiBufMP status
See also:
HeapMultiBufMP_close
Void HeapMultiBufMP_Params_init ( HeapMultiBufMP_Params params )

Initialize a HeapMultiBufMP parameters struct.

Parameters:
[out]paramsPointer to GateMP parameters
Void* HeapMultiBufMP_alloc ( HeapMultiBufMP_Handle  handle,
SizeT  size,
SizeT  align 
)

Allocate a block of memory of specified size and alignment.

Parameters:
handleHandle to previously created/opened instance.
sizeSize to be allocated (in MADUs)
alignAlignment for allocation (power of 2)
See also:
HeapMultiBufMP_free
Void HeapMultiBufMP_free ( HeapMultiBufMP_Handle  handle,
Ptr  block,
SizeT  size 
)

Frees a block of memory.

Parameters:
handleHandle to previously created/opened instance.
blockBlock of memory to be freed.
sizeSize to be freed (in MADUs)
See also:
HeapMultiBufMP_alloc
Void HeapMultiBufMP_getExtendedStats ( HeapMultiBufMP_Handle  handle,
HeapMultiBufMP_ExtendedStats stats 
)

Get extended memory statistics.

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

Parameters:
handleHandle to previously created/opened instance.
[out]statsExtendedStats structure
See also:
Void HeapMultiBufMP_getStats ( HeapMultiBufMP_Handle  handle,
Ptr  stats 
)

Get memory statistics.

Parameters:
handleHandle to previously created/opened instance.
[out]statsMemory statistics structure
See also:
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Copyright 2012, Texas Instruments Incorporated