doc: update profiling integration guidance and FAQ

Document the profiling and coverage integration constraints that are
easy to miss when users reuse the profiling component outside the
demo application.

Update Components/profiling/README.md with key reminders about
limiting -pg/-coverage to target application sources, checking heap
and linker layout, reusing the profiling component independently,
and parsing console dump output with parse.py.

Also add FAQ entries for common failure cases such as corrupted dump
output, missing generated files, and _mcleanup: tos overflow, update
app.rst with the same guidance for demo_profiling, and record the
documentation enhancement in the changelog.

Signed-off-by: Huaqi Fang <578567190@qq.com>

Author: fanghuaqi

Components/profiling/README.md

@@ -99,11 +99,36 @@ The ``demo_profiling`` example demonstrates:
 
 You can find the example at ``application/baremetal/demo_profiling`` in the Nuclei SDK.
 
+## Key Reminders
+
+> [!IMPORTANT]
+> **Apply profiling/coverage flags only to the application being analyzed.**
+> Do not enable `-pg` or `-coverage` globally for the whole SDK or unrelated components. These options should be added only to the source files or directories of the target application; otherwise they can introduce unexpected build, link, runtime, or memory issues.
+
+> [!IMPORTANT]
+> **Profiling and coverage need a large heap.**
+> Both gprof and gcov may allocate a significant amount of runtime memory, especially coverage collection. Make sure your heap is large enough before enabling these features.
+>
+> The `demo_profiling` example is intended to run with `DOWNLOAD=sram` or `DOWNLOAD=ddr` so that more runtime memory is available for profiling experiments.
+> In the linker script, `__HEAP_SIZE` only defines the minimum reserved heap space. The actual heap available to `malloc` is bounded by `__heap_start` and `__heap_end`, so it also depends on the final linker layout and remaining free RAM.
+> To reduce integration issues, it is recommended to use a memory layout with enough free RAM and verify the effective heap size in your own project.
+
+> [!TIP]
+> **This profiling component can be reused independently.**
+> You can copy the profiling library sources into another project and integrate them without moving the whole example application. A practical reference is the Nuclei Studio IDE flow below: add the required profiling sources, configure the library, then enable profiling or coverage compiler flags only for the application code you want to analyze.
+
 ## How to Use
 
 ### Step 1: Add Profiling Component to Your Project
 
-Add this `profiling` folder into your project or create project based on ``demo_profiling`` example, then configure your build system:
+Add this `profiling` folder into your project or create project based on ``demo_profiling`` example, then configure your build system.
+
+This component is designed to be integrated as a reusable library:
+
+- Add the required profiling sources and headers into your project
+- Configure the profiling library as needed for your platform
+- Enable `-pg` or `-coverage` only on the application source files you want to analyze
+- Do not apply these options globally to the whole SDK or all middleware
 
 #### For Nuclei Studio IDE
 
@@ -113,7 +138,8 @@ Add this `profiling` folder into your project or create project based on ``demo_
 4. Add the following flags:
    - `-pg` for profiling
    - `-coverage` for coverage analysis
-5. Click **Apply and Close**, then rebuild your project
+5. Apply the flags only to the selected application source file or source folder that needs profiling/coverage
+6. Click **Apply and Close**, then rebuild your project
 
 ![Set Profiling Options in Nuclei Studio](images/profiling_options_in_ide.png)
 
@@ -153,6 +179,8 @@ include $(NUCLEI_SDK_ROOT)/Build/Makefile.base
 > - Profiling and coverage analysis require significant memory
 > - Use ``DOWNLOAD=sram`` or ``DOWNLOAD=ddr`` for sufficient runtime memory
 > - When using ``-coverage`` flag, heap space may be insufficient - consider ``DOWNLOAD=ddr``
