feat: save stable CH390 bridge baseline

2026-04-04 02:48:21 +08:00
parent 6f4ba247a4
commit d5b2506269
18 changed files with 2146 additions and 1621 deletions
@@ -1,171 +1,374 @@
-# TCP2UART 工程调试指南
+# TCP2UART 调试指导

 ## 1. 适用范围

-本指南面向当前 `TCP2UART` 工程，目标是指导以下调试场景：
+本指导面向当前 `TCP2UART` 工程，覆盖以下四类调试场景：

 1. `STM32F103R8T6 + CH390D` 的基础 bring-up
-2. CH390D 的寄存器读写、链路检测、中断与收发调试
-3. `lwIP RAW API + NO_SYS=1` 路线下的网络链路问题定位
-4. UART 透传与 TCP 双链路联调
+2. `SEGGER RTT`、异常陷阱与主循环运行状态确认
+3. `USART1` 配置口、`USART2/USART3` 数据口与 `MUX / NET / LINK[idx]` 协议联调
+4. `TCP Server / TCP Client / UART` 三层数据通路联调与问题隔离

-本指南默认基线：
+本指导默认基线如下：

-1. 当前工程已切换为裸机主循环架构
-2. CH390 运行时访问统一由 `ch390_runtime` 持有
-3. 调试输出通过 `SEGGER RTT`
-4. 当前代码已经通过 `MDK-ARM` 构建，且构建结果为 `0 error / 0 warning`
+1. 当前工程采用裸机主循环架构，未使用 FreeRTOS 参与主业务调度
+2. `CH390` 运行时访问统一由 `ch390_runtime` 持有
+3. 调试输出统一使用 `SEGGER RTT`
+4. 当前应用层协议模型已经收敛到 `MUX / NET / LINK[idx]`
+5. 当前代码应以 `MDK-ARM` 工程构建结果为准，而不是 `CMake + MSVC` 结果

-## 2. 当前工程调试边界
+---

-截至当前版本，工程状态应按以下层级理解：
+## 2. 当前工程边界与真实状态

-1. MCU 启动、系统时钟、RTT、TIM4 心跳与主循环均可正常工作
-2. CH390D 已恢复基础寄存器读写，不再处于“全 `0xFF` / 全 `0x0000`”阶段
-3. 实机已读到可信芯片与 PHY 标识：`VID=0x1C00`、`PID=0x9151`、`REV=0x2B`、`PHYID1=0x7371`、`PHYID2=0x9011`
-4. 实机已观察到主机 Realtek USB GbE 网卡为 `Connected 100 Mbps`，且设备侧 `lwIP netif` 标志包含 `LINK_UP`
-5. 当前调试重点不再是“SPI 是否完全不通”，而是：
-   - 默认配置是否完整生效
-   - MAC 写入与回读是否一致
-   - PHY 协商、`INT/LINK/RX/TX` 是否进入正常工作态
-   - 网络链路与 UART 透传是否稳定协同
+在进入现场调试前，先统一以下工程边界，避免沿用过时结论：

-因此，后续调试应避免继续沿用“CH390 完全无响应”的旧结论，而应转入功能链路验证。
+1. 当前项目的主要软件路径已经切换为：
+   - `NET`：网络基础参数
+   - `LINK[idx]`：链路配置记录
+   - `MUX`：数据口承载模式
+2. 对外 AT 配置面应只围绕以下命令展开：
+   - `AT`
+   - `AT+?`
+   - `AT+QUERY`
+   - `AT+MUX`
+   - `AT+NET`
+   - `AT+LINK`
+   - `AT+SAVE`
+   - `AT+RESET`
+   - `AT+DEFAULT`
+3. 当前 `CH390D` 的历史“全 `0xFF` / 全 `0x0000`”结论不应再直接沿用。
+4. 已有结论表明：
+   - MCU 启动、RTT、主循环、TIM4 心跳路径可工作
+   - `CH390D` 基础寄存器读写与 `lwIP netif` 基本链路已经打通过一次
+   - 真实硬件侧曾定位到 `CH390D` 供电滤波电容虚焊问题
+5. 因此，当前调试重点不再是“CH390 是否完全不通”，而是：
+   - 启动阶段是否稳定
+   - `MUX / NET / LINK[idx]` 协议是否与代码一致
+   - UART / TCP / CH390 三层通路是否协同稳定
+   - 参数保存、复位和恢复流程是否可靠

