smallsolar/u-boot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: malloc: Document debugging features

Browse Source 
Update the malloc() with more info about the debugging features:

- CONFIG_MALLOC_DEBUG and CONFIG_MCHECK_HEAP_PROTECTION Kconfig options
- The malloc command with info and dump subcommands
- Caller backtrace display when mcheck is enabled

Series-to: concept
Series-cc: heinrich
Series-version: 2
Cover-letter:
malloc: Add heap debugging commands and mcheck caller tracking
This series adds improved heap-debugging capabilities.

As part of this, the recently added backtrace feature is reworked to
avoid itself using malloc(), which makes it difficult for malloc() to
use.

A new 'malloc' command with 'info' and 'dump' subcommands allows
inspecting the heap state at runtime.

The mcheck heap-protection feature is integrated into Kconfig and can be
used to to track caller information for each allocation, showing the
function name and line number.

The caller info can be seen with 'malloc dump', including for freed
chunks where possible.

The 'malloc info' command shows a few more heap statistics:

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

The 'malloc dump' command walks the heap showing each chunk:

    => malloc dump
    Heap dump: 19a0e000 - 1fa10000
         Address        Size  Status
    ----------------------------------
        19a0e000          10  (chunk header)
        19a0e010          a0        log_init:453 <-board_init_r:774 <-sandbox_flow:
        19a0e0b0       20070        membuf_new:420 <-console_record_init:880 <-boar
        19a2e120         170        membuf_new:420 <-console_record_init:886 <-boar
        19a2e290         150        unflatten_device_tree:299 <-of_live_build:328 <
        19a2e3e0          a0        uclass_get:157 <-device_bind_common:59 <-device
        ...
        19a4b080          70  free  done_word:2489 <-parse_stream_outer:3190 <-pars
        ...

This is useful for debugging memory leaks, understanding allocation
patterns, and tracking down heap corruption issues.

Some additional patches are included to make all this work:
- format_size() for human-readable size formatting
- ut_asserteq_regex() for flexible test assertions
- backtrace_str() for condensed backtrace output

Finally, this series includes a few patches for some of the more obvious
memory leaks (scmi and some test drivers), plus a reduction in truetype
memory allocations and a fix for a watchdog crash with 'ut dm'.
END

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>
This commit is contained in:
Simon Glass
2025-12-08 14:15:36 -07:00
parent 4739e7a89a
commit 48e4d58cc0
1 changed files with 95 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
doc/develop/malloc.rst
View File

@@ -117,6 +117,19 @@ Main U-Boot (post-relocation)
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
xPL Boot Phases
~~~~~~~~~~~~~~~
@@ -298,17 +311,90 @@ for memory-leak detection.
Debugging
---------
For debugging heap issues, consider:
U-Boot provides several features to help debug memory-allocation issues:
1. **mcheck**: U-Boot includes mcheck support for detecting buffer overruns.
Enable CONFIG_MCHECK to use mcheck(), mcheck_pedantic(), and
mcheck_check_all().
CONFIG_MALLOC_DEBUG
~~~~~~~~~~~~~~~~~~~
2. **Valgrind**: When running sandbox with Valgrind, the allocator includes
annotations to help detect memory errors. See :ref:`sandbox_valgrind`.
Enable ``CONFIG_MALLOC_DEBUG`` to activate malloc debugging features. This is
enabled by default when ``CONFIG_UNIT_TEST`` is set. It provides:
3. **malloc testing**: Unit tests can use malloc_enable_testing() to simulate
allocation failures.
- 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.
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.
API Reference
-------------
@@ -331,3 +417,4 @@ 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