u-boot/doc/develop/malloc.rst

.. SPDX-License-Identifier: GPL-2.0-or-later

Dynamic Memory Allocation
=========================

U-Boot uses Doug Lea's malloc implementation (dlmalloc) for dynamic memory
allocation. This provides the standard C library functions malloc(), free(),
realloc(), calloc(), and memalign().

Overview
--------

U-Boot's malloc implementation has two phases:

1. **Pre-relocation (simple malloc)**: Before U-Boot relocates itself to the
   top of RAM, a simple malloc implementation is used. This allocates memory
   from a small fixed-size pool and does not support free(). This is
   controlled by CONFIG_SYS_MALLOC_F_LEN.

2. **Post-relocation (full malloc)**: After relocation, the full dlmalloc
   implementation is initialized with a larger heap. The heap size is
   controlled by CONFIG_SYS_MALLOC_LEN.

The transition between these phases is managed by the GD_FLG_FULL_MALLOC_INIT
flag in global_data.

dlmalloc Version
----------------

U-Boot uses dlmalloc version 2.8.6 (updated from 2.6.6 in 2025), which
provides:

- Efficient memory allocation with low fragmentation
- Small bins for allocations up to 256 bytes (32 bins)
- Tree bins for larger allocations (32 bins)
- Best-fit allocation strategy
- Boundary tags for coalescing free blocks

Data Structures
---------------

The allocator uses two main static structures:

**malloc_state** (~944 bytes on 64-bit systems):

- ``smallbins``: 33 pairs of pointers for small allocations (528 bytes)
- ``treebins``: 32 tree root pointers for large allocations (256 bytes)
- ``top``: Pointer to the top chunk (wilderness)
- ``dvsize``, ``topsize``: Sizes of designated victim and top chunks
- Bookkeeping: footprint tracking, bitmaps, segment info

**malloc_params** (48 bytes on 64-bit systems):

- Page size, granularity, thresholds for mmap and trim

For comparison, the older dlmalloc 2.6.6 used a single 2064-byte ``av_`` array
on 64-bit systems. The 2.8.6 version uses about half the static data while
providing better algorithms.

Kconfig Options
---------------

