This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new b7305d87806 Documentation: nsh: document the top command
b7305d87806 is described below
commit b7305d878067d2434f05359c10403cba127420e5
Author: Jorge Guzman <[email protected]>
AuthorDate: Fri Jul 10 22:30:12 2026 -0300
Documentation: nsh: document the top command
The top command was added to nshlib in 2024 but was never documented.
Add a section to the NSH commands page covering syntax, options,
example output and configuration dependencies, including the
Linux-like summary header.
Also enable the command in the linum-stm32h753bi:nsh config: procfs,
CPU load measurement, stack coloration and task names, so that top
and ps are fully functional out of the box. This requires a dedicated
interrupt stack and larger IDLE/init task stacks: with SCHED_CPULOAD
the per-tick accounting runs in interrupt context, and with
ARCH_INTERRUPTSTACK=0 it lands on the stack of the interrupted task,
overflowing the 1 KiB IDLE stack and corrupting the adjacent heap.
Also add the VT100 escape sequences used by the top command screen
refresh as string literals in include/nuttx/vt100.h (VT100_STR_*),
next to the existing VT100_FMT_* definitions.
Tested on hardware.
Signed-off-by: Jorge Guzman <[email protected]>
---
Documentation/applications/nsh/commands.rst | 41 ++++++++++++++++++++++
.../arm/stm32h7/boards/linum-stm32h753bi/index.rst | 14 ++++++++
.../linum-stm32h753bi/configs/nsh/defconfig | 12 +++++--
include/nuttx/vt100.h | 9 +++++
4 files changed, 73 insertions(+), 3 deletions(-)
diff --git a/Documentation/applications/nsh/commands.rst
b/Documentation/applications/nsh/commands.rst
index e21c6e80044..2c3aa546ec6 100644
--- a/Documentation/applications/nsh/commands.rst
+++ b/Documentation/applications/nsh/commands.rst
@@ -1857,6 +1857,47 @@ command is run in background with the sleep command::
nsh>
2.0100 sec
+.. _cmdtop:
+
+``top`` Monitor Tasks
+=====================
+
+**Command Syntax**::
+
+ top [ -n <num>] [ -d <delay>] [ -p <pidlist>] [ -h ]
+
+**Synopsis**. Live task monitor similar to the UNIX ``top`` command. It
+periodically shows a summary header (uptime, task counts, CPU busy/idle
+and memory usage) followed by the same per-task information reported by
+the :ref:`ps <cmdps>` command, sorted by CPU load. The screen is
+refreshed in place. Press ``q``, ``ESC`` or ``Ctrl-C`` to exit.
+
+Options:
+
+========================= =================================================
+``-n <num>`` Show at most ``<num>`` tasks (highest CPU first)
+``-d <delay>`` Refresh interval in seconds (default 3)
+``-p <pidlist>`` Show only the given PIDs, comma-separated
+ (e.g. ``-p 0,2``)
+``-h`` Show the per-task heap usage column
+========================= =================================================
+
+**Example**::
+
+ nsh> top
+ top - up 00:01:01
+ Tasks: 2 total, 2 running, 0 sleeping
+ %Cpu(s): 9.2 busy, 90.8 idle
+ Mem : 1004876 total, 8140 used, 996736 free
+
+ TID PID PPID PRI POLICY TYPE NPX STATE EVENT SIGMASK
STACK USED FILLED CPU COMMAND
+ 0 0 0 0 FIFO Kthread - Ready
0000000000000000 0002024 0000500 24.7% 90.7% Idle_Task
+ 2 2 0 100 RR Task - Running
0000000000000000 0004048 0001952 48.2% 9.2% nsh_main
+
+NOTE: This command depends upon the *procfs* file system and CPU load
+measurement (``CONFIG_SCHED_CPULOAD``). The stack usage columns require
+``CONFIG_STACK_COLORATION``.
+
.. _cmdtruncate:
``truncate`` Set the Size of a File
diff --git
a/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst
b/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst
index c6f68b67ec6..d94f9df05eb 100644
--- a/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst
+++ b/Documentation/platforms/arm/stm32h7/boards/linum-stm32h753bi/index.rst
@@ -380,6 +380,20 @@ nsh
Configures the NuttShell (nsh) located at apps/examples/nsh. This
configuration enables a serial console on UART1.
+The procfs file system, CPU load measurement and stack coloration are
+enabled, so the system can be monitored live with the ``top`` command
+(press ``q`` to exit)::
+
+ nsh> top
+ top - up 00:00:19
+ Tasks: 2 total, 2 running, 0 sleeping
+ %Cpu(s): 8.1 busy, 91.9 idle
+ Mem : 1004876 total, 8140 used, 996736 free
+
+ TID PID PPID PRI POLICY TYPE NPX STATE EVENT SIGMASK
STACK USED FILLED CPU COMMAND
+ 0 0 0 0 FIFO Kthread - Ready
0000000000000000 0002024 0000500 24.7% 91.8% Idle_Task
+ 2 2 0 100 RR Task - Running
0000000000000000 0004048 0001952 48.2% 8.1% nsh_main
+
usbnsh
------
diff --git a/boards/arm/stm32h7/linum-stm32h753bi/configs/nsh/defconfig
b/boards/arm/stm32h7/linum-stm32h753bi/configs/nsh/defconfig
index 4f5046b5bf4..53928ff9959 100644
--- a/boards/arm/stm32h7/linum-stm32h753bi/configs/nsh/defconfig
+++ b/boards/arm/stm32h7/linum-stm32h753bi/configs/nsh/defconfig
@@ -5,8 +5,6 @@
# You can then do "make savedefconfig" to generate a new defconfig file that
includes your
# modifications.
#
-# CONFIG_NSH_DISABLE_IFCONFIG is not set
-# CONFIG_NSH_DISABLE_PS is not set
# CONFIG_STANDARD_SERIAL is not set
CONFIG_ARCH="arm"
CONFIG_ARCH_BOARD="linum-stm32h753bi"
@@ -16,6 +14,7 @@ CONFIG_ARCH_CHIP_STM32=y
CONFIG_ARCH_CHIP_STM32H753BI=y
CONFIG_ARCH_CHIP_STM32H7=y
CONFIG_ARCH_CHIP_STM32H7_CORTEXM7=y
+CONFIG_ARCH_INTERRUPTSTACK=2048
CONFIG_ARCH_STACKDUMP=y
CONFIG_ARMV7M_DCACHE=y
CONFIG_ARMV7M_DCACHE_WRITETHROUGH=y
@@ -26,12 +25,17 @@ CONFIG_BUILTIN=y
CONFIG_DEBUG_FEATURES=y
CONFIG_DEBUG_SYMBOLS=y
CONFIG_EXAMPLES_ALARM=y
+CONFIG_FS_PROCFS=y
+CONFIG_IDLETHREAD_STACKSIZE=2048
CONFIG_INIT_ENTRYPOINT="nsh_main"
+CONFIG_INIT_STACKSIZE=4096
CONFIG_INTELHEX_BINARY=y
CONFIG_LIBM=y
CONFIG_LINE_MAX=64
CONFIG_MM_REGIONS=4
CONFIG_NSH_BUILTIN_APPS=y
+CONFIG_NSH_DISABLE_IFUPDOWN=y
+CONFIG_NSH_DISABLE_VCONFIG=y
CONFIG_NSH_FILEIOSIZE=512
CONFIG_NSH_READLINE=y
CONFIG_PREALLOC_TIMERS=4
@@ -42,7 +46,9 @@ CONFIG_RR_INTERVAL=200
CONFIG_RTC_ALARM=y
CONFIG_RTC_DATETIME=y
CONFIG_RTC_DRIVER=y
+CONFIG_SCHED_CPULOAD_SYSCLK=y
CONFIG_SCHED_WAITPID=y
+CONFIG_STACK_COLORATION=y
CONFIG_START_DAY=6
CONFIG_START_MONTH=12
CONFIG_START_YEAR=2011
@@ -50,5 +56,5 @@ CONFIG_STM32_PWR=y
CONFIG_STM32_RTC=y
CONFIG_STM32_USART1=y
CONFIG_SYSTEM_NSH=y
-CONFIG_TASK_NAME_SIZE=0
+CONFIG_TASK_NAME_SIZE=20
CONFIG_USART1_SERIAL_CONSOLE=y
diff --git a/include/nuttx/vt100.h b/include/nuttx/vt100.h
index 3527348e0a3..16c3cde00e9 100644
--- a/include/nuttx/vt100.h
+++ b/include/nuttx/vt100.h
@@ -225,6 +225,15 @@
#define VT100_FMT_HVPOS "\033[%d;%df" /* Move cursor
to screen location v,h */
#define VT52_FMT_CURSORPOS "\033%d%d" /* Move cursor
to v,h location */
+/* VT100 escape sequences as strings, suitable for printf-style output */
+
+#define VT100_STR_CLEARSCREEN "\033[2J" /* Clear entire
screen */
+#define VT100_STR_CURSORHOME "\033[1;1H" /* Move cursor
to upper left corner */
+#define VT100_STR_CLEAREOL "\033[K" /* Erase to end
of current line */
+#define VT100_STR_CLEAREOS "\033[J" /* Erase to end
of screen */
+#define VT100_STR_BOLD "\033[1m" /* Turn bold
mode on */
+#define VT100_STR_MODESOFF "\033[0m" /* Turn off
character attributes */
+
/* VT100 Special Key Codes
*
* These are sent from the terminal back to the computer when the particular
