Closed
[Documentation|文档反馈]:[aclnnForeachAddListV2] aclnnForeachAddListV2 资料三处与实现/事实不符(out shape 约束、空 Tensor 支持面、头文件 dtype 注释) #7926
liuhanwen8Add on  20 days agoClosed at  17 days ago
liuhanwen8
liuhanwen8
20 days ago Create

Document Link(文档链接)

cann/ops-nn 的 foreach/foreach_add_list/docs/aclnnForeachAddListV2.md 存在资料问题(条目 2.1-01)。

项 值
接口 / 资料 aclnnForeachAddListV2
文件锚点 foreach/foreach_add_list/docs/aclnnForeachAddListV2.md
checklist 条目 2.1-01(维度 2.1)
影响旅程 -
证据等级 E1
级别 P2

Issues Section(问题文档片段)

问题描述:同一份资料与头文件里有三处与实现/事实不符,均已真机取证(Ascend 910B2 / CANN 9.2.0):
① out 行「使用说明」写「shape size 大于等于入参 x1 的 shape size」,但实现要求严格相等,out=fp32[2x4] 配 x1=fp32[2x3] 第一段返回 161002;
② x1/x2/out 三行都写「不支持空Tensor」,但实现没有空 tensor 拦截:单块 [0] 与「空块藏在多块列表里」两种形态两段均返回 0;
③ 交付头文件 op_host/op_api/aclnn_foreach_add_list_v2.h 的 x1/x2/alpha/out 四个 @param 注释都只写「FLOAT,FLOAT16,BFLOAT16,INT32」四种 dtype,漏列 INT16/INT8/UINT8(资料 dtype 列有,实测可用)。

推导链:① 资料 out 行原文「shape size大于等于入参x1的shape size」;op_host/op_api/aclnn_foreach_add_list_v2.cpp 的 ForeachAddListV2CheckShape 用 OP_CHECK_SHAPE_NOT_EQUAL((self)[i], (out)[i]) 要求严格相等;实测 out=fp32[2x4] vs x1=fp32[2x3] → rc=161002;参考框架 torch._foreach_add 传更大 out 也报 TypeError(与实现一致)。
② 资料三处「不支持空Tensor」;CheckParams 无 numel==0 分支;实测 x1=x2=out=fp32[0] 与「第二块 [0]」两段均 rc=0;torch.foreach_add 也接受空 tensor(与实现一致、与资料不一致)。
③ 头文件 x1 的 @param 注释原文「输入Tensor,数据类型支持FLOAT,FLOAT16,BFLOAT16,INT32。数据格式支持ND。」;资料 dtype 列含 INT16/INT8/UINT8;实测 int8/int16/uint8 用例全 PASS,kernel 名为 ForeachAddList_Int16
/ ForeachAddList_Uint8_
。
三条均由同一份自包含脚本复现:exit=1 且逐条打印 [DEFECT]。

反向排除:①② 不是实现缺陷:两处实现行为都与 torch 参考框架一致,只是资料表述超出/偏离实现;若维护者认为应支持更大 out 或应拒绝空 tensor,则属实现需求变更。③ 不涉及实现行为,属注释与资料的 dtype 面不一致。

影响:必备信息缺失,读者按资料操作会卡住或做出错误选择。

原文片段(foreach/foreach_add_list/docs/aclnnForeachAddListV2.md):

数据类型和数据格式与入参`x1`的数据类型和数据格式一致,shape size大于等于入参`x1`的shape size。

复现:

  • 复现类型:text_absent(断言目标文件中应存在的内容缺失)
  • 退出码语义:0 资料符合预期 / 1 缺陷成立 / 2 无法判定
  • 期望:shape size大于等于入参x1
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""aclnnForeachAddListV2 资料三项一致性复现(自包含,只用 CANN 公开 C API)。

只依赖 libascendcl.so / libopapi.so(CANN 运行包自带),不依赖任何测试框架。

    python3 aclnnForeachAddListV2_21-01.py [--repo-root <ops-nn 仓根>]

检查项与判据:
  ① 资料 out 行「shape size 大于等于入参 x1」      —— out 比 x1 大若返回 161002 则资料失真
  ② 资料 x1/x2/out 行「不支持空Tensor」            —— numel==0 若两段均返回 0 则资料失真
  ③ 头文件 x1 的 @param 注释只列 4 种 dtype         —— 资料/实测支持 7 种则注释漏列

