问题描述

aclnnUnfoldGrad 文档错误码表把 5 类约束统一归到 561002（ACLNN_ERR_INNER_TILING_ERROR），但其中至少 4 类在实际调用链上根本到不了 tiling——aclnnUnfoldGradGetWorkspaceSize 的 CheckParams 会先将其拦截并返回 161002（ACLNN_ERR_PARAM_INVALID）。文档承诺的错误码与代码路径不符。

位置：

• 文档错误码表：conversion/unfold_grad/docs/aclnnUnfoldGrad.md:214（561002，rowspan="5"）
• aclnn 层前置校验：conversion/unfold_grad/op_api/aclnn_unfold_grad.cpp:118-138（CheckParams）
• tiling 层校验：conversion/unfold_grad/op_host/unfold_grad_tiling.cpp:211-242

逐项对照

文档在 561002 下共列 5 项，逐项追踪实际返回路径：

¹ 第 1 项确实只由 tiling 校验（:230-235），但 tiling 返回 ge::GRAPH_FAILED 后，框架最终映射到哪个公开错误码，需沿调用链确认，不能仅凭 tiling 日志推断。

² 全仓无 size > inputSizes[dim] 的显式判断（grep 无命中）。size 偏大时只能由 tiling :230-236 的公式 gradOutSizeDim != (inputSizeArray[dim] - size) / step + 1 间接拦下，故其返回路径与第 1 项相同。这一点另见第 2 单（末维约束）的同源核对。

关键代码顺序

// op_api/aclnn_unfold_grad.cpp:118  先跑 CheckParams
static aclnnStatus CheckParams(...)
{
    CHECK_RET(CheckNotNull(gradOut, inputSizes, gradIn), ACLNN_ERR_INNER_NULLPTR);
    CHECK_RET(CheckDtypeValid(gradOut, gradIn), ACLNN_ERR_PARAM_INVALID);
    CHECK_RET(CheckShapeValid(gradOut, inputSizes, gradIn), ACLNN_ERR_PARAM_INVALID);   // <- 第 2 项在此拦截
    int64_t dimNum = gradOut->GetViewShape().GetDimNum();
    CHECK_RET(dim >= 0 && dim < dimNum - 1, ACLNN_ERR_PARAM_INVALID);                    // <- 第 5 项
    CHECK_RET(size > 0, ACLNN_ERR_PARAM_INVALID);                                        // <- 第 3 项
    CHECK_RET(step > 0, ACLNN_ERR_PARAM_INVALID);                                        // <- 第 4 项
    CHECK_RET(CheckFormat(gradOut), ACLNN_ERR_PARAM_INVALID);
    return ACLNN_SUCCESS;
}

// 主流程 :152  CheckParams 通过后才可能进入 tiling
auto ret = CheckParams(gradOut, inputSizes, dim, size, step, gradIn);
CHECK_RET(ret == ACLNN_SUCCESS, ret);

CheckParams 里的 CHECK_RET 一旦失败即刻 return，tiling 不会被调用。因此文档把这几类归到 561002（tiling 内部错误）与代码实际控制流直接矛盾。

CheckShapeValid 中对应第 2 项的实际校验

// :84-88
OP_CHECK(inputSizes->Size() == gradOutDimNum - 1,
         OP_LOGE(ACLNN_ERR_PARAM_INVALID, "inputSizes length should be equal to Dim of gradOut - 1, but got %zu.",
                 inputSizes->Size()),
         return false);

OP_CHECK 失败 → 返回 false → CheckParams 返回 ACLNN_ERR_PARAM_INVALID（161002）。

影响

调用方按文档错误码表做分类处理时，会走进错误分支：

• 文档写「561002 内部 tiling 异常」，调用方据此判定为算子内部故障并上报/重试；
• 实际是调用方自己传错了 size / step / dim / inputSizes 长度，返回 161002（参数错误），本应直接修正入参。

同一族「几何参数非法」被文档归入内部错误码，会把用户侧入参错误误判为算子缺陷，误导排查方向。

环境信息

• 被检仓：cann/ops-math HEAD 3e45432d（2026-10-21）
• 涉及算子：aclnnUnfoldGrad（conversion/unfold_grad）
• 本项结论来自源码控制流与文档的静态对照，不需要设备实测即可确认前置拦截顺序；第 1 项的实际公开返回码需沿调用链确认（见下文预期结果）

重现步骤

静态核对，无需编译运行：

# 1. 文档把 5 项都归到 561002
sed -n '214,228p' conversion/unfold_grad/docs/aclnnUnfoldGrad.md

# 2. aclnn 层在其之前就拦掉 4 项，返回 161002
sed -n '118,138p' conversion/unfold_grad/op_api/aclnn_unfold_grad.cpp

# 3. tiling 只在 CheckParams 通过后才执行
sed -n '150,155p' conversion/unfold_grad/op_api/aclnn_unfold_grad.cpp

真机验证（如需确认第 1 项的公开返回码）：

// 构造 gradOut 第 dim 维与公式不符，其余参数全部合法
// 使 size/step/dim/inputSizes 长度均通过 aclnn 前置校验
// 只违反「gradOut 第 dim 维 == (inputSizes[dim]-size)/step+1」
aclnnStatus ret = aclnnUnfoldGradGetWorkspaceSize(gradOut, inputSizes, dim, size, step, gradIn, ...);
// 记录 ret，对照文档承诺的 561002

预期结果

二者择一：

方案 A（推荐，改文档）：按实际控制流拆分错误码归属——

• size ≤ 0、step ≤ 0、dim 越界、inputSizes 长度 ≠ gradOut 维数-1 → 移入 161002；
• 仅 gradOut 第 dim 维不等于 (inputSizes[dim]-size)/step+1 保留在 561002（并核实实际公开返回码后填写准确值）。

方案 B（改实现）：若设计上确应统一为 561002，则需调整 CheckParams 中 size / step / dim / 形状校验的返回码，使其与文档一致。

无论选哪个方向，都需在文档中说明「前置校验（161002）」与「tiling 校验」的分界。

备注

与 #3797 的关系

本单拆自 #3797。按维护者分类口径，本项对应「tiling 与 API 返回码口径」，是 4 项中唯一涉及实现在位差异的一项，单独跟踪。

与 #3795 的边界

#3795 已覆盖 dim 的上界校验缺失（len(inputSizes)=3 时 dim=0 被放行）。本单不重复报告该校验缺失，只指出文档错误码归属与代码控制流不符；即使 #3795 修复了 dim 双轴校验，本单的「归属错误」依然成立（修复后 dim 越界仍返回 161002，而非文档写的 561002）。

未纳入本单的推断

原始汇总单 #3797 曾描述「形状类违规实测返回 561103」。经复核：561103（ACLNN_ERR_INNER_NULLPTR）对应空指针路径，而本算子 aclnn 层 CheckNotNull 失败返回的正是 ACLNN_ERR_INNER_NULLPTR（该行为已由 #3795 单列）；561002 在整个 conversion/ 目录中无任何引用，综上该「实测」结论缺乏依据，本单不予采用，改为按代码控制流陈述，并把 tiling 映射结果列为待确认。

涉及文件

• conversion/unfold_grad/docs/aclnnUnfoldGrad.md（错误码表，:214-229）
• conversion/unfold_grad/op_api/aclnn_unfold_grad.cpp（CheckParams，:118-138）
• conversion/unfold_grad/op_host/unfold_grad_tiling.cpp（:211-242）