Pull Request已成功合入, 合并人@CANN-robot
（感谢 ink_polymer 的贡献）
变更摘要
本次 PR 主要对 AscendC 算子开发教程中所有使用 TQue 模板的代码进行了一次系统性的语义重构：引入独立的 QUEUE_DEPTH 常量，将 TQue 的第二个模板参数从 BUFFER_NUM 统一替换为 QUEUE_DEPTH，使 Queue 深度参数在命名上与 buffer 数量概念分离。变更覆盖了 02 至 08 章节的 Jupyter Notebook 教程文件及其对应的 C++ 算子源码/答案文件，同时附带少量格式修正（缩进、文件末尾换行符）。
主要改动
- 引入
QUEUE_DEPTH常量：在所有涉及TQue声明的.cpp、.h、.asc及.ipynb文件中，新增constexpr int32_t/uint32_t QUEUE_DEPTH = <value>;，其值与同文件中已有的BUFFER_NUM保持一致（1 或 2）。 TQue模板参数替换：将AscendC::TQue<AscendC::TPosition::VECIN, BUFFER_NUM>和AscendC::TQue<AscendC::TPosition::VECOUT, BUFFER_NUM>（以及对应的QuePosition命名空间变体）中的第二个模板参数统一从BUFFER_NUM改为QUEUE_DEPTH，涉及输入/输出 Queue 的声明。03.05notebook 格式修正：修复了03.05_tiling_template_attr_tbuf_workspace.ipynb中!rm -rf和!msopgen gen两行 shell 命令的缩进错误。- 文件末尾换行符统一：多个 notebook 文件（如
02.04、03.02、03.05、05.03等）的 JSON 末尾换行符得到修正。
代码审查
Confirmed. Let me now provide the closing summary.
审查总结
本次 diff 共涉及 36 个文件，核心变更是将 Ascend C 算子 kernel 代码中 TQue 模板的第二个参数从 BUFFER_NUM 统一重命名为语义更明确的 QUEUE_DEPTH，同时保留 BUFFER_NUM 用于 tile 计算和 InitBuffer 等场景。所有实际源码文件（.cpp / .h / .asc / .txt）均正确同步添加了 QUEUE_DEPTH 常量定义，变更一致、无行为变化。
发现问题：2 个 P1
| # | 文件 | 问题 |
|---|---|---|
| 1 | 03.04_generalized_tiling_design.ipynb |
TQue 模板参数改为 QUEUE_DEPTH，但初始 %%writefile 单元未添加该常量的定义 → 用户按顺序执行 notebook 后编译失败 |
| 2 | 07.02_CPU_Debugging_Overview.ipynb |
同上，第一版 add.cpp 的 %%writefile 单元缺少 QUEUE_DEPTH 定义（后两个版本已正确添加） |
各文件审查结果
02_AscendC_basic/02.04_...ipynb— 无问题02_AscendC_basic/02.05_chapter_test.ipynb— 无问题02_AscendC_basic/answer/02.04_answer.txt— 无问题02_AscendC_basic/answer/02.05_answer.txt— 无问题02_AscendC_basic/src/add_custom.asc— 无问题03_.../03.02_operator_engineering_intro.ipynb— 无问题03_.../03.04_generalized_tiling_design.ipynb— P1：QUEUE_DEPTH 定义缺失03_.../03.05_tiling_template_attr_tbuf_workspace.ipynb— 无问题03_.../answer/03.02_answer/.../sub_custom_template.cpp— 无问题03_.../answer/03.04_answer/.../sub_custom_template.cpp— 无问题03_.../answer/03.05_answer/.../add_custom_template.cpp— 无问题03_.../answer/03.06_answer/.../sigmoid_custom.cpp— 无问题03_.../src/custom_op/.../add_custom_template.cpp— 无问题03_.../src/custom_op_04/.../add_custom_template.cpp— 无问题05_.../05.03_vv_fused_operator_development.ipynb— 无问题05_.../answer/05.03_answer/.../square_diff.cpp— 无问题06_.../06.03_operator_development_based_on_opensource_repo.ipynb— 无问题06_.../06.05_chapter_practice.ipynb— 无问题06_.../answer/06.03_answer/.../sub_custom.h(NsSub) — 无问题06_.../answer/06.05_answer/.../sigmoid.h(NsSigmoid) — 无问题06_.../src/add_custom/.../add_custom.h— 无问题07_Troubleshooting/07.02_CPU_Debugging_Overview.ipynb— P1：第一版 QUEUE_DEPTH 定义缺失07_Troubleshooting/07.03_NPU_On-Board_Debugging.ipynb— 无问题07_Troubleshooting/07.04_Typical_Issues_...ipynb— 无问题07_Troubleshooting/07.05_chapter_test.ipynb— 无问题07_Troubleshooting/answer/07.04_answer.txt— 无问题07_Troubleshooting/answer/07.05_answer.txt— 无问题08_.../08.02_profiling_tool_usage.ipynb— 无问题08_.../08.03_simulation_analysis.ipynb— 无问题08_.../08.04_ascendc_op_perf_optimization_demo.ipynb— 无问题08_.../08.05_chapter_practice.ipynb— 无问题08_.../src/custom_op/.../add_custom_template.cpp— 无问题08_.../src/custom_op_04_01/.../add_custom_template.cpp— 无问题08_.../src/custom_op_04_02/.../add_custom_template.cpp— 无问题08_.../src/custom_op_04_03/.../add_custom_template.cpp— 无问题08_.../src/custom_op_05/.../add_custom_template.cpp— 无问题
整体风险判断：中等。两个 P1 问题都会导致用户在跟随教程执行时遇到编译失败，但不影响已存在的独立源码文件。修复方式简单明确：在对应 notebook 的 %%writefile 单元中补上 QUEUE_DEPTH 常量定义即可。
| 类型 | 数量 |
|---|---|
| 🔴 阻塞 | 2 |
| 🟡 建议 | 2 |
⛔ 需要修改
Thanks for your pull-request.
The full list of commands accepted by me can be found at here。
You can get sig-info at here
PR Approval Progress
✅ Congratulations! All modules have met the lgtm and approve requirements.
Module Approval Details
| module | lgtm status | approve status |
|---|---|---|
| repo-cann/cann-learning-hub | ✅ waimaidaole, fuyangchenghu (2/2) | ✅ waimaidaole (1/1) |
💡 Tip:
- Committer can comment
/approveor/lgtm- Commenting
/approveimplies both code review (lgtm) and intent to merge (approve)
CLA Signature Pass
ink_polymer, thanks for your pull request. All authors of the commits have signed the CLA. 👍
🟠 High Priority
在 07.02_CPU_Debugging_Overview.ipynb 中，第一个创建 Sources/07.02/cpu_debug/add.cpp 的 %%writefile 单元（第 144-155 行）定义了 BUFFER_NUM = 2（第 154 行），但未添加 QUEUE_DEPTH。然而后续的 %%writefile -a 单元（第 175 行起）中 TQue 声明已被修改为引用 QUEUE_DEPTH（第 228-229 行）。
虽然 notebook 后部还有两个独立的 %%writefile 单元（第 740 行和第 899 行）分别创建了完整版 add.cpp 并正确添加了 QUEUE_DEPTH，但第一个版本缺失该常量，用户在 2.2.1–2.2.3 节顺序执行时会遇到编译错误。
影响行为：第一版 add.cpp 中的 TQue 模板参数引用未定义的编译期常量。
触发条件：从 2.2.1 节开始顺序执行 notebook 单元后编译。
失败模式：C++ 编译错误 —— QUEUE_DEPTH 未声明。
建议：在第一个 %%writefile 单元的 BUFFER_NUM 定义之后添加 QUEUE_DEPTH = 2 的定义，与同一 notebook 后两个版本（第 751 行和第 910 行）的处理方式保持一致。
| 155
| - |
|
155 | + "constexpr int32_t BUFFER_NUM = 2; // tensor num for each queue\n", |
|
156 | + "constexpr int32_t QUEUE_DEPTH = 2;\n", |
changed this line on 530033b7 view diff detail
🟠 High Priority
在 03.04_generalized_tiling_design.ipynb 中，%%writefile -a 代码单元（第 837-850 行）将 TQue 的模板参数从 BUFFER_NUM 改为 QUEUE_DEPTH（第 840-841 行），但创建该文件的 %%writefile 单元（第 642-647 行）仅定义了 BUFFER_NUM = 1，并未同步添加 QUEUE_DEPTH 的定义。
用户在顺序执行 notebook 单元后，生成的 Sources/03.04/custom_op/op_kernel/add_custom_template.cpp 文件中引用了未定义的 QUEUE_DEPTH，导致编译失败。
影响行为：TQue 模板参数引用未定义的编译期常量。
触发条件：按 notebook 单元顺序执行后编译生成的算子 kernel 文件。
失败模式：C++ 编译错误 —— QUEUE_DEPTH 未声明。
建议：在第一个 %%writefile 单元中，BUFFER_NUM 定义之后添加 QUEUE_DEPTH 的定义，与 notebook 中其他文件的处理方式保持一致。即将第 646 行的 "constexpr int32_t BUFFER_NUM = 1;" 改为两行：先定义 BUFFER_NUM，再定义 QUEUE_DEPTH = 1。
| 646
| - |
|
646 | + "constexpr int32_t BUFFER_NUM = 1;\n", |
|
647 | + "constexpr int32_t QUEUE_DEPTH = 1;" |
changed this line on 6b1381ab view diff detail
🟡 Medium Priority
该文件中有 6 个独立的算子代码示例（AddCustom × 5 + SinhCustom × 1），每个都新增了 QUEUE_DEPTH = 2 常量并将 TQue 模板参数从 BUFFER_NUM 改为 QUEUE_DEPTH。但每个代码块中以下位置仍然使用 BUFFER_NUM：
具体受影响的代码块（按 cell 出现的行范围）：
- 第 285-366 行（AddCustom，含 printf 调试）
- 第 525-604 行（AddCustom，含 printf 调试）
- 第 745-824 行（AddCustom，含 printf 调试）
- 第 990-1069 行（AddCustom，CopyOut 中 zLocal 越界场景）
- 第 1255-1334 行（AddCustom，正确示例）
- 第 1485-1564 行（SinhCustom）
当前 BUFFER_NUM 和 QUEUE_DEPTH 值相同（均为 2），不会触发运行时错误。但这是教程代码，不一致的命名会误导学习者；且未来若只修改其中一个常量会导致队列深度与 buffer 分配数量不匹配，引发内存错误或流水线死锁。
建议：统一使用 QUEUE_DEPTH（或统一使用 BUFFER_NUM）作为唯一常量名，并将上述 6 个代码块中所有 InitBuffer、tileLength 计算、loopCount 计算中的 BUFFER_NUM 替换为与 TQue 模板参数一致的常量。两个常量只应保留一个，另一个应删除。
🟡 Medium Priority
该 diff 在 add_custom.asc 和 sub_custom.asc 两个代码块中新增了 constexpr uint32_t QUEUE_DEPTH = 2;，并将 TQue 的第二个模板参数从 BUFFER_NUM 改为 QUEUE_DEPTH（第 300-301 行）。但是以下位置仍使用 BUFFER_NUM：
- 第 406 行：
this->tileLength = this->blockLength / tileNum / BUFFER_NUM; - 第 412-414 行：
pipe.InitBuffer(inQueueX, BUFFER_NUM, ...)等三处 - 第 443-444 行：
int32_t loopCount = this->tileNum * BUFFER_NUM;
在 AscendC 中，TQue 的 depth 参数与 InitBuffer 的 buffer 数量参数必须一致，tileLength 和 loopCount 的计算也依赖同一数值。当前两者值相同（均为 2），不会触发运行时错误；但如果未来只修改其中一个常量而忘记另一个，会导致队列深度与分配的 buffer 数量不匹配，引发内存越界或流水线死锁。
作为教程代码，这种不一致会误导学习者认为 QUEUE_DEPTH 和 BUFFER_NUM 是两个独立的概念，实际上它们必须一致。建议将 InitBuffer、tileLength、loopCount 中的 BUFFER_NUM 也统一改为 QUEUE_DEPTH，或反之在 TQue 中保持使用 BUFFER_NUM 以确保语义统一。
建议：统一使用 QUEUE_DEPTH 替换所有 BUFFER_NUM（或反之保持原样），确保 TQue 模板参数、InitBuffer 调用、tileLength 计算、loopCount 计算使用同一常量。具体需修改的 02.04 文件内行：406（tileLength）、412-414（InitBuffer 三处）、443（loopCount）。如果保留 BUFFER_NUM 作为唯一常量，则应将 TQue 模板参数改回 BUFFER_NUM。
ink_polymerink_polymer/lgtm
描述
补充图片修改问题关联的Issue
测试
文档更新
类型标签
其他信息