IPC API  3.40.00.06
Data Structures | Macros | Typedefs | Functions
HeapMemMP.h File Reference

Detailed Description

Multi-processor variable size buffer heap implementation.

Note
HeapMemMP is currently only available for SYS/BIOS.

HeapMemMP is a heap implementation that manages variable size buffers that can be used in a multiprocessor system with shared memory. HeapMemMP manages a single buffer in shared memory from which blocks of user- specified length are allocated and freed.

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

HeapMemMP_create() initializes the shared memory as needed. Once an instance is created, HeapMemMP_open() can be called. The open is used to gain access to the same HeapMemMP instance. Generally an instance is created on one processor and opened on the other processor(s).

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

Because HeapMemMP is a variable-size heap implementation, it is also used by the SharedRegion module to manage shared memory in each shared region. When any shared memory IPC instance is created in a particular shared region, the HeapMemMP that manages shared memory in the shared region allocates shared memory for the instance.

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

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

Go to the source code of this file.

Data Structures

struct  HeapMemMP_Params
 Structure defining parameters for the HeapMemMP module. More...
 
struct  HeapMemMP_ExtendedStats
 Stats structure for HeapMemMP_getExtendedStats() More...
 

Macros

#define HeapMemMP_S_BUSY   2
 The resource is still in use. More...
 
#define HeapMemMP_S_ALREADYSETUP   1
 The module has been already setup. More...
 
#define HeapMemMP_S_SUCCESS   0
 Operation is successful. More...
 
#define HeapMemMP_E_FAIL   -1
 Generic failure. More...
 
#define HeapMemMP_E_INVALIDARG   -2
 Argument passed to function is invalid. More...
 
#define HeapMemMP_E_MEMORY   -3
 Operation resulted in memory failure. More...
 
#define HeapMemMP_E_ALREADYEXISTS   -4
 The specified entity already exists. More...
 
#define HeapMemMP_E_NOTFOUND   -5
 Unable to find the specified entity. More...
 
#define HeapMemMP_E_TIMEOUT   -6
 Operation timed out. More...
 
#define HeapMemMP_E_INVALIDSTATE   -7
 Module is not initialized. More...
 
#define HeapMemMP_E_OSFAILURE   -8
 A failure occurred in an OS-specific call. More...
 
#define HeapMemMP_E_RESOURCE   -9
 Specified resource is not available. More...
 
#define HeapMemMP_E_RESTART   -10
 Operation was interrupted. Please restart the operation. More...
 

Typedefs

typedef struct HeapMemMP_Object * HeapMemMP_Handle
 HeapMemMP_Handle type. More...
 
typedef struct HeapMemMP_Params HeapMemMP_Params
 Structure defining parameters for the HeapMemMP module. More...
 
typedef struct HeapMemMP_ExtendedStats HeapMemMP_ExtendedStats
 Stats structure for HeapMemMP_getExtendedStats() More...
 

Functions

Int HeapMemMP_close (HeapMemMP_Handle *handlePtr)
 Close a HeapMemMP instance. More...
 
HeapMemMP_Handle HeapMemMP_create (const HeapMemMP_Params *params)
 Create a HeapMemMP instance. More...
 
Int HeapMemMP_delete (HeapMemMP_Handle *handlePtr)
 Delete a created HeapMemMP instance. More...
 
Int HeapMemMP_open (String name, HeapMemMP_Handle *handlePtr)
 Open a created HeapMemMP instance. More...
 
Void HeapMemMP_Params_init (HeapMemMP_Params *params)
 Initialize a HeapMemMP parameters struct. More...
 
Void * HeapMemMP_alloc (HeapMemMP_Handle handle, SizeT size, SizeT align)
 Allocate a block of memory of specified size and alignment. More...
 
Void HeapMemMP_free (HeapMemMP_Handle handle, Ptr block, SizeT size)
 Frees a block of memory. More...
 
Void HeapMemMP_getExtendedStats (HeapMemMP_Handle handle, HeapMemMP_ExtendedStats *stats)
 Get extended memory statistics. More...
 
Void HeapMemMP_getStats (HeapMemMP_Handle handle, Ptr stats)
 Get memory statistics. More...
 
Void HeapMemMP_restore (HeapMemMP_Handle handle)
 Restore an instance to it's original created state. More...
 

Macro Definition Documentation

#define HeapMemMP_S_BUSY   2

The resource is still in use.

#define HeapMemMP_S_ALREADYSETUP   1

The module has been already setup.

#define HeapMemMP_S_SUCCESS   0

