@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ascendc-precision-debug/references/ascendc-dumptensor.md

@@ -0,0 +1,205 @@
+# AscendC DumpTensor Debugging
+
+Systematic approach to debug AscendC kernels using DumpTensor API.
+
+## Quick Start
+
+```cpp
+// Add DumpTensor after key computation points
+DumpTensor(inputLocal, 100, 32);   // After CopyIn
+DumpTensor(tmpLocal, 200, 32);     // After computation
+DumpTensor(outputLocal, 300, 32); // Before CopyOut
+```
+
+## 7-Step Debugging Workflow
+
+### 1. Add DumpTensor at Key Points
+
+Insert after: CopyIn, each Compute step, before CopyOut.
+
+```cpp
+// After DataCopy
+LocalTensor<T> inputLocal = inQueue.DeQue<T>();
+DumpTensor(inputLocal, 100, 32);
+
+// After computation
+Adds(tmpLocal, inputLocal, 1.0f, tileLength);
+DumpTensor(tmpLocal, 200, 32);
+
+// Before CopyOut
+DumpTensor(outputLocal, 300, 32);
+```
+
+### 2. Use Systematic Desc Numbering
+
+| Range   | Stage         |
+|---------|---------------|
+| 100-199 | Inputs        |
+| 200-299 | Intermediates |
+| 300-399 | Outputs       |
+
+Increment by 10 within each range.
+
+### 3. Add CPU Golden Prints
+
+Match NPU dump points with CPU prints:
+
+```cpp
+// CPU reference
+printf("[CPU-100] input: %.6f, %.6f\n", input[0], input[1]);
+printf("[CPU-200] tmp: %.6f, %.6f\n", tmp[0], tmp[1]);
+printf("[CPU-300] output: %.6f, %.6f\n", output[0], output[1]);
+```
+
+### 4. Verify Input Data First
+
+Always confirm inputs are correct before debugging computation.
+
+Checklist:
+
+- Input values match CPU golden
+- No NaN/Inf in inputs
+- Data alignment correct
+- Shape/size match expectations
+
+### 5. Segment Verification
+
+Verify each stage independently:
+
+1. **CopyIn** → If wrong, fix DataCopy/DataCopyPad
+2. **Compute** → If wrong, debug computation logic
+3. **CopyOut** → If wrong, fix output stage
+
+### 6. Analyze Error Patterns
+
+See [ascendc-dumptensor-refs/error-patterns.md](ascendc-dumptensor-refs/error-patterns.md) for common patterns and root causes.
+
+### 7. Apply Fix and Verify
+
+Re-run with DumpTensor to confirm fix works.
+
+## References
+
+- [API Reference](ascendc-dumptensor-refs/api-reference.md) - DumpTensor API details and best practices
+- [Error Patterns](ascendc-dumptensor-refs/error-patterns.md) - Common error patterns and root causes
+
+---
+
+## 使用陷阱 ⭐⭐⭐
+
+DumpTensor 本身也受 AscendC 流水线规则约束，用错会读到错的数据从而误导诊断。
+
+### 1. 必须在 DeQue 之后 Dump，不要在 AllocTensor 之后
+
+```cpp
+// ❌ 错误：搬运未完成就 Dump，读到的是上次残留 / 未初始化值
+LocalTensor<T> x = inQueue.AllocTensor<T>();
+DataCopy(x, gm, size);
+DumpTensor(x, 100, 32);   // 读到的不是 gm 的值
+inQueue.EnQue(x);
+
+// ✅ 正确：DeQue 等搬运完成后再 Dump
+LocalTensor<T> x = inQueue.AllocTensor<T>();
+DataCopy(x, gm, size);
+inQueue.EnQue(x);
+LocalTensor<T> xIn = inQueue.DeQue<T>();
+DumpTensor(xIn, 100, 32);  // 此时数据已就绪
+```
+
+如果不方便加 EnQue/DeQue（例如临时插桩），用 `PipeBarrier<PIPE_ALL>()` 兜底——确认结果正确后再决定是补同步还是确实没问题。
+
+### 2. 多核场景必须把 blockIdx 编进 desc
+
+多核并发时所有核的 dump 都会写到同一份日志，无 blockIdx 编号会导致结果完全无法区分。
+
+```cpp
+// ❌ 错误：只看 desc 无法分辨是哪个核
+DumpTensor(inputLocal, 100, 32);
+
+// ✅ 正确：把 blockIdx 编入 desc
+uint32_t desc = 100 + GetBlockIdx() * 1000;   // core 0: 100, core 1: 1100, ...
+DumpTensor(inputLocal, desc, 32);
+```
+
+调试单核问题时，用 `if (GetBlockIdx() == 0)` 把 dump 限制到 0 号核，避免日志爆炸。
+
+### 3. dumpSize 控制
+
+- 默认 32 元素够诊断模式（看头几个值就能判断 NaN / 全零 / 偏移）
+- 大 tensor 完整 dump 会瞬间填满日志缓冲区，并且影响 kernel 时序，掩盖原本的 bug
+- `dumpSize` 不要超过 tensor 实际长度，否则越界
+
+```cpp
+uint32_t dumpSize = std::min(tileLength, 32u);
+DumpTensor(outputLocal, 300, dumpSize);
+```
+
+### 4. 调试完成必须移除
+
+DumpTensor 引入显著时序开销，可能改变流水线行为，定位完后必须删除或宏开关包起来：
+
+```cpp
+#ifdef DEBUG_DUMP
+DumpTensor(outputLocal, 300, 32);
+#endif
+```
+
+---
+
+## 输出读法
+
+输出形如（实际格式以 CANN 版本为准）：
+```
+[DumpTensor] block_idx=0 desc=100 size=32 dtype=float32
+  0.123, 0.456, -0.789, ...
+```
+
+实战流程：
+```bash
+# 跑用例
+./run_op > dump.log 2>&1
+
+# 按 desc 抽取某阶段
+grep "desc=100" dump.log    # 输入
+grep "desc=200" dump.log    # 中间
+grep "desc=300" dump.log    # 输出
+
+# 多核场景按核分离
+grep "block_idx=0" dump.log
+```
+
+把 NPU 输出与 CPU golden 同 desc 编号对齐输出，逐段比对快速定位异常段。
+
+---
+
+## 调试方法选择
+
+DumpTensor 不是唯一选择，根据场景挑：
+
+| 方法           | 场景                              | 优点                  | 局限                    |
+|----------------|-----------------------------------|----------------------|-------------------------|
+| **DumpTensor** | NPU 模式，看 LocalTensor 数据     | 直接看 UB 实际值     | 时序开销大，需流水线同步 |
+| `PRINTF`       | NPU 模式，看 scalar / 控制流      | 轻量                 | 不能直接 dump 整段 tensor |
+| `printf`       | CPU 仿真模式                      | 与普通 C++ 调试一致   | 不能验证 NPU 实际行为    |
+| 二分调试       | 已知有 bug 但插桩定位失败         | 必然能收敛           | 慢、需多次编译运行       |
+
+衔接父 skill 的「调试策略层级」：
+- 先用 DumpTensor 7步法（≤7 次尝试），定位失败立刻切二分调试
+- DumpTensor 看到数据异常后，配合父 skill「症状-原因速查表」对症下药
+- 改完代码记得清 `build/` 和 `$HOME/atc_data/kernel_cache/`，否则 dump 会和上次一致让人误以为没生效
+
+---
+
+## 检查清单
+
+插桩前：
+- [ ] 已在 DeQue 后插桩，没有在 AllocTensor 后直接 dump
+- [ ] 多核场景已把 blockIdx 编进 desc
+- [ ] dumpSize ≤ 32（除非确认需要更多）
+- [ ] CPU golden 已用相同 desc 输出
+- [ ] 编译缓存已清
+
+定位后：
+- [ ] 已识别异常出现的最早阶段（CopyIn / Compute / CopyOut）
+- [ ] 已对照 [error-patterns.md](ascendc-dumptensor-refs/error-patterns.md) 匹配根因
+- [ ] 修复后 dump 验证通过，已移除/宏关闭 DumpTensor

