企业官网建设流程全解析

CANN Runtime 断点分析：用 API 资料支撑情况表评估 aclnn 预置算子调用链路的文档覆盖度

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本篇指南介绍 CANN Runtime 开源仓库中断点分析流程的核心工具——API 资料支撑情况表（api-coverage-table）。该表用于在编写 aclnn 预置算子调用代码时，逐 API 核对文档覆盖情况与代码可写性，帮助开发者判断"某个算子能否仅凭仓库资料写出正确调用"。读完本文，你将掌握该表格的结构、各列填写标准、衔接区域（aclnn 算子库与 Runtime 交界）的评估方法，并能结合本仓库的 docs/zh/api_ref 与 example/0_quickstart/0_hello_cann 完成一次完整的覆盖度评估。

一、背景：为什么要逐 API 评估资料支撑情况

在 CANN Runtime 中，使用预置算子（aclnn 系列 API）完成一次计算任务，需要串联起两类性质完全不同的 API：

• Runtime 基础 API：aclInit、aclrtSetDevice、aclrtCreateStream、aclrtMalloc、aclrtMemcpy、aclrtSynchronizeStream、aclrtFree等，由 Runtime 仓库负责维护；
• aclnn 衔接区域 API：aclCreateTensor/aclDestroyTensor、aclCreateScalar/aclDestroyScalar、$0GetWorkspaceSize、$0（算子执行接口）等，由 opbase 与算子库组件维护，属于外源知识。

前者文档不足属于Runtime 缺陷（计入整改项），后者文档不足属于外源知识缺失（记录但不计入 Runtime 整改）。这种责任归属必须逐 API 判定、不留灰色地带——这正是 SKILL.md 中断点分析流程的核心纪律。

API 资料支撑情况表正是这一纪律的可执行载体：它在Step 5（编写 Runtime 调用框架代码）阶段被使用，将"整个流程能不能走通"的宏观问题，拆解为"每个 API 有没有文档、文档全不全、有没有示例、能不能写出调用"的微观核对。其模板定义于 references/api-coverage-table.md。

二、表格结构：逐 API 记录五维信息

该表以"API / 操作"为行、五个评估维度为列，完整模板如下：

其中$0代表当前正在分析的目标算子，例如aclnnAdd、aclnnMatmul、aclnnSin。表中把调用链切成"初始化 → Device/Stream → 内存与拷贝 → Tensor/Scalar 描述 → 两段式调用 → 同步回传 → 释放"几个段落，确保任何一个环节的文档缺口都不会被遗漏。

三、五列填写规范详解

3.1 文档位置

• 记录具体文件路径，如docs/zh/api_ref/11-01_device_memory_malloc_and_free.md#aclrtMalloc；
• 可附带锚点定位到具体 API 小节；
• 如无文档，填无。

在本仓库中，Runtime 基础 API 的文档集中在 docs/zh/api_ref 分类目录下，例如aclInit对应 02_initialization_and_deinitialization.md、aclrtSetDevice对应 04_device_management.md、aclrtCreateStream对应 06_stream_management.md、aclrtMalloc/aclrtFree对应 11-01_device_memory_malloc_and_free.md、aclrtMemcpy对应 11-03_memory_copy_and_set.md。评估时需核对锚点是否真实存在、小节是否覆盖该 API 的全部用法。

3.2 参数说明完整度

• 完整：所有参数的类型、含义、取值范围均有说明；
• 缺参数：部分参数有说明，但关键参数缺失；
• 无说明：仅有函数签名，无参数说明。

这是衡量"能不能不靠猜测就写出正确调用"的关键指标。以aclrtMalloc为例，除了函数签名，还需要说明第三个参数（内存分配策略，如ACL_MEM_MALLOC_HUGE_FIRST）的可选值与语义，才可判为"完整"。

3.3 示例代码位置

• 记录具体文件路径和行号，如example/0_quickstart/0_hello_cann/main.cpp中的对应调用行；
• 如无示例，填无。

本仓库的 example/0_quickstart/0_hello_cann/main.cpp 是一个以aclnnAdd为载体、覆盖完整调用闭环的最小示例：aclInit→aclrtSetDevice→aclrtCreateStream→ 创建 Tensor/Scalar →aclnnAddGetWorkspaceSize→ 分配 workspace →aclnnAdd→aclrtSynchronizeStream→aclrtMemcpy回传 → 资源释放。其中 Tensor 创建封装在CreateAclTensor模板（约第 38-67 行），两段式调用见第 160-177 行，资源释放见第 197-229 行。评估其他算子时，若仓库中没有该算子的专门示例，则以此 quickstart 为通用参照模板。

3.4 资料来源

• Runtime docs：来自 Runtime 仓库 docs/；
• Runtime example：来自 Runtime 仓库 example/（含 quickstart 及其他示例）；
• 推测：基于经验推测，必须明确标注、不得当作确定信息使用。

这一列直接决定断点的责任归属：标Runtime docs/Runtime example的属于 Runtime 仓内知识，缺失即记录为 Runtime 缺陷；aclCreateTensor、aclCreateScalar、aclnn 算子签名、aclnnStatus错误码等属于非 Runtime 仓知识，应从外源知识仓库（ops-nn、ops-transformer、ops-math）获取，缺失时记录为外源知识缺失。规则详见 references/source-rules.md。

3.5 能否写出调用

• 是：有充分文档支撑，可写出正确调用；
• 否：资料完全缺失，无法写出；
• 靠猜测：资料不完整，靠推测或从示例反推勉强写出；
• 衔接重点：标记为 aclnn 算子库与 Runtime 衔接区域的关键 API；
• 不适用：$0 不需要此 API（如不需要 Scalar 参数的算子）。

