# TCP2UART 调试指导

## 1. 适用范围

本指导面向当前 `TCP2UART` 工程，覆盖以下四类调试场景：

1. `STM32F103RCT6 + CH390D` 的基础 bring-up
2. `SEGGER RTT`、异常陷阱与 FreeRTOS 任务运行状态确认
3. `USART1` 配置口、`USART2/USART3` 数据口与 `MUX / NET / LINK[idx]` 协议联调
4. `TCP Server / TCP Client / UART` 三层数据通路联调与问题隔离

本指导默认基线如下：

1. 当前工程采用 `FreeRTOS` 任务调度架构
2. `CH390` 运行时访问由 `xSpiMutex` 保护，`NetworkTask` 持有主要访问权
3. 调试输出统一使用 `SEGGER RTT`
4. 当前应用层协议模型已经收敛到 `MUX / NET / LINK[idx]`
5. 当前代码应以 `MDK-ARM` 工程构建结果为准

---

## 2. 当前工程边界与真实状态

在进入现场调试前，先统一以下工程边界：

1. 当前项目的主要软件路径已经切换为：
   - `NET`：网络基础参数
   - `LINK[idx]`：链路配置记录
   - `MUX`：数据口承载模式
2. 对外 AT 配置面应只围绕以下命令展开：
   - `AT` / `AT+?` / `AT+QUERY`
   - `AT+MUX` / `AT+NET` / `AT+LINK`
   - `AT+SAVE` / `AT+RESET` / `AT+DEFAULT`
3. 已有结论表明：
   - MCU 启动、RTT、FreeRTOS 调度、TIM4 心跳路径可工作
   - `CH390D` 基础寄存器读写与 `lwIP netif` 基本链路已经打通过一次
   - 真实硬件侧曾定位到 `CH390D` 供电滤波电容虚焊问题
4. 当前调试重点是：
   - FreeRTOS 任务是否正常创建与调度
   - `MUX / NET / LINK[idx]` 协议是否与代码一致
   - UART / TCP / CH390 三层通路是否协同稳定
   - 参数保存、复位和恢复流程是否可靠

---

## 3. 代码入口与调试责任边界

### 3.1 启动与 FreeRTOS 入口

以下代码路径是 bring-up 的第一现场：

1. `Core/Src/main.c`
   - `main()`：总启动入口
   - `SystemClock_Config()`：时钟初始化
   - `MX_FREERTOS_Init()`：FreeRTOS 任务创建（在 `freertos.c` 中实现）
2. `Core/Src/freertos.c`
   - `StartDefaultTask()`：默认任务（LED 心跳 + 看门狗）
   - `MX_FREERTOS_Init()`：用户任务创建入口
3. `Core/Src/stm32f1xx_it.c`
   - 故障与中断入口
   - `TIM4_IRQHandler`：HAL 时间基准
   - `USART1/2/3`、`EXTI0`、DMA 回调等联调关键入口

### 3.2 CH390 责任边界

当前 CH390 调试必须遵守以下责任边界：

1. `Drivers/CH390/CH390_Interface.c`：GPIO / SPI / 寄存器与内存事务
2. `Drivers/CH390/CH390.c`：芯片级 helper
3. `Drivers/CH390/ch390_runtime.c`：唯一的运行时拥有者
4. `Drivers/LwIP/src/netif/ethernetif.c`：netif glue 与轮询桥接
5. SPI 访问由 `xSpiMutex` 保护，避免多任务竞争

### 3.3 配置口与业务口边界

1. `USART1`：AT 配置口，接收 `AT` 命令
2. `USART2 / USART3`：数据口，普通透传或 MUX 承载

---

## 4. 当前硬件与调试工具基线

### 4.1 核心硬件对象

1. MCU：`STM32F103RCT6`（256KB Flash / 48KB SRAM）
2. 以太网芯片：`CH390D`
3. 配置串口：`USART1`
4. 数据串口：`USART2 / USART3`
5. 调试输出：`SEGGER RTT`

### 4.2 构建与下载基线

1. `MDK-ARM/TCP2UART.uvprojx`
2. 启动文件：`startup_stm32f103xe.s`
3. 目标器件：`STM32F103RC`
4. 预处理器宏：`USE_HAL_DRIVER, STM32F103xE`

### 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. FreeRTOS 专项调试

### 5.1 任务状态检查

使用 `vTaskList` 获取所有任务运行状态：

```c
char buf[512];
vTaskList(buf);
SEGGER_RTT_WriteString(0, buf);
```

输出格式：

```text
任务名        状态  优先级  剩余栈  编号
NetworkTask   R     4       120     1
UartTask      B     4       200     2
ConfigTask    B     3       150     3
RouteTask     R     3       180     4
DefaultTask   B     1       80      5
IDLE          R     0       100     6
Tmr Svc       B     2       90      7
```

