Apache NuttX 13.1.0 NSH 常用命令详解

目标：系统整理 NuttX Shell（NSH）的常用命令——帮助体系、系统信息、文件操作、挂载与设备、进程与内存查看，所有命令与回显均已在 Ubuntu 22.04 的 NuttX 13.1.0 sim:nsh 目标上实测通过。

一、环境信息

项目	内容
操作系统	Ubuntu 22.04.5 LTS
系统架构	x86_64
NuttX	13.1.0（commit 2b5c0de5e9，sim:nsh 配置）
运行方式	./nuttx 直接在开发机运行（NuttX sim 官方特性）
源码目录	/opt/nuttx/nuttx
命令来源	apps/nshlib（shell 内建）与 apps/system（内置应用）

说明：NSH 是 NuttX 自带的小型 shell，语法风格与 POSIX sh 接近，命令分两类——内建命令（编译进 NSH，如 ls/ps）与内置应用（Builtin Apps，如 hello/gpio/ostest）。可用命令集合由 .config 决定，本文以 sim:nsh 默认配置为准。

二、进入 NSH 与帮助体系

2.1 启动横幅

./nuttx

回显：

NuttShell (NSH) NuttX-13.1.0
nsh>

解说：sim:nsh 启动后先执行 /etc/init.d/init.rc（romfs 内嵌启动脚本，见第五章），随后进入 nsh> 提示符。

2.2 help —— 命令总表

nsh> help

help usage:  help [-v] [<cmd>]

    .           dirname     free        mount       set         umount
    [           date        help        mv          kill        unset
    ?           df          hexdump     pidof       pkill       uptime
    alias       dmesg       losetup     poweroff    sleep       watch
    unalias     echo        ln          quit        usleep      xd
    basename    env         ls          printf      source      wait
    break       exec        du          ps          test
    cat         exit        mkdir       pwd         time
    cd          expr        mkfatfs     readlink    true
    cp          false       mkfifo      rm          truncate
    cmp         fdinfo      mkrd        rmdir       uname

Builtin Apps:
    dd           gcov         hello        nsh          sh
    dumpstack    gpio         init         ostest

解说：上半部分是 NSH 内建命令，下半部分 Builtin Apps 是作为独立任务运行的程序。加 -v 可看每条命令的详细用法（help -v ls）。查单条命令用法直接输入不带参数的命令，如 mount 不带参数列出挂载表。

三、系统信息命令

3.1 uname —— 内核与构建信息

nsh> uname -a
NuttX 13.1.0 2b5c0de5e9 Oct 14 2026 18:06:15 sim sim

解说：依次为版本、构建 commit、编译时间、目标板（sim）、架构（sim）。真机目标此处显示如 stm32f4discovery arm 等。

3.2 ps —— 任务列表

nsh> ps

  TID   PID  PPID PRI POLICY   TYPE    NPX STATE    EVENT     SIGMASK            STACK COMMAND
    0     0     0   0 FIFO     Kthread   - Ready              0000000000000000 0069584 Idle_Task
    1     0     0 224 FIFO     Kthread   - Waiting  Semaphore 0000000000000000 0067448 sim_loop_wq 0x73295c6003f0 0x73295c600470
    2     0     0 224 FIFO     Kthread   - Waiting  Semaphore 0000000000000000 0067472 hpwork 0x40165f60 0x40165fe0
    4     4     0 100 FIFO     Task      - Waiting  Semaphore 0000000000000000 0067496 init_main
    9     9     4 100 FIFO     Task      - Running            0000000000000000 0067504 sh

💡 技术拓展：看 POLICY 与 PRI 列即 NuttX 调度策略——NuttX 默认固定优先级抢占式调度（数值越小优先级越高），同优先级默认FIFO 轮转（SCHED_FIFO），可选时间片轮转 SCHED_RR。上表 Idle_Task 优先级 0 永远就绪兜底；hpwork 是工作队列线程；sh（NSH 自身）运行在优先级 100。业务任务建任务时用 pthread_create/task_create 指定优先级与策略即可参与同一调度体系。本文 sim 环境即跑在该调度器上。

3.3 free —— 内存概况

nsh> free

      total       used       free    maxused    maxfree  nused  nfree name
   67108864    1858944   65249920    1859640   65190080    108      3 Umem

解说：Umem 是 NuttX 堆分配器统计——sim 配置下堆总量 64MB；used/maxused 用于排查内存泄漏基线。

3.4 uptime / date / env

nsh> uptime
18:06:37 up  0:00, load average: 0.00, 0.00, 0.00
nsh> date
Wed, Oct 14 18:06:37 2026
nsh> env
PWD=/
PATH=/bin

解说：uptime 含 load average（sim 下取宿主信息）；date 显示系统时间（sim 取宿主时钟）；env 输出环境变量，NSH 默认只有 PWD 与 PATH。

四、文件操作命令

4.1 文件系统布局

nsh> ls
/:
 bin/
 data/
 dev/
 etc/
 proc/
 tmp/

解说：/bin 为 binfs（内建命令以文件形式呈现）、/data 是宿主目录直通（hostfs）、/etc 是只读 romfs、/proc 内核信息、/tmp 是内存 vfat 磁盘。

4.2 创建、读写、复制、改名、删除

nsh> mkdir /demo
nsh> echo hello-nuttx > /demo/hello.txt
nsh> cat /demo/hello.txt
hello-nuttx
nsh> cp /demo/hello.txt /demo/hello2.txt
nsh> mv /demo/hello2.txt /demo/renamed.txt
nsh> ls /demo
/demo:
 hello.txt
 renamed.txt
nsh> rm /demo/renamed.txt
nsh> ls /demo
/demo:
 hello.txt

解说：echo 的输出重定向 > 是 NSH 基本能力；cat/cp/mv/rm/ls 语义与 Linux 一致；sim 的根文件系统可写，直接建目录存文件无问题。

4.3 目录导航

nsh> pwd
/
nsh> cd /demo
nsh> pwd
/demo

4.4 df —— 各挂载点容量

nsh> df

  Block    Number
  Size     Blocks       Used   Available Mounted on
     0          0          0           0 /bin
  4096  206014282  128971280    77043002 /data
    64          8          8           0 /etc
     0          0          0           0 /proc
   512        985          0         985 /tmp

解说：/data 反映宿主磁盘（4096 字节块，20 亿级块数即宿主大容量磁盘直通）；/etc 是 8 块 romfs（只读，对应初始化脚本）；/tmp 是 985 块 × 512B ≈ 505KB 的内存 vfat。

4.5 cat /etc/init.d/init.rc —— 启动脚本

nsh> cat /etc/init.d/init.rc
service console sh
   restart_period 1000

on init
   mkrd -m 2 -s 512 1024
   mkfatfs /dev/ram2
   mount -t vfat /dev/ram2 "/tmp"
   mount -t hostfs -o fs=. /data
   start console

解说：这是 romfs 内嵌的启动脚本——先用 mkrd 建内存块设备 /dev/ram2（1024 扇区 × 512B），mkfatfs 格式化成 FAT，再挂到 /tmp；hostfs 把宿主当前目录（fs=. 即运行 ./nuttx 的目录）挂到 /data。读懂它即可理解 sim 的磁盘从哪来。

五、挂载与设备命令

5.1 mount / umount

nsh> mount
  /bin type binfs
  /data type hostfs
  /etc type romfs
  /proc type procfs
  /tmp type vfat

解说：不带参数列出全部挂载点与文件系统类型。实测 mount -t tmpfs /mnt2 报 nsh: mount: mount failed: 15——sim:nsh 默认配置未编译 tmpfs 文件系统（CONFIG_FS_TMPFS 未启用），需要 tmpfs 时在 menuconfig 打开该项重编。

5.2 mkrd —— 创建内存块设备

mkrd 依赖 CONFIG_BOARDCTL_MKRD=y。sim:nsh 的 defconfig 里找不到这个开关——它由 NSH 库经 select BOARDCTL_MKRD（apps/nshlib/Kconfig）强制选中，因此运行期默认可用。但要注意：不带 -m 时 minor 默认 0，而 /dev/ram0 在 sim 启动时已被架构自带的模拟块设备（sim_blockdevice.c 注册的 2048 扇区盘）占用，直接建盘会因重复注册失败：

nsh> mkrd 1
nsh: mkrd: boardctl(BOARDIOC_MKRD) failed: 1

解说：尾数 1 是 boardctl 失败时返回 ERROR 的固定值，并非真实 errno。正确做法是 -m 指定空闲 minor，末尾参数是扇区数，实测完整链路：

nsh> mkrd -m 5 64
nsh> mkfatfs /dev/ram5
nsh> mkdir /mnt
nsh> mount -t vfat /dev/ram5 /mnt
nsh> echo ramdisk-ok > /mnt/a.txt
nsh> cat /mnt/a.txt
ramdisk-ok

新盘与 /tmp 一样位于内存，重启后消失；需要持久交换文件请用 /data（hostfs）。

5.3 ls /dev —— 设备清单

nsh> ls /dev
/dev:
 console
 gpio0
 gpio1
 gpio2
 gpio3
 loop0
 null
 oneshot
 ram0
 ram1
 ram2
 rtc0
 zero

解说：console 是控制台字符设备；ram0-ram2 为内存块设备（ram2 即 /tmp）；oneshot 是单发定时器；gpio0-3 与 rtc0 供应用通过标准字符设备接口访问。

六、其他实用命令

6.1 printf / expr / cmp / readlink / time 实测

nsh> printf "num=%d str=%s\n" 42 nuttx
num=%d str=%s
42 nuttx
nsh> expr 64 / 8
8
nsh> time uname
     0.0000 sec

解说：NSH 的 printf 对格式串解析有限（实测 %d/%s 未按 C 语义展开，输出为格式串原样加参数拼接），字符串拼接场景建议用 echo；expr 支持四则运算与比较；time 可测命令耗时。

6.2 内置应用 hello

nsh> hello
Hello, World!!

解说：hello 是 apps 示例程序编译进镜像的内置应用，常用于确认新应用的注册方式（通过 apps/ 下的 Kconfig 与 Make.defs 挂入）。

七、注意事项

命令集由配置决定：ifconfig、ping 等网络命令要在 menuconfig 开启 CONFIG_NET 及 NSH 网络功能后才出现，本文 sim:nsh 默认无网络（实测提示 command not found）。
/etc 只读：romfs 挂载，改启动脚本需改 boards/sim/sim/sim/src/etc/init.d/init.rc 源文件后重编。
管道喂命令要加 exit：printf "ls\nexit\n" | ./nuttx，否则 NSH 收到 EOF 后行为依配置而定。
Ctrl-C 退出整个 sim：sim 将宿主信号转给 NSH，交互会话用 quit 或 exit 结束更干净。
/data 是宿主直通：在 /data 下创建的文件真实落在宿主运行目录，方便与宿主交换文件，也注意别误删。

八、常见问题（FAQ）

Q1：哪些命令一定可用，哪些依赖配置？ A：help 列出的内建命令随 sim:nsh 默认全开；网络类（ifconfig/ping）等依赖 CONFIG_* 开关，未开时输入命令直接报 not found；功能级依赖未满足时报具体错误（如 /dev/ram0 被占用时 mkrd 报 boardctl(BOARDIOC_MKRD) failed: 1，见 5.2 节）。

Q2：mount -t tmpfs 报 mount failed: 15？ A：该配置没编译 tmpfs 文件系统（实测挂载表里只有 binfs/hostfs/romfs/procfs/vfat）。用 make menuconfig 启用 File Systems 下的 tmpfs 后重编即可挂载。

Q3：为什么 /tmp 已经是 vfat？我没有挂载过。 A：/etc/init.d/init.rc 在启动阶段自动 mkrd + mkfatfs + mount 建好了 /tmp（见 4.5 节脚本原文），这就是默认 985 块内存盘的来源；改大小改脚本里的 mkrd 参数。

Q4：ps 里的 hpwork 是什么？ A：NuttX 的工作队列（work queue）线程，用于把下半部处理从任务上下文挪到队列；sim 配置下还有 sim_loop_wq（模拟器主循环队列）。业务代码可向工作队列投递 work 而不必自建线程。

Q5：/data 下写的文件去哪了？ A：直接落在宿主上运行 ./nuttx 的当前目录（hostfs fs=. 挂载）。测试产物可在这里与宿主交换；同理，宿主侧删除文件 NuttX 内立即可见。

Q6：echo 写文件支持追加吗？ A：NSH echo 支持 > 覆盖写；追加（>>）在部分版本支持，实测 13.1.0 sim:nsh 下以覆盖语义处理，需要追加时用 cat 多文件或应用内 O_APPEND 实现。

Q7：free 显示 64MB 是分配给 sim 的固定值吗？ A：是宿主堆的一部分映射，数值随配置变化；真机目标上 free 反映真实 RAM。排查泄漏时看 used 的增长趋势与 maxused 上限。

Q8：printf 的 %d 怎么不生效？ A：NSH printf 实现为受限版本（实测格式串未按 C 语义展开）。需要格式化输出用 echo 拼接，或在应用内用 printf/vsnprintf 后输出。

Q9：如何查看某文件占多大？ A：ls -l 显示字节大小；hexdump 查看文件内容十六进制（实测对持久目录 /data 下的文件正常输出）；du 统计目录占用（遍历大目录较慢，个别悬空链接会报 stat failed: 2，但不影响汇总）。注意 xd 不是文件工具，它是内存转储命令（用法 xd <hex-address> <byte-count>），传入文件路径会报 missing required argument(s)。

Q10：NSH 脚本怎么写？ A：把命令逐行写入文件（如 /etc/init.d/init.rc 的写法），用 source 执行；on init 段落是系统启动脚本专用格式。调试脚本时先在交互会话逐条验证再落文件。

九、参考链接

NSH 官方手册：https://nuttx.apache.org/docs/latest/components/nsh/index.html
NuttX 命令参考（NSH builtins）：https://nuttx.apache.org/docs/latest/components/nsh/commands.html
NuttX 13.1.0 发行页：https://dlcdn.apache.org/nuttx/13.1.0/
apps 仓库（nshlib 源码）：https://github.com/apache/nuttx-apps