cann-workbench 0.0.0-stage → 0.0.2-alpha

package/skills/asc-tools/tool-ops-tune/ops-family/references/common/tail_block_design.md

@@ -0,0 +1,268 @@
+# Tail Block / Data Alignment 优化设计
+
+## 1. 优化目标
+
+在 Convolution、Pooling、Gather 等算子中，输入数据量往往不能被核心数或 tile 大小整除，产生尾块（tail block）。Naive 实现采用固定 tile 处理，导致尾块访问越界、数据竞争或负载不均衡。
+
+本优化通过双轨制计算、向量化尾块处理、多维度 Tiling 尾块分离等手段，确保在所有场景下实现近完美的负载均衡和正确的边界处理。
+
+| 指标 | naive | optimized | 收益 |
+|------|-------|-----------|------|
+| 尾块处理 | 简单截断，可能越界 | 双轨制 norm/tail 核分离 | 避免数据竞争和越界访问 |
+| 尾块计算 | 标量循环处理 | GatherMask 向量化处理 | 一次处理 64 个元素，提升 4-8 倍 |
+| 多核负载 | 尾核空闲或超载 | 动态 costLimit + 容忍度机制 | 非整除场景性能提升 10-30% |
+| 内存对齐 | 未考虑对齐 | 32B/64B 对齐 + DataCopyPad | 避免非对齐访问性能损失 |
+
+
+## 2. 架构概览
+
+### 2.1 存储层级与数据流
+
+Tail Block 处理的数据流：输入数据经 MTE2 从 GM 搬入 UB/L1，分为正常块（normBlock）和尾块（tailBlock）。正常核处理 `defaultUbFactor` 整数倍的数据量，尾核处理剩余数据量。尾块使用 GatherMask 向量化处理或 DataCopyPad 对齐填充，结果经 MTE3 写回 GM，多核竞争场景使用 AtomicAdd 避免数据竞争。
+
+### 2.2 双轨制计算模型
+
+Host 侧将数据分为正常核（normCore）和尾核（tailCore）两组：
+- **正常核**：处理 `defaultUbFactor` 整数倍的数据量
+- **尾核**：处理剩余数据量，单独计算尾块循环次数和尾块大小
+
+Kernel 侧根据 `blockIdx_` 判断自己是正常核还是尾核，选择对应的循环参数。
+
+### 2.3 事件同步模型
+
+| 事件类型 | 含义 | 用途 |
+|---------|------|------|
+| `MTE2_V` | MTE2 搬运完成 → 允许 Vector 读取 | 主数据 tile 就绪 |
+| `V_MTE3` | Vector 完成 → 允许 MTE3 写回 | 尾块计算完成，可写 GM |
+| `PIPE_V` | Vector 管道屏障 | 向量化指令间数据依赖 |
+
+## 3. 关键参数配置
+
+```cpp
+// Host 侧 TilingData
+struct TailBlockTiling {
+    uint32_t normBlockLoop;           // 正常核循环次数
+    uint32_t normBlockTailLoopSize;   // 正常核最后循环大小
+    uint32_t tailBlockLoop;           // 尾核循环次数
+    uint32_t tailBlockTailLoopSize;   // 尾核最后循环大小
+    uint32_t defaultValueUsedCoreNum; // 正常核数量
+    uint32_t defaultUbFactor;         // 默认 UB 处理粒度
+};
+```
+
+### 3.1 Tile 大小选取原则
+
+| 参数 | 典型值 | 说明 |
+|------|--------|------|
+| `defaultUbFactor` | 64 / 128 / 256 | 向量化处理粒度，需对齐 Vector 单元宽度 |
+| `alignCoef` | 32B / 64B | 数据类型相关对齐系数（FP16=32B, FP32=64B） |
+
+**Ascend 对齐约束**：
+
+- Global Memory 访问需 32B 对齐
+- Vector 指令最优访问粒度为 32B（FP16）或 64B（FP32）
+- Cube 矩阵乘需 16x16 或 32x32 对齐
+
+```cpp
+// 对齐计算
+uint32_t numPerBlock = ONE_BLK_SIZE / sizeof(T);  // 32B / sizeof(T)
+uint32_t alignedSize = (size + numPerBlock - 1) / numPerBlock * numPerBlock;
+```
+
+### 3.2 内存预算
+
+尾块处理需要额外的 pattern buffer（用于 GatherMask）和索引 buffer：
+- `tmpPattern` buffer：约 64B（uint32_t/uint16_t pattern）
+- `indexBuf` buffer：6 个索引 × tile 大小（用于 adaptive pooling）
+
+## 4. 核心计算循环
+
+### 4.1 naive 版本（优化前）
+
+```cpp
+// 固定 tile 处理，无尾块特殊处理
+for (uint32_t i = 0; i < this->innerLoops; i++) {
+    CopyIn(i);
+    Compute(i);
+    CopyOut(i);
+}
+// 问题：最后一 tile 可能越界；尾核负载不均
+```
+
+### 4.2 optimized 版本（优化后）：双轨制尾块处理
+
+```cpp
+// Host 侧：计算 norm/tail 核参数
+normBlockLoop_ = Ops::Base::CeilDiv(normCoreHandleDefaultValues_, defaultUbFactor_);
+normBlockTailLoopSize_ = normCoreHandleDefaultValues_ - defaultUbFactor_ * (normBlockLoop_ - 1);
+tailBlockLoop_ = Ops::Base::CeilDiv(tailCoreHandleDefaultValues, defaultUbFactor_);
+tailBlockTailLoopSize_ = tailCoreHandleDefaultValues - defaultUbFactor_ * (tailBlockLoop_ - 1);
+
+// Kernel 侧：根据 blockIdx 选择参数
+loop_ = tilingData_.normBlockLoop;
+tailLoopSize_ = tilingData_.normBlockTailLoopSize;
+if (blockIdx_ == tilingData_.defaultValueUsedCoreNum - 1) {
+    loop_ = tilingData_.tailBlockLoop;
+    tailLoopSize_ = tilingData_.tailBlockTailLoopSize;
+}
+
+// 主循环
+for (uint32_t i = 0; i < loop_; i++) {
+    bool isLastLoop = (i == loop_ - 1);
+    uint32_t currentTileSize = isLastLoop ? tailLoopSize_ : defaultUbFactor_;
+
+    // 使用 DataCopyPad 处理非对齐尾块
+    if (isLastLoop && currentTileSize != defaultUbFactor_) {
+        DataCopyExtParams copyParams{1, static_cast<uint32_t>(currentTileSize * sizeof(T)), 0, 0, 0};
+        DataCopyPadExtParams<T> padParams{false, 0, 0, 0};
+        DataCopyPad(dataLocal, inTensorsGM[...], copyParams, padParams);
+    } else {
+        DataCopy(dataLocal, inTensorsGM[...], currentTileSize);
+    }
+
+    Compute(dataLocal, currentTileSize);
+    CopyOut(dataLocal, currentTileSize);
+}
+```
+
+### 4.3 GatherMask 向量化尾块处理
+
+```cpp
+// 对于最后一个输出点的尾块，使用 GatherMask 进行数据重排
+if constexpr (std::is_same_v<T, float>) {
+    LocalTensor<uint32_t> bufPattern = tmpPattern.Get<uint32_t>();
+    int32_t preLeftShift = numPerBlock + lastLeftShift;
+    bufPattern.SetValue(0, (1u << preLeftShift) - (1u << lastLeftShift));
+    GatherMask(outputLocal[gatherOffset], outputLocal[gatherOffset],
+               bufPattern, true, mask, {1, 1, 8, 8}, rsvdCnt);
+}
+// 避免 atomic 操作开销，正确处理尾块数据布局
+```
+
+### 4.4 非对齐数据的原子操作处理
+
+```cpp
+// 针对数据非 32B 对齐的情况，使用 AtomicAdd 避免数据竞争
+uint64_t mask0 = (1ul << numPerBlock) - (1ul << validDataLen);
+uint64_t mask[2] = {mask0, 0};
+Duplicate<T>(outputLocal, 0, mask, 1, 1, 1);
+SetAtomicAdd<T>();
+DataCopy(outputGlobal[offset], outputLocal, cTailAlign);
+SetAtomicNone();
+```
+
+## 5. 从 naive 到 tail_block 的关键修改点
+
+| 修改项 | naive（优化前） | tail_block（优化后） |
+|--------|---------------|---------------------|
+| 核类型 | 所有核处理相同数据量 | 双轨制：normCore + tailCore |
+| 尾块处理 | 简单截断或越界访问 | GatherMask 向量化 / DataCopyPad 对齐 |
+| 数据竞争 | 无保护，可能写冲突 | AtomicAdd / 边界跳过 |
+| 负载均衡 | 固定分配 | 动态 costLimit + 容忍度机制 |
+| 内存对齐 | 未考虑 | 32B/64B 对齐 + padding |
+| 索引计算 | 运行时除法/取模 | IndexBuffer 预计算复用 |
+
+## 6. 注意事项 / 约束
+
+1. **GatherMask 的 pattern buffer 类型**。float 类型用 uint32_t pattern，half/bfloat16_t 用 uint16_t pattern。
+
+2. **AtomicAdd 的性能开销**。虽然保证正确性，但 atomic 操作有一定性能损失，优先使用 GatherMask 避免竞争。
+
+3. **尾块大小必须 > 0**。若尾块大小为 0，该核应直接返回，避免空循环。
+
+4. **多维度 Tiling 的尾块**。每个维度（Channel、Spatial、Batch）都需独立计算尾块参数。
+
+5. **重叠检测**。Adaptive Pooling 中 kernel 可能重叠，需检测并设置 `isOverLap` 标志，使用 atomic add 保证正确性。
+
+6. **对齐填充的数据正确性**。SkipPad 策略需确保 padding 区域的 0 不会被错误计入后续计算（如方差）。
+
+7. **32B 对齐是硬性要求**。未对齐的 GM 访问可能导致硬件异常或性能下降。
+
+## 7. 实施常见问题与解决方案
+
+### Q1: 尾核处理量远小于正常核，导致尾核很快完成但需等待正常核
+**A**: 使用容忍度机制（tolerance ratio），允许轻微超载以减少碎片。`costLimit` 动态计算为"剩余总代价 / 剩余核数"。
+
+### Q2: GatherMask 的 pattern 计算错误导致数据重排异常
+**A**: 确保 `preLeftShift` 和 `lastLeftShift` 计算正确，pattern 值为 `(1u << preLeftShift) - (1u << lastLeftShift)`。
+
+### Q3: DataCopyPad 的 padding 值污染后续计算
+**A**: 使用 `SkipPadSubMean` 等策略跳过 padding 区域，或在计算前用 `Duplicate` 填充 padding 区域为中性值（如 0 或 MASK_VALUE）。
+
+### Q4: 多核场景下尾块原子加导致结果非确定性
+**A**: 使用确定性模式（deterministic mode），反向处理并检测边界索引冲突，跳过冲突索引由前一个核处理。
+
+## 8. 场景用例
+
+### 8.1 各算子族实例
+
+**Elementwise** `[1000, 128]`, tileRows=256，尾块 232 行，策略 1：
+
+```cpp
+uint32_t loopCount = (rows + tileRows - 1) / tileRows;
+for (uint32_t loop = 0; loop < loopCount; loop++) {
+    uint32_t curRows = (loop == loopCount - 1)
+                           ? (rows - loop * tileRows) : tileRows;
+    uint32_t curLen = curRows * cols;
+    DataCopy(xLocal, xGm[loop * tileRows * cols], curLen);
+    Adds(yLocal, xLocal, 1.0f, curLen);
+    DataCopy(yGm[loop * tileRows * cols], yLocal, curLen);
+}
+```
+
+**MatMul** `M=1023`, blockM=128，尾块 127 行，策略 2+1：
+
+```cpp
+// Host：双轨制分核
+uint32_t mPerCore = CeilDiv(M, coreNum);
+// Kernel：根据 blockIdx 确定 M 范围
+uint32_t localM = (blockIdx < coreNum - 1) ? mPerCore : M - blockIdx * mPerCore;
+uint32_t loopCount = (localM + blockM - 1) / blockM;
+for (uint32_t loop = 0; loop < loopCount; loop++) {
+    uint32_t curM = (loop == loopCount - 1) ? (localM - loop * blockM) : blockM;
+}
+```
+
+**FlashAttention** `seqLen=1025`, tileSeq=1024，尾块 1 行，策略 1+3：
+
+```cpp
+uint32_t kvLoopCount = (kvSeqLen + kvTileSize - 1) / kvTileSize;
+for (uint32_t kvLoop = 0; kvLoop < kvLoopCount; kvLoop++) {
+    uint32_t curKvLen = (kvLoop == kvLoopCount - 1)
+                            ? (kvSeqLen - kvLoop * kvTileSize) : kvTileSize;
+    if (curKvLen % 16 != 0) {  // Cube 输入需对齐
+        DataCopyPad(kLocal, kGm[...], copyParams, padParams);
+    }
+    if (isCausal && qLoop == kvLoopCount - 1) {
+        ApplyCausalMaskPartial(..., curKvLen);  // 尾块 causal mask
+    }
+}
+```
+
+---
+
+## 9. 选型决策与自检清单
+
+### 9.1 选型决策
+
+```
+if (算子包含迭代循环 && 数据量不能被 tile 大小整除):
+    → 启用 tail_block 优化
+    → 计算 normBlockLoop / tailBlockLoop
+    → 尾块使用 DataCopyPad 或 GatherMask
+    → 多核场景使用 AtomicAdd 或确定性模式
+else:
+    → 标准 tile 处理即可
+```
+
+### 9.2 自检清单
+
+- [ ] Host 侧正确计算 normBlockLoop / tailBlockLoop / normBlockTailLoopSize / tailBlockTailLoopSize
+- [ ] Kernel 侧根据 blockIdx_ 正确选择 norm/tail 参数
+- [ ] 尾块大小为 0 时核直接返回
+- [ ] DataCopyPad 参数正确（blockCount, blockLen, srcStride, dstStride）
+- [ ] GatherMask pattern 类型与数据类型匹配（float→uint32_t, half→uint16_t）
+- [ ] 32B/64B 对齐约束满足
+- [ ] AtomicAdd 在 SetAtomicAdd / SetAtomicNone 配对内使用
+- [ ] 确定性模式下反向处理和边界检测正确
+- [ ] 精度校验通过：与 naive 实现对比，误差 < 1e-5（FP32）或 < 1e-3（FP16）

