# 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.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 实验代码长期留在正式启动路径中

## 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`