module xdc.runtime.Memory
index URL

Static and run-time memory manager

All memory allocations are performed either by Memory.staticPlace() at build time or through Memory_alloc() (or its varients Memory_calloc(), Memory_valloc(), etc.) at run-time. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/Memory.xdc
#include <xdc/runtime/Memory.h>
Functions
Ptr 
Memory_alloc// Allocate a block of memory from a heap(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
Ptr 
Memory_calloc// Allocate a block of memory from a heap and zero out the contents(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
Void 
Memory_free// Frees the space if the heap manager offers such functionality(IHeap_Handle heap, Ptr block, SizeT size);
SizeT 
Memory_getMaxDefaultTypeAlign// Return the largest alignment required by the target();
Void 
Memory_getStats// Obtain statistics from a heap(IHeap_Handle heap, Memory_Stats *stats);
Bool 
Memory_query// Test for a particular xdc.runtime.IHeap quality(IHeap_Handle heap, Int qual);
Ptr 
Memory_valloc// Allocate a block of memory from a heap and initialize the contents to the value specified(IHeap_Handle heap, SizeT size, SizeT align, Char value, Error_Block *eb);
Functions common to all target modules
Memory_Module_getMask// Returns the diagnostics mask for this module, Memory_Module_hasMask// Test whether this module has a diagnostics mask, Memory_Module_heap// The heap from which this module allocates memory, Memory_Module_id// Get this module's unique id, Memory_Module_setMask// Set the diagnostics mask for this module, Memory_Module_startupDone// Test if this module has completed startup
Defines
#define
Memory_Q_BLOCKING// Blocking quality (Int)1
Typedefs
typedef UArg 
Memory_Size// Type to be used to specify heap buffer sizes;
typedef struct
Memory_Stats// Memory heap statistics ...
Constants
extern const IHeap_Handle 
Memory_defaultHeapInstance// The default heap;
 
DETAILS
All memory allocations are performed either by Memory.staticPlace() at build time or through Memory_alloc() (or its varients Memory_calloc(), Memory_valloc(), etc.) at run-time.
Run-time memory management is performed by modules that implement the xdc.runtime.IHeap interface. The Memory module itself simply provides a common interface for any variety of system and application specific memory management policies implemented by IHeap modules; for example, HeadStd and HeadMin.
Heap instances are created statically or dynamically via heap specific create functions and these instances are then passed as an input parameter to the Memory calls that have a xdc.runtime.IHeap.Handle parameter.
 
const Memory_Q_BLOCKING
index URL

Blocking quality

C synopsis target-domain
#define Memory_Q_BLOCKING (Int)1
 
DETAILS
xdc.runtime.IHeaps with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
 
typedef Memory_Size
index URL

Type to be used to specify heap buffer sizes

C synopsis target-domain
typedef UArg Memory_Size;
 
 
struct Memory_Stats
index URL

Memory heap statistics

C synopsis target-domain
typedef struct Memory_Stats {
    Memory_Size totalSize;
    Memory_Size totalFreeSize;
    Memory_Size largestFreeSize;
} Memory_Stats;
 
FIELDS
totalSize — total size (in MADUs) of heap.
totalFreeSize — current size (in MADUs) of free memory in the heap
largestFreeSize — current largest contiguous free block (in MADUs)
DETAILS
This structure defines generic statistics that must be supplied by each module that implements the xdc.runtime.IHeap interface.
 
config Memory_defaultHeapInstance  // module-wide
index URL

The default heap

C synopsis target-domain
extern const IHeap_Handle Memory_defaultHeapInstance;
 
DETAILS
If no heap is specified in the Memory module's methods (i.e. heap == NULL) defaultHeapInstance is used. If defaultHeapInstance is not set (or set to null), a xdc.runtime.HeapStd heap instance is created and assigned to this configuration parameter. The size of the heap is determined by the xdc.runtime.HeapStd.HEAP_MAX parameter.
By default, all modules are configured with a null instance heap. Instances created by modules with a null instance heap are allocated from the defaultHeapInstance heap.
 
Memory_alloc()  // module-wide
index URL

Allocate a block of memory from a heap

