[Docs] Problems found in PTODSL user guide

[Zhendong404]

Documentation location

ptodsl/docs/user_guide

What's wrong or missing?

PTODSL Kernel Module 文档问题（用户指南视角）

对 ptodsl/docs/user_guide/ 全 12 章 + README 的 review。

---

一、不正确 / 有错误

1. 03-kernel-entry-and-subkernels.md L292-293：句子重复

A module accepts device-side types:

A module accepts device-side types:

完全相同的句子连续出现两次，应删除一个。

2. 引用了不存在的章节

01-introduction.md 的 Chapter Overview 表格列出了 Chapter 13（Migration）、14（Common Errors）、16（Next Steps），但这些文件在仓库中不存在。ptodsl/docs/user_guide/ 下只有 01-12 章。Chapter 15 也不存在。

3. Section 编号交叉引用不一致

位置	当前引用	应为
03-kernel-entry-and-subkernels.md L876	"Section 3.8"	Section 3.10
05-control-flow.md L217	"Section 3.8"	Section 3.10
01-introduction.md L286	"Chapter 5 and Chapter 6"	正确但提到了不存在的标量章节细节

4. constexpr（参数注解）vs const_expr()（trace-time 分支函数）命名混淆

文档中存在两个极易混淆的名称，只差一个下划线：

名称	角色	使用位置
pto.constexpr	@pto.jit 签名中的参数注解	def kernel(*, BLOCK: pto.constexpr = 128)
pto.const_expr(...)	body 内的 trace-time 分支函数	if pto.const_expr(ENABLE):

两者在文档中从未被显式区分说明。05-control-flow.md 的 Summary 表格写的是 pto.const_expr / pto.static_range，完全不提 pto.constexpr。用户极易混淆。

5. Flash Attention Walkthrough 中 tile 分配重复/混乱

11-flash-attention-walkthrough.md 第 11.3.4 节 tile 分配出现了两段大量重叠的内容：

• L167-213 "MAT-backed bridge tiles" 段列出了 o_prev_tile, o_next_tile, m_prev_tile, m_next_tile, l_prev_tile, l_next_tile, s_tile, p_tile, pv_tile, alpha_tile, beta_tile
• L220-232 "UB-resident state and scratch tiles" 段再次列出完全相同的 tile（除了 MAT-backed 带 memory_space 的那几个）

这是明确的复制粘贴错误，用户会以为某些 tile 被分配了两次。

6. mte_load / mte_store 速记名未记录

02-quick-start.md L234-242 和 01-introduction.md 使用了：

pto.mte_load(k_part.as_ptr(), k_tile.as_ptr(), 0, row_bytes, nburst=(...))
pto.mte_store(o_tile.as_ptr(), o_part.as_ptr(), row_bytes, nburst=(...))

但 Chapter 7（Data Movement Operations）记录的正式名称是 pto.mte_gm_ub 和 pto.mte_ub_gm。mte_load/mte_store 在整个 Chapter 7 中完全不出现。如果是 shorthand/alias，应文档化；如果是旧名，应统一。

7. pto.tile.mov 未记录

11-flash-attention-walkthrough.md L426 使用了：

pto.tile.mov(p_tile, p_mat)

但 Chapter 7（Data Movement）和 Chapter 8（Compute Operations）都没有 tile.mov 的文档。用户无法从任何操作参考章节了解这个 API。

8. Chapter 12 GEMM 示例的 mode="explicit" 标注不当

12-additional-examples.md L186 GEMM 示例使用了 mode="explicit"，但 kernel body 只使用了 tile ops（tile.load、tile.store、tile.fill），完全没有 micro-instruction（mte_*、pipe_barrier 等）。虽然 explicit mode 向下兼容 tile ops（如 §3.4 所述），但把这个例子标为 explicit 会让用户困惑。

更严重的是 L270-272 的注释：

"For reference, the same GEMM could be written in mode="explicit" when the kernel needs micro-instruction control."

但代码已经在 mode="explicit" 了，这句话毫无意义。

---

二、不清楚 / 容易误导

9. Kernel module vs sub-kernel 的选择指南不够直接

03-kernel-entry-and-subkernels.md §3.3 的对比表（L398-407）列出了 module 和 sub-kernel 的区别，但没有正面回答用户最可能问的问题：

"我想把一个大 kernel 拆成多个函数，应该用 entry=False module 还是 @pto.simd/@pto.cube/@pto.simt sub-kernel？"

