doc: clarify STACKSZ and HEAPSZ behavior in evalsoc linker layout

Document how the default evalsoc linker scripts arrange heap and stack
from opposite ends of RAM, and how SMP reserves one fixed stack slot
per hart from the shared stack area.

Clarify that HEAPSZ only controls the minimum heap reservation in the
linker layout. The effective runtime heap used by malloc is bounded by
__heap_start and __heap_end, so increasing HEAPSZ alone does not always
increase the actual heap available at runtime.

Also add matching comments in evalsoc GCC linker scripts and record the
documentation clarification in changelog.rst.

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

Author: fanghuaqi

SoC/evalsoc/Board/nuclei_fpga_eval/Source/GCC/gcc_evalsoc_ddr.ld

@@ -42,7 +42,9 @@ REGION_ALIAS("DATA_LMA", ram)
 SECTIONS
 {
   /* To provide symbol __STACK_SIZE, __HEAP_SIZE and __SMP_CPU_CNT */
+  /* __STACK_SIZE is the reserved stack size for each hart. */
   PROVIDE(__STACK_SIZE = 2K);
+  /* __HEAP_SIZE is the minimum heap space reserved in linker layout. */
   PROVIDE(__HEAP_SIZE = 2K);
   PROVIDE(__SMP_CPU_CNT = 1);
   __TOT_STACK_SIZE = __STACK_SIZE * __SMP_CPU_CNT;
@@ -208,11 +210,18 @@ SECTIONS
    * 1. heap need to be align at 16 bytes
    * 2. __heap_start and __heap_end symbol need to be defined
    * 3. reserved at least __HEAP_SIZE space for heap
+   *
+   * Note:
+   * - __HEAP_SIZE defines the minimum reserved heap size in linker layout
+   * - the C runtime heap implementation uses the range [__heap_start, __heap_end)
+   * - therefore actual heap available at runtime can be larger than __HEAP_SIZE
+   *   when there is extra free RAM between .bss/.heap and the stack region
    */
   .heap (NOLOAD)   : ALIGN(16)
   {
     . = ALIGN(16);
     PROVIDE( __heap_start = . );
+    /* Reserve at least __HEAP_SIZE bytes for heap from low address upward. */
     . += __HEAP_SIZE;
     . = ALIGN(16);
     PROVIDE( __heap_limit = . );
@@ -221,11 +230,15 @@ SECTIONS
   .stack ORIGIN(RAM) + LENGTH(RAM) - __TOT_STACK_SIZE (NOLOAD) :
   {
     . = ALIGN(16);
+    /* Heap can grow up to the start of the reserved stack area. */
     PROVIDE( _heap_end = . );
     PROVIDE( __heap_end = . );
     PROVIDE( __stack_start__ = . );
     PROVIDE( __StackLimit = . );
     PROVIDE( __StackBottom = . );
+    /* Reserve per-hart stack slots at the top of RAM. In SMP, overflow may
+     * corrupt a neighboring hart stack.
+     */
     . += __TOT_STACK_SIZE;
     . = ALIGN(16);
     PROVIDE( __StackTop = . );

SoC/evalsoc/Board/nuclei_fpga_eval/Source/GCC/gcc_evalsoc_flash.ld

@@ -41,7 +41,9 @@ REGION_ALIAS("RAM", ram)
 SECTIONS
 {
   /* To provide symbol __STACK_SIZE, __HEAP_SIZE and __SMP_CPU_CNT */
+  /* __STACK_SIZE is the reserved stack size for each hart. */
   PROVIDE(__STACK_SIZE = 2K);
+  /* __HEAP_SIZE is the minimum heap space reserved in linker layout. */
   PROVIDE(__HEAP_SIZE = 2K);
   PROVIDE(__SMP_CPU_CNT = 1);
   __TOT_STACK_SIZE = __STACK_SIZE * __SMP_CPU_CNT;
@@ -206,11 +208,18 @@ SECTIONS
    * 1. heap need to be align at 16 bytes
    * 2. __heap_start and __heap_end symbol need to be defined
    * 3. reserved at least __HEAP_SIZE space for heap
+   *
+   * Note:
+   * - __HEAP_SIZE defines the minimum reserved heap size in linker layout
+   * - the C runtime heap implementation uses the range [__heap_start, __heap_end)
+   * - therefore actual heap available at runtime can be larger than __HEAP_SIZE
+   *   when there is extra free RAM between .bss/.heap and the stack region
    */
   .heap (NOLOAD)   : ALIGN(16)
   {
     . = ALIGN(16);
     PROVIDE( __heap_start = . );
+    /* Reserve at least __HEAP_SIZE bytes for heap from low address upward. */
     . += __HEAP_SIZE;
     . = ALIGN(16);
     PROVIDE( __heap_limit = . );
@@ -219,11 +228,15 @@ SECTIONS
   .stack ORIGIN(RAM) + LENGTH(RAM) - __TOT_STACK_SIZE (NOLOAD) :
   {
     . = ALIGN(16);
+    /* Heap can grow up to the start of the reserved stack area. */
     PROVIDE( _heap_end = . );
     PROVIDE( __heap_end = . );
     PROVIDE( __stack_start__ = . );
     PROVIDE( __StackLimit = . );
     PROVIDE( __StackBottom = . );
+    /* Reserve per-hart stack slots at the top of RAM. In SMP, overflow may
+     * corrupt a neighboring hart stack.
+     */
     . += __TOT_STACK_SIZE;
     . = ALIGN(16);
     PROVIDE( __StackTop = . );

SoC/evalsoc/Board/nuclei_fpga_eval/Source/GCC/gcc_evalsoc_flashxip.ld

@@ -40,7 +40,9 @@ REGION_ALIAS("RAM", ram)
 SECTIONS
 {
   /* To provide symbol __STACK_SIZE, __HEAP_SIZE and __SMP_CPU_CNT */
+  /* __STACK_SIZE is the reserved stack size for each hart. */
   PROVIDE(__STACK_SIZE = 2K);
+  /* __HEAP_SIZE is the minimum heap space reserved in linker layout. */
   PROVIDE(__HEAP_SIZE = 2K);
   PROVIDE(__SMP_CPU_CNT = 1);
   __TOT_STACK_SIZE = __STACK_SIZE * __SMP_CPU_CNT;
@@ -208,11 +210,18 @@ SECTIONS
    * 1. heap need to be align at 16 bytes
    * 2. __heap_start and __heap_end symbol need to be defined
    * 3. reserved at least __HEAP_SIZE space for heap
+   *
+   * Note:
+   * - __HEAP_SIZE defines the minimum reserved heap size in linker layout
+   * - the C runtime heap implementation uses the range [__heap_start, __heap_end)
+   * - therefore actual heap available at runtime can be larger than __HEAP_SIZE
+   *   when there is extra free RAM between .bss/.heap and the stack region
    */
   .heap (NOLOAD)   : ALIGN(16)
   {
     . = ALIGN(16);
     PROVIDE( __heap_start = . );
+    /* Reserve at least __HEAP_SIZE bytes for heap from low address upward. */
     . += __HEAP_SIZE;
     . = ALIGN(16);
     PROVIDE( __heap_limit = . );
@@ -221,11 +230,15 @@ SECTIONS
   .stack ORIGIN(RAM) + LENGTH(RAM) - __TOT_STACK_SIZE (NOLOAD) :
   {
     . = ALIGN(16);
+    /* Heap can grow up to the start of the reserved stack area. */
     PROVIDE( _heap_end = . );
     PROVIDE( __heap_end = . );
     PROVIDE( __stack_start__ = . );
     PROVIDE( __StackLimit = . );
     PROVIDE( __StackBottom = . );
+    /* Reserve per-hart stack slots at the top of RAM. In SMP, overflow may
+     * corrupt a neighboring hart stack.
+     */
     . += __TOT_STACK_SIZE;
     . = ALIGN(16);
     PROVIDE( __StackTop = . );

SoC/evalsoc/Board/nuclei_fpga_eval/Source/GCC/gcc_evalsoc_ilm.ld

@@ -40,7 +40,9 @@ REGION_ALIAS("DATA_LMA", ram)
 SECTIONS
 {
   /* To provide symbol __STACK_SIZE, __HEAP_SIZE and __SMP_CPU_CNT */
+  /* __STACK_SIZE is the reserved stack size for each hart. */
   PROVIDE(__STACK_SIZE = 2K);
+  /* __HEAP_SIZE is the minimum heap space reserved in linker layout. */
   PROVIDE(__HEAP_SIZE = 2K);
   PROVIDE(__SMP_CPU_CNT = 1);
   __TOT_STACK_SIZE = __STACK_SIZE * __SMP_CPU_CNT;
@@ -206,11 +208,18 @@ SECTIONS
    * 1. heap need to be align at 16 bytes
    * 2. __heap_start and __heap_end symbol need to be defined
    * 3. reserved at least __HEAP_SIZE space for heap
+   *
+   * Note:
+   * - __HEAP_SIZE defines the minimum reserved heap size in linker layout
+   * - the C runtime heap implementation uses the range [__heap_start, __heap_end)
+   * - therefore actual heap available at runtime can be larger than __HEAP_SIZE
+   *   when there is extra free RAM between .bss/.heap and the stack region
    */
   .heap (NOLOAD)   : ALIGN(16)
   {
     . = ALIGN(16);
     PROVIDE( __heap_start = . );
+    /* Reserve at least __HEAP_SIZE bytes for heap from low address upward. */
     . += __HEAP_SIZE;
     . = ALIGN(16);
     PROVIDE( __heap_limit = . );
@@ -219,11 +228,15 @@ SECTIONS
   .stack ORIGIN(RAM) + LENGTH(RAM) - __TOT_STACK_SIZE (NOLOAD) :
   {
     . = ALIGN(16);
+    /* Heap can grow up to the start of the reserved stack area. */
     PROVIDE( _heap_end = . );
     PROVIDE( __heap_end = . );
     PROVIDE( __stack_start__ = . );
     PROVIDE( __StackLimit = . );
     PROVIDE( __StackBottom = . );
+    /* Reserve per-hart stack slots at the top of RAM. In SMP, overflow may
+     * corrupt a neighboring hart stack.
+     */
     . += __TOT_STACK_SIZE;
     . = ALIGN(16);
     PROVIDE( __StackTop = . );

SoC/evalsoc/Board/nuclei_fpga_eval/Source/GCC/gcc_evalsoc_sram.ld

@@ -43,7 +43,9 @@ REGION_ALIAS("DATA_LMA", ram)
 SECTIONS
 {
   /* To provide symbol __STACK_SIZE, __HEAP_SIZE and __SMP_CPU_CNT */
+  /* __STACK_SIZE is the reserved stack size for each hart. */
   PROVIDE(__STACK_SIZE = 2K);
+  /* __HEAP_SIZE is the minimum heap space reserved in linker layout. */
   PROVIDE(__HEAP_SIZE = 2K);
   PROVIDE(__SMP_CPU_CNT = 1);
   __TOT_STACK_SIZE = __STACK_SIZE * __SMP_CPU_CNT;
@@ -209,11 +211,18 @@ SECTIONS
    * 1. heap need to be align at 16 bytes
    * 2. __heap_start and __heap_end symbol need to be defined
    * 3. reserved at least __HEAP_SIZE space for heap
+   *
+   * Note:
+   * - __HEAP_SIZE defines the minimum reserved heap size in linker layout
+   * - the C runtime heap implementation uses the range [__heap_start, __heap_end)
+   * - therefore actual heap available at runtime can be larger than __HEAP_SIZE
+   *   when there is extra free RAM between .bss/.heap and the stack region
    */
   .heap (NOLOAD)   : ALIGN(16)
   {
     . = ALIGN(16);
     PROVIDE( __heap_start = . );
+    /* Reserve at least __HEAP_SIZE bytes for heap from low address upward. */
     . += __HEAP_SIZE;
     . = ALIGN(16);
     PROVIDE( __heap_limit = . );
@@ -222,11 +231,15 @@ SECTIONS
   .stack ORIGIN(RAM) + LENGTH(RAM) - __TOT_STACK_SIZE (NOLOAD) :
   {
     . = ALIGN(16);
+    /* Heap can grow up to the start of the reserved stack area. */
     PROVIDE( _heap_end = . );
     PROVIDE( __heap_end = . );
     PROVIDE( __stack_start__ = . );
     PROVIDE( __StackLimit = . );
     PROVIDE( __StackBottom = . );
+    /* Reserve per-hart stack slots at the top of RAM. In SMP, overflow may
+     * corrupt a neighboring hart stack.
+     */
     . += __TOT_STACK_SIZE;
     . = ALIGN(16);
     PROVIDE( __StackTop = . );

doc/source/changelog.rst

@@ -219,6 +219,7 @@ This is release version of ``0.9.0`` of Nuclei SDK.
   - Update documentation about n100 with eclic is now supported in Nuclei SDK
   - Add ``demo_smpcc`` and ``demo_ecc`` application documentation in ``app.rst``
   - Update :ref:`design_app_demo_profiling` documentation in ``app.rst`` with detailed GCC and LLVM/Clang toolchain-specific instructions for profiling and coverage analysis, and command-line workflows using ``lcov``
+  - Clarify :ref:`develop_buildsystem_var_stacksz` and :ref:`develop_buildsystem_var_heapsz` documentation in ``buildsystem.rst`` to explain the default ``evalsoc`` stack/heap layout, per-hart SMP stack reservation, and that ``HEAPSZ`` only controls the minimum linker reservation while the effective runtime heap is bounded by ``__heap_start`` and ``__heap_end``
   - Add warning note in :ref:`develop_buildsystem_var_semihost` about heap and stack collision risk when using semihosting with ``malloc``, due to newlib semihost ``_sbrk`` implementation assumes unlimited heap size
 
 * Test

doc/source/develop/buildsystem.rst

@@ -1494,15 +1494,58 @@ ld options ``-Wl,--defsym=__STACK_SIZE=$(STACKSZ)`` to overwrite the default val
 **STACKSZ** variable must be a valid value accepted by ld, such as 0x2000, 2K, 4K, 8192.
 
 For SMP version, stack size space need to reserve **STACKSZ** x SMP Core Count size.
+For the default ``evalsoc`` startup implementation, each hart gets its own stack window of
+size ``__STACK_SIZE`` from the reserved stack area.
 
 You can refer to ``SoC/evalsoc/Board/nuclei_fpga_eval/Source/GCC/gcc_evalsoc_ilm.ld`` for smp version.
 
+For the default ``evalsoc`` GCC linker scripts in Nuclei SDK, the stack and heap are arranged
+from opposite directions in the RAM region:
+
+- ``.data/.bss`` and other runtime sections are placed first in RAM
+- the ``.heap`` section starts after these runtime sections from low address to high address
+- the linker script reserves at least ``__HEAP_SIZE`` bytes in ``.heap``
+- the ``.stack`` section is placed at the top of RAM and grows downward logically, while the
+  linker reserves ``__STACK_SIZE * __SMP_CPU_CNT`` bytes for it
+- ``__heap_end`` is defined at the start of the stack section, so the effective heap is bounded
+  by the free space between ``__heap_start`` and the reserved stack area
+
+This means increasing ``STACKSZ`` reduces the remaining room available for heap growth, and
+increasing ``HEAPSZ`` increases the minimum heap space reserved by the linker before the stack
+area. In the default ``evalsoc`` runtime, however, ``malloc`` is bounded by ``__heap_start``
+and ``__heap_end`` rather than by ``__HEAP_SIZE`` alone. So changing ``HEAPSZ`` by itself does
+not necessarily increase the effective heap available at runtime unless the final linker layout
+also leaves more room between the heap start and the reserved stack area. When debugging
+memory-related issues, always consider stack size, heap reservation, actual section usage,
+and total RAM size together.
+
+For single-core layouts, ``STACKSZ`` can be understood as the minimum stack space reserved for
+the current hart, and the runtime only needs to avoid colliding with the heap or other RAM
+sections. For SMP layouts, this interpretation is no longer sufficient: each hart is assigned a
+fixed stack slot of size ``__STACK_SIZE`` from the shared stack area. If one hart uses more than
+its reserved stack slot, it may overwrite the neighboring hart stack instead of only consuming
+more shared free RAM.
+
+This layout keeps the linker script simple and makes memory reservation tuning easier through
+``STACKSZ`` and ``HEAPSZ`` without requiring users to rewrite the linker script structure for
+common adjustments. It also improves RAM utilization, because the heap can continue to use the
+free space below the reserved stack area instead of being limited to a completely fixed-size
+region. This design is especially useful for applications such as profiling and coverage, where
+runtime memory demand can vary significantly between different builds and workloads.
+
+.. note::
+
+    The linker script design in Nuclei SDK may vary by SoC, board, runtime library, or specific
+    memory map requirements. The ``evalsoc`` layout described here is a reference design to help
+    explain how ``STACKSZ`` and ``HEAPSZ`` interact, but it is not guaranteed to match every SoC
+    or every customer integration scenario exactly.
+
 .. _develop_buildsystem_var_heapsz:
 
 HEAPSZ
 ~~~~~~
 
-**HEAPSZ** variable is used to control the heap size reserved in linker script,
+**HEAPSZ** variable is used to control the minimum heap size reserved in linker script,
 this need to cooperate with link script file and linker options.
 
 In link script file, ``__HEAP_SIZE`` symbol need to use ``PROVIDE`` feature of ld
@@ -1512,6 +1555,20 @@ ld options ``-Wl,--defsym=__HEAP_SIZE=$(HEAPSZ)`` to overwrite the default value
 
 **HEAPSZ** variable must be a valid value accepted by ld, such as 0x2000, 2K, 4K, 8192.
 
+For the default C runtime heap implementations used by Nuclei SDK, such as newlib and
+libncrt, the actual heap available to dynamic allocation is bounded by ``__heap_start``
+and ``__heap_end``. In other words, ``__HEAP_SIZE`` is the minimum reserved heap size in
+linker layout, while the effective runtime heap size depends on the final linker layout,
+stack placement, and remaining RAM.
+
+As a result, increasing ``HEAPSZ`` does not directly set the runtime heap size seen by
+``malloc``. It only raises the minimum reservation that the linker must keep for the heap
+region. If the final layout does not leave additional space between ``__heap_start`` and
+``__heap_end``, the effective heap size may stay unchanged even after ``HEAPSZ`` is increased.
+
+This is especially important for features such as profiling and coverage, which may allocate
+large runtime buffers and therefore require a more relaxed memory layout.
+
 .. _develop_buildsystem_var_riscv_arch:
 
 RISCV_ARCH