For configuration-time
HeapMin.create, the heap is aligned to
Memory.getMaxDefaultTypeAlignMeta() for those targets that support
static alignment. For targets that do not support static alignment, the
buffer alignment is undefined.
When calling
create() at runtime, the client
is responsible for aligning the buffer.
config HeapMin_A_zeroSize // module-wide |
|
Assert that the size is non-zero on the create
config HeapMin_E_freeError // module-wide |
|
Error raised if free() is called
extern const Error_Id HeapMin_E_freeError;
DETAILS
This error is only raised if a
free()
is called and
freeError is true.
config HeapMin_freeError // module-wide |
|
Flag to control whether E_freeError is enabled
extern const Bool HeapMin_freeError;
DETAILS
If true, a
E_freeError error occurs when trying
to free a buffer.
If false, no error occurs and the
free() does nothing.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool HeapMin_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapMin_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 HeapMin_Module_getMask();
// Returns the diagnostics mask for this module
Void HeapMin_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct HeapMin_Object HeapMin_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapMin_Struct HeapMin_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 HeapMin_Params {
// Instance config-params structure
// Common per-instance configs
Ptr buf;
// Buffer that will be managed by the heap instance
// Size (in MADUs) of the heap
} HeapMin_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapMin_buf // instance |
|
Buffer that will be managed by the heap instance
DETAILS
When creating a heap at runtime, the user must supply the memory
that the heap will manage. It is up to the caller to align
the buffer as needed.
This parameter is ignored when creating heaps during configuration.
config HeapMin_size // instance |
|
Size (in MADUs) of the heap
DETAILS
This parameter specifies the size of the heap managed by a
HeapMin instance. In the static case, a buffer of length size
will be created. In the dynamic case, size specifies the size of
the buffer (i.e. parameter buf) that the caller provides.
This is a required parameter. It must be set by the caller. Failure
to do so, will result in a build error for the static create or an
A_zeroSize assert for the runtime create.
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
This heap is a growth-only heap that is intended to be used by
systems that never delete objects or free memory. Objects can be
created at runtime based on values determined at runtime, but
objects can not be deleted.
SEE
Instance Deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
HeapMin_alloc() // instance |
|
Allocate a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapMin 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.
RETURNS
Returns the address of the allocated memory.
CONSTRAINTS
The alignment must be a power of 2.
SEE
HeapMin_free() // instance |
|
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapMin 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.
This is a growth only heap. Calling the
HeapMin_free function
will result in a
E_freeError error unless
freeError is set to
false.
SEE
HeapMin_getStats() // instance |
|
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapMin 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.
HeapMin_isBlocking() // instance |
|
Can this heap block the caller
ARGUMENTS
handle
handle of a previously-created HeapMin instance object
RETURNS
If the heap might block, TRUE is returned.
If the heap does not block, FALSE is returned.
HeapMin always returns FALSE since it never blocks on a
resource.
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 HeapMin_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
config HeapMin.A_zeroSize // module-wide |
|
Assert that the size is non-zero on the create
XDCscript usage |
meta-domain |
msg: "HeapMin_create cannot have a zero size value"
};
C SYNOPSIS
config HeapMin.E_freeError // module-wide |
|
Error raised if free() is called
XDCscript usage |
meta-domain |
msg: "free() invalid in growth-only HeapMin"
};
DETAILS
This error is only raised if a
free()
is called and
freeError is true.
C SYNOPSIS
config HeapMin.freeError // module-wide |
|
Flag to control whether E_freeError is enabled
XDCscript usage |
meta-domain |
HeapMin.freeError = Bool true;
DETAILS
If true, a
E_freeError error occurs when trying
to free a buffer.
If false, no error occurs and the
free() does nothing.
C SYNOPSIS
metaonly config HeapMin.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 HeapMin.Params;
// Instance config-params object
params.align = SizeT undefined;
// Alignment of the buffer being managed by this heap instance
params.buf = Ptr 0;
// Buffer that will be managed by the heap instance
params.sectionName = String null;
// Section name of the heap
params.size = UArg 0;
// Size (in MADUs) of the heap
config HeapMin.buf // instance |
|
Buffer that will be managed by the heap instance
XDCscript usage |
meta-domain |
var params = new HeapMin.Params;
...
params.buf = Ptr 0;
DETAILS
When creating a heap at runtime, the user must supply the memory
that the heap will manage. It is up to the caller to align
the buffer as needed.
This parameter is ignored when creating heaps during configuration.
C SYNOPSIS
config HeapMin.size // instance |
|
Size (in MADUs) of the heap
XDCscript usage |
meta-domain |
var params = new HeapMin.Params;
...
params.size = UArg 0;
DETAILS
This parameter specifies the size of the heap managed by a
HeapMin instance. In the static case, a buffer of length size
will be created. In the dynamic case, size specifies the size of
the buffer (i.e. parameter buf) that the caller provides.
This is a required parameter. It must be set by the caller. Failure
to do so, will result in a build error for the static create or an
A_zeroSize assert for the runtime create.
C SYNOPSIS
metaonly config HeapMin.align // instance |
|
Alignment of the buffer being managed by this heap instance
XDCscript usage |
meta-domain |
var params = new HeapMin.Params;
...
params.align = SizeT undefined;
DETAILS
In the static HeapMin.create() call, the buffer allocated for the
HeapMin instance will have the alignment specified by this parameter
on targets that support static alignment.
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 align parameter must be a power of 2.
The default alignment of zero causes the buffer to get aligned using
Memory.getMaxDefaultTypeAlignMeta().
metaonly config HeapMin.sectionName // instance |
|
Section name of the heap
XDCscript usage |
meta-domain |
var params = new HeapMin.Params;
...
params.sectionName = String null;
DETAILS
When creating heaps during configuration, this parameter specifies
where the heap's buffer will be placed. This parameter is passed as
the section name in the
Memory.staticPlace function.
SEE
Instance Creation |
|
XDCscript usage |
meta-domain |
var params =
new HeapMin.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapMin.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
This heap is a growth-only heap that is intended to be used by
systems that never delete objects or free memory. Objects can be
created at runtime based on values determined at runtime, but
objects can not be deleted.
SEE