package/skills/asc-tools/tool-ops-tune/ops-family/references/common/timing_harness/index.md

@@ -0,0 +1,38 @@
+# timing_harness — 计时口径货架
+
+> snapshot.py `--kernel-avg-us` 的第一生产者。此前的状态：口径纪律只在
+> ops-collect SKILL.md 计时口径表（文字），无自带 benchmark 的工程要靠
+> agent 手写计时代码——短 kernel launch 开销掩盖收益是最高频的坑。
+> 本目录把「warmup 剔除 + 稳态 ≥3 取中位 + 多 launch 单 event」从纪律变成拷模板。
+
+## 模板清单
+
+| 模板 | 适用 | 产物 |
+|------|------|------|
+| [`timing_harness_aclrt_event.cpp`](timing_harness_aclrt_event.cpp) | C++ Kernel 直调工程（无自带 benchmark 时的标配） | `result.json`（opstune.timing/1.0：kernel_avg_us + p50/p95/max + 逐轮值） |
+| [`timing_harness_torch_event.py`](timing_harness_torch_event.py) | torch_npu 侧（torch.ops 调用形态 / torch 工程对标） | 同上 |
+
+## 使用纪律（模板拷贝纪律同款：直接拷贝 + 最小适配）
+
+1. 拷模板入工程（`test/` 或根目录），只改 `[MODIFY]` 标注点
+   （被测调用 + 设备/链接），**计时结构（warmup/repeat/多 launch 单 event/取中位）
+   不许改**——改了口径，前后对比全部失效；
+2. 输入输出分配放 `setup()`（循环外），`run_once()` 只留 launch；
+3. `warmup/repeat` 是 HARD 口径字段：与 scope.json 一致；噪声带内复测时
+   repeat 翻倍并**同步重采基线**（delta_compare 会拒绝单侧口径漂移）；
+4. 产物 `result.json` 的数值直接喂 snapshot.py：
+   `--kernel-avg-us <avg> --timing-method event --kernel-p50-us ... --kernel-p95-us ...`。
+
+## 何时不用本货架
+
+- 工程自带正式 benchmark → 视为正式口径，按优先级采信（ops-collect 计时口径表第 1 行）；
+- 长 kernel（ms 级）无 event 设施 → 允许 Task Duration 作基线，
+  `--timing-method msprof_task_duration` 并在报告注明（表第 3 行）；
+- torch_npu.profiler 路径 → 见 tool-routing 决策树⑤（schedule 固定 5/5）。
+
+## 复制目录带入优化副本（perf-implementer 联动）
+
+perf-implementer「复制目录」步骤把本 harness 视为**测量设施**带入优化副本
+（非优化变量）——基线与优化侧同一 harness、同一 warmup/repeat，口径两侧同源；
+对照 ops-collect SKILL.md「允许在产物目录工程副本补 aclrtEvent harness
+（属测量设施而非优化变量），原基线源码先备份」。

