【topk / radix-select】PTO ISA 与当前编译器 TileOP API 一致性对比（需修改 4 / 一致 1；含完整 top-K 抽取相的前置 API 缺口）

[liujiang833]

关联 #14（同一口径的 API 一致性核对，本 issue 聚焦 kernels/sort/topk）。

目的

以 kernels/sort/topk.hpp 用到的 tile-level 指令为基准，逐条比对当前编译器
tileop_api.hpp 的 C++ 接口与 PTO ISA 文档定义，识别 API 层面的不一致并推动编译器修改。

范围：只看编译器对外 API 签名层面的一致性（名称、参数、行为语义、类型支持、变体缺失）。
编译器内部如何实现（内联汇编 / SIMT / 块指令 / 模型支持）不作为判定依据。

PTO ISA 权威来源：github.com/hw-native-sys/pto-isa@main:include/pto/common/pto_instr.hpp
（文档站 pto-isa.github.io/.../thistogram 为 stub，不含签名，勿作来源）。

---

A. shipped 路径（topk 实际编译进 kernel 的指令）

#	类别	PTO ISA	当前编译器 API	需要的修改
A1	需要修改	THISTOGRAM	THISTOGRAM(dst, src, Idx, int ByteId)（在 jcore/template_asm.hpp）	① 字节选择 int ByteId → 模板枚举 HistByte byte（编译期）；② src/idx 拆成独立类型参数（现强制 src 与 Idx 同类型，无法表达 src=u16 + idx=u8）；③ 补 WaitEvents... + 返回 RecordEvent；④ 从裸汇编 helper 提升为标准 tileop_api.hpp 一等接口
A2		TLOAD	TCOPYIN(dst, src)	改名 TCOPYIN → TLOAD（参数/行为已一致）
A3		TSTORE	TCOPYOUT(dst, src)	改名 TCOPYOUT → TSTORE；补 AtomicType / preQuantScalar 参数
A4		TEXPANDS	TEXPANDSCALAR(dst, s)	改名 TEXPANDSCALAR → TEXPANDS（参数/行为已一致）
A5	完全一致	TADD	TADD(dst, src0, src1)	无差异

统计（shipped 路径）：需要修改 4 · 完全一致 1。

THISTOGRAM 签名对比

PTO ISA 权威签名（pto_instr.hpp:2360）：

template <HistByte byte, typename TileDataDst, typename TileDataSrc, typename TileDataIdx,
          typename... WaitEvents>
PTO_INST RecordEvent THISTOGRAM(TileDataDst &dst, TileDataSrc &src, TileDataIdx &idx,
                                WaitEvents &... events);
// 用法：THISTOGRAM<HistByte::BYTE_1>(dst, src, idx);   （src=u16 tile、idx=u8 tile）

当前编译器（jcore/template_asm.hpp:198）：

template <is_tile_data_v tile_shape_out, is_tile_data_v tile_shape_in>
void THISTOGRAM(tile_shape_out &dst, tile_shape_in &src, tile_shape_in &Idx, int ByteId);

维度	PTO ISA	当前编译器	需修改
字节选择	模板枚举 HistByte byte	运行值 int ByteId	✔
idx 类型	独立 TileDataIdx	与 src 共用 tile_shape_in	✔
事件	WaitEvents... + RecordEvent（内部 TSYNC(events...)）	无、返回 void	✔
操作数顺序/语义	(dst 256-bin 前缀累积, src 值, idx 前缀过滤)	一致	—
暴露位置	pto_instr.hpp 一等 intrinsic	仅 jcore/template_asm.hpp 裸汇编 helper	✔

注：PTO THISTOGRAM 无 tmp / PrecisionType 参数。

---

B. 贯穿性不一致（所有指令共通，最高影响面）

补齐 WaitEvents... / RecordEvent 事件模型：PTO 每条 intrinsic 内部首句都是
TSYNC(events...)，是强制约定；当前编译器 API 全线缺失（不带、返回 void）。
建议作为一次统一改造，而非逐条打补丁。

命名映射（需编译器改名以对齐 PTO）：
TCOPYIN→TLOAD、TCOPYOUT→TSTORE、TEXPANDSCALAR→TEXPANDS、TSELECT→TSEL（与 #14 #17–#20 一致）。

---

C. masked-select 抽取相（完整 top-K 的前置依赖）

当前 topk 只算到 threshold（第 K 大元素的“值”）并 O(1) 校验，未做真正的元素抽取
（masked_select 是未调用的标量参考代码）。要把 topk 补成完整 top-K，就需要
masked_select + gather + 局部排序 相，而其高效 tile-op 化卡在下列 API 缺口：

#	类别	PTO ISA	当前编译器 API	需要的修改
C1	需要修改	TCVT	TCVT(dst, src)	补 RoundMode / SaturationMode / tmp（同 #14 #10）
C2		TCMP + TCMPS	TCMP(dst, src0, src1, cmpMode)	补 WaitEvents；EQ 模式当前写死只支持 int32_t，需放宽到含 u16 等；新增 tile-标量比较变体 TCMPS
C3		TSEL	TSELECT(dst, cond, src0, src1)	改名 TSELECT → TSEL；补 tmp（PTO TSEL 用 packed predicate，需 tmp 解包缓冲；当前用 unpacked 掩码 tile）；补 WaitEvents

现状说明：旧硬阻塞（TCAST u16→u32 崩 ClockHands pass）已修复（TCAST 改走 TCVT 块指令）。
现在 tile-op 抽取“可行但很丑/低效”——需 TCAST u16→int32（绕 EQ 的 int32 限制）+
TEXPANDS 广播标量（绕无 TCMPS）+ TCMP 出掩码。补齐 C 档后即可干净、原生地 tile-op 化。

---

参考

• 本仓库对照文档：kernels/sort/TOPK_PTOISA_COMPLETENESS.md
• 当前编译器 API：Linx-TileOP-API/include/common/tileop_api.hpp、jcore/template_asm.hpp
• PTO ISA 权威源：hw-native-sys/pto-isa@main — include/pto/common/pto_instr.hpp
  （THISTOGRAM:2360）、用法样例 tests/npu/a5/src/st/testcase/thistogram/thistogram_kernel.cpp