docs: add debug handoff package
This commit is contained in:
@@ -0,0 +1,208 @@
|
||||
# TCP2UART 调试交接清单
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
本清单用于把当前 `TCP2UART` 工程的调试状态、已验证结论、后续动作建议一次性交接给下一位 agent 或开发者。
|
||||
|
||||
这份文档本身就可以当作下一位 agent 的工作 prompt 使用。
|
||||
|
||||
---
|
||||
|
||||
## 2. 先读哪些文档
|
||||
|
||||
接手本工程后，推荐按以下顺序阅读：
|
||||
|
||||
1. `交接清单.md` —— 当前状态、下一步、禁止回退到哪些旧假设
|
||||
2. `工程调试指南.md` —— 已固化的调试经验与真实工程边界
|
||||
3. `项目技术实现.md` —— 架构、任务模型、协议模型
|
||||
4. `项目需求说明.md` —— 用户需求与协议要求
|
||||
5. `AT固件使用手册.md` —— AT 命令与配置面
|
||||
|
||||
---
|
||||
|
||||
## 3. 当前工程状态（交接时刻）
|
||||
|
||||
### 3.1 当前平台与构建状态
|
||||
|
||||
1. 当前 Keil 工程目标仍是 `STM32F103RC`
|
||||
2. 当前代码可以真实构建通过
|
||||
3. 当前构建真值应查看：
|
||||
- `MDK-ARM/build_capture.txt`
|
||||
- `MDK-ARM/TCP2UART/TCP2UART.build_log.htm`
|
||||
- `MDK-ARM/TCP2UART/TCP2UART.map`
|
||||
4. 最近一次 Keil 构建示例：
|
||||
- `Code=84560`
|
||||
- `RW-data=432`
|
||||
- `ZI-data=47056`
|
||||
- `0 Error(s), 0 Warning(s)`
|
||||
|
||||
### 3.2 当前调试结论摘要
|
||||
|
||||
1. `DIAG_TASK_ISOLATION=1` 稳定
|
||||
2. `DIAG_TASK_ISOLATION=0` 仍会卡死
|
||||
3. 卡死边界已经从更早的启动阶段被推进到更靠后的 enabled `netconn_*` 路径
|
||||
4. 在 `RCT6` 上，四个 TCP task 创建后 `FreeRTOS heap` 仅剩约 `944 bytes`
|
||||
5. 这说明当前 `RCT6` 上的资源余量已经严重干扰调试判断
|
||||
6. 因此当前推荐策略是：**先换到 pin2pin 的 `STM32F103RDT6`，再继续 full-task 调试**
|
||||
|
||||
### 3.3 已做过并有信息量的改动/观察
|
||||
|
||||
以下工作已经做过，不要在没有新理由的情况下重复一遍：
|
||||
|
||||
1. 清理与恢复 `DIAG_TASK_ISOLATION=0`
|
||||
2. 用真实 Keil 日志替代 viewer 作为构建真值
|
||||
3. staged creation：将四个 TCP task 延后到 `netif-ready` 后创建
|
||||
4. `lwIP netif` 初始化、post-init、post-ready 关键 RTT 日志
|
||||
5. CH390 TX bounded wait / timeout 观察
|
||||
6. TCP task 栈从 `256` 提高到 `384 words`
|
||||
7. TCP task 入口 `hwm` 日志
|
||||
8. 对 `C1` 增加 one-shot first-connect defer discriminator
|
||||
|
||||
这些动作都让故障边界后移了，但仍未在 `RCT6` 上把问题彻底消灭。
|
||||
|
||||
---
|
||||
|
||||
## 4. 当前最可信的判断
|
||||
|
||||
当前最可信的判断不是“某一行代码单点必错”，而是：
|
||||
|
||||
1. `RCT6` 上的静态 RAM 占用与 FreeRTOS heap 余量都已经接近极限
|
||||
2. disabled 的 task 可以持续打印，说明调度器与基础日志路径未整体死亡
|
||||
3. enabled 的 `S1 / C1` 一旦进入真实 `netconn_*` 路径，就更容易触发新的运行期问题
|
||||
4. 因此如果继续在 `RCT6` 上做更多 discriminator，很容易一直被资源边界噪声带偏
|
||||
|
||||
换句话说，**先把“内存极限平台”这个干扰项拿掉，再看逻辑问题还剩多少，是当前性价比最高的路线。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 下一位 agent 现在应该做什么
|
||||
|
||||
### 5.1 第一目标
|
||||
|
||||
先完成 `STM32F103RCT6 -> STM32F103RDT6` 的工程切换，然后在**尽量不再改业务逻辑**的前提下复现当前版本。
|
||||
|
||||
### 5.2 为什么先这样做
|
||||
|
||||
因为下一位 agent 最先需要回答的，不是“立刻怎么修”，而是：
|
||||
|
||||
1. 换片后 full-task 模式是否还挂
|
||||
2. 如果还挂，挂点是否后移
|
||||
3. 换片后 `free/min heap` 是否显著改善
|
||||
4. enabled `S1 / C1` 是否能进入更深的 `netconn_*` 路径
|
||||
|
||||
---
|
||||
|
||||
## 6. 下一位 agent 的推荐工作步骤
|
||||
|
||||
### Step 1：切换目标器件到 `STM32F103RDT6`
|
||||
|
||||
建议动作：
|
||||
|
||||
1. 更新 Keil target 里的 device 选择
|
||||
2. 对齐 Flash / RAM 容量描述
|
||||
3. 确认 linker / scatter / startup 相关目标描述与新器件一致
|
||||
4. 再次真实构建，确认 `0 Error(s), 0 Warning(s)`
|
||||
|
||||
### Step 2：保持当前代码基线，直接上板复测
|
||||
|
||||
要求：
|
||||
|
||||
1. 不要一换片就继续改业务逻辑
|
||||
2. 使用当前代码基线直接验证
|
||||
3. 仍以 `build_capture.txt` 和 RTT 为主证据
|
||||
|
||||
### Step 3：收集第一轮换片后的关键证据
|
||||
|
||||
至少记录：
|
||||
|
||||
1. `netif-ready` 后是否仍卡死
|
||||
2. `free/min heap` 变化
|
||||
3. enabled `S1 / C1` 的新 RTT 行为
|
||||
4. `C1 first-connect defer` 是否仍然影响故障边界
|
||||
5. LED 心跳和 IWDG 表现是否变化
|
||||
|
||||
### Step 4：根据换片结果分流
|
||||
|
||||
#### 情况 A：换片后明显稳定 / 不再挂
|
||||
|
||||
说明：
|
||||
|
||||
1. RAM 压力是主要阻碍项之一
|
||||
2. 后续需要回头做“资源预算收敛”，而不是继续把当前临时参数直接当最终方案
|
||||
|
||||
#### 情况 B：换片后仍挂，但更晚 / 更深
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前逻辑问题仍在
|
||||
2. 但已经去掉了最主要的资源噪声
|
||||
3. 这时再围绕 `S1 / C1` 的真实 `netconn_new / bind / connect / listen / accept` 做最小日志/判别，会更有信息量
|
||||
|
||||
#### 情况 C：换片后几乎同点位仍挂
|
||||
|
||||
说明：
|
||||
|
||||
1. 主问题不再是单纯 RAM
|
||||
2. 应优先检查 enabled 路径的 API 使用、阻塞行为、线程间交互与资源释放
|
||||
|
||||
---
|
||||
|
||||
## 7. 不要重复的方向
|
||||
|
||||
下一位 agent 接手后，除非有新证据，否则不要优先回到以下旧方向：
|
||||
|
||||
1. 单纯怀疑 startup/init 早期 bring-up
|
||||
2. 把 viewer 当构建真值
|
||||
3. 继续只靠加大 TCP task 栈来解释所有现象
|
||||
4. 默认把 CH390 TX timeout 当成当前一号嫌疑
|
||||
5. 在 `RCT6` 上继续大量增加日志、队列、栈或临时 buffer
|
||||
|
||||
---
|
||||
|
||||
## 8. 关键文件
|
||||
|
||||
### 构建/目标
|
||||
|
||||
1. `MDK-ARM/TCP2UART.uvprojx`
|
||||
2. `MDK-ARM/build_capture.txt`
|
||||
3. `MDK-ARM/TCP2UART/TCP2UART.build_log.htm`
|
||||
4. `MDK-ARM/TCP2UART/TCP2UART.map`
|
||||
|
||||
### 任务与运行期
|
||||
|
||||
1. `Core/Inc/FreeRTOSConfig.h`
|
||||
2. `Core/Src/freertos.c`
|
||||
3. `App/task_net_poll.c`
|
||||
4. `App/tcp_server.c`
|
||||
5. `App/tcp_client.c`
|
||||
|
||||
### 网络与驱动
|
||||
|
||||
1. `Drivers/LwIP/src/netif/ethernetif.c`
|
||||
2. `Drivers/CH390/CH390.c`
|
||||
3. `Drivers/CH390/CH390.h`
|
||||
|
||||
### 文档
|
||||
|
||||
1. `工程调试指南.md`
|
||||
2. `项目技术实现.md`
|
||||
3. `交接清单.md`
|
||||
4. `CODING_PROMPT.md`
|
||||
|
||||
---
|
||||
|
||||
## 9. 可直接给下一位 agent 的 Prompt
|
||||
|
||||
下面这段文字可以直接作为下一位 agent 的起始 prompt：
|
||||
|
||||
```text
|
||||
请先阅读：`交接清单.md`、`工程调试指南.md`、`项目技术实现.md`。
|
||||
|
||||
当前项目是 STM32F103 + FreeRTOS + lwIP + CH390 的 TCP↔UART 透传工程。此前在 `STM32F103RCT6` 上调试时，`DIAG_TASK_ISOLATION=1` 稳定，`DIAG_TASK_ISOLATION=0` 仍会卡死，但故障边界已被多轮 discriminator 推进到 enabled 的 `netconn_*` 路径。当前最关键的资源事实是：在 `RCT6` 上 full-task 创建完四个 TCP 任务后，FreeRTOS heap 只剩约 944 bytes，静态 RAM 也已逼近物理上限，因此当前推荐先切换到 pin2pin 的 `STM32F103RDT6`，保持现有代码基线基本不变，先完成第一轮换片复测，再根据新器件上的 RTT、free/min heap 和 enabled `S1/C1` 行为决定下一步。
|
||||
|
||||
你的当前目标不是立刻修完所有问题，而是：
|
||||
1. 完成 `RCT6 -> RDT6` 目标切换；
|
||||
2. 用真实 Keil 日志确认构建通过；
|
||||
3. 在新器件上复测当前代码，判断故障是否消失、后移或保持原状；
|
||||
4. 仅在拿到新器件上的第一轮 RTT 后，再继续做最小化的下一步判别。
|
||||
```
|
||||
Reference in New Issue
Block a user