package/skills/asc-tools/tool-ops-tune/ops-family/references/common/timing_harness/timing_harness_aclrt_event.cpp

@@ -0,0 +1,199 @@
+// ----------------------------------------------------------------------------------------------------------
+// Copyright (c) 2026 Huawei Technologies Co., Ltd.
+// This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+// CANN Open Software License Agreement Version 2.0 (the "License").
+// Please refer to the License for details. You may not use this file except in compliance with the License.
+// THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+// INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+// See LICENSE in the root of the software repository for the full text of the License.
+// ----------------------------------------------------------------------------------------------------------
+
+// timing_harness_aclrt_event.cpp — 短 kernel 计时模板（aclrtEvent 多 launch 单 event）
+//
+// 对应：（计时 harness 货架）；ops-collect SKILL.md 计时口径表
+// 「短 kernel（µs 级）launch 开销掩盖收益：stream 内多 launch 单 event 对计时」的
+// 可拷贝实现。snapshot.py --kernel-avg-us 的第一生产者。
+//
+// 结构（固定，禁改动语义）：
+//   warmup 轮剔除（默认 5，冷跑与稳态实测可差 25%）→ 稳态 repeat ≥3 轮
+//   → 每轮 event 差值 → 取中位数（对离群轮稳健）。p50/p95/max 一并产出，
+//   直接对齐 snapshot.py 可选分布字段（抖动诊断的数据源）。
+//
+// 集成方式（模板拷贝纪律：直接拷贝 + 最小适配，两处 [MODIFY]）：
+//   1. 把本文件拷入算子工程（如 test/ 或根目录）；
+//   2. [MODIFY-1] 替换 RUN_ONCE 为被测 kernel 的一次完整调用
+//      （含全部输入输出分配与初始化——分配留在循环外，只计时 launch+执行）；
+//   3. [MODIFY-2] 按 CMake 链接 aclrt / ascendcl；
+//   4. 编译运行，result.json 即可直接喂 snapshot.py。
+//
+// 产物契约（opstune.timing/1.0）：kernel_avg_us = 稳态中位数；分布字段 p50/p95/max。
+
+#include <acl/acl.h>
+#include <algorithm>
+#include <chrono>
+#include <cstdio>
+#include <cstring>
+#include <fstream>
+#include <sstream>
+#include <string>
+#include <vector>
+
+namespace {
+
+constexpr int32_t kDeviceId = 0;   // [MODIFY-2] 目标设备
+constexpr int kWarmupDefault = 5;  // 固定 warmup 剔除（口径字段，须与 scope.json 一致）
+constexpr int kRepeatDefault = 20; // 稳态轮数（口径字段；噪声带内复测时翻倍并同步重采基线）
+
+// ---------------------------------------------------------------------------
+// [MODIFY-1] 被测算子的一次完整调用：替换为真实的 kernel launch。
+// 输入输出张量的分配与初始化应放在 setup()（循环外），此处只保留 launch，
+// 否则计时里混入 malloc/初始化，口径失效。
+// ---------------------------------------------------------------------------
+struct BenchContext {
+    aclrtStream stream = nullptr;
+    // 示例占位：int8_t *devIn, *devOut; size_t inBytes, outBytes;
+};
+
+bool setup(BenchContext& ctx)
+{
+    // 示例形态（按算子实际 shape/dtype 修改）：
+    //   aclrtMalloc(&ctx.devIn, ctx.inBytes, ACL_MEM_MALLOC_HUGE_FIRST);
+    //   ... 初始化输入（host→device 拷贝）...
+    (void)ctx;
+    return true;
+}
+
+bool run_once(BenchContext& ctx)
+{
+    // 示例形态：
+    //   return RunKernelLaunch(ctx.devIn, ctx.devOut, shape, ctx.stream) == 0;
+    (void)ctx;
+    return true;
+}
+
+void teardown(BenchContext& ctx)
+{
+    // 示例形态：aclrtFree(ctx.devIn); ...
+    (void)ctx;
+}
+
+double median(std::vector<double> v)
+{
+    if (v.empty())
+        return 0.0;
+    std::sort(v.begin(), v.end());
+    size_t n = v.size();
+    return (n % 2 == 1) ? v[n / 2] : (v[n / 2 - 1] + v[n / 2]) / 2.0;
+}
+
+double pct(std::vector<double>& v, double p)
+{
+    if (v.empty())
+        return 0.0;
+    std::sort(v.begin(), v.end());
+    size_t idx = static_cast<size_t>(p * (v.size() - 1) + 0.5);
+    return v[idx];
+}
+
+} // namespace
+
+int main(int argc, char** argv)
+{
+    int warmup = kWarmupDefault, repeat = kRepeatDefault;
+    const char* outPath = nullptr; // 必填 --output（结果路径由调用方指定）
+    for (int i = 1; i + 1 < argc; ++i) {
+        if (!std::strcmp(argv[i], "--warmup"))
+            warmup = std::atoi(argv[i + 1]);
+        if (!std::strcmp(argv[i], "--repeat"))
+            repeat = std::atoi(argv[i + 1]);
+        if (!std::strcmp(argv[i], "--output"))
+            outPath = argv[i + 1];
+    }
+    if (outPath == nullptr) {
+        std::fprintf(stderr, "ERROR: --output <path> 必填（结果 JSON 路径由调用方指定）\n");
+        return 1;
+    }
+    if (repeat < 3) {
+        std::fprintf(stderr, "ERROR: repeat >= 3（稳态采样下限，SKILL.md 计时口径）\n");
+        return 1;
+    }
+
+    if (aclInit(nullptr) != ACL_SUCCESS) { /* 已初始化场景（宿主先 aclInit）容忍 */
+    }
+    ACL_CHECK(aclrtSetDevice(kDeviceId));
+    BenchContext ctx;
+    ACL_CHECK(aclrtCreateStream(&ctx.stream));
+    if (!setup(ctx)) {
+        std::fprintf(stderr, "ERROR: setup 失败（检查输入分配/初始化）\n");
+        return 1;
+    }
+
+    // ---- warmup 轮（剔除冷跑：首次含初始化与缓存预热）----
+    for (int i = 0; i < warmup; ++i) {
+        if (!run_once(ctx)) {
+            std::fprintf(stderr, "ERROR: warmup run 失败\n");
+            return 1;
+        }
+    }
+    ACL_CHECK(aclrtSynchronizeStream(ctx.stream));
+
+    // ---- 稳态轮：多 launch 单 event 对计时（短 kernel：单 launch 的 event 分辨率
+    //      与 launch 开销都会掩盖收益；一轮 = N 次 launch 用首尾 event 差值 / N）----
+    constexpr int kLaunchPerRound = 10; // 每轮内 launch 数（按 kernel 时长调整：总时长 ≥ 100us 为宜）
+    std::vector<double> perLaunchUs;
+    aclrtEvent evStart, evEnd;
+    ACL_CHECK(aclrtCreateEvent(&evStart));
+    ACL_CHECK(aclrtCreateEvent(&evEnd));
+    for (int r = 0; r < repeat; ++r) {
+        ACL_CHECK(aclrtRecordEvent(evStart, ctx.stream));
+        for (int i = 0; i < kLaunchPerRound; ++i) {
+            if (!run_once(ctx)) {
+                std::fprintf(stderr, "ERROR: steady run 失败\n");
+                return 1;
+            }
+        }
+        ACL_CHECK(aclrtRecordEvent(evEnd, ctx.stream));
+        ACL_CHECK(aclrtSynchronizeStream(ctx.stream));
+        float ms = 0.0f;
+        ACL_CHECK(aclrtEventElapsedTime(&ms, evStart, evEnd));
+        perLaunchUs.push_back(static_cast<double>(ms) * 1000.0 / kLaunchPerRound);
+    }
+    ACL_CHECK(aclrtDestroyEvent(evStart));
+    ACL_CHECK(aclrtDestroyEvent(evEnd));
+
+    // ---- 统计与落盘（opstune.timing/1.0；直接对齐 snapshot.py 输入字段）----
+    std::vector<double> sorted = perLaunchUs;
+    const double p50 = median(perLaunchUs);
+    const double p95 = pct(sorted, 0.95);
+    const double maxv = sorted.back();
+    const double avg = p50; // 口径：kernel_avg_us = 稳态中位数（对离群轮稳健）
+
+    std::ostringstream os;
+    os << "{\n"
+       << "  \"schema\": \"opstune.timing/1.0\",\n"
+       << "  \"timing_method\": \"event\",\n"
+       << "  \"harness\": \"aclrtEvent multi-launch single-pair\",\n"
+       << "  \"launch_per_round\": " << kLaunchPerRound << ",\n"
+       << "  \"warmup\": " << warmup << ",\n"
+       << "  \"repeat\": " << repeat << ",\n"
+       << "  \"kernel_avg_us\": " << avg << ",\n"
+       << "  \"kernel_p50_us\": " << p50 << ",\n"
+       << "  \"kernel_p95_us\": " << p95 << ",\n"
+       << "  \"kernel_max_us\": " << maxv << ",\n"
+       << "  \"per_round_us\": [";
+    for (size_t i = 0; i < perLaunchUs.size(); ++i) {
+        os << (i ? ", " : "") << perLaunchUs[i];
+    }
+    os << "]\n}\n";
+    std::ofstream f(outPath);
+    f << os.str();
+    std::printf(
+        "kernel_avg_us(p50)=%.3f  p95=%.3f  max=%.3f  (warmup=%d repeat=%d × %d launch)\n", avg, p95, maxv, warmup,
+        repeat, kLaunchPerRound);
+    std::printf("→ %s（喂 snapshot.py：--kernel-avg-us %.3f --timing-method event ...）\n", outPath, avg);
+
+    teardown(ctx);
+    ACL_CHECK(aclrtDestroyStream(ctx.stream));
+    ACL_CHECK(aclrtResetDevice(kDeviceId));
+    return 0;
+}

