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.