module ti.sysbios.heaps.HeapMultiBuf |
![](../../../Arrow_left.png) |
![](../../../Arrow_up.png) |
![](../../../Arrow_right.png) |
Multiple fixed size buffer heap manager
The HeapMultiBuf manager provides functions to allocate and free storage
from a heap of type HeapMultiBuf which inherits from IHeap. HeapMultiBuf
manages multiple fixed-size memory buffers. Each buffer contains a fixed
number of allocable memory 'blocks' of the same size. Simply put, a
HeapMultiBuf instance manages a collection of HeapBuf instances.
HeapMultiBuf is intended as a fast and deterministic memory manager which
can service requests for blocks of arbitrary size.
[
more ... ]
#include <ti/sysbios/heaps/HeapMultiBuf.h>
Functions |
Void | |
| |
Void | |
Void | |
Void | |
Functions common to all IHeap modules |
Ptr | |
Void | |
Void | |
Bool | |
Functions common to all target instances |
|
HeapMultiBuf_handle// Convert this instance structure pointer into an instance handle,
HeapMultiBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure,
HeapMultiBuf_Handle_label// The label associated with this instance object,
HeapMultiBuf_Handle_name// The name of this instance object,
HeapMultiBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy,
HeapMultiBuf_Object_count// The number of statically-created instance objects,
HeapMultiBuf_Object_first// The handle of the first dynamically-created instance object, or NULL,
HeapMultiBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL),
HeapMultiBuf_Object_heap// The heap used to allocate dynamically-created instance objects,
HeapMultiBuf_Object_next// The handle of the next dynamically-created instance object, or NULL,
HeapMultiBuf_struct// Convert this instance handle into an instance structure pointer
|
Functions common to all target modules |
|
|
Typedefs |
| |
typedef struct | |
typedef struct | |
typedef struct | |
Constants |
| |
| |
DETAILS
The HeapMultiBuf manager provides functions to allocate and free storage
from a heap of type HeapMultiBuf which inherits from IHeap. HeapMultiBuf
manages multiple fixed-size memory buffers. Each buffer contains a fixed
number of allocable memory 'blocks' of the same size. Simply put, a
HeapMultiBuf instance manages a collection of HeapBuf instances.
HeapMultiBuf is intended as a fast and deterministic memory manager which
can service requests for blocks of arbitrary size.
An example HeapMultiBuf 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 HeapMultiBuf 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
If the first matching buffer is empty, HeapMultiBuf will only continue
searching for a block if 'block borrowing' is enabled (see Block
Borrowing).
HeapMultiBuf and HeapBuf
The HeapMultiBuf module is built on top of the HeapBuf module. Each buffer
in a HeapMultiBuf is in fact managed by a HeapBuf instance. Configuration
of a HeapMultiBuf is done by providing an array of configured HeapBuf
parameter structures. Refer to the HeapBuf documentation for information on
the buffer parameters. All of the documentation and parameters for HeapBuf
apply equally to HeapMultiBuf.
Another consequence of this is that configuration checking is left to the
HeapBuf module. If a buffer in a HeapMultiBuf has been incorrectly
configured (with blockSize = 0, for example), HeapBuf, not HeapMultiBuf,
will raise an Assert.
Since HeapMultiBuf is built on HeapBuf, it simply performs the logic to
determine which HeapBuf to allocate a block from or which HeapBuf to free
a block to.
Configuration Example
The following configuration code creates a HeapMultiBuf instance which
manages 3 pools of 10 blocks each, with block sizes of 64, 128 and 256.
var HeapMultiBuf = xdc.useModule('ti.sysbios.heaps.HeapMultiBuf');
var HeapBuf = xdc.useModule('ti.sysbios.heaps.HeapBuf');
// Create parameter structure for HeapMultiBuf instance.
var hmbParams = new HeapMultiBuf.Params();
hmbParams.numBufs = 3;
// Create the parameter structures for each of the three
// HeapBufs to be managed by the HeapMultiBuf instance.
hmbParams.bufParams.$add(new HeapBuf.Params());
hmbParams.bufParams[0].blockSize = 64;
hmbParams.bufParams[0].numBlocks = 10;
hmbParams.bufParams.$add(new HeapBuf.Params());
hmbParams.bufParams[1].blockSize = 128;
hmbParams.bufParams[1].numBlocks = 10;
hmbParams.bufParams.$add(new HeapBuf.Params());
hmbParams.bufParams[2].blockSize = 256;
hmbParams.bufParams[2].numBlocks = 10;
// Create the HeapMultiBuf instance, and assign the global handle
// 'multiBufHeap' to it. Add '#include <xdc/cfg/global.h>' to your
// .c file to reference the instance by this handle.
Program.global.multiBufHeap = HeapMultiBuf.create(hmbParams);
Block Borrowing
HeapMultiBuf can support "block borrowing". With this feature turned on,
if a request is made for a 32-byte block and none are available,
HeapMultiBuf will continue looking for an available block in other buffers.
When a borrowed block is freed, it will be returned back to its original
buffer. Enabling Block Borrowing changes the determinism of alloc, since it
may have to check any number of buffers to find an available block.
Block borrowing may also occur, even if it is disabled, if a block of a
particular size is requested with an alignment that is greater than the
configured alignment for that block size. For example, a HeapMultiBuf is
configured with a buffer of 32-byte blocks with an alignment of 8, and
a buffer of 64-byte blocks with an alignment of 16. If a request is made
for a 32-byte block with an alignment of 16, it will be serviced by the
buffer of 64-byte blocks.
Static vs. Dynamic Creation
As with HeapBuf, a statically created HeapMultiBuf instance will ignore the
bufSize and buf parameters. Dynamic creates require all of the parameters.
It should be noted that static creates are ideal if code space is a
concern; dynamically creating a HeapMultiBuf requires a relatively large
amount of initialization code to be pulled in to the executable.
Block Sizes and Alignment
- A buffer with a requested alignment of 0 will receive the target-
specific minimum alignment.
- The actual block sizes will be a multiple of the alignment. For
example, if a buffer is configured to have 56-byte blocks with an
alignment of 32, HeapMultiBuf will actually create 64-byte blocks.
When providing the buffer for a dynamic create, make sure it is
large enough to take this into account.
- Multiple buffers with the same block size ARE allowed. This may
occur, for example, if sizeof is used to specify the block sizes.
- If any buffers have both the same block size and alignment, they
will be merged. If this is a problem, consider managing these buffers
directly with HeapBuf objects.
Real-Time Concerns
Allocation from and freeing to a HeapMultiBuf instance is non-blocking.
HeapMultiBuf is deterministic:
- A call to alloc will always take the same amount of time for a given
block size (with block borrowing disabled).
- The worst case call to free is constant and proportional to the number
of buffers managed.
Restrictions
- Align parameters must be a power of 2.
- The buffers passed to dynamically create a HeapMultiBuf must be aligned
according to the alignment parameter, and must be large enough to account
for the actual block size after it has been rounded up to a multiple of
the alignment.
- Buffers must be provided to dynamically create a HeapMultiBuf, and cannot
be provided to statically create a HeapMultiBuf.
Unconstrained Functions
All functions
Calling Context
Function | Hwi | Swi |
Task | Main | Startup |
Params_init | Y | Y |
Y | Y | Y |
alloc | Y | Y |
Y | Y | N |
construct | N* | N* |
Y | Y | N |
create | N* | N* |
Y | Y | N |
delete | N* | N* |
Y | Y | N |
destruct | N* | N* |
Y | Y | N |
free | Y | Y |
Y | Y | N |
getStats | Y | Y |
Y | Y | N |
isBlocking | 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. HeapMultiBuf_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. HeapMultiBuf_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.
|
config HeapMultiBuf_A_blockNotFreed // module-wide |
![](../../../Arrow_up.png) |
Invalid block pointer
extern const Assert_Id HeapMultiBuf_A_blockNotFreed;
DETAILS
This Assert is raised if a call to free does not successfully
free the block back to any of the buffers. Indicates that the
block pointer is invalid, or that the HeapMultiBuf state has been
corrupted.
config HeapMultiBuf_E_size // module-wide |
![](../../../Arrow_up.png) |
Raised when requested size exceeds all blockSizes
extern const Error_Id HeapMultiBuf_E_size;
Module-Wide Built-Ins |
![](../../../Arrow_up.png) |
// Get this module's unique id
Bool HeapMultiBuf_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapMultiBuf_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapMultiBuf_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapMultiBuf_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
![](../../../Arrow_up.png) |
typedef struct HeapMultiBuf_Object HeapMultiBuf_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapMultiBuf_Struct HeapMultiBuf_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
![](../../../Arrow_up.png) |
typedef struct HeapMultiBuf_Params {
// Instance config-params structure
// Common per-instance configs
Bool blockBorrow;
// Turn block borrowing on (true) or off (false)
// Config parameters for each buffer
Int numBufs;
// Number of memory buffers
} HeapMultiBuf_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMultiBuf_Params.blockBorrow // instance |
![](../../../Arrow_up.png) |
Turn block borrowing on (true) or off (false)
DETAILS
With block borrowing on, if there are no blocks available of the
requested size, then alloc will look for a larger block to return.
Calls to alloc which borrow blocks will be slower, and will cause
internal fragmentation of the heap (until the block is freed), so it
is ideal to configure a HeapMultiBuf such that block borrowing is not
needed.
config HeapMultiBuf_Params.bufParams // instance |
![](../../../Arrow_up.png) |
Config parameters for each buffer
DETAILS
Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance.
Configuration of a HeapMultiBuf is done by providing an array of
configured HeapBuf parameter structures. Refer to the HeapBuf
documentation for information on the buffer parameters. All of the
documentation and parameters for HeapBuf apply to HeapMultiBuf.
If a buffer is configured incorrectly, HeapBuf, not HeapMultiBuf,
will raise an Assert.
config HeapMultiBuf_Params.numBufs // instance |
![](../../../Arrow_up.png) |
Number of memory buffers
DETAILS
The number of different fixed size memory buffers that are managed
by the heap instance. The bufParams array has length numBufs.
The default number of buffers is 0.
Runtime Instance Creation |
![](../../../Arrow_up.png) |
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
Instance Deletion |
![](../../../Arrow_up.png) |
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
HeapMultiBuf_alloc() // instance |
![](../../../Arrow_up.png) |
Allocates a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapMultiBuf instance object
size
size (in MADUs) of the block
align
alignment (in MADUs) of the block
eb
pointer to error block
DETAILS
This method returns a block of memory from the heap.
It is called by the
xdc.runtime.Memory.alloc() function.
HEAPMULTIBUF
HeapMultiBuf will return a block that is >= 'size' with
an alignment that is >= 'align'.
The HeapMultiBuf will attempt to service a request for any size; the
specified size does not need to match the configured block sizes of
the buffers.
RETURNS
Returns the address of the allocated memory.
HeapMultiBuf_free() // instance |
![](../../../Arrow_up.png) |
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapMultiBuf instance object
block
non-NULL address of allocated block to free
size
size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap.
It is called by the
xdc.runtime.Memory.free() function.
HEAPMULTIBUF
HeapMultiBuf ignores the 'size' parameter to free. It
determines the correct buffer to free the block to by comparing
addresses.
HeapMultiBuf_getStats() // instance |
![](../../../Arrow_up.png) |
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapMultiBuf instance object
stats
non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a
xdc.runtime.Memory.Stats
structure and
getStats fills in this structure.
This function is called by the
xdc.runtime.Memory.getStats()
function.
HeapMultiBuf_isBlocking() // instance |
![](../../../Arrow_up.png) |
Returns whether the heap may block during an alloc() or
free()
ARGUMENTS
handle
handle of a previously-created HeapMultiBuf instance object
HEAPMULTIBUF
This function always returns FALSE since the alloc/free
never block on a resource.
RETURNS
If the heap might block, TRUE is returned.
If the heap does not block, FALSE is returned.
Instance Convertors |
![](../../../Arrow_up.png) |
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins |
![](../../../Arrow_up.png) |
Int HeapMultiBuf_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object
var HeapMultiBuf = xdc.useModule('ti.sysbios.heaps.HeapMultiBuf');
module-wide config parameters
msg: "Invalid block address on the free. Failed to free block back to heap."
};
msg: "requested size is too big: handle=0x%x, size=%u"
};
per-instance config parameters
per-instance creation
config HeapMultiBuf.A_blockNotFreed // module-wide |
![](../../../Arrow_up.png) |
Invalid block pointer
msg: "Invalid block address on the free. Failed to free block back to heap."
};
DETAILS
This Assert is raised if a call to free does not successfully
free the block back to any of the buffers. Indicates that the
block pointer is invalid, or that the HeapMultiBuf state has been
corrupted.
C SYNOPSIS
config HeapMultiBuf.E_size // module-wide |
![](../../../Arrow_up.png) |
Raised when requested size exceeds all blockSizes
msg: "requested size is too big: handle=0x%x, size=%u"
};
C SYNOPSIS
metaonly config HeapMultiBuf.common$ // module-wide |
![](../../../Arrow_up.png) |
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
Instance Config Parameters |
![](../../../Arrow_up.png) |
var params = new HeapMultiBuf.Params;
// Instance config-params object
params.blockBorrow = Bool false;
// Turn block borrowing on (true) or off (false)
// Config parameters for each buffer
params.numBufs = Int 0;
// Number of memory buffers
config HeapMultiBuf.Params.blockBorrow // instance |
![](../../../Arrow_up.png) |
Turn block borrowing on (true) or off (false)
var params = new HeapMultiBuf.Params;
...
params.blockBorrow = Bool false;
DETAILS
With block borrowing on, if there are no blocks available of the
requested size, then alloc will look for a larger block to return.
Calls to alloc which borrow blocks will be slower, and will cause
internal fragmentation of the heap (until the block is freed), so it
is ideal to configure a HeapMultiBuf such that block borrowing is not
needed.
C SYNOPSIS
config HeapMultiBuf.Params.bufParams // instance |
![](../../../Arrow_up.png) |
Config parameters for each buffer
var params = new HeapMultiBuf.Params;
...
DETAILS
Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance.
Configuration of a HeapMultiBuf is done by providing an array of
configured HeapBuf parameter structures. Refer to the HeapBuf
documentation for information on the buffer parameters. All of the
documentation and parameters for HeapBuf apply to HeapMultiBuf.
If a buffer is configured incorrectly, HeapBuf, not HeapMultiBuf,
will raise an Assert.
C SYNOPSIS
config HeapMultiBuf.Params.numBufs // instance |
![](../../../Arrow_up.png) |
Number of memory buffers
var params = new HeapMultiBuf.Params;
...
params.numBufs = Int 0;
DETAILS
The number of different fixed size memory buffers that are managed
by the heap instance. The bufParams array has length numBufs.
The default number of buffers is 0.
C SYNOPSIS
Static Instance Creation |
![](../../../Arrow_up.png) |
var params =
new HeapMultiBuf.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMultiBuf.create(params);
// Create an instance-object
ARGUMENTS
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
generated on Fri, 10 Jun 2016 23:29:34 GMT