The HeapBuf manager provides functions to allocate and free storage from a
heap of type HeapBuf which inherits from IHeap. HeapBuf manages a single
fixed-size buffer, split into equally sized allocable blocks.
The HeapBuf manager is intended as a very fast and deterministic memory
manager which can only allocate blocks of a single size. It is ideal for
managing a heap that is only used for allocating a single type of object,
or for objects that have very similar sizes.
Allocation from and freeing to a HeapBuf instance is non-blocking and
deterministic: a call to alloc or free will always take the same amount of
time.
struct HeapBuf_ExtendedStats |
|
Stat structure for the HeapBuf_getExtendedStats function
typedef struct HeapBuf_ExtendedStats {
UInt maxAllocatedBlocks;
UInt numAllocatedBlocks;
} HeapBuf_ExtendedStats;
FIELDS
maxAllocatedBlocks
The maximum number of blocks allocated from
this heap at any single point in time, during
the lifetime of this HeapBuf instance.
numAllocatedBlocks
The total number of blocks currently
allocated in this HeapBuf instance.
config HeapBuf_A_bufAlign // module-wide |
|
Misalligned buffer
DETAILS
This Assert is raised when the buf parameter has not been aligned
on the requested alignment.
config HeapBuf_A_invalidAlign // module-wide |
|
Invalid alignment
extern const Assert_Id HeapBuf_A_invalidAlign;
DETAILS
This Assert is raised when the align parameter is not the default
value of zero, or a power of 2 that is greater than or equal to
the value defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign.
config HeapBuf_A_invalidBufSize // module-wide |
|
Invalid buffer size
extern const Assert_Id HeapBuf_A_invalidBufSize;
DETAILS
This Assert is raised when the bufSize parameter is too small
to handle requested blocks.
config HeapBuf_A_invalidFree // module-wide |
|
Assert raised when an invalid free occurs
extern const Assert_Id HeapBuf_A_invalidFree;
DETAILS
This assert can be caused when passing a NULL pointer to the free.
config HeapBuf_A_noBlocksToFree // module-wide |
|
No allocated blocks
extern const Assert_Id HeapBuf_A_noBlocksToFree;
DETAILS
This Assert is raised when free is called and there are no blocks
allocated.
config HeapBuf_A_nullBuf // module-wide |
|
Null buf parameter
DETAILS
This Assert is raised when the buf parameter has been omitted (null)
for a dynamic create.
config HeapBuf_A_zeroBlockSize // module-wide |
|
Assert raised when the blockSize parameter is 0
extern const Assert_Id HeapBuf_A_zeroBlockSize;
config HeapBuf_A_zeroBlocks // module-wide |
|
Assert raised when the numBlocks parameter is 0
config HeapBuf_A_zeroBufSize // module-wide |
|
Assert raised when the bufSize parameter is 0
extern const Assert_Id HeapBuf_A_zeroBufSize;
config HeapBuf_E_size // module-wide |
|
Raised when requested size exceeds blockSize
config HeapBuf_trackMaxAllocs // module-wide |
|
Track maximum number of allocations
extern const Bool HeapBuf_trackMaxAllocs;
DETAILS
This will enable/disable the tracking of the maximum number of
allocations for a HeapBuf instance. This maximum refers to the "all
time" maximum number of allocations for the history of a HeapBuf
instance, not the current number of allocations.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool HeapBuf_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapBuf_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapBuf_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapBuf_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct HeapBuf_Object HeapBuf_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapBuf_Struct HeapBuf_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 |
|
typedef struct HeapBuf_Params {
// Instance config-params structure
// Common per-instance configs
SizeT align;
// Alignment (in MAUs) of each block
SizeT blockSize;
// Size (in MAUs) of each block
Ptr buf;
// User supplied buffer; for dynamic creates only
// Size (in MAUs) of the entire buffer; for dynamic creates only
UInt numBlocks;
// Number of fixed-size blocks
} HeapBuf_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapBuf_align // instance |
|
Alignment (in MAUs) of each block
DETAILS
The alignment must be a power of 2 that is greater than or equal to
the target dependent value defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign. If the default value
of 0 is specified, this value will be changed to be the minimum
structure alignment requirement, as defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign.
For static creates, the HeapBuf module will allocate space for the
buffer and will align it on this requested alignment.
For dynamic creates, this parameter is used solely for error checking.
The buffer provided to a dynamically created HeapBuf must be aligned
manually, and an assert will be raised if the buffer is not properly
aligned. For dynamic creates, HeapBuf will NOT adjust the buffer to
satisfy the alignment.
config HeapBuf_blockSize // instance |
|
Size (in MAUs) of each block
DETAILS
HeapBuf will round the blockSize up to the nearest multiple of the
alignment, so the actual blockSize may be larger. When creating a
HeapBuf dynamically, this needs to be taken into account to determine
the proper buffer size to pass in.
Required parameter.
The default size of the blocks is 0 MAUs.
config HeapBuf_buf // instance |
|
User supplied buffer; for dynamic creates only
DETAILS
The caller must supply the memory buffer for a dynamically created
HeapBuf to manage. The provided buffer must be aligned according to the
HeapBuf's alignment parameter. i.e., if a buffer's alignment parameter
is 128, then the buffer's start address must be a multiple of 128.
For static creates, the buffer is allocated automatically based on the
blockSize and numBlocks parameters.
This parameter is required for dynamic creates and ignored for static
creates.
config HeapBuf_bufSize // instance |
|
Size (in MAUs) of the entire buffer; for dynamic creates only
DETAILS
When dynamically creating a HeapBuf, this should be the actual size
of the memory buffer provided for HeapBuf to manage.
This parameter is used solely for error checking; an Error is raised
if the bufSize is too small for the requested blockSize and numBlocks.
Because of minimum alignment considerations, it's easy to provide too
small of a buffer to manage, and difficult to detect if it happened.
This parameter is required for dynamic creates and ignored for static
creates.
The default buffer size is 0 MAUs.
config HeapBuf_numBlocks // instance |
|
Number of fixed-size blocks
DETAILS
Required parameter.
The default number of blocks is 0.
Instance Creation |
|
// 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 |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
HeapBuf_alloc() // instance |
|
Allocates a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapBuf 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.
HeapBuf_alloc will only fail if there are no available blocks or if the
requested block size is larger than the HeapBuf's blockSize. All other
requests, regardless of size, will succeed.
HEAPBUF
All alignment is handled in the create, therefore the
align argument in alloc is ignored.
RETURNS
Returns the address of the allocated memory.
HeapBuf_free() // instance |
|
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapBuf 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.
HeapBuf_getExtendedStats() // instance |
|
Retrieves the extended statistics for a HeapBuf instance
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
stats
Location for the returned extended statistics.
DETAILS
This function retrieves the extended statistics for a HeapBuf instance.
It does not retrieve the standard xdc.runtime.Memory.Stats information.
HeapBuf_getStats() // instance |
|
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapBuf 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.
HeapBuf_isBlocking() // instance |
|
Returns whether the heap may block during an alloc() or
free()
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
HEAPBUF
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 |
|
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins |
|
Int HeapBuf_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
struct HeapBuf.ExtendedStats |
|
Stat structure for the HeapBuf_getExtendedStats function
XDCscript usage |
meta-domain |
var obj = new HeapBuf.ExtendedStats;
obj.maxAllocatedBlocks = UInt ...
obj.numAllocatedBlocks = UInt ...
FIELDS
maxAllocatedBlocks
The maximum number of blocks allocated from
this heap at any single point in time, during
the lifetime of this HeapBuf instance.
numAllocatedBlocks
The total number of blocks currently
allocated in this HeapBuf instance.
C SYNOPSIS
config HeapBuf.A_bufAlign // module-wide |
|
Misalligned buffer
XDCscript usage |
meta-domain |
msg: "buf not properly aligned"
};
DETAILS
This Assert is raised when the buf parameter has not been aligned
on the requested alignment.
C SYNOPSIS
config HeapBuf.A_invalidAlign // module-wide |
|
Invalid alignment
XDCscript usage |
meta-domain |
msg: "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"
};
DETAILS
This Assert is raised when the align parameter is not the default
value of zero, or a power of 2 that is greater than or equal to
the value defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign.
C SYNOPSIS
config HeapBuf.A_invalidBufSize // module-wide |
|
Invalid buffer size
XDCscript usage |
meta-domain |
msg: "HeapBuf_create's bufSize parameter is invalid (too small)"
};
DETAILS
This Assert is raised when the bufSize parameter is too small
to handle requested blocks.
C SYNOPSIS
config HeapBuf.A_invalidFree // module-wide |
|
Assert raised when an invalid free occurs
XDCscript usage |
meta-domain |
msg: "A_invalidFree: Invalid free"
};
DETAILS
This assert can be caused when passing a NULL pointer to the free.
C SYNOPSIS
config HeapBuf.A_noBlocksToFree // module-wide |
|
No allocated blocks
XDCscript usage |
meta-domain |
msg: "Cannot call HeapBuf_free when no blocks have been allocated"
};
DETAILS
This Assert is raised when free is called and there are no blocks
allocated.
C SYNOPSIS
config HeapBuf.A_nullBuf // module-wide |
|
Null buf parameter
XDCscript usage |
meta-domain |
msg: "buf parameter cannot be null"
};
DETAILS
This Assert is raised when the buf parameter has been omitted (null)
for a dynamic create.
C SYNOPSIS
config HeapBuf.A_zeroBlockSize // module-wide |
|
Assert raised when the blockSize parameter is 0
XDCscript usage |
meta-domain |
msg: "blockSize cannot be zero"
};
C SYNOPSIS
config HeapBuf.A_zeroBlocks // module-wide |
|
Assert raised when the numBlocks parameter is 0
XDCscript usage |
meta-domain |
msg: "numBlocks cannot be zero"
};
C SYNOPSIS
config HeapBuf.A_zeroBufSize // module-wide |
|
Assert raised when the bufSize parameter is 0
XDCscript usage |
meta-domain |
msg: "bufSize cannot be zero"
};
C SYNOPSIS
config HeapBuf.E_size // module-wide |
|
Raised when requested size exceeds blockSize
XDCscript usage |
meta-domain |
msg: "requested size is too big: handle=0x%x, size=%u"
};
C SYNOPSIS
config HeapBuf.trackMaxAllocs // module-wide |
|
Track maximum number of allocations
XDCscript usage |
meta-domain |
HeapBuf.trackMaxAllocs = Bool false;
DETAILS
This will enable/disable the tracking of the maximum number of
allocations for a HeapBuf instance. This maximum refers to the "all
time" maximum number of allocations for the history of a HeapBuf
instance, not the current number of allocations.
C SYNOPSIS
metaonly config HeapBuf.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.
Instance Config Parameters |
|
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
// Instance config-params object
params.align = SizeT 0;
// Alignment (in MAUs) of each block
params.blockSize = SizeT 0;
// Size (in MAUs) of each block
params.buf = Ptr 0;
// User supplied buffer; for dynamic creates only
params.bufSize = UArg 0;
// Size (in MAUs) of the entire buffer; for dynamic creates only
params.numBlocks = UInt 0;
// Number of fixed-size blocks
params.sectionName = String null;
// Section name for the buffer managed by the instance
config HeapBuf.align // instance |
|
Alignment (in MAUs) of each block
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.align = SizeT 0;
DETAILS
The alignment must be a power of 2 that is greater than or equal to
the target dependent value defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign. If the default value
of 0 is specified, this value will be changed to be the minimum
structure alignment requirement, as defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign.
For static creates, the HeapBuf module will allocate space for the
buffer and will align it on this requested alignment.
For dynamic creates, this parameter is used solely for error checking.
The buffer provided to a dynamically created HeapBuf must be aligned
manually, and an assert will be raised if the buffer is not properly
aligned. For dynamic creates, HeapBuf will NOT adjust the buffer to
satisfy the alignment.
C SYNOPSIS
config HeapBuf.blockSize // instance |
|
Size (in MAUs) of each block
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.blockSize = SizeT 0;
DETAILS
HeapBuf will round the blockSize up to the nearest multiple of the
alignment, so the actual blockSize may be larger. When creating a
HeapBuf dynamically, this needs to be taken into account to determine
the proper buffer size to pass in.
Required parameter.
The default size of the blocks is 0 MAUs.
C SYNOPSIS
config HeapBuf.buf // instance |
|
User supplied buffer; for dynamic creates only
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.buf = Ptr 0;
DETAILS
The caller must supply the memory buffer for a dynamically created
HeapBuf to manage. The provided buffer must be aligned according to the
HeapBuf's alignment parameter. i.e., if a buffer's alignment parameter
is 128, then the buffer's start address must be a multiple of 128.
For static creates, the buffer is allocated automatically based on the
blockSize and numBlocks parameters.
This parameter is required for dynamic creates and ignored for static
creates.
C SYNOPSIS
config HeapBuf.bufSize // instance |
|
Size (in MAUs) of the entire buffer; for dynamic creates only
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.bufSize = UArg 0;
DETAILS
When dynamically creating a HeapBuf, this should be the actual size
of the memory buffer provided for HeapBuf to manage.
This parameter is used solely for error checking; an Error is raised
if the bufSize is too small for the requested blockSize and numBlocks.
Because of minimum alignment considerations, it's easy to provide too
small of a buffer to manage, and difficult to detect if it happened.
This parameter is required for dynamic creates and ignored for static
creates.
The default buffer size is 0 MAUs.
C SYNOPSIS
config HeapBuf.numBlocks // instance |
|
Number of fixed-size blocks
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.numBlocks = UInt 0;
DETAILS
Required parameter.
The default number of blocks is 0.
C SYNOPSIS
metaonly config HeapBuf.sectionName // instance |
|
Section name for the buffer managed by the instance
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.sectionName = String null;
DETAILS
The buffer allocated for a statically created HeapBuf instance will be
placed in this section.
The default section is the 'dataSection' in the platform.
Instance Creation |
|
XDCscript usage |
meta-domain |
var params =
new HeapBuf.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapBuf.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.