Merged
docs(pypto_pro): Document SK early-start API (SkCap, wait/set) and the superkernel example #7258
zhouqingheAdd on 9 days ago
docs(pypto_pro): Document SK early-start API (SkCap, wait/set) and the superkernel example #7258
Merged
zhouqingheAdd on 9 days ago
Total: 15 files changed+443-21
@@ -543,10 +543,12 @@
543 - [pypto_pro.language.system.mutex_lock](pro_api/SIMD-API/synchronization/mutex_lock.md)543 - [pypto_pro.language.system.mutex_lock](pro_api/SIMD-API/synchronization/mutex_lock.md)
544 - [pypto_pro.language.system.mutex_unlock](pro_api/SIMD-API/synchronization/mutex_unlock.md)544 - [pypto_pro.language.system.mutex_unlock](pro_api/SIMD-API/synchronization/mutex_unlock.md)
545 - [pypto_pro.language.system.set_cross_core](pro_api/SIMD-API/synchronization/set_cross_core.md)545 - [pypto_pro.language.system.set_cross_core](pro_api/SIMD-API/synchronization/set_cross_core.md)
546+ - [pypto_pro.language.system.set_next_task_start](pro_api/SIMD-API/synchronization/set_next_task_start.md)
546 - [pypto_pro.language.system.sync_all](pro_api/SIMD-API/synchronization/sync_all.md)547 - [pypto_pro.language.system.sync_all](pro_api/SIMD-API/synchronization/sync_all.md)
547 - [pypto_pro.language.system.sync_src](pro_api/SIMD-API/synchronization/sync_src.md)548 - [pypto_pro.language.system.sync_src](pro_api/SIMD-API/synchronization/sync_src.md)
548 - [pypto_pro.language.system.sync_dst](pro_api/SIMD-API/synchronization/sync_dst.md)549 - [pypto_pro.language.system.sync_dst](pro_api/SIMD-API/synchronization/sync_dst.md)
549 - [pypto_pro.language.system.wait_cross_core](pro_api/SIMD-API/synchronization/wait_cross_core.md)550 - [pypto_pro.language.system.wait_cross_core](pro_api/SIMD-API/synchronization/wait_cross_core.md)
551+ - [pypto_pro.language.system.wait_pre_task_end](pro_api/SIMD-API/synchronization/wait_pre_task_end.md)
550 - [缓存控制](pro_api/SIMD-API/cache_control/index.md)552 - [缓存控制](pro_api/SIMD-API/cache_control/index.md)
551 - [pypto_pro.language.system.dcci](pro_api/SIMD-API/cache_control/dcci.md)553 - [pypto_pro.language.system.dcci](pro_api/SIMD-API/cache_control/dcci.md)
552 - [系统访问变量](pro_api/SIMD-API/system_variables/index.md)554 - [系统访问变量](pro_api/SIMD-API/system_variables/index.md)
@@ -13,8 +13,10 @@ bar_all
13mutex_lock13mutex_lock
14mutex_unlock14mutex_unlock
15set_cross_core15set_cross_core
16+set_next_task_start
16sync_all17sync_all
17sync_src18sync_src
18sync_dst19sync_dst
19wait_cross_core20wait_cross_core
21+wait_pre_task_end
20```22```
lyz0328lyz03288 days ago

建议明确sk功能定位,是否需要输出特性文档,指导用户开发sk算子

likedislike
@@ -0,0 +1,87 @@
1+# pypto_pro.language.system.set_next_task_start
2+ 
3+## 产品支持情况
4+ 
5+<!-- npu="950" id1 -->
6+ 
7+- Ascend 950PR&950DT系列产品:支持
8+ 
9+<!-- end id1 -->
10+ 
11+<!-- npu="A3" id2 -->
12+ 
13+- Atlas A3系列产品:不支持
14+ 
15+<!-- end id2 -->
16+ 
17+<!-- npu="910b" id3 -->
18+ 
19+- Atlas A2系列产品:不支持
20+ 
21+<!-- end id3 -->
22+ 
23+## 功能说明
24+ 
25+SuperKernel是一种算子二进制融合技术;本接口是SK子核函数内的任务间同步接口,用于开启早启(Early-Start)能力中“与后序子核并行”的行为。调用位置之后的指令可以与**后序**子核函数并行执行,是[pypto_pro.language.system.wait_pre_task_end](wait_pre_task_end.md)的对偶接口。
26+ 
27+该接口只在核函数被融合为SK子核时生效:需要在[JIT编译](../../../../guide/programming_guide/pro/development/compilation_and_execution/JIT_compilation.md)的sk_cap参数中打开能力位2(pypto_pro.language.SkCap.CAP_2_EARLY_START_SET),并由SK框架/图编译侧开启early_start选项(例如TorchAir图后端的`super_kernel_optimize_options={"early_start": 1}`)。未融合或未开启early_start时,早启配置为0,本接口为空操作。
28+ 
29+## 函数原型
30+ 
31+```python
32+pypto_pro.language.system.set_next_task_start(
33+ *,
34+ force: bool = True,
35+) -> None
36+```
37+ 
38+## 参数说明
lyz0328
lyz0328lyz03288 days ago

[LOW] [开源写作规范/多余空行] docs/zh/api/pro_api/SIMD-API/synchronization/set_next_task_start.md:38(wait_pre_task_end.md:38同) 问题:「## 参数说明」标题与参数表之间存在连续两个空行(39-40行,多余空行)。 建议:删除多余空行,保留一个。

