Merged
修复基础API、CAPI PRELU公式和边界场景说明 #7007
LycheeeeeAdd on 11 days ago
修复基础API、CAPI PRELU公式和边界场景说明 #7007
Merged
LycheeeeeAdd on 11 days ago
Total: 5 files changed+10-10
@@ -29,7 +29,7 @@
29 29 
30头文件路径为:`"basic_api/kernel_operator_vec_binary_scalar_intf.h"`。30头文件路径为:`"basic_api/kernel_operator_vec_binary_scalar_intf.h"`。
31 31 
32-Prelu属于双目矢量类计算接口,源操作数src0大于0的情况下直接将src0写入目的操作数dst,否则将源操作数src0 * src1的结果写入dst。计算公式如下:32+Prelu属于双目矢量类计算接口,源操作数src0大于等于0的情况下直接将src0写入目的操作数dst,否则将源操作数src0 * src1的结果写入dst。注:源操作数src0中数据为浮点数正零(+0)时按正数处理并直接输出;为浮点数负零(-0)时按负数处理并与src1相乘。计算公式如下:
33 33 
34$dst_i = (src0_i \ge 0) ? src0_i : src0_i * src1_i$34$dst_i = (src0_i \ge 0) ? src0_i : src0_i * src1_i$
35 35 
@@ -41,10 +41,10 @@
41 41 
42头文件路径:`"basic_api/reg_compute/kernel_reg_compute_vec_binary_intf.h"`。42头文件路径:`"basic_api/reg_compute/kernel_reg_compute_vec_binary_intf.h"`。
43 43 
44-该接口用于实现PReLU(Parametric ReLU)激活函数:当源操作数srcReg0中对应元素大于0时,直接将该元素写入目的操作数dstReg;否则将srcReg0与srcReg1对应元素相乘的结果写入dstReg,计算公式如下:44+该接口用于实现PReLU(Parametric ReLU)激活函数:当源操作数srcReg0中对应元素大于等于0时,直接将该元素写入目的操作数dstReg,否则将srcReg0与srcReg1对应元素相乘的结果写入dstReg。注:源操作数srcReg0中数据为浮点数正零(+0)时按正数处理并直接输出;为浮点数负零(-0)时按负数处理并与srcReg1相乘。计算公式如下:
45 45 
46$$46$$
47-dstReg_i = \begin{cases} srcReg0_i & srcReg0_i > 0 \\ srcReg0_i \times srcReg1_i & srcReg0_i \leq 0 \end{cases}47+dstReg_i = \begin{cases} srcReg0_i & srcReg0_i >= 0 \\ srcReg0_i \times srcReg1_i & srcReg0_i < 0 \end{cases}
atomgit-botatomgit-bot
atomgit-botatomgit-bot11 days ago

🟡 Medium Priority

本次只改了 Prelu.md 的分段条件(> 0/\leq 0 → >= 0/< 0),但同一接口在其他文档中的公式与描述仍是旧形式:

失败模式:同一接口现在存在两套互斥的公式——概览页与索引页把 srcReg0 == 0 判到乘法分支,详情页判到直接输出分支。用户在概览页速查或由索引页跳转时,对零值边界(尤其本次新增强调的 +0/-0)会得到与详情页相反的结论,导致按概览页写出的边界处理代码与详情页契约不符。这类「契约在一侧改了、兄弟文档保留旧形态」的不一致属于本次改动单边引入。

建议:同步更新 overview.md:28 的 Prelu 公式(改为与详情页一致的条件,并同步 -0 归负说明)与 basic_api_list.md:348 的描述文案(「大于0」改为「大于等于0」,或直接改为「非负(含 +0)时直接输出」),保证概览、索引与详情页三处口径一致。

likedislike
Incorrect?
atomgit-botatomgit-bot11 days ago

🟡 Medium Priority

改动把分段条件从 srcReg0_i > 0 / srcReg0_i \leq 0 改为 srcReg0_i >= 0 / srcReg0_i < 0,同时在第 44、86 行新增说明「+0 按正数直接输出,-0 按负数并乘 srcReg1」。

问题在于:按 IEEE 754 比较语义,-0 >= 0 为真、-0 < 0 为假,即新公式把 -0 判到「直接输出」分支;而第 44/86 行的文字说明要求 -0 走乘法分支。二者互相矛盾。第 44/86 行的行为只能由符号位判定(signbit)实现,而不是由 >=/< 比较实现。

失败模式:用户按公式编写参考实现/校验代码 src >= 0 ? src : src * alpha,在 src 为 -0 且 alpha 为负数时,参考实现得到 -0(直接输出),硬件按文字说明得到 +0(=-0 × 负斜率),符号零不一致,进而影响后续 1/x(±inf)、log 等运算,导致自测误判或下游数值异常。校验示例第 208 行正是这种写法。

另外该行用 ASCII >= 而非与仓库其他文档一致的 LaTeX 记法 \geq,渲染排版不一致。

建议:把分段条件改为按符号位判定,并明确 +0/-0 的归属,使其与第 44/86 行文字一致,例如将两个分支条件写成 \operatorname{sign}(srcReg0_i) \geq 0(含 +0)与 \operatorname{sign}(srcReg0_i) < 0(含 -0),或在公式后紧跟一句「分支由符号位判定,+0 归正、-0 归负」;同时把 >= 改为 \geq。

likedislike
Incorrect?
48$$48$$
49 49 
50## 函数原型<a name="section620mcpsimp"></a>50## 函数原型<a name="section620mcpsimp"></a>
@@ -83,7 +83,7 @@ __simd_callee__ inline void Prelu(U &dstReg, U &srcReg0, U &srcReg1, MaskReg &ma
83 83 
84## 约束说明<a name="section633mcpsimp"></a>84## 约束说明<a name="section633mcpsimp"></a>
85 85 
86-无86+- 源操作数`srcReg0`中数据为浮点数正零(+0)时按正数处理并直接输出;为浮点数负零(-0)时按负数处理并与`srcReg1`相乘,乘法满足IEEE 754浮点乘法规则。
87 87 
88## 调用示例<a name="section232816306478"></a>88## 调用示例<a name="section232816306478"></a>
89 89 
@@ -25,7 +25,7 @@
25| [Min](Min.md) | $dstReg_i = \min(srcReg0_i, srcReg1_i)$ |25| [Min](Min.md) | $dstReg_i = \min(srcReg0_i, srcReg1_i)$ |
26| [Mul](Mul.md) | $dstReg_i = srcReg0_i \times srcReg1_i$ |26| [Mul](Mul.md) | $dstReg_i = srcReg0_i \times srcReg1_i$ |
27| [Mull](Mull.md) | $dstReg0_i = (srcReg0_i \times srcReg1_i) \bmod 2^{bit}$<br>$dstReg1_i = (srcReg0_i \times srcReg1_i) / 2^{bit}$<br>其中,bit表示操作数的位宽bit数。 |27| [Mull](Mull.md) | $dstReg0_i = (srcReg0_i \times srcReg1_i) \bmod 2^{bit}$<br>$dstReg1_i = (srcReg0_i \times srcReg1_i) / 2^{bit}$<br>其中,bit表示操作数的位宽bit数。 |
28-| [Prelu](Prelu.md) | $dstReg_i = \begin{cases} srcReg0_i & srcReg0_i > 0 \\ srcReg0_i \times srcReg1_i & srcReg0_i \leq 0 \end{cases}$ |28+| [Prelu](Prelu.md) | $dstReg_i = \begin{cases} srcReg0_i & srcReg0_i \geq 0 \\ srcReg0_i \times srcReg1_i & srcReg0_i < 0 \end{cases}$ |
29| [Sub](Sub.md) | $dstReg_i = srcReg0_i - srcReg1_i$ <br>$\{carry_i, dstReg_i\} = \{1'b0, srcReg0_i\} + \{1'b0, \sim srcReg1_i\} + 33'b1$ |29| [Sub](Sub.md) | $dstReg_i = srcReg0_i - srcReg1_i$ <br>$\{carry_i, dstReg_i\} = \{1'b0, srcReg0_i\} + \{1'b0, \sim srcReg1_i\} + 33'b1$ |
30| [SubC](SubC.md) | $\{carry_i, dstReg_i\} = \{1'b0, srcReg0_i\} + \{1'b0, \sim srcReg1_i\} + \{32'b0,carrySrc_i\}$ |30| [SubC](SubC.md) | $\{carry_i, dstReg_i\} = \{1'b0, srcReg0_i\} + \{1'b0, \sim srcReg1_i\} + \{32'b0,carrySrc_i\}$ |
31 31 
@@ -494,7 +494,7 @@ C API文档按最细粒度公共头文件归类。除试验接口外,整体使
494|[asc_madd](reg_compute/reg_fused/asc_madd.md)|madd(multiply-add),对源操作数执行逐元素乘法和加法。|`c_api/reg_compute/compute/reg_fused.h`|494|[asc_madd](reg_compute/reg_fused/asc_madd.md)|madd(multiply-add),对源操作数执行逐元素乘法和加法。|`c_api/reg_compute/compute/reg_fused.h`|
495|[asc_mul_scalar_float2half_rn](reg_compute/reg_fused/asc_mul_scalar_float2half_rn.md)|将float类型源操作数逐元素乘以标量后,按照RINT舍入模式转换为half类型。|`c_api/reg_compute/compute/reg_fused.h`|495|[asc_mul_scalar_float2half_rn](reg_compute/reg_fused/asc_mul_scalar_float2half_rn.md)|将float类型源操作数逐元素乘以标量后,按照RINT舍入模式转换为half类型。|`c_api/reg_compute/compute/reg_fused.h`|
496|[asc_mula](reg_compute/reg_fused/asc_mula.md)|根据掩码将两个源寄存器按元素相乘,并与目的寄存器累加。|`c_api/reg_compute/compute/reg_fused.h`|496|[asc_mula](reg_compute/reg_fused/asc_mula.md)|根据掩码将两个源寄存器按元素相乘,并与目的寄存器累加。|`c_api/reg_compute/compute/reg_fused.h`|
497-|[asc_prelu](reg_compute/reg_fused/asc_prelu.md)|源操作数src0大于0的情况下直接将src0写入目的操作数dst,否则将src0 * src1的结果写入dst。|`c_api/reg_compute/compute/reg_fused.h`|497+|[asc_prelu](reg_compute/reg_fused/asc_prelu.md)|源操作数src0大于等于0的情况下直接将src0写入目的操作数dst,否则将src0 * src1的结果写入dst。|`c_api/reg_compute/compute/reg_fused.h`|
498|[asc_relu](reg_compute/reg_fused/asc_relu.md)|逐元素执行ReLU运算。|`c_api/reg_compute/compute/reg_fused.h`|498|[asc_relu](reg_compute/reg_fused/asc_relu.md)|逐元素执行ReLU运算。|`c_api/reg_compute/compute/reg_fused.h`|
499|[asc_exp_sub](reg_compute/reg_fused/asc_exp_sub.md)|根据mask将src0与src1按元素相减,并计算以差值为指数的自然指数函数。|`c_api/reg_compute/compute/reg_fused.h`|499|[asc_exp_sub](reg_compute/reg_fused/asc_exp_sub.md)|根据mask将src0与src1按元素相减,并计算以差值为指数的自然指数函数。|`c_api/reg_compute/compute/reg_fused.h`|
500 500 
@@ -28,12 +28,12 @@
28 28 
29头文件路径为:`"c_api/reg_compute/compute/reg_fused.h"`。29头文件路径为:`"c_api/reg_compute/compute/reg_fused.h"`。
30 30 
31-根据掩码对源操作数矢量数据寄存器`src0`中的元素执行PReLU(Parametric ReLU)运算,负半轴斜率由矢量数据寄存器`alpha`中的对应元素指定,并将结果通过函数返回值返回或写入目的操作数矢量数据寄存器。`src0`大于0时直接写入输出结果,否则将`src0`与`alpha`相乘后写入输出结果。掩码对应位置为1的元素参与计算,为0的元素在输出结果中置零。计算公式如下:31+根据掩码对源操作数矢量数据寄存器`src0`中的元素执行PReLU(Parametric ReLU)运算,负半轴斜率由矢量数据寄存器`alpha`中的对应元素指定,并将结果通过函数返回值返回或写入目的操作数矢量数据寄存器。`src0`大于等于0时直接写入输出结果,否则将`src0`与`alpha`相乘后写入输出结果。注:源矢量数据寄存器中数据为浮点数正零(+0)时按正数处理并直接输出;为浮点数负零(-0)时按负数处理并与`alpha`相乘。掩码对应位置为1的元素参与计算,为0的元素在输出结果中置零。计算公式如下:
atomgit-bot
atomgit-botatomgit-bot11 days ago

🟡 Medium Priority

本次只改了详情页 asc_prelu.md 的分支条件与零值说明(第 31、35-36、102 行),但 C API 索引页 docs/zh/api/SIMD-API/c_api/c_api.md:497 仍是旧口径:

|[asc_prelu](reg_compute/reg_fused/asc_prelu.md)|源操作数src0大于0的情况下直接将src0写入目的操作数dst,否则将src0 * src1的结果写入dst。|

失败模式:索引页把 src0 == 0 判到乘法分支,详情页判到直接输出分支,同一接口在两页给出相反的零值契约;用户从 c_api.md 速查接口语义时无法得知本次修正的 +0/-0 边界行为,按索引页写的边界用例会按旧语义构造期望值。此外索引页的 src1 参数名与详情页的 alpha 也不一致(历史遗留,本次改动使两页口径差距进一步扩大)。

建议:同步更新 docs/zh/api/SIMD-API/c_api/c_api.md:497 的 asc_prelu 描述为「源操作数 src0 大于等于 0(含 +0)时直接写入 dst,否则将 src0 与 alpha 相乘后写入 dst」,并把参数名 src1 改为 alpha,使其与详情页契约一致。

likedislike
Incorrect?
32 32 
33$$33$$
34dst_i = \begin{cases}34dst_i = \begin{cases}
35-src0_i, & src0_i > 0 \\35+src0_i, & src0_i >= 0 \\
36-src0_i \times \alpha_i, & src0_i \leq 036+src0_i \times \alpha_i, & src0_i < 0
atomgit-bot
atomgit-botatomgit-bot11 days ago

🟡 Medium Priority

asc_prelu.md 的公式条件改为 src0_i >= 0 / src0_i < 0(第 35、36 行),但第 31、102 行新增文字要求「+0 直接输出、-0 按负数并与 alpha 相乘」。

按 IEEE 754 比较语义,-0 >= 0 为真、-0 < 0 为假,即公式把 -0 归入「直接输出」分支,与第 31/102 行的说明(-0 走乘法分支)矛盾;说明所述行为只能由符号位判定实现,无法用 >=/< 表达。

失败模式:用户以公式为准编写参考实现或精度比对脚本 src0 >= 0 ? src0 : src0 * alpha,在 src0 为 -0 且 alpha 为负时得到 -0,而硬件按说明得到 +0,符号零不一致,会使自测误判或让下游 1/x、log 等产生 ±inf 差异。对照 asc_leakyrelu.md:99 与 tensor_api/.../prelu.md:74 均以「负零按负数处理」表述,说明仓库内约定是按符号位判定,本条公式与之不符。

建议:将分段条件改为按符号位判定以与第 31/102 行说明一致(如 \operatorname{sign}(src0_i) \geq 0 含 +0 / \operatorname{sign}(src0_i) < 0 含 -0),或在公式后补一句「分支由符号位判定,+0 归正、-0 归负」;同时把 ASCII >= 改成与仓库其他文档一致的 LaTeX \geq。

likedislike
Incorrect?
37\end{cases}37\end{cases}
38$$38$$
39 39 
@@ -99,7 +99,7 @@ __simd_callee__ inline void asc_prelu(vector_half& dst,
99 99 
100### 计算约束100### 计算约束
101 101 
102-- 源矢量数据寄存器中数据为负零(-0)时按负数处理,乘法满足IEEE 754浮点乘法规则。102+- 源矢量数据寄存器中数据为浮点数正零(+0)时按正数处理并直接输出;为浮点数负零(-0)时按负数处理并与`alpha`相乘,乘法满足IEEE 754浮点乘法规则。
103 103 
104## 调用示例104## 调用示例
105 105