Issue: 工具链更新后两处回归阻断全部编译（BLayout::ND2M 笔误 + B.DIM 立即数 matcher 拒收）

[lvhao7896]

Issue: 工具链更新后两处回归阻断全部编译（BLayout::ND2M 笔误 + B.DIM 立即数 matcher 拒收）

• 日期: 2026-09-06
• 组件: linx toolchain (LLVM LinxV5 后端 + Linx-TileOP-API 头文件)
• 类型: 功能性 bug（编译期/汇编期，非代码生成质量）
• 严重度: High（阻断所有包含 TileOP 头文件的翻译单元；参考内核同样无法编译）

摘要

一次工具链更新（output/ 重建）引入两个独立回归，二者叠加后 任何 使用
tileop-api 的内核都无法编译。更新前同一份源码可干净编译并产出 ELF。

#	回归	层级	触发条件	现态
1	BLayout::ND2M16/BLayout::ND2M32 枚举作用域笔误	头文件（phase-1 名查找）	任何 TU 包含 template_asm.hpp	安装副本已临时改对；源未改
2	B.DIM <立即数> 被汇编器 matcher 拒收	汇编器后端 / 头文件约束	任何 TLOAD/TMULS 等模板的 valid_row/valid_col 为编译期常量	未修，无法在内核侧规避

环境

• 编译器: output/linx_blockisa_llvm_musl/bin/clang++（clang 15.0.4，target linx64v5-unknown-linux-musl）
• 头文件根: output/linx_blockisa_llvm_musl/lib/clang/15.0.4/include/tileop-api/
• 受影响内核（复现用）:
  • SuperNPUBench/benchmark/one-level-arch/kernels/multi_thread/fa/fa_opt.hpp
  • SuperNPUBench/benchmark/one-level-arch/test/kernel/multi_thread/fa/src/fa_2d_unroll_gmma.cpp（参考内核，未改动）
• 典型编译命令:

  export COMPILER_DIR=/Users/blacktraker/Programming/gitproj/DV4/linx-toolchain-build/output/linx_blockisa_llvm_musl/bin
  make -C benchmark/one-level-arch/test/kernel/multi_thread/fa diss \
      TESTCASE=fa_opt|fa_2d_unroll_gmma \
      COMPILER_DIR="$COMPILER_DIR" FA_MODE=FP32_VECFP32 \
      Sq=256 Skv=256 Tm=128 Tk=128 X_dim=1 Y_dim=1 OBJ_ROOT=/tmp/<build>
  

现象

回归 1：BLayout::ND2M16 / BLayout::ND2M32 笔误

template_asm.hpp:8949-8950，TIMG2COL 模板内：

[Layout] "i"(tile_shape_out::BFractal == BLayout::CubeM16 ?
                     BLayout::ND2M16 : BLayout::ND2M32),

ND2M16/ND2M32 实为无作用域枚举 LayoutCvtEnum（common/layout.hpp:64）的成员，不属于 enum class BLayout（layout.hpp:35，成员仅 RowMajor/ColMajor/CubeM16/CubeM32/CubeN8）。此处误抄了条件里 BLayout::CubeM16 的前缀。

报错（fa_opt 根本未调用 TIMG2COL 也被拦下）：

template_asm.hpp:8950:26: error: no member named 'ND2M16' in 'pto::BLayout'; did you mean simply 'ND2M16'?
template_asm.hpp:8950:44: error: no member named 'ND2M32' in 'pto::BLayout'; did you mean simply 'ND2M32'?
layout.hpp:79:3: note: 'ND2M16' declared here   // LayoutCvtEnum
layout.hpp:78:3: note: 'ND2M32' declared here   // LayoutCvtEnum

为什么所有 TU 都炸：BLayout::ND2M16 是不依赖模板参数的受限名，按
[temp.nondep] 在模板定义点（phase-1）即做名字查找与绑定，不要求 TIMG2COL
被实例化。因此任何包含该头文件的翻译单元都会在 phase-1 失败。

回归 2：B.DIM <立即数> Match Instruction Error

修补回归 1 后编译继续，撞到汇编期错误。来自工具链自身的 TLOAD/TMULS
模板，fa_opt 与参考内核 fa_2d_unroll_gmma 同样失败、模式一致：

template_asm.hpp:2027:6: error: Match Instruction Error!   "B.DIM %[VCOL], 0, ->lb0\n"
<inline asm>:2:1: B.DIM 128, 0, ->lb0        # TLOAD，valid_col=128
template_asm.hpp:2028:6: error: Match Instruction Error!   "B.DIM %[VROW], 0, ->lb1\n"
<inline asm>:3:1: B.DIM 128, 0, ->lb1        # TLOAD，valid_row=128
template_asm.hpp:8062:6: error: Match Instruction Error!   "B.DIM %2, 0, ->lb0\n"
<inline asm>:2:1: B.DIM 128, 0, ->lb0        # TMULS，valid_col=128
template_asm.hpp:8063:6: error: Match Instruction Error!   "B.DIM %3, 0, ->lb1\n"
<inline asm>:3:1: B.DIM 32, 0, ->lb1         # TMULS，valid_row=32 (tW: 32×128)
template_asm.hpp:169/170   B.DIM 128/32 ...   # 另一处 TLOAD 变体

被拒收的立即数值都是内核 tile 的有效维度（128、32），更新前同样源码可编译。

根因分析

回归 1

BLayout（enum class）与 LayoutCvtEnum（无作用域 enum）是两个不同枚举，
ND2M16/ND2M32 属于后者。template_asm.hpp:8950 把它们误写成 BLayout::
前缀（疑似从条件 BLayout::CubeM16 复制粘贴）。属头文件笔误，phase-1 命名查找
失败，阻断所有翻译单元。

回归 2

TLOAD（template_asm.hpp:2015-2041）等模板把 tile 的 valid_col/valid_row
以 "ri"（寄存器或立即数）约束送入 B.DIM 第一操作数：