注意"衔接重点"与"是/否/靠猜测"是并列的判定位：被标记为衔接重点的 API（Tensor/Scalar 创建与销毁、$0GetWorkspaceSize、$0）即使能写出调用，也必须单独标注，因为其资料来源依赖外源知识，属于整条链路上最容易出现断点的区域。

四、逐 API 评估的实战要点

4.1 Runtime 基础 API：重点核对参数完整度

aclInit、aclrtSetDevice、aclrtCreateStream、aclrtMalloc、aclrtMemcpy（H2D/D2H 两个方向）、aclrtSynchronizeStream与资源释放步骤均属于 Runtime 仓职责。评估时重点核对：

• aclInit的入参（nullptr表示使用默认配置）是否有说明；
• aclrtMemcpy的kind参数枚举（ACL_MEMCPY_HOST_TO_DEVICE/ACL_MEMCPY_DEVICE_TO_HOST）是否完整；
• 释放顺序（aclrtFree→aclrtDestroyStream→aclrtResetDeviceForce→aclFinalize）是否有文档依据。

4.2 衔接区域 API：标注"衔接重点"并区分知识归属

衔接区域是断点高发区，共五类：

1. aclCreateTensor— 需要知道 shape、strides、format、dataType、offset 的传递方式。本仓库 example/0_quickstart/0_hello_cann/main.cpp 展示了实际调用：strides 按"从后往前累乘"方式计算（strides[i] = shape[i+1] * strides[i+1]），format 使用ACL_FORMAT_ND，offset 传0；
2. aclCreateScalar— 如算子需要标量参数（如aclnnAdd的alpha），需说明标量值指针与数据类型；若算子不需要 Scalar，直接标注"不适用"；
3. $0GetWorkspaceSize— 两段式调用的第一段，内部执行入参校验、输出 Shape 推导、Tiling 与 workspace 大小计算，输出workspaceSize与executor；
4. $0— 第二段执行接口，接收workspace、workspaceSize、executor、stream四个参数；
5. aclDestroyTensor / aclDestroyScalar— 资源释放。

两段式调用范式的概念说明（workspace 的分配/释放时机、executor 的生命周期与不可复用性）属于 aclnn 知识，详见 Skill 内置文档 references/aclnn-two-phase-calling.md，以及 example/0_quickstart/0_hello_cann/README.md 中对aclnnAddGetWorkspaceSize与aclnnAdd的函数签名示例。

4.3 结果验证与资源释放

"结果验证"关注预期输出的可判定性：quickstart 示例采用 Host 侧按数学公式手算 expected 值、与 Device 输出逐元素打印对比的方式（见 example/0_quickstart/0_hello_cann/main.cpp）。"资源释放"则核对 Tensor、Scalar、DataBuffer、Device 内存、Stream、Device 的完整释放链（同一文件第 197-229 行）。

五、从表格到整改：完成度统计与断点闭环

填完表格后，评估并未结束。表格结果将驱动后续三个环节：

1. 代码完成度统计：按 references/completion-stats-template.md 将步骤分为"Runtime 基础 API 步骤"与"aclnn 衔接区域步骤"，统计"可完成 / 靠猜测勉强完成 / 无法完成"的步数并计算完成率。注意"靠猜测"不计入可完成，且若算子不需要 Scalar，对应步骤标注"不适用"并从总步骤数中扣除。

2. 断点格式化记录：每个"文档缺失/不足"的单元格都要按 references/blockpoint-format.md 的标准格式展开记录，字段包括：问题类型（Runtime 缺陷 / 外源知识缺失 / 体验问题）、发生步骤、查找过程（必须列出实际查过的文件路径）、影响程度（阻塞 / 半阻塞 / 不阻塞）等。

3. 整改 TodoList 生成：阻塞点映射为 P0、优化点映射为 P1，每条任务附带问题描述、目标状态与行动步骤。核心判断原则是：该 API 是否由 Runtime 仓库维护？是 → Runtime 缺陷（入整改项）；否 → 外源知识缺失（记录但不计入整改项），不存在中间状态。

六、以 aclnnAdd 为例的表格填写示范

假设$0 = aclnnAdd，基于本仓库现状，一行典型记录如下：

可以看到，Runtime 基础 API 由于 docs/ 与 example/ 双重支撑，通常可判"是"；而衔接区域 API 即便能从示例反推出用法，也必须保留"衔接重点"标记，并在断点记录中注明其外源知识归属，避免将 aclnn/opbase 的文档缺口误算为 Runtime 缺陷。

七、总结与使用建议

API 资料支撑情况表是一张"体检单"：它以单个 API 为最小单元，将"能否走通 aclnn 预置算子调用全流程"拆解为可量化、可追责的评估项。使用时请遵循以下要点：

• 完整继承模板行：从aclInit到"资源释放"的十五行评估项是标准调用链的最小覆盖集，不要随意删减；
• 严格区分知识归属：Runtime 基础 API 只看 docs/zh/api_ref 与 example，衔接区域 API 优先从外源知识仓库获取，两者缺失分别按 Runtime 缺陷与外源知识缺失处理；
• 先填表、后定级：先客观记录"文档位置 / 完整度 / 示例 / 来源"四个事实列，再据实判定"能否写出调用"，避免先入为主；
• 以表格驱动整改：表格中每一条"靠猜测"或"衔接重点"记录，都应能追溯到一个结构化的断点记录和一条可执行的整改任务，形成"评估 → 记录 → 整改"的完整闭环。

掌握这张表，你就能以可复现的方式评估任意 aclnn 算子在 CANN Runtime 中的文档支撑度，并准确区分"Runtime 该补的文档"与"算子库该补的文档"，让断点分析既不冤枉 Runtime 仓库，也不放过真实的文档缺口。

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime