AN672

Rev. 0.1

11

manner. These functions are provided by the si32BaseComponent and should be used for all dynamic memory

allocation because they provided tracked, aligned, memory management transparently to the library and its

applications.

6.2.1. Allocation of Objects

Objects must be allocated and initialized before they can be used. They are typically allocated on the stack as

automatic variables. For example:

si32UsartAPortalObject my_usart = si32UsartAPortalObject();

Objects whose lifetime must exceed that of the scope in which they are defined can be declared static, just like any

other variable in C.

static si32UsartAPortalObject my_usart = si32UsartAPortalObject();

Objects can also be dynamically allocated.

si32UsartAPortalObject* my_usart = si32UsartAPortalObject_allocate();

Objects are allocated from the default allocation zone, one of the si32AllocationZoneEnumType values:

SI32_RETENTION_ZONE,

SI32_INCREMENTAL_ZONE,

or

SI32_HEAP_ZONE.

The

default

zone

is

SI32_HEAP_ZONE. Applications are free to change the default allocation zone at runtime.

Both the retention zone and the incremental zone are incremental. They are simply blocks of bytes, and each

allocation request just advances a pointer within the zone by the amount requested. Allocating from these zones

does not incur additional RAM overhead. However, it is not possible to reclaim memory allocated from these zones

except by resetting the entire zone. They are intended to support a programming model wherein all memory is

preallocated at startup time and persists throughout the duration of the program's execution.

The heap zone is implemented using the allocator provided by the tool chain. It allows dynamic deallocation and

reallocation, at the cost of potential memory fragmentation and subsequent compaction.

To determine the default allocation zone use:

si32AllocationZoneEnumType si32Base_get_default_allocation_zone()

To change the default allocation use:

si32Base_set_default_allocation_zone(si32AllocationZoneEnumType zone)

6.2.2. Rules for Initializing Objects

Regardless of how an object is allocated, it should not be used until it has been initialized. Initialization sets up the

object's attributes and configures it for operation.

si32UsartAPortalObject_initialize(&my_usart,

SI32_PORTAL_OBJECT_CAPABILITY_FULL_DUPLEX

|SI32_PORTAL_OBJECT_CAPABILITY_TRANSMIT

|SI32_PORTAL_OBJECT_CAPABILITY_RECEIVE,

SI32_USART_0);

Attempting to invoke an object function on an uninitialized object results in an assertion (for debug builds) or

(occasionally) a fault.