-## 3. 代码入口与责任边界
+---

-### 3.1 启动路径
+## 3. 代码入口与调试责任边界

-当前 CH390 相关启动链路为：
+### 3.1 启动与主循环入口

-1. `main()`
-2. `App_Init()`
-3. `lwip_netif_init()`
-4. `ethernetif_init()` / `low_level_init()`
-5. `ch390_runtime_init()`
-6. `ch390_gpio_init()`
-7. `ch390_spi_init()`
-8. `ch390_hardware_reset()`
-9. `ch390_runtime_probe_identity()`
-10. `ch390_default_config()`
-11. `ch390_set_mac_address()` / `ch390_get_mac()`
-12. `ch390_interrupt_init()`
+以下代码路径是 bring-up 的第一现场：

-### 3.2 运行时责任边界
+1. `Core/Src/main.c`
+   - `main()`：总启动入口
+   - `SystemClock_Config()`：时钟初始化
+   - `App_Init()`：应用层初始化
+   - `App_Poll()`：主循环核心路径
+   - `BootDiag_ReportCh390()`：启动阶段 CH390 诊断输出
+2. `Core/Src/stm32f1xx_it.c`
+   - 故障与中断入口
+   - `USART1/2/3`、`EXTI0`、DMA 回调等联调关键入口

-当前代码约束如下：
+### 3.2 CH390 责任边界
+
+当前 CH390 调试必须遵守以下责任边界：

 1. `Drivers/CH390/CH390_Interface.c`
-   - 只负责底层 GPIO、SPI 与寄存器/内存访问
-   - 当前寄存器读写路径使用 `Mode 3 + bytewise exchange` 事务模型
+   - 只负责 GPIO / SPI / 寄存器与内存事务
 2. `Drivers/CH390/CH390.c`
-   - 只负责芯片级 helper，例如 `default_config`、PHY 访问、MAC 操作
+   - 只负责芯片级 helper，例如默认配置、PHY、MAC 读写
 3. `Drivers/CH390/ch390_runtime.c`
-   - 唯一的 CH390 运行时拥有者
-   - 负责初始化、链路查询、IRQ 消费、RX/TX 服务
+   - 唯一的运行时拥有者
+   - 负责初始化、链路检查、IRQ 消费、RX/TX 服务与诊断快照
 4. `Drivers/LwIP/src/netif/ethernetif.c`
-   - 不再直接承担复杂 CH390 运行时事务，只做 netif glue
+   - 只承担 netif glue 与轮询桥接，不应重新下沉复杂 CH390 运行时事务
 5. `Core/Src/main.c`
-   - 启动后只通过 `BootDiag_ReportCh390()` 读取 runtime 提供的启动快照
+   - 启动后只通过 runtime 对外暴露的诊断与轮询接口工作

-调试时应优先维护这个边界，不要重新把原始寄存器访问散落回 `main.c` 或 EXTI 中断中。
+调试时不要把原始 CH390 寄存器访问重新散回 `main.c`、中断或多个业务层。

-## 4. 当前硬件连接事实
+### 3.3 配置口与业务口边界

-根据 `PCB/SCH_Schematic1_2026-03-26.pdf`，CH390D 关键硬件事实如下：
+1. `USART1`
+   - 配置口
+   - 负责接收 `AT` 命令
+   - 当前接收逻辑在：
+     - `Core/Src/main.c` 的 `App_PollUart1ConfigRx()`
+     - `Core/Src/stm32f1xx_it.c` 的 `HAL_UART_RxCpltCallback()`
+     - `App/config.c` 的 `config_uart_rx_byte()` / `config_process_at_cmd()`
+2. `USART2 / USART3`
+   - 数据口
+   - 负责普通透传或 MUX 承载
+   - 当前入口在 `App/uart_trans.c`

