shell_usmart.c

源文件路径：midware/debug/shell_usmart.c 所属模块：midware/debug（设备中间件 - 板级调试/产线测试） 代码行数：65

1. 文件职责

本文件是开源调试 shell 组件 USMART 在 EMS 工程里的配置与任务外壳。USMART 的通用实现（命令接收 usmart_cmd_rec、函数查表执行 usmart_exe、扫描 usmart_scan、字符串工具）放在 common/usmart/ 下，属于可复用的公共库；本文件的职责只有两件事：①提供 USMART 要求的两个"配置表"——函数注册表 usmart_nametab[] 和设备结构体实体 usmart_dev；②提供一个 uCOS-II 任务 task_usmart，周期性调用 usmart_scan() 去解析从 USART0 进来的命令行。

它处在最外层的"人工调试入口"位置：开发人员通过调试串口（USART0）敲入函数名和参数，USMART 解析后直接调用固件里的任意已注册函数，免去重新编译下载。它不参与任何业务数据流，是纯粹的在线调试通道。整个文件体被 #if DEBUG_SUMART（shell_usmart.c:6）包住，而 DEBUG_SUMART 在 shell_usmart.h:13 定义为 0，因此在当前固件里本文件编译后为空——任务不会被创建（user/main.c:50 与 user/main.c:321-331 的 #if DEBUG_SUMART 同样为假），调试 shell 处于关闭状态。

2. 关键数据结构与宏

usmart_nametab[] 注册内容（shell_usmart.c:14-23）

usmart_dev 的初始化值（shell_usmart.c:34-45）

3. 函数清单

本文件只有这一个函数定义。usmart_nametab[] 与 usmart_dev 是数据定义，不是函数；usmart_init / usmart_cmd_rec / usmart_exe / usmart_scan / usmart_test 都定义在 common/usmart/usmart.c，本文件只取它们的地址填进配置表。

4. 核心逻辑解析

4.1 编译期总开关

shell_usmart.c:6 的 #if DEBUG_SUMART 一直作用到文件末尾的 #endif（shell_usmart.c:65），把注册表、设备实体、任务三部分全部包住。DEBUG_SUMART 的唯一定义在 shell_usmart.h:13（值 0）。因此：

• 本文件编译后不产生任何符号；
• common/usmart/usmart.c:27 与 common/usmart/usmart_str.c:24 的同名开关也为假，整个 USMART 库不产生代码；
• user/main.c:50 的任务栈 TASK_USMART_STK、user/main.c:321-331 的 OSTaskCreateExt(task_usmart, ...) 与 OSTaskNameSet(..., "task_usmart_parse", ...) 也一并被剔除。

对使用者的意义：工程里保存着完整的在线调试 shell，但发行固件里它是关闭的。要启用需要把 shell_usmart.h:13 改为非 0 并重新编译。

4.2 命令解析与执行流程

本文件不实现解析，但它是解析链路的入口。当 task_usmart 调用 usmart_scan() 时（实现在 common/usmart/usmart.c:412），完整流程为：

usmart_scan()
 ├─ usart0_is_recv_async_data() ?             ← 查 USART0 环形缓冲是否有新数据
 │   否 → return（本次无输入）
 │   是 ↓
 ├─ len = usart0_get_data_len();  len < 2 ? return;   ← 太短的丢弃
 ├─ for (i < len) data[i] = usart0_read_data_async();  ← 取走本次全部字节到 data[50]
 ├─ sta = usmart_dev.cmd_rec(data);            ← 解析：查表匹配函数名与参数
 └─ sta == 0 ? usmart_dev.exe()                ← 执行已注册函数
              : usmart_sys_cmd_exe(data)       ← 系统命令 help/list/id/hex/dec/runtime

关键点：

• 输入源固定为 USART0（usmart.c:419/421/431），即 debug.c 里 fputc() 重定向的同一个口，因此"敲命令"和"看打印"共用一根串口。
• 匹配依据是 usmart_nametab[] 的 name 字段（形如 "u8 get_e_linker_sn(u8 *pdata)"）。USMART 用字符串比较从 左括号之后 截出参数表，据此决定要读几个参数、按什么类型解析，所以注册表里的原型字符串必须与真实函数签名严格一致，否则参数个数和类型会解析错误。
• data[50] 是局部缓冲（usmart.c:415），usmart_scan() 对 len 没有上限裁剪就直接 for (i < len) data[i] = ...，一次超过 50 字节的输入会栈溢出。正常人工输入不会触发，但该缺陷客观存在。
• usmart_dev.sptype = 1（16 进制显示）在 usmart_init() 中被再次赋值（usmart.c:111）——common/usmart/usmart.c:110 显示 "十进制显示进制" 的中文注释与实际赋值 1（十六进制）语义相反，注释是错的。

4.3 双重扫描路径与节拍

这是本文件最需要注意的时序特征。USMART_ENTIMX_SCAN 被设为 1（common/usmart/usmart.h:22），同时工程又建立了一个专门的扫描任务，于是同一个 usmart_scan() 有两条驱动路径：

其中 A 路径的中断在 hardware/timer/timer3.c:30-48 的 timer3_init() 中通过 timer_interrupt_enable(TIMER3, TIMER_INT_UP) 使能，因此是真实生效的。两条路径共享同一份 usmart_dev 全局状态和同一个 USART0 环形缓冲，而没有任何互斥保护：

• ISR 里的 usmart_dev.scan() 会调用 usmart_dev.exe()，进而直接执行用户敲入的函数（例如 get_e_linker_sn）。在中断上下文里执行任意业务函数是明确的风险点：这些函数可能阻塞、可能访问被任务持有的共享数据、可能调用 printf（USART0 阻塞写）。
• 若任务侧正好在 usmart_scan() 中途被 TIMER3 中断打断，ISR 再次进入 usmart_scan()，会重复消费环形缓冲、覆盖 usmart_dev.parm[]/plentbl[]/pnum/id 等中间状态，导致本次命令被解析成错误的内容或被执行两次。

OSTaskCreateExt 侧的参数（user/main.c:321-331）：优先级 TASK_USMART_PRIO = 22（UCOSII/uCOS-CONFIG/app_cfg.h:73，全工程最低优先级之一），栈 TASK_USMART_STK_SIZE = 512（app_cfg.h:100），选项 OS_TASK_OPT_STK_CHK | OS_TASK_OPT_STK_CLR | OS_TASK_OPT_SAVE_FP，任务名 "task_usmart_parse"。

4.4 全局变量的读写

runtimeflag/runtime 因为没有出现在 shell_usmart.c:34-45 的初始化列表里，由 C 语言的"部分初始化自动补零"规则置 0，功能上正确。

4.5 usmart_init(SystemCoreClock) 的参数类型

task_usmart 传入的是 CMSIS 的全局变量 SystemCoreClock（u32，GD32F407 上通常为 200000000），而 usmart_init 的形参是 u8 sysclk（common/usmart/usmart.h:69，实现 common/usmart/usmart.c:109），实参被静默截断为低 8 位。所幸 usmart_init 内部根本没用 sysclk，而是自己算分频：

void usmart_init(u8 sysclk)                                             // usmart.c:109
{
    timer3_init(999, (u32)rcu_clock_freq_get(CK_APB1)*4/10000-1);       // usmart.c:110
    usmart_dev.sptype = 1;                                              // usmart.c:111
}

timer3_init(u16 arr, u16 psc)（hardware/timer/timer3.c:30）的两个形参也都是 u16：arr = 999，psc = APB1频率*4/10000-1。按注释（usmart.c:110）意图是 10 kHz 计数、100 ms 溢出一次，说明这里的乘除系数是与 RCU_TIMER_PSC_MUL4（timer3.c:35）配合的定点换算。但 psc 是 u16，最大 65535：若 APB1 频率较高使 freq*4/10000-1 > 65535，会被静默截断，定时周期随之取错；这是隐藏在类型里的定时基准风险。

5. 对外接口

本文件导出

注：common/usmart/usmart.h:65-66 的注释写的是"在 usmart_config.c 中定义"，那是原版 STM32 例程的文件名；本工程把这两个实体的定义搬到了 shell_usmart.c 里。

