RTOS

Task
Event

Memory allocation

group MemAlloc

Memory management.

This provides support for memory allocation in internal memories of GAP8/GAP9.

There are 3 types of memory :

L2 memory : L2 memory used by both FC and cluster cores(using delegation).
FC TCDM memory or L2 Private : L1 memory close to Fabric Controller.
Cluster L1 memory : L1 memory used by the cluster cores and NE16.

Functions

void pi_malloc_init(void)

Initialize the memory allocators.

This function initializes the FC and L2 memory allocators to allocate from the FC or L2 memory heap.

Note

If this function is called first, those subfunctions do not need to be called.

int32_t pi_alloc_fail(pi_allocator_name_e allocator, int32_t size)

Called if an allocation failed.

Note

Function is weak and can be overriden default implementation will dump the allocator state

Parameters:

allocator – Allocator structure
size – Size of the failed allocation

void *pi_malloc(size_t size)

Allocate memory from FC or L2 memory allocator.

This function allocates a memory chunk in FC if there is enough memory to allocate otherwise in L2. BEWARE, in GAP9, it will allocate memory from L2 ONLY.

Parameters:

size – Size of the memory to be allocated.

Returns:

Pointer to an allocated memory chunk or NULL if there is not enough memory to allocate.

void *pi_malloc_align(size_t size, uint32_t align)

Allocate memory from FC or L2 memory allocator with aligned address.

This function allocates an adress aligned memory chunk in FC if there is enough memory to allocate required chunk of memory otherwise in L2.

Parameters:

size – Size of the memory to be allocated.
align – Memory alignement size.

Returns:

Pointer to an allocated memory chunk or NULL if there is not enough memory to allocate.

void pi_free(void *_chunk)

Free an allocated memory chunk.

This function frees an allocated memory chunk.

Parameters:

_chunk – Start address of an allocated memory chunk.

void pi_malloc_dump(void)

Display free blocks.

This function displays free blocks available in either FC or L2 memory.

group L2_Malloc

Memory allocation in L2 memory from FC.

Functions

void *pi_l2_malloc(int32_t size)

Allocate in L2 memory.

The allocated memory is 4-bytes aligned. The caller has to provide back the size of the allocated chunk when freeing it.

Parameters:

size – Size in bytes of the memory to be allocated.

Returns:

The allocated chunk or NULL if there was not enough memory available.

void pi_l2_free(void *chunk, int32_t size)

Free L2 memory.

Parameters:

chunk – Chunk to be freed.
size – Size in bytes of the memory to be freed.

void *pi_l2_malloc_align(int32_t size, int32_t align)

Allocate in L2 memory.

The allocated memory is aligned on the specified number of bytes. The caller has to provide back the size of the allocated chunk when freeing it.

Parameters:

size – Size in bytes of the memory to be allocated.
align – Alignment in bytes.

Returns:

The allocated chunk or NULL if there was not enough memory available.

void pi_l2_malloc_dump(void)

Display free blocks.

This function can be used to display free blocks available from the L2 allocator.

void pi_l2_available_get(uint32_t *totalMemAvailable, uint32_t *largestMemAllocatable)

Get available blocks in L2.

This function can be used to get free blocks available from the L2 allocator.

Parameters:

totalMemAvailable – Size in bytes of total available L2.
largestMemAllocatable – Size in bytes of largest free block.

void pi_l2_watermark_get(uint32_t *lowestMemAvailable, uint32_t *currentMemAvailable)

Get free bytes watermark in L2.

This function can be used to get free blocks available watermark from the L2 allocator.

Parameters:

lowestMemAvailable – Lowest amount of bytes ever avaialble in L2.
currentMemAvailable – Amount of bytes currently available for allocation in L2

void pi_l2_watermark_reset(uint32_t startTracking)

Reset and optionally start tracking watermark of free space in heap.

This function can be used to reset and optionally start tracking watermark of free space in heap

void pi_fc_l1_available_get(uint32_t *totalMemAvailable, uint32_t *largestMemAllocatable)

Get available blocks in L2 Private.

This function can be used to get free blocks available from the L2 private.

Parameters:

totalMemAvailable – Size in bytes of total available L2.
largestMemAllocatable – Size in bytes of largest free block.

group CL_L1_Malloc

Memory allocation in Cluster L1 memory.

Functions

void *pi_cl_l1_malloc(pi_device_t *device, uint32_t size)

Allocate in Cluster L1 memory.

The allocated memory is 4-bytes aligned. The caller has to provide back the size of the allocated chunk when freeing it. This can be called only when the speficied cluster is opened.

Parameters:

device – Cluster device where to allocate memory.
size – Size in bytes of the memory to be allocated.

Returns:

The allocated chunk or NULL if there was not enough memory available.

void pi_cl_l1_free(pi_device_t *device, void *chunk, int32_t size)

Free Cluster L1 memory.

This can be called only when the speficied cluster is opened.

Parameters:

