TVM TIRx CUDA 内核编写指南:同步原语、归约与内联 CUDA/PTX 内建函数
TVM TIRx CUDA 内核编写指南:同步原语、归约与内联 CUDA/PTX 内建函数
本文聚焦 TVM 的 TIRx(新一代张量内核编写前端)中 Tx.cuda.* 与 Tx.ptx.* 两大内建函数命名空间,讲解如何在不依赖 tile primitive 的情况下直接触达 CUDA 硬件能力——包括块级/束级同步、CTA 归约、mbarrier 屏障、warp shuffle 全归约,以及通过 func_call 内联原始 CUDA 源码。读完本文,你将掌握在 TIRx 内核中直接调用 CUDA 内建函数与 PTX 指令的完整方法,并能对照源码理解每个内建函数最终生成什么样的 CUDA C++ 代码。
何时需要越过 tile primitive
TIRx 的核心抽象是 tile primitive(Tx.tile.*)——布局感知、自动分发(dispatch)的算子级原语。但在真实内核开发中,总会遇到 tile primitive 尚未覆盖的需求:自定义同步协议、跨束归约、手工实现 warp shuffle、需要特定 PTX 指令(如 cp.async、TMA 的 cp.async.bulk.tensor、Blackwell 的 tcgen05 MMA)等。此时文档 docs/tirx/native_basics/cuda/threads_sync.rst 给出两条直达硬件的"逃生通道":
- 调用后端内建函数:
Tx.cuda.*/Tx.ptx.*命名空间,由tvm.backend.cuda后端提供; - 内联原始 CUDA 源码:通过
Tx.cuda.func_call(..., source_code=...)把一段__device__函数源码原样注入生成代码。
两条路径都以 TVMScript 编写,最终统一降级(lower)为 CUDA C++ 源码,因此你可以像写普通 TIR 内核一样保持类型安全与可调度性,同时获得手写 CUDA 的全部自由度。
调用后端内建函数:Tx.cuda.* 与 Tx.ptx.*
Tx.cuda.* 与 Tx.ptx.* 把 CUDA 后端的设备内建函数直接暴露给脚本层,覆盖同步、mbarrier、归约以及 PTX 数据搬移 / MMA 指令族。两者的分工在其 API 文档中写得很清楚:
Tx.ptx.*(见 docs/tirx/api/ptx.rst)是表驱动的 PTX 指令命名空间:每条指令必须匹配tvm.backend.cuda.ptx.table中注册的表项,由表校验指令族、修饰符组合、操作数个数与类型,并构造一条tirx.ptx.*IR 调用。它只表示"一条"表格描述的 PTX 指令。Tx.cuda.*(见 docs/tirx/api/cuda.rst)是后端辅助函数命名空间:覆盖需要多条指令、C/C++ 表达式、描述符打包、编译器注解等无法用单条 PTX 指令表达的行为。
同步族:cta_sync / warp_sync / warpgroup_sync
文档 docs/tirx/native_basics/cuda/threads_sync.rst 给出同步族的基础用法:
Tx.cuda.cta_sync() # 块级屏障,等价于 __syncthreads()
Tx.cuda.warp_sync() # 束级同步,等价于 __syncwarp()
Tx.cuda.warpgroup_sync(8) # warpgroup 具名屏障,屏障 ID 为 8
这三个内建函数的底层生成逻辑可以在 CUDA 后端源码中直接确认。python/tvm/backend/cuda/cpp/builtins.py 中以最直白的方式注册了前两者:
device_intrinsic("cuda_warp_sync", body=" __syncwarp();")
device_intrinsic("cuda_cta_sync", body=" __syncthreads();")
也就是说,Tx.cuda.cta_sync() 在代码生成阶段就是一条字面意义上的 __syncthreads();,Tx.cuda.warp_sync() 就是 __syncwarp();,没有任何中间包装。Tx.cuda.warpgroup_sync(8) 则对应 PTX 的 warpgroup 具名屏障机制,屏障 ID 需要由内核作者显式约定,常用于 multi-warpgroup 协作的持久化内核(persistent kernel)中划分阶段。
Tx.cuda 的同步与参与(participation)族在 docs/tirx/api/cuda.rst 中还有更完整的成员:any_sync、elect_sync、warp_sync、warpgroup_sync、cta_sync、grid_sync、cluster_sync、syncthreads_and、syncthreads_or、thread_rank、ballot_sync、__shfl_sync、__shfl_up_sync、__shfl_down_sync、__shfl_xor_sync、__activemask。其中 thread_rank 的实现也很有意思——它并非直接用 threadIdx.x,而是经由 CUDA cooperative groups 的 cg::this_thread_block().thread_rank()(见 python/tvm/backend/cuda/cpp/builtins.py),语义上返回当前线程在块内的全局线性编号。
归约族:cta_sum 与块级归约
文档示例中使用了 Tx.cuda.cta_sum 做块级归约:
Tx.cuda.cta_sum(val, num_warps, scratch.ptr_to([0])) # 块级求和归约
从源码看,cta_sum 属于 cuda_cta_reduce 代码生成器一族(python/tvm/backend/cuda/cpp/builtins.py):它校验 num_warps 必须是 2 到 32 之间的 2 的幂(validate_power_of_two_range(num_warps, 1, 32, "cta_reduce num_warps")),先生成一段 32 宽度的 warp 归约辅助函数,再做"束内归约 → 每束首线程写 scratch → __syncthreads → 束 0 再次归约"的两阶段归约。这就是为什么调用时必须提供一块足够容纳归约中间结果的 shared memory scratch——scratch.ptr_to([0]) 正是把共享缓冲区首地址传给归约内核。
归约族在 API 文档中还包括 warp_reduce、warp_sum、warp_max、warp_min、cta_reduce、cta_sum、cta_max、cta_min、reduce_add_sync_u32、reduce_min_sync_u32。warp_reduce 的代码生成器(python/tvm/backend/cuda/cpp/builtins.py)同样会先验证宽度为 2 的幂,再把归约操作翻译成相应的 shuffle 序列。
mbarrier:CTA 共享屏障的完整生命周期
mbarrier(memory barrier)是 CUDA 中面向异步数据搬移的细粒度同步机制,典型用法是配合 TMA 或 cp.async 做生产者-消费者流水。文档给出了一段完整的初始化 + 等待流程:
bar = Tx.alloc_shared((1,), "uint64")
if Tx.cuda.thread_rank() == 0: # 仅由 1 个线程初始化 CTA 共享屏障
Tx.ptx.mbarrier.init.shared.b64(bar.data, Tx.uint32(1))
Tx.cuda.cta_sync() # 确保初始化完成后再有任何线程使用 bar
Tx.cuda.mbarrier_wait(bar.data, phase)
这段代码包含三个必须遵守的纪律:
- 单线程初始化:mbarrier 的存储单元是 64 位(
.b64),只能由一个线程通过Tx.ptx.mbarrier.init.shared.b64初始化,初始化时第二个参数是预期的到达计数(这里为 1); - 初始化后必须同步:
Tx.cuda.cta_sync()保证"初始化已完成"这一事实对所有线程可见,之后任何线程才能安全使用bar; - 相位(phase)匹配:
Tx.cuda.mbarrier_wait(bar.data, phase)中的phase需要与生产者发布(arrive)后翻转的相位一致,这是 mbarrier 免锁同步的关键。
在 CUDA 后端中,mbarrier_wait 通过内置辅助函数 tvm_builtin_cuda_mbarrier_wait 生成(见 python/tvm/backend/cuda/cpp/asm.py),并带有一个自旋超时上限(源码中可见 unsigned int ticks = 0x989680;),避免死锁时无限自旋。Tx.cuda 屏障与内存序族还包括 mbarrier_wait_acquire_cluster、thread_fence、atomic_add、atomic_cas。
完整可运行示例:基于 warp shuffle 的 warp 全归约
文档 docs/tirx/native_basics/cuda/threads_sync.rst 附带一个可直接运行的全归约内核——通过 Tx.tvm_warp_shuffle_xor 实现 32 线程的束内全归约(all-reduce):
@Tx.prim_func
def warp_reduce(A_ptr: Tx.handle):
A = Tx.match_buffer(A_ptr, (32,), "float32", align=16)
Tx.device_entry()
cta_id = Tx.cta_id([1]); warp_id = Tx.warp_id([1]); lane_id = Tx.lane_id([32])
v = Tx.alloc_local((1,), "float32"); i = Tx.alloc_local((1,), "int32")
v[0] = Tx.float32(31 - lane_id)
i[0] = 16
while i[0] >= 1:
v[0] += Tx.tvm_warp_shuffle_xor(0xFFFFFFFF, v[0], i[0], 32, 32)
i[0] = i[0] // 2
A[lane_id] = v[0]
这里的关键点:
Tx.cta_id([1])、Tx.warp_id([1])、Tx.lane_id([32])分别给出块 ID、束 ID 与束内通道号(lane ID,取值范围 0–31),用于定位当前线程;Tx.tvm_warp_shuffle_xor(0xFFFFFFFF, v[0], i[0], 32, 32)的语义是:全 1 掩码(所有 32 条通道都参与)、被交换的值、异或距离i[0]、束宽 32、线程总数 32;- 归约采用经典的 butterfly 模式:距离从 16 逐次减半到 1,每轮把所有线程的值汇聚到每条通道,因此结束时每条通道都持有全束之和。
文档同时给出该内核降级后的 CUDA C++ 形态,证明 shuffle 被直接翻译为 __shfl_xor_sync:
v_ptr[0] = v_ptr[0] + __shfl_xor_sync(0xFFFFFFFF, v_ptr[0], i_ptr[0], 32);
对照 python/tvm/backend/cuda/cpp/builtins.py 中 shuffle 族辅助函数的生成源码,可以看到同样的 __shfl_xor_sync(0xFFFFFFFF, val, mask) 模式——全 1 掩码、目标值与异或掩码作为参数,0xFFFFFFFF 即 PTX 0xffffffff 的活动掩码,表示要求全部 32 条通道参与,任何通道未就绪都会触发未定义行为,因此调用前必须确保束内所有线程到达。
PTX 指令命名空间:Tx.ptx.*
Tx.ptx.* 是比 Tx.cuda.* 更底层的表驱动命名空间。根据 docs/tirx/api/ptx.rst,当前指令表包含 506 条指令、覆盖 101 个指令族,包括但不限于:cp(含 cp.async 即 LDGSTS)、ldmatrix / stmatrix、mma / wgmma / tcgen05(Blackwell MMA)、atom(原子操作)、fence、mbarrier、bar / barrier、shfl_sync、red / red_async、multimem_*(多内存系统)等。文档原文提到的 cp.async(LDGSTS)、cp.async.bulk.tensor(TMA)、ldmatrix/stmatrix、tcgen05.*、atomic_add、fence 都在该表中。
Tx.ptx.* 在 TIRx 中是一个"创作命名空间"而非独立的 IR 方言(见 docs/tirx/api/ptx.rst):每个 Tx.ptx 调用都会在脚本解析阶段被校验并折叠成一条 tirx.ptx.* IR 调用,这一层位于布局感知的 Tx.tile.* 原语之下,不经过 tile primitive 分发。该层由 python/tvm/backend/cuda/ptx/table.py 驱动,新指令的接入方式是扩展指令表并为需要新表示形式的指令补充代码生成支持。
PTX 属性链的书写约定(docs/tirx/api/ptx.rst 的 "Instruction forms" 一节):
- 属性链依次填充 PTX 的修饰符槽位;
- Python 关键字尾部加下划线(如
global_、and_、or_); - PTX 的
::分隔符写作双下划线:shared__cluster、shared__cta; - 索引形式可直接使用 PTX 原文拼写:
Tx.ptx"st.weak.shared::cta.b32"; - 目标寄存器作为前导操作数,因此 PTX 调用是语句(statement)而非表达式;
- 谓词(predication)为关键字参数:
Tx.ptx.ld.global_.b32(value, pointer, pred=predicate, preserve_dst=True); Tx.ptx.pred(value)标记谓词寄存器操作数,Tx.ptx.addr(base, byte_offset)构造带立即数偏移的地址,Tx.ptx.SINK表示 PTX 的 sink 操作数_。
例如 docs/tirx/api/ptx.rst 中的两个直接可用的形式:
Tx.ptx.ld.acquire.gpu.global_.b32(value, pointer)
Tx.ptx.mbarrier.arrive.shared__cluster.b64(barrier, count)
内联原始 CUDA:Tx.cuda.func_call
当某个硬件能力连 PTX 指令表都没有对应条目时,最后一条逃生通道是把一段手写 CUDA __device__ 函数源码作为字符串注入。文档给出了一个 relu 内核的完整示例:
SRC = r"""
__device__ __forceinline__ float my_relu(float x) { return x > 0.f ? x : 0.f; }
"""
@Tx.prim_func
def k(A_ptr: Tx.handle, B_ptr: Tx.handle):
A = Tx.match_buffer(A_ptr, (256,), "float32")
B = Tx.match_buffer(B_ptr, (256,), "float32")
Tx.device_entry(); bx = Tx.cta_id([1]); tx = Tx.thread_id([256])
B[tx] = Tx.cuda.func_call("my_relu", A[tx], source_code=SRC, return_type="float32")
机制上,func_call 做两件事:把 source_code 字符串原样发射到生成的 CUDA 源文件中(作为 __device__ 函数定义),并把调用点接线到该函数——降级后的代码形态如下:
__device__ __forceinline__ float my_relu(float x) { return x > 0.f ? x : 0.f; }
// ...
B_ptr[tx] = my_relu(A_ptr[tx]);
从代码生成实现看,func_call 最终落到 tvm.backend.cuda.op 的 cuda_func_call 构造语句上(见 python/tvm/backend/cuda/codegen/schema.py 与 python/tvm/backend/cuda/cpp/asm.py),也就是说内联 CUDA 与后端内建辅助函数走的是同一条代码生成路径。这解释了为何 Tx.cuda 中的 printf、trap_when_assert_failed、clock64、nano_sleep 等调试/诊断辅助函数也能以同样的机制工作(见 docs/tirx/api/cuda.rst 的 "Loads, calls, and diagnostics" 分类)。
func_call 的使用约束:return_type 需要显式给出返回类型字符串;source_code 中的函数名与调用点的 name 必须一致;源码字符串是逐字(verbatim)发射的,因此应使用 __forceinline__ 等 CUDA 关键字而无需(也不应)依赖 TIRx 的类型推导。
四层选型:如何在 TIRx 中权衡
综合原文档与两个 API 参考文档,编写 CUDA 内核时的选型可以总结为四个层次,从高到低:
| 层次 | 入口 | 适用场景 |
|---|---|---|
| Tile primitive | Tx.tile.* |
布局感知、需要自动分发的高层算子(gemm、copy、reduction 等),见 docs/tirx/tile_primitives.rst |
| CUDA 辅助函数 | Tx.cuda.* |
需要多条指令、C/C++ 表达式、描述符打包或多步行为的操作:同步、归约、mbarrier、shuffle、func_call 等 |
| PTX 指令 | Tx.ptx.* |
单条、表格注册过的 PTX 指令:cp.async、ldmatrix、mma、tcgen05、fence 等 |
| 内联 CUDA | Tx.cuda.func_call |
完全没有内建覆盖的定制 __device__ 函数 |
python/tvm/backend/cuda/cpp/builtins.py 中几乎所有 device_intrinsic / @register_codegen 注册的辅助函数都是"单条 C/C++ 语句即可表达"的形态(如 __syncthreads();、__syncwarp();),而需要多条语句的(如 cta_reduce 的两阶段归约、mbarrier_wait 的超时自旋)则通过源码字符串拼接实现——这正对应 API 文档中 Tx.cuda 与 Tx.ptx 的划分依据:"Use Tx.ptx for one table-described PTX instruction. Use Tx.cuda for backend helpers that require multiple statements..."(见 docs/tirx/api/ptx.rst 的 "PTX versus CUDA helpers" 一节)。
小结
在 TIRx 中触达 CUDA 硬件不需要跳出 TVMScript 生态:Tx.cuda.* 提供多语句级后端辅助函数(同步、归约、mbarrier、shuffle、内联 CUDA),Tx.ptx.* 提供 500+ 条表驱动的 PTX 指令,func_call 则允许任意 __device__ 函数源码注入。理解它们的生成路径(python/tvm/backend/cuda/cpp/builtins.py、python/tvm/backend/cuda/cpp/asm.py、python/tvm/backend/cuda/ptx/table.py)有助于在编写内核时准确预判最终 CUDA 代码形态,例如 cta_sync 就是一行 __syncthreads()、warp shuffle 全归约就是一行 __shfl_xor_sync。更完整的 Tx.cuda 辅助函数清单与 Tx.ptx 指令族列表,分别见 docs/tirx/api/cuda.rst 与 docs/tirx/api/ptx.rst;本主题的原始操作手册位于 docs/tirx/native_basics/cuda/threads_sync.rst。