文档链接

• 仓库：cann/ops-math
• 版本：master @ 584b2ea6cbaeba684a51a74296d82d4d50ab3b0f
• 头文件：math/round/op_api/aclnn_round.h:54
• 资料：math/round/docs/aclnnRound&aclnnInplaceRound.md:249

问题文档片段

问题描述：aclnnInplaceRoundGetWorkspaceSize 的 @param [in] selfRef 注释中，dtype 支持列表漏列 BFLOAT16；而同一文件里 out-of-place 的 self 注释、以及同仓资料参数表中 selfRef 的「数据类型」列，均包含 BFLOAT16。三处口径不一致，头文件是唯一漏掉的那一处。

推导链：

1. 同文件 aclnn_round.h:26，aclnnRoundGetWorkspaceSize 的 self 注释写明支持 BFLOAT16,FLOAT16, FLOAT32, DOUBLE, INT32, INT64。
2. 同文件 aclnn_round.h:54，aclnnInplaceRoundGetWorkspaceSize 的 selfRef 注释只写 FLOAT16, FLOAT32, DOUBLE, INT32, INT64，缺 BFLOAT16。
3. 资料 math/round/docs/aclnnRound&aclnnInplaceRound.md:245-249 的 selfRef（aclTensor*） 行，「数据类型」列为 BFLOAT16、FLOAT16、FLOAT32、DOUBLE、INT32、INT64，含 BFLOAT16。
4. Round 与 InplaceRound 是同一算子的两种写法，selfRef 与 self 的 dtype 支持面在语义上应当对齐；资料侧确实已对齐（两处都是同一张六元列表）。
5. 因此漏列只在 aclnn_round.h:54 这一处注释，判定为注释与资料不一致，而非「BFLOAT16 本就不支持」。

反向排除：

1. 不是资料也漏了：资料 selfRef 行逐字包含 BFLOAT16（见下「对照片段 2」），所以不是「两侧一致地不支持」，而是头文件单侧漂移。
2. 不是该接口整体不支持 BFLOAT16：同文件同算子的 self 注释（L26）含 BFLOAT16，若 InplaceRound 真的不支持该 dtype，资料表就不会把 BFLOAT16 列进 selfRef。
3. 不是措辞差异导致的误读：两处列表元素个数不同（5 项 vs 6 项），是缺项而不是换序或别名写法（如用 BF16 之类缩写），脚本对 BFLOAT16 字面量做精确匹配。

影响：以头文件注释作为唯一契约来源的下游（自研框架适配层、算子选型脚本、文档生成流水线）会把 BFLOAT16 排除在 InplaceRound 的可用 dtype 之外，从而对 bf16 张量额外插入一次 Cast，或在 bf16 场景下退回 out-of-place 写法，多一次显存往返。资料侧目前已是对的，所以这是纯头文件侧缺陷。

原文片段（math/round/op_api/aclnn_round.h:54-55，逐字）：

 * @param [in] selfRef: npu device侧的aclTensor，数据类型支持FLOAT16, FLOAT32, DOUBLE, INT32, INT64，
 * 数据格式支持ND，shape不支持9D及以上。

对照片段 1（同文件 aclnn_round.h:26-27，self，逐字）：

 * @param [in] self: npu device侧的aclTensor，数据类型支持BFLOAT16,FLOAT16, FLOAT32, DOUBLE, INT32, INT64，
 * 数据格式支持ND，shape不支持9D及以上。

对照片段 2（math/round/docs/aclnnRound&aclnnInplaceRound.md:245-251，逐字）：

      <td>selfRef（aclTensor*）</td>
      <td>输入/输出</td>
      <td>输入Tensor。</td>
      <td>支持空Tensor。</td>
      <td>BFLOAT16、FLOAT16、FLOAT32、DOUBLE、INT32、INT64</td>
      <td>ND</td>
      <td>0-8</td>

复现三件套：

• 类型：静态文本断言（头文件注释 dtype 列表）
• 退出码语义：0 = 符合预期（不成立）／1 = 缺陷成立并打印 [DEFECT]／2 = 无法判定
• 期望值：0；实测值：1