likedislike
39+ 
40+| 参数 | 输入/输出 | 说明 |
41+| ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42+| force | 输入 | 可选,bool编译期常量,默认True。True时生成`AscendC::SetNextTaskStart<PIPE_MTE3, PIPE_FIX, true>()`;False时生成`AscendC::SetNextTaskStart()`。在Ascend 950PR&950DT系列产品上,AIV/AIC的默认pipe分别为PIPE_MTE3/PIPE_FIX,强制形式会显式写出。SK子核上下文中默认(FORCE=false)形式会被编译优化掉,因此默认使用强制形式。 |
43+ 
44+## 约束说明
45+ 
46+- 只能在SK子核函数中调用;普通(未融合)Kernel中调用不产生效果。
47+- 需与pypto_pro.language.jit的sk_cap参数配套:设置pypto_pro.language.SkCap.CAP_2_EARLY_START_SET(如需同时关闭DCCI,可写pypto_pro.language.SkCap.CAP_2_EARLY_START_SET | pypto_pro.language.SkCap.CAP_4_DISABLE_DCCI_ALL)。sk_cap含CAP_1/CAP_2时框架自动追加`-D__ASCENDC_SUPERKERNEL_EARLY_START_V3`。
48+- 与配对子核中的[pypto_pro.language.system.wait_pre_task_end](wait_pre_task_end.md)配合使用:二者作用于同一个子核间边界的两侧,当前子核调用本接口(set),相邻的后序子核调用wait_pre_task_end(wait)。SK图编译按相邻子核配对生成同步任务,未配对时同步任务退化为空同步,不产生重叠效果。
49+- 应放在算子最后一次数据搬运之后,使其后的指令与后序子核并行。
50+- 每个核、每个TilingKey分支中必须且只能调用一次,避免在运行时if/for中按不同条件调用;所有可能运行的TilingKey分支都应调用,否则同步指令数量不匹配可能卡住。
51+- 避免与[pypto_pro.language.system.sync_all](sync_all.md)、[pypto_pro.language.system.set_cross_core](set_cross_core.md)的核间同步事件ID冲突;早启同步内部占用核间同步事件ID。
52+- force必须是编译期bool常量;传入字符串、整数或运行时标量会被前端拒绝。
53+ 
54+## 返回值说明
55+ 
56+无。
57+ 
58+## 调用示例
59+ 
60+本示例在SIMD(Tile)kernel的最后一次数据搬运之后调用pypto_pro.language.system.set_next_task_start,使调用位置之后的指令可以与后序子核并行。
61+ 
62+```python
63+import pypto_pro.language as pl
64+ 
65+ 
66+@pl.jit(auto_mutex=True, sk_cap=pl.SkCap.CAP_2_EARLY_START_SET)
67+def early_start_set_kernel(
68+ x: pl.Tensor[[1024, 64], pl.DT_FP32],
69+ out: pl.Tensor[[1024, 64], pl.DT_FP32],
70+):
71+ tt = pl.TileType(shape=[1, 64], dtype=pl.DT_FP32, target_memory=pl.MemorySpace.Vec)
72+ tile_x = pl.make_tile(tt, addr=0x0000)
73+ tile_out = pl.make_tile(tt, addr=0x0100)
74+ 
75+ with pl.section_vector():
76+ for row in pl.range(
77+ pl.get_block_idx(),
78+ x.shape[0],
79+ pl.get_block_num() * pl.get_subblock_num(),
80+ ):
81+ pl.load(tile_x, x, [row, 0])
82+ pl.add(tile_out, tile_x, tile_x)
83+ pl.store(out, tile_out, [row, 0])
84+ 
85+ # 最后一次数据搬运算完之后调用,后续指令可与后序子核并行。
86+ pl.system.set_next_task_start(force=True)
87+```
@@ -0,0 +1,86 @@
1+# pypto_pro.language.system.wait_pre_task_end
2+ 
3+## 产品支持情况
4+ 
5+<!-- npu="950" id1 -->
6+ 
7+- Ascend 950PR&950DT系列产品:支持
8+ 
9+<!-- end id1 -->
10+ 
11+<!-- npu="A3" id2 -->
12+ 
13+- Atlas A3系列产品:不支持
14+ 
15+<!-- end id2 -->
16+ 
17+<!-- npu="910b" id3 -->
18+ 
19+- Atlas A2系列产品:不支持
20+ 
21+<!-- end id3 -->
22+ 
23+## 功能说明
24+ 
25+SuperKernel是一种算子二进制融合技术;本接口是SK子核函数内的任务间同步接口,用于开启早启(Early-Start)能力中“等待前序子核”的行为。调用位置之前的指令可以与**前序**子核函数并行执行,调用位置之后恢复子核间的保序。
26+ 
27+该接口只在核函数被融合为SK子核时生效:需要在[JIT编译](../../../../guide/programming_guide/pro/development/compilation_and_execution/JIT_compilation.md)的sk_cap参数中打开能力位1(pypto_pro.language.SkCap.CAP_1_EARLY_START_WAIT),并由SK框架/图编译侧开启early_start选项(例如TorchAir图后端的`super_kernel_optimize_options={"early_start": 1}`)。未融合或未开启early_start时,早启配置为0,本接口为空操作。
28+ 
29+## 函数原型
30+ 
31+```python
32+pypto_pro.language.system.wait_pre_task_end(
33+ *,
34+ force: bool = True,
35+) -> None
36+```
37+ 
38+## 参数说明
39+ 
40+| 参数 | 输入/输出 | 说明 |
41+| ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
42+| force | 输入 | 可选,bool编译期常量,默认True。True时生成`AscendC::WaitPreTaskEnd<true>()`;False时生成`AscendC::WaitPreTaskEnd()`。在SK子核上下文中,默认(FORCE=false)形式会被编译优化掉,因此默认使用强制形式。 |
43+ 
44+## 约束说明
45+ 
46+- 只能在SK子核函数中调用;普通(未融合)Kernel中调用不产生效果。
47+- 需与pypto_pro.language.jit的sk_cap参数配套:设置pypto_pro.language.SkCap.CAP_1_EARLY_START_WAIT(如需同时关闭DCCI,可写pypto_pro.language.SkCap.CAP_1_EARLY_START_WAIT | pypto_pro.language.SkCap.CAP_4_DISABLE_DCCI_ALL)。sk_cap含CAP_1/CAP_2时框架自动追加`-D__ASCENDC_SUPERKERNEL_EARLY_START_V3`。
48+- 与配对子核中的[pypto_pro.language.system.set_next_task_start](set_next_task_start.md)配合使用:二者作用于同一个子核间边界的两侧,相邻的前序子核调用set_next_task_start(set),当前子核调用本接口(wait)。SK图编译按相邻子核配对生成同步任务,未配对时同步任务退化为空同步,不产生重叠效果。
49+- 每个核、每个TilingKey分支中必须且只能调用一次,避免在运行时if/for中按不同条件调用;所有可能运行的TilingKey分支都应调用,否则同步指令数量不匹配可能卡住。
50+- 避免与[pypto_pro.language.system.sync_all](sync_all.md)、[pypto_pro.language.system.set_cross_core](set_cross_core.md)的核间同步事件ID冲突;早启同步内部占用核间同步事件ID。
51+- force必须是编译期bool常量;传入字符串、整数或运行时标量会被前端拒绝。
52+ 
53+## 返回值说明
54+ 
55+无。
56+ 
57+## 调用示例
58+ 
59+调用位置之前的代码可与前序子核并行;需要在依赖前序子核输出的指令之前调用,以恢复保序。
60+ 
61+```python
62+import pypto_pro.language as pl
63+ 
64+ 
65+@pl.jit(auto_mutex=True, sk_cap=pl.SkCap.CAP_1_EARLY_START_WAIT)
66+def early_start_wait_kernel(
67+ x: pl.Tensor[[1024, 64], pl.DT_FP32],
68+ out: pl.Tensor[[1024, 64], pl.DT_FP32],
69+):
70+ tt = pl.TileType(shape=[1, 64], dtype=pl.DT_FP32, target_memory=pl.MemorySpace.Vec)
71+ tile_x = pl.make_tile(tt, addr=0x0000)
72+ tile_out = pl.make_tile(tt, addr=0x0100)
73+ 
74+ with pl.section_vector():
75+ # 调用前的准备工作可与前序子核并行。
76+ pl.system.wait_pre_task_end(force=True)
77+ # 以下指令依赖前序子核的输出。
78+ for row in pl.range(
79+ pl.get_block_idx(),
80+ x.shape[0],
81+ pl.get_block_num() * pl.get_subblock_num(),
82+ ):
83+ pl.load(tile_x, x, [row, 0])
84+ pl.add(tile_out, tile_x, tile_x)
85+ pl.store(out, tile_out, [row, 0])
86+```
@@ -1,19 +1,21 @@
1# 术语表1# 术语表
2 2 
3-| 术语/缩略语 | 含义 |3+| 术语/缩略语 | 含义 |
4-| ----------------- | ------------------------------------------------------------ |4+| ----------------------- | ------------------------------------------------------------ |
5-| **PyPTO** | PyPTO是CANN采用PTO编程范式的高性能编程框架,旨在简化算子开发流程,同时保留高性能计算的能力。 |5+| **PyPTO** | PyPTO是CANN采用PTO编程范式的高性能编程框架,旨在简化算子开发流程,同时保留高性能计算的能力。 |
6-| **PTO** | PTO(Parallel Tensor/Tile Operation)是一种基于Tensor的编程范式,核心思想是将Tensor作为数据的基本表达方式,通过一系列对Tensor的基本运算来描述并组装完整的计算流程(或计算图)。 |6+| **PTO** | PTO(Parallel Tensor/Tile Operation)是一种基于Tensor的编程范式,核心思想是将Tensor作为数据的基本表达方式,通过一系列对Tensor的基本运算来描述并组装完整的计算流程(或计算图)。 |
7-| **Operation** | PyPTO中描述计算图中基本运算的单元。每个Operation定义了一个具体的计算逻辑,能够处理输入Tensor并生成输出Tensor。通过组合不同的Operation,可以实现复杂的计算逻辑。 |7+| **Operation** | PyPTO中描述计算图中基本运算的单元。每个Operation定义了一个具体的计算逻辑,能够处理输入Tensor并生成输出Tensor。通过组合不同的Operation,可以实现复杂的计算逻辑。 |
8-| **计算图** | PyPTO程序从抽象计算描述到硬件执行的完整编译流程。 |8+| **计算图** | PyPTO程序从抽象计算描述到硬件执行的完整编译流程。 |
9-| **Tensor Graph** | Tensor Graph由Tensor和Operation节点构成,用于描述用户定义的计算流程。该图不涉及Tile展开与内存层级等底层语义,仅作为高层计算逻辑的表达。基于Tensor Graph的优化主要集中在与硬件无关的通用图优化技术上,例如冗余节点消除、常量折叠等。 |9+| **Tensor Graph** | Tensor Graph由Tensor和Operation节点构成,用于描述用户定义的计算流程。该图不涉及Tile展开与内存层级等底层语义,仅作为高层计算逻辑的表达。基于Tensor Graph的优化主要集中在与硬件无关的通用图优化技术上,例如冗余节点消除、常量折叠等。 |
10-| **Tile Graph** | Tile Graph由Tile和TileOp构成。Tensor Graph根据TileShape展开,将Tensor分解为Tile,将Operation分解为TileOp。Tile Graph依据TileOp信息以及目标硬件的内存层级,自动推导Tile的存储位置,并在必要时插入内存搬运节点,确保数据在不同内存层级之间正确传输。 |10+| **Tile Graph** | Tile Graph由Tile和TileOp构成。Tensor Graph根据TileShape展开,将Tensor分解为Tile,将Operation分解为TileOp。Tile Graph依据TileOp信息以及目标硬件的内存层级,自动推导Tile的存储位置,并在必要时插入内存搬运节点,确保数据在不同内存层级之间正确传输。 |
11-| **Block Graph** | Block Graph通过将Tile Graph切分为多个子图,使得每个子图可以调度运行在单个AI Core上。Block Graph用于硬件相关的优化,包括指令编排、片上内存分配、同步操作插入等,从而提升硬件执行效率。 |11+| **Block Graph** | Block Graph通过将Tile Graph切分为多个子图,使得每个子图可以调度运行在单个AI Core上。Block Graph用于硬件相关的优化,包括指令编排、片上内存分配、同步操作插入等,从而提升硬件执行效率。 |
12-| **Execute Graph** | Execute Graph是编译流程的最终产物,整合了所有优化结果,精确描述各Block Graph之间的依赖关系,用于设备调度器的调度执行。 |12+| **Execute Graph** | Execute Graph是编译流程的最终产物,整合了所有优化结果,精确描述各Block Graph之间的依赖关系,用于设备调度器的调度执行。 |
13-| **泳道图** | 泳道图用于直观展示计算图的实际调度与执行过程。通过IDE的可视化界面,开发者可以观察数据流动路径、操作间的依赖关系以及可能的性能瓶颈,从而更高效地分析和优化算子的执行性能。 |13+| **泳道图** | 泳道图用于直观展示计算图的实际调度与执行过程。通过IDE的可视化界面,开发者可以观察数据流动路径、操作间的依赖关系以及可能的性能瓶颈,从而更高效地分析和优化算子的执行性能。 |
14-| **TileShape** | PyPTO中用于定义张量分块(Tiling)形状的参数,决定了操作在硬件上的并行粒度与数据划分模式。通过合理配置TileShape,可以优化内存使用与计算效率,使计算过程更好地适配硬件特性。 |14+| **TileShape** | PyPTO中用于定义张量分块(Tiling)形状的参数,决定了操作在硬件上的并行粒度与数据划分模式。通过合理配置TileShape,可以优化内存使用与计算效率,使计算过程更好地适配硬件特性。 |
15-| **Pass** | PyPTO中用于编译优化计算图的阶段,以提升计算图的执行效率和硬件利用率。每个Pass可以对计算图进行特定的优化操作,例如图简化、算子融合、调度优化等。 |15+| **Pass** | PyPTO中用于编译优化计算图的阶段,以提升计算图的执行效率和硬件利用率。每个Pass可以对计算图进行特定的优化操作,例如图简化、算子融合、调度优化等。 |
16-| **合图** | 将计算图中多个逻辑上独立的Operation合并为一个逻辑子图,并由该子图最终生成一个物理计算内核(Kernel)的过程,主要分为深度方向合图和广度方向合图两类。<br> |16+| **合图** | 将计算图中多个逻辑上独立的Operation合并为一个逻辑子图,并由该子图最终生成一个物理计算内核(Kernel)的过程,主要分为深度方向合图和广度方向合图两类。<br> |
17-| **同构子图** | 在计算图中,拓扑结构、算子类型完全一致的局部片段。<br> |17+| **同构子图** | 在计算图中,拓扑结构、算子类型完全一致的局部片段。<br> |
18-| **同构子图组** | 互为同构子图的片段,形成的集合被称为同构子图组。在广度方向合图Pass处理过程中,会为每一组同构子图生成一个唯一的特征标识,即hashorder。<br> |18+| **同构子图组** | 互为同构子图的片段,形成的集合被称为同构子图组。在广度方向合图Pass处理过程中,会为每一组同构子图生成一个唯一的特征标识,即hashorder。<br> |
19-| **stitch** | 打破多个loop循环的边界,将没有依赖关系的多个leaf function执行任务缝合成一个大任务统一下发,减少同步开销,提升调度性能。 |19+| **stitch** | 打破多个loop循环的边界,将没有依赖关系的多个leaf function执行任务缝合成一个大任务统一下发,减少同步开销,提升调度性能。 |
20+| **SuperKernel(SK)** | 算子二进制融合技术:图编译阶段将多个已编译的子核函数融合成一个超级核函数,减少任务调度与下发开销。 |
21+| **早启(Early-Start)** | SuperKernel子核间的任务重叠执行能力:通过成对的set_next_task_start与wait_pre_task_end接口,使子核与相邻子核的指令并行执行。 |
@@ -56,6 +56,7 @@
56 - [高级编程](programming_guide/pro/advanced_programming/index.md)56 - [高级编程](programming_guide/pro/advanced_programming/index.md)
57 - [自动CV并行流水](programming_guide/pro/advanced_programming/auto_parallel_pipeline.md)57 - [自动CV并行流水](programming_guide/pro/advanced_programming/auto_parallel_pipeline.md)
58 - [Cube计算进阶](programming_guide/pro/advanced_programming/cube_computation_advanced_usage.md)58 - [Cube计算进阶](programming_guide/pro/advanced_programming/cube_computation_advanced_usage.md)
59+ - [SuperKernel](programming_guide/pro/advanced_programming/superkernel.md)
59 - [调试调优](programming_guide/pro/debug/index.md)60 - [调试调优](programming_guide/pro/debug/index.md)
60 - [功能调试](programming_guide/pro/debug/functional_debugging.md)61 - [功能调试](programming_guide/pro/debug/functional_debugging.md)
61 - [内存检测](programming_guide/pro/debug/sanitizer.md)62 - [内存检测](programming_guide/pro/debug/sanitizer.md)
@@ -6,4 +6,5 @@
6 6 
7auto_parallel_pipeline7auto_parallel_pipeline
8cube_computation_advanced_usage8cube_computation_advanced_usage
9+superkernel
9```10```
@@ -0,0 +1,83 @@
1+# SuperKernel
2+ 
3+## 功能说明
4+ 
5+SuperKernel是一种算子二进制融合技术:图编译阶段把多个已编译的子核函数融合成一个超级核函数,减少任务调度与下发开销;融合后的子核共享一次下发,相邻子核之间通过核间同步事件完成依赖交接。
6+ 
7+PyPTO Pro通过pypto_pro.language.jit的sk_cap参数声明Kernel的SK能力。设置后,JIT在Host侧Launcher中额外生成`__sk__`入口与`SK_BIND`记录,并在编译阶段追加SK相关的头文件路径和编译宏;kernel.cpp内容与普通构建一致。Kernel是否被融合由图层决定:未融合时按普通Kernel执行,早启接口不产生效果。
8+ 
9+## 使用方法
10+ 
11+### 声明SK能力(sk_cap)
12+ 
13+在pypto_pro.language.jit中通过sk_cap声明能力位,取值为pypto_pro.language.SkCap的成员或其按位或组合,只接受枚举成员,不接受裸整数。各能力位的位值与含义见[JIT编译:JIT装饰器参数](../development/compilation_and_execution/JIT_compilation.md#jit装饰器参数)。
14+ 
15+```python
16+import pypto_pro.language as pl
17+ 
18+ 
19+@pl.jit(auto_mutex=True, sk_cap=pl.SkCap.CAP_4_DISABLE_DCCI_ALL)
20+def exp_tile_kernel(input_tensor, output_tensor):
21+ ...
22+```
23+ 
24+### 在torch.compile中开启SuperKernel <a id="enable-superkernel"></a>
25+ 
26+图编译侧还需开启SuperKernel优化。通过npugraph_ex后端编译时,在torch.compile的options中设置super_kernel_optimize=True:
27+ 
28+```python
29+model = torch.compile(
30+ module,
31+ backend="npugraph_ex",
32+ options={"super_kernel_optimize": True},
33+)
34+```
35+ 
36+如需控制融合范围,可通过torch.npu.super_kernel_scope_begin与torch.npu.super_kernel_scope_end一对接口标定参与融合的子图:两个接口成对使用、scope标识一致,二者之间标记为同一scope的算子作为一个融合范围参与SuperKernel。
37+ 
38+```python
39+class Model(torch.nn.Module):
40+ def forward(self, x):
41+ torch.npu.super_kernel_scope_begin("sk_scope")
42+ y = exp_tile_op(x) # 参与融合的PyPTO Pro子核
43+ y = y + 1.0 # 同范围内的torch算子一并参与融合
44+ torch.npu.super_kernel_scope_end("sk_scope")
45+ return y
46+ 
47+ 
48+model = torch.compile(
49+ Model(),
50+ backend="npugraph_ex",
51+ options={"super_kernel_optimize": True},
52+)
53+```
54+ 
55+### 早启(Early-Start)交互 <a id="early-start"></a>
56+ 
57+相邻子核之间存在可重叠的依赖时,通过成对的早启接口让指定位置的指令与相邻子核并行:
58+ 
59+| 接口 | 作用 |
60+| ----------------------------------------------- | ------------------------------------------------------------------ |
61+| pypto_pro.language.system.wait_pre_task_end | 调用点之前的指令可与前序子核并行,配合CAP_1_EARLY_START_WAIT使用 |
62+| pypto_pro.language.system.set_next_task_start | 调用点之后的指令可与后序子核并行,配合CAP_2_EARLY_START_SET使用 |
63+ 
64+- 两个接口作用于同一个子核间边界的两侧,应在相邻子核中配合使用:前序子核调用set_next_task_start,后序子核调用wait_pre_task_end。SK图编译按相邻子核配对生成同步任务,未配对时同步任务退化为空同步,不产生重叠效果。
65+- 每个核、每个TilingKey分支中必须且只能调用一次,避免在运行时if/for中按不同条件调用;所有可能运行的TilingKey分支都应调用,否则同步指令数量不匹配可能卡住。
66+- force参数为编译期bool常量,默认True;SK子核上下文中非强制形式会被编译优化掉。
67+ 
68+详细说明见[pypto_pro.language.system.wait_pre_task_end](../../../../api/pro_api/SIMD-API/synchronization/wait_pre_task_end.md)与[pypto_pro.language.system.set_next_task_start](../../../../api/pro_api/SIMD-API/synchronization/set_next_task_start.md)。
69+ 
70+### 调度模式(schedmode)
71+ 
72+schedmode=1时,JIT在`__global__`入口生成`__schedmode__(1)`限定符(batch模式)。Kernel内使用pypto_pro.language.system.sync_all()且存在多流并发时建议设置为1,以降低死锁风险;参与融合时需同时设置CAP_8_DISABLE_BATCHMODE_CHECK。
73+ 
74+### 核数按容器扩展
75+ 
76+设置CAP_16_BLOCKDIM_SCALE_UP后,Kernel按融合容器的核数启动,Kernel内需使用pypto_pro.language.get_block_num()动态确定实际核数,不能假设核数等于自身配置值。
77+ 
78+## 约束说明
79+ 
80+- SIMT kernel暂不支持SK适配,设置sk_cap会在编译阶段报错。
81+- 图编译侧需开启SuperKernel优化,融合才会实际发生(详见[在torch.compile中开启SuperKernel](#enable-superkernel)一节)。
82+- 早启的两个接口应在相邻子核中配合使用,详见[早启(Early-Start)交互](#early-start)一节。
83+- sk_cap必须为pypto_pro.language.SkCap成员或其按位或组合,传入裸整数或非法位会被前端拒绝。
@@ -90,6 +90,8 @@ JIT复用范围限于当前Python进程。重新启动进程后会重新执行
90| datatype | dict[str, str] | 声明需要进行数据类型特化的Kernel参数,以及Kernel函数体中引用的数据类型变量名。 | None |90| datatype | dict[str, str] | 声明需要进行数据类型特化的Kernel参数,以及Kernel函数体中引用的数据类型变量名。 | None |
91| compile_timeout | int | 设置当前Kernel的编译超时时间,单位为秒。 | None(基础默认值为600秒) |91| compile_timeout | int | 设置当前Kernel的编译超时时间,单位为秒。 | None(基础默认值为600秒) |
92| max_threads | int或None | SIMT kernel每个Thread Block允许的最大线程数,取值为[1, 2048],SIMT模式必填,SIMD模式不接受该参数。 | None |92| max_threads | int或None | SIMT kernel每个Thread Block允许的最大线程数,取值为[1, 2048],SIMT模式必填,SIMD模式不接受该参数。 | None |
93+| sk_cap | pypto_pro.language.SkCap | SuperKernel能力位。设置后除`__global__`入口外,额外生成`__sk__`入口和`SK_BIND`记录,Kernel可被图编译侧融合;按位或组合`CAP_1_EARLY_START_WAIT`、`CAP_2_EARLY_START_SET`、`CAP_4_DISABLE_DCCI_ALL`、`CAP_8_DISABLE_BATCHMODE_CHECK`、`CAP_16_BLOCKDIM_SCALE_UP`。只接受pypto_pro.language.SkCap成员及其按位或组合,不接受裸整数;SIMT Kernel不支持。 | None |
94+| schedmode | int | Kernel调度模式,写入`__global__`入口的`__schedmode__(mode)`限定符:0为普通模式,1为batch模式。`schedmode=1`且需要参与融合时,应同时设置`CAP_8_DISABLE_BATCHMODE_CHECK`。 | 0 |
93 95 
94```python96```python
95import pypto_pro.language as pl97import pypto_pro.language as pl
@@ -106,6 +108,20 @@ def add_kernel(x, y, out):
106 108 
107`pipeline`接收`pypto_pro.language.pipeline.PipelineConfig`对象,用于配置自动CV并行流水变换;未设置时不执行该变换。配置方法和使用约束参考[自动CV并行流水](../../advanced_programming/auto_parallel_pipeline.md)。109`pipeline`接收`pypto_pro.language.pipeline.PipelineConfig`对象,用于配置自动CV并行流水变换;未设置时不执行该变换。配置方法和使用约束参考[自动CV并行流水](../../advanced_programming/auto_parallel_pipeline.md)。
108 110 
111+`sk_cap`用于SuperKernel(SK)融合适配,取值为pypto_pro.language.SkCap的成员或其按位或组合,`None`表示不生成SK入口。设置后JIT在Host侧Launcher中额外生成`__sk__`入口与`SK_BIND`记录,并在编译阶段追加SK相关的头文件路径和编译宏;`kernel.cpp`内容与普通构建一致。能力位含义如下:
112+ 
113+| 成员 | 位值 | 含义 |
114+| --- | --- | --- |
115+| `CAP_1_EARLY_START_WAIT` | 1 | 核内调用pypto_pro.language.system.wait_pre_task_end,允许调用点之前的指令与前序子核重叠 |
116+| `CAP_2_EARLY_START_SET` | 2 | 核内调用pypto_pro.language.system.set_next_task_start,允许调用点之后的指令与后序子核重叠 |
117+| `CAP_4_DISABLE_DCCI_ALL` | 4 | 框架跳过子核调用前后的DCCI,常作为只需完成绑定的默认取值 |
118+| `CAP_8_DISABLE_BATCHMODE_CHECK` | 8 | 跳过`__schedmode__`检查,使`schedmode=1`的Kernel仍可参与融合 |
119+| `CAP_16_BLOCKDIM_SCALE_UP` | 16 | 允许按容器核数启动,Kernel需按pypto_pro.language.get_block_num()动态确定核数 |
120+ 
121+`sk_cap`只声明Kernel可被融合,是否融合由图层决定;未融合时按普通Kernel执行,早启接口不产生效果。早启位需与配对子核中的接口配合使用(前序子核set、后序子核wait),且每个核、每个TilingKey分支只调用一次。SIMT Kernel暂不支持SK适配,设置`sk_cap`会在编译阶段报错。
122+ 
123+`schedmode`只影响Kernel的下发方式:`0`为普通模式,`1`为batch模式,JIT据此在入口上生成`__schedmode__`限定符。Kernel内使用pypto_pro.language.system.sync_all()且存在多流并发时建议设置为`1`,以降低死锁风险;参与融合时需要配合`CAP_8_DISABLE_BATCHMODE_CHECK`,否则融合会被`__schedmode__`检查拒绝。
124+ 
109## Kernel下发与同步125## Kernel下发与同步
110 126 
111编译完成后,JIT通过Host侧Launcher将Kernel提交到指定Stream。SIMD模式中,`kernel[None, block_dim](...)`使用当前Stream,`kernel[stream, block_dim](...)`使用显式Stream。SIMT kernel的启动方式参见[从Host启动SIMT kernel](../vector_computation/simt_computation.md#从host启动simt-kernel)。127编译完成后,JIT通过Host侧Launcher将Kernel提交到指定Stream。SIMD模式中,`kernel[None, block_dim](...)`使用当前Stream,`kernel[stream, block_dim](...)`使用显式Stream。SIMT kernel的启动方式参见[从Host启动SIMT kernel](../vector_computation/simt_computation.md#从host启动simt-kernel)。
@@ -1,6 +1,6 @@
1# 高级样例 (Advanced Examples)1# 高级样例 (Advanced Examples)
2 2 
3-本目录包含 PyPTO 的高级开发样例,展示了复杂的架构实现、高级设计模式以及系统级的性能调优。3+本目录包含 PyPTO 与 PyPTO Pro 的高级开发样例,展示了复杂的架构实现、高级设计模式以及系统级的性能调优。
4 4 
5## 样例说明5## 样例说明
6 6 
@@ -32,6 +32,12 @@
32 - 将 pypto kernel 声明为 `torch.ops` 自定义算子,导出为 ONNX 制品。32 - 将 pypto kernel 声明为 `torch.ops` 自定义算子,导出为 ONNX 制品。
33 - 从导出的 ONNX 构建可部署的 `libcust_opapi.so`。33 - 从导出的 ONNX 构建可部署的 `libcust_opapi.so`。
34 34 
35+### 6. SuperKernel 用法 ([superkernel](./superkernel))
36+ 
37+- **PyPTO Pro SK 用例 ([superkernel.py](./superkernel/superkernel.py))**:
38+ - 基于 **PyPTO Pro**(`pypto_pro.language`)的 `sk_cap=pl.SkCap.CAP_4_DISABLE_DCCI_ALL` SIMD(Tile)kernel,生成 `__sk__` 入口与 `SK_BIND` 记录。
39+ - 与 torch 原生算子一起通过 `npugraph_ex` + `super_kernel_optimize` 融合为一个超级核。
40+ 
35## 核心特性41## 核心特性
36 42 
37在高级样例中,您将接触到:43在高级样例中,您将接触到:
@@ -61,4 +67,4 @@ export TILE_FWK_DEVICE_ID=0
61 67 
621. 首先深入学习 `advanced_nn/attention`,这是所有现代 LLM 的核心。681. 首先深入学习 `advanced_nn/attention`,这是所有现代 LLM 的核心。
632. 通过 `patterns/function` 学习如何组织大型算子项目。692. 通过 `patterns/function` 学习如何组织大型算子项目。
64-3. 参考 `models` 目录下的真实模型实现,将这些高级特性应用到实际生产中。70+3. 参考 `superkernel` 了解 PyPTO Pro 的 SuperKernel 融合流程。
@@ -1,6 +1,6 @@
1# Advanced Examples1# Advanced Examples
2 2 
3-This directory contains PyPTO advanced development samples, showcasing complex architecture implementations, advanced design patterns, and system-level performance tuning.3+This directory contains PyPTO and PyPTO Pro advanced development samples, showcasing complex architecture implementations, advanced design patterns, and system-level performance tuning.
4 4 
5## Sample Description5## Sample Description
6 6 
@@ -32,6 +32,12 @@ The advanced samples cover the following core areas:
32 - Declares a pypto kernel as a `torch.ops` custom op and exports it as an ONNX artifact.32 - Declares a pypto kernel as a `torch.ops` custom op and exports it as an ONNX artifact.
33 - Builds a deployable `libcust_opapi.so` from the exported ONNX.33 - Builds a deployable `libcust_opapi.so` from the exported ONNX.
34 34 
35+### 6. SuperKernel ([superkernel](./superkernel))
36+ 
37+- **PyPTO Pro SK Sample ([superkernel.py](./superkernel/superkernel.py))**:
38+ - A **PyPTO Pro** (`pypto_pro.language`) SIMD (Tile) kernel with `sk_cap=pl.SkCap.CAP_4_DISABLE_DCCI_ALL`, emitting the `__sk__` entry and the `SK_BIND` record.
39+ - Fused with a native torch op into one superkernel through `npugraph_ex` with `super_kernel_optimize`.
40+ 
35## Core Features41## Core Features
36 42 
37In the advanced samples, you will encounter:43In the advanced samples, you will encounter:
@@ -61,4 +67,4 @@ Navigate to the corresponding subdirectory and run the script.
61 67 
621. First, study `advanced_nn/attention` in depth, as it is the core of all modern LLMs.681. First, study `advanced_nn/attention` in depth, as it is the core of all modern LLMs.
632. Learn how to organize large operator projects through `patterns/function`.692. Learn how to organize large operator projects through `patterns/function`.
64-3. Refer to the real model implementations in the `models` directory to apply these advanced features to production.70+3. Refer to `superkernel` to learn the PyPTO Pro SuperKernel fusion flow.
@@ -0,0 +1,59 @@
1+# SuperKernel 样例 (SuperKernel Sample)
2+ 
3+本示例展示 PyPTO Pro 在 **SIMD(Tile)** 编程方式下使用 **SuperKernel(SK)** 的最小用法。
4+ 
5+## 总览介绍
6+ 
7+SuperKernel 是一种算子二进制融合技术:图编译阶段把多个已编译的子核函数融合成一个超级核函数,减少任务调度与下发开销。PyPTO Pro 通过 `@pypto_pro.language.jit(sk_cap=...)` 在生成的 `call_kernel.cpp` 中增加 `__sk__` 入口和 `SK_BIND` 记录,使 kernel 可以被 SuperKernel 融合。
8+ 
9+## 样例代码特性
10+ 
11+- **PyPTO Pro 脚本**:使用 `import pypto_pro.language as pl`,与 `pypto`(tensor API)示例区分。
12+- **SIMD(Tile)核函数**:在 `with pypto_pro.language.section_vector():` 中使用 `pypto_pro.language.load` / `pypto_pro.language.exp` / `pypto_pro.language.store`,并通过 `pypto_pro.language.get_block_num()` / `pypto_pro.language.get_block_idx()` 按核切分行块。
13+- **SK 绑定**:`@pypto_pro.language.jit(auto_mutex=True, sk_cap=pypto_pro.language.SkCap.CAP_4_DISABLE_DCCI_ALL)` 生成 `__sk__` 入口与 `SK_BIND` 记录;普通 `__global__` 入口保留用于非融合场景。
14+- **与 torch 算子融合**:kernel 通过 `torch.library.custom_op` 暴露给 `torch.compile`,与 `+ 1.0` 一起经 `npugraph_ex` 后端、开启 `super_kernel_optimize` 后融合为一个超级核。
15+- **精度校验**:融合后的结果与 eager `torch.exp(x) + 1` 对比。
16+ 
17+## 代码结构
18+ 
19+- **`superkernel.py`**:
20+ - `exp_tile_kernel`:SIMD(Tile)逐元素 `exp` kernel,`sk_cap=pypto_pro.language.SkCap.CAP_4_DISABLE_DCCI_ALL`。
21+ - `_exp`:包装为 `torch.library.custom_op` 的 PyPTO Pro 子核。
22+ - `ExpAddOne`:PyPTO Pro 子核 + torch `+ 1.0` 的执行模型。
23+ - `test_superkernel`:预热、`torch.compile`(SuperKernel 开启)、精度校验。
24+ 
25+## 运行方法
26+ 
27+### 环境准备
28+ 
29+```bash
30+# 配置 CANN 环境变量
31+# 安装完成后请配置环境变量,请用户根据set_env.sh的实际路径执行如下命令。
32+# 上述环境变量配置只在当前窗口生效,用户可以按需将以上命令写入环境变量配置文件(如.bashrc文件)。
33+ 
34+# 默认路径安装,以root用户为例(非root用户,将/usr/local替换为${HOME})
35+source /usr/local/Ascend/ascend-toolkit/set_env.sh
36+ 
37+# 设置设备 ID
38+export TILE_FWK_DEVICE_ID=0
39+```
40+ 
41+### 执行脚本
42+ 
43+```bash
44+python3 examples/03_advanced/superkernel/superkernel.py
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 Medium Priority

建议:随本 PR 一并提交 examples/03_advanced/superkernel/superkernel.py,或待 !7036 合入后再引入该 README;暂不能提交脚本时,请移除 zh/en README 及 03_advanced 索引中的 superkernel.py 链接、运行命令与"预期输出",避免断链和不可执行的指引。

likedislike
Incorrect?
45+```
46+ 
47+### 预期输出
48+ 
49+```text
50+Input shape: (1024, 512)
51+Output shape: (1024, 512)
52+PASS: SuperKernel example passed (sk_cap=CAP_4_DISABLE_DCCI_ALL, SIMD Tile exp + torch add)
53+```
54+ 
55+## 注意事项
56+ 
57+- 本示例依赖支持 SuperKernel 的 CANN / torch_npu 版本;`npugraph_ex` 后端或 `super_kernel_optimize` 不可用时无法完成融合。
58+- 首次运行会触发 JIT 编译,耗时明显长于后续执行。
59+- 若需关闭 SK 做对照,可将 `sk_cap` 参数去掉,并把 `super_kernel_optimize` 置为 `False`。
@@ -0,0 +1,69 @@
1+# SuperKernel Sample
2+ 
3+This sample shows the minimal usage of **SuperKernel (SK)** for a PyPTO Pro kernel
4+written in the **SIMD (Tile)** programming style.
5+ 
6+## Overview
7+ 
8+SuperKernel is an operator binary fusion technique: at graph compilation time, multiple
9+compiled sub-kernels are fused into one superkernel, reducing task scheduling and launch
10+overhead. With `@pypto_pro.language.jit(sk_cap=...)`, PyPTO Pro adds an `__sk__` entry and an `SK_BIND`
11+record to the generated `call_kernel.cpp`, so the kernel can be fused by SuperKernel.
12+ 
13+## Sample Features
14+ 
15+- **PyPTO Pro script**: uses `import pypto_pro.language as pl`, distinct from the `pypto` (tensor API) samples.
16+- **SIMD (Tile) kernel**: uses `pypto_pro.language.load` / `pypto_pro.language.exp` / `pypto_pro.language.store` inside
17+ `with pypto_pro.language.section_vector():`, and partitions row tiles with `pypto_pro.language.get_block_num()` /
18+ `pypto_pro.language.get_block_idx()`.
19+- **SK binding**: `@pypto_pro.language.jit(auto_mutex=True, sk_cap=pypto_pro.language.SkCap.CAP_4_DISABLE_DCCI_ALL)` emits the `__sk__` entry and the
20+ `SK_BIND` record; the normal `__global__` entry is kept for the non-fused path.
21+- **Fusion with a torch op**: the kernel is exposed through `torch.library.custom_op` to
22+ `torch.compile`, and is fused with `+ 1.0` into one superkernel through the
23+ `npugraph_ex` backend with `super_kernel_optimize` enabled.
24+- **Precision check**: the fused result is compared with eager `torch.exp(x) + 1`.
25+ 
26+## Code Structure
27+ 
28+- **`superkernel.py`**:
29+ - `exp_tile_kernel`: SIMD (Tile) elementwise `exp` kernel with `sk_cap=pypto_pro.language.SkCap.CAP_4_DISABLE_DCCI_ALL`.
30+ - `_exp`: the PyPTO Pro sub-kernel wrapped as a `torch.library.custom_op`.
31+ - `ExpAddOne`: PyPTO Pro sub-kernel plus torch `+ 1.0`.
32+ - `test_superkernel`: warm-up, `torch.compile` (SuperKernel enabled), precision check.
33+ 
34+## Running the Sample
35+ 
36+### Environment Setup
37+ 
38+```bash
39+# Configure the CANN environment variables
40+# After installation, configure the environment variables. For the actual path of set_env.sh, refer to the following command.
41+# The environment variable configuration above takes effect only in the current window. You can write the commands into an environment variable configuration file (for example, .bashrc) as needed.
42+ 
43+# Default path installation, using the root user as an example (for non-root users, replace /usr/local with ${HOME})
44+source /usr/local/Ascend/ascend-toolkit/set_env.sh
45+ 
46+# Set the NPU device ID
47+export TILE_FWK_DEVICE_ID=0
48+```
49+ 
50+### Execute the Script
51+ 
52+```bash
53+python3 examples/03_advanced/superkernel/superkernel.py
54+```
55+ 
56+### Expected Output
57+ 
58+```text
59+Input shape: (1024, 512)
60+Output shape: (1024, 512)
61+PASS: SuperKernel example passed (sk_cap=CAP_4_DISABLE_DCCI_ALL, SIMD Tile exp + torch add)
62+```
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 Medium Priority

变更行:examples/03_advanced/superkernel/README_en.md 第 53 行给出运行命令 python3 examples/03_advanced/superkernel/superkernel.py,第 28 行「Code Structure」也声明该示例由 superkernel.py 实现(exp_tile_kernel / _exp / ExpAddOne / test_superkernel)。

证据链:当前 examples/03_advanced/superkernel/ 目录下只有 README.md 与 README_en.md 两个文件,没有任何 .py 脚本(本次 PR 说明代码变更放在 !7036 中单独提交)。因此本 PR 合入后,README 描述的运行步骤在仓库中无对应文件。

失败模式:用户按 README 执行会直接得到 python3: can't open file '.../superkernel.py': [Errno 2] No such file or directory;同时第 58-62 行的「Expected Output」宣称能打印 PASS: SuperKernel example passed ...,实际无法复现,使用户误以为示例已验证/可用,属于误导性的使用与验证说明。

建议:确认 superkernel.py 是否随本 PR 合入;若否,在 README 中注明脚本随实现 MR 提供、当前不可运行,并移除/标注无法复现的 Expected Output,避免用户执行后直接报文件不存在的错误。

likedislike
Incorrect?
63+ 
64+## Precautions
65+ 
66+- This sample requires a CANN / torch_npu version that supports SuperKernel. Fusion is
67+ unavailable when the `npugraph_ex` backend or `super_kernel_optimize` is not supported.
68+- The first run triggers JIT compilation and takes noticeably longer than subsequent runs.
69+- To run a non-SK baseline, drop the `sk_cap` argument and set `super_kernel_optimize` to `False`.
@@ -78,6 +78,7 @@ python3 examples/01_beginner/basic/basic_ops.py --run_mode sim
783. **第三阶段:深度实践**783. **第三阶段:深度实践**
79 - [03_advanced/advanced_nn](03_advanced/advanced_nn/README.md)79 - [03_advanced/advanced_nn](03_advanced/advanced_nn/README.md)
80 - [03_advanced/patterns](03_advanced/patterns/README.md)80 - [03_advanced/patterns](03_advanced/patterns/README.md)
81+ - [03_advanced/superkernel](03_advanced/superkernel/README.md)
81 82 
82---83---
83 84 
@@ -77,6 +77,7 @@ python3 examples/01_beginner/basic/basic_ops.py --run_mode sim
773. **Phase 3: In-Depth Practice**773. **Phase 3: In-Depth Practice**
78 - [03_advanced/advanced_nn](03_advanced/advanced_nn/README_en.md)78 - [03_advanced/advanced_nn](03_advanced/advanced_nn/README_en.md)
79 - [03_advanced/patterns](03_advanced/patterns/README_en.md)79 - [03_advanced/patterns](03_advanced/patterns/README_en.md)
80+ - [03_advanced/superkernel](03_advanced/superkernel/README_en.md)
80 81 
81---82---
82 83