Skip to content

Ascend/msagent / skills/operator/ops-performance-tuning

ops-performance-tuning

Verified

Compile, profile, diagnose, optimize, and compare Ascend NPU operators across CANN versions and A2/A3/A5 for Ascend C, CATLASS, Triton-Ascend, TileLang-Ascend, PyPTO, and SHMEM/MC2. Use when an operator already has a runnable implementation and the user asks for msOpProf collection, bottleneck analysis, source-level tuning, or a reproducible before/after performance report. Do not use as the primary workflow for operator creation, migration, or unresolved correctness failures.

FileKindSize
SKILL.mdskill md15.4 KB
evals/evals.jsonconfig3.6 KB
references/case-routing.mdmarkdown30.0 KB
references/cases/ascendc/pr_ascendc_allgathermm_scalar_align.mdmarkdown1.7 KB
references/cases/ascendc/pr_ascendc_cann_samples_perf_story.mdmarkdown3.9 KB
references/cases/ascendc/pr_ascendc_cgdr_vf_inverse.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_conv3ddx_tque_tbuf.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_layernorm_areg.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_logit_a5_microapi.mdmarkdown1.9 KB
references/cases/ascendc/pr_ascendc_matmul_case_18x.mdmarkdown1.5 KB
references/cases/ascendc/pr_ascendc_matmul_full_load_wiki.mdmarkdown1.6 KB
references/cases/ascendc/pr_ascendc_matmul_vcv_wiki.mdmarkdown1.8 KB
references/cases/ascendc/pr_ascendc_mc2_fusion.mdmarkdown1.4 KB
references/cases/ascendc/pr_ascendc_mhc_24x.mdmarkdown1.2 KB
references/cases/ascendc/pr_ascendc_msopprof_add_block_imbalance.mdmarkdown1.7 KB
references/cases/ascendc/pr_ascendc_quantize_a2_micro_opt.mdmarkdown2.0 KB
references/cases/ascendc/pr_ascendc_rotate_quant_blaze.mdmarkdown2.8 KB
references/cases/ascendc/pr_ascendc_tiling_l2_official.mdmarkdown1.6 KB
references/cases/catlass/pr_catlass_baseline.mdmarkdown1.3 KB
references/cases/catlass/pr_catlass_fixpipe_dualdst.mdmarkdown1.6 KB
references/cases/catlass/pr_catlass_grouped_matmul_tiling.mdmarkdown1.5 KB
references/cases/catlass/pr_catlass_mstuner_3p8x.mdmarkdown1.9 KB
references/cases/catlass/pr_catlass_swizzle_balance.mdmarkdown1.6 KB
references/cases/pypto/pr_pypto_gqa_decode_vector_merge.mdmarkdown2.4 KB
references/cases/pypto/pr_pypto_l2_hit_layout_s13.mdmarkdown1.9 KB
references/cases/pypto/pr_pypto_per_matmul_tile_shapes.mdmarkdown2.4 KB
references/cases/pypto/pr_pypto_small_shape_matmul.mdmarkdown2.3 KB
references/cases/pypto/pr_pypto_weight_none_cacheable.mdmarkdown2.6 KB
references/cases/shmem/pr_shmem_alltoallv_mr152.mdmarkdown2.4 KB
references/cases/shmem/pr_shmem_reduce_scatter_serial.mdmarkdown2.6 KB
references/cases/tilelang/pr_tilelang_benchmark_vs_ascendc.mdmarkdown1.7 KB
references/cases/tilelang/pr_tilelang_compiler_prs.mdmarkdown2.3 KB
references/cases/tilelang/pr_tilelang_fa_pr698.mdmarkdown1.5 KB
references/cases/tilelang/pr_tilelang_gqa_bwd_pr1494.mdmarkdown1.3 KB
references/cases/tilelang/pr_tilelang_persistent_mqa_decode.mdmarkdown2.2 KB
references/cases/tilelang/pr_tilelang_sfa_pr665.mdmarkdown914 B
references/cases/triton/pr_triton_atomic_simd_24x.mdmarkdown1.8 KB
references/cases/triton/pr_triton_autotune_background.mdmarkdown1.0 KB
references/cases/triton/pr_triton_constexpr_recompile.mdmarkdown1.1 KB
references/cases/triton/pr_triton_lgamma_simt.mdmarkdown1.6 KB
references/compile/compile-ascendc.mdmarkdown9.0 KB
references/compile/compile-catlass.mdmarkdown2.4 KB
references/compile/compile-pypto.mdmarkdown2.0 KB
references/compile/compile-shmem.mdmarkdown2.6 KB
references/compile/compile-tilelang.mdmarkdown2.7 KB
references/compile/compile-triton.mdmarkdown4.4 KB
references/diagnose/diagnose-l2-cache.mdmarkdown2.2 KB
references/diagnose/diagnose-occupancy.mdmarkdown4.0 KB
references/diagnose/diagnose-pipeline.mdmarkdown4.1 KB
references/diagnose/diagnose-roofline.mdmarkdown3.1 KB
references/optimize/optimize-api-usage.mdmarkdown1.7 KB
references/optimize/optimize-ascendc-regbase-vf.mdmarkdown5.9 KB
references/optimize/optimize-ascendc-tiling.mdmarkdown935 B
references/optimize/optimize-catlass.mdmarkdown3.0 KB
references/optimize/optimize-data-copy.mdmarkdown870 B
references/optimize/optimize-index.mdmarkdown3.6 KB
references/optimize/optimize-memory-hierarchy.mdmarkdown599 B
references/optimize/optimize-pipeline.mdmarkdown1.0 KB
references/optimize/optimize-pypto.mdmarkdown1.5 KB
references/optimize/optimize-shmem.mdmarkdown5.1 KB
references/optimize/optimize-tilelang.mdmarkdown1.7 KB
references/optimize/optimize-triton.mdmarkdown3.8 KB
references/profile/benchmark-harness.mdmarkdown2.2 KB
references/profile/profile-msopprof.mdmarkdown7.4 KB
references/troubleshooting.mdmarkdown5.8 KB
scripts/bound_analyzer.pyscript9.0 KB
scripts/delta_report.pyscript4.8 KB
scripts/env_check.shscript5.0 KB
scripts/result_saver.pyscript5.0 KB