-1. MCU 与 CH390D 的连接关系：
-   - `PA4 -> CH_CS -> U4.SCS`
-   - `PA5 -> CH_CLK -> R10(22Ω) -> U4.SCK`
-   - `PA6 <- CH_SDO <- U4.SDO/MISO`
-   - `PA7 -> CH_SDI -> U4.SDI/MOSI`
-   - `PB0 <- CH_INT <- U4.INT`
-   - `PB1 -> CH_RST -> R8(470Ω) -> U4.RSTB`
-2. CH390D 使用 `25MHz` 晶振 `X2`
-3. CH390D 存在独立相关电源域：
-   - `VDDK`
-   - `AVDD33/VDDIO`
-   - `AVDD33`
-4. CH390D 周边去耦电容包括 `C18/C20/C21/C22`
-5. 原理图上未看到独立的 `MISO` 外部上拉电阻
-6. 当前代码中的 `ch390_hardware_reset()` 采用：
-   - 复位前等待 `10ms`
-   - `RSTB` 拉低 `3ms`
-   - 释放后等待 `50ms`
+---

-调试时必须优先在 **CH390 芯片脚侧** 量测，而不是只在 MCU GPIO 侧判断。
+## 4. 当前硬件与调试工具基线

-## 5. 推荐调试顺序
+### 4.1 核心硬件对象

-### 5.1 P0：先确认基础条件
+1. MCU：`STM32F103R8T6`
+2. 以太网芯片：`CH390D`
+3. 配置串口：`USART1`
+4. 数据串口：`USART2 / USART3`
+5. 调试输出：`SEGGER RTT`

-每次进入功能调试前，先确认以下最小基线：
+### 4.2 构建与下载基线

-1. `MDK` 可成功构建，且当前日志为 `0 error / 0 warning`
-2. RTT 可输出启动日志
-3. `BootDiag_ReportCh390()` 能打印出 `VID/PID/REV/NSR/NCR/RCR/IMR/INTCR/GPR/ISR`
-4. `App_Poll()` 正常运行，LED 心跳正常
+当前建议优先使用以下工程与产物：

-### 5.2 P1：验证 CH390 初始化状态
+1. `MDK-ARM/TCP2UART.uvprojx`
+2. `MDK-ARM/TCP2UART/TCP2UART.axf`
+3. `MDK-ARM/TCP2UART/TCP2UART.hex`
+4. `MDK-ARM/TCP2UART/TCP2UART.map`
+5. `MDK-ARM/TCP2UART/TCP2UART.build_log.htm`
+6. `build_keil.log`

-优先检查以下问题：
+说明：

-1. `ETH init: probe/default/mac/getmac/irq/done` 是否完整打印
-2. `VID/PID/REV` 与 PHY ID 是否稳定、可信
-3. MAC 写入与 `ch390_get_mac()` 回读是否一致
-4. `RCR/IMR/INTCR/GPR` 是否进入预期工作态
-5. `link_up` 与 `lwIP netif` 的 `LINK_UP` 标志是否与物理网线状态一致
+1. 当前 `CMake configure` 可以完成，但 `CMake + MSVC` 不适合作为 STM32/CMSIS 的最终构建验收依据。
+2. 若需要验证“当前代码是否真实可编译”，优先看 `MDK-ARM` 构建产物与日志。

