fix: restore CH390 bridge flow and sync driver docs

工程调试指南.md

@@ -0,0 +1,212 @@
+# 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`