HeapMem manager provides functions to allocate and free storage from a
heap of type HeapMem which inherits from IHeap.
struct HeapMem.ExtendedStats |
|
Stats structure for the getExtendedStats API
XDCscript usage |
meta-domain |
var obj = new HeapMem.ExtendedStats;
obj.buf = Ptr ...
obj.size = SizeT ...
typedef struct HeapMem_ExtendedStats {
Ptr buf;
SizeT size;
} HeapMem_ExtendedStats;
FIELDS
buf
Base address of the internal buffer.
This may be different from the original buf
parameter due to alignment requirements.
size
Size of the internal buffer.
This may be different from the original size
parameter due to alignment requirements.
metaonly struct HeapMem.FreeBlockView |
|
XDCscript usage |
meta-domain |
var obj = new HeapMem.FreeBlockView;
obj.address = String ...
obj.label = String ...
obj.size = String ...
config HeapMem.A_align // module-wide |
|
Assert raised when the requested alignment is not a power of 2
XDCscript usage |
meta-domain |
msg: "A_align: Requested align is not a power of 2"
};
config HeapMem.A_heapSize // module-wide |
|
Assert raised when the requested heap size is too small
XDCscript usage |
meta-domain |
msg: "A_heapSize: Requested heap size is too small"
};
config HeapMem.A_invalidFree // module-wide |
|
Assert raised when the free detects that an invalid addr or size
XDCscript usage |
meta-domain |
msg: "A_invalidFree: Invalid free"
};
extern const Assert_Id HeapMem_A_invalidFree;
DETAILS
This could arise when multiple frees are done on the same buffer or
if corruption occurred.
This also could occur when an alloc is made with size N and the
free for this buffer specifies size M where M > N. Note: not every
case is detectable.
This assert can also be caused when passing an invalid addr to free
or if the size is causing the end of the buffer to be
out of the expected range.
config HeapMem.A_zeroBlock // module-wide |
|
Assert raised when a block of size 0 is requested
XDCscript usage |
meta-domain |
msg: "A_zeroBlock: Cannot allocate size 0"
};
metaonly config HeapMem.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
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.
module-wide built-ins |
|
// Get this module's unique id
Bool HeapMem_Module_startupDone( );
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapMem_Module_hasMask( );
// Test whether this module has a diagnostics mask
Bits16 HeapMem_Module_getMask( );
// Returns the diagnostics mask for this module
Void HeapMem_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
per-instance object types |
|
typedef struct HeapMem_Object HeapMem_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapMem_Struct HeapMem_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
per-instance config parameters |
|
XDCscript usage |
meta-domain |
var params = new HeapMem.Params;
// Instance config-params object
params.align = SizeT 0;
// Alignment of the buffer being managed by this heap instance
params.buf = Ptr 0;
// Buffer being managed by this heap instance
params.sectionName = String null;
// Section name for the buffer managed by the instance
params.size = UArg 0;
// Size of buffer being managed by this heap instance
typedef struct HeapMem_Params {
// Instance config-params structure
// Common per-instance configs
Ptr buf;
// Buffer being managed by this heap instance
// Size of buffer being managed by this heap instance
} HeapMem_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMem.buf // per-instance |
|
Buffer being managed by this heap instance
XDCscript usage |
meta-domain |
var params = new HeapMem.Params;
...
params.buf = Ptr 0;
DETAILS
This parameter is ignored in the static HeapMem.create() call. It is a
required parameter in the dynamic HeapMem_create() call.
HeapMem requires that the buffer be aligned on a target-specific minimum
alignment, and will adjust the buffer's start address and size as
neccessary to satisfy this requirement.
config HeapMem.size // per-instance |
|
Size of buffer being managed by this heap instance
XDCscript usage |
meta-domain |
var params = new HeapMem.Params;
...
params.size = UArg 0;
DETAILS
The usable size may be smaller depending on alignment requirements.
metaonly config HeapMem.align // per-instance |
|
Alignment of the buffer being managed by this heap instance
XDCscript usage |
meta-domain |
var params = new HeapMem.Params;
...
params.align = SizeT 0;
DETAILS
In the static HeapMem.create() call, the buffer allocated for the
HeapMem instance will have the alignment specified by this parameter.
In the dynamic case, the client must supply the buffer, so it is the
client's responsibility to manage the buffer's alignment, and there is
no 'align' parameter.
The specified alignment must be a power of 2.
HeapMem requires that the buffer be aligned on a target-specific minimum
alignment, and will adjust (round up) the requested alignment as
neccessary to satisfy this requirement.
The default alignment is 0.
metaonly config HeapMem.sectionName // per-instance |
|
Section name for the buffer managed by the instance
XDCscript usage |
meta-domain |
var params = new HeapMem.Params;
...
params.sectionName = String null;
DETAILS
The default section is the 'dataSection' in the platform.
per-instance creation |
|
XDCscript usage |
meta-domain |
var params =
new HeapMem.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMem.create( params );
// Create an instance-object
// 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.
per-instance deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
HeapMem.alloc( ) // per-instance |
|
Allocates a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapMem 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.
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.
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.
RETURNS
Returns the address of the allocated memory.
HEAPMEM
The actual block returned may be larger than requested to satisfy
alignment requirements.
HeapMem.free( ) // per-instance |
|
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapMem 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.
free() will lock the heap using the HeapMem Gate, if one is specified
using 'HeapMem.common$.gate'.
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().
HeapMem.getExtendedStats( ) // per-instance |
|
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
stats
Location for the returned extended statistics.
DETAILS
This function retrieves the extended statistics for a HeapMem instance.
It does not retrieve the standard xdc.runtime.Memory.Stats information.
HEAPMEM
Retrieves the extended statistics for a HeapMem instance.
HeapMem.getStats( ) // per-instance |
|
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapMem 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.
The returned totalSize reflects the usable size of the buffer, not
necessarily the size specified during create.
HEAPMEM
getStats() will lock the heap using the HeapMem Gate while it retrieves
the HeapMem's statistics.
HeapMem.isBlocking( ) // per-instance |
|
Returns whether the heap may block during an alloc() or
free()
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
RETURNS
If the heap might block, TRUE is returned.
If the heap does not block, FALSE is returned.
HEAPMEM
This function queries the gate (as specified by 'HeapMem.common$.gate')
to determine if the alloc/free can be blocking.
HeapMem.restore( ) // per-instance |
|
ARGUMENTS
handle
handle of a previously-created HeapMem instance object
DETAILS
This function restores a static or dynamically created 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.
HEAPMEM
Restores an instance to it's original created state.
per-instance convertors |
|
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
per-instance built-ins |
|
Int HeapMem_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