@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/causal-mask/techniques.md

@@ -1,68 +0,0 @@
----
-id: technique-ascendc-causal-mask-vectorized
-title: "Build a Causal Mask with Five Vector Instructions, Not a Scalar Loop"
-type: technique
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.1.0'
-evidence_level: measured
-confidence: experimental
-reproducibility: snippet
-scope: >-
-  A causal or top-k limit that is uniform across rows, so one mask vector serves every
-  row. A per-row limit needs the mask rebuilt per row and the saving shrinks
-  proportionally.
-tags:
-- ascendc
-- ai-core
-- vector-unit
-- attention
-hardware_features:
-- ai-core
-- vector-unit
-kernel_types:
-- attention
-techniques: []
-prerequisites:
-- hw-ascend910b2c
-related:
-- technique-ascendc-vector-repeat-granularity
-sources:
-- exp-ascend910b2c-reduction-and-broadcast-costs
-source:
-- path: sources/experience/ascend-campaign/ascend910b2c-reduction-and-broadcast-costs.md
-  anchor: Broadcast path rewrites, same campaign
-aliases:
-- "因果掩码 不要用标量循环"
-- "五条向量指令构造掩码"
----
-
-## The scalar loop is the whole cost
-
-A scalar mask iterated over `topK` cost **4.3 ms** on one case by itself. Building the
-same `-FLT_MAX` mask with five full-width vector instructions and adding it to whole
-rows:
-
-```cpp
-Cast(mask, index, RoundMode::CAST_NONE, topk32);
-Adds(mask, mask, -(float)causal_limit, topk32);
-Mins(mask, mask, 1.0f, topk32);
-Maxs(mask, mask, 0.0f, topk32);
-Muls(mask, mask, -3.402823466e38f, topk32);        // 0/1 -> 0/-FLT_MAX
-for (row...) Add(score[row * TOPK], score[row * TOPK], mask, topk32);
-```
-
-Softmax on that case went **5075 → 567 µs**.
-
-## Why it works
-
-The clamp pair `Mins(...,1) / Maxs(...,0)` turns an arbitrary signed difference into a
-0/1 indicator without a compare-and-select, so no mask register is involved and the
-whole thing stays in the vector pipeline. Multiplying the indicator by `-FLT_MAX`
-produces an additive mask, which composes with the score row by a plain `Add` — no
-select, no branch, and the mask is built once and reused for every row.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/compare-select/pitfalls.md

@@ -1,59 +0,0 @@
----
-id: pitfall-ascendc-compare-select-stride
-title: "Compare* + Select — Mask Stride Mismatch, and a Wide-Range Failure That Passes Every Visible Case"
-type: pitfall
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.0.0'
-evidence_level: measured
-confidence: experimental
-scope: >-
-  DAV_2201. P1 is a layout fact and applies to any use of CompareScalar feeding Select.
-  P2 was observed on a tanh branch selection over a wide value range; the recommendation
-  to prefer arithmetic blending is drawn from that one case plus P1.
-tags:
-- ascendc
-- ai-core
-- vector-unit
-hardware_features:
-- ai-core
-- vector-unit
-related:
-- pitfall-ascendc-level0-mask-ignored
-- api-ascendc-reduce-data-block-strides
-aliases:
-- "CompareScalar Select 错位"
-- "算术混合代替 Select"
----
-
-## P1. `n > 64` produces garbage — the mask is written strided and read packed
-
-`CompareScalar` writes its 8-byte mask **at 32 B block spacing** per repeat, while
-`Select` reads it **packed**. From the second repeat onwards everything is displaced.
-
-Any shape with `H ≥ 127` fails immediately. This is the same class of defect as
-[`api-ascendc-reduce-data-block-strides`](../../../api-definitions/ascendc/reduce-data-block-strides.md):
-a producer and a consumer disagreeing about a stride, with nothing reporting it.
-
-## P2. Even restricted to one repeat it is wrong over a wide value range
-
-Restricting to `n ≤ 64` fixes P1 and leaves a second defect:
-
-- Every visible case passed — **20 of 20** — and the local score even went *up* by 0.23.
-- Over a wider shape and value sweep it went **29/80 → 22/80**, with `max_diff = 312`
-  and a 59% error rate.
-
-That is a **coarse** failure, not a precision one. It passed everything anyone was
-looking at.
-
-> ### Prefer arithmetic blending — clamp, step, linear interpolation — over
-> ### `Compare*` + `Select` for branch selection.
-
-The rewrite that motivated this cut 23 instructions to 15, which is real, and it is
-still not worth it: the instruction saving is ≈8 × 56 cycle, and the failure mode is
-invisible until you sweep the value range yourself.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/cross-repeat-fold/pitfalls.md

@@ -1,66 +0,0 @@
----
-id: pitfall-ascendc-cross-repeat-fold-src1
-title: "Cross-Repeat Folding — the Accumulator Must Sit in the src1 Slot"
-type: pitfall
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.0.0'
-evidence_level: measured
-confidence: experimental
-scope: >-
-  Only when dstRepStride = 0, i.e. every repeat targets the same destination. With a
-  non-zero dstRepStride the repeats sweep different rows and the problem does not
-  exist. MulAddDst is unaffected because dst is its genuine accumulate operand.
-tags:
-- ascendc
-- ai-core
-- vector-unit
-- reduction
-hardware_features:
-- ai-core
-- vector-unit
-kernel_types:
-- reduction
-related:
-- pitfall-ascendc-int8-cast-no-clamp
-- technique-ascendc-reduction-cost-overview
-aliases:
-- "跨 repeat 折叠 累加器 src1"
-- "一个归约对一个归约错"
----
-
-## P1. Accumulator in src0 does not forward between repeats
-
-To fold a whole row into 64 lanes with one instruction you set `dstRepStride = 0` so
-every repeat lands on the same place. Put the accumulator in **src0** and the repeats
-do not forward — you are left with the last beat only.
-
-```cpp
-Max(acc, acc, chunk, 64, reps, {1,1,1, 0, 0, 8});   // ❌ result = max(last 64 elements)
-Max(acc, chunk, acc, 64, reps, {1,1,1, 0, 8, 0});   // ✅ real fold — same shape as
-                                                    //    the vendor's ReduceMaxInplace
-```
-
-`MulAddDst` is **not** affected: `dst` is its true accumulate operand.
-
-## P2. The fingerprint is "one reduction right, one reduction wrong"
-
-Because `MulAddDst` is immune, a kernel that computes both `Σt²` and `max|u|` will
-have the sum correct and the maximum wrong. That asymmetry inside a single kernel is
-the signature.
-
-**How to confirm it:** back-solve the implied `m = scale·127·rms` and compare it
-against `max(u[-64:])` — they come out bit-identical when this is the bug.
-
-## P3. Why it is expensive downstream
-
-If the row maximum feeds a quantization scale, a slightly-too-small `m` makes
-`u·127/m` exceed 127, and `Cast<int8_t, half>` **wraps to negative rather than
-clamping**. Measured `max_diff` jumps past 200 immediately. See
-[`pitfall-ascendc-int8-cast-no-clamp`](../int8-quantize/pitfalls.md) — this pitfall is
-that one's amplifier.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/double-buffer-war/techniques.md

@@ -1,150 +0,0 @@
----
-id: technique-ascendc-double-buffer-war
-title: "Hand-Written Double Buffering in Ascend C — Removing the Single-Buffer WAR Stall"
-type: technique
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910c
-languages:
-- ascendc
-cann_version: '9.1.0'
-evidence_level: measured
-confidence: experimental
-reproducibility: snippet
-scope: >-
-  Historical Conv2D stage reuse and capacity constraints. Per-block iteration
-  count, stage costs, dispatch, shared inputs and startup/drain jointly determine
-  overlap; one or two iterations do not imply zero overlap or a fixed speed ratio.
-tags:
-- ascendc
-- ai-core
-- ub
-- double-buffering
-- pipeline-stages
-hardware_features:
-- ai-core
-- ub
-techniques:
-- double-buffering
-- pipeline-stages
-prerequisites:
-- hw-ascend910b2c
-related:
-- api-ascendc-event-id-alloc
-- pitfall-ascendc-tiny-case-fixed-cost
-- technique-ascendc-datacopypad-burst-cost
-sources: []
-aliases:
-- double buffering
-- ping pong buffer
-- WAR hazard
-- write after read
-- MTE3_MTE2
-- AllocEventID
-- 双缓冲
-- 手写双缓冲
-- 单缓冲串行
-- 写后读
-- 事件 id
----
-
-> [CB-04 后置限定](../../../experience/cb04-conv2d-stage-lifetime.md)：下文同步占比和双槽收益只绑定当次Conv2D。后续容量门放宽曾73/80→31/80，短循环也非永远零收益（历史FastFinal比率.87）；按单槽/总量、所有路由与实际调度核，不按轮数线性外推。Strided共享inputPlane仍有独立PIPE_ALL保护；完整skip/acquire/drain、低精度舍入和事件API版本要一起读。
-
-## Search Keywords
-
-double buffering, ping-pong, WAR hazard, write-after-read, MTE3_MTE2, AllocEventID,
-SetFlag, WaitFlag, pipeline stall, sync latency, 双缓冲, 手写双缓冲, 单缓冲, 写后读,
-同步延迟, 事件 id.
-
-## Symptom: three Set/Wait round trips per iteration
-
-A single staging buffer forces load and store to serialise, because the next
-iteration's `DataCopyPad` into the stage must wait for the previous iteration's
-`DataCopyPad` out of it. The third flag pair is pure WAR protection:
-
-```cpp
-for (...) {
-    DataCopyPad(stage, gm[...], ...);        // MTE2
-    SetFlag<HardEvent::MTE2_V>(e1); WaitFlag<HardEvent::MTE2_V>(e1);
-    <vector work>                             // V
-    SetFlag<HardEvent::V_MTE3>(e2); WaitFlag<HardEvent::V_MTE3>(e2);
-    DataCopyPad(gm[...], stage, ...);        // MTE3
-    SetFlag<HardEvent::MTE3_MTE2>(e3);       // <- only one stage buffer, so this
-    WaitFlag<HardEvent::MTE3_MTE2>(e3);      //    pair fully serialises load/store
-}
-```
-
-**Measured: the critical path is 467-1011 ns per iteration while that iteration's
-DMA moves only 0.4-4 KB.** More than 90% of the iteration is synchronisation
-latency, not transfer - which is why retiling or shrinking the copy does not move
-it.
-
-## The transform: two stages, two event ids
-
-```cpp
-// Two stages + two event ids. WaitFlag goes after every `continue`, immediately
-// before the inbound DataCopyPad; SetFlag immediately after the outbound one;
-// the two pair up one-to-one. Drain both flags before every kernel return.
-auto stageA = buf, stageB = buf[STAGE_ELEMENTS];
-const event_t ev[2] = { pipe.AllocEventID<HardEvent::MTE3_MTE2>(),
-                        pipe.AllocEventID<HardEvent::MTE3_MTE2>() };
-SetFlag<HardEvent::MTE3_MTE2>(ev[0]);   // mark both stages free
-SetFlag<HardEvent::MTE3_MTE2>(ev[1]);
-...
-    auto stage = (idx == 0) ? stageA : stageB;
-    WaitFlag<HardEvent::MTE3_MTE2>(ev[idx]);   // wait only on the store that used
-    DataCopyPad(stage, ...);                   // this buffer two rounds ago
-    ...
-    DataCopyPad(gm, stage, ...);
-    SetFlag<HardEvent::MTE3_MTE2>(ev[idx]);
-    idx ^= 1;
-```
-
-`MTE3_MTE2` is the pair that matters: it is the write-after-read edge between the
-store that frees a stage and the load that refills it. The other two pairs
-(`MTE2_V`, `V_MTE3`) are true data dependencies and stay.
-
-## Three details that decide whether it actually works
-
-**1. Allocate the ids with `AllocEventID`, never `FetchEventID`.** `FetchEventID`
-does not reserve, so two calls return the *same* id and the ping-pong collapses onto
-one flag - a double buffer that measures like a single one. See
-[event id allocation](../../../api-definitions/ascendc/event-id-alloc.md).
-
-**2. Replace an in-loop `PipeBarrier<PIPE_ALL>` with a directional flag.** A
-`PIPE_ALL` barrier drains every pipe, including MTE2, which switches off the
-prefetch this transform exists to create. Swapping the two `PIPE_ALL` calls per
-kernel position for `V_MTE3` / `MTE3_V` measured **-10.7% to -17.4%** on the
-affected cases. **The swap leaves a debt**: the barrier was also ordering across
-task iterations (this round's input reload against last round's read), so add one
-directional guarantee at the top of the task loop. The in-loop barrier itself is a
-static check, `C2-pipe-all-in-loop`, so it does not need to be remembered.
-
-**3. The stage index must cross call boundaries by reference.** On short shapes one
-call handles a single tile, so the overlap has to happen *between* calls. A stage
-index declared inside the per-tile function resets to 0 on entry, both consecutive
-rows start from stage A, and the double buffering does nothing while looking
-correct. Pass the **stage index** by reference; the local-variable form is a static
-check, `C7-stage-index-per-call`.
-
-## UB budget: the second stage is usually cheap
-
-| buffer | one stage | two stages |
-|---|---:|---:|
-| im2col | 96 KB | 160 KB |
-| epilogue | 16.9 KB | 33 KB |
-
-Ceiling is 192 KB and **neither crossed the fast-path admission predicate**, because
-that predicate is written against the per-stage capacity constant rather than the
-total. Check which of the two your predicate uses before assuming the budget is the
-blocker - this is the cheap half of the transform, and it is often assumed expensive.
-
-## When it does not pay
-
-The saving is per iteration, so an operator whose blocks run only two or three tiles
-can spend the whole gain on pipeline startup and drain. The diagnostic half of this -
-recognising single-buffered execution in a profile - is
-`npu-profiling-skill/references/06-optimization-playbook.md` Pattern I; this page is
-the Ascend C form of the fix, which that playbook does not carry.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/fused-multiply-add/half-intermediate-open-question.md

@@ -1,87 +0,0 @@
----
-id: pitfall-ascendc-fma-half-intermediate
-title: "Two Measurements Disagree on Mixed-Precision FMA — Use the Conservative Rule"
-type: pitfall
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.0.0'
-evidence_level: measured
-confidence: inferred
-status: open-question
-scope: >-
-  Both measurements are on the same part and the same CANN release. This page states
-  a rule that is safe under either explanation, not a resolved mechanism. Treat the
-  mechanism as unsettled.
-tags:
-- ascendc
-- ai-core
-- vector-unit
-hardware_features:
-- ai-core
-- vector-unit
-related:
-- pitfall-ascendc-fma-half-multiply
-- technique-ascendc-fma-saves-buffer
-aliases:
-- "两次实测互相打架"
-- "半精度中间量 判据"
-- "未决条目"
----
-
-## The contradiction
-
-One operator swept `MulAddDst(acc_f32, x_h, x_h)` across `|x|` = 1e-4 / 1e-2 / 1 / 100
-at N = 65537 and got results **bit-identical to the fp32 reference**
-(`rel = 0.000e+00`). At `|x| = 1e-4`, `x² = 1e-8` is below half's smallest subnormal
-(5.96e-8) — **if the product were computed in half, that whole band should have
-flushed to zero, and it did not.**
-
-Another operator, same part and same CANN release, showed the opposite: MARE 41.69,
-82 of 3234 elements wrong, with a mechanism that requires the product to be in half.
-
-Both measurements are sound. The difference is **whether the half value fed in was
-itself computed in half**: the passing case fed **raw input**, the failing case fed an
-**intermediate produced earlier in the pipeline**.
-
-## The rule to use until this is settled
-
-> **The danger is not "mixed-precision multiply". It is "a half intermediate you
-> computed yourself".**
->
-> `MulAddDst` / `Axpy` consuming **raw half inputs** is safe. The moment you build the
-> operand with a half `Mul` / `Sqrt` / `Muls` first, that intermediate has to have its
-> own range checked.
-
-## What the second half of that rule catches
-
-Building `|x|^p` from half `Mul` / `Sqrt` — **half's exponent range is far narrower
-than fp32's**, and leaving it is silent:
-
-| Order | Range | Output | Correct |
-|---|---|---:|---:|
-| p = 2.5 | \|x\| ≤ 1e-4 | **0** | 0.00510 |
-| p = 3 | \|x\| ≤ 1e-4 | **0** | 0.00253 |
-| p = 5 | \|x\| ≤ 1e-2 | **0** | 0.0641 |
-| p = 5 | \|x\| ≤ 100 | **inf** | 641.5 |
-
-`|x|^5` overflows above 16 and flushes to zero below 0.03. **No shape in either the
-visible or the held-out set reached those bands**, so the accuracy report was clean —
-this class of defect does not appear in an evaluation at all. Only a deliberate
-value-range sweep finds it.
-
-The fix was to narrow the half path to orders that build no intermediate: `p = 1` is
-just `Abs`, `p = 2` is the single `MulAddDst` multiply.
-
-## Related constraint: bf16 has no arithmetic here
-
-`Axpy<float, bfloat16_t>` and `MulAddDst<float, bfloat16_t>` **do not compile**. bf16
-has no element-wise arithmetic on AIV beyond `Cast` — `bfloat16` does not appear in
-`dav_c220`'s `kernel_operator_vec_{unary,binary}_impl.h` at all.
-
-The one way to save a pass on bf16 is `abs` via `And<int16_t>` with a `0x7FFF` mask,
-which is bit-exact and half the traffic of an fp32 `Abs`.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/fused-multiply-add/pitfalls.md

@@ -1,74 +0,0 @@
----
-id: pitfall-ascendc-fma-half-multiply
-title: "Mixed-Precision MulAddDst / Axpy Multiply in half — float dst Only Means float Accumulate"
-type: pitfall
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.0.0'
-evidence_level: measured
-confidence: experimental
-scope: >-
-  Observed where the half operand was an intermediate computed earlier in half. A
-  second measurement on raw half inputs did not reproduce it - see the open-question
-  page before concluding the product is always in half.
-tags:
-- ascendc
-- ai-core
-- vector-unit
-hardware_features:
-- ai-core
-- vector-unit
-related:
-- pitfall-ascendc-fma-half-intermediate
-- technique-ascendc-fma-saves-buffer
-aliases:
-- "混合精度乘法在 half 里做"
-- "dst 是 float 只说明累加在 fp32"
----
-
-## P1. The instruction-count win is real and the accuracy failure is silent
-
-`dav_c220`'s implementation header lists `Tuple<float, half>` support (bf16 is not
-listed). Feeding fp16 gradients into `vmla` / `vaxpy` without a `Cast` cuts the chain
-from 13 instructions to 12, and the speedup is genuine: 205→189 µs, 16.1→14.8,
-28.3→26.1.
-
-It fails accuracy: **MARE 41.69** against a 0.1 threshold, 82 of 3234 elements wrong.
-
-## P2. The mechanism
-
-**"dst is float" only says the accumulation is fp32. The product is not.**
-
-```
-v_hat = 999·v + g²
-```
-
-When `v ≈ 0`, `v_hat` is determined entirely by `g²`. At `g ~ 1e-4`, `g² = 1e-8`
-flushes to zero in half, so `sqrt(v_hat) = 0` and `update = m_hat / eps` explodes to
-NaN. The failure is confined to the elements where the accumulator is near zero, which
-is why it is a small fraction of the tensor and easy to mistake for noise.
-
-## P3. The rule
-
-> **A mixed-precision multiply is unusable when the product can be very small *and*
-> the result lands in a denominator** — squared terms, the intermediate of a norm.
-> A purely linear accumulation (`a·x + y`, with `x` not squared) is far safer.
-
-```cpp
-// UNSAFE — g is half, g*g is computed in half, and v_hat feeds a sqrt in a denominator
-MulAddDst(vAccF32, gHalf, gHalf, n);
-
-// SAFE — cast first; costs one pass, and the pass is not where the time goes
-Cast(gF32, gHalf, RoundMode::CAST_NONE, n);
-MulAddDst(vAccF32, gF32, gF32, n);
-```
-
-Before applying this rule, read
-[`pitfall-ascendc-fma-half-intermediate`](./half-intermediate-open-question.md) —
-a second measurement contradicts the blanket form of P2, and the conservative rule
-stated there is the one to follow.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/fused-multiply-add/techniques.md

@@ -1,75 +0,0 @@
----
-id: technique-ascendc-fma-saves-buffer
-title: "MulAddDst / Axpy Save a Buffer, and the Buffer Is What Buys the Speedup"
-type: technique
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.0.0'
-evidence_level: measured
-confidence: experimental
-reproducibility: snippet
-scope: >-
-  Holds where per-tile fixed cost is a significant share of the kernel, which is the
-  usual case for element-wise and optimizer-shaped operators. On a kernel already
-  bound by transfer time, freeing a buffer buys nothing.
-tags:
-- ascendc
-- ai-core
-- ub
-- vector-unit
-- tiling-optimization
-hardware_features:
-- ai-core
-- ub
-- vector-unit
-techniques:
-- tiling-optimization
-prerequisites:
-- hw-ascend910b2c
-related:
-- pitfall-ascendc-fma-half-multiply
-- technique-ascendc-vector-repeat-granularity
-sources:
-- exp-ascend910b2c-memory-and-arith-techniques
-source:
-- path: sources/experience/ascend-campaign/ascend910b2c-memory-and-arith-techniques.md
-  anchor: Fused multiply-add saves a buffer, and the buffer is the point
-aliases:
-- "MulAddDst Axpy 省 buffer"
-- "省出来的 UB 换更大 tile"
----
-
-## The instruction saving is not the point
-
-```cpp
-// v, g, dst, var: LocalTensor<float>;  k: float folded on the host
-__aicore__ inline void Step(const LocalTensor<float> &v, uint32_t n) {
-    MulAddDst(v, g, g, n);   // v += g*g       — drops a Mul AND a scratch buffer
-    Axpy(dst, var, k, n);    // dst += k*var   — drops a Muls plus an Add
-}
-```
-
-Removing an instruction is worth ≈40 cycle. Removing the **scratch buffer** raises
-the tile ceiling, and the tile size is what actually moves the clock: 2048 → 4096
-took one case from **135.9 to 114.2 µs**. Freed UB went from a 4096-element tile to
-6144.
-
-> Per-tile fixed cost is heavy on this part, so the number of live buffers *is* the
-> tile-size limit. Count buffers, not instructions.
-
-## Fold the coefficients on the host so the fused form fits
-
-The fused form only applies if the constant lands where the instruction expects it.
-Do the algebra host-side: bias correction, the signed learning rate, and pulling `b2`
-out of the square root so that `MulAddDst`'s coefficient comes out as exactly 1.
-(At `step == 1`, `b2 ≡ 1`, so that transformation is an identity and costs nothing.)
-
-## Do not reach for the mixed-precision form
-
-The `Tuple<float, half>` instantiation is faster and is wrong for a whole class of
-expressions — see [`pitfall-ascendc-fma-half-multiply`](./pitfalls.md) before using it.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/ascend/foundations/compute/int8-quantize/pitfalls.md

@@ -1,64 +0,0 @@
----
-id: pitfall-ascendc-int8-cast-no-clamp
-title: "Cast<int8_t, half> Supports CAST_RINT but Does Not Clamp — It Wraps"
-type: pitfall
-vendor: ascend
-architectures:
-- ascend910b
-soc:
-- ascend910b2c
-languages:
-- ascendc
-cann_version: '9.0.0'
-evidence_level: measured
-confidence: experimental
-scope: >-
-  dav_c220. The two-step fp32 -> half -> int8 path replaces the older
-  int32 + SetDeqScale chain on this part; on a part where vconv_f162s8r is absent the
-  old chain is still required.
-tags:
-- ascendc
-- ai-core
-- vector-unit
-- quantization
-hardware_features:
-- ai-core
-- vector-unit
-kernel_types:
-- quantization
-related:
-- pitfall-ascendc-cross-repeat-fold-src1
-- pitfall-ascendc-quant-matmul-output
-aliases:
-- "Cast int8 不 clamp"
-- "超过 127 回绕成负数"
----
-
-## P1. The short path exists
-
-`vconv_f162s8r` is present on dav_c220, so **fp32 → half → int8 in two casts** is
-enough; the three-step `int32 + SetDeqScale` chain is not needed.
-
-There is also `MulCast<int8_t, half>` (`vmulconv_f162s8`), which does half × half → int8
-in one instruction — **but it requires the product not to overflow in half**. With fp16
-values reaching ±65504, `t·γ` can reach 8.6e9, so in practice you have to multiply by
-`k` in fp32 first to bring the value into [−127, 127], and by then the fused form no
-longer applies.
-
-## P2. Above 127 it wraps to negative — there is no clamp
-
-```cpp
-// u/m is exactly 1.0 at the row maximum, so u*127/m lands exactly on 127 — safe,
-// PROVIDED m is exact.
-Muls(q, u, 127.0f / m, n);
-Cast(qi8, q, RoundMode::CAST_RINT, n);   // > 127 wraps to negative. No saturation.
-```
-
-As long as the row maximum `m` is exact, `u·127/m` lands exactly on 127 and the path
-is safe. **The moment `m` is slightly too small — a buggy reduction, say — `max_diff`
-jumps past 200.**
-
-> This is the amplifier for
-> [`pitfall-ascendc-cross-repeat-fold-src1`](../cross-repeat-fold/pitfalls.md): a
-> reduction that is a little wrong produces an output that is very wrong, so the size
-> of the error tells you nothing about the size of the bug.