This is an automated email from the ASF dual-hosted git repository. xiaoxiang pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 1295ccdd0e38930b5b9cdfc1ccf797654c499412 Author: anjiahao <[email protected]> AuthorDate: Wed Oct 25 22:30:26 2023 +0800 Documentation:add Documentation for stack statistics Signed-off-by: anjiahao <[email protected]> --- Documentation/guides/index.rst | 1 + Documentation/guides/stackrecord.rst | 73 ++++++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+) diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index e8a8f5e253..9f092e140a 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -29,3 +29,4 @@ Guides automounter.rst stm32nullpointer.rst stm32ccm.rst + stackrecord.rst diff --git a/Documentation/guides/stackrecord.rst b/Documentation/guides/stackrecord.rst new file mode 100644 index 0000000000..13bad93b46 --- /dev/null +++ b/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.