+> - Increase heap size explicitly if your application or test case uses gcov/gprof buffers heavily
+> - Avoid `DOWNLOAD=ilm` for such examples unless you have verified the available memory is still sufficient
 >
 > **Optimization Considerations:**
 > - Use ``-O0`` optimization level for accurate profiling results
@@ -161,6 +189,10 @@ include $(NUCLEI_SDK_ROOT)/Build/Makefile.base
 > **Extension Compatibility:**
 > - When using Zc extension with ``-pg``, note that ``-fomit-frame-pointer`` (enabled by Zc) is incompatible with ``-pg``
 > - You may need to adjust compiler flags accordingly
+>
+> **Scope of Instrumentation:**
+> - Set `APPDIRS` or equivalent build rules so that `-pg` and `-coverage` are added only to the target application sources
+> - Do not enable these flags for the whole SDK by default
 
 ### Step 2: Customize gprof_stub.c (For Profiling Only)
 
@@ -295,3 +327,78 @@ llvm-cov gcov *.gcda
 > - ``.gcda`` files: Runtime coverage data generated by your program execution (different format for GCC vs LLVM/Clang)
 > - ``.gcov`` files: Annotated source files generated by gcov tools showing line-by-line coverage
 > - GCC and LLVM/Clang generate incompatible ``.gcda`` formats - use the corresponding toolchain's gcov tool
+
+## FAQ
+
+### Why do I see garbled coverage or profiling dump output, or partial dump logs?
+
+In most cases, this means the runtime memory is insufficient, especially heap space used by gcov or gprof internal buffers.
+
+Typical symptoms include:
+
+- Dump output looks truncated, corrupted, or mixed with unexpected text
+- Coverage dump starts but does not complete correctly
+- Runtime errors disappear after increasing heap size
+
+Check the following first:
+
+- Make sure the application has enough heap, not only enough stack
+- Verify the actual available SRAM size in your project
+- Compare your linker script and `_sbrk` implementation with the SDK example, because the effective heap size may not match the number you expected from a macro or comment
+
+The `demo_profiling` example is typically run with `DOWNLOAD=sram` or `DOWNLOAD=ddr` so that more runtime memory is available for profiling experiments.
+The SDK linker script only guarantees a minimum heap reservation through `__HEAP_SIZE`. The actual heap that `malloc` can use is the range between `__heap_start` and `__heap_end`, so the effective size also depends on the linker layout, stack placement, and remaining RAM in your project.
+
+### Why are `gmon.out` or `*.gcda` files not generated when I use console or UART output?
+
+If you use `gprof_collect(2)` or `gcov_collect(2)`, the data is dumped to console output instead of being written directly to host files.
+
+That means:
+
+- UART or console output alone does not create `gmon.out` or `*.gcda` files automatically
+- You must save the dump log first
+- Then run `parse.py` on the host to reconstruct the binary profiling or coverage files
+
+Example:
+
+```bash
+python3 /path/to/Components/profiling/parse.py prof.log
+```
+
+If you want the files to be written directly to the host filesystem, use interface `1` with semihosting enabled instead.
+
+### What does `_mcleanup: tos overflow` usually mean?
+
+This error typically indicates a profiling configuration problem, and the first items to check are:
+
+- Heap is still too small for profiling runtime allocation
+- `-pg` or `-coverage` was applied to the wrong scope
+- Too much code was instrumented instead of only the target application
+
+In practice, insufficient heap is a very common cause. If increasing heap resolves earlier dump failures but triggers `_mcleanup: tos overflow`, review both memory size and instrumentation scope together.
+
+### Should I add `-pg` and `-coverage` to the whole SDK or all source files?
+
+No. These flags should only be added to the application code you want to analyze.
+
+Do not enable them globally for:
+
+- The whole SDK
+- All middleware
+- All BSP or driver code
+- Unrelated libraries
+
+Instrumenting too much code increases memory usage and may introduce unexpected profiling behavior. In IDE projects, apply the flags only to the target source file or source folder. In Makefile projects, restrict the flags through `APPDIRS` or equivalent per-application build rules.
+
+### I already configured heap to 2 KB, 20 KB, or 40 KB. Why can it still fail?
+
+Because the configured heap number alone is not enough evidence that the runtime can actually allocate that much memory.
+
+Please verify:
+
+- The linker script really leaves enough heap region at runtime
+- `_sbrk` is implemented correctly
+- Stack, heap, and other runtime sections are not overlapping
+- Your SDK port uses the same memory layout assumptions as the Nuclei SDK example
+
+In one real integration case, profiling still failed at 40 KB heap and started working only after increasing heap to 80 KB. If the usage flow is otherwise correct, treat allocation failure as the first debugging direction.

