Skip to content

Documentation: nsh: document the top command#19399

Merged
acassis merged 1 commit into
apache:masterfrom
JorgeGzm:top-linux-style
Jul 11, 2026
Merged

Documentation: nsh: document the top command#19399
acassis merged 1 commit into
apache:masterfrom
JorgeGzm:top-linux-style

Conversation

@JorgeGzm

@JorgeGzm JorgeGzm commented Jul 11, 2026

Copy link
Copy Markdown
Contributor

Summary

The nsh top command exists since 2024 but was never documented.

  • Add a top section to the NSH commands documentation page
    (Documentation/applications/nsh/commands.rst): syntax, options,
    example output and configuration dependencies.
  • Add a top usage example to the linum-stm32h753bi board
    documentation.
  • Enable the command in the linum-stm32h753bi:nsh defconfig: procfs,
    SCHED_CPULOAD, STACK_COLORATION and TASK_NAME_SIZE, so top
    and ps are fully functional out of the box. This also configures a
    dedicated interrupt stack and enlarges the 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 (~60% used at
    rest) and corrupting the adjacent heap.

Companion PR (nshlib improvements shown in the examples):
apache/nuttx-apps#3628

Impact

  • User: the top command is now discoverable in the documentation;
    linum-stm32h753bi:nsh users get top/ps working out of the box.
  • Build: none for the documentation. The defconfig adds procfs and
    CPU load measurement to one board configuration (flash: ~186 KB,
    1.7% SRAM on a 2 MB / 1 MB part).
  • Hardware: linum-stm32h753bi only (defconfig change).
  • Documentation: this PR is the documentation.
  • Compatibility: none.

Testing

  • Documentation: sphinx-build -b html completes with no warnings on
    the changed pages; new section renders at
    applications/nsh/commands.html#cmdtop.
  • Defconfig: tools/configure.sh linum-stm32h753bi:nsh from distclean
    • build, then verified on hardware:
  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
  • Without the interrupt/IDLE stack changes, enabling SCHED_CPULOAD
    on this board causes heap corruption and random asserts ("Stack
    pointer is not within the stack"), reproduced and fixed on hardware.
  • tools/checkpatch.sh -g HEAD~1..HEAD: all checks pass

@github-actions github-actions Bot added Area: Documentation Improvements or additions to documentation Size: S The size of the change in this PR is small Board: arm labels Jul 11, 2026
linguini1
linguini1 previously approved these changes Jul 11, 2026
@github-actions

github-actions Bot commented Jul 11, 2026

Copy link
Copy Markdown

MemBrowse Memory Report

No memory changes detected for:

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 <jorge.gzm@gmail.com>
@JorgeGzm JorgeGzm dismissed stale reviews from xiaoxiang781216 and linguini1 via 1e2f9cb July 11, 2026 10:13
@JorgeGzm JorgeGzm requested a review from jerpelea as a code owner July 11, 2026 10:13
@acassis acassis merged commit b7305d8 into apache:master Jul 11, 2026
43 of 56 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Area: Documentation Improvements or additions to documentation Board: arm Size: S The size of the change in this PR is small

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants