将 RT-Thread MSH 移植到 Linux: 嵌入式调试 Shell 的多后端设计

RT-Thread 的 MSH (Micro Shell) 是嵌入式领域最成功的命令行交互组件之一。本文剖析 MSH 的核心设计理念，讨论在嵌入式 Linux 上实现同等功能的三种方案 (Embedded CLI 移植、newosp shell、自研 embsh)，并重点介绍 embsh 如何在一个纯头文件库中融合多后端 I/O、telnet 协议、认证、历史导航和 Tab 补全。

1. RT-Thread MSH 的设计精髓

RT-Thread MSH 具备以下核心设计:

• MSH_CMD_EXPORT 宏注册: 一行宏将函数注册为 Shell 命令，零侵入
• argc/argv 标准签名 : int cmd(int argc, char** argv)，与 POSIX 一致
• 多传输后端: 串口、Telnet、USB CDC 等多种输入源
• 自动 help: 内置命令列表，开发者无需手动维护
• Tab 补全 + 历史记录: 交互体验接近 Linux bash

这些设计使得 MSH 成为嵌入式 shell 的标杆。在嵌入式 Linux 平台上，我们需要同等的调试能力。

2. 方案对比: 三种实现路径

2.1 方案 A: Embedded CLI 移植

Embedded CLI 是一个纯 C 实现的轻量级命令行框架:

• 零 RTOS 依赖，适合裸机和 Linux
• 支持命令注册、参数解析、历史记录、Tab 补全
• 输入源无关: 任意字节流 (UART、TCP、USB CDC)

局限性:

维度	Embedded CLI	RT-Thread MSH
语言	纯 C	纯 C
认证	不支持	不支持
Telnet IAC	不支持	内置
命令 context	有 (void*)	无
多 session	需自行实现	需自行实现

Embedded CLI 适合单后端场景，但缺少 telnet 协议支持和认证机制，在需要远程调试的嵌入式 Linux 场景下不够完整。

2.2 方案 B: newosp 内置 shell

newosp 框架的 shell.hpp 提供了三后端 Shell:

// TCP telnet (最多 N 并发 session)
osp::DebugShell shell(cfg);
shell.Start();

// stdin/stdout 控制台
osp::ConsoleShell console(cfg);
console.Start();

// UART 串口
osp::UartShell uart(cfg);
uart.Start();

优点: 多后端、Tab 补全、线程安全注册。 局限: 与 newosp 耦合 (依赖 platform.hpp + vocabulary.hpp)，无认证，无方向键历史，命令签名无 context 指针。

2.3 方案 C: embsh -- 独立的嵌入式 Shell 库 (推荐)

embsh 融合了 newosp shell (多后端) 和 telsh (IAC + 认证 + 历史) 的优点:

特性	Embedded CLI	newosp shell	embsh
多后端 I/O	需自行实现	TCP + Console + UART	TCP + Console + UART
Telnet IAC	不支持	部分	完整 FSM
认证	不支持	不支持	用户名/密码
方向键历史	有	无	16 条环形缓冲
Tab 补全	有	有	有 (最长公共前缀)
Context 指针	有	无	有
MSH 兼容宏	需适配	不兼容	MSH_CMD_EXPORT
外部依赖	无	osp 框架	无 (自包含)

3. embsh 核心架构

3.1 命令签名: 带 context 的函数指针

// embsh 命令签名 (兼容 RT-Thread MSH + 扩展 context)
using CmdFn = int (*)(int argc, char* argv[], void* ctx);

context 指针的价值: 无状态函数指针可以绑定有状态对象，而不需要闭包或全局变量。

// 无状态命令 (等价于 MSH 签名)
static int cmd_help(int argc, char* argv[], void* /*ctx*/) {
    // ...
    return 0;
}

// 有状态命令 (通过 context 绑定对象)
struct LedController {
    int pin;
    void toggle() { /* ... */ }
};

static int cmd_led(int argc, char* argv[], void* ctx) {
    auto* led = static_cast<LedController*>(ctx);
    led->toggle();
    return 0;
}

// 注册时绑定 context
LedController led{13};
embsh::CommandRegistry::Instance().Register("led", cmd_led, &led, "Toggle LED");

3.2 MSH_CMD_EXPORT 兼容宏

embsh 提供与 RT-Thread MSH 源码级兼容的注册宏:

// embsh 上使用
#include "embsh/command_registry.hpp"

static int reboot(int argc, char* argv[], void* ctx) {
    // ...
    return 0;
}
MSH_CMD_EXPORT(reboot, "Reboot the system");

未来迁移到 RT-Thread 时，只需替换头文件:

#ifdef __LINUX__
  #include "embsh/command_registry.hpp"
#else
  #include <finsh.h>   // RT-Thread 原生 MSH
#endif

3.3 多后端 I/O 抽象

embsh 通过函数指针抽象 I/O，三个后端共享同一命令注册表:

                    +--> TelnetServer (TCP, 8 sessions, IAC + auth)
CommandRegistry <---+--> ConsoleShell (stdin/stdout, termios raw)
                    +--> UartShell    (serial, configurable baud)

函数指针 (非虚函数) 实现零开销后端切换:

using WriteFn = ssize_t (*)(int fd, const void* buf, size_t len);
using ReadFn  = ssize_t (*)(int fd, void* buf, size_t len);

// TCP: send/recv with MSG_NOSIGNAL
// POSIX: write/read for console/UART

3.4 行编辑与历史导航

embsh 的 line_editor 模块提供:

• 256B 行缓冲区: 固定大小，零堆分配
• 方向键导航 : ESC 序列 FSM 解析 \x1b[A/B/C/D
• 16 条历史记录: 环形缓冲，跳过重复
• Tab 补全: 单匹配自动填充 + 空格，多匹配显示列表 + 最长公共前缀
• IAC 过滤: telnet 协议字节透明处理

输入处理流程:

字节输入 -> IAC 过滤 (telnet) -> ESC FSM -> 字符分类
  |
  +-- 普通字符: line_buf[pos++] + 回显
  +-- Tab: AutoComplete
  +-- Up/Down: 历史导航
  +-- Enter: ShellSplit + 命令执行
  +-- Backspace: 删除 + 回退
  +-- Ctrl+C: 取消当前行
  +-- Ctrl+D: EOF / 退出

4. 串口集成: 嵌入式 Linux 上的 UART Shell

4.1 串口初始化

embsh 的 UartShell 封装了完整的 termios 配置:

embsh::UartShell::Config cfg;
cfg.device = "/dev/ttyPS0";    // Zynq PS UART
cfg.baudrate = 115200;
cfg.prompt = "sensor> ";

embsh::UartShell uart(cfg);
uart.Start();

内部实现: 打开设备 -> cfmakeraw -> 设置波特率/8N1/无流控 -> VMIN=1 阻塞读取。

4.2 在 RT-Thread 上的等价用法

// RT-Thread: MSH 自动绑定到 console 设备
MSH_CMD_EXPORT(sensor_read, "Read sensor data");

// 嵌入式 Linux (embsh): 手动指定串口设备
MSH_CMD_EXPORT(sensor_read, "Read sensor data");
// + UartShell 配置

业务命令代码完全一致，仅 Shell 后端配置不同。

5. TCP Telnet 远程调试

5.1 认证与安全

embsh 的 TelnetServer 支持可选的用户名/密码认证:

embsh::ServerConfig cfg;
cfg.port = 2323;
cfg.username = "admin";
cfg.password = "secret";
cfg.banner = "\r\n=== Sensor Debug Shell ===\r\n";

embsh::TelnetServer server(cfg);
server.Start();

认证流程:

1. 连接后发送 banner + "Username:" 提示
2. 密码输入星号掩码显示
3. 最多 3 次尝试，失败断开连接
4. 认证通过后进入正常命令模式

5.2 IAC 协议处理

telnet 客户端会发送 IAC (Interpret As Command) 协议字节。embsh 内置 IAC FSM:

Normal -> 收到 0xFF -> IAC 状态
  -> WILL/WONT/DO/DONT (0xFB-0xFE) -> Negotiate 状态 -> 消费 option 字节 -> Normal
  -> SB (0xFA) -> Sub 状态 -> 消费直到 IAC SE -> Normal
  -> 0xFF (IAC IAC) -> 传递 literal 0xFF -> Normal

6. 多后端同时运行

embsh 支持 TCP 和 Console 同时运行，共享同一命令注册表:

#include "embsh/console_shell.hpp"
#include "embsh/telnet_server.hpp"

// TCP 远程调试
embsh::TelnetServer tcp_server(tcp_cfg);
tcp_server.Start();

// 本地控制台 (main 线程阻塞)
embsh::ConsoleShell console(con_cfg);
console.Run();

运维人员可通过 telnet 远程登录，开发人员同时在本地控制台调试。

7. 编译期配置

宏	默认值	说明
EMBSH_MAX_COMMANDS	64	最大命令数
EMBSH_MAX_SESSIONS	8	TCP 最大并发 session
EMBSH_LINE_BUF_SIZE	256	行缓冲区大小
EMBSH_HISTORY_SIZE	16	历史记录条数
EMBSH_MAX_ARGS	32	单条命令最大参数数
EMBSH_DEFAULT_PORT	2323	TCP 默认端口

8. 资源预算

资源	数值	说明
Session 内存	~4.5KB	256B line_buf + 16x256B history + 控制字段
8 Session 总计	~36KB	TCP 最大并发
命令表	~2KB	64 x 32B (name+desc+fn+ctx)
编译期可控	全部	通过宏调整，适配不同资源约束

9. 总结

维度	Embedded CLI	RT-Thread MSH	embsh
平台	裸机 + Linux	RT-Thread	嵌入式 Linux
语言	C	C	C++17 (header-only)
后端	单后端	多后端	TCP + Console + UART
认证	无	无	用户名/密码
历史	有	有	16 条 + 方向键
Tab 补全	有	有	有
Context 指针	有	无	有
MSH 兼容	需适配	原生	MSH_CMD_EXPORT 宏
外部依赖	无	RT-Thread	无

embsh 已开源: github.com/DeguiLiu/em...，52 个 Catch2 单元测试全部通过，适用于工业传感器、机器人、边缘计算等嵌入式 Linux 调试场景。

---