269 lines
9.4 KiB
Markdown
269 lines
9.4 KiB
Markdown
# TCP2UART 工程调试指南
|
||
|
||
## 1. 适用范围
|
||
|
||
本指南面向当前 `TCP2UART` 工程，目标是指导以下调试场景：
|
||
|
||
1. `STM32F103R8T6 + CH390D` 的基础 bring-up
|
||
2. CH390D 的寄存器读写、链路检测、中断与收发调试
|
||
3. `lwIP RAW API + NO_SYS=1` 路线下的网络链路问题定位
|
||
4. UART 透传与 TCP 双链路联调
|
||
|
||
本指南默认基线：
|
||
|
||
1. 当前工程已切换为裸机主循环架构
|
||
2. CH390 运行时访问统一由 `ch390_runtime` 持有
|
||
3. 调试输出通过 `SEGGER RTT`
|
||
4. 当前代码已经通过 `MDK-ARM` 构建，且构建结果为 `0 error / 0 warning`
|
||
|
||
## 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 完全无响应”的旧结论，而应转入功能链路验证。
|
||
|
||
## 3. 代码入口与责任边界
|
||
|
||
### 3.1 启动路径
|
||
|
||
当前 CH390 相关启动链路为：
|
||
|
||
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()`
|
||
|
||
### 3.2 运行时责任边界
|
||
|
||
当前代码约束如下：
|
||
|
||
1. `Drivers/CH390/CH390_Interface.c`
|
||
- 只负责底层 GPIO、SPI 与寄存器/内存访问
|
||
- 当前寄存器读写路径使用 `Mode 3 + bytewise exchange` 事务模型
|
||
2. `Drivers/CH390/CH390.c`
|
||
- 只负责芯片级 helper，例如 `default_config`、PHY 访问、MAC 操作
|
||
3. `Drivers/CH390/ch390_runtime.c`
|
||
- 唯一的 CH390 运行时拥有者
|
||
- 负责初始化、链路查询、IRQ 消费、RX/TX 服务
|
||
4. `Drivers/LwIP/src/netif/ethernetif.c`
|
||
- 不再直接承担复杂 CH390 运行时事务，只做 netif glue
|
||
5. `Core/Src/main.c`
|
||
- 启动后只通过 `BootDiag_ReportCh390()` 读取 runtime 提供的启动快照
|
||
|
||
调试时应优先维护这个边界，不要重新把原始寄存器访问散落回 `main.c` 或 EXTI 中断中。
|
||
|
||
## 4. 当前硬件连接事实
|
||
|
||
根据 `PCB/SCH_Schematic1_2026-03-26.pdf`，CH390D 关键硬件事实如下：
|
||
|
||
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 侧判断。
|
||
|
||
## 5. 推荐调试顺序
|
||
|
||
### 5.1 P0：先确认基础条件
|
||
|
||
每次进入功能调试前，先确认以下最小基线：
|
||
|
||
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. `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. `RSTB`
|
||
2. `CS`
|
||
3. `SCK`
|
||
4. `MOSI`
|
||
5. `MISO`
|
||
6. `VDDK / AVDD33/VDDIO / AVDD33`
|
||
|
||
### 5.3 P2：验证 IRQ 与链路检测
|
||
|
||
在基础寄存器读写可信后，重点验证：
|
||
|
||
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`”
|
||
|
||
### 5.4 P3：验证 RX/TX 数据通路
|
||
|
||
在 `link_up` 可信后，再继续验证数据通路：
|
||
|
||
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 透传是否联通
|
||
|
||
### 5.4.1 最小 TCP 调试工具
|
||
|
||
当需要验证 `TCP server(8080)` 到 `TCP client(8081)` 的原始桥接行为时，优先使用仓库内置的最小工具，而不是直接依赖 VOFA 这类带协议/显示假设的上位机工具。
|
||
|
||
推荐工具如下：
|
||
|
||
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`
|
||
|
||
推荐使用方法：
|
||
|
||
```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
|
||
```
|
||
|
||
直接运行 Python 服务端也可以：
|
||
|
||
```powershell
|
||
python .\tools\tcp_debug_server.py --host 0.0.0.0 --port 8081 --no-stdin
|
||
```
|
||
|
||
使用该工具时，推荐调试顺序如下：
|
||
|
||
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 工具是否打印：
|
||
- 客户端已连接
|
||
- 收到的原始字节长度
|
||
- 文本视图与十六进制视图
|
||
|
||
如果板子 RTT 显示 `TCP client connected to ...:8081`，但 Python 工具没有任何连接提示，优先检查本机端口占用：
|
||
|
||
```powershell
|
||
Get-NetTCPConnection -LocalPort 8081 -ErrorAction SilentlyContinue |
|
||
Select-Object LocalAddress,LocalPort,RemoteAddress,RemotePort,State,OwningProcess
|
||
```
|
||
|
||
若存在多个监听者，优先清理后再测，否则板子可能连接到错误的本机进程。
|
||
|
||
### 5.5 P4：验证系统级联调
|
||
|
||
最终再验证：
|
||
|
||
1. TCP Server 与 UART2 双向透传
|
||
2. TCP Client 与 UART3 双向透传
|
||
3. 配置保存、复位与 MAC 生效路径
|
||
4. 长时间运行稳定性
|
||
|
||
## 6. 推荐的现场观测点
|
||
|
||
### 6.1 软件观测点
|
||
|
||
优先关注以下函数与状态：
|
||
|
||
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 硬件观测点
|
||
|
||
优先关注 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. 常见误区
|
||
|
||
调试当前工程时，应避免以下误区：
|
||
|
||
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` 但目标工具无数据
|
||
|
||
## 8. 当前推荐结论表达方式
|
||
|
||
当需要向项目成员同步当前状态时，推荐使用如下表述：
|
||
|
||
1. 当前工程软件架构已稳定在 `bare-metal + lwIP RAW + ch390_runtime 单一拥有者`
|
||
2. 当前 CH390D 已恢复基础寄存器读写，调试重点已转入初始化完整性、链路、中断与收发功能
|
||
3. 硬件验证仍必须以 CH390 芯片脚侧波形与电源域量测为准
|
||
4. 上层 `TCP/UART` 联调应建立在 CH390 初始化、链路与供电稳定三者都可信之后
|
||
5. 本项目已确认过一次真实硬件根因：CH390D 供电滤波电容虚焊会直接表现为网络收发异常
|
||
|
||
## 9. 建议配套文档
|
||
|
||
建议与本指南配套阅读：
|
||
|
||
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`
|