cann-robotAdd a same-width vector bit reinterpretation to the TLA DSL

nav_order
10

TLA DSL Kernel API 参考

本文档介绍 TLA DSL 的 kernel 侧 Core API（通常以 import catlass.tla as tla 导入）。内容覆盖基本数据类型、计算与同步接口、片上资源管理以及调试打印。Host 侧编译 / 启动 / tensor 绑定见 Host API 参考；DLPack 接入教程见 Host Tensor 接入。

接口说明与调用示例来自各 op 源码 docstring；所有接口均须在 @tla.kernel 装饰的 kernel 函数体内调用。

基本数据类型与操作

Shape / Coord / Stride / Layout / Tensor 等前端结构化值的构造与视图，以及指针相关辅助接口。

`make_shape`

源码： catlass.core_api.make_shape

功能说明：

构造打包的 !tla.shape，分量可为嵌套 tuple。

函数原型：

tla.make_shape(*components: IndexTree) -> TlaShape

参数说明：

components（IndexTree）：shape 各维分量。zN / nZ / L0Clayout / zNUnAlign 的物理布局用嵌套 tuple。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
至少提供 1 个 shape 分量。
RowMajor / ColumnMajor：用二维 shape (M, N)。
zN / nZ / L0Clayout / zNUnAlign：在 make_layout / make_tensor 中要用嵌套物理 shape ((m0, m1), (n0, n1))。只写二维 (M, N) 不合法；请改成嵌套，或优先用 make_tensor_like(..., layoutTag=zN)（由逻辑二维 origin_shape 自动换算）。

调用示例：

# RowMajor / ColumnMajor（逻辑二维）：
shape = tla.make_shape(256, 128)

# zN 物理 shape（f16，逻辑 128x64）：
# m0=16，m1=8（=128/16）；n0=16，n1=4（=64/16）
zn_shape = tla.make_shape((16, 8), (16, 4))

`make_coord`

源码： catlass.core_api.make_coord

功能说明：

构造打包的 !tla.coord。

函数原型：

tla.make_coord(*components: IndexTree) -> TlaCoord

参数说明：

components（IndexTree）：coord 各维分量。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
至少提供 1 个 coord 分量。

调用示例：

coord = tla.make_coord(block_row, 0)

`make_stride`

源码： catlass.core_api.make_stride

功能说明：

构造打包的 !tla.stride（嵌套规则与 make_shape 相同）。

函数原型：

tla.make_stride(*components: IndexTree) -> TlaStride

参数说明：

components（IndexTree）：stride 各维分量。必填。

常见写法：

布局	典型 `make_stride(...)`	含义
RowMajor 二维 `(M, N)`	`(N, 1)`	行方向每次跨 `N` 个元素；列方向跨 1
ColumnMajor 二维 `(M, N)`	`(1, M)`	行方向跨 1；列方向每次跨 `M` 个元素
`zN` / `nZ` / …	嵌套 `((s00, s01), (s10, s11))`	与物理 `shape` 同结构；数值须匹配对应 layout

对 zN / nZ / L0Clayout / zNUnAlign：一块 C0 是 32 字节， M 方向分块大小是 16。记 每块C0元素数 = 32 // sizeof(dtype)（f16→16，f32→8）， 每分块元素数 = 每块C0元素数 * 16。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
至少提供 1 个 stride 分量。
对 zN / nZ / L0Clayout / zNUnAlign，stride 数值须匹配 layout（见示例）；make_tensor 会按 shape + layoutTag 检查。

调用示例：

# RowMajor 二维（逻辑 256x128，紧凑存放）：
stride = tla.make_stride(128, 1)

# f16 zN，逻辑尺寸 (128, 64)：
# shape = ((16, 8), (16, 4))
# stride = ((每块C0元素数, 每分块元素数),
#           (1, 向上取整到16的M * 每块C0元素数))
#        = ((16, 256), (1, 2048))
zn_stride = tla.make_stride((16, 256), (1, 2048))

# f16 nZ，同一逻辑 (128, 64)：
# shape = ((16, 8), (16, 4))
# stride = ((1, 向上取整到16的N * 每块C0元素数),
#           (每块C0元素数, 每分块元素数))
#        = ((1, 1024), (16, 256))
nz_stride = tla.make_stride((1, 1024), (16, 256))

`make_layout`

源码： catlass.core_api.make_layout

功能说明：

由 shape / stride 合成 !tla.layout（对应 tla.make_layout）。

函数原型：

tla.make_layout(shape: _Shape, stride: _Stride, *, origin_shape: _Shape | None = None, layoutTag: _LayoutTag | None = None) -> TlaLayout

参数说明：

shape（_Shape）：布局 shape，由 tla.make_shape 构造。必填。 RowMajor / ColumnMajor：二维 (M, N)。 zN / nZ / L0Clayout / zNUnAlign：嵌套 ((m0, m1), (n0, n1))。
stride（_Stride）：布局 stride，由 tla.make_stride 构造。必填。嵌套形态须与 shape 一致。
origin_shape（_Shape | None）：逻辑工作尺寸（对齐前的真实数据大小）。可选，默认 None。拷贝 / 切块按该逻辑尺寸；物理存放方式在 shape / stride。
layoutTag（_LayoutTag | None）：布局标签（如 tla.arch.RowMajor、 tla.arch.zN）。可选，默认 None（RowMajor）。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
shape / stride 须为 make_shape / make_stride 的返回值。
RowMajor / ColumnMajor 省略 origin_shape 时推断为 shape； zN / nZ / L0Clayout / zNUnAlign 则从 shape=((m0,m1),(n0,n1)) 推断为 (m0*m1, n0*n1)。
不要给 zN / nZ / L0Clayout / zNUnAlign 配普通二维 shape，检查会失败。请写嵌套物理 shape，或用 make_tensor_like(ptr, like, layoutTag=...) 由 like.origin_shape 自动换算。

调用示例：

# RowMajor 二维：
layout = tla.make_layout(
    tla.make_shape(256, 128),
    tla.make_stride(128, 1),
    layoutTag=tla.arch.RowMajor,
)

# 显式 f16 zN（逻辑 128x64 → 嵌套物理 + 二维 origin）：
# 前：逻辑 ND tile 为 (128, 64)。
zn = tla.make_layout(
    tla.make_shape((16, 8), (16, 4)),
    tla.make_stride((16, 256), (1, 2048)),
    origin_shape=tla.make_shape(128, 64),  # 拷贝/切块用的逻辑尺寸
    layoutTag=tla.arch.zN,
)
# 后：layout.shape 为 zN 打包；layout.origin_shape 仍为 (128, 64)。

`make_layout_with_tag`

源码： catlass.core_api.make_layout_with_tag

功能说明：

由扁平二维逻辑 shape、元素类型与 layout tag 直接合成 !tla.layout （前端重映射物理树后对应 tla.make_layout）。

make_layout_with_tag 直接采用调用方给出的 extent，因此片上 tile 可以大于为其供数的 GM tile（例如 MX mmad 将 K 向上取整到 64）。

函数原型：

tla.make_layout_with_tag(shape: tuple, dtype: Any, layoutTag: _LayoutTag | None = None) -> TlaLayout

参数说明：

shape（tuple）：扁平二维逻辑 extent (rows, cols)。每个叶子为 int 或运行时 Numeric（动态叶子）。必填。
dtype（Numeric 子类）：元素类型；决定重映射物理树的 C0/分块几何。必填。
layoutTag（_LayoutTag | None）：布局标签（如 tla.arch.zN）。可选，默认 None（RowMajor）。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
仅用于片上 tensor 布局：合成后的 layout 应通过 tla.make_tensor(ptr, layout) 落到片上指针，而不是绑定 GM Host 内存。
shape 必须是扁平二元组；嵌套树与 None 叶子会被拒绝——整个 extent 由调用方拥有。
结果 layout 的 origin shape 等于 shape（对齐后的 extent）；配合 tla.make_tensor(ptr, layout) 落到片上指针。
仅片上 tag：zZMxScale / nNMxScale 要求元素类型 tla.Float8E8M0 （其 C0 由 e8m0 格式固定为 2 元素 / 32 字节）。GM 侧 MxScale tag （RowMajorMxScaleA、ColMajorMxScaleA、RowMajorMxScaleB、 ColMajorMxScaleB）会被拒绝。

调用示例：

# fp8 zN tile：M 运行时裁剪，K 向上取整到 64：
lay = tla.make_layout_with_tag((m_valid, k_l0), dtype_a, tla.arch.zN)
t_l1a = tla.make_tensor(l1a, lay)

`tile_view`

源码： catlass.core_api.tile_view

功能说明：

在 !tla.tensor 源上按 tile 坐标粒度创建 tile 视图。

函数原型：

tla.tile_view(source: Tensor, shape: _Shape, coord: _Coord) -> TlaTensor

参数说明：

source（Tensor）：源 !tla.tensor。必填。
shape（_Shape）：tile 形状，由 tla.make_shape 构造。必填。
coord（_Coord）：tile 坐标，由 tla.make_coord 构造（tile 粒度）。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
coord 以 tile 粒度传入，前端会按 shape 换算为元素偏移。

调用示例：

tile = tla.tile_view(
    source, tla.make_shape(256, 128), tla.make_coord(block_row, 0)
)

`get_tile`

源码： catlass.core_api.get_tile

功能说明：

从 tensor 抽取子 tile，基于源的底层指针用 tla.make_tensor 构造新的 !tla.tensor。

返回的 tensor 共享源的 buffer 几何——stride 树原样透传——并携带：

coord：coord + source.coord（各维元素偏移）；
origin_shape：相对源 origin_shape 裁剪后的 shape （各维 min(shape[d], origin[d] - coord[d])），保证 tile 不会越过源的逻辑范围；
shape：按裁剪后的 extent 重新生成的物理打包（zN/nZ 与 make_layout_with_tag 相同的分块分解；RowMajor/ColumnMajor 则为 extent 本身）。

下游看到的是该 tile 的绝对坐标与自身逻辑范围；例如对结果调用 Tensor.fill 只会填充这个 tile。

函数原型：

tla.get_tile(tensor: Tensor, coord: TlaCoord, shape: TlaShape) -> TlaTensor

参数说明：

tensor（Tensor）：源 !tla.tensor。必填。
coord（TlaCoord）：由 tla.make_coord 得到的起点，相对源的扁平二维元素偏移。必填。
shape（TlaShape）：由 tla.make_shape 得到的请求 tile extent，扁平二维。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
coord 偏移必须落在源的 origin_shape 内——裁剪只缩短 extent，不会钳制偏移。
支持的 layout tag 与 tla.make_tensor 一致（RowMajor、ColumnMajor、 zN、nZ、L0Clayout、zNUnAlign）。

调用示例：

# 将 L1 A tile 的 K-pad 尾部清零（见 Tensor.fill）：
pad = tla.get_tile(t_l1a, tla.make_coord(0, k_valid),
                   tla.make_shape(m, k_l0 - k_valid))
pad.fill(0)

`make_tensor`

源码： catlass.core_api.make_tensor

功能说明：

由显式指针、layout 与可选 coord 构造 !tla.tensor。

函数原型：

