TIRx 内核级编译器完全指南:Apache TVM 的下一代硬件原生 Kernel DSL 与 Tile 抽象
TIRx 内核级编译器完全指南:Apache TVM 的下一代硬件原生 Kernel DSL 与 Tile 抽象
本文是 TVM 仓库中 docs/tirx/overview.rst 的中文深度解读。TIRx(读作 "tier-ex")是 Apache TVM 的下一代内核级编译器结构,定位在"快速演进的 Kernel 与快速演进的硬件"交汇处:它把流水线状态、角色分配、同步与后端内建指令保留在硬件原生源码中,同时通过执行作用域(execution scope)、**张量布局(tensor layout)**和 **Tile 原语分派(tile primitive dispatch)**三个核心构造,把反复出现的 tile 级结构暴露给编译器。读完本文,你将掌握 TIRx 的设计哲学、三层作者模型、编程模型核心概念、它能支撑的新硬件扩展 / Megakernel / Agentic 编程三大能力,以及从安装到写出并运行第一个 CUDA kernel 的完整实操路径。
TIRx 是什么:硬件原生、面向 Kernel 的 DSL 与编译器
TIRx 是一个开源、**硬件原生(hardware-native)**的机器学习内核 DSL 与编译器。它瞄准 AI 软件栈中"快速演进的 Kernel 遇到快速演进的硬件"的那一层:今天它编译到 GPU 与专用 AI 加速器,并被设计为能够随后续硬件世代持续生长。同样的设计使它不仅是专家手写 Kernel 的基础设施,也可以作为 Agent 生成内核与 Megakernel 系统的底层基板。
从项目定位看,TIRx 是 Apache TVM 的下一代内核级编译器结构,构建在 TVM 编译器基础设施之上。仓库中可以看到它的完整实现脉络:
- Python 前端:python/tvm/tirx/(作者 API、
tile_primitive.py、exec_scope.py、layout.py、compilation_pipeline.py等); - C++ 核心 IR 与变换:src/tirx/ir/(buffer、exec_scope、stmt、transform 等)、src/tirx/transform/;
- 后端分派与代码生成:src/tirx/backend/、src/tirx/op/;
- 公开 C++ 头文件:include/tvm/tirx/(
layout.h、tile_primitive.h、exec_context.h、index_map.h等)。
在 TVMScript 侧,TIRx 注册了一个方言别名 tirx(见 python/tvm/tirx/init.py 的 tvm.script.register_dialect("tirx", "tvm.tirx.script")),所有示例统一通过 from tvm.script import tirx as Tx 进入。
设计哲学:选择更低、更明确的分界
Kernel DSL 的价值在于在程序员与机器之间选择正确的分界。对于成熟硬件上的成熟 Kernel,这个分界可以很高层:编译器把线程分配、内存搬运、布局细节和指令选择藏在紧凑的 tensor 或 tile 抽象之后,这非常适合既有的 Kernel 模式。
但在前沿领域,同样的分界正承受压力:新指令、新内存空间、新的协作模式与新的 Kernel 算法,往往先于编译器内置机制出现。TIRx 因此选择了更低、更明确的分界:
- 保留在硬件原生源码中的部分:流水线结构(pipeline structure)、同步(synchronization)、角色分配(role assignment)、内存放置(memory placement)、后端内建指令(backend intrinsics)——这些正是经常需要专家级控制的部分;
- 暴露给编译器的部分:通过执行作用域、张量布局、Tile 原语分派三个构造,把反复出现的 tile 级结构呈现给编译器。
硬件原生控制强大,但需要工程投入;把反复出现的操作暴露为 tile 原语则可以减轻这种负担——作者复用一份分派后的实现,而不是为每个 Kernel、每个后端重写同样的操作。
由此得到的 DSL 能够随硬件生长(grow with the hardware):一个新特性可以先直接作为原生内建指令使用,待模式稳定后晋升为可复用的原语。保持基础小而明确、让后端库随新一代加速器不断演进,这正是 TIRx 的核心设计哲学。
编程模型:一个结构化原生内核,三个作者层
一个 TIRx 程序读起来就像结构化的原生内核:循环、分支、缓冲区、同步、流水线状态、后端内建指令与硬件角色都是直接写出的;Tile 原语只出现在"某个重复的硬件级操作应当可复用、可分派"的位置。
作者层与 IR 的关系
TIRx 程序使用同一个 TVMScript 方言别名:
from tvm.script import tirx as Tx
该命名空间暴露三个作者层。它们共享同一个 TIRx 程序,但从不同层级进入编译器:
| 作者层 | 语法 | 表示与降低方式 |
|---|---|---|
| 核心语言 | Tx.* |
创建 TIRx 语句、表达式、缓冲区与控制流 |
| Tile 原语 | Tx.tile.* |
创建一个 TilePrimitiveCall,在 tile 分派期间被替换为目标特定实现 |
| 后端操作 | Tx.cuda.* 与 Tx.ptx.* |
直接创建后端调用;这些调用绕过 tile 分派 |
关键事实:tvm.script.tirx 是 tvm.tirx 对象模型的构造语法,而非独立的 IR。Tile 分派与布局/作用域降低(layout/scope lowering)会把高层 TIRx 节点替换为更低层的 TIRx 语句与调用,但不会把程序转换到独立的 tvm.tir 对象模型。整体编译流水如下:
Tx.* ──────────────────────────────▶ TIRx statements and expressions ──────┐
Tx.tile.* ─▶ TilePrimitiveCall ─▶ target dispatch ─────────────────────────┤
Tx.cuda.* / Tx.ptx.* ─────────────▶ backend calls ─────────────────────────┤
▼
layout and scope lowering ─▶ codegen
从源码结构看,Python 侧的 Tx 是普通模块别名(from tvm.script import tirx as Tx),不是语言关键字;tile 原语与核心语言、后端操作共享 Tx 命名空间,但在 __init__.py 中分别从 tile_primitive.py、stmt.py、expr.py 等模块导出(参见 python/tvm/tirx/init.py)。
核心构造一:执行作用域(Execution Scope)
执行作用域描述一次原语调用的活跃参与者与逻辑作用域:
- 控制流(如
if wg_id == ...、warp_id == ...、cbx == ...)选择哪些硬件角色进入某个区域; - 谓词(如
Tx.cuda.elect_sync())在活跃 warp 内进一步选择发出指令的 lane; - 要为一个更宽的作用域取得唯一发布者,应先选出一个 warp,再在其内部使用
elect_sync。
原语命名空间本身也是作用域的一部分:例如 Tx.tile.wg.* 表示 warpgroup 级原语,而未限定作用域的 Tx.tile.* 调用默认是 thread 级调用。
核心构造二:张量布局(Tensor Layout)
张量布局采用**存储优先(storage-first)**接口,描述逻辑张量如何映射到物理资源。一个 tile 可以位于全局内存、共享内存、每线程本地存储、tensor memory 或加速器 SRAM 中。用户声明每个 tile 驻留在哪里、其元素如何分布在 lanes、warps 与每线程存储单元之间;tile 原语分派读取这些声明来选择实现。
特别要强调:布局是一种存储描述,而不是循环变换工具——用户可以构造 tile 的布局,但永远不能用布局来变换循环。
完整的布局模型(shard / replica / offset 结构与设计动机)参见 docs/tirx/layout.rst。其核心是一个 iter 三元组 (extent, stride, axis),定义某条轴上的线性带步长访问:
- D(Shard,分片):一个或多个 iter 的列表,每个 iter 带 extent 与 stride,把逻辑索引划分到这些 iter 上并产生基坐标;它把 shape–stride 推广到多条轴,用小括号书写,如
S[(8,2,4,2):(4@laneid,1@warpid,1@laneid,1)]; - R(Replica,复制):一组复制 iter,枚举硬件空间中的偏移,与逻辑索引无关;把集合中每个元素加到 D 结果上即得到复制或广播,用方括号书写,如
R[2:4@warpid]; - O(Offset,偏移):固定坐标偏移(每条轴一个整数),加到每个结果上,用于把数据放到基址或预留独占资源。
形式化地,对逻辑索引 x 有 L(x) = { D(x) + r + O | r ∈ R }。单个项写作 n @ axis;若 stride 未配对 axis,默认使用内存轴 m。布局文档中还给出了 NVIDIA tensor-core tile((8,16) tile 分布到 2 个 warp × 32 lanes,带 5@warpid 偏移与 R[2:4@warpid] 复制)、Blackwell tensor memory(TLane × TCol 二维地址空间,224 列非 2 的幂布局)、SFA/SFB 缩放因子(首个使用 replica 的布局,stride 32 覆盖 lanes 0–127 的 "warpx4" 路由)等完整案例,以及共享内存 32B/64B/128B swizzle(XOR 地址置换)的设计,值得单篇深入阅读。
核心构造三:Tile 原语分派(Tile Primitive Dispatch)
Tile 原语分派根据原语、当前执行作用域、操作数布局与目标后端来选择实现。例如:
- 在 CUDA 上,
copy目前选择定宽或自动向量化的 load/store、ldmatrix/stmatrix,或标量回退;异步copy_async原语则有独立的ldgsts、TMA、分布式共享内存(DSMEM)与 tensor-memory 变体; - 在 CUDA 上,
gemm目前选择mma.m16n8k*实现,而gemm_async选择tcgen05;Trainium 则注册了自己的copy、gemm、reduction 与 elementwise 实现。
一旦选定变体,分派会生成把该指令应用到整个 tile 所需的循环与寻址。
在原语目录层面,C++ 注册表当前定义了 31 个操作名,按用途分组(详见 docs/tirx/tile_primitives.rst):
| 分组 | 操作 | 用途 |
|---|---|---|
| 数据移动 | copy、copy_async、permute_layout |
同步/异步搬运,或布局间重排 |
| 矩阵乘 | gemm、gemm_async |
同步寄存器 MMA,或异步/后端特定 MMA(支持处含块缩放) |
| 初始化 | fill、memset、zero |
初始化 tile 或区域 |
| 一元与转换 | cast、sqrt、exp、exp2、log2、reciprocal、silu |
逐元素转换或一元数学 |
| 二元与三元 | add、sub、mul、fdiv、maximum、minimum、fma、select |
逐元素算术与选择 |
| 归约 | sum、max、min |
归约选中轴,可选累加到目标 |
| 融合与组合 | binary_reduce、unary_reduce、binary_chain、reduce_negate、compose_op |
把多个原语组合成后端一次性分派的单元 |
一次调用被物化为 TilePrimitiveCall 节点(python/tvm/tirx/tile_primitive.py),字段携带分派所需的全部信息:op(原语身份,如 tirx.tile.copy_async)、args(操作数)、workspace(预分配 scratch 缓冲区)、config(开放式调优袋,无中央 schema,各分派实现自行解释;TMA 变体会拒绝未知键)、dispatch(强制变体名,None 表示自动选择,这是分派器唯一通用解释的字段)、scope(协作作用域,默认 thread)。
调用约定上,Tx.tile.<name>(...) 默认在 thread 作用域运行,Tx.tile.warp.* / Tx.tile.wg.*(别名 Tx.tile.warpgroup)/ Tx.tile.cta.* / Tx.tile.cluster.* / Tx.tile.thread.* 绑定更宽作用域——通过命名空间前缀选择作用域,而非直接传参。操作数是携带 TileLayout 的 Buffer / BufferRegion 值。此外还有三个隐式分派输入:执行作用域(由命名空间设定,并沿控制流追踪活跃线程集合到 inter/intra 映射与 scope_kind)、操作数布局(每个 Buffer.layout)与目标(分派表按目标类型键控,如 "cuda")。
把三者合起来
在整个 kernel 上:编排(orchestration)留在普通源码中,反复出现的硬件操作以 tile 原语形式出现。TMA 加载、tcgen05 异步 MMA、归约等构件的逐个分派讲解,见 docs/tirx/tile_primitives/ 目录下按原语组织的 walkthrough(copy、copy_async、gemm、gemm_async、elementwise、reduction、permute_layout 等,以及 tma、ldgsts、dsmem、tcgen05_cp、tcgen05_ldst 等变体子页)。
TIRx 支持什么:三大系统级能力
TIRx 作为 Kernel DSL 立即可用;同样的结构还支撑着 ML 系统正在变得重要的三件事:支持新硬件、构建 Megakernel、Agentic 内核编程。
为新硬件提供稳定的扩展边界
新硬件支持是一个分阶段过程,而不是 DSL 的重设计:特性先作为后端内建指令暴露,待使用模式重复出现后再晋升为 tile 原语。未来硬件扩展的是后端库,而不是核心语言。这正好呼应了设计哲学中"先原生内建、后原语化"的演进路径。
Megakernel 与可组合的 tile 任务
由于 TIRx 任务以编译器 IR 的形式存在,而不是独立编译的 kernel,一个 megakernel 编译器可以直接对它们进行拼接与调度——重新偏移共享内存、重命名 barrier、重新分配 warp 角色、跨任务交错流水线。从 kernel 逐发 + CUDA graph 执行(任务间保留 kernel 边界)到单个 megakernel(任务融合进一个 kernel),融合后暴露的是细粒度依赖与 kernel 内(静态或动态)调度。
Agentic 内核编程
TIRx 通过 TVM FFI 在 Python、C++ 与 Rust 之间暴露其 IR 与编译器工具。其结构化 IR 支持在 kernel 基准测试之前进行检查与良构性校验(well-formedness checks),而目标编译与执行提供后端特定行为的最终验证——编译器中介的优化表面,配合覆盖 L1–L4 的结构化搜索空间,使 TIRx 成为 Agent 可用的优化面。
快速上手:安装、验证与第一个 CUDA Kernel
安装 TIRx 编译器
TIRx 由两部分组成:
- TIRx 编译器(
tvm.tirx):随 Apache TVM 发布,即作者、IR、降低与后端基础设施。要为特定目标编译/运行,还需要启用了该目标的 TVM 构建; - 可选 Kernel 库(
tirx-kernels):一组用 TIRx 构建的现成 kernel 与基准基础设施。
环境要求:Python ≥ 3.10;对 CUDA 编程指南与捆绑 kernel,需要启用 CUDA 的 TVM 构建、NVIDIA 驱动与兼容的 CUDA toolkit——捆绑 kernel 面向 Blackwell(sm_100a),TIRx 本身也支持其他目标后端。
安装编译器(TIRx 编译器就是 tvm.tirx 模块):
pip install apache-tvm
wheel 足以检查与编写 TIRx IR。部分 CUDA 工作流还需要 NVIDIA 的 Python CUDA 绑定,可通过 apache-tvm<a href="https://link.gitcode.com/i/6b67c644ef49eebf68c9213dc912b3b6" target="_blank">cuda] 获得;该 extra 不会在 TVM 库中启用 CUDA,也不安装驱动或 toolkit。要编译运行 CUDA 示例,请使用配置了 USE_CUDA=ON 的 TVM 源码构建(参见 [docs/install/from_source.rst)。
验证安装:
python -c "import tvm, tvm.tirx; print(tvm.__version__)"
安装 Kernel 库(可选)
从 PyPI 安装最新 tirx-kernels 版本:
pip install tirx-kernels
或安装源码检出进行开发:
git clone <tirx-kernels 仓库地址> # 仓库地址见其官方发布说明
cd tirx-kernels
pip install -e .
注意:Apache TVM 与 PyTorch 是外部托管的运行时/编译器依赖,安装 tirx-kernels 不会顺带安装它们;需自行将启用 TIRx 的 TVM 放入 PYTHONPATH,并使用与系统匹配的 CUDA 版 PyTorch。个别正确性测试与参考基线需要额外的上游项目,源码检出可安装其锁定的互兼容版本:
python scripts/install_reference_dependencies.py
kernel 注册表与参考依赖集会独立于 TVM 演进,可用 python -m tirx_kernels.registry --format json 查看已安装 kernel 列表。
编写、编译、运行并检视第一个 Kernel
完整示例见 docs/tirx/native_basics/cuda/first_kernel.rst:一个块 256 线程、将向量乘以 2 的 kernel,覆盖写 → 编译 → 运行 → 检视的完整闭环:
import numpy as np
import tvm
from tvm.script import tirx as Tx
@Tx.prim_func
def scale(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() # everything below runs on the device
bx = Tx.cta_id([1]) # 1 block (blockIdx)
tx = Tx.thread_id([256]) # 256 threads per block (threadIdx)
B[tx] = A[tx] * Tx.float32(2.0)
# compile for CUDA through the TIRx pipeline -> an Executable
exe = tvm.compile(tvm.IRModule({"main": scale}),
target=tvm.target.Target("cuda"), tir_pipeline="tirx")
dev = tvm.cuda(0)
a = tvm.runtime.tensor(np.random.rand(256).astype("float32"), device=dev)
b = tvm.runtime.tensor(np.zeros(256, "float32"), device=dev)
exe(a, b) # run
print(exe.mod.imports[0].inspect_source()) # the generated CUDA C
各调用含义:
tvm.IRModule({"main": scale})把PrimFunc包成 IRModule(命名的函数集合);"main"是编译器构建的入口,也是调用符号;tvm.compile(mod, target=..., tir_pipeline="tirx")返回 Executable——编译好的 host launcher 与设备代码捆绑在一起,像函数一样调用(exe(a, b)),参数按位置匹配 kernel 参数顺序;tvm.cuda(0)是 CUDA 设备 0 的句柄;tvm.runtime.tensor(arr, device=dev)把数据放到该设备上成为 TVM tensor(NDArray);exe.mod是底层运行时Module;exe.mod.imports[0]是导入的设备(CUDA)模块,其.inspect_source()返回生成的 CUDA C。
上述 kernel 生成的 CUDA C(省略样板)为:
extern "C" __global__ void __launch_bounds__(256)
scale_kernel(float* __restrict__ A_ptr, float* __restrict__ B_ptr) {
int tx = ((int)threadIdx.x);
B_ptr[tx] = A_ptr[tx] * 2.0f;
}
每个线程写一个元素——B[tx] = A[tx] * 2.0 与生成索引的直接对应。此外,编译好的 Executable 也能直接接受 CUDA torch tensor(经 TVM FFI tensor 互操作,无需显式转换):
import torch
a = torch.rand(256, device="cuda")
b = torch.empty(256, device="cuda")
exe(a, b)
torch.testing.assert_close(b, a * 2)
深入阅读路线
按 docs/tirx/overview.rst 的指引,下一步可以按序推进:
- docs/tirx/install.rst —— 安装 TIRx 与 kernel 库;
- docs/tirx/native_basics/cuda/first_kernel.rst —— 编写并编译第一个 CUDA kernel(后续章节依次展开 functions、buffers、control_flow、threads_sync、compiling);
- docs/tirx/programming/index.rst —— 完整编程指南(核心语言、布局、tile 原语);
- docs/tirx/layout.rst 与 docs/tirx/tile_primitives.rst —— 可复用的 tensor 与 tile 抽象(含
TileLayout的 S/R/O 模型、swizzle、31 个原语目录与分派配置表); - docs/tirx/arch/index.rst —— 编译器内部(lowering pipeline、passes、codegen、tile 分派扩展点);
- docs/tirx/api/index.rst —— authoring、IR、编译器与扩展 API 签名(含
tile、tile_dispatch、cuda、ptx、trainium、layout、transform、analysis、compilation、execution、script、backend、tirx各参考页)。
若要在源码层面继续追索,可沿三条线深入:Python 作者层(python/tvm/tirx/ 的 tile_primitive.py、layout.py、exec_scope.py、compilation_pipeline.py)、C++ IR 与降低(src/tirx/ir/、src/tirx/transform/)、后端分派实现(src/tirx/backend/、src/tirx/op/),并对照 tests/python/tirx/ 下的测试用例验证行为。