FreeRTOS on Raspberry Pi Pico: Identify Which Heap an Allocation Actually Uses

A Pico application can report free FreeRTOS heap space while a library allocation fails elsewhere. A single “free memory” number is only useful when its allocator and coverage are known.

Start by tracing allocation entry points through the linked firmware. This example examines FreeRTOS V11.3.1 heap_4 and Pico SDK 2.3.1 malloc wrappers. It describes a configuration to audit, not an assertion that every Pico FreeRTOS project uses two separate heaps.

Trace the kernel allocation implementation

The tagged heap_4 implementation implements `pvPortMalloc()` and `vPortFree()` over a `ucHeap` array sized by `configTOTAL_HEAP_SIZE`; the array can instead be supplied by the application. Its free-space counters belong to that allocator. Total free bytes alone do not describe the arrangement of free blocks.

Confirm that heap_4 is actually linked before using those facts. A different heap implementation, custom wrappers or an application-supplied allocation policy can change the relationship between kernel and C-library memory. Find the provider of each symbol in the map and linked objects rather than inferring it from an unused source file in the checkout.

For a hypothetical failure in a parsing library, first identify whether that library calls `malloc()`, a configurable allocator callback or the kernel allocation API. Increasing the kernel heap budget without answering that question may consume more static RAM while leaving the failing path unchanged.

Follow the SDK wrapper to its underlying allocator

The Pico SDK malloc wrapper forwards wrapped malloc-family calls to the underlying functions. Optional configuration adds mutex protection and allocation checks. Its panic-on-allocation-failure behavior is configurable rather than a universal return-NULL contract for every build.

These wrappers do not by themselves establish that C-library allocations use the FreeRTOS heap array. Verify the final link and any project overrides. Similarly, a configured mutex says something about a particular protection path; it does not make allocation appropriate in arbitrary interrupt contexts.

Document the resulting route for each important object type: task resources, communications buffers, library workspaces and application-owned data. If two routes share storage through an intentional custom design, record that relationship explicitly. If they are separate, keep their budgets and observations separate too.

Keep allocation and release in the same ownership family

Once an allocation crosses a module boundary, preserve the matching deallocation rule. A function accepting a pointer should not guess whether it came from `malloc()` or `pvPortMalloc()`. Give ownership to one module or carry an explicit release contract with the object.

A hypothetical callback-driven library makes this especially important. If the application supplies an allocation callback, pair it with the corresponding release callback and inspect every error path that may return early. A successful steady-state demonstration can miss a mismatched release that occurs only after partial initialization.

Do not deliberately cross-free pointers as a test of compatibility. Establish the implementation relationship from source and linking, then exercise supported allocation and failure paths on a development target.

Measure the budget that explains the failure

Use observations tied to the failing allocator. For a kernel-heap failure, distinguish total free space from whether the requested allocation can be satisfied. For another allocator, use its supported diagnostics and the actual linker memory arrangement instead of labeling the kernel's free-space counter as whole-device RAM.

Test initialization, peak concurrent work and cleanup separately. A system may have enough space for each component alone but not for their simultaneous buffers. Keep instrumentation modest: diagnostic formatting or logging can allocate memory and alter the condition being measured.

The useful conclusion identifies the failing allocation route, its available storage and the object's release owner. Only then is a budget change justified. A larger number in an unrelated heap configuration is not evidence that the original failure has been addressed.