Partition Memory in Nucleus SE: Configuration, APIs, and Best Practices

View the RTOS Revealed series

Memory partitions were first introduced in our earlier article, where we compared them to the conventional C malloc() function. A partition is a fixed‑size memory block that comes from a partition pool, offering deterministic allocation and deallocation that tasks can rely on.

Using Partitions

In Nucleus SE, partition pools are defined at compile time. Up to 16 pools can be configured per application. If no pools are defined, all related data structures and API code are omitted from the build, keeping the footprint minimal.

A pool is simply a contiguous memory area divided into a set number of identical partitions. The application controls the size and count of each pool. Tasks request a partition and receive a pointer to the block. It is the caller’s responsibility to stay within the allocated bounds. A partition can be returned to the pool by any task via the deallocate API. If the pool is exhausted, the call may return an error or suspend the task, depending on the API parameters and build options.

Configuring Memory Partitions

Number of Partition Pools

Partition pools are enabled through #define statements in nuse_config.h. The key symbol is NUSE_PARTITION_POOL_NUMBER, which sets the count of pools. The default is 0, meaning no pools are active. Valid values range from 1 to 16; an invalid value triggers a compile‑time #error generated by nuse_config_check.h.

Setting a non‑zero value activates the necessary data structures and initialises them in ROM. It also unlocks the API enable symbols described below.

API Enables

Each service call has an enable macro in nuse_config.h. For partitions the following symbols exist:

• NUSE_PARTITION_ALLOCATE
• NUSE_PARTITION_DEALLOCATE
• NUSE_PARTITION_POOL_INFORMATION
• NUSE_PARTITION_POOL_COUNT

By default all are set to FALSE, stripping the implementation from the build. To use a feature, set the corresponding macro to TRUE. Enabling an API while no pools are defined (except NUSE_Partition_Pool_Count()) results in a compile‑time error. Using an API that is not enabled causes a link‑time error.

Partition Pool Service Calls

Nucleus RTOS offers seven service calls for partition pools. In Nucleus SE, only the core allocation and deallocation APIs are implemented. The table below lists each call, its implementation status, and a brief description:

API	Implementation	Description
NU_Allocate_Partition()	Implemented	Allocate a partition.
NU_Deallocate_Partition()	Implemented	Free a partition.
NU_Partition_Pool_Information()	Implemented	Retrieve pool metadata.
NU_Established_Partition_Pools()	Implemented	Count active pools.
NU_Create_Partition_Pool()	Not implemented	Dynamic pool creation.
NU_Delete_Partition_Pool()	Not implemented	Dynamic pool deletion.
NU_Partition_Pool_Pointers()	Not implemented	Return pool pointers.

Note that neither Nucleus RTOS nor SE provide a reset routine for partition pools. This design choice reflects typical use cases where a task allocates a partition and hands its pointer to another task that will eventually deallocate it. Resetting a pool would silently mark all partitions as free, breaking the task‑level contract.

Allocation and Deallocation Services

The core operations are:

• Allocate: mark a partition as used and return its address.
• Deallocate: mark a partition as free.

Nucleus RTOS Allocation API

Prototype:

STATUS NU_Allocate_Partition(NU_PARTITION_POOL *pool,
                              VOID **return_pointer,
                              UNSIGNED suspend);

Return values include NU_SUCCESS, NU_NO_PARTITION, NU_INVALID_POOL, NU_INVALID_POINTER, NU_INVALID_SUSPEND, NU_TIMEOUT, and NU_POOL_DELETED.

Nucleus SE Allocation API

Prototype:

STATUS NUSE_Partition_Allocate(NUSE_PARTITION_POOL pool,
                                ADDR *return_pointer,
                                U8 suspend);

Parameters:

• pool – index of the pool to use.
• return_pointer – address of the allocated block.
• suspend – NUSE_NO_SUSPEND or NUSE_SUSPEND.

Return codes mirror those of RTOS but are prefixed with NUSE_. Invalid suspend requests from non‑task threads or when blocking APIs are disabled produce NUSE_INVALID_SUSPEND.

For a full implementation walkthrough, see the subsequent articles in the RTOS Revealed series.