Operation is successful.

#define HeapMemMP_E_FAIL   -1

Generic failure.

#define HeapMemMP_E_INVALIDARG   -2

Argument passed to function is invalid.

#define HeapMemMP_E_MEMORY   -3

Operation resulted in memory failure.

#define HeapMemMP_E_ALREADYEXISTS   -4

The specified entity already exists.

#define HeapMemMP_E_NOTFOUND   -5

Unable to find the specified entity.

#define HeapMemMP_E_TIMEOUT   -6

Operation timed out.

#define HeapMemMP_E_INVALIDSTATE   -7

Module is not initialized.

#define HeapMemMP_E_OSFAILURE   -8

A failure occurred in an OS-specific call.

#define HeapMemMP_E_RESOURCE   -9

Specified resource is not available.

#define HeapMemMP_E_RESTART   -10

Operation was interrupted. Please restart the operation.

Typedef Documentation

typedef struct HeapMemMP_Object* HeapMemMP_Handle

HeapMemMP_Handle type.

Structure defining parameters for the HeapMemMP module.

See also
HeapMemMP_create()

Function Documentation

Int HeapMemMP_close ( HeapMemMP_Handle handlePtr)

Close a HeapMemMP 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
[in,out]handlePtrPointer to handle returned from HeapMemMP_open()
Returns
HeapMemMP status:
See also
HeapMemMP_open()
HeapMemMP_Handle HeapMemMP_create ( const HeapMemMP_Params params)

Create a HeapMemMP instance.

Parameters
[in]paramsHeapMemMP parameters
Returns
HeapMemMP Handle
See also
HeapMemMP_delete()
Int HeapMemMP_delete ( HeapMemMP_Handle handlePtr)

Delete a created HeapMemMP instance.

Parameters
[in,out]handlePtrPointer to handle to delete.
Returns
HeapMemMP status:
See also
HeapMemMP_create()
Int HeapMemMP_open ( String  name,
HeapMemMP_Handle handlePtr 
)

Open a created HeapMemMP instance.

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

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

Parameters
[in]nameName of created HeapMemMP instance
[out]handlePtrPointer to HeapMemMP handle to be opened
Returns
HeapMemMP status:
See also
HeapMemMP_close
Void HeapMemMP_Params_init ( HeapMemMP_Params params)

Initialize a HeapMemMP parameters struct.

Parameters
[out]paramsPointer to creation parameters
See also
HeapMemMP_create()
Void* HeapMemMP_alloc ( HeapMemMP_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. NULL is returned if the alloc fails.

HeapMemMP_alloc will lock the heap using the HeapMemMP 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 allocation can fail even if the heap contains a sufficient absolute amount of unallocated space. This is because the largest free memory block may be smaller than total amount of unallocated memory.
Parameters
[in]handleHandle to previously created/opened instance.
[in]sizeSize to be allocated (in MADUs)
[in]alignAlignment for allocation (power of 2)
See also
HeapMemMP_free()
Void HeapMemMP_free ( HeapMemMP_Handle  handle,
Ptr  block,
SizeT  size 
)

Frees a block of memory.

HeapMemMP_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 future allocations.

HeapMemMP_free() will lock the heap using the HeapMemMP gate if one is specified or the system GateMP if not.

Parameters
[in]handleHandle to previously created/opened instance.
[in]blockBlock of memory to be freed.
[in]sizeSize to be freed (in MADUs)
See also
HeapMemMP_alloc()
Void HeapMemMP_getExtendedStats ( HeapMemMP_Handle  handle,
HeapMemMP_ExtendedStats stats 
)

Get extended memory statistics.

This function retrieves extended statistics for a HeapMemMP instance. Refer to HeapMemMP_ExtendedStats for more information regarding what information is returned.

Parameters
[in]handleHandle to previously created/opened instance.
[out]statsExtendedStats structure
See also
HeapMemMP_getStats
Void HeapMemMP_getStats ( HeapMemMP_Handle  handle,
Ptr  stats 
)

Get memory statistics.

Parameters
[in]handleHandle to previously created/opened instance.
[out]statsMemory statistics structure
See also
HeapMemMP_getExtendedStats()
Void HeapMemMP_restore ( HeapMemMP_Handle  handle)

Restore an instance to it's original created state.

This function restores an instance to its original created state. Any memory previously allocated from the heap is no longer valid after this API is called. This function does not check whether there is allocated memory or not.

Parameters
[in]handleHandle to previously created/opened instance.
Copyright 2015, Texas Instruments Incorporated