退出码:0 = 资料与实现一致;1 = 缺陷成立(逐条打印 [DEFECT]);2 = 无法判定(缺库/缺仓)。
"""
from __future__ import annotations

import argparse
import ctypes
import glob
import os
import re
import sys

# ---- acl 枚举(acl_base.h / acl_base_rt.h 公开值) -------------------------
DT = {"fp32": 0, "fp16": 1, "int8": 2, "int32": 3, "uint8": 4,
      "int16": 6, "fp64": 11, "bf16": 27, "int64": 9}
SIZE = {"fp32": 4, "fp16": 2, "int8": 1, "int32": 4, "uint8": 1,
        "int16": 2, "fp64": 8, "bf16": 2, "int64": 8}
FMT_ND = 2
H2D, D2H = 1, 2
HUGE_FIRST = 0

DEFECTS = []


def find_home() -> str:
    """CANN 根:先看 ASCEND_HOME_PATH,再扫常见安装位置(含 libopapi.so 的目录向上两级)。"""
    home = os.environ.get("ASCEND_HOME_PATH", "").strip()
    if home and os.path.isdir(home):
        return home
    for cand in ("/usr/local/Ascend/ascend-toolkit/latest", "/usr/local/Ascend/latest"):
        if os.path.isdir(cand):
            return cand
    for pat in ("/usr/local/Ascend/*/latest", "/home/*/cann/cann-*", "/home/*/cann/ascend-toolkit/latest",
                "/usr/local/Ascend/ascend-toolkit/*"):
        for cand in sorted(glob.glob(pat)):
            if glob.glob(os.path.join(cand, "**", "libopapi.so"), recursive=True):
                return cand
    raise RuntimeError("找不到 CANN 安装目录(设 ASCEND_HOME_PATH)")


def load_libs(home: str):
    def pick(lib: str):
        pats = [os.path.join(home, "aarch64-linux", "lib64", lib),
                os.path.join(home, "lib64", lib),
                os.path.join(home, "**", lib)]
        for p in pats:
            for hit in glob.glob(p, recursive=True):
                try:
                    return ctypes.CDLL(hit)
                except OSError:
                    continue
        return None

    acl = pick("libascendcl.so")
    opapi = pick("libopapi.so")
    nno = pick("libnnopbase.so")   # aclCreateTensor/aclCreateScalar/aclCreateTensorList 在这里
    if acl is None or opapi is None:
        raise RuntimeError("缺 libascendcl.so 或 libopapi.so(home=%s)" % home)
    return acl, opapi, nno


class Rt:
    def __init__(self) -> None:
        self.home = find_home()
        self.acl, self.opapi, self.nno = load_libs(self.home)
        a = self.acl
        a.aclInit.argtypes = [ctypes.c_void_p]
        a.aclInit.restype = ctypes.c_int
        a.aclrtSetDevice.argtypes = [ctypes.c_int32]
        a.aclrtSetDevice.restype = ctypes.c_int
        a.aclrtCreateStream.argtypes = [ctypes.POINTER(ctypes.c_void_p)]
        a.aclrtCreateStream.restype = ctypes.c_int
        a.aclrtSynchronizeStream.argtypes = [ctypes.c_void_p]
        a.aclrtSynchronizeStream.restype = ctypes.c_int
        a.aclrtMalloc.argtypes = [ctypes.POINTER(ctypes.c_void_p), ctypes.c_size_t, ctypes.c_int]
        a.aclrtMalloc.restype = ctypes.c_int
        a.aclrtMemcpy.argtypes = [ctypes.c_void_p, ctypes.c_size_t, ctypes.c_void_p,
                                  ctypes.c_size_t, ctypes.c_int]
        a.aclrtMemcpy.restype = ctypes.c_int
        a.aclrtFree.argtypes = [ctypes.c_void_p]
        a.aclrtFree.restype = ctypes.c_int
        _op = self.nno if self.nno is not None else a
        self._op = _op
        _op.aclCreateTensor.restype = ctypes.c_void_p
        _op.aclCreateTensor.argtypes = [ctypes.POINTER(ctypes.c_int64), ctypes.c_uint64,
                                      ctypes.c_int, ctypes.POINTER(ctypes.c_int64),
                                      ctypes.c_int64, ctypes.c_int,
                                      ctypes.POINTER(ctypes.c_int64), ctypes.c_uint64,
                                      ctypes.c_void_p]
        _op.aclCreateScalar.restype = ctypes.c_void_p
        _op.aclCreateScalar.argtypes = [ctypes.c_void_p, ctypes.c_int]
        for nm in ("aclDestroyTensor", "aclDestroyScalar", "aclDestroyTensorList"):
            if hasattr(a, nm):
                getattr(a, nm).argtypes = [ctypes.c_void_p]
                getattr(a, nm).restype = ctypes.c_int
        self._list_fn = None
        for lib in (self.nno, self.acl, self.opapi):
            if hasattr(lib, "aclCreateTensorList"):
                fn = lib.aclCreateTensorList
                fn.restype = ctypes.c_void_p
                fn.argtypes = [ctypes.POINTER(ctypes.c_void_p), ctypes.c_uint64]
                self._list_fn = fn
                break
        if self._list_fn is None:
            raise RuntimeError("lib 里没有 aclCreateTensorList(CANN 版本过旧)")
        self.opapi.aclnnForeachAddListV2GetWorkspaceSize.restype = ctypes.c_int
        self.opapi.aclnnForeachAddListV2GetWorkspaceSize.argtypes = [
            ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p,
            ctypes.POINTER(ctypes.c_uint64), ctypes.POINTER(ctypes.c_void_p)]
        self.opapi.aclnnForeachAddListV2.restype = ctypes.c_int
        self.opapi.aclnnForeachAddListV2.argtypes = [ctypes.c_void_p, ctypes.c_uint64,
                                                    ctypes.c_void_p, ctypes.c_void_p]
        self._init = False

    def init(self, dev: int = 0) -> None:
        if self._init:
            return
        rc = self.acl.aclInit(None)
        if rc != 0:
            raise RuntimeError("aclInit failed rc=%d" % rc)
        rc = self.acl.aclrtSetDevice(dev)
        if rc != 0:
            raise RuntimeError("aclrtSetDevice(%d) failed rc=%d" % (dev, rc))
        self.stream = ctypes.c_void_p()
        rc = self.acl.aclrtCreateStream(ctypes.byref(self.stream))
        if rc != 0:
            raise RuntimeError("aclrtCreateStream failed rc=%d" % rc)
        self._init = True

    # ---- 张量构造 ----
    def tensor(self, dtype: str, shape, fill=None):
        n = 1
        for d in shape:
            n *= d
        nbytes = max(n * SIZE[dtype], 1)
        ptr = ctypes.c_void_p()
        rc = self.acl.aclrtMalloc(ctypes.byref(ptr), nbytes, HUGE_FIRST)
        if rc != 0:
            raise RuntimeError("aclrtMalloc %d bytes failed rc=%d" % (nbytes, rc))
        vals = fill if fill is not None else [1.0] * n
        buf = (ctypes.c_float * n)(*[float(v) for v in vals]) if dtype in ("fp32",) else None
        host = ctypes.create_string_buffer(nbytes)
        if dtype == "fp32":
            ctypes.memmove(host, buf, nbytes)
        else:  # 其余 dtype 用 0/1 填充即可,只关心返回码
            ctypes.memset(host, 0, nbytes)
        rc = self.acl.aclrtMemcpy(ptr, nbytes, ctypes.cast(host, ctypes.c_void_p), nbytes, H2D)
        if rc != 0:
            raise RuntimeError("aclrtMemcpy H2D failed rc=%d" % rc)
        dims = (ctypes.c_int64 * max(len(shape), 1))(*([1] if not shape else list(shape)))
        strides = []
        acc = 1
        for d in reversed(list(shape) or [1]):
            strides.insert(0, acc)
            acc *= d
        st = (ctypes.c_int64 * max(len(strides), 1))(*(strides or [1]))
        t = self._op.aclCreateTensor(dims, len(shape), DT[dtype], st, 0, FMT_ND,
                                     dims, len(shape), ptr)
        if not t:
            raise RuntimeError("aclCreateTensor 返回空")
        return t, ptr

    def scalar(self, dtype: str, value: float):
        buf = ctypes.c_double(float(value))
        s = self._op.aclCreateScalar(ctypes.byref(buf), DT[dtype])
        if not s:
            raise RuntimeError("aclCreateScalar 返回空")
        return s

    def tensorlist(self, tensors):
        arr = (ctypes.c_void_p * len(tensors))(*tensors)
        lst = self._list_fn(arr, len(tensors))
        if not lst:
            raise RuntimeError("aclCreateTensorList 返回空")
        return lst

    def run(self, shapes, dtype="fp32", out_shapes=None, alpha=1.0, alpha_dt="fp32"):
        """构造 x1/x2/out 三个等长列表并跑两段式,返回 (rc1, rc2)。"""
        n = len(shapes)
        out_shapes = out_shapes or shapes
        keep = []
        x1 = [self.tensor(dtype, sh)[0] for sh in shapes]
        x2 = [self.tensor(dtype, sh)[0] for sh in shapes]
        outs = [self.tensor(dtype, sh)[0] for sh in out_shapes]
        keep = x1 + x2 + outs
        l1 = self.tensorlist(x1)
        l2 = self.tensorlist(x2)
        lo = self.tensorlist(outs)
        sc = self.scalar(alpha_dt, alpha)
        ws = ctypes.c_uint64(0)
        ex = ctypes.c_void_p()
        rc1 = self.opapi.aclnnForeachAddListV2GetWorkspaceSize(l1, l2, sc, lo,
                                                              ctypes.byref(ws), ctypes.byref(ex))
        rc2 = None
        if rc1 == 0:
            wptr = ctypes.c_void_p()
            if ws.value > 0:
                self.acl.aclrtMalloc(ctypes.byref(wptr), ws.value, HUGE_FIRST)
            rc2 = self.opapi.aclnnForeachAddListV2(wptr, ws.value, ex, self.stream)
            if rc2 == 0:
                self.acl.aclrtSynchronizeStream(self.stream)
            if ws.value > 0:
                self.acl.aclrtFree(wptr)
        for h in (l1, l2, lo):
            if hasattr(self.acl, "aclDestroyTensorList"):
                self.acl.aclDestroyTensorList(h)
        for t in keep:
            if hasattr(self.acl, "aclDestroyTensor"):
                self.acl.aclDestroyTensor(t)
        if hasattr(self.acl, "aclDestroyScalar"):
            self.acl.aclDestroyScalar(sc)
        return rc1, rc2


def main() -> int:
    ap = argparse.ArgumentParser()
    ap.add_argument("--repo-root", default=os.environ.get("FOREACH_ADD_LIST_REPO", "."),
                    help="ops-nn 仓根(默认当前目录)")
    ap.add_argument("--device", type=int, default=0)
    args = ap.parse_args()
    sub = "foreach/foreach_add_list"
    doc_path = os.path.join(args.repo_root, sub, "docs/aclnnForeachAddListV2.md")
    hdr_path = os.path.join(args.repo_root, sub, "op_host/op_api/aclnn_foreach_add_list_v2.h")
    if not os.path.isfile(doc_path):
        print("[UNABLE] 找不到资料:%s(用 --repo-root 指定 ops-nn 仓根)" % doc_path)
        return 2
    doc = open(doc_path, encoding="utf-8").read()

    # ③ 头文件注释(纯文本,不需要 NPU)
    if os.path.isfile(hdr_path):
        hdr = open(hdr_path, encoding="utf-8").read()
        m = re.search(r"@param\s*\[in\]\s*x1[^\n]*", hdr)
        if m:
            tail = m.group(0) + " " + " ".join(x.strip(" *") for x in hdr[m.end():].splitlines()[:3])
            print("[HDR] ③ %s" % tail.strip()[:160])
            lacking = [d for d in ("INT16", "INT8", "UINT8") if d not in tail.replace(" ", "")]
            if lacking and all(d in doc for d in ("INT16", "INT8", "UINT8")):
                DEFECTS.append("③ 头文件 aclnn_foreach_add_list_v2.h 的 x1 注释漏列 %s"
                               "(资料 dtype 列有、实测可用)" % "/".join(lacking))

    # ①② 上板
    try:
        rt = Rt()
        rt.init(args.device)
    except Exception as exc:  # noqa: BLE001
        print("[UNABLE] 上板环境不可用(%s);③ 仍有效,①② 需在 NPU 机器复跑" % str(exc)[:160])
        if DEFECTS:
            for d in DEFECTS:
                print("[DEFECT] " + d)
            return 1
        return 2

    try:
        if "shape size" in doc and "大于等于" in doc:
            rc1, rc2 = rt.run([[2, 3]], out_shapes=[[2, 4]])
            print("[RUN] ① out=fp32[2x4] vs x1=fp32[2x3] → rc1=%s rc2=%s" % (rc1, rc2))
            if rc1 == 161002:
                DEFECTS.append("① 资料声明 out 可以「shape size 大于等于 x1」,实测 out 比 x1 大返回 161002"
                               "(实现要求严格相等)")
            elif rc1 == 0:
                print("[OK] ① 实现接受更大的 out,与资料一致")
        else:
            print("[SKIP] ① 资料已无该表述")

        if "不支持空Tensor" in doc:
            rc_a = rt.run([[0]])
            print("[RUN] ② 单块 x1=x2=out=fp32[0] → rc1=%s rc2=%s" % rc_a)
            rc_b = rt.run([[2, 3], [0]])
            print("[RUN] ② 两块列表(第二块为空) → rc1=%s rc2=%s" % rc_b)
            if rc_a == (0, 0) and rc_b == (0, 0):
                DEFECTS.append("② 资料声明 x1/x2/out「不支持空Tensor」,实测两种空 tensor 形态两段均返回 0")
    finally:
        pass

    if DEFECTS:
        for d in DEFECTS:
            print("[DEFECT] " + d)
        print("[SUMMARY] 共 %d 项资料与实现/事实不符" % len(DEFECTS))
        return 1
    print("[OK] 各项与实现/事实一致")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

实测输出(退出码 1):

[HDR] ③ @param [in]   x1  输入Tensor,数据类型支持FLOAT,FLOAT16,BFLOAT16,INT32。数据格式支持ND。 @param [in]   x2
[RUN] ① out=fp32[2x4] vs x1=fp32[2x3] → rc1=161002 rc2=None
[RUN] ② 单块 x1=x2=out=fp32[0] → rc1=0 rc2=0
[RUN] ② 两块列表(第二块为空) → rc1=0 rc2=0
[DEFECT] ③ 头文件 aclnn_foreach_add_list_v2.h 的 x1 注释漏列 INT16/INT8/UINT8(资料 dtype 列有、实测可用)
[DEFECT] ① 资料声明 out 可以「shape size 大于等于 x1」,实测 out 比 x1 大返回 161002(实现要求严格相等)
[DEFECT] ② 资料声明 x1/x2/out「不支持空Tensor」,实测两种空 tensor 形态两段均返回 0
[SUMMARY] 共 3 项资料与实现/事实不符

运行方式:

python3 aclnnForeachAddListV2_21-01.py --repo-root <仓根>

Existing Issues(存在的问题)

修复建议:① out 行改为「shape 与入参 x1 完全一致(shape size 必须相等)」;② 三处「不支持空Tensor」改为「支持空Tensor(元素数 0 时直接返回,不做计算)」,或在 CheckParams 补空 tensor 拦截并返回 161002;③ 头文件四个 @param 注释的 dtype 补成 FLOAT、FLOAT16、BFLOAT16、INT32、INT16、INT8、UINT8。

证据与环境:

  • 仓库与版本:cann/ops-nn 711a4f5d
likedislike
east_yang
east_yangCollaborators
20 days ago Comments:

/assign @Tian_1122

likedislike
CANN-robotCANN-robotCollaborators
20 days ago Assign Tian_1122 as responsible person
yuning_chen
yuning_chenCollaborators
19 days ago Comments:

初步分析

感谢反馈,我们已开始核对这个问题。

现象理解:缺陷反馈;aclnnForeachAddListV2 资料三处与实现/事实不符(out shape 约束、空 Tensor 支持面、头文件 dtype 注释)。
当前判断:从描述看这是缺陷反馈「aclnnForeachAddListV2 资料三处与实现/事实不符(out shape 约束、空 Tensor 支持面、头文件 dtype 注释)」。正文里出现报错信息(如 raise RuntimeError("找不到 CANN 安装目录(设 ASCEND_HOME_PATH)")),更像实现或使用问题。以上为初步判断,待复现确认,不能当成已确认根因。
涉及范围:aclnnForeachAddListV2、aclnnForeachAddListV2GetWorkspaceSize、foreach_add_list、aclnn_foreach_add_list_v2、acl_base_rt、create_string_buffer
下一步:我们会继续对照代码/文档定位。

正文中的报错摘录:

  • raise RuntimeError("找不到 CANN 安装目录(设 ASCEND_HOME_PATH)")
  • except OSError:
  • raise RuntimeError("缺 libascendcl.so 或 libopapi.so(home=%s)" % home)
likedislike
yuning_chen
yuning_chenCollaborators
19 days ago Comments:

您好,该问题已收到,当前问题 @Tian_1122 正在处理中

likedislike
Tian_1122Tian_1122Collaborators
18 days ago Associated pull request
CANN-robotCANN-robotCollaborators
17 days ago Close issue
CANN-robotCANN-robotCollaborators
17 days ago Added label: resolved