C synopsis target-domain
Ptr Memory_alloc(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
 
ARGUMENTS
heap — heap from which the memory is allocated
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
size — requested memory block size (in MADUs)
align — alignment (in MADUs) of the block of memory
A value of 0 denotes maximum default type alignment.
eb — pointer to error block
RETURNS
If the allocation was successful, Memory_alloc() returns non-NULL pointer to the allocated and uninitialized block; otherwise it returns NULL and the error block will indicate the cause of the error.
 
Memory_calloc()  // module-wide
index URL

Allocate a block of memory from a heap and zero out the contents

C synopsis target-domain
Ptr Memory_calloc(IHeap_Handle heap, SizeT size, SizeT align, Error_Block *eb);
 
ARGUMENTS
heap — heap from which the memory is allocated
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
size — requested memory block size (in MADUs)
align — alignment (in MADUs) of the block of memory
A value of 0 denotes maximum default type alignment.
eb — pointer to error block
RETURNS
If the allocation was successful, Memory_calloc() returns non-NULL pointer to the allocated and initialized block; otherwise it returns NULL and the error block will indicate the cause of the error.
 
Memory_free()  // module-wide
index URL

Frees the space if the heap manager offers such functionality

C synopsis target-domain
Void Memory_free(IHeap_Handle heap, Ptr block, SizeT size);
 
ARGUMENTS
heap — heap that the block of memory will be freed back to.
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
block — block of memory to free back to the heap
size — size (in MADUs) of the block of memory to free.
 
Memory_getMaxDefaultTypeAlign()  // module-wide
index URL

Return the largest alignment required by the target

C synopsis target-domain
SizeT Memory_getMaxDefaultTypeAlign();
 
DETAILS
getMaxDefaultTypeAlign returns the largest alignment required for all the standard base types supported by the current configuration's target (Program.build.target)
This is the runtime version of the getMaxDefaultTypeAlignMeta function.
RETURNS
Returns target-specific alignment in MADUs.
SEE
getMaxDefaultTypeAlignMeta
 
Memory_getStats()  // module-wide
index URL

Obtain statistics from a heap

C synopsis target-domain
Void Memory_getStats(IHeap_Handle heap, Memory_Stats *stats);
 
ARGUMENTS
heap — the heap to get the statistics from
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
stats — the output buffer for the returned statistics
 
Memory_query()  // module-wide
index URL

Test for a particular xdc.runtime.IHeap quality

C synopsis target-domain
Bool Memory_query(IHeap_Handle heap, Int qual);
 
ARGUMENTS
heap — the heap to query
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is queried
qual — quality to test
For example: Q_BLOCKING.
DETAILS
There currently is only one quality, namely Q_BLOCKING.
RETURNS
If heap has the qual quality, this method returns TRUE, otherwise it returns FALSE.
 
Memory_valloc()  // module-wide
index URL

Allocate a block of memory from a heap and initialize the contents to the value specified

C synopsis target-domain
Ptr Memory_valloc(IHeap_Handle heap, SizeT size, SizeT align, Char value, Error_Block *eb);
 
ARGUMENTS
heap — heap from which the memory is allocated
The heap is created by a module that implements the xdc.runtime.IHeap interface. If heap is NULL, the defaultHeapInstance is used.
size — requested memory block size (in MADUs)
align — alignment (in MADUs) of the block of memory
A value of 0 denotes maximum default type alignment.
value — value to initialize the contents of the block
eb — pointer to error block
RETURNS
If the allocation was successful, Memory_valloc() returns non-NULL pointer to the allocated and initialized block; otherwise it returns NULL and the error block will indicate the cause of the error.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId Memory_Module_id();
// Get this module's unique id
 
Bool Memory_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Memory_Module_heap();
// The heap from which this module allocates memory
 
Bool Memory_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 Memory_Module_getMask();
// Returns the diagnostics mask for this module
 
Void Memory_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
Configuration settings sourced in xdc/runtime/Memory.xdc
var Memory = xdc.useModule('xdc.runtime.Memory');
module-wide constants & types
    const Memory.Q_BLOCKING// Blocking quality = 1;
 
    var obj = new Memory.Stats// Memory heap statistics;
        obj.totalSize = UArg  ...
        obj.totalFreeSize = UArg  ...
        obj.largestFreeSize = UArg  ...
module-wide config parameters
    Memory.defaultHeapInstance// The default heap = IHeap.Handle undefined;
 
    Memory.common$// Common module configuration parameters = Types.Common$ undefined;
    Memory.defaultHeapSize// The size (in target MADUs) of the defaultHeapInstance = Int 0x1000;
module-wide functions
    Memory.getMaxDefaultTypeAlignMeta// Return the largest alignment required by the target() returns SizeT
    Memory.staticPlace// Statically places buffers(Any obj, SizeT align, String section) returns Bool
 
 
const Memory.Q_BLOCKING
index URL

Blocking quality

Configuration settings
const Memory.Q_BLOCKING = 1;
 
DETAILS
xdc.runtime.IHeaps with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
C SYNOPSIS
Memory_Q_BLOCKING
 
struct Memory.Stats
index URL

Memory heap statistics

Configuration settings
var obj = new Memory.Stats;
 
    obj.totalSize = UArg  ...
    obj.totalFreeSize = UArg  ...
    obj.largestFreeSize = UArg  ...
 
FIELDS
totalSize — total size (in MADUs) of heap.
totalFreeSize — current size (in MADUs) of free memory in the heap
largestFreeSize — current largest contiguous free block (in MADUs)
DETAILS
This structure defines generic statistics that must be supplied by each module that implements the xdc.runtime.IHeap interface.
C SYNOPSIS
Memory_Stats
 
config Memory.defaultHeapInstance  // module-wide
index URL

The default heap

Configuration settings
Memory.defaultHeapInstance = IHeap.Handle undefined;
 
DETAILS
If no heap is specified in the Memory module's methods (i.e. heap == NULL) defaultHeapInstance is used. If defaultHeapInstance is not set (or set to null), a xdc.runtime.HeapStd heap instance is created and assigned to this configuration parameter. The size of the heap is determined by the xdc.runtime.HeapStd.HEAP_MAX parameter.
By default, all modules are configured with a null instance heap. Instances created by modules with a null instance heap are allocated from the defaultHeapInstance heap.
C SYNOPSIS
Memory_defaultHeapInstance
 
metaonly config Memory.common$  // module-wide
index URL

Common module configuration parameters

Configuration settings
Memory.common$ = Types.Common$ undefined;
 
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.
 
metaonly config Memory.defaultHeapSize  // module-wide
index URL

The size (in target MADUs) of the defaultHeapInstance

Configuration settings
Memory.defaultHeapSize = Int 0x1000;
 
DETAILS
This parameters is used when the defaultHeapInstance is not configured.
 
metaonly Memory.getMaxDefaultTypeAlignMeta()  // module-wide
index URL

Return the largest alignment required by the target

Configuration settings
Memory.getMaxDefaultTypeAlignMeta() returns SizeT
 
DETAILS
This method scans the standard base types supported by the current configuration's target (Program.build.target) and returns the largest alignment required for these types.
RETURNS
Returns target-specific alignment in MADUs.
SEE
xdc.bld.ITarget.stdTypes
 
metaonly Memory.staticPlace()  // module-wide
index URL

Statically places buffers

Configuration settings
Memory.staticPlace(Any obj, SizeT align, String section) returns Bool
 
ARGUMENTS
obj — object to place
This object always has the length property; obj.length determines the size of the allocated buffer for obj
align — the alignment required by obj
section — section name to contain obj
This parameter names the section where obj will be placed. If this parameter is null, no explicit placement is done.
DETAILS
This function places the object specified by obj into the specified memory section. The section string is a target-specific name that is interpreted by the underlying target tool-chain. In the case of TI tool-chains, this section can be a subsection (e.g. ".data:someSection").
The amount of memory that is created for obj is dependent on its size and the value of the property length. The length (number of elements in an array) is set before the staticPlace() is called. For example, setting obj.length = 5; before calling staticPlace(), will create 5 * sizeof (obj) MADUs of memory.
If 0 is specified for the alignment, the allocated buffer is aligned as determined by the target toolchain. For instance, if obj is an array of structs that have only 16-bit integers, the alignment would be on a 16-bit boundary.
All non-zero alignments must be a power of 2. Not all targets support directives that allow one to specify alignment. The readonly config parameter Program.build.target.alignDirectiveSupported can be used to determine if the target supports alignment directives.
RETURNS
Returns false if the alignment request cannot be honored. The obj is still placed regardless of the return code.
generated on Thu, 23 May 2019 00:24:46 GMT