device – Cluster device where to free memory.
chunk – Chunk to be freed.
size – Size in bytes of the memory to be freed.

void *pi_cl_l1_malloc_align(pi_device_t *device, int32_t size, int32_t align)

Allocate in Cluster L1 memory.

The allocated memory is aligned on the specified number of bytes. The caller has to provide back the size of the allocated chunk when freeing it. This can be called only when the speficied cluster is opened.

Parameters:

device – Cluster device where to allocate memory.
size – Size in bytes of the memory to be allocated.
align – Alignment in bytes.

Returns:

The allocated chunk or NULL if there was not enough memory available.

void pi_cl_l1_malloc_dump(void)

Display free blocks.

This function can be used to display free blocks available from the CL L1 allocator.

void pi_cl_l1_available_get(uint32_t *totalMemAvailable, uint32_t *largestMemAllocatable)

Get available blocks in cluster L1.

This function can be used to get free blocks available from the L1 in cluster.

Parameters:

totalMemAvailable – Size in bytes of total available L2.
largestMemAllocatable – Size in bytes of largest free block.

group HOST_SYNC_ACCESS

This file provides an API to synchronize access to a dynamically loaded memory area. The typical case is for lazy load, from an external source or a special flash file. It can be also use for command and notification.

The host sync access API allows to synchronize access to a dynamically loaded memory area. The typical case is for lazy load, from an external source or a special flash file. It can be also use for command and notification.

Typedefs

typedef struct pi_host_sync_s pi_host_sync_t

Functions

int32_t pi_host_sync_init(pi_host_sync_t *area, uintptr_t addr, size_t size)

Add an evt to wait list.

This function is used to add an event to a region wait list. Once the region is ready (loaded), all events will be signaled.

Parameters:

area – Pointer to memory area info
addr – Start address for the region
size – Size of the region

Return values:

PI_OK – Success.
PI_ERR – Error code.

int32_t pi_host_sync_ready_wait(pi_host_sync_t *area)

Add an event to wait list, and immediately wait for it.

This function is used to add an event to a region wait list, and block on it. Event creation is handled by function itself. Once the region is ready (loaded), all events will be signaled. If the region is ready, event will be signaled immediately.

Parameters:

area – Pointer to memory area info

Return values:

PI_OK – Success.
PI_ERR – Error code.

int32_t pi_host_sync_ready_wait_async(pi_host_sync_t *area, pi_evt_t *evt)

Add an evt to wait list.

This function is used to add an event to a region wait list. Once the region is ready (loaded), all events will be signaled. If the region is ready, event will be signaled immediately.

Parameters:

area – Pointer to memory area info
evt – Event used to be pushed to wait list

Return values:

PI_OK – Success.
PI_ERR – Error code.

int32_t pi_host_sync_ready_signal(pi_host_sync_t *area)

Set a region as ready to be used (loaded) and signal all waiters.

This function is used to signal the region passed as argument as ready. All events in wait list will be signaled.

Parameters:

area – Pointer to memory area info
evt – Event used to be pushed to wait list

Return values:

PI_OK – Success.
PI_ERR – Error code.

struct pi_host_sync_s

Public Members

uintptr_t addr: Address of the memory area.

size_t size: Size of the memory area

pi_evt_t *wait_list: List of events to execute when ready

int8_t rdy: True if region is already loaded

struct pi_host_sync_t

#include <host_sync_access.h>

Dynamically loaded memory area infos.

This structure is used to describe the state of a host sync memory area

Errors Definition

group Error_Def

Enums

enum pi_err_t

RTOS Errors’ definition.

Values:

enumerator PI_OK = 0x00: indicating success (no error)

enumerator PI_FAIL = 0x01: Generic code indicating failure

enumerator PI_ERR_INVALID_ARG = 0x02: Invalid argument

enumerator PI_ERR_INVALID_STATE = 0x03: Invalid state

enumerator PI_ERR_INVALID_SIZE = 0x04: Invalid size

enumerator PI_ERR_NOT_FOUND = 0x05: Requested resource not found

enumerator PI_ERR_NOT_SUPPORTED = 0x06: Operation or feature not supported

enumerator PI_ERR_TIMEOUT = 0x07: Operation timed out

enumerator PI_ERR_INVALID_CRC = 0x08: CRC or checksum was invalid

enumerator PI_ERR_INVALID_VERSION = 0x09: Version was invalid

enumerator PI_ERR_INVALID_APP = 0x0A: App binary is not compliant with GAP.

enumerator PI_ERR_INVALID_MAGIC_CODE = 0x0B: Magic code does not match.

enumerator PI_ERR_ALREADY_EXISTS = 0x0C

enumerator PI_ERR_I2C_NACK = 0x100: An item already exists.

enumerator PI_ERR_NO_MEM = 0x200: I2C request ended with a NACK Generic out of memory

enumerator PI_ERR_L2_NO_MEM = 0x201: L2 out of memory