Documentation:add Documentation for stack statistics

Signed-off-by: anjiahao <[email protected]>

Documentation/guides/index.rst

@@ -29,3 +29,4 @@ Guides
   automounter.rst
   stm32nullpointer.rst
   stm32ccm.rst
+  stackrecord.rst

Documentation/guides/stackrecord.rst

@@ -0,0 +1,73 @@
+=========================
+Run time stack statistics
+=========================
+
+Introduce
+=========
+When debugging code, it is often necessary to focus on how to track
+the maximum stack usage of the calling functions in order to optimize
+the code structure and reduce stack usage. This article will introduce
+a method based on the running state to track the deepest call stack of all tasks.
+
+Configuration
+=============
+   .. code-block:: c
+
+      CONFIG_SCHED_STACKRECORD=32
+      CONFIG_ARCH_INSTRUMENT_ALL=y
+
+```CONFIG_SCHED_STACKRECORD``` is used to record the maximum stack usage of all tasks
+```CONFIG_ARCH_INSTRUMENT_ALL``` is used to instrument all code.
+
+Please note that CONFIG_ARCH_INSTRUMENT_ALL is not necessary.
+This configuration option will instrument all code,
+but if you only want to instrument specific functions,
+you can add '-finstrument-functions' to the corresponding makefile.
+
+Example
+=======
+1. ```./tools/configure.sh esp32c3-devkit:stack```
+2. ```make -j20```
+3. flash the image to your board
+   .. code-block :: bash
+
+      nsh> cat /proc/1/stack
+      StackAlloc: 0x3fc8b5b0
+      StackBase:  0x3fc8b5e0
+      StackSize:  2000
+      MaxStackUsed:1344
+      Backtrace         Size
+      0x42009198          32
+      0x42009200          48
+      0x420081a0         128
+      0x42008d18          64
+      0x4201da60          80
+      0x420199e0          80
+      0x42018c6c          48
+      0x420194f4          48
+      0x42017d30          32
+      0x4201634c          32
+      0x420163ac          48
+      0x42016408          32
+      0x420132c0          48
+      0x42010598          32
+      0x4200fd98          48
+      0x4200f5dc          80
+      0x4200f8e0         160
+
+Implementation details
+======================
+The specific principle is based on the instrumentation of gcc.
+In the TCB (Thread Control Block) of the corresponding task,
+the maximum value of the stack pointer (sp) is recorded at the entry of each function.
+If it is the maximum value, the backtrace is recorded.
+
+Notice
+======
+Be cautious when using the CONFIG_ARCH_INSTRUMENT_ALL option:
+1. It will instrument every function, which may have a risk of recursion.
+2. It will also instrument entry functions, such as _start(). At this point,
+the bss segment and data segment have not been initialized,
+which may cause errors. The current implementation uses a magic number to avoid this,
+but it performs poorly during hot start. The solution is to mark
+the entry function with the noinstrument_function flag to prevent instrumentation.