-如这一层失败，优先回到芯片侧量测：
+### 4.3 常用调试工具
+
+1. `Keil MDK-ARM`
+2. `ST-Link / J-Link`
+3. `SEGGER RTT Viewer`
+4. `PowerShell`
+5. `tools/start_tcp_debug_server.ps1`
+6. `tools/tcp_debug_server.py`
+
+---
+
+## 5. 启动阶段调试顺序
+
+建议按 P0 ~ P5 顺序推进，不要跳层。
+
+### 5.1 P0：确认最小基础条件
+
+每次现场调试前，先确认：
+
+1. `MDK-ARM` 可构建并产出新的 `axf/hex/map`
+2. 板卡可正常下载与复位
+3. RTT 可连接并看到启动输出
+4. LED 心跳可工作
+5. `App_Poll()` 已经进入稳定轮询
+
+这一层若失败，不要进入网络或协议调试。
+
+### 5.2 P1：确认启动日志与 trap 状态
+
+上电或复位后，优先看 RTT 输出中是否出现：
+
+1. `TCP2UART boot`
+2. 若 HSE 启动失败，则会出现：
+   - `WARN: HSE start failed, fallback to HSI PLL`
+3. `BootDiag_ReportCh390()` 输出的 CH390 诊断与网络配置快照
+
+若发生异常，优先观察是否打印：
+
+1. `TRAP: Error_Handler`
+2. `TRAP: HardFault_Handler`
+3. `TRAP: MemManage_Handler`
+4. `TRAP: BusFault_Handler`
+5. `TRAP: UsageFault_Handler`
+
+当前 trap 统一收敛到：
+
+1. `Core/Src/main.c` 的 `Debug_TrapWithRttHint()`
+2. 它会打印 RTT、执行 `__BKPT(0)` 并停住
+
+因此，若 RTT 中出现 `TRAP:`，应立即接调试器看断点现场，而不是继续盲猜高层逻辑。
+
+### 5.3 P2：确认 CH390 初始化链路
+
+启动阶段应重点关注 `Drivers/CH390/ch390_runtime.c` 中初始化阶段日志，理想情况下应能依次看到：
+
+1. `ETH init: gpio`
+2. `ETH init: spi`
+3. `ETH init: reset`
+4. `ETH init: probe`
+5. `ETH init: default`
+6. `ETH init: mac`
+7. `ETH init: getmac`
+8. `ETH init: irq`
+9. `ETH init: done`
+
+此阶段重点判定：
+
+1. `VID / PID / REV` 是否可信
+2. PHY 寄存器是否稳定可读
+3. MAC 写入与回读是否一致
+4. `link_up` 是否与真实网线状态一致
+
+若这一层失败，优先做硬件侧量测，而不是先改业务层：

 1. `RSTB`
 2. `CS`
 3. `SCK`
 4. `MOSI`
 5. `MISO`
-6. `VDDK / AVDD33/VDDIO / AVDD33`
+6. `INT`
+7. `VDDK`
+8. `AVDD33 / VDDIO / AVDD33`
+9. `XI / XO`

-### 5.3 P2：验证 IRQ 与链路检测
+---

-在基础寄存器读写可信后，重点验证：
+## 6. USART1 配置口调试

-1. `PB0/EXTI0` 是否能接收到 CH390 的 `INT`
-2. `ISR_LNKCHG` 发生时，`ch390_runtime_poll()` 是否正确更新链路状态，不再依赖阻塞式 `HAL_Delay(65)`
-3. `ethernetif_check_link()` 与 `ch390_runtime_check_link()` 的结果是否一致
-4. 必须区分“启动快照中的 `g_diag.link_up`”与“主循环中实时更新后的 `netif->flags & NETIF_FLAG_LINK_UP`”
+### 6.1 当前命令面

-### 5.4 P3：验证 RX/TX 数据通路
+根据当前代码与手册，配置口应围绕以下命令验证：

-在 `link_up` 可信后，再继续验证数据通路：
+1. `AT`
+2. `AT+?`
+3. `AT+QUERY`
+4. `AT+MUX=...`
+5. `AT+MUX?`
+6. `AT+NET=...`
+7. `AT+NET?`
+8. `AT+LINK=...`
+9. `AT+LINK?`
+10. `AT+SAVE`
+11. `AT+RESET`
+12. `AT+DEFAULT`

-1. 先确保主机网卡与设备处于同一子网；当前联调基线曾使用主机 `192.168.31.1` 与设备 `192.168.31.x`
-2. `ch390_runtime_input()` 是否能稳定读取 `RX SRAM`
-3. `rx_status / rx_len` 是否合理
-4. `ch390_runtime_output()` 是否能正确等待 `TCR_TXREQ` 清零并发送帧
-5. 网络端与 UART2/UART3 透传是否联通
+### 6.2 现场关键规则

-### 5.4.1 最小 TCP 调试工具
+根据已有联调记录，配置口最关键的 bench 规则是：

-当需要验证 `TCP server(8080)` 到 `TCP client(8081)` 的原始桥接行为时，优先使用仓库内置的最小工具，而不是直接依赖 VOFA 这类带协议/显示假设的上位机工具。
+1. 当前现场验证时，配置命令必须保证以换行完成帧。
+2. 若主机侧发送方式不对，现象会很像“配置口完全无响应”。
+3. 因此，配置口不响应时，第一优先级不是改 parser，而是先验证主机端发送格式与接线。

-推荐工具如下：
+### 6.3 最小验证步骤
+
+建议按以下顺序验证：
+
+1. 连接 `USART1`
+2. 先发 `AT`
+3. 再发 `AT+QUERY`
+4. 再发 `AT+NET?`
+5. 再发 `AT+LINK?`
+6. 修改一个最小参数，例如：
+   - `AT+MUX=1`
+7. 执行：
+   - `AT+SAVE`
+   - `AT+RESET`
+8. 复位后再次查询，确认配置是否保留
+
+### 6.4 持久化失败时怎么查
+
+优先检查以下路径：
+
+1. `App/config.c`
+   - `config_save()`
+   - `config_load()`
+   - `config_set_defaults()`
+2. `App/flash_param.c`
+   - Flash 解锁
+   - 页擦除
+   - 半字编程
+   - 写后校验
+3. 参数页地址：
+   - `0x0800FC00`
+
+不要在还没证明 `AT+SAVE` 已真正被接受之前，就直接把 `Flash 全 FFFFFFFF` 归因到 Flash 驱动错误。
+
+---
+
+## 7. MUX / NET / LINK[idx] 联调指导
+
+### 7.1 协议总则
+
+当前协议必须按以下模型理解：
+
+1. `MUX`：全局数据承载模式开关
+2. `NET`：IP / Mask / GW / MAC
+3. `LINK[idx]`：链路配置项
+
+固定链路索引映射为：
+
+1. `LINK[0] = S1`
+2. `LINK[1] = S2`
+3. `LINK[2] = C1`
+4. `LINK[3] = C2`
+
+固定端点编码为：
+
+1. `C1 = 0x01`
+2. `C2 = 0x02`
+3. `UART2 = 0x04`
+4. `UART3 = 0x08`
+5. `S1 = 0x10`
+6. `S2 = 0x20`
+
+### 7.2 MUX 数据口规则
+
+当 `MUX=1` 时，数据口应使用 MUX 帧。
+
+重点规则：
+
+1. `DSTMASK=0x00` 表示系统控制帧
+2. 控制帧中的 AT 文本必须严格按手册要求结束
+3. 普通数据帧走业务转发路径，不应进入配置解析器
+
+### 7.3 调试时重点检查什么
+
+若怀疑 `MUX` 模式不工作，优先检查：
+
+1. `App/uart_trans.c`
+   - `uart_mux_try_extract_frame()`
+   - `uart_mux_encode_frame()`
+2. `Core/Src/main.c`
+   - `App_RouteMuxUartTraffic()`
+   - `App_RouteRawUartTraffic()`
+   - `App_RouteTcpTraffic()`
+3. `App/config.c`
+   - `config_build_response_frame()`
+   - `config_process_at_cmd()`
+
+推荐最小 MUX 联调顺序：
+
+1. 先在 `MUX=0` 下跑通原始透传
+2. 再切换 `MUX=1`
+3. 先发一个控制帧，确认 `DSTMASK=0x00` 路径可通
+4. 再发一个单目标数据帧，例如只打到 `S1`
+5. 最后验证多目标位图转发
+
+---
+
+## 8. TCP / UART / CH390 联调顺序
+
+### 8.1 先做链路，再做业务
+
+在 `CH390` 初始化、链路和 IRQ 未被证明稳定前，不要先调高层 TCP/UART 业务。
+
+### 8.2 推荐顺序
+
+建议按以下顺序推进：
+
+1. RTT 启动与 trap 状态正常
+2. CH390 启动日志完整
+3. 链路检测可信
+4. `TCP server` / `TCP client` 建链可信
+5. UART 原始透传可信
+6. 再切入 `MUX` 模式联调
+
+### 8.3 最小 TCP 调试工具
+
+当需要验证板子是否真的把 payload 发到主机时，优先使用仓库内置最小工具：

 1. `tools/tcp_debug_server.py`
-   - 纯 Python 原始 TCP 服务端
-   - 可直接打印连接、收包、文本视图和十六进制视图
-   - 适合确认“板子到底有没有把原始 payload 发到 PC 的 8081 端口”
+   - 打印连接、收包、文本视图和十六进制视图
 2. `tools/start_tcp_debug_server.ps1`
-   - PowerShell 包装脚本
-   - 会先清理本机 `8081` 端口上的现有监听，再启动 Python 调试服务端
-   - 适合避免 `ncat`、遗留 Python、VOFA 等进程抢占 `8081`
+   - 会先清理冲突监听，再启动 Python 服务端

-推荐使用方法：
+推荐命令：

 ```powershell
 powershell -ExecutionPolicy Bypass -File ".\tools\start_tcp_debug_server.ps1" -Port 8081 -NoStdin
 ```

-如需回显模式：
+如需回显：

 ```powershell
 powershell -ExecutionPolicy Bypass -File ".\tools\start_tcp_debug_server.ps1" -Port 8081 -Echo
@@ -177,92 +380,117 @@ powershell -ExecutionPolicy Bypass -File ".\tools\start_tcp_debug_server.ps1" -P
 python .\tools\tcp_debug_server.py --host 0.0.0.0 --port 8081 --no-stdin
 ```

-使用该工具时，推荐调试顺序如下：
+### 8.4 推荐验证方法

 1. 先关闭 VOFA、`ncat` 和其它可能占用 `8081` 的进程
 2. 启动 `start_tcp_debug_server.ps1`
-3. 再让板子连接 `192.168.31.1:8081`
-4. 然后从 PC 连接板子的 `192.168.31.100:8080`，发送一段明确文本，例如 `hello`
-5. 观察 Python 工具是否打印：
-   - 客户端已连接
-   - 收到的原始字节长度
-   - 文本视图与十六进制视图
+3. 让板子连接主机 `TCP client` 目标端口
+4. 再从主机连接板子的 `TCP server` 端口发送固定测试文本
+5. 同时观察：
+   - Python 工具是否收到连接与 payload
+   - 板子 RTT 是否出现连接或错误信息

-如果板子 RTT 显示 `TCP client connected to ...:8081`，但 Python 工具没有任何连接提示，优先检查本机端口占用：
+若板子 RTT 显示已连接，但主机工具无数据，优先检查本机端口占用而不是先改板端逻辑。

-```powershell
-Get-NetTCPConnection -LocalPort 8081 -ErrorAction SilentlyContinue |
-Select-Object LocalAddress,LocalPort,RemoteAddress,RemotePort,State,OwningProcess
-```
+---

-若存在多个监听者，优先清理后再测，否则板子可能连接到错误的本机进程。
+## 9. 异常、卡死与假死排查

-### 5.5 P4：验证系统级联调
+### 9.1 看到 `TRAP:` 时怎么做

-最终再验证：
+1. 先记录 RTT 中的 trap 标签
+2. 立刻用调试器查看当前 PC / LR / 调用栈
+3. 结合 `Core/Src/stm32f1xx_it.c` 中对应 handler 定位异常类型

-1. TCP Server 与 UART2 双向透传
-2. TCP Client 与 UART3 双向透传
-3. 配置保存、复位与 MAC 生效路径
-4. 长时间运行稳定性
+### 9.2 没有 `TRAP:` 但系统不工作时怎么做

-## 6. 推荐的现场观测点
+若没有 `TRAP:`，但系统表现异常，应优先区分以下情况：

-### 6.1 软件观测点
+1. 主循环仍在跑，只是业务路径没反应
+2. 中断未到或链路未更新
+3. 发生了阻塞式等待或超时问题
+4. 上层工具接错端口或被错误进程抢占

-优先关注以下函数与状态：
+### 9.3 历史上已经确认过的典型软件问题

-1. `BootDiag_ReportCh390()`
-2. `ch390_runtime_probe_identity()`
-3. `ch390_runtime_init()`
-4. `ch390_runtime_poll()`
-5. `ch390_runtime_check_link()`
-6. `ch390_runtime_input()`
-7. `ch390_runtime_output()`
+以下问题在历史排查中已经出现过，应优先复核，不要重复踩坑：

-### 6.2 硬件观测点
+1. PHY 访问无超时，导致永久卡死
+2. 刷新未初始化的 IWDG 句柄导致 HardFault
+3. 在长耗时 SPI 路径中错误扩大临界区，导致看似“系统假死”
+4. 在多个层次同时触达 CH390 / SPI，导致运行时边界混乱
+5. 配置口命令结束方式不对，导致误判为 parser 无响应

-优先关注 CH390 芯片脚侧：
+---

-1. `RSTB`
-2. `SCS`
-3. `SCK`
-4. `SDI/MOSI`
-5. `SDO/MISO`
-6. `INT`
-7. `VDDK`
-8. `AVDD33/VDDIO`
-9. `AVDD33`
-10. `XI/XO`
-
-## 7. 常见误区
+## 10. 常见误区

 调试当前工程时，应避免以下误区：