package/assets/ops-direct-invoke/skills/ascendc-precision-debug/references/best-practices.md

@@ -0,0 +1,317 @@
+# 精度调试最佳实践
+
+## 调试原则
+
+### 1. 先怀疑公式，再怀疑实现
+
+大部分精度问题是数学/算法本身的问题，而非实现错误。
+
+**检查顺序**：
+1. 数学公式是否正确
+2. 公式到代码的映射是否正确
+3. API 使用是否正确
+4. 数据类型是否匹配
+5. 数值稳定性问题
+
+### 2. 从小样本开始
+
+测试金字塔：
+```
+     ┌────────────┐
+     │  完整测试   │  ← 最后验证
+     ├────────────┤
+     │  中等规模   │  ← 扩展验证
+     ├────────────┤
+     │  小规模     │  ← 基本验证
+     ├────────────┤
+     │  单元素     │  ← 最先测试
+     └────────────┘
+```
+
+### 3. 记录一切
+
+每次修改都要记录：
+- 修改内容
+- 误差变化
+- 性能影响
+
+```markdown
+### 调试日志
+
+| 修改 | Max Error | Mean Error | 性能 |
+|-----|-----------|------------|------|
+| 初始 | 1.2e-2 | 3.5e-4 | - |
+| FP32 累加器 | 2.1e-4 | 1.2e-6 | -5% |
+| 数值稳定算法 | 8.5e-6 | 2.3e-7 | -8% |
+```
+
+### 4. 理解才能解决
+
+不要盲目试错，要理解误差来源：
+- 为什么会有误差？
+- 误差来自哪个步骤？
+- 如何从根本上避免？
+
+## 验证策略
+
+### 测试金字塔
+
+```
+          ┌────────────┐
+          │  边界测试   │  ← 少量但重要
+          │  特殊值     │
+          ├────────────┤
+          │  随机测试   │  ← 发现未知问题
+          │  多种规模   │
+          ├────────────┤
+          │  回归测试   │  ← 确保不倒退
+          │  标准用例   │
+          └────────────┘
+```
+
+### 边界值覆盖
+
+| 类型 | 测试值 | 说明 |
+|-----|-------|------|
+| 零值 | 0.0 | 测试零值处理 |
+| 极小值 | 1e-10 | 下溢边界 |
+| 小值 | 1e-6 | 正常小值 |
+| 正常值 | 1.0 | 典型值 |
+| 大值 | 1e6 | 正常大值 |
+| 极大值 | 1e10 | 上溢边界 |
+| 负值 | -1.0 | 负数处理 |
+| FP16 饱和 | 65504.0 | FP16 最大值 |
+
+### 对齐覆盖
+
+| 测试类型 | 形状示例 | 目的 |
+|---------|---------|------|
+| 32 字节对齐 FP32 | (8, 16, 8) | 排除对齐问题 |
+| 32 字节对齐 FP16 | (8, 16, 16) | 排除对齐问题 |
+| 非对齐 | (8, 17, 9) | 测试非对齐处理 |
+| 硬件约束边界 | (8, 8, 8) | 最小元素数 |
+
+## 预防措施
+
+### 设计阶段
+
+1. **选择数值稳定的算法**
+   - 避免 a-b 当 a≈b
+   - 使用 log-sum-exp 避免溢出
+   - 先归一化再计算
+
+2. **规划混合精度方案**
+   - 输入/输出 FP16
+   - 关键中间计算 FP32
+   - 累加类操作 FP32
+
+3. **了解硬件约束**
+   - 数据对齐要求
+   - 最小元素数约束
+   - 单次处理上限
+
+### 编码阶段
+
+1. **关键路径注释**
+```cpp
+// 精度敏感：使用 FP32 避免累加误差
+float sum_fp32 = 0.0f;
+for (int i = 0; i < size; ++i) {
+    sum_fp32 += static_cast<float>(input[i]);
+}
+
+// 精度敏感：先减 max 避免 exp 溢出
+half max_val = ReduceMax(input);
+half shifted = input[i] - max_val;
+```
+
+2. **输入验证**
+```cpp
+// 检查硬件约束
+if (cols < 8) {
+    printf("Error: cols must be >= 8 (got %d)\n", cols);
+    return;
+}
+
+// 检查数值范围
+for (int i = 0; i < size; ++i) {
+    if (isinf(static_cast<float>(input[i]))) {
+        printf("Warning: input[%d] is Inf\n", i);
+    }
+}
+```
+
+3. **调试支持**
+```cpp
+#ifdef DEBUG_PRECISION
+    printf("Step %d: value=%.6f\n", step, static_cast<float>(value));
+#endif
+```
+
+## 容差设置指南
+
+### 推荐容差
+
+| 场景 | rtol | atol | 说明 |
+|-----|------|------|------|
+| **FP16 标准** | 1e-3 | 1e-4 | 浮点精度有限 |
+| **FP32 标准** | 1e-5 | 1e-6 | 标准精度 |
+| **整数** | - | 0 | 必须精确匹配 |
+
+### 特殊场景容差
+
+| 场景 | rtol | atol | 原因 |
+|-----|------|------|------|
+| Softmax FP16 | 1e-3 | 1e-4 | 概率输出，精度有限 |
+| Softmax FP32 | 1e-5 | 1e-6 | 标准精度 |
+| Reduce FP16 | 5e-3 | 1e-4 | 累加误差较大 |
+| Reduce FP32 | 1e-5 | 1e-6 | 标准精度 |
+| exp/log FP16 | 1e-3 | 1e-4 | 超越函数精度有限 |
+| 三角函数 FP16 | 5e-3 | 1e-4 | 泰勒展开近似 |
+
+### 容差选择原则
+
+1. **根据应用场景**
+   - 科学计算：严格要求
+   - 深度学习：相对宽松
+   - 可视化：最宽松
+
+2. **根据数据类型**
+   - FP16：宽松容差
+   - FP32：标准容差
+   - INT：零容差
+
+3. **根据算子特性**
+   - 逐元素操作：标准容差
+   - Reduce 操作：宽松容差
+   - 超越函数：宽松容差
+
+## 常见错误模式
+
+### 错误 1：过度调试
+
+**症状**：反复尝试不同方法，没有系统性
+
+**正确做法**：
+1. 先分析误差模式
+2. 识别可能根因
+3. 针对性验证
+4. 记录每次尝试
+
+### 错误 2：忽略 FP32
+
+**症状**：直接用 FP16 调试，难以区分精度问题
+
+**正确做法**：
+1. 先用 FP32 验证算法正确性
+2. 再测试 FP16 精度
+3. 对比差异定位问题
+
+### 错误 3：盲目提高精度
+
+**症状**：所有计算都用 FP32，性能下降
+
+**正确做法**：
+1. 识别真正需要高精度的步骤
+2. 只在关键步骤使用 FP32
+3. 平衡精度和性能
+
+### 错误 4：忽略硬件约束
+
+**症状**：特定输入规模结果异常
+
+**正确做法**：
+1. 查阅硬件约束文档
+2. 添加输入验证
+3. 在文档中说明限制
+
+## 调试效率技巧
+
+### 1. 诊断先行
+
+```
+问题 → 误差分析 → 模式识别 → 根因推断 → 针对性修复
+```
+
+### 2. 快速验证
+
+```
+单元素 → 小规模 → 标准规模 → 大规模 → 边界值
+```
+
+### 3. 计数规则
+
+```
+快速方法计数 < 7 → 继续
+快速方法计数 >= 7 → 切换二分调试
+```
+
+### 4. 记录模板
+
+```markdown
+## 调试记录
+
+### 问题
+- 症状：
+- 输入规模：
+- 数据类型：
+
+### 误差分析
+- 最大误差：
+- 平均误差：
+- 误差模式：
+
+### 调试过程
+1. 尝试：
+   - 方法：
+   - 结果：
+   - 计数：
+
+2. 尝试：
+   - 方法：
+   - 结果：
+   - 计数：
+
+### 解决方案
+- 根因：
+- 修复：
+- 验证：
+```
+
+## 性能与精度平衡
+
+### 混合精度设计
+
+| 部件 | 精度选择 | 原因 |
+|-----|---------|------|
+| 输入 | FP16 | 节省带宽 |
+| 输出 | FP16 | 节省存储 |
+| 中间计算 | FP32 | 提升精度 |
+| 累加器 | FP32 | 避免累积误差 |
+| 比较 | FP16 足够 | 不影响精度 |
+
+### 性能评估
+
+修复精度问题后评估性能影响：
+- 性能损失 < 5%：可接受
+- 性能损失 5-10%：需评估
+- 性能损失 > 10%：考虑优化方案
+
+## 文档化
+
+### 算子文档应包含
+
+1. **精度说明**
+   - 支持的数据类型
+   - 各数据类型的精度特性
+   - 推荐容差设置
+
+2. **已知限制**
+   - 硬件约束（对齐、最小元素数）
+   - 精度限制（FP16 有效数字）
+   - 数值范围限制
+
+3. **使用建议**
+   - 推荐的数据类型组合
+   - 需要避免的输入模式
+   - 性能优化提示