CANN ops-math aclnnAcosh 算子深度解析:两段式接口、参数约束与 NPU 内核实现
CANN ops-math aclnnAcosh 算子深度解析:两段式接口、参数约束与 NPU 内核实现
本指南以 CANN ops-math 仓库中 acosh 算子 API 文档 为主体,结合 aclnn_acosh.cpp、acosh_tiling.cpp 与 KernelAcosh 内核 等源码实现,系统讲解 aclnnAcosh 的数学语义、两段式调用流程、参数与约束、错误码语义以及从 L2 接口到 AI Core 内核的完整执行链路。读完本文,你将能够独立编写、编译并运行调用 aclnnAcosh 的 NPU 程序,并理解该算子在宿主侧校验、Tiling 切分与 Kernel 计算各阶段的行为。
产品支持情况
aclnnAcosh 接口在 CANN ops-math 中的产品支持情况如下表(以 aclnnAcosh.md 为准):
| 产品 | 是否支持 |
|---|---|
| Ascend 950PR/Ascend 950DT | × |
| Atlas A3 训练系列产品/Atlas A3 推理系列产品 | × |
| Atlas A2 训练系列产品/Atlas A2 推理系列产品 | × |
| Atlas 200I/500 A2 推理产品 | × |
| Atlas 推理系列产品 | × |
| Atlas 训练系列产品 | × |
需要注意的是,文档表格与仓库源码存在一处细节差异:acosh_def.cpp 中明确注册了 ascend950 的 AICore 配置,aclnn_acosh.cpp 的 IsDtypeSupported 也仅在 NpuArch::DAV_3510(即 Ascend 950 系列)上放行 FLOAT16/FLOAT/BF16 三种类型,且 README 将 Ascend 950PR/Ascend 950DT 标为支持。从源码结构看,该算子的 AI Core 实现面向 Ascend 950 系列(arch35)开发,其余产品形态走的是"不支持"路径;实际部署时请以运行环境对应版本的官方支持矩阵为准。
功能说明与数学语义
aclnnAcosh 的接口功能是:对输入张量 self 逐元素计算反双曲余弦值(inverse hyperbolic cosine),结果写入输出张量 out。计算公式为:
其中 self_i 表示输入张量第 i 个元素,out_i 表示对应的输出元素。
两个与精度/值域相关的关键语义:
- NaN 语义:当
self_i < 1时,数学上无实数解,计算结果为 NaN。接口层不做拦截,与 PyTorchtorch.acosh语义保持一致,由调用方保证输入值域合法。 - 逐元素、无广播:aclnnAcosh 是逐元素(elementwise)算子,不涉及广播机制,输入输出 shape 必须完全一致。
Kernel 侧对 fp16/bf16 大值还有一个额外的精度保护细节:acosh.h 注释指出,AscendC 的 Acosh 原语对 fp16 大值(如 65504)会因中间步骤 x^2 溢出而返回 0,bf16 原语不支持,因此 fp16/bf16 走 Cast 回退路径(详见后文内核实现)。
两段式接口与函数原型
aclnnAcosh 采用 CANN aclnn 标准的两段式接口设计(两段式接口的通用约定可参考 two_phase_api.md):
- 必须先调用
aclnnAcoshGetWorkspaceSize获取计算所需 workspace 大小以及包含了算子计算流程的执行器(executor); - 再调用
aclnnAcosh执行实际计算。
第一段接口原型:
aclnnStatus aclnnAcoshGetWorkspaceSize(
const aclTensor *self,
aclTensor *out,
uint64_t *workspaceSize,
aclOpExecutor **executor)
第二段接口原型:
aclnnStatus aclnnAcosh(
void *workspace,
uint64_t workspaceSize,
aclOpExecutor *executor,
aclrtStream stream)
从 aclnn_acosh.h 的声明可见,两段接口均以 ACLNN_API 导出(默认可见性),头文件仅依赖 aclnn/aclnn_base.h。
aclnnAcoshGetWorkspaceSize 参数说明
第一段接口的参数说明如下:
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| self(aclTensor*) | 输入 | 输入张量,对应公式中 self,表示待计算反双曲余弦值的数据。 | 支持空 Tensor(元素数为 0);数据类型需与 out 保持一致;shape 需与 out 完全一致;输入值域建议为 [1, +∞),小于 1 的值会产生 NaN,框架层不做拦截。 | FLOAT16、FLOAT、BFLOAT16 | ND | 0-8 | √ |
| out(aclTensor*) | 输出 | 输出张量,对应公式中 out,用于存放反双曲余弦计算结果。 | 不支持空 Tensor(self 为空 Tensor 时除外);数据类型需与 self 一致;shape 需与 self 完全一致。 | FLOAT16、FLOAT、BFLOAT16 | ND | 0-8 | √ |
| workspaceSize(uint64_t*) | 输出 | 返回需要在 Device 侧申请的 workspace 大小。 | - | - | - | - | - |
| executor(aclOpExecutor**) | 输出 | 返回 op 执行器,包含了算子计算流程。 | - | - | - | - | - |
参数要点补充(结合源码确认):
- 空 Tensor 支持:aclnn_acosh.cpp 中在
CheckParams之后会先判断self->IsEmpty(),若为空则直接令workspaceSize = 0并快速返回,不再构建执行链。 - 非连续 Tensor 支持:L2 接口内部通过
l0op::Contiguous将非连续输入转为连续存储(见下方源码链路),非连续 Tensor 的通用约定可参考 non_contiguous_tensor.md。 - 数据格式:仅支持 ND,私有格式会被 CheckFormat 直接拒绝,ND 格式的定义参见 data_format.md。
返回值与错误码
两段接口的返回值类型均为 aclnnStatus,返回码的完整说明参见 aclnn_return_code.md。
第一段接口会完成入参校验,出现以下场景时报错:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | self 或 out 存在空指针。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 或 out 的数据类型不在支持的范围之内(仅支持 FLOAT16、FLOAT、BFLOAT16)。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 与 out 的数据类型不一致。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 或 out 的 shape 维度不在支持的范围之内(仅支持 0-8 维),或 self 与 out 的 shape 不一致。 |
对照 aclnn_acosh.cpp 的 CheckParams 实现,校验顺序为:空指针检查(CheckNotNull)→ 数据类型一致性及平台支持检查(CheckDtypeValid,其中 ACLNN_MAX_SHAPE_RANK = 8 同时约束维度上限)→ 格式检查(CheckFormat)→ 维度上限检查(CheckShape)。这与上表错误码的优先级完全对应。
aclnnAcosh 参数说明
第二段接口的参数说明如下:
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnAcoshGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
第二段接口不再做入参校验,直接通过 CommonOpExecutorRun 提交执行(见 aclnn_acosh.cpp)。
约束说明
使用 aclnnAcosh 时需注意以下约束:
- 确定性:aclnnAcosh 默认确定性实现,多次运行结果一致。
- 数据类型:Atlas A2 训练/推理系列产品仅支持 FLOAT16、FLOAT、BFLOAT16 数据类型,不支持其他数据类型;从源码看,AI Core 路径(Ascend 950)同样仅放行这三种类型。
- 输入值域:acosh 数学定义域为 [1, +∞),输入元素小于 1 时结果为 NaN,接口层不做拦截,由调用方保证输入合法性。
- 无广播:逐元素算子,不涉及广播,输入输出 shape 须完全一致。
调用示例
以下代码来自 test_aclnn_acosh.cpp 的核心调用流程(该示例以 float32 为例,计算 acosh(<a href="https://link.gitcode.com/i/db531d298b2d85f4c70d790be26e4ba6" target="_blank">1.0, 2.0, 5.0, 10.0])),完整编译和执行过程参考 [compile_and_run_sample.md:
#include "acl/acl.h"
#include "aclnn_acosh.h"
// 1. ACL 初始化
aclInit(nullptr);
aclrtSetDevice(0);
aclrtStream stream = nullptr;
aclrtCreateStream(&stream);
// 2. 准备输入数据(以 float32 为例,计算 acosh([1.0, 2.0, 5.0, 10.0]))
std::vector<float> inputData = {1.0f, 2.0f, 5.0f, 10.0f};
std::vector<int64_t> shape = {4};
size_t dataSize = inputData.size() * sizeof(float);
// 3. 分配 NPU 内存并拷贝输入数据
void* inputDev = nullptr;
void* outputDev = nullptr;
aclrtMalloc(&inputDev, dataSize, ACL_MEM_MALLOC_HUGE_FIRST);
aclrtMalloc(&outputDev, dataSize, ACL_MEM_MALLOC_HUGE_FIRST);
aclrtMemcpy(inputDev, dataSize, inputData.data(), dataSize, ACL_MEMCPY_HOST_TO_DEVICE);
// 4. 创建 aclTensor(连续 ND 格式)
std::vector<int64_t> strides = {1}; // shape={4} 时 stride={1}
aclTensor* selfTensor = aclCreateTensor(shape.data(), shape.size(), ACL_FLOAT,
strides.data(), 0, ACL_FORMAT_ND, shape.data(), shape.size(), inputDev);
aclTensor* outTensor = aclCreateTensor(shape.data(), shape.size(), ACL_FLOAT,
strides.data(), 0, ACL_FORMAT_ND, shape.data(), shape.size(), outputDev);
// 5. 第一段接口:获取 workspace 大小和 executor
uint64_t workspaceSize = 0;
aclOpExecutor* executor = nullptr;
aclnnAcoshGetWorkspaceSize(selfTensor, outTensor, &workspaceSize, &executor);
// 6. 分配 workspace(大小为 0 时跳过)
void* workspace = nullptr;
if (workspaceSize > 0) {
aclrtMalloc(&workspace, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST);
}
// 7. 第二段接口:执行算子
aclnnAcosh(workspace, workspaceSize, executor, stream);
aclrtSynchronizeStream(stream);
// 8. 拷回结果
std::vector<float> output(inputData.size());
aclrtMemcpy(output.data(), dataSize, outputDev, dataSize, ACL_MEMCPY_DEVICE_TO_HOST);
// output = [0.0, 1.3169578, 2.2924316, 2.9932227]
// 9. 清理资源
if (workspace) aclrtFree(workspace);
aclDestroyTensor(selfTensor);
aclDestroyTensor(outTensor);
aclrtFree(inputDev);
aclrtFree(outputDev);
aclrtDestroyStream(stream);
aclrtResetDevice(0);
aclFinalize();
该示例的预期输出可以通过数学关系验证:acosh(1)=0,acosh(2)=ln(2+√3)≈1.31696,acosh(5)≈2.29243,acosh(10)≈2.99322,与注释中的结果一致。仓库中的完整示例还提供了更贴近生产的写法,包括:
CHECK_RET宏对每一步 ACL 调用返回值做检查;CreateAclTensor辅助函数根据 shape 自动计算连续 strides 并完成aclrtMalloc+aclrtMemcpy;- fp16 数据的
FloatToFp16/Fp16ToFloat转换工具; - 以
atol=1e-3, rtol=1e-3为阈值的逐元素精度验证逻辑(std::acosh为标准对照),并统计 NaN 个数后返回进程退出码。
仓库示例默认使用 fp16、shape 为 [8, 8](64 个元素,小于 1024),因此触发的是 TilingKey_A(fp16 单缓冲)路径,输入值域取 [1.0, 10.0) 保证 acosh 有效。
源码级实现原理
L2 接口的完整调用链
aclnn_acosh.cpp 中第一段接口的流程为:
CREATE_EXECUTOR -> CheckParams -> HasEmptyTensor -> Contiguous
-> l0op::Acosh -> ViewCopy -> GetWorkspaceSize
具体步骤:
CREATE_EXECUTOR()创建执行器;CheckParams完成空指针、dtype、格式、维度校验;- 空 Tensor 快速返回(workspaceSize 置 0);
l0op::Contiguous(self)将非连续输入规整为连续存储;l0op::Acosh(selfContiguous)进入 L0 层,完成形状推导并分配输出;l0op::ViewCopy将中间结果写回调用方传入的 out;GetWorkspaceSize汇总返回所需 workspace 大小。
L0 层实现位于 op_api/acosh.cpp:AcoshInferShape 直接令输出 shape 等于输入 shape;IsAiCoreSupport 在 DAV_2201/DAV_3510 上校验 dtype;Acosh 入口通过 executor->AllocTensor 按输入 dtype 分配输出,再经 ADD_TO_LAUNCHER_LIST_AICORE 将算子挂入 AI Core 启动器列表。
第二段接口则简洁地调用 CommonOpExecutorRun(workspace, workspaceSize, executor, stream) 完成最终执行。
算子定义与形状推导
- acosh_def.cpp:声明算子输入
x、输出y(均REQUIRED),数据类型为 DT_FLOAT16/DT_FLOAT/DT_BF16,格式为 FORMAT_ND,并开启AutoContiguous;AICore 配置中DynamicRankSupportFlag(true)支持动态 rank、DynamicShapeSupportFlag(true)支持动态 shape、PrecisionReduceFlag(true)允许精度降低优化。 - acosh_infershape.cpp:
InferShape4Acosh将输出 shape 直接拷贝为输入 shape,从宿主侧再次印证"逐元素、shape 完全一致"的约束。
Tiling 切分策略
acosh_tiling.cpp 实现了 arch35(Ascend 950)上的 Tiling:
- 多核切分:按元素总数均分到各 AI Core,
blockFactor = CeilDiv(totalNum, coreNum),实际使用的核数为CeilDiv(totalNum, blockFactor)(L142-L145); - UB 切分:按可用 UB 大小与缓冲区数量均分,
ubFactor通过FloorAlign(FloorDiv(ubSize/typeSize, bufferNum), GetUbBlockSize())计算; - 缓冲模式选择:总元素数大于 1024(
MIN_SPLIT_THRESHOLD)时启用双缓冲(L149); - TilingData:结构体见 acosh_tiling_data.h,包含
totalNum、blockFactor、ubFactor三个字段; - TilingKey:dtype × buffer_mode 共 6 个组合(A~F),定义见 acosh_tiling_key.h:A= fp16 单缓冲、B=fp16 双缓冲、C=fp32 单缓冲、D=fp32 双缓冲、E=bf16 单缓冲、F=bf16 双缓冲。
Kernel 计算与 fp16/bf16 精度回退
Kernel 入口 acosh_apt.cpp 按模板参数 D_T_X(half/float/bfloat16_t)与 BUFFER_MODE(0/1)实例化 NsAcosh::KernelAcosh,调用 Init 与 Process。核心实现位于 acosh.h:
- fp32 路径:直接调用
AscendC::Acosh(yLocal, xLocal, currentNum),无溢出问题; - fp16/bf16 回退路径:由于 fp16 大值(65504)直接计算会因
x^2中间步骤溢出返回 0、bf16 原语不支持,因此走Cast(fp16/bf16->fp32, CAST_NONE) -> Acosh(fp32) -> Cast(fp32->fp16/bf16)的三段链路;fp32→fp16 使用CAST_ROUND,fp32→bf16 使用CAST_RINT,中转缓冲tmpBuf_位于VECCALC位置(L118-L132); - 流水结构:
Process按ubFactor分块循环,每轮执行CopyIn(DataCopyPad从 GM 搬运到 VECIN 队列)→Compute(队列 DeQue/Alloc + 计算 + EnQue)→CopyOut(写回 GM),缓冲数为BUFFER_MODE ? 2 : 1; - 尾部核处理:
Init中通过blockFactor * blockIdx计算当前核的起始偏移,尾部核元素数可能少于blockFactor,blockLength_ <= 0时直接跳过(L78-L84)。
由此可以完整还原 aclnnAcosh 的执行链路:调用方两段式接口 → L2 层校验与执行器构建 → L0 层形状推导与输出分配 → Tiling 阶段的多核/UB 切分 → arch35 AI Core 上的逐元素 acosh 计算(含 fp16/bf16 的 fp32 中转精度回退)。
总结
aclnnAcosh 是 CANN ops-math 中面向 Ascend 950 系列(arch35)实现的逐元素反双曲余弦算子,遵循 aclnn 标准两段式接口(GetWorkspaceSize + 执行),仅支持 FLOAT16/FLOAT/BFLOAT16、ND 格式、0-8 维、输入输出 shape 与 dtype 严格一致,且默认确定性实现。其数值语义与 PyTorch torch.acosh 一致(输入小于 1 产生 NaN,框架不拦截),工程上通过 Cast 回退路径规避了 fp16/bf16 在 x² 中间步骤的溢出问题。开发者可直接复用 examples/test_aclnn_acosh.cpp 作为上手模板,并结合 two_phase_api.md 与 compile_and_run_sample.md 理解更通用的 aclnn 算子调用范式。