AscendC Operator Precision Debugging

Phase 1: Error Analysis → Phase 2: Code Review → Phase 3: Experimental Isolation → Phase 4: Instrumentation Localization → Phase 5: Fix Verification

Phase 1: Error Analysis

csrc/ops/<op_name>/test/debug_<op_name>_precision.py

scripts/debug_precision_template.py

1. Error Statistics: MaxAbsErr, MeanAbsErr, MaxRelErr
2. First Error Element: Multi-dimensional coordinates + linear index + NPU value vs reference value
3. Error Distribution: Number/proportion of error elements, whether error intervals are periodic
4. Special Values: Whether output is all-zero, contains NaN/Inf
5. Automatic Comparison: Fixed input vs random input, binary search with reduced shape

Error Characteristics → Preliminary Judgment

Phase 2: Code Review

op_host/<op_name>.cpp

op_kernel/<op_name>.cpp

design.md

Layer 1: Basic Correctness (Highest Frequency)

• FP16/BF16 not upcast: In Compute, does half-precision data first

  Cast

  to FP32 for computation then

  Cast

  back? This is the most frequent precision bug.
• Incorrect calculation formula: Compare API call sequence with design document/PyTorch step by step — operation order, scalar sign, missing steps.
• GM offset unit confusion:

  xGm[progress * tileLength]

  is element offset, do not multiply by

  sizeof(T)

  extra.
• tileLength vs curTileLength: Use

  tileLength

  for offset, use

  curTileLength

  for computation/transfer (tail tile may be smaller).

Layer 2: Data Transfer and Alignment

• DataCopyPad copyLen:

  copyLen

  in

  DataCopyExtParams

  is byte count =

  curTileLength * sizeof(T)

  .
• Tail tile alignment: When tail tile does not meet 32B alignment, is the calculation and usage of

  alignedTailLen

  correct?
• Inconsistent offsets for multiple inputs: When shapes of multiple input tensors are different (such as x vs cos/sin in RoPE), is the offset calculation for each correct?

Layer 3: Tiling and Multi-core

• Host/Kernel tiling inconsistency: Does the same symbol (e.g.,

  tileLength

  ) have the same meaning in host and kernel?
• Inter-core boundary overlap/omission: Does formerNum × formerLength + tailNum × tailLength exactly cover all data?
• bufferCoefficient error: Check against the UB allocation table in design document, incorrect coefficient will cause tileLength deviation.

Layer 4: API Traps

• ReduceSum/Max modifies source data: Reduction may rewrite source tensor, need to backup first with

  Adds(backup, src, 0.0f, len)

  if reused later.
• AllocTensor/FreeTensor not paired: Must be strictly paired with EnQue/DeQue, otherwise buffer leakage occurs.
• Vector length parameter: The length parameter of AscendC vector API is number of elements, not byte count.

Layer 5: Boundary Cases

• Division by zero / domain out of bounds: Prevent zero for Div, Reciprocal; Ln requires positive numbers; Sqrt requires non-negative numbers.
• Tiling integer overflow: Is multiplication likely to overflow int32? int64_t is recommended.

Phase 3: Experimental Isolation

Experiment A: block_dim → 1 (Multi-core Isolation)

blockDim = 1

Experiment B: PipeBarrier<PIPE_ALL> (Synchronization Isolation)

AscendC::PipeBarrier<PIPE_ALL>()

PIPE_ALL

is only used for experimental isolation, never use it as the final solution.

Experiment C: Fixed/Regular Input (Address Isolation)

torch.arange

Experiment D: Reduce Shape (Boundary Isolation)

shape=(32,)

(tileLength,)

(tileLength*2,)

Reverse-engineering from First Error Index + Tiling

First error linear index → Which tile → Which core → GM start offset of the core → Expected byte count for transfer

Phase 4: Instrumentation Localization

AscendC::printf

AscendC::DumpTensor

Core Rules

1. Print only on core 0: When calculation logic of each core is consistent, add

   if (AscendC::GetBlockIdx() == 0)

   to reduce output volume.
2. Read after synchronization:

   LocalTensor

   can only be read after

   DeQue

   /

   PipeBarrier

   , otherwise dirty data from unfinished transfer will be read.
3. Convert FP16 to float first:

   AscendC::printf("v=%.6f\n", static_cast<float>(tensor.GetValue(idx)));

   , directly printing half-precision will cause garbled characters.
4. Use desc to distinguish phases: desc parameter of DumpTensor (0=after CopyIn, 1=middle of Compute, 2=before CopyOut).
5. Start with small amount: Start with small dumpSize for DumpTensor, large size will cause buffer overflow or truncation.

printf vs DumpTensor Selection

AscendC::printf

AscendC::DumpTensor(tensor, desc, dumpSize)

Instrumentation Strategy

// Example: Core 0, 0th tile
if (AscendC::GetBlockIdx() == 0 && progress == 0) {
    AscendC::printf("[step1] tmp[0]=%.6f\n", static_cast<float>(tmp.GetValue(0)));
}

Phase 5: Fix Verification

Common Fix Patterns

After Fix

1. Remove all debugging instrumentation (printf/DumpTensor), or wrap with

   #ifdef DEBUG_PRECISION

2. Recompile and install
3. Run original failed case + full precision test
4. Still fails → Return to Phase 1 (max 3 rounds), report to user if still fails after 3 rounds

Output Requirements (MANDATORY)

Typical Cases (Load On Demand)

examples/fp16-no-upcast.md

examples/gm-offset-error.md

examples/tail-tile-misalign.md

examples/multicore-tiling-overlap.md

examples/async-sync-missing.md

Do not load all cases at once. Only load corresponding case when error characteristics match.

Anti-Patterns (NEVER)

• NEVER modify code directly without analyzing error distribution
• NEVER loop printf full tensor in kernel — Use DumpTensor or Host-side comparison
• NEVER print massively on multiple cores at the same time — Add

  GetBlockIdx() == 0

  to print only on core 0
• NEVER read LocalTensor at unsynchronized position — Must be after DeQue/PipeBarrier
• NEVER use

  PIPE_ALL

  as final fix — Only for experimental isolation
• NEVER leave debugging code after fix
• NEVER only fix known failed cases without running full precision test
• NEVER continue trying if fails after more than 3 rounds — Should report to user