const size_t valid_col = dst.GetValidCol();
const size_t valid_row = dst.GetValidRow();
asm volatile(
  "BSTART.TLSU TLOAD, %D[SrcType]\n"
  "B.DIM %[VCOL], 0, ->lb0\n"     // VCOL = "ri"(valid_col)
  "B.DIM %[VROW], 0, ->lb1\n"     // VROW = "ri"(valid_row)
  "B.DIM zero, %c[COL], ->lb2\n"  // COL = "i"(常量, 用 %c 修饰)
  ...

当 valid_col/valid_row 为编译期常量（fa_opt 的 128×128 Q/K/V、32×128 的
tW 等），LLVM 常量折叠把它物化为裸立即数，于是汇编文本变成
B.DIM 128, 0, ->lb0。新汇编器的指令 matcher 不再接受 B.DIM <立即数> 形式，
报 Match Instruction Error。

对照：同一指令第三行的 B.DIM zero, %c[COL], ->lb2 用 %c 修饰符输出常量
（B.DIM zero, 128, ->lb2），不报错——说明问题不在"128 这个值越界"，
而在"第一操作数位置出现裸立即数"这条匹配路径被新 matcher 移除/未实现。

波及面

• B.DIM %<...> + "ri" 模式在 template_asm.hpp 中有 284 处，其中约
  235 处带 "ri" 约束。这是工具链级约定，波及 TLOAD/TSTORE/TCVT/
  TMULS/TROWMAX/TROWSUM 等几乎所有 tile 操作模板。任何 valid 维度为
  编译期常量的内核都会命中。
• 参考内核 fa_2d_unroll_gmma（未改动）在新编译器下报与 fa_opt 完全相同
  的 B.DIM 128/32 错误，证明为工具链全局回归，与 fa_opt 实现无关。

责任归属

• 回归 1：Linx-TileOP-API 头文件笔误（template_asm.hpp:8950），属明确 bug。
• 回归 2：新汇编器后端的 B.DIM 指令 matcher 不接受第一操作数为立即数；
  与头文件 "ri" 约束共同作用触发。是后端 matcher 回归，还是头文件约束
  本应为 "r"（强制寄存器）而旧汇编器过于宽松，需工具链维护者定夺——但
  从用户内核侧无法规避（相关 B.DIM 全在工具链模板里）。

临时处理与建议修复

回归 1（已临时改对安装副本）

• 临时：已把 output/.../include/tileop-api/jcore/template_asm.hpp:8950 的
  BLayout::ND2M16/BLayout::ND2M32 改为 LayoutCvtEnum::ND2M16/
  LayoutCvtEnum::ND2M32。仅改了安装产物，重编工具链会被覆盖。
• 建议源侧修复：在工具链源对应文件作同样一行修正即可。

回归 2（未修，无法在内核侧规避）

二选一，由工具链维护者判定：

1. 汇编器后端恢复 B.DIM 第一操作数接受立即数（恢复旧 matcher 行为）；
2. 或将相关模板的 "ri" 约束改为 "r"（强制寄存器，规避物化为立即数）。
   该改动面大（约 235 处），但机械一致；需评估对代码生成质量的影响。

在回归 2 修复前，建议回滚本次工具链更新至可编译状态，以恢复日常构建与
gfrun 回归。

复现

cd /Users/blacktraker/Programming/gitproj/DV4/SuperNPUBench
export COMPILER_DIR=/Users/blacktraker/Programming/gitproj/DV4/linx-toolchain-build/output/linx_blockisa_llvm_musl/bin

# fa_opt（优化 FA 内核）
make -C benchmark/one-level-arch/test/kernel/multi_thread/fa diss \
    TESTCASE=fa_opt COMPILER_DIR="$COMPILER_DIR" FA_MODE=FP32_VECFP32 \
    Sq=256 Skv=256 Tm=128 Tk=128 X_dim=1 Y_dim=1 OBJ_ROOT=/tmp/fa_opt_v4

# 参考内核（未改动，更新前可编译）
make -C benchmark/one-level-arch/test/kernel/multi_thread/fa \
    TESTCASE=fa_2d_unroll_gmma COMPILER_DIR="$COMPILER_DIR" FA_MODE=FP32_VECFP32 \
    Sq=256 Skv=256 Tm=128 Tk=128 X_dim=1 Y_dim=1 OBJ_ROOT=/tmp/fa_ref_v4

# 观察：
#  - 回归1：template_asm.hpp:8950 no member named 'ND2M16' in 'pto::BLayout'
#  - 回归2：template_asm.hpp:2027/2028/8062/8063/169/170 Match Instruction Error
#           + <inline asm> B.DIM 128/32, 0, ->lb0|lb1
#  - 两者均出现在 fa_opt 与 fa_2d_unroll_gmma 上，模式一致。

附：fa_opt 侧未改动

fa_opt.hpp / fa_opt.cpp 与上一可编译状态（OBJ_ROOT=/tmp/fa_opt_v3，旧编译器）
一致，未为本次更新做任何调整；上一状态编译干净，反汇编已验证
TMATMUL=8, TCVT=0, B.TRB=0（无 transpose_b）。本次失败完全由工具链回归造成。

[VV0003]

两个回归都已在 linx 分支修复并合入，逐一回复：

回归 1:BLayout::ND2M16/32 笔误 — ✅ 已修复(PR #82,merge commit 67d47ab)

template_asm.hpp 中 TIMG2COL 处已改为 LayoutCvtEnum::ND2M16 : LayoutCvtEnum::ND2M32(你临时改安装副本的方向正确，源侧已同步修入)。你观察到的 phase-1 全 TU 阻断会随之消失。

回归 2:B.DIM <立即数> matcher 拒收 — ✅ 已修复(PR #82)

采用的不是 issue 里给的二选一，而是第三种(也是更优的)方案：逐维静态/动态双路径。"ri" 约束已在源头全部清除(全文件 0 处残留)，改为：

• 静态 valid 维度 → if constexpr 分支 + "i" 约束 + B.DIM zero, %c[imm] → 汇编器压缩为 C.B.DIMI(比旧 matcher 接受立即数更优：省指令字)
• 动态 valid 维度 → "r" 约束 + B.DIM %[reg], 0(issue 建议方案 2 的逐维精确版)
• lb2 固定 B.DIM zero, imm

97 个接口 × SS/SD/DS/DD 四组合穷举验证(PR #83,101 个实例化，0 编译错误)，反汇编形态矩阵：lb0/lb1 静态/动态对称出现，lb2 全部 C.B.DIMI,零非法形式。

用你的场景验证

按 issue 复现参数(Q/K/V 128×128、tW 32×128)直接实例化 TLOAD/TMULS:

BSTART.TLSU TLOAD, FP32
C.B.DIMI 128, ->lb0      # 原 B.DIM 128, 0 报错处,现为压缩立即数
C.B.DIMI 128, ->lb1
C.B.DIMI 128, ->lb2
...
C.B.DIMI 128, ->lb0      # TMULS 同理
C.B.DIMI 32,  ->lb1

ND2M16 与 B.DIM 128/32, 0 两类报错在 linx-llvm 主仓编译器下均为 0。

⚠️ 注意：BLK-build 编译器还有一个独立问题

如果 output/linx_blockisa_llvm_musl/bin/clang++ 还是旧构建，它会报另一个错：

invalid operand in inline asm: 'BSTART.TLSU TLOAD, ${2:D}'

这是该构建的 LinxV5AsmPrinter 缺 %D modifier(DataType 文本打印)实现，主仓 linx-llvm 编译器(带 case 'D' 的 %D 支持)没有此问题——与 #77 两个回归无关，是编译器构建差异，建议另开 issue 跟踪或用主仓编译器构建替换。

修复版本:linx @ 67d47ab(PR #82)+ PR #83(补充回归覆盖)。