doc/source/changelog.rst

@@ -255,6 +255,7 @@ This is release version of ``0.9.0`` of Nuclei SDK.
   - Add LLVM/Clang ``-coverage`` option support in ``gcov.c`` with comprehensive Doxygen-style documentation
   - Fix printf format specifiers in ``gcov.c`` and ``gprof.c`` for better portability
   - Enhance profiling component documentation with GCC/LLVM toolchain support matrix, usage guide and result analysis examples
+  - Enhance ``Components/profiling/README.md`` with integration reminders and FAQ entries for common profiling/coverage issues, including limiting ``-pg``/``-coverage`` to target application sources, heap sizing considerations, standalone component reuse, console dump parsing via ``parse.py``, and troubleshooting dump corruption or ``_mcleanup: tos overflow`` errors
   - Improve profiling component ``_mcount`` function documentation in ``Components/profiling/gprof.c`` with detailed RISC-V calling convention explanation and LLVM bug workaround (https://github.com/llvm/llvm-project/issues/121103)
 
 V0.8.1

doc/source/design/app.rst

@@ -2197,6 +2197,19 @@ console when main part code is executed.
       For detailed toolchain-specific command-line analysis instructions, see the IDE configuration steps below
       and :ref:`demo_profiling_cmdline_usage`.
 
+.. warning::
+
+    To reduce integration issues when using profiling or coverage:
+
+    * Add ``-pg`` or ``-coverage`` only to the application source files you want to analyze.
+      Do not enable these options globally for the whole SDK or unrelated libraries.
+    * Profiling and coverage may require a large heap. In the linker script, ``__HEAP_SIZE``
+      is only the minimum reserved heap size. The actual heap available to ``malloc`` is bounded
+      by ``__heap_start`` and ``__heap_end``, so it also depends on the linker layout, stack placement,
+      and remaining RAM.
+    * If you use console/UART dump mode, the run will not directly create ``gmon.out`` or ``*.gcda``.
+      You must save the dump log and run ``Components/profiling/parse.py`` to reconstruct these files.
+
 Import or download Nuclei SDK 0.6.0 or later release NPK in Nuclei Studio, and then create a
 project called ``demo_profiling`` based on ``app-nsdk_demo_profiling`` using
 ``Create Nuclei RISC-V C/C++ Project`` Wizard as below:
@@ -2291,6 +2304,11 @@ To use the profiling and code coverage features from the command line:
       - When using ``-coverage`` flag, the application requires more memory to store coverage data.
         You may need to change the ``DOWNLOAD`` variable in the Makefile from ``sram`` to ``ddr``
         to ensure sufficient memory is available.
+      - ``__HEAP_SIZE`` in the linker script is only the minimum reserved heap size. The effective
+        heap available to ``malloc`` is determined by ``__heap_start`` and ``__heap_end``, so also
+        check the final linker layout and remaining RAM in your project.
+      - Apply ``APP_COMMON_FLAGS`` together with ``APPDIRS`` so profiling/coverage instrumentation
+        is limited to the target application source directories.
 
       - When the Zc extension is used, ``-fomit-frame-pointer`` is passed by default, but
         ``-pg`` and ``-fomit-frame-pointer`` are incompatible. If you encounter issues, you may