mlu-operator-skill

name	mlu-operator-skill
description	Use when writing, testing, profiling, or optimizing Cambricon MLU operators with BANG C/C++, CNCC, CNRT/CNDrv queues and notifiers, CNPerf evidence, or mlu-ops examples.

Skill: Cambricon MLU Operator Development

When to use

Use this skill when the user asks to write a Cambricon MLU operator, port an operator to BANG C/C++, diagnose why an MLU operator is slow, collect CNPerf evidence, interpret MLU performance data, or produce an optimization plan for a custom operator.

Trigger phrases include MLU operator, BANG C, BANG C++, CNPerf, cncc, cnrtQueue_t, cnrtNotifier_t, mlu-ops, NRAM, WRAM, SRAM, GDRAM, taskDim, taskId, Block task, Union task, and Chinese variants such as 寒武纪算子, mlu 算子, bang c 算子, cnperf 分析, 为什么慢, and 优化这个算子.

Golden rule

Specify -> test -> implement -> validate -> profile -> diagnose -> optimize -> report. Never optimize from guesses.

An MLU operator is only ready to tune after its contract, input shapes, layouts, dtypes, and correctness criteria are explicit. Start with a CPU or library reference, add representative cases, implement the smallest BANG C/C++ kernel that passes those cases, then collect timing and CNPerf evidence before choosing an optimization.

Required workflow

1. Create an isolated run directory under profile/<run_name>/ or the user's chosen workspace. Keep operator source, tests, CNPerf artifacts, parsed analysis, and REPORT.md together. See reference/00-directory-layout.md.

2. Define the operator contract. Record tensor ranks, shapes, dtypes, layouts, broadcasting rules, workspace needs, numerical tolerance, and unsupported cases. If using the mlu-ops style, draft the design notes before coding.

3. Write correctness checks first. Use a CPU reference, a trusted library path, or existing mlu-ops test conventions. Cover representative contiguous, strided, aligned, tail, and boundary cases before tuning.

4. Build a standalone BANG C/C++ driver unless the user must profile inside an existing framework. The driver owns CNRT/CNDrv initialization, device memory, queues, notifiers, kernel launch, and result validation. See reference/02-harness-guide.md and helpers/operator_template.mlu.

5. Compile with CNCC and preserve the command. Record the target architecture flag, include paths, library paths, and instrumentation flags used for profiling. See reference/01-workflow.md.

6. Measure baseline runtime with notifiers. Place notifiers around the target kernel or operator path on the same queue, synchronize the queue, and record duration with the tested shape and launch policy.

7. Collect CNPerf evidence. Use monitor, PMU, kernel profiling, parse, report, and timechart flows as appropriate. Store raw and parsed artifacts under the run directory. See reference/03-collection.md and reference/04-cnperf-parsing.md.

8. Diagnose using MLU dimensions. Check task/core utilization, partition balance, GDRAM traffic, NRAM/WRAM/SRAM staging, compute/IO overlap, vector builtin use, queue gaps, and numerical constraints. See reference/05-analysis-dimensions.md and reference/06-diagnosis-playbook.md.

9. Optimize one bottleneck at a time. Prefer changes supported by measurements: better task partitioning, on-chip tiling, vector builtins, aligned copies, deeper pipeline, kernel fusion, workspace reuse, or queue-level overlap. Re-run correctness and profiling after each meaningful change.

10. Write the report. Include contract, environment, build command, launch policy, correctness coverage, timing, CNPerf evidence, diagnosis, ranked changes, and reproduction steps. See reference/07-report-template.md.

File index

File	Purpose
reference/00-directory-layout.md	Run directory and artifact conventions
reference/01-workflow.md	End-to-end MLU operator workflow
reference/02-harness-guide.md	Standalone BANG C/C++ driver and CNRT/CNDrv launch guide
reference/03-collection.md	CNPerf collection recipes
reference/04-cnperf-parsing.md	Parsing and comparing CNPerf outputs
reference/05-analysis-dimensions.md	MLU performance analysis dimensions
reference/06-diagnosis-playbook.md	Observation -> cause -> fix guidance
reference/07-report-template.md	Evidence-backed optimization report template
reference/08-cnperf-counters-and-fields.md	CNPerf fields, counters, and version notes
reference/09-common-issues.md	CNToolkit, CNCC, CNRT/CNDrv, and CNPerf troubleshooting
cambricon-mlu-programming.md	Companion MLU programming reference

Helper	Purpose
helpers/operator_template.mlu	Minimal BANG C/C++ operator driver template
helpers/cnperf_utils.py	Shared CNPerf parsing and comparison helpers
helpers/analyze_cnperf.py	Extract key fields and compare CNPerf runs
helpers/inspect_workloads.py	Inspect generic shape/workload manifests
helpers/safetensors_loader.h	Optional real tensor input loader

Critical lessons

1. Correctness is part of performance work. A faster operator that fails tail, stride, layout, dtype, or workspace cases is not an optimization.

2. Task policy is a first-class design choice. Record cnrtDim3_t, function type, task partitioning, and tail handling for every measured run.

3. Memory hierarchy drives most wins. Explain what lives in GDRAM, NRAM, WRAM, SRAM, or workspace, and why that movement is minimal enough for the target shape.

4. Notifier timing and CNPerf answer different questions. Notifiers give launch-path duration on a queue; CNPerf explains hardware activity, PMU counters, task-level behavior, and timeline gaps.

5. Do not promise unsupported profiler detail. If a CNPerf version or device does not expose a counter or source-level field, state that limitation and use available evidence instead.

6. Use mlu-ops conventions when possible. Treat Cambricon/mlu-ops as the default upstream reference for operator contracts, host wrappers, .mlu kernels, tests, generated cases, accuracy standards, performance standards, and workspace handling.

Skill identity note

Install or link this checkout under the skill name mlu-operator-skill. The skill identity and workflow are MLU-only.