tools: replace showstack.sh with stackusage.py

[xiaoxiang781216]

Summary

• Replace tools/showstack.sh with tools/stackusage.py for static stack
  analysis with call graph based worst-case estimation.
• Reads DWARF .debug_frame CFA offsets via readelf -wF for per-function
  stack sizes, builds call graphs from objdump -d disassembly, resolves
  source locations via addr2line -fe.
• Zero Python package dependencies — uses only the Python standard library
  plus standard toolchain binaries (readelf, objdump, addr2line).
• Supports both GNU and LLVM toolchains via -p/--prefix option
  (e.g. -p arm-none-eabi- for GCC, -p llvm- for LLVM).
• Works with all architectures supported by the toolchain (ARM, AArch64,
  x86, x86_64, RISC-V, MIPS, Xtensa, PowerPC, SPARC, TriCore, SuperH, etc.).
• Flags uncertain cases: recursion, indirect calls (function pointers),
  and missing DWARF data.
• Adds Documentation/debugging/stackusage.rst.

Impact

• New feature added? YES — stackusage.py replaces showstack.sh.
• User impact? YES — showstack.sh removed, use stackusage.py instead.
• Build impact? NO
• Hardware impact? NO
• Documentation update needed? YES — included (stackusage.rst).
• Security implications? NO
• Backward compatibility? showstack.sh is removed and replaced by stackusage.py.

Testing

Build Host(s): Linux x86_64
Target(s): nucleo-f429zi:nsh (arm-none-eabi-gcc, CONFIG_DEBUG_SYMBOLS=y)

Testing logs after change:

$ python3 tools/stackusage.py -p arm-none-eabi- -n 20 nuttx

Total  Self  Backtrace                  File:Line
-----  ----  -------------------------  -----------------------------------------------
@1696    16  sh_main(26)                apps/system/nsh/sh_main.c:40
         16  nsh_system_ctty(28)        apps/nshlib/nsh_system.c:105
        ^32  nsh_system_(56)            apps/nshlib/nsh_system.c:41
        ^48  nsh_session(380)           apps/nshlib/nsh_session.c:73
        ^48  nsh_script(368)            apps/nshlib/nsh_script.c:98
        ^56  nsh_parse(292)             apps/nshlib/nsh_parse.c:2981
       ^240  nsh_parse_command(1548)    apps/nshlib/nsh_parse.c:2481
        @96  nsh_execute(700)           apps/nshlib/nsh_parse.c:510
        ^56  nsh_builtin(272)           apps/nshlib/nsh_builtin.c:76
         88  exec_builtin(404)          apps/builtin/exec_builtin.c:61
         48  task_spawn(76)             nuttx/sched/task/task_spawn.c:314
         72  nxtask_spawn_exec(162)     nuttx/sched/task/task_spawn.c:191
         64  nxtask_spawn_create(146)   nuttx/sched/task/task_spawn.c:88
         40  nxtask_init(280)           nuttx/sched/task/task_init.c:93
         40  group_setuptaskfiles(128)  nuttx/sched/group/group_setuptaskfiles.c:65
         24  spawn_file_actions(110)    nuttx/sched/task/task_spawnparms.c:257
         32  nxspawn_open(120)          nuttx/sched/task/task_spawnparms.c:87
         32  fdlist_open(42)            nuttx/fs/vfs/fs_open.c:411
         48  nx_vopen(112)              nuttx/fs/vfs/fs_open.c:313
        ^64  file_vopen(410)            nuttx/fs/vfs/fs_open.c:124
         24  inode_find(72)             nuttx/fs/inode/fs_inodefind.c:53
         24  inode_search(84)           nuttx/fs/inode/fs_inodesearch.c:470
         ...
@1680    24  nsh_main(84)               apps/system/nsh/nsh_main.c:54
        ^24  nsh_consolemain(62)        apps/nshlib/nsh_consolemain.c:65
        ^48  nsh_session(380)           apps/nshlib/nsh_session.c:73
         ...

[Copilot]

Pull request overview

Replaces the legacy showstack.sh stack-usage sorter with a Python-based static stack analyzer that can combine GCC .su data with an objdump-derived call graph to estimate worst-case stack depth, and documents the new workflow.

Changes:

• Added tools/stackusage.py implementing .su parsing, optional call-graph extraction, and worst-case stack depth estimation with uncertainty reasons.
• Removed tools/showstack.sh and updated Kconfig help text to point users at the new tool.
• Added new documentation page and linked it from the debugging docs index.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tools/stackusage.py	New Python analyzer for per-function self + worst-case total stack usage with uncertainty reporting.
tools/showstack.sh	Removed the old .su sorting shell script.
Kconfig	Updates STACK_USAGE help text to reference tools/stackusage.py.
Documentation/debugging/stackusage.rst	New documentation for using the new stack usage analyzer.
Documentation/debugging/index.rst	Adds stackusage.rst to the debugging docs toctree.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[linguini1]

Why is copilot reviewing this PR? Is the feature enabled on the NuttX repo?

[xiaoxiang781216]

Why is copilot reviewing this PR? Is the feature enabled on the NuttX repo?

I request Coplit review my patch

[linguini1]

Why is copilot reviewing this PR? Is the feature enabled on the NuttX repo?

I request Coplit review my patch

Okay! Makes sense, thanks!

[acassis]

@xiaoxiang781216 same comment as @raiden00pl did here: #18396

If this code is supposed to be integrated in the build system, it is better to avoid Python dependence.
Not a BIG issue, but as he commented, we need to decide and vote if Python is a requirement for NuttX.

In that PR @Abhishekmishra2808 rewrote this Python script as C file.

I understand that currently it is not used in the build-system, but may it become integrated into build system in the future? If that is the case, then we need to rewrite it.

[raiden00pl]

@acassis this PR is a completely different case. In this PR, we don't add Python as a dependency to the build system. This PR is about a debug tool; the debug tools in nuttx have been using Python for a long time.

Using Python for such tools is an obvious choice for me personally, it gives endless possibilities and is now easy to vibe-code

[acassis]

@acassis this PR is a completely different case. In this PR, we don't add Python as a dependency to the build system. This PR is about a debug tool; the debug tools in nuttx have been using Python for a long time.

Using Python for such tools is an obvious choice for me personally, it gives endless possibilities and is now easy to vibe-code

Hi @raiden00pl thank you for explanation. Ok, so everything is fine for this PR