实际规则很简单：

• 需要跑在特定硬件单元上（Cube/SIMD/SIMT）→ 用 sub-kernel
• 只是一般性的代码组织/复用/混合 backend → 用 entry=False module

建议在 §3.3 对比表旁加上这个决策规则。

10. Module / sub-kernel 中 Python for/if 的 AST rewrite 行为说明埋得太深

几乎所有 module 和 sub-kernel 示例都在 body 中使用了 Python for range(...)。但 AST rewrite 对 named sub-kernel 同样生效这一点只在 05-control-flow.md L417-418 一句话带过：

"Named sub-kernel decorators use the same source rewrite semantics when their body is traced."

Module body 的 AST rewrite 行为应该在 §3.3 中明确说明（1-2 句即可），sub-kernel 的应该在 §3.7 中说明，而不是让用户跳到 Chapter 5 才能确认。

11. valid_shape 的动态更新模式没有显式文档化

04-type-system-and-buffer.md 描述 valid_shape 为：

"Logical data region, ≤ shape in each dimension"

完全没有提到：

• valid_shape 是可写的（tile.valid_shape = [q_rows, dim]）
• 需要在每次 sub-kernel / module 调用之前更新
• 这是处理 tail block 的关键模式

这个模式在 Flash Attention walkthrough 中大量出现（L282-318），但在 Type System 章节中没有任何 hint。

12. Module ABI 中 PartitionTensorView 的传递限制

§3.3 的 Module ABI 表格（L308-316）列出了 pto.PartitionTensorView。但在 §3.7 sub-kernel 中，@pto.simd 的 ABI 是 Tile + PTO scalars（L663-665），不包含 PartitionTensorView。这意味着 PartitionTensorView 只能通过 module 传递——这个重要的区分没有被强调。

另外 §3.4 说 explicit mode 下 sub-kernel 也能接收 PartitionTensorView——行为在 auto 和 explicit 间不同，但这种 mode-dependent 的差异没有被突出说明。

13. Module 是否能调用 sub-kernel 的规则不清晰

§3.3 提到 "The subkernel rules still apply: @pto.simd / @pto.cube / @pto.simt are not replaced by module-to-module nesting."（L396-397）

但 module 内部是否可以调用 sub-kernel？module 对比表说 "Can call modules: Yes" 但没有说 "Can call sub-kernels: Yes/No"。用户可能困惑于是否能在 module body 里写 @pto.simd 装饰的内部函数。

14. auto vs explicit mode 的区别散落多处

mode 概念在以下位置分散出现：

• 01-introduction.md L201-230 — 概述
• 02-quick-start.md §2.5 — 通过例子展示
• 03-kernel-entry-and-subkernels.md §3.4 — 最详尽的说明
• 11-flash-attention-walkthrough.md — 实践中展示

用户线性阅读时会在多个地方遇到部分解释，直到 §3.4 才得到完整说明。

15. l2_cache_ctl 参数完全无解释

07-data-movement-ops.md mte_gm_ub 的参数表中：

l2_cache_ctl | int | L2 cache allocate control (2 bits)

没有说明合法值、含义，或至少给一个"大多数情况下传 0"的指导。

16. scalar.* namespace vs Python 内置函数的边界

Chapter 6 解释了 +, -, *, / 可以用于 PTO scalar，但 scalar.max(), scalar.exp() 等需要显式调用。Python 也有内置的 max()、abs()。文档没有说明 max(a, b)（Python 内置）vs scalar.max(a, b) 的区别——前者在 trace time 求值，后者产生 device-side 指令。这个差异可能导致微妙的 bug。

17. Pipe API 对 user guide 来说过于底层

07-data-movement-ops.md §7.6 包含约 335 行的 Pipe Communication 文档，涵盖 c2v、v2c、bidirectional、global-entry、local FIFO 等多种变体。pipe 是高级特性，新用户大概率头几周用不到。放在 user guide 核心章节增加了认知负担，建议移到单独的 advanced topic。

18. pto.const() 在 valid_shape 中的用法令人困惑

12-additional-examples.md L123-125：

a_tile = pto.alloc_tile(shape=[BLOCK], dtype=pto.f32, valid_shape=[pto.const(BLOCK)])

