@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ops-profiling/references/csv_fields_reference.md

@@ -0,0 +1,260 @@
+# msprof op CSV 字段完整参考
+
+数据来源: MindStudio 8.3.0 官方文档。适用于 Atlas A2/A3 训练系列产品和推理系列产品。
+
+> 字段名中 `ai*` 表示 `aic`（Cube Core）或 `aiv`（Vector Core），具体取决于算子类型。
+
+---
+
+## 目录
+
+1. [OpBasicInfo.csv](#1-opbasicinfocsv)
+2. [PipeUtilization.csv](#2-pipeutilizationcsv)
+3. [ArithmeticUtilization.csv](#3-arithmeticutilizationcsv)
+4. [Memory.csv](#4-memorycsv)
+5. [MemoryL0.csv](#5-memoryl0csv)
+6. [MemoryUB.csv](#6-memoryubcsv)
+7. [L2Cache.csv](#7-l2cachecsv)
+8. [ResourceConflictRatio.csv](#8-resourceconflictratiocsv)
+
+---
+
+## 1. OpBasicInfo.csv
+
+算子基本信息，首先查看此文件了解全局情况。
+
+| 字段名 | 含义 | 关注点 |
+|--------|------|--------|
+| Op Name | 算子名称 | — |
+| Op Type | 算子类型 | — |
+| Task Duration(us) | Task 总耗时（含调度+执行+响应），单位 us | **核心指标**，与理论耗时对比判定性能 |
+| Block Dim | Task 运行核数（开发者设置的逻辑核数） | 检查是否用满可用核数 |
+| Mix Block Dim | 混合算子从核 blockDim（非 Mix 算子显示 N/A） | 仅 A2/A3 |
+| Device ID | 运行使用的 NPU ID | — |
+| PID | 进程号 | — |
+| Current Freq | 当前运行频率 | **与 Rated Freq 对比**，确认是否满频 |
+| Rated Freq | 理论额定频率 | Current < Rated 说明 DVFS 降频 |
+
+---
+
+## 2. PipeUtilization.csv
+
+**最重要的文件**。各流水线单元的耗时和占比，用于判定瓶颈类型。
+
+每一行对应一个核（由 block_id + sub_block_id 标识）。
+
+### 公共字段
+
+| 字段名 | 含义 |
+|--------|------|
+| block_id | Task 运行切分数量（核数） |
+| sub_block_id | 每个 block 内的 Vector/Cube 核名称和序号 |
+| aic_time(us) | 每个 Cube Core 执行时间 |
+| aic_total_cycles | 每个 Cube Core 执行 cycle 总数 |
+| aiv_time(us) | 每个 Vector Core 执行时间 |
+| aiv_total_cycles | 每个 Vector Core 执行 cycle 总数 |
+
+### 流水线单元耗时和占比
+
+| 字段名 | 含义 | 瓶颈判定阈值 |
+|--------|------|-------------|
+| aiv_vec_time(us) | Vector 指令耗时 | — |
+| aiv_vec_ratio | Vector 指令 cycle 占比 | >50% = VEC Bound |
+| aic_cube_time(us) | Cube 指令耗时 | — |
+| aic_cube_ratio | Cube 指令 cycle 占比 | >40% 正常(MatMul)；VEC 算子应≈0 |
+| ai*_scalar_time(us) | Scalar 指令耗时 | — |
+| ai*_scalar_ratio | Scalar 指令 cycle 占比 | >30% = SCALAR Bound |
+| aic_fixpipe_time(us) | FixPipe 指令（L0C→GM/L1）耗时 | — |
+| aic_fixpipe_ratio | FixPipe cycle 占比 | >15% = **地址未对齐** |
+| aic_mte1_time(us) | MTE1（L1→L0A/L0B）耗时（不含等待） | — |
+| aic_mte1_ratio | MTE1 cycle 占比 | — |
+| ai*_mte2_time(us) | MTE2（GM→AICORE）耗时 | — |
+| ai*_mte2_ratio | MTE2 cycle 占比 | >50% = MTE2 Bound |
+| ai*_mte3_time(us) | MTE3（AICORE→GM）耗时 | — |
+| ai*_mte3_ratio | MTE3 cycle 占比 | — |
+| ai*_icache_miss_rate | ICache 缺失率 | >15% 需关注 |
+
+### 活跃带宽（仅 A2/A3）
+
+| 字段名 | 含义 |
+|--------|------|
+| aiv_mte2_active_bw(GB/s) | Vector 核 MTE2 活跃带宽 |
+| aiv_mte3_active_bw(GB/s) | Vector 核 MTE3 活跃带宽 |
+| aic_mte1_active_bw(GB/s) | Cube 核 MTE1 活跃带宽（需 MemoryDetail） |
+| aic_mte2_active_bw(GB/s) | Cube 核 MTE2 活跃带宽（需 MemoryDetail） |
+| aic_mte3_active_bw(GB/s) | Cube 核 MTE3 活跃带宽 |
+| aic_fixpipe_active_bw(GB/s) | Cube 核 FixPipe 活跃带宽 |
+
+---
+
+## 3. ArithmeticUtilization.csv
+
+Cube 和 Vector 类型指令的详细占比和计算量。
+
+### 公共字段
+
+同 PipeUtilization.csv（block_id, sub_block_id, aic_time, aiv_time 等）。
+
+### Cube 指令详情
+
+| 字段名 | 含义 |
+|--------|------|
+| aic_cube_ratio | Cube 指令 cycle 占比 |
+| aic_cube_fp16_ratio | Cube fp16 指令占比 |
+| aic_cube_int8_ratio | Cube int8 指令占比 |
+| aic_cube_fops | Cube 浮点运算总数（用于计算理论利用率） |
+| aic_cube_total_instr_number | Cube 指令总条数 |
+| aic_cube_fp_instr_number | Cube fp 类型指令条数 |
+| aic_cube_int_instr_number | Cube int 类型指令条数 |
+
+### Vector 指令详情
+
+| 字段名 | 含义 |
+|--------|------|
+| aiv_vec_ratio | Vec 指令 cycle 占比 |
+| aiv_vec_fp32_ratio | Vec fp32 指令占比 |
+| aiv_vec_fp16_ratio | Vec fp16 指令占比 |
+| aiv_vec_int32_ratio | Vec int32 指令占比 |
+| aiv_vec_int16_ratio | Vec int16 指令占比 |
+| aiv_vec_misc_ratio | Vec misc 类型指令占比 |
+| aiv_vec_fops | Vector 浮点运算总数 |
+
+---
+
+## 4. Memory.csv
+
+内存读写带宽和数据搬运量。
+
+### 带宽速率
+
+| 字段名 | 含义 |
+|--------|------|
+| aiv_gm_to_ub_bw(GB/s) | GM→UB 写入带宽 |
+| aiv_ub_to_gm_bw(GB/s) | UB→GM 写入带宽 |
+| aic_l1_read_bw(GB/s) | L1 读带宽 |
+| aic_l1_write_bw(GB/s) | L1 写带宽 |
+| ai*_main_mem_read_bw(GB/s) | 主存储器读带宽 |
+| ai*_main_mem_write_bw(GB/s) | 主存储器写带宽 |
+
+### 指令统计
+
+| 字段名 | 含义 |
+|--------|------|
+| aic_mte1_instructions | MTE1 指令条数 |
+| aic_mte1_ratio | MTE1 cycle 占比 |
+| ai*_mte2_instructions | MTE2 指令条数 |
+| ai*_mte2_ratio | MTE2 cycle 占比 |
+| ai*_mte3_instructions | MTE3 指令条数 |
+| ai*_mte3_ratio | MTE3 cycle 占比 |
+
+### 数据搬运量
+
+| 字段名 | 含义 |
+|--------|------|
+| read_main_memory_datas(KB) | 读主存储器总量 |
+| write_main_memory_datas(KB) | 写主存储器总量 |
+| GM_to_L1_datas(KB) | GM→L1 搬运量 |
+| L1_to_GM_datas(KB)(estimate) | L1→GM 搬运量（估算） |
+| L0C_to_L1_datas(KB) | L0C→L1 搬运量 |
+| L0C_to_GM_datas(KB) | L0C→GM 搬运量 |
+| GM_to_UB_datas(KB) | GM→UB 搬运量 |
+| UB_to_GM_datas(KB) | UB→GM 搬运量 |
+
+### 带宽利用率
+
+| 字段名 | 含义 | 达标标准 |
+|--------|------|---------|
+| GM_to_L1_bw_usage_rate(%) | GM→L1 带宽利用率 | >60% 良好 |
+| L1_to_GM_bw_usage_rate(%)(estimate) | L1→GM 带宽利用率 | >60% 良好 |
+| L0C_to_L1_bw_usage_rate(%) | L0C→L1 带宽利用率 | — |
+| L0C_to_GM_bw_usage_rate(%) | L0C→GM 带宽利用率 | — |
+| GM_to_UB_bw_usage_rate(%) | GM→UB 带宽利用率 | >60% 良好 |
+| UB_to_GM_bw_usage_rate(%) | UB→GM 带宽利用率 | >60% 良好 |
+
+---
+
+## 5. MemoryL0.csv
+
+L0A/L0B/L0C 读写带宽，主要关注 Cube 场景。
+
+| 字段名 | 含义 |
+|--------|------|
+| aic_l0a_read_bw(GB/s) | L0A 读带宽 |
+| aic_l0a_write_bw(GB/s) | L0A 写带宽 |
+| aic_l0b_read_bw(GB/s) | L0B 读带宽 |
+| aic_l0b_write_bw(GB/s) | L0B 写带宽 |
+| aic_l0c_read_bw_cube(GB/s) | Cube 从 L0C 读带宽 |
+| aic_l0c_write_bw_cube(GB/s) | Cube 向 L0C 写带宽 |
+
+---
+
+## 6. MemoryUB.csv
+
+Vector 和 Scalar 对 UB 的读写带宽。
+
+| 字段名 | 含义 |
+|--------|------|
+| aiv_ub_read_bw_vector(GB/s) | Vector 从 UB 读带宽 |
+| aiv_ub_write_bw_vector(GB/s) | Vector 向 UB 写带宽 |
+| aiv_ub_read_bw_scalar(GB/s) | Scalar 从 UB 读带宽 |
+| aiv_ub_write_bw_scalar(GB/s) | Scalar 向 UB 写带宽 |
+
+---
+
+## 7. L2Cache.csv
+
+L2 Cache 命中率数据。
+
+### Atlas A2/A3
+
+| 字段名 | 含义 | 达标标准 |
+|--------|------|---------|
+| ai*_write_cache_hit | 写 cache 命中次数 | — |
+| ai*_write_cache_miss_allocate | 写 cache 缺失重新分配次数 | — |
+| ai*_r*_read_cache_hit | 读 r* 通道 cache 命中次数 | — |
+| ai*_r*_read_cache_miss_allocate | 读 r* 通道缺失重新分配次数 | — |
+| ai*_write_hit_rate(%) | 写 cache 命中率 | >80% |
+| ai*_read_hit_rate(%) | 读 cache 命中率 | >80% |
+| ai*_total_hit_rate(%) | 读/写 cache 总命中率 | **>80% 良好，<50% 需优化** |
+
+---
+
+## 8. ResourceConflictRatio.csv
+
+UB 上的 bank group、bank conflict 和资源冲突占比。**上板独有数据，仿真无法获取。**
+
+### 核心冲突指标
+
+| 字段名 | 含义 | 达标标准 |
+|--------|------|---------|
+| aiv_vec_total_cflt_ratio | Vector 指令被阻塞的总占比 | **<5% 良好，>15% 严重** |
+| aiv_vec_bankgroup_cflt_ratio | 被 bankgroup 冲突阻塞占比（block stride 不合理） | <3% |
+| aiv_vec_bank_cflt_ratio | 被 bank 冲突阻塞占比（读写指针地址不合理） | <3% |
+| aiv_vec_resc_cflt_ratio | 被计算单元资源冲突阻塞占比 | <5% |
+| aiv_vec_mte_cflt_ratio | 被 MTE 冲突阻塞占比 | <3% |
+
+### 等待指标
+
+| 字段名 | 含义 |
+|--------|------|
+| aic_cube_wait_ratio | Cube 单元被阻塞占比 |
+| aiv_vec_wait_ratio | Vector 单元被阻塞占比 |
+| ai*_mte1_wait_ratio | MTE1 被阻塞占比 |
+| ai*_mte2_wait_ratio | MTE2 被阻塞占比 |
+| ai*_mte3_wait_ratio | MTE3 被阻塞占比 |
+
+### Bank Conflict 解读
+
+- **bankgroup 冲突**: UB 中每个 bank group 包含多个 bank。Vector 指令的 `block_stride` 设置不合理导致多次访问落入同一 bank group → 调整 block stride
+- **bank 冲突**: Vector 指令操作数的读写指针地址不合理，多个操作数命中同一 bank → 调整 UB 地址分配，添加 padding
+- **资源冲突**: 多个计算单元竞争同一执行单元 → 调整流水编排，错开不同计算单元的调度
+- **MTE 冲突**: Vector 和 MTE 操作竞争共享资源 → 调整数据搬运和计算的时序
+
+### 优化建议
+
+| 冲突类型 | 优化方向 |
+|---------|---------|
+| bankgroup_cflt 高 | 修改 block_stride（Vector API 的 repeatStride/blockStride 参数） |
+| bank_cflt 高 | 修改 UB tensor 起始地址，添加 padding 使不同操作数落入不同 bank |
+| resc_cflt 高 | 错开 Vector 和 Cube 调度，增加流水并行度 |
+| mte_cflt 高 | 错开 MTE2/MTE3 和 Vector 操作的执行时序 |

package/assets/ops-direct-invoke/skills/ops-profiling/references/msprof-guide.md

@@ -0,0 +1,252 @@
+# `msprof` 采集与分析
+
+> 使用各 CANN 自带的 `msprof`：多组 `--aic-metrics` + sample-based `aicore.db`，得到可分析的 `op_summary_*`、`per_core_cycles.csv` 与 `summary.txt`。
+
+---
+
+## 适用场景与分流
+
+使用 `msprof` 采集时，首先判断算子是否为 MC² 多 rank 算子：
+
+| 判定条件 | 采集流程 |
+|---------|---------|
+| 算子通过 `fork()` 创建多个子进程，各绑定不同 NPU 卡，子进程间通过 SHMEM UDMA / BarrierAll / CrossCoreFlag 协同通信（如 alltoall_matmul、allgather_matmul、matmul_reducescatter） | → **[MC² 多 rank 采集](#mc-多-rank-算子采集)**（本文末尾章节） |
+| 单卡算子或单进程多设备算子 | → 下文 Step 1～3 + 主 Bound 判定（常规流程） |
+
+> MC² 多 rank 算子的采集命令、数据结构、稳态取值方法与单卡有本质区别（跨 rank 同步、木桶效应），`msprof op` 不适用于此类算子。如果不确定算子是否为 MC²，先检查源码是否调用 `fork()` 和 `aclshmemx_*` API。
+
+---
+
+## Step 1：构建算子（如果有指定的调用方式，这一步可跳过）
+
+**直调算子**：
+
+```bash
+cd ops/{operator_name} && mkdir -p build && cd build && cmake .. && make -j
+```
+
+**aclnn 算子**：
+
+```bash
+bash build.sh --pkg --soc=ascend910b --ops={operator_name} --vendor_name=custom -j16
+./build_out/*.run --install-path=$CANN
+bash build.sh --run_example {operator_name} eager cust --vendor_name=custom
+```
+
+---
+
+## Step 2：采集
+
+原生 `msprof` 每次运行只支持一个 `--aic-metrics` 组，且 `op_summary_*.csv` 是 per-op 聚合值而非逐核。流程：
+
+1. 在正式采集前 warm-up N 次（规避 DVFS）
+2. 按顺序分别采集 7 组 `--aic-metrics`：`PipeUtilization`、`ArithmeticUtilization`、`Memory`、`MemoryL0`、`MemoryUB`、`L2Cache`、`ResourceConflictRatio`
+3. 额外跑一次 `--aic-mode=sample-based`，从 `device_0/sqlite/aicore.db`（`AICoreOriginalData.task_cyc`）拿到**逐核 cycle**
+4. 以 aicore_time / max_cycles 反推主频，把逐核 cycle 折算成 per-core 时长
+
+一键脚本：
+
+```bash
+# 位于 {skill_path}/scripts/msprof_profile_run.sh
+bash {skill_path}/scripts/msprof_profile_run.sh \
+     --warm-up=3 \
+     --output=./msprof_output \
+     -- ./demo arg1 arg2 ...
+```
+
+**关键点**：msprof 的 `op_summary.csv` **没有** `Current Freq/Rated Freq` 和逐核 `time(us)` 字段；逐核分析必须依赖 `PROF_Sample` 下的 `aicore.db`。采集落盘目录树见文末 **数据目录结构 → 临时输出**（根路径为 `--output` 下的 `PROF_GROUP_*`）。
+
+---
+
+## Step 3：归档 + 统计摘要
+
+```bash
+GROUP_DIR=$(ls -td <output_dir>/PROF_GROUP_* | head -1)
+
+python3 {skill_path}/scripts/msprof_perf_summary.py $GROUP_DIR ops/{operator_name}
+```
+
+脚本会：
+
+1. 在 `ops/{operator_name}/docs/perf/round_NNN/` 创建归档目录（轮次自动递增）
+2. 按目标 `Op Name` 在 7 份 `op_summary.csv` 里合并列，复制为 `op_summary_<Metric>.csv`
+3. 读 `PROF_Sample/.../aicore.db` 的 `task_cyc`，根据 `aicore_time(us)` 反推主频，换算每核耗时
+4. 输出 `summary.txt`，在全局统计之外附加「逐核负载均衡」段，例如：
+
+   ```
+   --- 逐核负载均衡 (sample-based aicore.db) ---
+     有效核数: 32  | 主频推算: 1.651 GHz (0.6058 ns/cycle)
+     min=185.93us  avg=193.13us  max=199.27us
+     (max-min)/max = 6.69%  ->  达标 (<10%)
+     Top-3 慢核: Core3=199.27us, ...
+     Top-3 快核: Core21=185.93us, ...
+     [提示] 前半段 core 均值 198.17us vs 后半段 188.10us，差距 5.99%
+            疑似两簇 (NUMA / L2 slice) 负载偏斜，建议尝试 block swat / 尾轮均衡策略。
+   ```
+
+5. 同步把 `per_core_cycles.csv` 归档到同目录，方便二次分析
+
+归档完成后即结束本 Step 的职责。下游从 `summary.txt`（含逐核负载均衡段）、`op_summary_*.csv`、`per_core_cycles.csv` 读取指标后，按 **下文「主 Bound 判定」** 推导**主 bound 档位**；算子族级细化与报告专有条目见 **`/ascendc-performance-optimization`**。
+
+---
+
+## 主 Bound 判定（msprof 归档）
+
+本节适用于 **`msprof` 经 Step 2～3 得到的归档目录**（`round_NNN/`）。判据与 `/ops-simulator` 流水图路径**同一套优先级表**，便于对接 `/ascendc-performance-optimization`。
+
+> MC² 多 rank 算子同样使用本节判定规则，但需额外注意 MTE2 污染问题（见 [MC² 特有分析](#mc-注意事项)）。
+
+### 输入与输出
+
+| 项目 | 说明 |
+|------|------|
+| **输入** | 从归档中的 `op_summary_*.csv`、`summary.txt` 等抽取的**单核侧**各流水线 **busy 占 case（或 task）总时长** 的百分比；口径须与 `/ops-simulator` 流水分析中的「占 case」可比 |
+| **不适用** | msprof 聚合指标**无**可对照流水图的气泡时间；报告中气泡列标注「不适用」，**不得**填写气泡数值 |
+| **输出** | **主 bound 档位**：`MTE2 BOUND` / `CUBE BOUND` / `VEC BOUND` / `FIXP BOUND` / `MTE3 BOUND` / `SCALAR BOUND` / **无 bound** |
+
+各流水线 busy 占比的**抽取与列映射**以本文 Step 3 产物及 [`csv_fields_reference.md`](csv_fields_reference.md) 为准；若归档 CSV 表头与文档示例不一致，**以实际表头为准**。
+
+### 判定规则（与 `/ops-simulator` 一致）
+
+在已得到各流水线 busy 占比后，**从上到下**匹配**第一条成立**：
+
+| 优先级 | Bound 类型 | 判断规则 |
+|--------|-----------|----------|
+| 1 | MTE2 BOUND | MTE2 busy 占 case > 80%，或（MTE2 在 8 条中占比最大且 > 70%） |
+| 2 | CUBE BOUND | CUBE busy 占 case > 80%，或（CUBE 在 8 条中占比最大且 > 70%） |
+| 3 | VEC BOUND | PUSHQ busy 占 case > 80% |
+| 4 | FIXP BOUND | FIXP busy 占 case > 80% |
+| 5 | MTE3 BOUND | MTE3 busy 占 case > 80% |
+| 6 | SCALAR BOUND | SCALAR busy 占 case > 80%，或 SCALARLDST busy 占 case > 80% |
+| — | **无 bound** | 以上条件均不满足 |
+
+「占比最大」比较对象为上述单元对应的统计。
+
+---
+
+## 数据目录结构
+
+### 临时输出（`msprof_profile_run.sh` 的 `--output` 目录下）
+
+```
+<output_dir>/PROF_GROUP_<YYYYMMDD_HHMMSS>/
+├── PROF_PipeUtilization/PROF_*/mindstudio_profiler_output/op_summary_*.csv
+├── PROF_ArithmeticUtilization/...
+├── PROF_Memory/...
+├── PROF_MemoryL0/...
+├── PROF_MemoryUB/...
+├── PROF_L2Cache/...
+├── PROF_ResourceConflictRatio/...
+└── PROF_Sample/PROF_*/device_0/sqlite/aicore.db   ← 逐核 task_cyc
+```
+
+### 持久归档
+
+```
+ops/{算子名}/docs/perf/
+├── round_001/
+│   ├── op_summary_PipeUtilization.csv
+│   ├── op_summary_ArithmeticUtilization.csv
+│   ├── op_summary_Memory.csv
+│   ├── op_summary_MemoryL0.csv
+│   ├── op_summary_MemoryUB.csv
+│   ├── op_summary_L2Cache.csv
+│   ├── op_summary_ResourceConflictRatio.csv
+│   ├── op_statistic_<Metric>.csv
+│   ├── task_time_<Metric>.csv
+│   ├── per_core_cycles.csv
+│   └── summary.txt
+└── ...
+```
+
+字段含义详见 [`csv_fields_reference.md`](csv_fields_reference.md)（按 `op_summary_*` 列名对齐同类指标）。
+
+---
+
+## 注意事项
+
+1. **必须 warm-up**：脚本默认 `--warm-up=3` 可调，避免 DVFS 影响首次运行
+2. **无频率字段**：`op_summary` 没有 `Current Freq/Rated Freq`；脚本通过 `aicore_time / max_cycles` 反推主频
+3. **MTE2/MTE3 带宽共享**：同时读写 GM 时总带宽共享，评估搬运段负载时宜按 MTE2、MTE3 合并字节量与平台带宽对照
+4. **小数据量场景**：数据量很小时头开销占比会很高，这不一定是算子问题
+5. **多核同地址访问**：多核同时读同一 512B 地址范围会被串行化，导致 MTE2 耗时异常
+
+---
+
+## MC² 多 rank 算子采集
+
+MC² 通算融合算子通过 fork 多个子进程实现多 rank 协同，每个 rank 绑定一张 NPU 卡。这类算子的性能采集与单卡算子**有本质区别**——通信开销需要跨卡交互才能真实体现，多 rank 间的 BarrierAll/CrossCoreFlag 同步使整体性能受制于最慢的 rank（木桶效应）。
+
+> **`msprof op`（msopprof）不适用于 MC² 多 rank 算子**——它设计用于单进程单设备，对 fork 程序的行为未定义，采集到的数据不可靠。
+
+### 采集命令
+
+```bash
+# MC² 多 rank 算子专用采集命令
+msprof --output={prof_dir} \
+       --ai-core=on \
+       --aic-mode=task-based \
+       --aic-metrics=PipeUtilization \
+       --task-time=on \
+       --ascendcl=on \
+       {code_dir}/build/{exe} {args...}
+```
+
+**关键参数说明**：
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `--aic-mode=task-based` | 固定 | task-based 模式确保每个 kernel launch 产生独立记录，而非聚合 |
+| `--aic-metrics=PipeUtilization` | 推荐 | 采集各流水线占比，用于瓶颈分析 |
+| `--task-time=on` | 固定 | 记录每次 kernel 的 Task Duration |
+| `--ascendcl=on` | 固定 | 采集 AscendCL 层信息 |
+
+### 多设备数据结构
+
+msprof 包裹 fork 程序时，会自动为每个活跃设备分别产出 profiling 数据：
+
+```
+{prof_dir}/
+├── PROF_{timestamp}_*/           # device 0
+│   └── mindstudio_profiler_output/
+│       └── op_summary_*.csv      # ← Task Duration(us) 在这里
+├── PROF_{timestamp}_*/           # device 1
+│   └── mindstudio_profiler_output/
+│       └── op_summary_*.csv
+├── PROF_{timestamp}_*/           # device 2
+│   └── ...
+└── PROF_{timestamp}_*/           # device 3
+    └── ...
+```
+
+每个 `op_summary_*.csv` 中每行对应一次 kernel launch。如果程序内部循环 10 次，则每个设备有 10 行。
+
+### 稳态取值
+
+MC² 算子 perf 模式下循环执行至少 10 次算子调用：
+
+1. **前 5 次为 warm-up**，丢弃
+2. **取后 5 次 Task Duration 的均值**作为该 rank 的稳态性能
+
+### 跨 rank 取最大值
+
+多 rank 协同算子存在**木桶效应**——所有 rank 通过 BarrierAll / CrossCoreFlag 同步，整体性能由**最慢的 rank** 决定.
+
+> 此方法适用于 MC² 算子的**所有**性能测试场景：基线 profiling、隔离测试、方案对比测试。
+
+### MC² 注意事项
+
+1. **必须用 `msprof` 而非 `msprof op`**：`msprof op` 对 fork 程序的采集行为未定义，数据不可靠
+2. **必须 warm-up**：前 5 次受 DVFS 和 L2 cache 预热影响，不可作为性能指标
+3. **必须取跨 rank max**：木桶效应决定整体性能由最慢 rank 决定，取平均会高估性能
+4. **隔离测试取 max 的正确性**：注释通信后某些 rank 的 Task Duration 可能极短，这是因为该 rank 无需等待通信同步。取 max 代表包含了完整同步等待的真实通信时间
+
+---
+
+## 相关资源
+
+| 文件 | 内容 |
+|------|------|
+| [`csv_fields_reference.md`](csv_fields_reference.md) | 字段定义和阈值（按 `op_summary_*` 列名对齐），供下游分析角色参考 |
+| `scripts/msprof_profile_run.sh` | 一键采集脚本（Step 2 调用） |
+| `scripts/msprof_perf_summary.py` | 归档 + 摘要 + 逐核负载均衡（Step 3 调用） |