Partition Memory in Nucleus RTOS/SE: Utility Services and Data Structures

View the RTOS Revealed series

Building on our previous exploration of RTOS partition memory, this article delves into the practical utilities and underlying data structures that enable efficient memory management in Nucleus RTOS and its streamlined edition, Nucleus SE.

Partition Pool Utility Services

Nucleus RTOS offers three dedicated API calls that provide essential information and management capabilities for partition pools: retrieving detailed pool information, determining the total number of pools in an application, and acquiring pointers to all pool structures. The first two functions are fully supported in Nucleus SE, albeit with some feature differences due to its reduced feature set.

Obtaining Partition Pool Information

The NU_Partition_Pool_Information service returns a comprehensive snapshot of a specified partition pool. In Nucleus SE, the function returns a pared‑down set of data, reflecting the absence of object naming, suspend ordering, and task suspend support.

Nucleus RTOS API Call for Partition Pool Information

Service call prototype:

STATUS NU_Partition_Pool_Information(NU_PARTITION_POOL *pool, CHAR *name, VOID **start_address, UNSIGNED *pool_size, UNSIGNED *partition_size, UNSIGNED *available, UNSIGNED *allocated, OPTION *suspend_type, UNSIGNED *tasks_waiting, NU_TASK **first_task);

Parameters:

pool – pointer to the partition pool for which information is requested.

name – pointer to an 8‑character buffer that will receive the pool’s name (including the null terminator).

start_address – pointer to a variable that will receive the base address of the pool’s data area.

pool_size – pointer to a variable that will receive the total pool size in bytes.

partition_size – pointer to a variable that will receive the size of each partition.

available – pointer to a variable that will receive the count of currently free partitions.

allocated – pointer to a variable that will receive the count of partitions in use.

suspend_type – pointer to a variable that will receive the suspend policy (valid values: NU_FIFO or NU_PRIORITY).

tasks_waiting – pointer to a variable that will receive the number of tasks suspended on this pool.

first_task – pointer to a variable that will receive the pointer to the first suspended task.

Returns:

NU_SUCCESS – operation succeeded.

NU_INVALID_POOL – the provided pool pointer is invalid.

Nucleus SE API Call for Partition Pool Information

In Nucleus SE, the same functionality is provided via the streamlined interface below. Because SE does not support task suspend, related fields are omitted.

Service call prototype:

STATUS NUSE_Partition_Pool_Information(NUSE_PARTITION_POOL pool, ADDR *start_address, U32 *pool_size, U16 *partition_size, U8 *available, U8 *allocated, U8 *tasks_waiting, NUSE_TASK *first_task)

Parameters:

pool – the index of the partition pool.

start_address – pointer to a variable that will receive the base address of the pool’s data area.

pool_size – pointer to a variable that will receive the total pool size in bytes.

partition_size – pointer to a variable that will receive the size of each partition.

available – pointer to a variable that will receive the number of free partitions.

allocated – pointer to a variable that will receive the number of used partitions.

tasks_waiting – pointer to a variable that will receive the number of waiting tasks (zero if task suspend is disabled).

first_task – pointer to a variable that will receive the index of the first suspended task (zero if task suspend is disabled).

Returns:

NUSE_SUCCESS – operation succeeded.

NUSE_INVALID_POOL – the pool index is invalid.

NUSE_INVALID_POINTER – one or more pointer arguments are null.

Nucleus SE Implementation of Partition Pool Information

The SE implementation is concise: the routine populates the requested fields and, when blocking APIs are enabled, sets the waiting‑task count and the first task index (otherwise these fields are zeroed).

Obtaining the Number of Partition Pools

This service returns the total number of partition pools defined in the application. In Nucleus RTOS, the count can change dynamically as pools are created or destroyed; in Nucleus SE, the count is fixed at build time.

Nucleus RTOS API Call for Number of Partition Pools

Service call prototype:

UNSIGNED NU_Established_Partition_Pools(VOID);

Parameters: None.

Returns: The current number of active partition pools.

Nucleus SE API Call for Number of Partition Pools

Service call prototype:

U8 NUSE_Partition_Pool_Count(void);

Parameters: None.

Returns: The number of partition pools configured at compile time.

Implementation

The SE routine simply returns the value of the compile‑time constant NUSE_PARTITION_POOL_NUMBER.