本文件调用的外部函数/变量

6. 依赖关系

依赖

usmart.h、shell_usmart.h、main.h、e_linker_wifi.h（shell_usmart.c:1-4，该文件为 GBK 编码，已转码阅读）。

被依赖

• user/main.c：#if DEBUG_SUMART 下创建 task_usmart 任务（user/main.c:321-331）
• common/usmart/usmart.c、common/usmart/usmart_str.c：通过 extern 引用 usmart_nametab[] 与 usmart_dev
• midware/ethernt/wireless/wifi/e_linker_wifi.c：提供注册表中被调用的两个函数

7. 备注与风险点

1. 当前固件中本文件为"空文件"：DEBUG_SUMART 为 0，注册表、usmart_dev、task_usmart 全部被条件编译剔除，任务不创建。修改 shell_usmart.h:13 时务必同步确认 common/usmart/usmart.c:27、common/usmart/usmart_str.c:24、user/main.c:50/321 的开关一致性，否则会出现"任务创建了但库没编译"的链接错误。
2. 双重扫描路径 + 无互斥：USMART_ENTIMX_SCAN = 1 使 TIMER3_IRQHandler（common/usmart/usmart.c:35-52）和 task_usmart（shell_usmart.c:59-63）都以约 100 ms 的周期调用同一个 usmart_scan()，共享 usmart_dev 全局状态与 USART0 环形缓冲，无信号量保护。任务侧扫描被定时器中断打断时，会重复消费串口数据、覆盖 parm[]/plentbl[]/pnum/id，造成命令被错误解析或执行两次。
3. 在中断上下文里执行任意业务函数：ISR 经 usmart_dev.exe() 直接调用注册函数（当前含 get_e_linker_sn），这些函数可能阻塞、访问被任务持有的资源，或经 printf 阻塞在 USART0 上，属于明确的设计风险。若启用本模块，建议把 USMART_ENTIMX_SCAN 改成 0 只保留任务路径。
4. usmart_scan() 的局部缓冲 data[50] 无长度上限检查（common/usmart/usmart.c:415-431）：一次输入超过 50 字节即栈溢出，而 task_usmart 的栈只有 512 项（app_cfg.h:100），溢出后果不可预测。
5. usmart_init(SystemCoreClock) 实参被 u8 截断（shell_usmart.c:58）：SystemCoreClock 是 u32，形参是 u8。虽然函数体未使用该参数（usmart.c:109-113），但接口类型不匹配属于隐患，编译器也可能给出精度丢失告警。
6. timer3_init() 的 psc 形参为 u16 而实参算式可超范围（common/usmart/usmart.c:110 → hardware/timer/timer3.c:30）：rcu_clock_freq_get(CK_APB1)*4/10000-1 一旦超过 65535 会被静默截断，导致扫描中断周期偏离 100 ms。
7. sptype 的中文注释与实际语义相反：common/usmart/usmart.c:110 附近及 usmart.h:56 的"0,10进制;1,16进制"描述没问题，但 usmart_init 内那一行注释写成"十进制显示进制"而赋的值是 1（16 进制），容易被后续维护者改错。
8. 注册表原型字符串必须与真实签名一致（shell_usmart.c:20-22）：get_e_linker_sn 的字符串为 "u8 get_e_linker_sn(u8 *pdata)"，与 e_linker_wifi.h:49 的声明吻合；但 usmart_test 为 "void usmart_test(void)"，需注意这类字符串一旦与实际签名不符，参数解析会静默出错而不是报错。
9. parm[PARM_LEN] 只写了单个 0 初始化（shell_usmart.c:44-45，注释写着"需要 MAX_PARM 个 0 初始化"）：C 语言部分初始化会自动补零，功能正确，但注释与写法不一致，说明是从上游例程整段复制而来。
10. 原版注释指向已不存在的文件名：common/usmart/usmart.h:65-66 写着"在 usmart_config.c 中定义"，实际定义在本文件 shell_usmart.c，容易误导查找。
11. runtimeflag / runtime 从未被赋值，函数执行时间统计功能实际不可用（需 runtimeflag = 1 且配合 USMART_ENTIMX_SCAN = 1）。