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.
The configuration parameter
trackMaxAllocs must be set to true
for this field to have any meaning.
Otherwise, this field will be set to '0'.
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_invalidBlockSize // module-wide |
|
Assert raised when the blockSize parameter is not large enough to
hold two pointers
extern const Assert_Id HeapBuf_A_invalidBlockSize;
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 for the following reasons
- Passing a NULL pointer to the free.
- The block is not within the heap's buffer range. This can occur if
the block is freed to the wrong heap.
- The block is not on the proper boundary. This can occur if the
pointer returned from alloc is changed by the application and not set
back to its original value when free is called.
config HeapBuf_A_invalidRequestedAlign // module-wide |
|
Invalid alignment parameter in the alloc
extern const Assert_Id HeapBuf_A_invalidRequestedAlign;
DETAILS
This Assert is raised when the align argument is not a power of 2 (or 0).
It is also raised if the parameter is greater the alignment
specified when creating the heap.
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_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_Params.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_Params.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_Params.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_Params.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_Params.numBlocks // instance |
|
Number of fixed-size blocks
DETAILS
Required parameter.
The default number of blocks is 0.
Runtime 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
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.
The configuration parameter
trackMaxAllocs must be set to true
for this field to have any meaning.
Otherwise, this field will be set to '0'.
numAllocatedBlocks
The total number of blocks currently
allocated in this HeapBuf instance.
C SYNOPSIS
config HeapBuf.A_bufAlign // module-wide |
|
Misalligned buffer
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
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_invalidBlockSize // module-wide |
|
Assert raised when the blockSize parameter is not large enough to
hold two pointers
msg: "blockSize must be large enough to hold atleast two pointers"
};
C SYNOPSIS
config HeapBuf.A_invalidBufSize // module-wide |
|
Invalid buffer size
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
msg: "A_invalidFree: Invalid free"
};
DETAILS
This assert can be caused for the following reasons
- Passing a NULL pointer to the free.
- The block is not within the heap's buffer range. This can occur if
the block is freed to the wrong heap.
- The block is not on the proper boundary. This can occur if the
pointer returned from alloc is changed by the application and not set
back to its original value when free is called.
C SYNOPSIS
config HeapBuf.A_invalidRequestedAlign // module-wide |
|
Invalid alignment parameter in the alloc
msg: "align parameter 1) must be 0 or a power of 2 and 2) not greater than the heaps alignment"
};
DETAILS
This Assert is raised when the align argument is not a power of 2 (or 0).
It is also raised if the parameter is greater the alignment
specified when creating the heap.
C SYNOPSIS
config HeapBuf.A_noBlocksToFree // module-wide |
|
No allocated blocks
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
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_zeroBlocks // module-wide |
|
Assert raised when the numBlocks parameter is 0
msg: "numBlocks cannot be zero"
};
C SYNOPSIS
config HeapBuf.A_zeroBufSize // module-wide |
|
Assert raised when the bufSize parameter is 0
msg: "bufSize cannot be zero"
};
C SYNOPSIS
config HeapBuf.E_size // module-wide |
|
Raised when requested size exceeds blockSize
msg: "requested size is too big: handle=0x%x, size=%u"
};
C SYNOPSIS
config HeapBuf.trackMaxAllocs // module-wide |
|
Track maximum number of allocations
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
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 |
|
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.Params.align // instance |
|
Alignment (in MAUs) of each block
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.Params.blockSize // instance |
|
Size (in MAUs) of each block
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.Params.buf // instance |
|
User supplied buffer; for dynamic creates only
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.Params.bufSize // instance |
|
Size (in MAUs) of the entire buffer; for dynamic creates only
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.Params.numBlocks // instance |
|
Number of fixed-size blocks
var params = new HeapBuf.Params;
...
params.numBlocks = UInt 0;
DETAILS
Required parameter.
The default number of blocks is 0.
C SYNOPSIS
metaonly config HeapBuf.Params.sectionName // instance |
|
Section name for the buffer managed by the instance
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.
Static Instance Creation |
|
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.