From fae8d6f73241eb884e2d52e6813eb86c45b03b19 Mon Sep 17 00:00:00 2001
From: hanzhijian <hanzhijian@zepp.com>
Date: Wed, 27 May 2026 10:54:02 +0800
Subject: [PATCH] Documentation: Document stackmonitor command.

Add documentation for the stackmonitor command, which starts a
background daemon to monitor stack usage for all tasks and threads.

Refs #11081

Signed-off-by: hanzj <your-email@example.com>
---
 .../system/stackmonitor/index.rst             | 107 ++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/Documentation/applications/system/stackmonitor/index.rst b/Documentation/applications/system/stackmonitor/index.rst
index 2a94a4b1ef25e..74214879e366e 100644
--- a/Documentation/applications/system/stackmonitor/index.rst
+++ b/Documentation/applications/system/stackmonitor/index.rst
@@ -1,3 +1,110 @@
 ==============================
 ``stackmonitor`` Stack Monitor
 ==============================
+
+Overview
+========
+
+The ``stackmonitor`` command starts a background daemon that periodically
+monitors stack usage for all tasks and threads in the system. It reads the
+procfs filesystem to collect stack size and usage information, helping
+developers identify potential stack overflow issues and optimize memory
+allocation.
+
+The daemon runs as a separate task and outputs a table showing the PID,
+stack size, stack used, and thread name (if available) for each task.
+The monitoring continues until explicitly stopped with the
+``stackmonitor_stop`` command.
+
+Configuration
+=============
+
+Enable the command with ``CONFIG_SYSTEM_STACKMONITOR``. This option depends
+on:
+
+- ``CONFIG_FS_PROCFS`` - procfs filesystem support
+- ``CONFIG_STACK_COLORATION`` - stack coloration feature for usage tracking
+
+The following configuration options are available:
+
+``CONFIG_SYSTEM_STACKMONITOR_STACKSIZE``
+  Stack size for the monitor daemon task. Default: 2048 bytes.
+
+``CONFIG_SYSTEM_STACKMONITOR_PRIORITY``
+  Priority for the monitor daemon task. Default: 50.
+
+``CONFIG_SYSTEM_STACKMONITOR_INTERVAL``
+  Monitoring interval in seconds. Default: 2 seconds.
+
+``CONFIG_SYSTEM_STACKMONITOR_MOUNTPOINT``
+  procfs mount point path. Default: ``/proc``.
+
+Usage
+=====
+
+.. code-block:: console
+
+   stackmonitor
+
+Start the stack monitoring daemon. If the daemon is already running, display
+its current status.
+
+.. code-block:: console
+
+   stackmonitor_stop
+
+Stop the running stack monitoring daemon.
+
+Options
+=======
+
+The ``stackmonitor`` and ``stackmonitor_stop`` commands accept no options.
+
+Examples
+========
+
+Start the stack monitor and observe the output:
+
+.. code-block:: console
+
+   nsh> stackmonitor
+   Stack Monitor: Started: 3
+
+The daemon will periodically output stack usage information:
+
+.. code-block:: console
+
+   PID   SIZE   USED   THREAD NAME
+   0     2048   1024   Idle_Task
+   1     2048   512    hpwork
+   2     2048   768    nsh_main
+   3     2048   256    Stack Monitor
+
+Check the daemon status:
+
+.. code-block:: console
+
+   nsh> stackmonitor
+   Stack Monitor: Running: 3
+
+Stop the daemon:
+
+.. code-block:: console
+
+   nsh> stackmonitor_stop
+   Stack Monitor: Stopping: 3
+   Stack Monitor: Stopped: 3
+
+Notes
+=====
+
+- The daemon requires the procfs filesystem to be mounted at the configured
+  mount point (default ``/proc``).
+- Stack usage tracking depends on the ``CONFIG_STACK_COLORATION`` feature,
+  which fills unused stack space with a known pattern to detect usage.
+- The daemon will automatically stop after 100 consecutive errors reading
+  the procfs directory.
+- The monitoring interval can be adjusted at compile time using
+  ``CONFIG_SYSTEM_STACKMONITOR_INTERVAL``.
+- The output format includes the thread name only when
+  ``CONFIG_TASK_NAME_SIZE`` is greater than 0.