references/diagnose/diagnose-occupancy.md

View on GitHub
# occupancy(核间负载分析)

> occupancy(§2):msOpProf `--aic-metrics=Occupancy` 的核间负载分析;工具总览与五类对照表见 [msOpProf 采集指南](../profile/profile-msopprof.md)。

## 1. 特性介绍

occupancy 特性用于**核间负载分析**:判断多核之间任务分配是否均衡、是否存在部分核空转。当前官方用户指南列出 A2/A3/A5 支持;安装版本仍须以本机 `--help` 为准。

> **说明**:没有以 "occupancy" 命名的独立工具;该能力以 msOpProf 的 `--aic-metrics=Occupancy` 选项形式出现。

## 2. 特性功能

- **输出文件**:与 msOpProf 归档一同产出(`visualize_data.bin` 可用 MindStudio Insight 看热力图);输出文件名随版本变化,必须从本次输出目录识别。
- **判读**:怀疑核间不均衡时开启;推荐分析路径"先看 Default 基础指标 → 开 Roofline 判 bound 类型 → 偏内存看 Memory.csv/MemoryDetail → 怀疑核间不均衡开 Occupancy → 看 MTE 与 VECTOR/CUBE 是否并行、有无 bubble"。
- **其他出现形式**:核间负载不均衡也作为 10 类瓶颈之一判读(无独立 occupancy 指标,靠 PipeUtilization 等交叉诊断);SHMEM 侧用 SHMEMI_PROF frame 的 `max_core_us` vs `avg_us` 观察核间差异;PyPTO 侧以"负载均衡度"指标出现。

## 3. 如何使用

- 命令行:在本机帮助声明支持的指标参数中选择 `Occupancy`。以位置参数形式为例(输出目录需先 `chmod 755`):

  ```bash
  mkdir -p msprof_occupancy && chmod 755 msprof_occupancy
  msprof op --output=./msprof_occupancy --aic-metrics=Occupancy \
    --kernel-name=add_custom ./execute_add_op
  ```

  若本机使用独立 `msopprof`、`--application` 或不同指标选项名,按 [跨版本探测模板](case-routing.md#3-msopprof-跨版本采集先探测再选命令) 切换。

- 使用场景:多核算子疑似负载不均(如各核处理数据量不同、尾核拖后腿)、 PipeUtilization 各 block 行数值差异大、SHMEM frame 的 `max_core_us` 明显高于 `avg_us` 时开启。

## 4. 分析案例

若当前归档没有 Occupancy 数据,不得从单个 block 时延外推所有核的负载。先按上一节检查本机帮助并补采;版本不支持时使用完整 block 时延、任务规模和 blockDim 作为替代证据,并降低置信度。

**两类 occupancy 问题要区分开(实测常见误判)**:

- **核间不均衡**:Block Dim 已接近物理核数,但各 block 行时延差异大(长尾核拖慢整体)——本文档主体覆盖的场景。
- **核数不足(占用率低)**:`OpBasicInfo.csv` 的 Block Dim 远小于 SoC 物理核数(如 Block Dim=1/4 vs A5 约 48 AIV),PipeUtilization 只有对应行数——此时各 block 行数值一致也不能排除 occupancy,瓶颈是"根本没用满核",机制上对应 blockDim 提升/工作量重切(optimize-ascendc-tiling.md 的 blockDim 候选)。A5 实测物理核数与 `GetCoreNumAiv()` 等**逻辑核数接口可能不一致**(如逻辑报 54/56、实测单波满载约 48),分核参数用 blockDim sweep 实测校准,不要直接照抄接口返回值。

另外注意:SIMT/VF 样例的网格语义是 `BLOCKS × THREAD_NUM`,**只加 BLOCKS 而不重切线程映射是空操作**(新增核的起始行越界直接空转);这两者是同一机制的原子对,必须一起改。

可给出的替代证据是"靠 PipeUtilization 交叉诊断核间均衡"判读路径在该用例上的真实应用:`PipeUtilization.csv` 按 `block_id` 0–7 分行,8 核数值几乎一致——

- before:各核 `aiv_mte2_ratio` 0.8805~0.9058、`aiv_mte2_active_bw(GB/s)` 2.2420~2.5649、`aiv_time(us)` 864.9~961.9;
- after:各核 `aiv_mte2_ratio` 0.9298~0.9422、`aiv_mte2_active_bw(GB/s)` 75.3424~75.7526、`aiv_time(us)` 21.41~21.75。

核间差异 ≤13%(仍属均衡范围),说明该用例的 8 核均分(204800/核)负载均衡,瓶颈不在核间不均衡——这正是"先看各 block 行是否一致、不一致才开 Occupancy"判读顺序的实际用法。
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall