---
name: dcu-profiler-report
description: "Use when a LightOp DCU/ROCm operator needs profiling evidence: run hipprof or deeper ROCm/DTK profilers, capture synchronized benchmark logs, summarize API/kernel/memory time, inspect counters or AMDGPU ISA when available, and produce exactly one concrete next operator edit."
type: flow
---

# dcu-profiler-report

Use this skill when benchmark numbers are not enough and the next LightOp
HIP/ROCm kernel, binding, dispatch, or config-table edit should be driven by
DCU profiling evidence.

The rule is:

```text
profile first, diagnose second, optimize third
```

The output is not just "memory-bound" or "launch overhead". It must be an
inference chain from measured DCU evidence to a likely mechanism to one
actionable LightOp edit.

## Official Reference

Use the SourceFind DCU performance analysis tool guide as the local official
reference for first-pass DCU profiling:

```text
https://developer.sourcefind.cn/gitbook//dcu_developer/DeveloperGuide/dcu_programming/DCU_programming_chapter3_7.html
```

Prefer DTK/DCU tools first. Use `hipprof` for first-pass API/kernel/memcpy
timing. Escalate to `rocprof`, `rocprofv3`, `rocprof-compute`, counter tools,
or AMDGPU ISA/code-object inspection only when timing evidence cannot explain
the next edit.

## When To Invoke

Invoke `dcu-profiler-report` when any of these hold:

- A LightOp baseline benchmark has passed and no baseline profile digest exists.
- A correct candidate is within +/-2% of baseline or the prior best.
- A correct candidate regresses on one or more important shapes.
- A candidate is much faster than expected and needs explanation.
- The next edit is unclear after benchmark results.
- A Humanize/RLCR reviewer asks for profile evidence.
- A candidate may be limited by launch overhead, host-device copies, global
  memory layout, LDS/bank conflicts, VGPR/occupancy pressure, wavefront
  divergence, MFMA underuse, or shape-dispatch choices.

Do not profile while correctness is failing unless the failure is itself a
profiler collection problem. Fix correctness first.

## Required Artifacts

Store artifacts under the LightOp loop state or user-specified evidence path:

```text
.humanize/lightop-agent/profile-artifacts/<version>/
  benchmark.log
  hipprof.txt
  rocprof.csv                 # when rocprof/rocprofv3 is used
  rocprof-stats.csv           # when available
  rocprof-compute/            # when available
  code-object-metadata.txt    # when extracted
  amdgpu-isa.txt              # when extracted
  digest.md
```

When comparing a candidate, include the baseline or parent artifact path in
the digest.

## Workflow

1. Pick one representative shape first. Prefer the smallest shape that still
   exposes the regression, plateau, launch overhead, or suspected bottleneck.
2. Build a focused benchmark harness with stable warmup, fixed dtype, fixed
   shape, fixed seed, and explicit synchronization around timed regions.
3. Capture normal benchmark output before profiling, so profiler overhead does
   not become the performance claim.
4. Run `hipprof` for first-pass API/kernel/memcpy timing.
5. If `hipprof` shows one or a few dominant kernels but does not explain why,
   collect deeper counters with the installed ROCm/DTK profiler.
6. If the issue looks codegen-sensitive, inspect AMDGPU ISA or code-object
   metadata before choosing an edit.
7. Compare candidate against baseline or parent, not only absolute metrics.
8. Diagnose using the metric groups in [metrics.md](references/metrics.md).
9. Write `digest.md` using the template below. The final section must contain
   exactly one next edit.
10. Update the LightOp loop ledger with the digest path, bottleneck class, and
    selected next edit.

## Common Commands

Load [examples.md](references/examples.md) for copyable command variants.

Minimal first-pass capture from the LightOp root:

```bash
mkdir -p .humanize/lightop-agent/profile-artifacts/v000_baseline
python test/test_<op>.py 2>&1 | tee .humanize/lightop-agent/profile-artifacts/v000_baseline/benchmark.log
hipprof python test/test_<op>.py 2>&1 | tee .humanize/lightop-agent/profile-artifacts/v000_baseline/hipprof.txt
```

For a benchmark script:

```bash
mkdir -p .humanize/lightop-agent/profile-artifacts/v001_candidate
hipprof python test/<family>/benchmark_<op>.py 2>&1 \
  | tee .humanize/lightop-agent/profile-artifacts/v001_candidate/hipprof.txt
```

Optional helper:

