From patchwork Wed Dec 10 00:07:26 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 892 Return-Path: X-Original-To: u-boot-concept@u-boot.org Delivered-To: u-boot-concept@u-boot.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765325431; bh=tgsGfH2HfuT25hzCjtVly5UeW3pCYMiNrF2TJ3dsU9Y=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=B4IWDNLdvFtaFSa8fYhBjsRLAlPG5IyWF1eYCDbG7wIJ4ObNadWewITNIIyiji2n+ uCbCxSJvv22rEAGbUkQDhwYf6WfVGKvFnvjMifAyxBW420M23cIKr/fXJo5JNHW7vW NULWJqaAqbnaXd6gWI29cl4pOecUbri1VnXeIAeGu5VnEwbW7hmqMRRF2lmmVKRds9 fR7J4T12Xd6AJAo1M68C82f8+s24BU0Jj2X6XqS8R9F2WTYBoyB+R+BejUzyWYkCwB 2DcyGOKc/KhwOS611STP/+TMAfX5FyD+eOInQ1qjkZHjZOkzKBG3zByKcshBzgYM2l AMWVjYgpKy+uA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 10911689EA for ; Tue, 9 Dec 2025 17:10:31 -0700 (MST) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10024) with ESMTP id J0jwAIcys_TF for ; Tue, 9 Dec 2025 17:10:31 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765325430; bh=tgsGfH2HfuT25hzCjtVly5UeW3pCYMiNrF2TJ3dsU9Y=; h=From:To:Date:In-Reply-To:References:CC:Subject:List-Id: List-Archive:List-Help:List-Owner:List-Post:List-Subscribe: List-Unsubscribe:From; b=Av34kNCejZCPaGkihTUYF/qZFZinqoxf65Um6rsa85DW/yFq6+itq3mYoURJHTVAu 2DZp16o4fhvBGUb2EfwnqSscwuGHthokCkxsQPPDpNWrH2f8j4tyo4WbzxKZKP4GFR geVaRk/4DWPLEBREcjCr0wStQyuAZFWH/VOB+GAQGa7GcDlEgA4cS/CXffJzlPgOSe /hH+E0S8GErhtWZG4gLBI5c8885Q4cQDxpedA2NzOjGgT0cZjpUbfkW43scRl9sNE9 h5Wm+JdI6jBbfCaILf8wDuC8Z5fHkwTp1QSRaUaNFbVH5ojc9+qvdUyp37oPQplxvK LzpKH8OEJh3Pw== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id F36D46895B for ; Tue, 9 Dec 2025 17:10:30 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765325429; bh=rtDui87/krw82VUM0LnWC0cyX6SAJShObB+pbfG4OXo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=LklQo3DKUKXtAkRE8849AtSXK9/oksFNSK1GQarL37bqQN6XS88cazmMMW2/LvvIi e0uF22xVHjugxuGTYZIZD9jz06vUMxOnw25klmKCAurqEqTImXC5xwFxftxgtuaO+i utDqLQnZRDkYTUleXfx7gD02uEPreY+/debiceikGfIP1CJH39C4MU21rVNVN5kWHU QbkuU/EQuqLcEe6E8TMp0w+DxOUt3zhJKtMTBZ4rOvArR64DPoGYHqiCOi4gbnlwMA hzoQbOgbVLWEqYWQvhls1VBOde7bZtjw3Hp9SibBm+8YWA2bGKxAbeUdDduLqVJLCx YC5S4Y+UPEnCw== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 67BEE687A7; Tue, 9 Dec 2025 17:10:29 -0700 (MST) X-Virus-Scanned: Debian amavis at Received: from mail.u-boot.org ([127.0.0.1]) by localhost (mail.u-boot.org [127.0.0.1]) (amavis, port 10026) with ESMTP id s23HcKDvbilU; Tue, 9 Dec 2025 17:10:29 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1765325424; bh=m/BOtZf9aDRWbWusBfV392ySNWEN1wXuHGQLi81WYoI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=m+rOgEsAWDkdj9hIdDvXzFFB74Ik4ezemTCJODujrOLRAelVr5gkUIDUhUwuQqbFi CUyaLFTILOg7S50K6RWSHGgC2ZOjRGoa7tLhQC+NYvVVufQ4DLl8YYDlIlMKq0M/f0 Cn0WpAu8tHcF/TdBarikFLOh9BQsP1AONje2ANcLVwkOkPnTM1rBRLQAuEn2t/4lhL NHYSValBVocqIaQZQICq+wVwB+Ten49EmgTIz2qZVMY30VijNwf94KlmR2yQaHBxIW EUZruaVbLYonZOAcYnYVE93BHxRUOZzhH4hEx9G9PKcxxWeonOxp6ZpsIzSaMpXxkT geazHr6Ym24kg== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 6E6AD689EA; Tue, 9 Dec 2025 17:10:24 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Tue, 9 Dec 2025 17:07:26 -0700 Message-ID: <20251210000737.180797-36-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20251210000737.180797-1-sjg@u-boot.org> References: <20251210000737.180797-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: AAF6P2NUOGZLLACV52Q4HKPLBQN7DXB7 X-Message-ID-Hash: AAF6P2NUOGZLLACV52Q4HKPLBQN7DXB7 X-MailFrom: sjg@u-boot.org X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Heinrich Schuchardt , Simon Glass , Claude X-Mailman-Version: 3.3.10 Precedence: list Subject: [Concept] [PATCH 35/35] doc: malloc: Document debugging features List-Id: Discussion and patches related to U-Boot Concept Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Simon Glass 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 Co-developed-by: Claude Signed-off-by: Simon Glass --- doc/develop/malloc.rst | 103 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 95 insertions(+), 8 deletions(-) diff --git a/doc/develop/malloc.rst b/doc/develop/malloc.rst index 3c6b6ea65a4..8dba2d98afe 100644 --- a/doc/develop/malloc.rst +++ b/doc/develop/malloc.rst @@ -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: + +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 + 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 +~~~~~~~~ -1. **mcheck**: U-Boot includes mcheck support for detecting buffer overruns. - Enable CONFIG_MCHECK to use mcheck(), mcheck_pedantic(), and - mcheck_check_all(). +When running sandbox with Valgrind, the allocator includes annotations to help +detect memory errors. See :ref:`sandbox_valgrind`. -2. **Valgrind**: When running sandbox with Valgrind, the allocator includes - annotations to help detect memory errors. See :ref:`sandbox_valgrind`. +malloc testing +~~~~~~~~~~~~~~ -3. **malloc testing**: Unit tests can use malloc_enable_testing() to simulate - allocation failures. +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