Variable size buffer heap manager.
HeapMem manager provides functions to allocate and free storage from a heap of type HeapMem which inherits from IHeap.
In addition to allowing multiple static HeapMem instances to be created who's buffer placements and sizes are defined by their instance configuration parameters, HeapMem allows one Heap instance to be defined who's heap memory is defined by buffer start and end symbols in the linker command file. This singular Heap instance is referred to as the 'Primary Heap'.
HeapMem Gate
A HeapMem instance will use the HeapMem module Gate to protect any accesses
to its list of free memory blocks. The HeapMem instance will enter and
leave the module Gate when allocating blocks, freeing blocks, and
retrieving statistics about the HeapMem.
By default, the Gate is of type GateMutex.
A different Gate can be specified using the common$.gate parameter.
For example, to use a GateTask to protect HeapMem:
HeapMem.common$.gate = GateTask.create();
To save on overhead, HeapMem does not create additional Gate instances on a
per-instance basis; there is only one Gate instance shared across all of
the HeapMem instances. Therefore, the HeapMem.common$.gateParams parameter
(used for configuring per-instance Gates) is ignored.
The type of Gate used should be chosen based on the type of threads (Hwi,
Swi, Task, etc.) using the heap. It should also consider the
non-deterministic nature of the HeapMem. A call to alloc or free will
traverse a list of free blocks, so a GateHwi, for example, is likely an
inappropriate Gate for HeapMem.
Calling Context
Function | Hwi | Swi | Task
| Main | Startup |
Params_init | Y | Y |
Y | Y | Y |
alloc
| N** | N** | Y** | Y
| N |
construct | Y
| Y | Y | Y | N
|
create | N* | N*
| Y | Y | N |
delete | N* | N* | Y
| Y | N |
destruct
| Y | Y | Y | Y
| N |
free | N**
| N** | Y** | Y | N
|
getExtendedStats | Y | Y
| Y | Y | N |
getStats | N** | N** | Y**
| Y | N |
isBlocking
| Y | Y | Y | Y
| N |
restore | Y+
| Y+ | Y+ | Y | N
|
Definitions: - Hwi: API
is callable from a Hwi thread.
- Swi: API is callable from a
Swi thread.
- Task: API is callable from a Task thread.
- Main: API is callable during any of these phases:
-
In your module startup after this module is started (e.g.
HeapMem_Module_startupDone() returns true).
- During
xdc.runtime.Startup.lastFxns.
- During main().
- During
BIOS.startupFxns.
- Startup: API is callable during any
of these phases:
- During xdc.runtime.Startup.firstFxns.
- In your module startup before this module is started (e.g.
HeapMem_Module_startupDone() returns false).
- * :
Assuming blocking Heap is used for creation.
- **: Assuming
GateMutex is used as HeapMem's Gate.
- + : Cannot use HeapMem
object while it is being restored.
|
|
void * | HeapMem_alloc (HeapMem_Handle heap, size_t size, size_t align, Error_Block *eb) |
| The actual block returned may be larger than requested to satisfy alignment requirements, and its size will always be a multiple of the size of the HeapMem_Header data structure (usually 8 bytes) More...
|
|
void | HeapMem_free (HeapMem_Handle heap, void *buf, size_t size) |
| HeapMem_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(). More...
|
|
bool | HeapMem_isBlocking (HeapMem_Handle heap) |
| This function queries the gate to determine if the alloc/free can be blocking. More...
|
|
void | HeapMem_getStats (HeapMem_Handle heap, Memory_Stats *statBuf) |
| HeapMem_getStats will lock the heap using the HeapMem Gate while it retrieves the HeapMem's statistics. More...
|
|
void | HeapMem_getExtendedStats (HeapMem_Handle heap, HeapMem_ExtendedStats *statBuf) |
| Retrieves the extended statistics for a HeapMem instance. More...
|
|
HeapMem_Handle | HeapMem_create (const HeapMem_Params *params, Error_Block *eb) |
| Create a HeapMem heap. More...
|
|
HeapMem_Handle | HeapMem_construct (HeapMem_Struct *obj, const HeapMem_Params *params) |
| Construct a HeapMem heap. More...
|
|
void | HeapMem_delete (HeapMem_Handle *heap) |
| Delete a HeapMem heap. More...
|
|
void | HeapMem_destruct (HeapMem_Struct *obj) |
| Destruct a HeapMem heap. More...
|
|
void | HeapMem_restore (HeapMem_Handle heap) |
| Restore heap to its original created state. More...
|
|
void | HeapMem_init (void) |
| Initialize instance at runtime. More...
|
|
void | HeapMem_Params_init (HeapMem_Params *prms) |
| Initialize the HeapMem_Params structure with default values. More...
|
|
HeapMem_Handle | HeapMem_Object_first (void) |
| return handle of the first HeapMem on HeapMem list More...
|
|
HeapMem_Handle | HeapMem_Object_next (HeapMem_Handle heap) |
| return handle of the next HeapMem on HeapMem list More...
|
|
void* HeapMem_alloc |
( |
HeapMem_Handle |
heap, |
|
|
size_t |
size, |
|
|
size_t |
align, |
|
|
Error_Block * |
eb |
|
) |
| |
The actual block returned may be larger than requested to satisfy alignment requirements, and its size will always be a multiple of the size of the HeapMem_Header data structure (usually 8 bytes)
HeapMem_alloc() will lock the heap using the HeapMem Gate while it traverses the list of free blocks to find a large enough block for the request.
HeapMem_alloc() should not be called directly. Application code should use Memory_alloc() with a HeapMem_Handle as the first parameter. Among other things, Memory_alloc() makes sure that the alignment parameter is greater than or equal to the minimum alignment required for the HeapMem_Header data structure for a given C compiler (8 bytes in most cases). HeapMem_alloc() may crash if you pass a smaller alignment.
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 unallocated space. This is
because the largest free memory block may be smaller than
total amount of unallocated memory.
- Parameters
-
heap | heap handle |
size | Requested size |
align | Requested alignment |
eb | Error_Block used to denote location in case of a failure |
- Return values
-
allocated | block or NULL is request cannot be honored |