From patchwork Sat Jan 3 01:18:55 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 1213 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=1767403231; bh=PDW/EwlNaTTPQYQ4454e8PO7J4C9I0rDy4EpsMytRNo=; 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=j2GpZ8HKLPIKRW+O37A1//SQqs6450TlyvOrtygwpMHEJcOx5wGU4Y/eBJD6rA9aR RYAZzx34texsELHYKkE3mRYJLQRxgMxiiU0TEplHna3BqRezplnvv+b2OxiE6TB1W/ 5GIPg4F/fv4J+g6DdfCW5YKM0laupimFroRJE3A2vv+KgQQaSc0ycG88GeH3Xuo5iv frrZwrdbJxhvxbeFQmSGi0Rgody2Eg5tn4Z4R8o9NiVBfUX7xbSThT0qmTpC0qrQjp /hcTK2jUfY5fqJJjli+nrJm7NoYJ8WLdaVH04xdTrHNMByyHE0dxtOg0WQfcdEok5q W/Rs5NTWHVTPA== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id AC5EB6906F for ; Fri, 2 Jan 2026 18:20: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 Ql3Q07lrPQeG for ; Fri, 2 Jan 2026 18:20:31 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1767403231; bh=PDW/EwlNaTTPQYQ4454e8PO7J4C9I0rDy4EpsMytRNo=; 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=j2GpZ8HKLPIKRW+O37A1//SQqs6450TlyvOrtygwpMHEJcOx5wGU4Y/eBJD6rA9aR RYAZzx34texsELHYKkE3mRYJLQRxgMxiiU0TEplHna3BqRezplnvv+b2OxiE6TB1W/ 5GIPg4F/fv4J+g6DdfCW5YKM0laupimFroRJE3A2vv+KgQQaSc0ycG88GeH3Xuo5iv frrZwrdbJxhvxbeFQmSGi0Rgody2Eg5tn4Z4R8o9NiVBfUX7xbSThT0qmTpC0qrQjp /hcTK2jUfY5fqJJjli+nrJm7NoYJ8WLdaVH04xdTrHNMByyHE0dxtOg0WQfcdEok5q W/Rs5NTWHVTPA== Received: from mail.u-boot.org (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 92AD66905F for ; Fri, 2 Jan 2026 18:20:31 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1767403228; bh=gtmKmy2TE7JIqRD1fAiI/iA8ZfTqeznVwhhcmJx79Oc=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=f8Bm9pFJzI0GeLD4BLoS2SNlBqT3pF8FwWMak/RXwgpGr6Jim6e5Pv0L4f6O/eGj3 vF0tRkQ3z2eE+ExhHBWu80flfmrCtXuKaAAq893Ljewyp1HiGj0E9LAO65Pnac+hnh OiiFZ6iL23rVrDGIRXaoicUKGez8c9ZaPMzuvlFyaZ7kYWWlX53VQUM9mGGKfIsArk OUF8zcHIsz8N6L0iyvxYza0Gcm50un0EXVkQa0fMnuWR6WFD3E3Zipip4GL+8CW23Y +Uw2Qi3aeeu9ngqa/O93M8NxET7RXKclomX8Mkr0rhukdi4Fei8ddLYl29kQe20JgY 8dL8nPw3TSRUQ== Received: from localhost (localhost [127.0.0.1]) by mail.u-boot.org (Postfix) with ESMTP id 58AD468BF2; Fri, 2 Jan 2026 18:20:28 -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 E8W0l0tki515; Fri, 2 Jan 2026 18:20:28 -0700 (MST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=u-boot.org; s=default; t=1767403226; bh=+GPEuvvpF7lfwHq5jKq2xCSRBzboKwishNKbQKNWOP4=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=d+EJam/GheyXVN71s5Lr3y120xvnZNm4mizGMS8RvWRii7k7a5C+r8YmXkFjTfkVa qlUwMsnmN541GhlHJBDBIjUmzdL1wnPhrC5uLCtvAW2x3xv2fzuieldlgxWObIroQK cmLAcykT4InMyNJWSbREb9PpnpnxuhfFO5IBKmgh5FlJvY46JVpkvLE2WJaXFDx/Su OZh1x7lj4aDy3w52doUFTbVjSPfyFVCQjj8EMbzoJBfJ8t17Ch47R6/N8Sb4ZzvDMN +eMR8nDKa85iA9vLCzB28zoSWC6adGqdWjslKSti7VapZFr/4NXSuqSG0S+OVC24wr ddwEkhX+jl6Ig== Received: from u-boot.org (unknown [73.34.74.121]) by mail.u-boot.org (Postfix) with ESMTPSA id 8EA2B68F87; Fri, 2 Jan 2026 18:20:26 -0700 (MST) From: Simon Glass To: U-Boot Concept Date: Fri, 2 Jan 2026 18:18:55 -0700 Message-ID: <20260103011908.149445-20-sjg@u-boot.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20260103011908.149445-1-sjg@u-boot.org> References: <20260103011908.149445-1-sjg@u-boot.org> MIME-Version: 1.0 Message-ID-Hash: O4MVQUNV7VT73MTSEVU6HJX7ISRJ5DAT X-Message-ID-Hash: O4MVQUNV7VT73MTSEVU6HJX7ISRJ5DAT 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 19/24] doc: malloc: Add a section on finding memory leaks 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 Document the practical workflow for detecting and diagnosing memory leaks in U-Boot, particularly in sandbox builds. This covers: - Using ut_check_delta() in unit tests for leak detection - Comparing heap dumps with malloc_dump_to_file() - Using malloc traffic logging to trace allocations - Verifying debug functions don't affect heap state - A step-by-step practical workflow Co-developed-by: Claude Signed-off-by: Simon Glass --- doc/develop/malloc.rst | 93 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/doc/develop/malloc.rst b/doc/develop/malloc.rst index 776294809b8..9becd573e8c 100644 --- a/doc/develop/malloc.rst +++ b/doc/develop/malloc.rst @@ -418,6 +418,99 @@ 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 -------------