tla.make_tensor(ptr: Pointer, layout: TlaLayout, coord: CoordLike | None = None) -> TlaTensor

参数说明：

ptr（Pointer）：底层数据指针（!tla.ptr）。必填。
layout（TlaLayout）：tensor 布局，由 tla.make_layout 构造。必填。
coord（CoordLike | None）：可选起始坐标；缺省视为零坐标。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
指针、layout、coord 须匹配目标地址空间与 dtype。
coord 缺省为零坐标，秩与 layout 一致（秩 2 → make_coord(0, 0)，秩 1 → make_coord(0)）。元素类型与地址空间来自 ptr 的 !tla.ptr；layout tag、shape、stride、origin 来自 !tla.layout 操作数（未给 origin_shape 时 origin 默认为 shape）。
Lowering 支持 RowMajor、ColumnMajor、zN、nZ、L0Clayout、zNUnAlign。对 zN / nZ / L0Clayout / zNUnAlign，物理 shape / stride 为嵌套 2×2，逻辑 coord / origin_shape 仍是二维 (M, N)。若 make_layout 省略 origin_shape，则从物理 shape 推断逻辑尺寸（例如 (m0*m1, n0*n1)）。
完整编译要求 ptr 具备底层存储；可运行 kernel 中片上指针的推荐形式是 allocate（可选再经 recast_ptr）。

调用示例：

tensor = tla.make_tensor(ptr, layout, coord=tla.make_coord(0, 0))

`make_tensor_like`

源码： catlass.core_api.make_tensor_like

功能说明：

按参考 tile 的结构化元数据，在给定指针上构造同形态 tensor。

函数原型：

tla.make_tensor_like(ptr: Pointer, like: Tensor, layoutTag: _LayoutTag | None = None) -> TlaTensor

参数说明：

ptr（Pointer）：目标数据指针。必填。
like（Tensor）：参考 tile，提供结构化 tensor 元数据。必填。
layoutTag（_LayoutTag | None）：覆盖参考 tile 的布局标签。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
参考 tile 须提供可用的结构化 tensor 元数据。
元素类型来自 ptr 的 !tla.ptr 指向类型；仅接受片上目标指针。

调用示例：

dst = tla.make_tensor_like(ptr, like=src_tile, layoutTag=tla.arch.RowMajor)

`make_ptr`

源码： catlass.core_api.make_ptr

功能说明：

由整型位型经 tla.inttoptr 构造指针。

函数原型：

tla.make_ptr(dtype: type[Numeric] | None, value: int | mlir_ir.Value | Numeric, mem_space: AddressSpace = AddressSpace.gm, *, assumed_align: int | None = None) -> Pointer

参数说明：

dtype（type[Numeric] | None）：指针指向的元素类型；None 表示 Int8。可选，默认 None。
value（int | mlir_ir.Value | Numeric）：地址值（整数、mlir Value 或 Numeric）。必填。
mem_space（AddressSpace）：指针所在地址空间。可选，默认 AddressSpace.gm。
assumed_align（int | None）：假定对齐字节数。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
整型地址位宽须与目标 mem_space 匹配。

调用示例：

ptr = tla.make_ptr(tla.Float16, addr, mem_space=tla.AddressSpace.gm)

`recast_ptr`

源码： catlass.core_api.recast_ptr

功能说明：

仅改变 !tla.ptr 的逻辑元素类型（不做 swizzle）。

函数原型：

tla.recast_ptr(ptr: Pointer, *, dtype: type[Numeric]) -> Pointer

参数说明：

ptr（Pointer）：待重解释的指针。必填。
dtype（type[Numeric]）：新的元素类型。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
仅改变逻辑元素类型，不改变地址与 swizzle。

调用示例：

ptr_f32 = tla.recast_ptr(ptr_f16, dtype=tla.Float32)

标量 Numeric

Numeric 是 TLA DSL 在 @tla.kernel 内使用的标量类型与值的基类。具体类型包括整数（tla.Int8 / Int16 / Int32 / Int64 及无符号变体）、浮点（tla.Float16 / BFloat16 / Float32，以及更窄格式）和 tla.Bool。用类型构造值，例如 tla.Int32(0)、tla.Float32(1.5)。

循环下标、坐标，以及会在运行时 if / tla.range / while 中更新的单元素状态，请使用 Numeric 值。Python 字面量用 as_numeric 提升；改类型用 Numeric.to；按位宽重解释用 Numeric.bitcast。

约束说明：

优先使用具体类型（Int32、Float32 等）。抽象基类 Numeric / Integer / Float 不可直接构造。
参与设备侧控制流或计算时，须在 @tla.kernel 函数体内使用。
在运行时 if / tla.range / while 中对名字重新赋值时，该值须是 Numeric （由 as_numeric 或具体类型如 tla.Int32(...) 得到）。普通 Python int / float / bool 无法作为运行时状态跨过上述控制流。

`Numeric.to`

源码： catlass.base_dsl.typing.Numeric.to

功能说明：

将标量 Numeric 转换为另一种具体类型。

round_mode 选择浮点转整数（以及部分浮点转浮点）的舍入方式： ScalarRoundMode.NEAREST_EVEN / NEAREST_AWAY / FLOOR / CEIL / ODD。省略（或 TRUNC）时，浮点转整数向零截断。

函数原型：

Numeric.to(dtype: Any, *, round_mode: Any = None) -> Any

参数说明：

dtype（type[Numeric] | type[int] | type[float] | type[bool]）：目标类型。具体 Numeric 子类（如 Int32、Float32）得到另一个 Numeric；传入 Python int / float / bool 时，若值仍是 Host 常量，则提取 Host 侧 Python 标量。必填。
round_mode（ScalarRoundMode | None）：可选标量舍入模式。可选，默认 None。

约束说明：

优先在 @tla.kernel 函数体内调用。
产出 DSL 标量时，dtype 须为具体类型（如 Int32 / Float32），不能是抽象的 Integer / Float / Numeric。
此处使用 tla.params.ScalarRoundMode；不要传入 tla.params.RoundMode。
不支持的源/目标组合会抛出 TypeError。

调用示例：

@tla.kernel
def kernel(n: int) -> None:
    x = tla.as_numeric(n).to(tla.Int32)
    y = tla.Float32(1.5).to(
        tla.Int32, round_mode=tla.params.ScalarRoundMode.FLOOR
    )
    tla.make_coord(x, y)

`Numeric.bitcast`

源码： catlass.base_dsl.typing.Numeric.bitcast

功能说明：

将标量 Numeric 的位型重新解释为相同位宽的另一种具体类型（不做数值转换）。

函数原型：

Numeric.bitcast(dtype: type['Numeric']) -> 'Numeric'

参数说明：

dtype（type[Numeric]）：相同位宽的具体目标类型。必填。

约束说明：

优先在 @tla.kernel 函数体内调用。
dtype 须为具体 Numeric，且与源值位宽相同；否则抛出 TypeError / ValueError。
同类型 bitcast 为 no-op，返回 self。

调用示例：

bits = tla.Float32(1.0).bitcast(tla.Int32)

`as_numeric`

源码： catlass.base_dsl.typing.as_numeric

功能说明：

将 Python 标量转换为 DSL Numeric。

在运行时控制流（if / tla.range / while / 展开的 DSL with 区域）中更新之前，或从字面量组装少量固定运行时标量 list/tuple 时，请调用本接口。

映射规则：

已是 Numeric 的值原样返回；
bool → Bool；
落在有符号 32 位范围内的 int → Int32，否则 → Int64；
float → Float32。

函数原型：

tla.as_numeric(obj: Any) -> Numeric

参数说明：

obj（bool | int | float | Numeric）：Python 标量或已有 Numeric。必填。

约束说明：

结果用作运行时状态（控制流重绑定、循环边界等）时，优先在 @tla.kernel 函数体内调用。
也可在 Host 侧从 Python 标量构造，用于 staging。
不接受用户自定义对象与非标量容器；无法转换时抛出 ValueError。

调用示例：

@tla.kernel
def kernel(limit: int) -> None:
    index = tla.as_numeric(0)
    if limit > 0:
        index = index + 1
    tla.make_coord(index, 0)

`Float.sqrt`

源码： catlass.base_dsl.typing.Float.sqrt

功能说明：

标量浮点平方根。

对应 tla.sqrt 的标量形态。在 tla.vec.func(mode="simt") 内按线程执行；在 kernel 其他位置（含 cube / SIMD vector 区域与 kernel 函数体）走核内标量数学路径。

函数原型：

Float.sqrt() -> 'Float'

参数说明：

（除 self 外无额外参数）

约束说明：

设备侧值须在 @tla.kernel 函数体内调用。
在非 mode="simt" 时仅支持 Float32（Float16 / BFloat16 抛 TypeError）；请先 .to(tla.Float32)，或在 tla.vec.func(mode="simt") 内调用。

调用示例：

@tla.kernel
def kernel() -> None:
    r = tla.Float32(4.0).sqrt()
    tla.make_coord(r.to(tla.Int32), 0)

数据搬运

片上与全局内存之间的 tensor 拷贝，以及 UB 寄存器 load/store。

`copy`

源码： catlass.core_api.copy

功能说明：

在 tile 之间拷贝数据。硬件通路由 src/dst 地址空间决定（vector：GM↔UB、UB→L1、 UB→UB；cube：GM→L1、L1→L0A/L0B、L0C→GM|UB|L1）。 UB→UB 一律走专用的 MOV.UB.TO.UB 块搬运，因此支持所有元素宽度（含 1 字节类型）与任意行长度。该搬运以 32 字节块为单位计数，所以当每行不是 32 字节块的整数倍时，行长度会向上取整，该行自身的 32 字节对齐填充也随之一起搬运。因此有两种几何形状会被拒绝，而不会被拷贝：一是起始地址不在 32 字节边界上的 tile（子块视图可能产生这种情况）；二是行间距不足以容纳取整后整行的多行 tile，此时取整后的行会越界写入下一行。目的 tile 打 ColumnMajor tag 的 UB→UB 拷贝是转置：两侧 tile 带同样的逻辑形状 (M, N)，落到内存里的是 (N, M) 的转置结果，与 L0C→GM、L0C→UB 表达转置的方式一致。底层由 VNCHWCONV（vector 单元原生的转置指令）实现，它一次搬运 16 行 × C0 列的整块数据，C0 为一个 32 字节 DataBlock 内的元素个数（4 / 2 / 1 字节类型分别为 8 / 16 / 32）；1 字节类型需要四次调用才能覆盖其 32×32 的块。因此 tile 的形状必须是整数个这样的块：16 行 × C0 列，1 字节类型为 32 行 × 32 列。两侧 layout tag 选择格式转换（例如 ND→zN）。

vector 通路支持的元素类型：

通路	源 layout → 目的 layout	元素类型
GM → UB	`RowMajor` → `RowMajor`	`f32`、`f16`、`bf16`、`i32`、`i16`、`i8`、`f8e4m3fn`、`f8e5m2`
UB → GM	`RowMajor` → `RowMajor`	同上
UB → UB	`RowMajor` → `RowMajor`	`f32`、`f16`、`bf16`、`i32`、`i16`、`i8`、`f8e4m3fn`、`f8e5m2`
UB → UB	`RowMajor` → `ColumnMajor`（转置）	同上
UB → L1	`RowMajor` → `zN`	`f32`、`f16`、`bf16`、`i8`、`f8e4m3fn`、`f8e5m2`
UB → L1	`zN` → `zN`	同上
UB → L1	`zNUnAlign` → `zN`	同上

UB → L1 的目的 layout 只能是 zN；没有以 UB 为源、nZ 为目的的通路。i16 / i32 只有 GM↔UB 与 UB→UB，没有 UB→L1。

zN 源的 UB tile 需要先在 UB 里按 zN 摆好：用 BlockStoreParams 的带 stride block store 把每行分块写入打了 zN tag 的 UB view（见 examples/end_to_end/basic_mixed/basic_mixed_store_zN.py 与 basic_mixed_store_zNUnAlign.py，两者都用 --dtype 跑遍该通路支持的全部元素类型）。分块长度按元素类型算：一个 vector register 是 256 字节，vsstb 一次搬满它的 8 个 DataBlock，所以一块是 256 / sizeof(T) 个元素。8 位类型（i8 / fp8）的 block store 与 GM↔UB、UB→L1 拷贝一样，在 bc 层按 int8_t 实例化：搬运只用到宽度与 stride，不解释元素类型，而 AIV 后端对 fp8 没有标量语义。

拷贝 / 切块大小按各 tile 的逻辑 origin_shape（不是嵌套物理 shape）。物理 shape / stride 描述这些逻辑元素如何存放（凑齐对齐长度、zN 打包等）。

函数原型：

tla.copy(dst: Tensor, src: Tensor, params: CopyParams | None = None, *, scale: Tensor | None = None) -> None

参数说明：

dst（Tensor）：目的 tile。必填。
src（Tensor）：源 tile。必填。
params（CopyParams | None）：可选通路参数（CopyL0C2DstParams、CopyUbToGmParams / atomic 等）。默认 None。
MX scale tile（目的为 zZMxScale / nNMxScale）在 L1 上按整行字节平铺，源 tile 须覆盖缓冲区整行；按行堆叠各 chunk 的 scale block，不要沿列切宽 buffer。仅在行 pitch 为编译期常量时可检查；layout 动态的 tensor 无法在编译期校验。
scale（Tensor | None）：L1 上的 OCP e8m0 共享指数 tile（沿 K 每 32 个元素一份），使 L1→L0A/L0B 变为 microscaling（MX）load，并下沉为 tla.copy_mx。因 MLIR 无 e8m0 类型，以 i8/u8 存储；目的为 L0A 时 tag tla.arch.zZMxScale，为 L0B 时 tag tla.arch.nNMxScale。默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
scale 仅对 L1→L0A/L0B 通路有效；由此加载的 tile 随后须由 tla.mmad / tla.mmad_mx 消费。scale 由 load 消费，而非 matmul 参数——硬件 mad_mx 没有 scale 操作数，MX 关联在操作数进入 L0 时建立（对齐 AscendC 五参数 LoadData 重载）。
须在 tla.cube() 或 tla.vector() 内调用（上述 cube 通路在 cube()， vector 通路在 vector()）。
整 tile DMA 使用 tla.copy。寄存器级 UB 非对齐访问请改用 tensor.load / tensor.store，并传入 UnalignLoadParams / UnalignStoreParams。
尺寸未按 32 字节对齐时： C0 为 32 字节。ND GM↔UB 时，优先让主导维的字节数是 32 的倍数（如 RowMajor f16 选 N 使 N % 16 == 0）。若真实数据大小做不到这一点，请保持 origin_shape 为真实逻辑尺寸，并把物理 layout 放大到对齐后的尺寸，或改用上方非对齐寄存器 load/store。zN 在 M 不是 16 的整数倍时，用 tla.arch.zNUnAlign 而非 zN。

调用示例：

# --- 1) 对齐 GM ↔ UB（RowMajor，满足 32 字节对齐） ---
# 前：x_gm[i, j] 为 ND 数据；x_ub 为空。origin_shape==(M, N)。
with tla.vector():
    tla.copy(dst=x_ub, src=x_gm)
    # 后：对 origin_shape 内所有逻辑 (i, j)，x_ub[i, j] == x_gm[i, j]。
    tla.copy(dst=y_gm, src=y_ub)

# --- 2) ND → zN：GM RowMajor → L1 zN（排布变化） ---
# 前（逻辑）：gm_a.origin_shape==(128, 64)，RowMajor；元素 (r, c)
#   的 ND 偏移为 r*64+c。
# 后（L1 物理）：l1_a 使用嵌套 zN shape/stride，同一逻辑 (r, c) 按 zN 存放；
#   l1_a.origin_shape 仍为 (128, 64)。
l1_a = tla.make_tensor_like(l1_ptr, gm_a, layoutTag=tla.arch.zN)
with tla.cube():
    tla.copy(dst=l1_a, src=gm_a)

# 不用 make_tensor_like 时的显式 zN（同一逻辑 128x64 f16）：
l1_a = tla.make_tensor(
    l1_ptr,
    tla.make_layout(
        tla.make_shape((16, 8), (16, 4)),
        tla.make_stride((16, 256), (1, 2048)),
        origin_shape=tla.make_shape(128, 64),
        layoutTag=tla.arch.zN,
    ),
)

# --- 3) M 不是 16 的倍数：zNUnAlign ---
# 前：rows 可能为运行期值，且不是 16 的倍数。
l1_unalign = tla.make_tensor_like(l1_ptr, gm_tile, layoutTag=tla.arch.zNUnAlign)
with tla.cube():
    tla.copy(dst=l1_unalign, src=gm_tile)

# 相关（寄存器路径，不是 tla.copy）：UB ↔ vector 寄存器非对齐访问
#   with tla.vec.func(mode="simd"):
#       x_reg = x_ub.load(tla.params.UnalignLoadParams())
#       y_ub.store(y_reg, tla.params.UnalignStoreParams())

无 scale 的 Cube 拷贝通路，tla.copy(dst, src, scale=None)

`src_addr`	`src_layout`	`dst_addr`	`dst_layout`	`dtypes`
`gm`	`RowMajor`	`l1`	`zN`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`,`f4e2m1`,`f4e1m2`
`gm`	`ColumnMajor`	`l1`	`nZ`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`,`f4e2m1`,`f4e1m2`
`gm`	`RowMajorMxScaleA`	`l1`	`zZMxScale`	`f8e8m0`
`gm`	`ColMajorMxScaleA`	`l1`	`zZMxScale`	`f8e8m0`
`gm`	`RowMajorMxScaleB`	`l1`	`nNMxScale`	`f8e8m0`
`gm`	`ColMajorMxScaleB`	`l1`	`nNMxScale`	`f8e8m0`
`l1`	`zN`	`l0a`	`zN`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`
`l1`	`nZ`	`l0a`	`zN`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`
`l1`	`zN`	`l0b`	`nZ`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`
`l1`	`nZ`	`l0b`	`nZ`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`

带 scale 的 Cube 拷贝通路（供 tla.mmad_mx），即 tla.copy(dst=l0a|l0b, src=l1, scale=scale)；scale 仅支持 f8e8m0，且 scale 的 l1->l0 不支持转置。

`src_addr`	`src_layout`	`dst_addr`	`dst_layout`	`scale_addr`	`scale_layout`	`dtypes`
`l1`	`zN`	`l0a`	`zN`	`l1`	`zZMxScale`	`f8e4m3fn`,`f8e5m2`,`f4e2m1`,`f4e1m2`
`l1`	`nZ`	`l0a`	`zN`	`l1`	`zZMxScale`	`f8e4m3fn`,`f8e5m2`,`f4e2m1`,`f4e1m2`
`l1`	`zN`	`l0b`	`nZ`	`l1`	`nNMxScale`	`f8e4m3fn`,`f8e5m2`,`f4e2m1`,`f4e1m2`
`l1`	`nZ`	`l0b`	`nZ`	`l1`	`nNMxScale`	`f8e4m3fn`,`f8e5m2`,`f4e2m1`,`f4e1m2`

Cube fixpipe 通路：从 L0C 拷到 GM/L1/UB。 fixpipe 支持随路 quant 与 relu；quant 模式支持 NO_QUANT、PER_TENSOR、PER_CHANNEL。规则：

链路为 (l0c acc) → quant（可选）→ relu（可选）→ 写出到 dst。
NO_QUANT 含纯数据类型转换，如 f32→f16、f32→bf16。
目的为 UB 时额外有 split_mode：nosplit（NO_SPLIT_VEC_0、NO_SPLIT_VEC_1）与 split（SPLIT_M、SPLIT_N）。
目的为 (ub, ColumnMajor) 时仅支持 nosplit。
UB 的 split 模式下禁用任何 quant_mode/relu，也不做纯 cast，仅允许 f32→f32 与 i32→i32。

