FreeRTOS heap_5 Regions: Validate Linker Boundaries Before the First Allocation

FreeRTOS heap_5.c can allocate from several noncontiguous memory regions, but it cannot determine whether those addresses belong to the heap. Define valid, nonoverlapping regions in increasing address order, terminate the list correctly and initialize them before any dynamic kernel allocation. A successful allocator initialization is not proof that the linker, startup code and peripheral memory map agree.

This guide pins FreeRTOS-Kernel V11.1.0. It includes an executed host integration test using the official POSIX port and unmodified heap_5 implementation. That test checks allocator behavior, not MCU memory-bank accessibility, startup ordering, cache properties or linker correctness. Those remain target qualification tasks.

Treat the region table as a memory ownership declaration

The tagged portable API defines each HeapRegion_t using a start address and byte count. The heap_5 implementation and usage notes require low-to-high region order, a null/zero terminator and vPortDefineHeapRegions() before the first allocation. The definition function is a one-time initialization operation, not a way to add regions to a running heap.

For each proposed region, create a row containing start, exclusive end, length, linker reservation, memory-bank readiness and excluded subranges. Use the final build’s map, not a copied address from a previous board revision. Explicitly exclude stacks, static data, retained state, bootloader communication areas, device buffers and any other owner. A large region that spans a reserved hole hands that hole to the allocator.

Validate raw bounds before alignment adjustments

1. Confirm each region is writable ordinary memory suitable for every object that may be allocated there. Bring external memory online before the allocator writes its metadata.
2. Compute start plus length without integer overflow. Require positive usable regions and check that each exclusive end is no greater than the next region’s start.
3. Check the port’s alignment and account for bytes lost when the start is rounded upward. Ensure the remaining extent can contain allocator metadata and useful free storage.
4. Append the null-address, zero-length terminator inside the actual table. Verify the table length during review rather than hoping an adjacent zero value will stop traversal.
5. Compare the table against the final linker reservations and startup initialization ranges. Check that startup code will not later clear or copy over an active heap.

The implementation aligns region starts and places an end marker within each region. Consequently, reported initial free space is smaller than the sum of raw region lengths. Tiny or malformed regions require application validation; do not use assertions as a complete bounds checker. Some invalid inputs can reach arithmetic or metadata writes before a useful diagnostic.

Linker symbols need the interpretation required by the chosen toolchain. Do not confuse the address represented by a boundary symbol with a variable stored at that address. Prefer an established board integration pattern and validate its resulting numeric range in the map and debugger. This article intentionally supplies no invented device addresses.

Find the real first allocation

Review startup as an allocation dependency graph. Task creation, queues, semaphores, timers and application helpers can allocate before the scheduler starts. Defining heap regions immediately before vTaskStartScheduler() is too late if earlier initialization already created dynamic objects. Include constructor-like initialization and libraries in the audit.

Place the region definition after required memory-bank initialization but before any path that can reach pvPortMalloc(). Link exactly the intended heap implementation; do not leave another allocator source supplying the same FreeRTOS functions. Preserve the initialization order in a startup test so a future refactor cannot silently move the first allocation earlier.

Do not interpret aggregate free bytes as one large region

Noncontiguous storage remains physically separate. An allocation cannot bridge a gap merely because total free bytes exceed the requested size. Diagnose a failed large allocation by examining the available block sizes and region geometry, not only the aggregate counter. Also, a single heap does not tag allocations with memory capabilities. Combining a peripheral-accessible bank with a CPU-only bank does not make every returned pointer valid for that peripheral.

A hypothetical board may have two suitable ordinary-RAM windows separated by reserved storage. If the application needs one buffer larger than either usable window, listing both windows does not satisfy that requirement. The next design action is to change the buffer strategy or memory placement, not to enlarge the first region across the reserved area.

Executed host checks

An original fixture used an aligned host array with regions starting at offsets 1 and 4096, with raw lengths 1023 and 1024 bytes. The gap was filled with a sentinel. GCC 14.2.0 compiled the official V11.1.0 kernel, POSIX port and heap_5 without modifying their sources; upstream port warnings were retained in the build log.

• Initial reported free space was 2008 bytes in that host configuration. This is a test result, not a portable MCU capacity prediction.
• A 1200-byte request failed despite aggregate free space exceeding 1200, because neither region supplied a large enough contiguous block.
• Four 400-byte allocations succeeded. Their spans remained inside the listed regions and met the port alignment; the gap sentinel was unchanged.
• Freeing all four allocations restored the initial free count.
• Separate process tests for allocation before definition, reversed regions and repeated definition each stopped at an enabled assertion.

The invalid-input tests demonstrate selected diagnostics only. They do not justify disabling the preflight checks or trying malformed tables on a live product. Final acceptance still requires target map review, verified memory-bank initialization, allocation stress within the intended regions and inspection of reserved-area sentinels where safe. Archive the region table with that build’s map so allocator evidence remains tied to the firmware that produced it.