package/skills/asc-tools/tool-ops-tune/ops-family/references/common/timing_harness/timing_harness_torch_event.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+# timing_harness_torch_event.py — torch_npu 侧 event 计时模板（短 kernel 多 launch 单 event）
+#
+# 对应：timing_harness/index.md 的 torch 形态。
+# 与 C++ 模板同一结构：warmup 剔除 → 稳态 repeat ≥3 → 每轮 N 次 launch 用首尾
+# event 差值 / N → 取中位；p50/p95/max 一并产出（snapshot.py 分布字段数据源）。
+#
+# 集成方式（模板拷贝纪律：直接拷贝 + 最小适配，仅 [MODIFY] 一处）：
+#   1. 拷入 torch 工程测试目录；
+#   2. [MODIFY] run_once() 替换为被测调用（torch.ops.npu.xxx / torch.nn.functional.xxx）；
+#   3. python3 timing_harness_torch_event.py --warmup 5 --repeat 20 --output result.json
+#
+# 产物契约：opstune.timing/1.0（与 C++ 模板同 schema，字段同名同义）。
+
+import argparse
+import json
+import statistics
+from pathlib import Path
+
+SCHEMA = "opstune.timing/1.0"
+
+
+# ---------------------------------------------------------------------------
+# [MODIFY] 被测算子的一次完整调用：替换为真实的 torch 调用。
+# 张量分配与初始化放 setup_tensors()（循环外），此处只留调用——
+# 否则计时混入 malloc/初始化，口径失效。
+# ---------------------------------------------------------------------------
+def setup_tensors(device: str):
+    """示例形态（按算子实际输入修改）：
+    import torch, torch_npu
+    x = torch.randn(8448, 4096, dtype=torch.float16, device=device)
+    return (x,)
+    """
+    return ()
+
+
+def run_once(tensors) -> None:
+    """示例形态：
+    torch.ops.npu.gelu(x)   # 或 F.gelu(x) 对标原生
+    """
+    _ = tensors
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="torch_npu event 计时（短 kernel 多 launch 单 event）"
+    )
+    ap.add_argument("--warmup", type=int, default=5)
+    ap.add_argument("--repeat", type=int, default=20)
+    ap.add_argument(
+        "--launch-per-round",
+        type=int,
+        default=10,
+        help="每轮 launch 数（总时长 ≥100us 为宜；短 kernel 摊薄 launch 开销）",
+    )
+    ap.add_argument("--device", default="npu:0")
+    ap.add_argument("--output", required=True, help="结果 JSON 路径（由调用方指定）")
+    args = ap.parse_args()
+    if args.repeat < 3:
+        print("ERROR: repeat >= 3（稳态采样下限，ops-collect 计时口径表）", flush=True)
+        return 1
+
+    import torch  # noqa: F401  （模板运行环境：torch + torch_npu）
+    import torch_npu  # noqa: F401
+
+    dev = torch.device(args.device)
+    tensors = setup_tensors(dev)
+
+    # ---- warmup 轮（剔除冷跑：首次含初始化与缓存预热，实测可差 25%）----
+    for _ in range(args.warmup):
+        run_once(tensors)
+    torch.npu.synchronize()
+
+    # ---- 稳态轮：多 launch 单 event 对（Event 记时在 device 侧，不含 host 抖动）----
+    per_round_us: list[float] = []
+    ev_start = torch.npu.Event(enable_timing=True)
+    ev_end = torch.npu.Event(enable_timing=True)
+    for _ in range(args.repeat):
+        ev_start.record()
+        for _ in range(args.launch_per_round):
+            run_once(tensors)
+        ev_end.record()
+        torch.npu.synchronize()
+        per_round_us.append(
+            ev_start.elapsed_time(ev_end) * 1000.0 / args.launch_per_round
+        )
+
+    p50 = statistics.median(per_round_us)
+    srt = sorted(per_round_us)
+    p95 = srt[min(int(0.95 * (len(srt) - 1) + 0.5), len(srt) - 1)]
+    mx = srt[-1]
+
+    result = {
+        "schema": SCHEMA,
+        "timing_method": "event",
+        "harness": "torch_npu.Event multi-launch single-pair",
+        "launch_per_round": args.launch_per_round,
+        "warmup": args.warmup,
+        "repeat": args.repeat,
+        "kernel_avg_us": round(p50, 3),  # 口径：kernel_avg_us = 稳态中位数
+        "kernel_p50_us": round(p50, 3),
+        "kernel_p95_us": round(p95, 3),
+        "kernel_max_us": round(mx, 3),
+        "per_round_us": [round(v, 3) for v in per_round_us],
+    }
+    out = Path(args.output)
+    out.write_text(
+        json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    print(
+        f"kernel_avg_us(p50)={p50:.3f}  p95={p95:.3f}  max={mx:.3f}"
+        f"  (warmup={args.warmup} repeat={args.repeat} × {args.launch_per_round} launch)"
+    )
+    print(
+        f"→ {out}（喂 snapshot.py：--kernel-avg-us {p50:.3f} --timing-method event ...）"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())