Main U-Boot (post-relocation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``CONFIG_SYS_MALLOC_LEN``
    Hex value defining the size of the main malloc pool after relocation.
    This is the heap available for driver model, file systems, and general
    dynamic memory allocation. Default: 0x400000 (4 MB), varies by platform.

``CONFIG_SYS_MALLOC_F``
    Bool to enable malloc() pool before relocation. Required for driver model
    and many boot features. Default: y if DM is enabled.

``CONFIG_SYS_MALLOC_F_LEN``
    Hex value for the size of pre-relocation malloc pool. This small pool is
    used before DRAM is initialized. Default: 0x2000 (8 KB), varies by platform.

``CONFIG_SYS_MALLOC_CLEAR_ON_INIT``
    Bool to zero the malloc pool on initialization. This slows boot but ensures
    malloc returns zeroed memory. Disable for faster boot when using large
    heaps. Default: y

``CONFIG_SYS_MALLOC_DEFAULT_TO_INIT``
    Bool to call malloc_init() when mem_malloc_init() is called. Used when
    moving malloc from one memory region to another. Default: n

``CONFIG_SYS_MALLOC_BOOTPARAMS``
    Bool to malloc a buffer for bi_boot_params instead of using a fixed
    location. Default: n

``CONFIG_VALGRIND``
    Bool to annotate malloc operations for Valgrind memory debugging. Only
    useful when running sandbox builds under Valgrind. See
    :ref:`sandbox_valgrind` for details. Default: n

``CONFIG_SYS_MALLOC_SMALL``
    Bool to enable code-size optimisations for dlmalloc. This option combines
    several optimisations:

    - Disables tree bins for allocations >= 256 bytes, using simple linked-list
      bins instead. This changes large-allocation performance from O(log n) to
      O(n) but saves ~1.5-2KB.
    - Simplifies memalign() by removing fallback retry logic. Saves ~100-150 bytes.
    - Disables in-place realloc optimisation. Saves ~200 bytes.
    - Uses static malloc parameters instead of runtime-configurable ones.
    - Converts small chunk macros to functions to reduce code duplication.

    These optimisations may increase fragmentation and reduce performance for
    workloads with many large or aligned allocations, but are suitable for most
    U-Boot use cases where code size is more important. Default: n

``CONFIG_SYS_MALLOC_LEGACY``
    Bool to use the legacy dlmalloc 2.6.6 implementation instead of the modern
    dlmalloc 2.8.6. The legacy allocator has smaller code size (~450 bytes less)
    but uses more static data (~500 bytes more on 64-bit). Provided for
    compatibility and testing. New boards should use the modern allocator.
    Default: n

``CONFIG_MALLOC_DEBUG``
    Bool to enable malloc debugging features. This enables the
    ``malloc_get_info()`` function to retrieve memory statistics and supports
    the ``malloc`` command. Default: y if UNIT_TEST is enabled.

``CONFIG_MCHECK_HEAP_PROTECTION``
    Bool to enable heap protection using the mcheck library. This adds canary
    values before and after each allocation to detect buffer overflows,
    underflows, double-frees, and memory corruption. When enabled, caller
    backtraces are recorded for each allocation and displayed by
    ``malloc dump``. This significantly increases memory overhead and should
    only be used for debugging. Default: n

``CONFIG_MCHECK_BACKTRACE``
    Bool to enable backtrace collection for mcheck caller information. When
    enabled (the default), each allocation records a stack backtrace showing
    where it was made. This is useful for debugging memory leaks but adds
    overhead to every malloc call. Disable this to reduce mcheck overhead
    while keeping the canary checks and double-free detection. Default: y

xPL Boot Phases
~~~~~~~~~~~~~~~

The SPL (Secondary Program Loader), TPL (Tertiary Program Loader), and VPL
(Verification Program Loader) boot phases each have their own malloc
configuration options. These are prefixed with ``SPL_``, ``TPL_``, or ``VPL_``
and typically mirror the main U-Boot options.

Similar to U-Boot proper, xPL phases can use simple malloc (``malloc_simple``)
for pre-DRAM allocation. However, unlike U-Boot proper which transitions from
simple malloc to full dlmalloc after relocation, xPL phases that enable
``CONFIG_SPL_SYS_MALLOC_SIMPLE`` (or equivalent) cannot transition to full
malloc within that phase, since the dlmalloc code is not included in the
binary.

Note: When building with ``CONFIG_XPL_BUILD``, the code uses
``CONFIG_IS_ENABLED()`` macros to automatically select the appropriate
phase-specific option (e.g., ``CONFIG_IS_ENABLED(SYS_MALLOC_F)`` expands to
``CONFIG_SPL_SYS_MALLOC_F`` when building SPL).

SPL (Secondary Program Loader)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``CONFIG_SPL_SYS_MALLOC_F``
    Bool to enable malloc() pool in SPL before DRAM is initialized. Required
    for driver model in SPL. Default: y if SPL_FRAMEWORK and SYS_MALLOC_F.

``CONFIG_SPL_SYS_MALLOC_F_LEN``
    Hex value for SPL pre-DRAM malloc pool size. Default: inherits from
    CONFIG_SYS_MALLOC_F_LEN.

``CONFIG_SPL_SYS_MALLOC_SIMPLE``
    Bool to use only malloc_simple functions in SPL instead of full dlmalloc.
    The simple allocator is smaller (saves ~600 bytes) but cannot free()
    memory. Default: n

``CONFIG_SPL_SYS_MALLOC``
    Bool to enable a full malloc pool in SPL after DRAM is initialized.
    Used with CONFIG_SPL_CUSTOM_SYS_MALLOC_ADDR. Default: n

``CONFIG_SPL_HAS_CUSTOM_MALLOC_START``
    Bool to use a custom address for SPL malloc pool instead of the default
    location. Requires CONFIG_SPL_CUSTOM_SYS_MALLOC_ADDR. Default: n

``CONFIG_SPL_CUSTOM_SYS_MALLOC_ADDR``
    Hex address for SPL malloc pool when using custom location.

``CONFIG_SPL_SYS_MALLOC_SIZE``
    Hex value for SPL malloc pool size when using CONFIG_SPL_SYS_MALLOC.
    Default: 0x100000 (1 MB).

``CONFIG_SPL_SYS_MALLOC_CLEAR_ON_INIT``
    Bool to zero SPL malloc pool on initialization. Useful when malloc pool
    is in a region that must be zeroed before first use. Default: inherits
    from CONFIG_SYS_MALLOC_CLEAR_ON_INIT.

``CONFIG_SPL_SYS_MALLOC_SMALL``
    Bool to enable code-size optimisations for dlmalloc in SPL. Enables the
    same optimisations as CONFIG_SYS_MALLOC_SMALL (disables tree bins,
    simplifies memalign, disables in-place realloc, uses static parameters,
    converts small chunk macros to functions). SPL typically has predictable
    memory usage where these optimisations have minimal impact, making the
    code size savings worthwhile. Default: y

``CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN``
    Hex value for malloc_simple heap size after switching to DRAM stack in SPL.
    Only used when CONFIG_SPL_STACK_R and CONFIG_SPL_SYS_MALLOC_SIMPLE are
    enabled. Provides a larger heap than the initial SRAM pool. Default:
    0x100000 (1 MB).

TPL (Tertiary Program Loader)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``CONFIG_TPL_SYS_MALLOC_F``
    Bool to enable malloc() pool in TPL. Default: y if TPL and SYS_MALLOC_F.

``CONFIG_TPL_SYS_MALLOC_F_LEN``
    Hex value for TPL malloc pool size. Default: inherits from
    CONFIG_SPL_SYS_MALLOC_F_LEN.

``CONFIG_TPL_SYS_MALLOC_SIMPLE``
    Bool to use only malloc_simple in TPL instead of full dlmalloc. Saves
    code size at the cost of no free() support. Default: n

VPL (Verification Program Loader)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``CONFIG_VPL_SYS_MALLOC_F``
    Bool to enable malloc() pool in VPL. Default: y if VPL and SYS_MALLOC_F.

``CONFIG_VPL_SYS_MALLOC_F_LEN``
    Hex value for VPL malloc pool size. Default: inherits from
    CONFIG_SPL_SYS_MALLOC_F_LEN.

``CONFIG_VPL_SYS_MALLOC_SIMPLE``
    Bool to use only malloc_simple in VPL. Default: y

dlmalloc Compile-Time Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These options are set in the U-Boot section of ``common/dlmalloc.c``:

``NO_MALLOC_STATS``
    Disable malloc_stats() function. Default: 1 (disabled)

``NO_MALLINFO``
    Disable mallinfo() function. Default: 1 for non-sandbox builds

``INSECURE``
    Disable runtime heap validation checks. This reduces code size but removes
    detection of heap corruption. Default: 1 for non-sandbox builds

``NO_REALLOC_IN_PLACE``
    Disable in-place realloc optimisation. Enabled by CONFIG_SYS_MALLOC_SMALL.
    Saves ~200 bytes of code. Default: 0

``NO_TREE_BINS``
    Disable tree bins for large allocations (>= 256 bytes), using simple
    linked-list bins instead. Enabled by CONFIG_SYS_MALLOC_SMALL. Saves
    ~1.5-2KB but changes performance from O(log n) to O(n). Default: 0

``SIMPLE_MEMALIGN``
    Simplify memalign() by removing fallback retry logic. Enabled by
    CONFIG_SYS_MALLOC_SMALL. Saves ~100-150 bytes. Default: 0

``STATIC_MALLOC_PARAMS``
    Use static malloc parameters instead of runtime-configurable ones.
    Enabled by CONFIG_SYS_MALLOC_SMALL. Default: 0

``SMALLCHUNKS_AS_FUNCS``
    Convert small chunk macros (insert_small_chunk, unlink_first_small_chunk)
    to functions to reduce code duplication. Enabled by CONFIG_SYS_MALLOC_SMALL.
    Default: 0

``SIMPLE_SYSALLOC``
    Use simplified sys_alloc() that only supports contiguous sbrk() extension.
    Enabled automatically for non-sandbox builds. Saves code by removing mmap
    and multi-segment support. Default: 1 for non-sandbox, 0 for sandbox

``MORECORE_CONTIGUOUS``
    Assume sbrk() returns contiguous memory. Default: 1

``MORECORE_CANNOT_TRIM``
    Disable releasing memory back to the system. Default: 1

``HAVE_MMAP``
    Enable mmap() for large allocations. Default: 0 (U-Boot uses sbrk only)

Code Size
---------

The dlmalloc 2.8.6 implementation is larger than the older 2.6.6 version due
to its more sophisticated algorithms. To minimise code size for
resource-constrained systems, U-Boot provides several optimisation levels:

**Default optimisations** (always enabled for non-sandbox builds):

- INSECURE=1 (saves ~1100 bytes)
- NO_MALLINFO=1 (saves ~200 bytes)
- SIMPLE_SYSALLOC=1 (saves code by simplifying sys_alloc)

**CONFIG_SYS_MALLOC_SMALL** (additional optimisations, default y for SPL):

- NO_TREE_BINS=1 (saves ~1.5-2KB)
- NO_REALLOC_IN_PLACE=1 (saves ~200 bytes)
- SIMPLE_MEMALIGN=1 (saves ~100-150 bytes)
- STATIC_MALLOC_PARAMS=1
- SMALLCHUNKS_AS_FUNCS=1 (reduces code duplication)

With default optimisations only, the code-size increase over dlmalloc 2.6.6
is about 450 bytes, while data usage decreases by about 500 bytes.

With CONFIG_SYS_MALLOC_SMALL enabled, significant additional code savings
are achieved, making it suitable for size-constrained SPL builds.

Sandbox builds retain full functionality for testing, including mallinfo()
for memory-leak detection.

Debugging
---------

U-Boot provides several features to help debug memory-allocation issues:

CONFIG_MALLOC_DEBUG
~~~~~~~~~~~~~~~~~~~

Enable ``CONFIG_MALLOC_DEBUG`` to activate malloc debugging features. This is
enabled by default when ``CONFIG_UNIT_TEST`` is set. It provides:

- The ``malloc_get_info()`` function to retrieve memory statistics
- Allocation call counters (malloc, free, realloc counts)
- Support for the ``malloc`` command (see :doc:`/usage/cmd/malloc`)

The :doc:`/usage/cmd/malloc` command provides two subcommands:

``malloc info``
    Shows memory-allocation statistics including total heap size, memory in use,
    and call counts::

        => malloc info
        total bytes   = 96 MiB
        in use bytes  = 700.9 KiB
        malloc count  = 1234
        free count    = 567
        realloc count = 89

``malloc dump``
    Walks the entire heap and prints each chunk's address, size, and status
    (used, free, or top). This is useful for understanding heap layout and
    finding memory leaks::

        => malloc dump
        Heap dump: 19a0e000 - 1fa10000
             Address        Size  Status
        ----------------------------------
            19a0e000          10  (chunk header)
            19a0e010          a0
            19a0e0b0        6070
            19adfc30          60  <free>
            19adff90     5f3f030  top
            1fa10000              end
        ----------------------------------
        Used: c2ef0 bytes in 931 chunks
        Free: 5f3f0c0 bytes in 2 chunks + top

CONFIG_MCHECK_HEAP_PROTECTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enable ``CONFIG_MCHECK_HEAP_PROTECTION`` for heap protection using the mcheck
library. This adds canary values before and after each allocation to detect:

- Buffer overflows and underflows
- Double-frees
- Memory corruption

This significantly increases memory overhead and should only be used for
debugging. U-Boot includes mcheck support via mcheck(), mcheck_pedantic(), and
mcheck_check_all().

When mcheck is enabled, the ``malloc dump`` command also shows caller
information for each allocation, including a backtrace showing where the
allocation was made::

    => malloc dump
    Heap dump: 18a1d000 - 1ea1f000
         Address        Size  Status
    ----------------------------------
        18a1d000          10  (chunk header)
        18a1d010          90  used  log_init:453 <-board_init_r:774
        18a1d0a0        6060  used  membuf_new:420 <-console_record
        18a3b840          90  used  of_alias_scan:911 <-board_init_

This caller information makes it easy to track down memory leaks by showing
exactly where each allocation originated.

Malloc-Traffic Log
~~~~~~~~~~~~~~~~~~

On sandbox, when mcheck is enabled, a malloc-traffic log can record all
malloc/free/realloc calls. This is useful for debugging allocation patterns
and finding where allocations without caller info originate. See
:doc:`../usage/cmd/malloc` for usage.

The log buffer is allocated from host memory using ``os_malloc()``, so it
does not affect U-Boot's heap. The size is controlled by
``CONFIG_MCHECK_LOG_SIZE`` (default 512K entries, about 80MB).

If the log fills up, it wraps around and overwrites the oldest entries.
A warning is shown when dumping if entries were lost.

Valgrind
~~~~~~~~

When running sandbox with Valgrind, the allocator includes annotations to help
detect memory errors. See :ref:`sandbox_valgrind`.

malloc testing
~~~~~~~~~~~~~~

Unit tests can use malloc_enable_testing() to simulate allocation failures.

Finding Memory Leaks
~~~~~~~~~~~~~~~~~~~~

U-Boot provides several tools for detecting and diagnosing memory leaks.
These techniques are primarily supported on sandbox, which has the full
debugging infrastructure enabled by default (``CONFIG_MALLOC_DEBUG``,
``CONFIG_MCHECK_HEAP_PROTECTION``) and access to host filesystem functions
for writing dump files.

**Leak detection in unit tests**

Unit tests can use ``ut_check_delta()`` to detect memory leaks::

    ulong mem_start;

    mem_start = ut_check_delta(0);  /* Record starting heap usage */

    /* ... test code that allocates and frees memory ... */

    ut_asserteq(0, ut_check_delta(mem_start));  /* Verify no leak */

This uses ``mallinfo().uordblks`` to compare heap usage before and after.

**Heap dump comparison**

When a leak is detected, use ``malloc_dump()`` to capture heap state before
and after the operation. In sandbox builds, ``malloc_dump_to_file()`` writes
the dump to a host file for easier comparison::

    malloc_dump_to_file("/tmp/before.txt");

    /* ... operation that may leak ... */

    malloc_dump_to_file("/tmp/after.txt");

Then compare the dumps to find leaked allocations::

    $ diff /tmp/before.txt /tmp/after.txt

Or extract just the addresses and sizes for comparison::

    $ awk '{print $1, $2}' /tmp/before.txt | sort > /tmp/b.txt
    $ awk '{print $1, $2}' /tmp/after.txt | sort > /tmp/a.txt
    $ comm -13 /tmp/b.txt /tmp/a.txt   # Show allocations only in 'after'

The dump includes caller information when ``CONFIG_MCHECK_HEAP_PROTECTION``
is enabled, showing exactly where each leaked allocation originated.

**Malloc-traffic logging**

For more detailed analysis, use the malloc-traffic log to record all
allocations during an operation::

    malloc_log_start();

    /* ... operation to trace ... */

    malloc_log_stop();
    malloc_log_to_file("/tmp/malloc_log.txt");  /* Sandbox only */

The log shows every malloc(), free(), and realloc() call with addresses, sizes,
and caller backtraces (if enabled). Search for allocations that were never
freed::

    $ grep "alloc" /tmp/malloc_log.txt   # Find all allocations
    $ grep "16ad1290" /tmp/malloc_log.txt  # Check if a specific address was freed

**Verifying debug functions don't allocate**

When using these debugging functions, verify they don't affect heap state
by checking ``malloc_get_info()`` before and after::

    struct malloc_info before, after;

    malloc_get_info(&before);
    malloc_dump_to_file("/tmp/dump.txt");
    malloc_get_info(&after);

    /* Verify no allocations occurred */
    assert(before.malloc_count == after.malloc_count);
    assert(before.in_use_bytes == after.in_use_bytes);

**Practical workflow**

1. Add ``ut_check_delta()`` assertions to your test to detect leaks
2. When a leak is detected, add ``malloc_dump_to_file()`` calls before and
   after the leaking operation
3. Run the test and compare the dump files to identify leaked allocations
4. Use the caller backtrace in the dump to find the allocation site
5. If more detail is needed, enable ``malloc_log_start()`` to trace all
   allocations during the operation
6. Fix the leak and verify the test passes

API Reference
-------------

Standard C functions:

- ``void *malloc(size_t size)`` - Allocate memory
- ``void free(void *ptr)`` - Free allocated memory
- ``void *realloc(void *ptr, size_t size)`` - Resize allocation
- ``void *calloc(size_t nmemb, size_t size)`` - Allocate zeroed memory
- ``void *memalign(size_t alignment, size_t size)`` - Aligned allocation

Pre-relocation simple malloc (from malloc_simple.c):

- ``void *malloc_simple(size_t size)`` - Simple bump allocator
- ``void *memalign_simple(size_t alignment, size_t size)`` - Aligned version

See Also
--------

- :doc:`memory` - Memory management overview
- :doc:`global_data` - Global data and the GD_FLG_FULL_MALLOC_INIT flag
- :doc:`/usage/cmd/malloc` - malloc command reference