```bash
python3 <skill-root>/scripts/dcu_profile_digest.py \
  --hipprof .humanize/lightop-agent/profile-artifacts/v001_candidate/hipprof.txt \
  --baseline-hipprof .humanize/lightop-agent/profile-artifacts/v000_baseline/hipprof.txt \
  --benchmark-log .humanize/lightop-agent/profile-artifacts/v001_candidate/benchmark.log \
  --kernel-regex "<kernel-name-pattern>" \
  --output .humanize/lightop-agent/profile-artifacts/v001_candidate/digest.md
```

The helper is a first pass only. Inspect profiler output and any counter/ISA
evidence before treating the next edit as final.

## Metrics To Inspect

Start with these groups, then load [metrics.md](references/metrics.md) for the
full list and interpretation rules:

- Runtime identity: LightOp commit, operator, public API, shape, dtype, gfx
  arch, DTK/ROCm/PyTorch version, build command.
- Benchmark timing: warmup, repeats, p50/p90/mean, synchronization points,
  variance, baseline and candidate deltas.
- `hipprof` timing: total HIP API time, kernel time, memcpy/memset time,
  launch overhead, top kernels by inclusive/exclusive time.
- Kernel launch shape: grid/block, waves per block, occupancy clues, block
  count relative to CU count, tiny-kernel overhead.
- Memory path: global load/store volume, coalescing, alignment/vector width,
  L2/HBM pressure, redundant reads/writes, temporary tensors.
- LDS path: LDS use, bank conflicts, barriers, shared staging cost.
- Compute path: MFMA/vector ALU utilization, conversion/quantization overhead,
  scalar control overhead, epilogue fusion cost.
- Resource pressure: VGPR/SGPR, spills/scratch, LDS per block, occupancy
  limiters, overly aggressive unroll.
- Dispatch/config: wrong shape branch, overly broad config, missing gfx
  specialization, fallback path accidentally selected.
- ISA/code object: hot instruction window, vector width, MFMA selection,
  excessive scalarization, scratch loads/stores.

Validate exact tool availability on the target machine:

```bash
which hipprof || true
which rocprof || true
which rocprofv3 || true
which rocprof-compute || true
hipcc --version
```

## Digest Template

```markdown
### DCU Profile Digest: <operator> @ <version>

Environment
- LightOp root:
- Repo commit:
- GPU / gfx:
- DTK / ROCm / PyTorch:
- Build command:
- Benchmark command:
- Shape / dtype:
- Baseline or parent profile:
- Candidate profile:
- Artifacts:

Headline
- Bottleneck class:
- Dominant time sink or hotspot:
- Confidence: High | Medium | Low
- Why this profile is valid:

Evidence
| Signal | Baseline | Candidate | Delta | Interpretation |
|---|---:|---:|---:|---|
| <metric/log line> | <value> | <value> | <delta> | <meaning> |

Profiler Hotspots
- <kernel/API/copy/config branch>: <measured signal> -> <meaning>

Counter / ISA Analysis
- Counter source:
- Hot instruction window:
- Suspected codegen or resource issue:
- Instruction-level or launch-level edit:

Inference Chain
1. Measured signal:
2. Likely mechanism:
3. Why other hypotheses are weaker:
4. Risk:
5. Validation command after edit:

Next Edit
- <exactly one concrete LightOp code, binding, config, or benchmark edit>
```

## Diagnosis Hints

- High HIP API time with tiny kernel time: reduce Python/C++ launch count,
  fuse adjacent ops, or route to an existing fused LightOp path.
- High memcpy/memset time: remove host-device transfers, avoid temporary
  materialization, or make output allocation/reuse explicit.
- Dominant single kernel and poor benchmark scaling: inspect memory layout,
  vectorized loads/stores, block size, and dispatch config.
- Low occupancy clues or spills: reduce VGPR pressure, split the kernel,
  shrink unroll, or specialize for the target shape.
- LDS/barrier-heavy symptoms: reduce staging, fix bank conflicts, or simplify
  inter-wave synchronization.
- MFMA-capable GEMM/MoE path underperforms: verify the intended asm/rocBLAS/
  hipBLASLt/CK/Triton AMD route is selected and that shape config matches `W`.
- A candidate only wins on one shape: record it in the performance map and add
  shape/gfx dispatch instead of replacing the broader default.

## Ledger Rules

- Keep `hipprof.txt`, benchmark logs, deeper profiler exports, and digest paths
  in the attempt ledger.
- Only promote a profile-driven edit to the optimization ledger after
  correctness passes and the benchmark shows measured improvement.
- If the profiler tool is unavailable, record the command attempted, the
  failure, and the cheaper evidence used instead.