脚本全文：

#!/usr/bin/env python3
import argparse, os, re, sys

def blocks(lines, param):
    out, cur = [], None
    for ln in lines:
        if re.search(r"@param\s*\[in\]\s*%s\b" % re.escape(param), ln):
            cur = [ln]; out.append(cur); continue
        if cur is not None:
            if "@param" in ln or "*/" in ln: cur = None
            else: cur.append(ln)
    return out

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--repo", required=True)
    ap.add_argument("--file", required=True)
    ap.add_argument("--fn", required=True)
    ap.add_argument("--param", required=True)
    ap.add_argument("--needle", required=True)
    ap.add_argument("--claim", choices=["missing", "extra"], required=True)
    a = ap.parse_args()
    path = os.path.join(a.repo, a.file)
    if not os.path.isfile(path):
        print("[SKIP] 文件不存在: %s" % path); return 2
    src = open(path, encoding="utf-8", errors="replace").read()
    lines = src.splitlines()
    if a.fn not in src:
        print("[SKIP] 未找到 %s" % a.fn); return 2
    start = next(i for i, l in enumerate(lines) if a.fn in l)
    blks = blocks(lines[max(0, start - 40):start + 2], a.param)
    if not blks:
        print("[SKIP] 未找到 @param [in] %s 注释块（措辞可能已变，人工确认）" % a.param); return 2
    text = "\n".join("\n".join(b) for b in blks)
    if "数据类型" not in text and "FLOAT16" not in text:
        print("[SKIP] 注释块里没有可识别的 dtype 列表（人工确认）"); return 2
    hit = a.needle in text
    print("文件: %s" % a.file)
    print("锚点: @param [in] %s 的 dtype 列表" % a.param)
    print("现状: %s %s" % ("含" if hit else "不含", a.needle))
    if a.claim == "missing":
        if hit:
            print("结论: 已包含，本条不成立"); return 0
        print("[DEFECT] 应含 %s 而缺失" % a.needle); return 1
    else:
        if not hit:
            print("结论: 确实不含，本条不成立"); return 0
        print("[DEFECT] 不应含 %s 却出现" % a.needle); return 1

if __name__ == "__main__":
    sys.exit(main())

实测输出：

$ python3 check_param_dtype.py --repo <repo> --file math/round/op_api/aclnn_round.h \
    --fn aclnnInplaceRoundGetWorkspaceSize --param selfRef --needle BFLOAT16 --claim missing
文件: math/round/op_api/aclnn_round.h
锚点: @param [in] selfRef 的 dtype 列表
现状: 不含 BFLOAT16
[DEFECT] 应含 BFLOAT16 而缺失
exit=1

对照组（证明脚本有判别力，不是恒返回 1）：

$ python3 check_param_dtype.py --repo <repo> --file math/round/op_api/aclnn_round.h \
    --fn aclnnRoundGetWorkspaceSize --param self --needle BFLOAT16 --claim missing
文件: math/round/op_api/aclnn_round.h
锚点: @param [in] self 的 dtype 列表
现状: 含 BFLOAT16
结论: 已包含，本条不成立
exit=0

存在的问题

修复建议：将 math/round/op_api/aclnn_round.h:54 整行改为（补 BFLOAT16,，与 L26 的 self 行保持同一写法与顺序）：

 * @param [in] selfRef: npu device侧的aclTensor，数据类型支持BFLOAT16,FLOAT16, FLOAT32, DOUBLE, INT32, INT64，

证据与环境：

• 复现方式：静态断言脚本（无设备依赖，任何平台可复跑）
• 实测返回码：1（含 [DEFECT]），对照组 0
• 设备型号／CANN 版本：本条为纯注释文本断言，不涉及运行时，未使用设备
• 说明：本条仅主张「头文件注释 dtype 列表与同仓资料表不一致」，成立性完全由仓内文本决定，不依赖任何真机行为。

完整文件清单：

• math/round/op_api/aclnn_round.h（L54，待修改）
• math/round/docs/aclnnRound&aclnnInplaceRound.md（L245-251，参照，无需修改）