Flash Attention walkthrough 中用直接赋值 tile.valid_shape = [q_rows, dim]。pto.const() 和直接值的区别是什么？何时用哪个？文档未解释。

19. Module 的 backend 默认值和继承规则

§3.3 说 module 可以有自己的 backend，但没有说明如果 module 不指定 backend 时的默认行为——是继承 caller 的 backend？还是默认 vpto？混合 backend 场景（emitc entry → vpto module）需要两边都显式指定还是只在一侧指定即可？

---

三、不必要 / 冗余

20. 装饰器 overview 重复出现

完整的 @pto.jit / sub-kernel 层次图在以下位置以相似格式出现：

1. 01-introduction.md L53-69 — 完整层次图
2. 03-kernel-entry-and-subkernels.md L16-27 — 再次完整层次图

Introduction 应概述（1-2 句概念），Chapter 3 应详述。当前两者格式几乎相同。

21. backend 和 mode 的描述被多次切分

• 01-introduction.md L201-230 — mode + backend 概述
• 03-kernel-entry-and-subkernels.md L43-53 — 再次概述
• 03-kernel-entry-and-subkernels.md L410-503 — mode 详情（§3.4）
• 03-kernel-entry-and-subkernels.md L506-538 — backend 详情（§3.5）

Chapter 3 内的概述→详述是合理的，但 Introduction 中的详细程度应降到只留关键概念。

22. Compile + Launch 样板代码重复

compiled = kernel.compile(...) + compiled[grid, stream](...) 模式出现在：

• 02-quick-start.md L139-153
• 03-kernel-entry-and-subkernels.md L199-224
• 11-flash-attention-walkthrough.md L44-51
• 12-additional-examples.md L58-67

建议只在 Chapter 2 详细解释一次，后续用简写 + 交叉引用。

23. README 中的 API quick reference 与 user guide 重叠

ptodsl/README.md L242-399 的 "DSL-style API quick reference" 与 Chapter 4-10 详细文档高度重叠。README 应该指向 user guide，而不是维护一份不完整的平行 API 参考。

---

建议修复优先级

高优先级（应在此 PR 中修复）：

• 删除重复句子（Python wheel packaging for ptoas, in manylinux docker image #1）
• 添加 kernel module vs sub-kernel 选择指南（Verify across-platform compatibility of python wheel and ptoas binary, using multi-stage docker build  #9）
• 修复 Section 编号交叉引用（Fix ptoas samples: pointer_cast fallback, EmitC constants, runop out-of-tree #3）
• 在 §3.3 中说明 AST rewrite 对 module body 的行为（ptoas --enable-insert-sync does not generate correct set & wait #10）
• 在 §3.3 中明确 module 是否可以调用 sub-kernel（Pythonic frontend prototype #13）
• 说明 module 的 backend 默认值和继承规则（fix syntax error in mix_kernel.py #19）

中优先级（可后续 PR）：

• 明确 constexpr vs const_expr 的区别（Failed to parse MLIR for tmatmulk.pto #4）
• 在 Type System 章节文档化 valid_shape 的动态更新（Missing multi-core block_idx in tmatmulk.py example. #11）
• 修复/删除不存在章节的引用（(docker) fix platform on manylinux wheel #2）
• 统一 mte_load/mte_store vs mte_gm_ub/mte_ub_gm 命名（feat: add ptoas generated cpp and compile cmd #6）
• 在操作参考章节补充 pto.tile.mov 文档（tdivs: support scalar-first ins order #7）
• 修复 Flash Attention tile 分配重复（e2e usage from ptoas compile to npu execution #5）
• 修复 Chapter 12 GEMM mode="explicit" 标注和矛盾注释（feat: add mgather/mscatter/print ops  #8）
• 为 l2_cache_ctl 补充合法值/默认值说明（fix: fix build failed #15）

低优先级（后续迭代）：

• 减少概念重复：decorator overview、compile/launch 样板、backend/mode 切分（feat： support tileview type input of print and add mscatter/mgather t… #20, minimum kernel launch example with torch_npu #21, testci #22）
• 明确 scalar.* vs Python 内置函数的边界（fix: fix ptoas parse failed #16）
• 考虑将 Pipe API 移到单独的 advanced topic（testci #17）
• 说明 pto.const() 在 valid_shape 中的用法（Refine tensor_view shape semantics and partition view samples #18）
• README API quick reference 去重（Enable sync analysis for abs/tabs by wiring pipe + effects #23）