reverse-skills-max: initial public release (restored, redacted, hardened)

vendor-new/rev-skills/.claude/skills/re-hardware-io/references/gotchas.md

@@ -0,0 +1,47 @@
+# 硬件接口工具特有坑与边界
+
+## 电平与供电（烧板高危区）
+
+- **3.3V 板接 5V 信号 = 烧**：板上逻辑电平先万用表实测（常见 3.3V，也有 5V/1.8V）——适配器/分析仪电平不匹配用 TXS0108 类双向电平转换，绝不硬插
+- **VCC/GND 反接**：接线顺序先 GND 后信号线；上电前用万用表通断档复核 VCC-GND 不短路
+- **带电插拔**：USB 设备（调试器/编程器/分析仪）接线瞬间的浪涌可能损伤接口——标准流程是断电接线、上电验证
+- **夹子接触不良**：SOIC8 夹子夹歪/氧化导致识别失败或读出数据错位——用 `-v` 校验，多读两遍比对；接触不稳时换测试座
+
+## 接口识别与连接
+
+- **丝印不可靠**：板上标 TX/RX 的是芯片视角还是板级视角不确定——串口无输出先对调 TX/RX，再用逻辑分析仪实测
+- **波特率猜错**：乱码不代表坏——按 9600/115200 优先枚举（57600/38400/230400 兜底）；逻辑分析仪抓 TX 波形直接数位宽最准
+- **TTL 电平 ≠ RS-232 电平**：老设备上的 DB9 串口是 ±12V RS-232，USB-UART 适配器不能直连——需要 RS-232 电平转换（MAX232 类）
+- **JTAG 引脚复用**：量产板常把 JTAG 脚复用为 GPIO 或只引出 SWD——丝印只有 4 针时先按 SWD 试
+
+## JTAG/SWD 熔断与保护
+
+- **IDCODE 全 0/超时**：量产板熔断 JTAG（或 RDP 读保护开启）——openocd 连不上是常态；试 SWD 接口、按目标系列的 unlock 序列（如 `stm32f1x unlock 0`，部分系列 unlock 会擦除 flash——先备份数据评估）
+- **调试器供电冲突**：ST-Link/J-Link 默认给目标供电（3.3V），目标已独立供电时两路电源打架——关掉调试器供电选项或用只接信号的接线方式
+- **电平不匹配连不上**：1.8V 目标直接接 3.3V 调试器，除了烧口风险，电气参数也不合格——按目标电平选适配器（ST-Link 新版支持 1.65-3.6V 自适应，老版本不行）
+
+## flash 读取质量
+
+- **识别不出型号**：新芯片在老 flashrom 里没条目——先 `flashrom -p ch341a_spi` 看输出，识别失败但芯片丝印明确时用 `-c` 强制指定型号（风险自担，先验证 ID）
+- **读出全 0 或全 FF**：夹子没夹好/芯片被写保护/SPI 电压不对——读回内容与丝印型号容量核对，空数据先排查接触
+- **读保护芯片**：部分 MCU 内置 flash 读保护（RDP/OTP）——flashrom 读不到，走 openocd 解锁流程或改走 UART/固件升级通道
+- **大容量镜像校验**：64MB+ flash 读取耗时长，中途断线文件损坏——加 `-v` 校验，失败重读
+
+## 逻辑分析仪采样
+
+- **采样率不足 → 波形假象**：低于信号速率 4 倍会漏跳变（经验值）——UART 115200 用 ≥1MHz；SPI 数十 MHz 用 100MHz+ 设备，先按信号速率选设备再抓
+- **通道错位**：多通道同时抓时引脚标号与物理位置对应错——抓取前先用已知信号（如 TX 空闲高电平）校准通道
+- **解码器参数错**：UART 解码器波特率/数据位配置错会解出乱码——对照波形先确认位宽再改参数
+
+## 版本差异
+
+- **openocd**：0.12.x 为最近正式版（2021）；发行版打包版本新旧不一——脚本路径以 `/usr/share/openocd/scripts/` 实际为准；新版对部分国产 MCU 支持更好（target/ 下新增 cfg），旧版可能没有对应 target 文件
+- **flashrom**：1.4（2024）为主流，新芯片条目持续加入——老版本识别不了新 SPI flash，升级优先；ch341a_spi 支持自 1.0 起成熟
+- **sigrok-cli/pulseview**：0.7.x 长期稳定；解码器（decoders）随版本扩充，旧版本缺新协议解码器
+- **JTAGulator**：开源固件长期无正式新版，功能以烧录进板的固件版本为准；自行打样的板子注意引脚排列与官方一致
+
+## 使用注意
+
+- 断电接线、先测后接、共地必须（SKILL.md 坑 3 优先过一遍）
+- 提取产物（镜像 + sha256 + 板型/芯片型号）入档（[[re-triage]] 惯例），转 [[re-fw-extract]] / [[re-fw-rootfs]] 分析
+- 仅操作自己持有或有授权的硬件