状态码：`R`=Ready, `B`=Blocked, `S`=Suspended, `D`=Deleted, `I`=Invalid

### 5.2 栈溢出检测

已启用 `configCHECK_FOR_STACK_OVERFLOW = 2`，溢出时自动调用：

```c
void vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)
{
    SEGGER_RTT_printf(0, "STACK OVERFLOW: %s\n", pcTaskName);
    __BKPT(0);
}
```

### 5.3 堆内存失败检测

已启用 `configUSE_MALLOC_FAILED_HOOK`，分配失败时自动调用：

```c
void vApplicationMallocFailedHook(void)
{
    SEGGER_RTT_printf(0, "MALLOC FAILED: Free heap = %u\n", xPortGetFreeHeapSize());
    __BKPT(0);
}
```

### 5.4 常见 FreeRTOS 调试陷阱

1. **优先级反转**：使用 Mutex（含优先级继承）而非 Binary Semaphore 保护共享资源
2. **死锁**：多 Mutex 场景确保所有任务按相同顺序获取
3. **中断优先级**：FreeRTOS 可管理的 ISR 优先级必须 >= `configMAX_SYSCALL_INTERRUPT_PRIORITY`（本工程 5）
4. **栈不足**：每个任务定期调用 `uxTaskGetStackHighWaterMark(NULL)` 检查剩余栈
5. **禁止在中断中调用阻塞 API**：必须使用 `FromISR` 后缀版本

---

## 6. 启动阶段调试顺序

建议按 P0 ~ P5 顺序推进，不要跳层。

### 6.1 P0：确认最小基础条件

1. `MDK-ARM` 可构建并产出新的 `axf/hex/map`
2. 板卡可正常下载与复位
3. RTT 可连接并看到启动输出
4. FreeRTOS 任务创建成功，`DefaultTask` LED 心跳可工作
5. `TIM4` 1ms tick 正常运行

### 6.2 P1：确认 FreeRTOS 调度正常

上电或复位后，优先确认：

1. `StartDefaultTask` 是否进入运行
2. `vTaskList` 输出是否显示所有预期任务
3. `xPortGetFreeHeapSize()` 返回值是否合理
4. 无 `STACK OVERFLOW` 或 `MALLOC FAILED` 输出

### 6.3 P2：确认 CH390 初始化链路

启动阶段应重点关注 `NetworkTask` 中初始化日志：

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: done`

### 6.4 P3：确认 TCP 链路

1. lwIP `tcpip_thread` 是否正常运行
2. TCP Server 是否在指定端口监听
3. TCP Client 是否成功连接远端

---

## 7. MUX / NET / LINK[idx] 联调指导

### 7.1 协议总则

与裸机版本完全一致，参见 `AT固件使用手册.md`。

### 7.2 推荐最小 MUX 联调顺序

1. 先在 `MUX=0` 下跑通原始透传
2. 再切换 `MUX=1`
3. 先发一个控制帧，确认 `DSTMASK=0x00` 路径可通
4. 再发一个单目标数据帧
5. 最后验证多目标位图转发

---

## 8. 异常、卡死与假死排查

### 8.1 看到 `TRAP:` 时怎么做

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

### 8.2 FreeRTOS 任务卡死时怎么做

1. 使用 `vTaskList` 检查各任务状态
2. 如果某个任务始终 `B`(Blocked)，检查其等待的队列/信号量
3. 检查是否有 Mutex 被持有但从未释放
4. 使用调试器暂停，查看各任务的调用栈

### 8.3 常见 FreeRTOS 陷阱

1. 在 ISR 中误调用阻塞 API（如 `xQueueSend` 而非 `xQueueSendFromISR`）
2. 中断优先级低于 `configMAX_SYSCALL_INTERRUPT_PRIORITY` 但调用了 FreeRTOS API
3. Mutex 持有期间任务被删除导致 Mutex 永不释放
4. 栈溢出导致邻近变量被破坏

---

## 9. 常见误区

1. 不要继续沿用"CH390 恒为全 `0xFF`"过时结论
2. 不要在多个任务中直接访问 CH390 SPI（必须通过 Mutex 保护）
3. 不要在没有芯片脚侧证据前，只凭 GPIO 判断总线正常
4. 不要在基础寄存器读写尚不可信时，直接调高层业务
5. 不要在 ISR 中执行复杂 SPI 事务或调用阻塞 API
6. 不要忽视 `configCHECK_FOR_STACK_OVERFLOW` 报告

---

## 10. 推荐配套阅读

1. `AT固件使用手册.md`
2. `项目技术实现.md`
3. `项目需求说明.md`
4. `Keil工程配置说明.txt`