-1. 不要再直接沿用“CH390 恒为全 `0xFF`”这一过时结论
+1. 不要继续沿用“CH390 恒为全 `0xFF`”这一过时结论
 2. 不要在 `main.c`、IRQ、netif 多处重新插入原始 CH390 访问
-3. 不要在没有芯片脚侧证据前，只凭 MCU 侧 GPIO 就认定 `RST/CS/SCK/MISO` 正常
-4. 不要在基础寄存器读写尚不可信时，直接调高层 `TCP/UART` 业务逻辑
-5. 不要把一次性的 bring-up 实验代码长期留在正式启动路径中
-6. 不要让 `VOFA`、`ncat`、自写 Python 服务端等多个进程同时监听 `8081`；否则板子可能连接到错误的本机进程，导致 RTT 显示 `connected` 但目标工具无数据
+3. 不要在没有芯片脚侧证据前，只凭 MCU 侧 GPIO 判断总线正常
+4. 不要在基础寄存器读写尚不可信时，直接调高层 `TCP/UART/MUX` 业务逻辑
+5. 不要把一次性 bring-up 实验代码长期留在正式路径中
+6. 不要让多个本机进程同时监听板子要连接的 TCP 端口
+7. 不要在尚未证明命令已真正进入 parser 之前，直接归因到 Flash、协议或网络层

-## 8. 当前推荐结论表达方式
+---

-当需要向项目成员同步当前状态时，推荐使用如下表述：
+## 11. 推荐的现场记录模板
+
+建议每次现场调试至少记录以下信息：
+
+1. 日期时间
+2. 板卡编号
+3. 固件产物路径
+4. 下载方式
+5. RTT 关键日志
+6. 串口发送内容
+7. TCP 调试工具输出
+8. 关键波形或电压量测点
+9. 结论
+10. 下一步动作
+
+建议记录格式：
+
+```text
+时间：
+板卡：
+固件：
+下载方式：
+操作步骤：
+RTT输出：
+串口/TCP现象：
+硬件量测：
+结论：
+下一步：
+```
+
+---
+
+## 12. 当前推荐的结论表达方式
+
+若需要向项目成员同步当前状态，建议采用以下口径：

 1. 当前工程软件架构已稳定在 `bare-metal + lwIP RAW + ch390_runtime 单一拥有者`
-2. 当前 CH390D 已恢复基础寄存器读写，调试重点已转入初始化完整性、链路、中断与收发功能
-3. 硬件验证仍必须以 CH390 芯片脚侧波形与电源域量测为准
-4. 上层 `TCP/UART` 联调应建立在 CH390 初始化、链路与供电稳定三者都可信之后
-5. 本项目已确认过一次真实硬件根因：CH390D 供电滤波电容虚焊会直接表现为网络收发异常
+2. 当前调试重点已经从“CH390 是否完全无响应”转移到协议、链路和系统级联调
+3. 当前对外协议和配置模型应以 `MUX / NET / LINK[idx]` 为准
+4. `USART1` 配置口、`USART2/3` 数据口与 TCP 路由必须按最新代码路径调试，不应再参照历史 `IP/MASK/GW/PORT/RIP/RPORT` 公开接口模型
+5. 硬件验证仍必须以 CH390 芯片脚侧波形和供电域量测为准

-## 9. 建议配套文档
+---

-建议与本指南配套阅读：
+## 13. 建议配套阅读

-1. `项目技术实现.md`
-2. `CH390D_硬件检查指南.md`
-3. `uart-ch390-debug-handoff.md`
-4. `PCB/SCH_Schematic1_2026-03-26.pdf`
-5. `tools/tcp_debug_server.py`
-6. `tools/start_tcp_debug_server.ps1`
+建议与本指导配套阅读：
+
+1. `AT固件使用手册.md`
+2. `项目技术实现.md`
+3. `项目需求说明.md`
+4. `uart-ch390-debug-handoff.md`
+5. `CH390_最终结论报告.md`
+6. `build_keil.log`
+7. `PCB/SCH_Schematic1_2026-03-26.pdf`
+8. `tools/tcp_debug_server.py`
+9. `tools/start_tcp_debug_server.ps1`