`dst`	`dst_layout`	`split_mode`	`quant_mode`	`relu`	`src_dtype`:`dst_dtype`
`gm`	`RowMajor`	`-`	`NO_QUANT`	`False`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`gm`	`ColumnMajor`	`-`	`NO_QUANT`	`False`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`l1`	`zN`	`-`	`NO_QUANT`	`False`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`ub`	`RowMajor`	`nosplit`	`NO_QUANT`	`False`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`ub`	`RowMajor`	`split`	`NO_QUANT`	`False`	`f32`: `f32` `i32`: `i32`
`ub`	`ColumnMajor`	`nosplit`	`NO_QUANT`	`False`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`gm`	`RowMajor`	`-`	`NO_QUANT`	`True`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`gm`	`ColumnMajor`	`-`	`NO_QUANT`	`True`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`l1`	`zN`	`-`	`NO_QUANT`	`True`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`ub`	`RowMajor`	`nosplit`	`NO_QUANT`	`True`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`
`ub`	`ColumnMajor`	`nosplit`	`NO_QUANT`	`True`	`f32`: `f32`,`f16`,`bf16` `i32`: `i32`

Vector 拷贝通路

`src_addr`	`src_layout`	`dst_addr`	`dst_layout`	`dtypes`
`gm`	`RowMajor`	`ub`	`RowMajor`	`f32`,`f16`,`bf16`,`i32`,`i16`,`i8`,`f8e4m3fn`,`f8e5m2`
`ub`	`RowMajor`	`gm`	`RowMajor`	`f32`,`f16`,`bf16`,`i32`,`i16`,`i8`,`f8e4m3fn`,`f8e5m2`
`ub`	`RowMajor`	`ub`	`RowMajor`	`f32`,`f16`,`bf16`,`i32`,`i16`,`i8`,`f8e4m3fn`,`f8e5m2`
`ub`	`RowMajor`	`ub`	`ColumnMajor`	`f32`,`f16`,`bf16`,`i32`,`i16`,`i8`,`f8e4m3fn`,`f8e5m2`
`ub`	`RowMajor`	`l1`	`zN`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`
`ub`	`zN`	`l1`	`zN`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`
`ub`	`zNUnAlign`	`l1`	`zN`	`f32`,`f16`,`bf16`,`i8`,`f8e4m3fn`,`f8e5m2`

`Tensor.load`

源码： catlass.tla.tensor._Tensor.load

功能说明：

将本 UB tensor tile 载入 vector 或 mask SSA（tile.load）。

函数原型：

tile.load(params: LoadParams | None = None) -> MaskSSA | VectorSSA | tuple[VectorSSA, VectorSSA]

参数说明：

params（LoadParams | None）：载入模式。None / NormalLoadParams / UnalignLoadParams / BlockLoadParams → VectorSSA（DIST_DINTLV_B32 时可为二元组）；MaskLoadParams → MaskSSA。 NormalLoadParams.load_dist 选择分发模式：norm（默认）、 brc_b32（单个 b32 元素广播到全部 lane）、dintlv_b32（f32 解交织，双返回值）、us_b8 / us_b16（2 倍上采样）、brc_b16（单个 b16 元素广播）、unpack_b16（b16 零扩展到双倍宽度）、e2b_b16 / e2b_b32 （元素到 DataBlock 广播）、blk（一个 32 字节 DataBlock 广播到全部 8 个）。 BlockLoadParams 为跨步 DataBlock 收集：一条指令收集 8 个 DataBlock，块头间隔 block_stride 个 DataBlock（32B 单位）；block_stride == 0 时将首个 DataBlock 复制到全部 8 槽；post_update_stride 为编译期地址预偏移，单位 32B DataBlock。可选，默认 None。 UnalignLoadParams → VectorSSA（DIST_DINTLV_B32 时可为二元组）； MaskLoadParams → MaskSSA。可选，默认 None。 MaskLoadParams.load_dist 可为 DIST_NORM（默认，bit-packed 掩码载入）、 DIST_US（bit 上采样）或 DIST_DS（bit 下采样）。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；源 tile 须位于 UB。
Mask 载入 DIST_NORM 要求 UB 元素类型为 1/2/4 字节标量。
分发模式限定元素宽度：us_b8 要求 i8/u8；brc_b16 / us_b16 / unpack_b16 / e2b_b16 要求 2 字节（f16/bf16/i16/u16）；e2b_b32 要求 4 字节（f32/i32/u32）；dintlv_b32 要求 f32；blk 适用于任意元素宽度。
BlockLoadParams 要求 2/4 字节元素类型（f32/f16/bf16/i32/u32/i16/u16）； block_stride 与 post_update_stride 须在 [0, 65535] 范围内。
DIST_US / DIST_DS：UB 元素类型可为任意 b8/b16/b32/b64 标量。元素类型仅用于 UB 寻址；掩码位布局与元素宽度无关。静态 tile shape 乘积属于 {32,64,128,256} 时作为 !tla.mask<N> 的 N；否则 N=256。
掩码载入字节偏移对齐（UB 字节地址 base + offset×sizeof(T)）： DIST_NORM → VL/8；DIST_US → VL/16；DIST_DS → min(32, VL/4)。 VL=256 时为 32B / 16B / 32B。

调用示例：

with tla.vec.func(mode="simd"):
    x_reg = x_ub.load()
    x_unalign = x_ub.load(tla.params.UnalignLoadParams())
    x_blk = x_ub.load(tla.params.NormalLoadParams(
        load_dist=tla.params.LoadDist.DIST_BLK))
    x_gather = x_ub.load(tla.params.BlockLoadParams(block_stride=4))
    preg = mask_ub.load(
        tla.params.MaskLoadParams(load_dist=tla.params.MaskLoadDist.DIST_DS)
    )
    y = tla.where(preg, x_reg, min_reg)

`Tensor.store`

源码： catlass.tla.tensor._Tensor.store

功能说明：

将 vector 或 mask SSA 写回本 UB tensor tile（tile.store）。

函数原型：

tile.store(value: VectorSSA | MaskSSA, params: StoreParams | None = None, *, mask: MaskSSA | None = None) -> None

参数说明：

value（VectorSSA | MaskSSA）：要写入的 VectorSSA 或 MaskSSA。必填。
params（StoreParams | None）：写回模式。None / NormalStoreParams / UnalignStoreParams / BlockStoreParams → vector 写回；MaskStoreParams → mask 写回。 NormalStoreParams.store_dist 另可选 first-element 模式：first_element_b8 / first_element_b16 / first_element_b32——仅将源寄存器 lane 0 写入 tile 基址，后缀限定写出的元素字节宽度。可选，默认 None。
mask（MaskSSA | None）：vector 写回的可选谓词；与 MaskStoreParams 及 first-element 模式均不可同时使用。默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；目标 tile 须位于 UB。
first-element 模式要求被写值与目标 tile 的元素宽度匹配后缀（b8 → 1 字节，b16 → 2 字节，b32 → 4 字节）；传入谓词 mask 会报错。

调用示例：

with tla.vec.func(mode="simd"):
    y_ub.store(y_reg)
    y_ub.store(y_reg, tla.params.UnalignStoreParams())
    y_ub.store(y_reg, tla.params.NormalStoreParams(
        store_dist=tla.params.StoreDist.DIST_FIRST_ELEMENT_B16))

矩阵运算

Cube 侧矩阵乘加（tla.mmad / tla.mmad_mx）。

`mmad`

源码： catlass.core_api.mmad

功能说明：

在 TLA tile 上执行矩阵乘累加。

函数原型：

tla.mmad(acc: Tensor, lhs: Tensor, rhs: Tensor, init_c: bool | Bool | None = None, unit_flag: IndexLike | None = None, compute_order: ComputeOrder = ComputeOrder.M_FIRST, hf32_mode: HF32Mode = HF32Mode.HF32_DISABLE, **extra_kwargs: object) -> None

参数说明：

acc（Tensor）：累加器 / 输出 tile（通常在 L0C）。必填。
lhs（Tensor）：左矩阵 tile（通常在 L0A）。必填。
rhs（Tensor）：右矩阵 tile（通常在 L0B）。必填。
init_c（bool | Bool | None）：是否先清零累加器；省略时默认为 False。可选，默认 None。
unit_flag（IndexLike | None）：unit flag 控制位；省略时默认为 0。可选，默认 None。
compute_order（ComputeOrder）：M/N 计算方向优先级；默认 M_FIRST。
hf32_mode（HF32Mode）：FP32 操作数在 L0A/L0B 上、矩阵乘之前的 HF32 舍入模式。可选，默认 HF32_DISABLE。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 内调用；acc/lhs/rhs 须为匹配的 L0 tile。
支持的元素类型通路包括 f16/bf16/f32，以及任意 f8e4m3fn / f8e5m2 操作数配对，累加到 L0C 上的 fp32。
init_c 仅接受 Python bool 或 i1 SSA 值。
不接受未知关键字参数；传入则报错。

调用示例：

# 前：l0a / l0b 为当前 K 切片；l0c 为 L0C 上的累加器。
with tla.cube():
    tla.mmad(l0c, l0a, l0b, init_c=True, unit_flag=0b11)
    # 后：l0c 累加 lhs@rhs（init_c=True 时先清零）。

`mmad_mx`

源码： catlass.core_api.mmad_mx

功能说明：

在 TLA tile 上执行 microscaling（MX）矩阵乘累加。

与 tla.mmad 分开，因为 Cube 有专用 mad_mx 指令（AscendC 暴露为 asc_mmad_mx）。

与该指令一样，本接口不接受 scale 参数。lhs/rhs 必须先通过带 scale 操作数的 tla.copy 加载，从而把 e8m0 block 附着到 L0 tile；硬件再从 L0 tile 旁路缓冲读取 scale。传入未按此方式加载的操作数会报错；把 microscaling 操作数传给 tla.mmad 同样会报错——两个 op 不可互换，操作数本身也无法区分属于哪条路径。

函数原型：

tla.mmad_mx(acc: Tensor, lhs: Tensor, rhs: Tensor, init_c: bool | Bool | None = None, unit_flag: IndexLike | None = None, compute_order: ComputeOrder = ComputeOrder.M_FIRST, **extra_kwargs: object) -> None

参数说明：

acc（Tensor）：累加器 / 输出 tile，位于 L0C，始终为 fp32。必填。
lhs（Tensor）：左矩阵 tile，位于 L0A。必填。
rhs（Tensor）：右矩阵 tile，位于 L0B。必填。
init_c（bool | Bool | None）：是否先清零累加器；省略时默认为 False。可选，默认 None。
unit_flag（IndexLike | None）：unit flag 控制位；省略时默认为 0。可选，默认 None。
compute_order（ComputeOrder）：M/N 计算方向优先级；默认 M_FIRST。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 内调用；acc/lhs/rhs 须为匹配的 L0 tile。
操作数须为 f8e4m3fn/f8e5m2 配对，或 f4e2m1/f4e1m2 配对；同一对内两种格式可混用，累加器为 fp32。
两个操作数都必须经 tla.copy(..., scale=...) 加载。

调用示例：

# 前：l1a/l1b 为 fp8 操作数，l1sa/l1sb 为其 e8m0 scale block。
with tla.cube():
    tla.copy(l0a, l1a, scale=l1sa)   # scale 随 load，不在 matmul 参数里
    tla.copy(l0b, l1b, scale=l1sb)
    tla.mmad_mx(l0c, l0a, l0b, init_c=True)
    # 后：l0c 累加 microscaled 的 lhs@rhs。

Vector 运算

寄存器 Vector 路径上的计算与 mask 操作，通常须在 tla.vec.func() 内调用。

Mask 计算

Mask 创建与尾块更新。

`create_mask`

源码： catlass.core_api.create_mask

功能说明：

按固定 pattern（tla.mask.* token）创建 vector mask。

函数原型：

tla.create_mask(*, pattern: _MaskPattern | str | None = None, dtype: DTypeLike = Float32) -> MaskSSA

参数说明：

pattern（_MaskPattern | str | None）：掩码 pattern token 或其名字字符串。运行时必填（传 None 会报错）。token 挂在 tla.mask 下（如 tla.mask.ALL、tla.mask.VL8）：

Pattern	含义
`ALL`	全部元素有效
`ALLF`	全部元素无效
`VL1` / `VL2` / `VL3` / `VL4`	最低 1 / 2 / 3 / 4 个元素有效
`VL8` / `VL16` / `VL32` / `VL64` / `VL128`	最低 8 / 16 / 32 / 64 / 128 个元素有效
`M3`	下标为 3 的倍数的元素有效
`M4`	下标为 4 的倍数的元素有效
`H`	最低一半元素有效
`Q`	最低四分之一元素有效

dtype（DTypeLike）：与掩码关联的元素类型（也决定一条 vector 能放多少元素： 256 字节 / 元素大小）。可选，默认 Float32。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；pattern 必填。
接受 mask= 的接口需要 create_mask / update_mask 得到的 MaskSSA，不能直接传 tla.mask.* token。

调用示例：

with tla.vec.func(mode="simd"):
    # 用 pattern token 构建 mask：
    m_all = tla.create_mask(pattern=tla.mask.ALL, dtype=tla.Float16)
    m_tail = tla.create_mask(pattern=tla.mask.VL8, dtype=tla.Float16)
    # 前：x_reg / y_reg 为整 vector；只让最低 8 个元素做加法。
    z = tla.add(x_reg, y_reg, mask=m_tail)
    # 后：有效元素为 x+y；被 mask 掉的元素不参与。

`update_mask`

源码： catlass.core_api.update_mask

功能说明：

创建尾部 mask，并返回剩余元素计数。

函数原型：

tla.update_mask(true_shape: IndexLike, dtype: DTypeLike = Float32) -> tuple[MaskSSA, Numeric]

参数说明：

true_shape（IndexLike）：当前有效（true）区域形状。必填。
dtype（DTypeLike）：与掩码关联的元素类型。可选，默认 Float32。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    tail_mask, remain = tla.update_mask(true_shape, dtype=tla.Float32)

基础算术

`exp`

源码： catlass.core_api.exp

功能说明：

vector 逐元素指数（需 f16/f32）。

函数原型：

tla.exp(operand: VectorSSA, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

operand（VectorSSA）：源 vector 寄存器。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；元素类型须为 f16/f32。

调用示例：

with tla.vec.func(mode="simd"):
    y = tla.exp(x_reg)

`log`

源码： catlass.core_api.log

功能说明：

vector 逐元素对数（需 f16/f32）。

函数原型：

tla.log(operand: VectorSSA, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

operand（VectorSSA）：源 vector 寄存器。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；元素类型须为 f16/f32。

调用示例：

with tla.vec.func(mode="simd"):
    y = tla.log(x_reg)

`sqrt`

源码： catlass.core_api.sqrt

功能说明：

vector 或标量的平方根。

对 VectorSSA：逐元素 AVE 运算（需 f16/f32）。对浮点 Numeric：走核内标量单元，可在 tla.cube、SIMD/SIMT 的 tla.vec.func 或 kernel 函数体中使用。SIMT 区域内为逐线程 tla.simt_sqrt；其余路径为 math.sqrt。浮点 Numeric 上的 x.sqrt() 是同一操作。

函数原型：

tla.sqrt(operand: VectorSSA, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

operand（VectorSSA | Numeric）：源 vector 寄存器，或浮点标量。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。仅 vector 形态。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
vector 形态须在 tla.vec.func() 内调用；元素类型须为 f16/f32。
标量形态仅支持浮点，且不接受 mask。

调用示例：

with tla.vec.func(mode="simd"):
    y = tla.sqrt(x_reg)

with tla.cube():
    s = tla.sqrt(scale)

`abs`

源码： catlass.core_api.abs

功能说明：

vector 逐元素绝对值。

函数原型：

tla.abs(operand: VectorSSA, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

operand（VectorSSA）：源 vector 寄存器。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    y = tla.abs(x_reg)

`neg`

源码： catlass.core_api.neg

功能说明：

vector 逐元素取负。

函数原型：

tla.neg(operand: VectorSSA, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

operand（VectorSSA）：源 vector 寄存器。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    y = tla.neg(x_reg)

`add`

源码： catlass.core_api.add

功能说明：

vector 逐元素加法（支持 vector–vector 与 vector–scalar）。 VectorSSA 在不需要 mask 时也可通过 + / __radd__ 调用本接口。

函数原型：

tla.add(lhs: VectorSSA | Numeric | bool | int | float, rhs: VectorSSA | Numeric | bool | int | float, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

lhs（VectorSSA | Numeric | bool | int | float）：左操作数。必填。
rhs（VectorSSA | Numeric | bool | int | float）：右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；支持 vector–vector 与 vector–scalar。

调用示例：

with tla.vec.func(mode="simd"):
    # 计算前：x_reg、y_reg 已从 UB load 到寄存器。
    z = x_reg + y_reg            # 等价于 tla.add(x_reg, y_reg)
    z = x_reg + 1.0              # vector–scalar，走 __add__/__radd__
    # 带 mask：先 create_mask 得到 MaskSSA，再传 mask=（不能用运算符重载）。
    m = tla.create_mask(pattern=tla.mask.VL16, dtype=tla.Float16)
    z = tla.add(x_reg, y_reg, mask=m)
    # 计算后：有效元素为和；其余元素不参与。

`sub`

源码： catlass.core_api.sub

功能说明：

vector 逐元素减法。 VectorSSA 在不需要 mask 时也可通过 -（__sub__）调用本接口。

函数原型：

tla.sub(lhs: VectorSSA | Numeric | bool | int | float, rhs: VectorSSA | Numeric | bool | int | float, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

lhs（VectorSSA | Numeric | bool | int | float）：左操作数（被减数）。必填。
rhs（VectorSSA | Numeric | bool | int | float）：右操作数（减数）。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    # 计算前：x_reg / y_reg 为源 vector。
    z = x_reg - y_reg                 # 等价于 tla.sub(x_reg, y_reg)
    z = tla.sub(x_reg, y_reg, mask=m) # 需要 mask 时用函数形式
    # 计算后：z 为逐元素差。

`mul`

源码： catlass.core_api.mul

功能说明：

vector 逐元素乘法。 VectorSSA 在不需要 mask 时也可通过 * / __rmul__ 调用本接口。

函数原型：

tla.mul(lhs: VectorSSA | Numeric | bool | int | float, rhs: VectorSSA | Numeric | bool | int | float, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

lhs（VectorSSA | Numeric | bool | int | float）：左操作数。必填。
rhs（VectorSSA | Numeric | bool | int | float）：右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    # 计算前：x_reg 为激活；scale 可为 vector 或标量。
    z = x_reg * y_reg      # 等价于 tla.mul(x_reg, y_reg)
    z = x_reg * 2.0        # vector–scalar
    z = tla.mul(x_reg, y_reg, mask=m)
    # 计算后：z 为逐元素积。

`max`

源码： catlass.core_api.max

功能说明：

vector 逐元素最大值。

函数原型：

tla.max(lhs: VectorSSA | Numeric | bool | int | float, rhs: VectorSSA | Numeric | bool | int | float, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

lhs（VectorSSA | Numeric | bool | int | float）：左操作数。必填。
rhs（VectorSSA | Numeric | bool | int | float）：右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    z = tla.max(x_reg, y_reg)

`min`

源码： catlass.core_api.min

功能说明：

vector 逐元素最小值。

函数原型：

tla.min(lhs: VectorSSA | Numeric | bool | int | float, rhs: VectorSSA | Numeric | bool | int | float, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

lhs（VectorSSA | Numeric | bool | int | float）：左操作数。必填。
rhs（VectorSSA | Numeric | bool | int | float）：右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    z = tla.min(x_reg, y_reg)

`div`

源码： catlass.core_api.div

功能说明：

vector 逐元素除法。 VectorSSA 在不需要 mask 时也可通过 /（__truediv__）调用本接口。

函数原型：

tla.div(lhs: VectorSSA | Numeric | bool | int | float, rhs: VectorSSA | Numeric | bool | int | float, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

lhs（VectorSSA | Numeric | bool | int | float）：左操作数（被除数）。必填。
rhs（VectorSSA | Numeric | bool | int | float）：右操作数（除数）。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    # 计算前：x_reg 为被除数；y_reg / 标量为除数。
    z = x_reg / y_reg                 # 等价于 tla.div(x_reg, y_reg)
    z = tla.div(x_reg, y_reg, mask=m)
    # 计算后：z 为逐元素商。

逻辑计算

Mask / Vector 上的按位与逻辑运算。

`shift_left`

源码： catlass.core_api.shift_left

功能说明：

按 lane 或标量移位量，对 vector 做逐元素左移。

函数原型：

tla.shift_left(source: VectorSSA, shift: Any, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

source（VectorSSA）：待移位的源 vector。必填。
shift（VectorSSA | Numeric | int）：每 lane 移位量。可为与 source 同元素位宽的有符号 VectorSSA，或可转为 i16 的整型标量。必填。
mask（MaskSSA | None）：执行掩码。可选，默认 None（全 lane 有效）；被 mask 掉的 lane 写零。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。
源元素须为有符号 8/16/32 位整数（i8/i16/i32）；不支持 64 位与无符号移位。
移位量须为非负。

调用示例：

with tla.vec.func(mode="simd"):
    _tile = tla.shift_left(tile, bit_shift_reg, mask=mask)

`shift_right`

源码： catlass.core_api.shift_right

功能说明：

按 lane 或标量移位量，对 vector 做逐元素右移。

有符号源 vector 使用算术右移。

函数原型：

tla.shift_right(source: VectorSSA, shift: Any, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

source（VectorSSA）：待移位的源 vector。必填。
shift（VectorSSA | Numeric | int）：每 lane 移位量。可为与 source 同元素位宽的有符号 VectorSSA，或可转为 i16 的整型标量。必填。
mask（MaskSSA | None）：执行掩码。可选，默认 None（全 lane 有效）；被 mask 掉的 lane 写零。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。
源元素须为有符号 8/16/32 位整数（i8/i16/i32）；不支持 64 位与无符号移位。
移位量须为非负。

调用示例：

with tla.vec.func(mode="simd"):
    _tile = tla.shift_right(tile, bit_shift_reg, mask=mask)

`bitwise_not`

源码： catlass.core_api.bitwise_not

功能说明：

逐元素按位/逻辑非（Mask 或 Vector）。

函数原型：

tla.bitwise_not(operand: VectorSSA | MaskSSA, *, mask: MaskSSA | None = None) -> MaskSSA | VectorSSA

参数说明：

operand（VectorSSA | MaskSSA）：按位取反的源操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    m2 = tla.bitwise_not(m)

`bitwise_and`

源码： catlass.core_api.bitwise_and

功能说明：

逐元素按位与（Mask 或 Vector）。

函数原型：

tla.bitwise_and(src0_reg: VectorSSA | MaskSSA, src1_reg: VectorSSA | MaskSSA, *, mask: MaskSSA | None = None) -> MaskSSA | VectorSSA

参数说明：

src0_reg（VectorSSA | MaskSSA）：按位与左操作数。必填。
src1_reg（VectorSSA | MaskSSA）：按位与右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    m3 = tla.bitwise_and(m0, m1)

`bitwise_or`

源码： catlass.core_api.bitwise_or

功能说明：

逐元素按位或（Mask 或 Vector）。

函数原型：

tla.bitwise_or(src0_reg: VectorSSA | MaskSSA, src1_reg: VectorSSA | MaskSSA, *, mask: MaskSSA | None = None) -> MaskSSA | VectorSSA

参数说明：

src0_reg（VectorSSA | MaskSSA）：按位或左操作数。必填。
src1_reg（VectorSSA | MaskSSA）：按位或右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    m3 = tla.bitwise_or(m0, m1)

`bitwise_xor`

源码： catlass.core_api.bitwise_xor

功能说明：

逐元素按位异或（Mask 或 Vector）。

函数原型：

tla.bitwise_xor(src0_reg: VectorSSA | MaskSSA, src1_reg: VectorSSA | MaskSSA, *, mask: MaskSSA | None = None) -> MaskSSA | VectorSSA

参数说明：

src0_reg（VectorSSA | MaskSSA）：按位异或左操作数。必填。
src1_reg（VectorSSA | MaskSSA）：按位异或右操作数。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    m3 = tla.bitwise_xor(m0, m1)

比较与选择

`where`

源码： catlass.core_api.where

功能说明：

按 mask 在两路 vector 间逐元素选择；在 SIMT 区域内也可在两路 per-thread 标量间选择。

函数原型：

tla.where(mask: Any, x: Any, y: Any) -> Any

参数说明：

mask（MaskSSA | Bool）：选择掩码；真取 x，假取 y。可为整 vector 的 MaskSSA，或 SIMT 区域内比较得到的 Bool。必填。
x（VectorSSA | Numeric）：掩码为真时的取值。必填。
y（VectorSSA | Numeric）：掩码为假时的取值。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；mask/x/y 的有效元素布局须匹配。
per-thread 形式要求 mode="simt"，并生成 tla.simt_where。

调用示例：

with tla.vec.func(mode="simd"):
    z = tla.where(m, x_reg, y_reg)

`cmp`

源码： catlass.core_api.cmp

功能说明：

vector 比较，返回 mask。

函数原型：

tla.cmp(lhs: VectorSSA, rhs: VectorSSA | Numeric | bool | int | float, mode: str, *, mask: MaskSSA | None = None) -> MaskSSA

参数说明：

lhs（VectorSSA）：比较左操作数。必填。
rhs（VectorSSA | Numeric | bool | int | float）：比较右操作数（可为标量或 vector）。必填。
mode（str）：比较模式，如 'eq' / 'lt' / 'gt' 等。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；mode 须为支持的比较模式名。

调用示例：

with tla.vec.func(mode="simd"):
    m = tla.cmp(x_reg, y_reg, mode="lt")

数据填充

`full`

源码： catlass.core_api.full

功能说明：

用 Python 标量字面量填充一维 vector SSA，或将单 lane 的 vector 片段（例如 VectorSSA.reduce 的结果）广播到全部 lane。

函数原型：

tla.full(value: bool | int | float | Numeric | VectorSSA, dtype: type[Numeric], *, mask: Any | None = None) -> VectorSSA

参数说明：

value（bool | int | float | Numeric | VectorSSA）：填充常量，或待广播的单 lane vector 片段。必填。
dtype（type[Numeric]）：vector 元素类型。必填。
mask（MaskSSA | None）：谓词哪些 lane 被写入。可选；默认写全部 lane。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；value 须为 Python 标量字面量、Host Numeric，或单 lane vector 片段。
当 value 为 vector 时，必须恰好 1 个有效 lane，且元素类型与 dtype 一致。
若提供 mask，须与结果元素类型匹配。

调用示例：

with tla.vec.func(mode="simd"):
    zeros = tla.full(0.0, dtype=tla.Float32)
    all_lanes, _ = tla.update_mask(64, tla.Float32)
    total = src.reduce(tla.ReductionOp.ADD, mask=all_lanes)
    spread = tla.full(total, dtype=tla.Float32)

`arange`

源码： catlass.core_api.arange

功能说明：

创建单调递增或递减的一维 vector SSA（base + order）。

函数原型：

tla.arange(base: bool | int | float | Numeric = 0, *, order: str = 'increase', dtype: type[Numeric]) -> VectorSSA

参数说明：

base（bool | int | float | Numeric）：起始基数。可选，默认 0。
order（str）：'increase' 递增或 'decrease' 递减。可选，默认 'increase'。
dtype（type[Numeric]）：vector 元素类型。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；order 仅支持 increase / decrease。

调用示例：

with tla.vec.func(mode="simd"):
    lane_idx = tla.arange(base=0, order="increase", dtype=tla.Int32)

离散与聚合

按索引 gather，以及带 mask 的归约（VectorSSA.reduce）。

`gather`

源码： catlass.core_api.gather

功能说明：

按索引从 UB tile 或寄存器 gather 元素。

两种形态：

UB→Reg：x 为 UB 上的 Tensor；y 为 i32 索引；可选 mask。
Reg→Reg：x 为 VectorSSA；y 为与 x 元素位宽相同的整数索引（i8/u8、i16/u16 或 i32/u32）；result[i] = x[y[i] % VL]。无 mask。

函数原型：

tla.gather(x: Tensor | VectorSSA, y: VectorSSA, *, mask: MaskSSA | None = None) -> VectorSSA

参数说明：

x（Tensor | VectorSSA）：源 tile（UB）或源寄存器。必填。
y（VectorSSA）：索引 vector 寄存器。必填。
mask（MaskSSA | None）：仅 UB→Reg 可选执行掩码；None 表示全有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。
Tensor 源须位于 UB。

调用示例：

with tla.vec.func(mode="simd"):
    vals = tla.gather(ub_tile, idx_i32)
    w_brc = tla.gather(w, idx_u16)  # Reg→Reg

`VectorSSA.reduce`

源码： catlass.core_api.VectorSSA.reduce

功能说明：

在 mask 下对本寄存器驻留 vector 做归约，得到单 lane 片段（tla.ReductionOp.ADD / MAX / MIN）。可用 tla.full(fragment, dtype=...) 再广播回全宽。

函数原型：

VectorSSA.reduce(kind: ReductionOp, *, mask: Any, init_value: Any | None = None, reduction_profile: Any | None = None) -> Any

参数说明：

kind（ReductionOp）：归约种类（ADD、MAX 或 MIN）。必填。
mask（MaskSSA）：谓词哪些 lane 参与。必填。
init_value：预留；当前仅支持 None。可选，默认 None。
reduction_profile：预留；当前仅支持 None。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。
元素类型须为 f16/f32/i16/i32/u16/u32 之一。
init_value 与 reduction_profile 须省略或为 None。

调用示例：

with tla.vec.func(mode="simd"):
    m = tla.create_mask(pattern=tla.mask.ALL, dtype=tla.Float32)
    total = src_reg.reduce(tla.ReductionOp.ADD, mask=m)
    broadcast = tla.full(total, dtype=tla.Float32)

数据重排

提供 vector 寄存器或 predicate mask 的 lane 交插与解交插操作。

`interleave`

源码： catlass.core_api.interleave

功能说明：

按 lane 交替排列两个 vector 寄存器或两个 predicate mask，并返回两个寄存器。

函数原型：

tla.interleave(src0: VectorSSA | MaskSSA, src1: VectorSSA | MaskSSA) -> tuple[VectorSSA, VectorSSA] | tuple[MaskSSA, MaskSSA]

参数说明：

src0（VectorSSA 或 MaskSSA）：偶数 lane 输入。必填。
src1（VectorSSA 或 MaskSSA）：与 src0 类别和类型相同的奇数 lane 输入。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；输入类型须匹配。MaskSSA 仅支持 mask<64>、mask<128> 和 mask<256>。

调用示例：

with tla.vec.func(mode="simd"):
    lo, hi = tla.interleave(a, b)
    mask_lo, mask_hi = tla.interleave(mask0, mask1)

`deinterleave`

源码： catlass.core_api.deinterleave

功能说明：

按顺序拼接两个 vector 寄存器或两个 predicate mask，再分别返回偶数位置和奇数位置的 lane。

函数原型：

tla.deinterleave(src0: VectorSSA | MaskSSA, src1: VectorSSA | MaskSSA) -> tuple[VectorSSA, VectorSSA] | tuple[MaskSSA, MaskSSA]

参数说明：

src0（VectorSSA 或 MaskSSA）：拼接输入的前半部分。必填。
src1（VectorSSA 或 MaskSSA）：与 src0 类别和类型相同的后半部分。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；两路 vector 的元素类型与 lane 数须匹配。
MaskSSA 的输入和输出类型必须完全一致，仅支持 mask<64>、mask<128> 和 mask<256>；不支持 mask<32>/b64。

调用示例：

with tla.vec.func(mode="simd"):
    even, odd = tla.deinterleave(a, b)
    mask_even, mask_odd = tla.deinterleave(mask0, mask1)

数据压缩

`squeeze`

源码： catlass.core_api.squeeze

功能说明：

按 mask 将选中元素压缩到结果低位。

函数原型：

tla.squeeze(src: VectorSSA, mask: MaskSSA) -> VectorSSA

参数说明：

src（VectorSSA）：待压缩的源 vector。必填。
mask（MaskSSA）：保留元素的掩码。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。

调用示例：

with tla.vec.func(mode="simd"):
    packed = tla.squeeze(src, m)

类型转换

寄存器 vector 上的元素类型转换（VectorSSA.to）与同位宽按位重解释（VectorSSA.bitcast）。

`VectorSSA.to`

源码： catlass.core_api.VectorSSA.to

功能说明：

将寄存器内的 vector 转换为另一种元素类型。

lowering 支持有符号整数 tla.Int8 ~ tla.Int64、浮点 tla.Float16 / tla.BFloat16 / tla.Float32，以及两种 OCP fp8 格式 tla.Float8E4M3FN / tla.Float8E5M2。无符号整数、tla.Bool（i1）、tla.Float64 与 tla.Float8E8M0 会被拒绝。

tla.Float16 到 tla.BFloat16 使用一条直接转换指令，保留全部 lane，支持所有舍入模式。sat_mode 必须为 UNKNOWN；由于指令没有饱和模式参数，NOSAT 和 SAT 均会被拒绝。对于这一等宽转换，reg_slot 的 ZERO 与 ONE 效果相同。

fp8 操作数可与 tla.Float32、tla.Float16、tla.BFloat16 互相转换。其中只有 f32 这一对是单条指令：f16 与 bf16 两对由 lowering 展开为经过 f32 的两次 cast，扩宽一侧精确、收窄一侧只舍入一次；f8e5m2 -> f16 则展开为一次整数扩宽加一次移位，因为这两种格式共享同一符号与指数字段——与经过 f32 的组合路径选出相同元素，但只需两条指令而非五条。fp8 之间没有重编码路径——两者指数范围不同，属于重量化而非 cast——也没有 fp8 与整数之间的路径。

函数原型：

VectorSSA.to(dst_type: Any, params: CastParams, mask: Any | None = None) -> Any

参数说明：

dst_type（type[Numeric]）：目标元素类型。必填。
params（CastParams）：舍入模式、饱和模式与寄存器 slot。必填。
mask（MaskSSA | None）：可选执行掩码；None 表示所有 lane 使能。选填，默认 None。 mask 按源元素域索引：lane i 谓词源元素 i，与位宽变化无关；被 mask 关掉的元素对结果贡献为零。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。
reg_slot 的 TWO 与 THREE 指向 pack 的四分之一，仅在位宽变化为 4 倍的整数 cast 以及直接的 fp8↔f32 指令上合法。
线程级标量 cast 在 mode="simt" 下使用 Numeric.to；本方法是 vector（AVE）形态，始终需要 CastParams。

调用示例：

trait = tla.params.CastParams(
    reg_slot=tla.params.RegSlot.ZERO,
    sat_mode=tla.params.SatMode.NOSAT,
    round_mode=tla.params.RoundMode.CAST_ROUND,
)
with tla.vec.func(mode="simd"):
    wide = narrow.to(tla.Float32, trait)

`VectorSSA.bitcast`

源码： catlass.core_api.VectorSSA.bitcast

功能说明：

将寄存器内 vector 的比特按另一种同位宽元素类型重新解释。该操作不做任何数值转换，也不产生硬件指令：寄存器的比特保持原样，只有元素类型改变，因此开销为零。

这使得浮点数的比特模式在 DSL 前端变得可读——取出指数、通过移入第 23 位构造 2**k、清除符号位——而不必经由 UB 以另一种元素类型存取一轮。

同位宽的组合为 f32/i32/u32、f16/bf16/i16/u16、 i8/u8/f8e4m3fn/f8e5m2 以及 i64/u64，lane 数保持不变。位宽变化属于 VectorSSA.to 的职责，在此会被拒绝。tla.Bool（i1）、tla.Float8E8M0 与打包的 fp4 格式不是合法的 !tla.vector 元素类型，同样会被拒绝。

需要注意，i64/u64 虽然可以通过校验，但目前并不可达：tla.make_tensor_like 拒绝 i64 元素类型，因此没有任何路径能产生 64 位的 vector 寄存器。

函数原型：

VectorSSA.bitcast(dst_type: Any) -> Any

参数说明：

dst_type（type[Numeric]）：重新解释为的同位宽元素类型。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用。
dst_type 的位宽须与源元素类型相同。
重解释为源自身的元素类型是空操作，直接返回 self。

调用示例：

with tla.vec.func(mode="simd"):
    bits = x.bitcast(tla.Int32)
    exponent = tla.bitwise_and(
        tla.shift_right(bits, 23, mask=m), tla.full(0xFF, tla.Int32)
    )

同步控制

核内 / 跨核 flag、pipe barrier、mutex 与本地内存屏障。

`flag`

源码： catlass.core_api.flag

功能说明：

在两条 pipe 之间创建管内同步 flag。

函数原型：

tla.flag(name: str, src_pipe: PipeLike, dst_pipe: PipeLike) -> TlaFlag

参数说明：

name（str）：管内 flag 名称。必填。
src_pipe（PipeLike）：源 pipe 标识（例如 tla.arch.MTE2）。必填。
dst_pipe（PipeLike）：目的 pipe 标识（例如 tla.arch.VECTOR）。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
创建的是 flag 句柄；set_flag/wait_flag 须在 cube/vector 区域内成对使用。

调用示例：

# MTE2 完成 GM→UB 拷贝后，VECTOR 侧才可消费该 UB tile。
ub_loaded = tla.flag("ub_loaded", src_pipe=tla.arch.MTE2, dst_pipe=tla.arch.VECTOR)
with tla.vector():
    tla.copy(dst=x_ub, src=x_gm)
    tla.set_flag(ub_loaded)   # 拷贝后：标记 UB 数据就绪
    tla.wait_flag(ub_loaded)  # 计算前：等待就绪

`cross_flag`

源码： catlass.core_api.cross_flag

功能说明：

创建命名的跨核同步 flag。源/目的 pipe 由对应 set/wait 指定；mode=4 为 1:1 AIC↔AIV，并按 AIV0/AIV1 独立寻址。

函数原型：

tla.cross_flag(name: str, *, mode: int = 2) -> TlaCrossFlag

参数说明：

name（str）：跨核 flag 名称。必填。
mode（int）：跨核同步模式。可选，默认 2。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
mode 仅支持 0/1/2/4；源/目的 pipe 由对应 set/wait 指定。

调用示例：

cf = tla.cross_flag("aic_aiv", mode=2)

`cross_core_set_flag`

源码： catlass.core_api.cross_core_set_flag

功能说明：

从指定 pipe 置位跨核 flag；mode=4 时需提供 aiv_id（0 或 1）。

函数原型：

tla.cross_core_set_flag(cross_flag_value: CrossFlagLike, pipe: PipeLike, aiv_id: int | None = None) -> None

参数说明：

cross_flag_value（CrossFlagLike）：由 tla.cross_flag 得到的跨核 flag。必填。
pipe（PipeLike）：设置 flag 的 pipe。必填。
aiv_id（int | None）：目标 AIV 编号；缺省表示广播/默认路由。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用；mode=4 时 aiv_id 须为 0 或 1。

调用示例：

with tla.cube():
    tla.cross_core_set_flag(cf, tla.arch.CUBE)
    # mode=4: tla.cross_core_set_flag(cf, tla.arch.CUBE, aiv_id=0)

`cross_core_wait_flag`

源码： catlass.core_api.cross_core_wait_flag

功能说明：

在指定 pipe 上等待跨核 flag；mode=4 时需提供 aiv_id（0 或 1）。

函数原型：

tla.cross_core_wait_flag(cross_flag_value: CrossFlagLike, pipe: PipeLike, aiv_id: int | None = None) -> None

参数说明：

cross_flag_value（CrossFlagLike）：由 tla.cross_flag 得到的跨核 flag。必填。
pipe（PipeLike）：执行 wait 的 pipe。必填。
aiv_id（int | None）：目标 AIV 编号；缺省表示广播/默认路由。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用；mode=4 时 aiv_id 须为 0 或 1。

调用示例：

with tla.vector():
    tla.cross_core_wait_flag(cf, tla.arch.VECTOR)

`set_flag`

源码： catlass.core_api.set_flag

功能说明：

置位同核同步 flag。

函数原型：

tla.set_flag(flag_value: FlagLike) -> None

参数说明：

flag_value（FlagLike）：由 tla.flag 得到的核内 pipe flag。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用。

调用示例：

with tla.vector():
    tla.set_flag(ub_loaded)

`wait_flag`

源码： catlass.core_api.wait_flag

功能说明：

等待同核同步 flag。

函数原型：

tla.wait_flag(flag_value: FlagLike) -> None

参数说明：

flag_value（FlagLike）：由 tla.flag 得到的核内 pipe flag。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用。

调用示例：

with tla.vector():
    tla.wait_flag(ub_loaded)

`pipe_barrier`

源码： catlass.core_api.pipe_barrier

功能说明：

插入指定硬件 pipe 的屏障。

函数原型：

tla.pipe_barrier(pipe: PipeLike) -> None

参数说明：

pipe（PipeLike）：要插入 barrier 的 pipe。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用。

调用示例：

with tla.vector():
    tla.pipe_barrier(tla.arch.MTE2)

`mutex`

源码： catlass.core_api.mutex

功能说明：

创建与语义资源关联的 mutex 句柄。

函数原型：

tla.mutex(resource: str, id: int = -1) -> TlaMutex

参数说明：

resource（str）：互斥资源名。必填。
id（int）：互斥实例编号；-1 表示默认。可选，默认 -1。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
resource 非空；id 为 -1 或 0..31。

调用示例：

mtx = tla.mutex("l1_buf", id=0)

`mutex_guard`

源码： catlass.core_api.mutex_guard

功能说明：

创建上下文管理器，对代码块自动推断 mutex 访问。

函数原型：

tla.mutex_guard(*mutexes: MutexLike) -> _MutexGuard

参数说明：

mutexes（MutexLike）：一个或多个 mutex 对象。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
块内须调用 copy 或 mmad；guard 内不可再显式 lock/unlock。

调用示例：

with tla.mutex_guard(mtx):
    tla.copy(dst, src)

`mutex_lock`

源码： catlass.core_api.mutex_lock

功能说明：

从指定 pipe 获取 mutex。

函数原型：

tla.mutex_lock(mutex_value: MutexLike, *, pipe: PipeLike) -> None

参数说明：

mutex_value（MutexLike）：要加锁的 mutex。必填。
pipe（PipeLike）：加锁所在 pipe。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用；须指定 pipe。

调用示例：

tla.mutex_lock(mtx, pipe=tla.arch.MTE2)

`mutex_unlock`

源码： catlass.core_api.mutex_unlock

功能说明：

从指定 pipe 释放 mutex。

函数原型：

tla.mutex_unlock(mutex_value: MutexLike, *, pipe: PipeLike) -> None

参数说明：

mutex_value（MutexLike）：要解锁的 mutex。必填。
pipe（PipeLike）：解锁所在 pipe。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用；须指定 pipe。

调用示例：

tla.mutex_unlock(mtx, pipe=tla.arch.MTE2)

`local_mem_bar`

源码： catlass.core_api.local_mem_bar

功能说明：

在 vec.func 内插入本地内存屏障（按 MemType 对编码）。

函数原型：

tla.local_mem_bar(src: MemType, dst: MemType)

参数说明：

src（MemType）：源本地内存类型。必填。
dst（MemType）：目的本地内存类型。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.vec.func() 内调用；(src, dst) 须为支持的 MemType 对。

调用示例：

with tla.vec.func(mode="simd"):
    tla.local_mem_bar(tla.params.MemType.VEC_STORE, tla.params.MemType.VEC_LOAD)

系统变量访问

挂在 tla.arch 上的架构属性（布局标签、pipe、block 辅助等）。

`arch`

源码： catlass.core_api.arch

功能说明：

tla.arch 下的架构属性组：layout tag、pipe 标识、片上 memory-scope token，以及 block / SIMT 辅助接口。

函数原型：

tla.arch

参数说明：

布局标签（_LayoutTag，供 make_layout / make_tensor / make_tensor_like 使用）：RowMajor、ColumnMajor、zN、nZ、 L0Clayout、zNUnAlign。
Pipe 标识（供 flag / pipe_barrier / mutex_* / 跨核同步使用）： SCALAR、VECTOR、CUBE、MTE1、MTE2、MTE3、FIX。
Memory-scope token（供 local_mem_bar 等相关接口使用）：L1、L0A、L0B、L0C、UB。
可调用接口（返回 Int32 或如下注明的三元组）：
- block_idx()：当前 AI 核在本次 launch 中的 block 索引。
- block_num()：本次 launch 的 block（AI 核）数量。
- sub_block_idx()：当前 block 内的 sub-block 索引。
- thread_idx()：SIMT thread block 内的线程索引 (x, y, z)（仅可在 tla.vec.func(mode="simt") 内使用）。
- thread_block_dim()：SIMT thread-block 规模 (x, y, z)（仅可在 tla.vec.func(mode="simt") 内使用）。
- sync_threads()：对当前 SIMT tla.vec.func 内线程做 barrier（仅 mode="simt"）。
- get_capacity_in_bytes(mem_scope)：返回编译目标上某片上存储空间的字节容量。入参为 tla.AddressSpace（tla.AddressSpace.l1 / l0a / l0b / l0c / ub）。返回普通 int；host 侧与 kernel 内均可使用（kernel 内会折叠为常量）。
- get_dyn_ub(dtype, byte_alignment=None)：返回动态 UB 区域的指针——该区域的大小由 launch 决定，而非编译期决定。区域起始于所有 tla.allocate 之上， launch 时用 ub= 指定实际提供多少字节。每个 kernel 至多声明一个区域：需要多块缓冲时，用指针算术在该区域内切分。按 kernel 实际使用量申请即可——SIMT 场景下未被 kernel 占用的 UB 会成为 Data Cache，申请过多会让 Data Cache 变小从而拖慢访存。

约束说明：

layout tag / pipe 标识 / memory-scope token 是 tla.arch 对象上的普通属性（Python 没有 C++ 式命名空间）；它们本身不会生成计算 op。
block_idx / block_num / sub_block_idx / thread_idx / thread_block_dim / sync_threads 为可调用对象，须在 @tla.kernel 装饰的 kernel 函数体内使用。
thread_idx / thread_block_dim / sync_threads 还须嵌套在 tla.vec.func(mode="simt") 内。

调用示例：

# make_layout / make_tensor 用的 layout tag：
tag = tla.arch.RowMajor
# flag / barrier / mutex 用的 pipe 标识：
pipe = tla.arch.MTE2
# 运行时 block 辅助：
bid = tla.arch.block_idx()
nblocks = tla.arch.block_num()
# 片上存储容量（host 侧或 kernel 内均可）：
l1_bytes = tla.arch.get_capacity_in_bytes(tla.AddressSpace.l1)
ub_bytes = tla.arch.get_capacity_in_bytes(tla.AddressSpace.ub)
# 动态 UB：大小在 launch 时确定，基址为编译期常量。
base = tla.arch.get_dyn_ub(tla.Float32, byte_alignment=256)
lo = tla.make_tensor_like(base, gm_a, tla.arch.RowMajor)
hi = tla.make_tensor_like(base + HALF, gm_b, tla.arch.RowMajor)
# host 侧：artifact(..., ub=64 * 1024)

资源管理

片上缓冲分配。

`allocate`

源码： catlass.core_api.allocate

功能说明：

分配本地内存并返回类型化指针。

函数原型：

tla.allocate(shape: ShapeLike, dtype: type[Numeric], mem_scope: AddressSpace, byte_alignment: int) -> Pointer

参数说明：

shape（ShapeLike）：分配块的形状。必填。
dtype（type[Numeric]）：元素数值类型。必填。
mem_scope（AddressSpace）：地址空间（如 L1 / UB）。必填。
byte_alignment（int）：字节对齐要求。必填。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
mem_scope 须为片上地址空间（l1/l0a/l0b/l0c/ub），不可为 gm/generic；shape 须全静态。

调用示例：

ptr = tla.allocate(
    shape=(256, 128),
    dtype=tla.Float16,
    mem_scope=tla.AddressSpace.ub,
    byte_alignment=32,
)

调试接口

kernel 内标量 / tensor 调试打印。

`print`

源码： catlass.core_api.print

功能说明：

在 cube / vector 区域内打印标量、格式化标量字符串，或打印 GM、UB、L1、L0C tensor 的物理前缀。

函数原型：

tla.print(*args: object, **kwargs: object) -> None

参数说明：

args（object）：要打印的值（可变位置参数）。必填。
kwargs（object）：不接受关键字参数；传入则报错。可选。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须在 tla.cube() 或 tla.vector() 内调用。
GM/UB 支持 rank-1/rank-2 物理前缀；L1/L0C 仅支持 C310 AIC 和经验证的 CANN 9.1 DebugTunnel ABI。
L1 须为 32 字节对齐的 zN/nZ 稠密前缀，C0 维度占 32 字节，最多打印 8 个元素，并要求驱动提供 DebugBus HAL 映射接口。
L0C 须为 32 字节对齐的 L0Clayout 16x16 完整分形（256 个元素）；L0A/L0B 不支持。
Tensor dtype 支持 f16、f32、i8、i16、i32、u8、u16、u32。

调用示例：

with tla.vector():
    tla.print(x_scalar)
    tla.print(x_ub, 64)  # tensor + prefix length

作用域和控制流

Cube / Vector / vec.func 区域以及 kernel 侧循环范围。

从这些 region 内调用的外层 def、tla.Constexpr 函数入参与 @tla.jit helper，须遵守本节各 region 约束，以及所用算子条目的「约束说明」。

`range`

源码： catlass.core_api.range

功能说明：

创建前端动态循环范围（支持 Python range 形态）。

函数原型：

tla.range(start: IndexLike, end: IndexLike | None = None, step: IndexLike | None = None) -> _ast_helpers.FrontendRange

参数说明：

start（IndexLike）：循环起点（或当 end 缺省时的终点，此时起点为 0）。必填。
end（IndexLike | None）：循环终点（不含）；缺省时 start 视为终点。可选，默认 None。
step（IndexLike | None）：步长；缺省为 1。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
动态范围；循环体须符合前端动态 for 约束。

调用示例：

for i in tla.range(0, n, 1):
    ...

`range_constexpr`

源码： catlass.core_api.range_constexpr

功能说明：

创建前端静态范围，用于可展开的 Python 循环。

函数原型：

tla.range_constexpr(start: int, end: int | None = None, step: int | None = None) -> range

参数说明：

start（int）：编译期循环起点（或当 end 缺省时的终点）。必填。
end（int | None）：编译期循环终点（不含）。可选，默认 None。
step（int | None）：编译期步长；缺省为 1。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
起止与步长须为编译期常量，用于可展开循环。
边界也可来自 tla.as_numeric(...) 等编译期 Numeric 值。
迭代次数达到 64 次及以上时发出 DSLOptimizationWarning，但继续展开；大循环应优先用 tla.range(...)。

调用示例：

for k in tla.range_constexpr(0, 4):
    ...

`cube`

源码： catlass.core_api.cube

功能说明：

进入 cube 核区域（矩阵乘与相关搬运）。

函数原型：

tla.cube() -> TlaRegion

参数说明：

无。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
用于包裹 cube 侧矩阵乘与相关搬运。

调用示例：

with tla.cube():
    tla.mmad(acc=l0c, lhs=l0a, rhs=l0b, init_c=True)

`vector`

源码： catlass.core_api.vector

功能说明：

进入 vector 核区域（vector 搬运与同步）。

函数原型：

tla.vector() -> TlaRegion

参数说明：

无。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
用于包裹 vector 侧搬运与同步；tla.vec.func 须嵌套在其内。

调用示例：

with tla.vector():
    tla.copy(dst=x_ub, src=x_gm)

`vec.func`

源码： catlass.core_api._vec_func

功能说明：

进入寄存器 vector / mask 计算用的 vector 函数区域（tla.vec.func）。

函数原型：

tla.vec.func(*, mode: str = 'simd', thread_block_dim: int | tuple[int, int, int] | list[int] | None = None) -> TlaRegion

参数说明：

mode（str）：执行模式；simd（默认）或 simt。可选，默认 "simd"。
thread_block_dim（int | tuple[int, int, int] | list[int] | None）：SIMT thread-block 形状；仅在 mode="simt" 时有效。可选，默认 None。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用。
须嵌套在 tla.vector() 内。
寄存器 vector / mask API 与 local_mem_bar 须在此区域内调用。

调用示例：

with tla.vector():
    with tla.vec.func(mode="simd"):
        z = tla.add(x_reg, y_reg)

Tile 数据填充

对 L1 zN/nZ tensor 整 tile 填充（Tensor.fill）。

`Tensor.fill`

源码： catlass.tla.tensor._Tensor.fill

功能说明：

用给定值填充整个 L1 zN/nZ tile。填充区域即该 tile 自身：在逻辑二维（M, N）轴上覆盖 [self.coord, self.coord + self.origin_shape)。沿 layout 的 C0 轴（32 字节）会先把起点坐标向上对齐到 C0 边界再填充，因此只写入 tile 内完整的 C0 单元；起点处不完整的部分保持不动（残差需另途覆盖——MX pad 流程中通常由 GM→L1 copy 带入）。

以具体 fp8（一个 C0 单元 = 32 字节）zN 为例：取一个（例如经 tla.get_tile 得到的）tile，坐标 (0, 40)， origin_shape = (16, 56)：

    N   0               32  40          64              96
                                        ^   C0 边界：起点 40 向上对齐到 64
    M
    0   - - - - - - - - - - + + + + + + * * * * * * * *
    1   - - - - - - - - - - + + + + + + * * * * * * * *
    :   （第 2 .. 14 行相同）
   15   - - - - - - - - - - + + + + + + * * * * * * * *

图例：* = 设备写入：完整 C0 单元 [64, 96)（tile 末端 40 + 56 = 96 已 C0 对齐）。+ = 落在 tile 内但未写入：列 40..63 是不完整的 C0 单元。- = tile 外。此处 M 轴无 C0 对齐：对 zN 而言 C0 轴是 N。

函数原型：

tile.fill(value: int | float) -> None

参数说明：

value（int | float）：trace 期标量；当前仅支持 0 （设备写入全零比特模式）。

约束说明：

须在 @tla.kernel 装饰的 kernel 函数体内调用，并嵌套在 tla.cube() 内。
目的地须为带 zN 或 nZ 标签的 L1 tensor。
支持的元素类型：打包的 fp4/fp8 操作数格式（f4e2m1/f4e1m2/f8e4m3fn/f8e5m2），且仅支持填零。更宽类型、8 位整数与 e8m0 scale tile 不支持。

调用示例：

# 将 L1 A tile 的 K-pad 尾部清零：先切 tile，再 fill。
pad = tla.get_tile(t_l1a, tla.make_coord(0, k_valid),
                   tla.make_shape(m, k_l0 - k_valid))
pad.fill(0)

TLA DSL Kernel API 参考

目录

基本数据类型与操作

make_shape

make_coord

make_stride

make_layout

make_layout_with_tag

tile_view

get_tile

make_tensor

make_tensor_like

make_ptr

recast_ptr

标量 Numeric

Numeric.to

Numeric.bitcast

as_numeric

Float.sqrt

数据搬运

copy

Tensor.load

Tensor.store

矩阵运算

mmad

mmad_mx

Vector 运算

Mask 计算

create_mask

update_mask

基础算术

exp

log

sqrt

abs

neg

add

sub

mul

max

min

div

逻辑计算

shift_left

shift_right

bitwise_not

bitwise_and

bitwise_or

bitwise_xor

比较与选择

where

cmp

数据填充

full

arange

离散与聚合

gather

VectorSSA.reduce

数据重排

interleave

deinterleave

数据压缩

squeeze

类型转换

VectorSSA.to

VectorSSA.bitcast

同步控制

flag

cross_flag

cross_core_set_flag

cross_core_wait_flag

set_flag

wait_flag

pipe_barrier

mutex

mutex_guard

mutex_lock

mutex_unlock

local_mem_bar

系统变量访问

`make_shape`

`make_coord`

`make_stride`

`make_layout`

`make_layout_with_tag`

`tile_view`

`get_tile`

`make_tensor`

`make_tensor_like`

`make_ptr`

`recast_ptr`

`Numeric.to`

`Numeric.bitcast`

`as_numeric`

`Float.sqrt`

`copy`

`Tensor.load`

`Tensor.store`

`mmad`

`mmad_mx`

`create_mask`

`update_mask`

`exp`

`log`

`sqrt`

`abs`

`neg`

`add`

`sub`

`mul`

`max`

`min`

`div`

`shift_left`

`shift_right`

`bitwise_not`

`bitwise_and`

`bitwise_or`

`bitwise_xor`

`where`

`cmp`

`full`

`arange`

`gather`

`VectorSSA.reduce`

`interleave`

`deinterleave`

`squeeze`

`VectorSSA.to`

`VectorSSA.bitcast`

`flag`

`cross_flag`

`cross_core_set_flag`

`cross_core_wait_flag`

`set_flag`

`wait_flag`

`pipe_barrier`

`mutex`

`mutex_guard`

`mutex_lock`

`mutex_unlock`

`local_mem_bar`

`arch`

`allocate`

`print`

`range`

`range_constexpr`

`cube`

`vector`

`vec.func`

`Tensor.fill`