企业官网建设流程全解析

CANN ops-math 算子接口实战：aclnnLinalgCross 向量叉乘（Cross）算子详解

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math

本篇文章以 CANN ops-math 开源仓库中 Cross 算子的 aclnnLinalgCross 接口文档 为核心，系统讲解该算子支持的硬件平台、数学定义、两段式调用接口（aclnnLinalgCrossGetWorkspaceSize与aclnnLinalgCross）、全部入参/出参约束、错误码语义，并结合仓库内 op_api、op_host、op_kernel 的源码实现与 UT 测试用例，剖析接口背后的校验逻辑、广播处理、BF16 升精度策略与昇腾 AI Core 上的算子内核计算流程。读完本文，你将能够独立编写一个可编译、可运行的 aclnnLinalgCross 调用程序，并理解从 API 入参校验到 NPU 内核执行的完整链路。

一、算子功能与数学原理

aclnnLinalgCross是 CANN 提供的一个数学类基础算子接口，功能是对输入 Tensorself与other完成linear_cross（线性叉乘）运算，即逐组地对dim指定维度上长度为 3 的向量求三维向量叉积，对应 PyTorch 语义中的torch.linalg.cross。

设self = (x1, y1, z1)、other = (x2, y2, z2)，叉乘结果按三阶行列式展开为：

$$ out = self\times other = \begin{vmatrix}i&j&k\x_1&y_1&z_1\x_2&y_2&z_2\end{vmatrix} = (y_1z_2-y_2z_1)i-(x_1z_2-x_2z_1)j+(x_1y_2-x_2y_1)k $$

即输出三个分量为：

• out[0] = x1 * y2 - x2 * y1
• out[1] = x2 * y0 - x0 * y2（对应y1z2 - y2z1的通用分量式）
• out[2] = x0 * y1 - x1 * y0

这一计算公式在仓库内核实现中可得到直接印证，见 op_kernel/cross.h 的Compute()逻辑，三路输出分别用AscendC::Mul与AscendC::Sub组合实现。

二、产品支持情况

从算子定义源码看，op_host/cross_def.cpp 中通过this->AICore().AddConfig("ascend910b")声明该算子适配的 AI Core 架构（Atlas A2 系列对应昇腾 910B 架构），输入x1、x2与输出y均要求 ND 格式。

三、两段式接口调用模型

每个 CANN 算子 API 都遵循两段式接口（详见 两段式接口说明）：

1. 先调用aclnnLinalgCrossGetWorkspaceSize获取计算所需 workspace 大小以及包含算子计算流程的执行器（executor）；
2. 再调用aclnnLinalgCross执行计算。

两个接口的函数原型如下：

aclnnStatus aclnnLinalgCrossGetWorkspaceSize( const aclTensor* self, const aclTensor* other, int64_t dim, aclTensor* out, uint64_t* workspaceSize, aclOpExecutor** executor)

aclnnStatus aclnnLinalgCross( void* workspace, uint64_t workspaceSize, aclOpExecutor* executor, aclrtStream stream)

头文件声明位于 op_api/aclnn_linalg_cross.h，接口域为aclnn_math。

四、aclnnLinalgCrossGetWorkspaceSize 参数详解

4.1 参数说明

4.2 返回值

第一段接口返回aclnnStatus状态码，具体参见 aclnn 返回码说明。第一段接口会完成入参校验，出现如下场景时报错：

4.3 源码级校验链路

上述校验在 op_api/aclnn_linalg_cross.cpp 的CheckParams中按序完成，是理解各错误码触发条件的第一手依据：

1. 空指针校验（CheckNotNull）：对self、other、out逐一执行OP_CHECK_NULL，任一为空即返回ACLNN_ERR_PARAM_NULLPTR（161001）。
2. 数据类型校验（CheckDtypeValid）：源码中维护了两张支持列表：
   • DTYPE_SUPPORT_LIST：FLOAT、FLOAT16、DOUBLE、INT8、INT16、INT32、INT64、COMPLEX64、COMPLEX128、UINT8；
   • DTYPE_SUPPORT_LIST_910B：在上一列表基础上额外包含 BF16；
   • 当当前 NPU 架构为DAV_2201或DAV_3510时使用含 BF16 的列表，否则使用基础列表。同时通过OP_CHECK_DTYPE_NOT_MATCH强制self、other、out三者数据类型一致。
3. 维度校验（CheckShape）：三个 Tensor 的维度都必须小于MAX_SUPPORT_DIMS_NUMS（即 0-8 维）。
4. 广播与输出 shape 校验（CheckBroadcastShape）：先OP_CHECK_BROADCAST确认self/other满足广播关系，再调用BroadcastInferShape推导广播后的 shape，要求其与out的 shape 完全一致。
5. dim 范围校验（CheckDim）：dim必须落在[-dimSize, dimSize-1]（dimSize 为 self 的维度数），默认值 -1。

关于 broadcast 的具体规则（左对齐补 1、单维为 1 时拉伸、无可广播维时报错等），参见 broadcast 关系。

五、aclnnLinalgCross 参数详解

5.1 参数说明

5.2 返回值

返回aclnnStatus状态码，具体参见 aclnn 返回码说明。

从源码看，第二段接口内部通过CommonOpExecutorRun(workspace, workspaceSize, executor, stream)调用框架能力完成实际计算（见 op_api/aclnn_linalg_cross.cpp 第 233-238 行），用户无需关心 executor 内部细节。

六、约束说明

• 确定性计算：aclnnLinalgCross默认采用确定性实现，即相同输入多次执行结果一致，不会引入随机性偏差。
• 维度约束：指定进行叉乘的维度（dim轴）在广播后的 size 必须为 3。
• 广播约束：输入self、other的 shape 必须满足 broadcast 关系，运算前较小的张量会被广播拉伸到与较大张量一致。
• 类型约束：self、other、out的数据类型必须保持一致；Atlas A2 系列上支持 INT8、INT16、INT32、INT64、UINT8、FLOAT16、BFLOAT16、FLOAT、FLOAT64、COMPLEX64、COMPLEX128。

仓库 README.md 亦明确：指定维度的 size 必须为 3；输入 shape 需满足 broadcast 关系；输入数据类型需保持一致。

七、接口内部实现原理（源码纵深）

7.1 从 API 到算子内核的调用链

aclnnLinalgCrossGetWorkspaceSize的实现（op_api/aclnn_linalg_cross.cpp 的ExecLinalgCrossGetWorkspaceSize）完成了以下关键步骤：

1. 空 Tensor 短路处理：if (out->IsEmpty())时直接返回 workspace 大小与 executor，不进入内核计算（对照 UT 中多个case_empty_tensor用例，如{1, 0, 3}形状的输入可正常通过校验）。
2. 连续化：对非连续的self、other分别调用l0op::Contiguous转换为连续 Tensor（因此接口支持非连续 Tensor 输入）。
3. 广播展开：当两者 shape 不同时，通过BroadcastTensor调用l0op::BroadcastTo将两个输入统一广播到out的 shape；若dim >= 0且self维度少于other，还会把dim加上扩维数量以保持索引正确；若dim为负数，则加上广播后 Tensor 的维度数转为正索引。
4. 叉乘维度检查：校验广播后dimInner维上的 shape 为 3，否则返回ACLNN_ERR_PARAM_INVALID。
5. BF16 升精度：在非DAV_2201/DAV_3510架构上，BF16 输入会被l0op::Cast为 FLOAT 计算，计算结果再 Cast 回 BF16，保证精度。
6. 内核调用与结果回写：调用l0op::Cross(selfBroadCast, otherBroadCast, dimInner, executor)生成计算图，最后用l0op::ViewCopy将结果拷贝到可能非连续的out上，并汇总得到workspaceSize。

7.2 shape 推导（InferShape）

op_host/cross_infershape.cpp 中的InferShapeCross将输出 shape 直接填充为输入x（即 self）的 shape。由于广播已在 API 层完成，进入算子框架时输入已具备一致 shape。

7.3 Tiling 切分策略

op_host/cross_tiling.cpp 实现了编译期切分逻辑：

• 通过GetPlatformInfo获取 UB 大小与 AIV 核数（GetCoreNumAiv）；
• 依据输入 shape 与dim属性计算totalIdx（总元素数）、intervalNum与loopTimes：叉乘轴 size 固定为 3（kCrossAxisSize = 3），intervalNum = totalIdx / dimProduct，loopTimes = totalIdx / intervalNum / 3；
• 按数据类型计算单次搬入 UB 的tileDataNum（区分 FP32/FP16/INT8 及 group 模式，对应UB_DATA_NUM_FP32 = 19、UB_DATA_NUM_FP16 = 30、UB_DATA_NUM_INT8 = 18、UB_DATA_NUM_GROUP_MODE = 6等缓冲数常量）；
• 根据totalTileCount与核数计算blockDim，实现多核并行切分；
• 按 dtype 设置 tiling key：FLOAT→0、INT32→1、INT8→2、FLOAT16→3、UINT8→4、INT16→5；
• workspace 固定申请 16MB（WS_SYS_SIZE）。

7.4 AI Core 内核计算（AscendC）

op_kernel/cross.h 中的Cross<T>模板类实现了昇腾 AI Core 上的向量流水：

• 使用TPipe与TQue队列组织CopyIn → Compute → CopyOut三级流水（Process()中交错执行 Compute 与下一次 CopyIn，隐藏访存延迟）；
• 非 group 模式下，输入按x0/x1/x2、y0/y1/y2拆分为六个队列，输出z0/z1/z2三个队列，分别对应叉乘结果的三个分量；
• 对 FLOAT/INT32/INT16 使用向量指令AscendC::Mul+AscendC::Sub计算；对 FLOAT16（half）先Cast到 FP32 计算再Cast回（CAST_ROUND），避免半精度溢出；对 INT8/UINT8 提升到 INT32 计算后写回；
• op_kernel/cross.cpp 中cross内核入口按 tiling key 模板分发到Cross<float>、Cross<half>、Cross<int8_t>等具体实例。

八、完整调用示例

以下示例代码完整演示了两段式接口的调用流程，可直接参照 编译与运行样例 编译执行。代码逻辑为：初始化 ACL 资源 → 构造 self（3x3，值为 0~8）与 other（3x3，值为三组 1/2/3）→ 调用aclnnLinalgCrossGetWorkspaceSize获取 workspace → 申请 Device 内存 → 调用aclnnLinalgCross执行 → 拷贝结果回 Host 并打印 → 释放资源。

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_linalg_cross.h" #define CHECK_RET(cond, return_expr) \ do { \ if (!(cond)) { \ return_expr; \ } \ } while (0) #define LOG_PRINT(message, ...) \ do { \ printf(message, ##__VA_ARGS__); \ } while (0) int64_t GetShapeSize(const std::vector<int64_t>& shape) { int64_t shapeSize = 1; for (auto i : shape) { shapeSize *= i; } return shapeSize; } int Init(int32_t deviceId, aclrtStream* stream) { // 固定写法，资源初始化 auto ret = aclInit(nullptr); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret); ret = aclrtSetDevice(deviceId); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); return ret); ret = aclrtCreateStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); return ret); return 0; } template <typename T> int CreateAclTensor( const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr, aclDataType dataType, aclTensor** tensor) { auto size = GetShapeSize(shape) * sizeof(T); // 调用aclrtMalloc申请device侧内存 auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret); // 调用aclrtMemcpy将host侧数据拷贝到device侧内存上 ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret); // 计算连续tensor的strides std::vector<int64_t> strides(shape.size(), 1); for (int64_t i = shape.size() - 2; i >= 0; i--) { strides[i] = shape[i + 1] * strides[i + 1]; } // 调用aclCreateTensor接口创建aclTensor *tensor = aclCreateTensor( shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND, shape.data(), shape.size(), *deviceAddr); return 0; } aclError InitAcl(int32_t deviceId, aclrtStream* stream) { auto ret = Init(deviceId, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret); return ACL_SUCCESS; } aclError CreateInputs( std::vector<int64_t>& selfShape, std::vector<int64_t>& otherShape, std::vector<int64_t>& outShape, void** selfDeviceAddr, void** otherDeviceAddr, void** outDeviceAddr, aclTensor** self, aclTensor** other, aclTensor** out) { std::vector<double> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8}; std::vector<double> otherHostData = {1, 1, 1, 2, 2, 2, 3, 3, 3}; std::vector<double> outHostData = {0, 0, 0, 0, 0, 0, 0, 0, 0}; // 创建 self aclTensor auto ret = CreateAclTensor(selfHostData, selfShape, selfDeviceAddr, aclDataType::ACL_DOUBLE, self); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建 other aclTensor ret = CreateAclTensor(otherHostData, otherShape, otherDeviceAddr, aclDataType::ACL_DOUBLE, other); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建 out aclTensor ret = CreateAclTensor(outHostData, outShape, outDeviceAddr, aclDataType::ACL_DOUBLE, out); CHECK_RET(ret == ACL_SUCCESS, return ret); return ACL_SUCCESS; } aclError ExecOpApi( aclTensor* self, aclTensor* other, aclTensor* out, int64_t dim, void** workspaceAddrOut, uint64_t& workspaceSize, void* outDeviceAddr, std::vector<int64_t>& outShape, aclrtStream stream) { aclOpExecutor* executor; // 调用 aclnnLinalgCross 第一段接口 auto ret = aclnnLinalgCrossGetWorkspaceSize(self, other, dim, out, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnLinalgCrossGetWorkspaceSize failed. ERROR: %d\n", ret); return ret); // 根据 workspaceSize 申请 device 内存 void* workspaceAddr = nullptr; if (workspaceSize > 0) { ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret); } *workspaceAddrOut = workspaceAddr; // 调用 aclnnLinalgCross 第二段接口 ret = aclnnLinalgCross(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnLinalgCross failed. ERROR: %d\n", ret); return ret); // 同步 ret = aclrtSynchronizeStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret); // 从 device 拷贝结果到 host auto size = GetShapeSize(outShape); std::vector<double> resultData(size, 0); ret = aclrtMemcpy( resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr, size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret); for (int64_t i = 0; i < size; i++) { LOG_PRINT("result[%ld] is: %lf\n", i, resultData[i]); } return ACL_SUCCESS; } int main() { // 1. device/stream 初始化 int32_t deviceId = 0; aclrtStream stream; CHECK_RET(InitAcl(deviceId, &stream) == ACL_SUCCESS, return -1); // 2. 构造输入与输出 std::vector<int64_t> selfShape = {3, 3}; std::vector<int64_t> otherShape = {3, 3}; std::vector<int64_t> outShape = {3, 3}; void* selfDeviceAddr = nullptr; void* otherDeviceAddr = nullptr; void* outDeviceAddr = nullptr; aclTensor* self = nullptr; aclTensor* other = nullptr; aclTensor* out = nullptr; aclError ret = CreateInputs( selfShape, otherShape, outShape, &selfDeviceAddr, &otherDeviceAddr, &outDeviceAddr, &self, &other, &out); CHECK_RET(ret == ACL_SUCCESS, return ret); // 3. 调用 CANN 算子 API int64_t dim = 1; uint64_t workspaceSize = 0; void* workspaceAddr = nullptr; ret = ExecOpApi(self, other, out, dim, &workspaceAddr, workspaceSize, outDeviceAddr, outShape, stream); CHECK_RET(ret == ACL_SUCCESS, return ret); // 4. 释放 aclTensor aclDestroyTensor(self); aclDestroyTensor(other); aclDestroyTensor(out); // 5. 释放 device 资源 aclrtFree(selfDeviceAddr); aclrtFree(otherDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

示例中self取{3, 3}（dim=1 上每组向量为(0,1,2)、(3,4,5)、(6,7,8)），other取{3, 3}（每组向量(1,1,1)、(2,2,2)、(3,3,3)），逐行叉乘后可对照验证输出：第一行(1*2-2*1, 2*1-0*2, 0*1-1*1) = (0, 2, -1)。仓库另提供一份可独立编译的完整样例 examples/test_aclnn_linalg_cross.cpp。

九、测试与验证

仓库为 aclnnLinalgCross 提供了两层自动化测试，可作为接口行为与边界条件的权威参考：

• op_api 层 UT：tests/ut/op_api/test_aclnn_linalg_cross.cpp 覆盖了不支持类型校验（如ACL_BOOL输入返回ACLNN_ERR_PARAM_INVALID）、空 Tensor（{1, 0, 3}、{1, 1, 0, 3}等）在有无广播时的通过/失败分支，以及合法输入的TestGetWorkspaceSize调用；
• op_host / op_kernel 层测试：tests/ut/op_host/test_cross_tiling.cpp 验证 tiling 切分参数（intervalNum、loopTimes、tileDataNum、blockDim），tests/ut/op_kernel/test_cross.cpp 配合 gen_data.py 与 compare_data.py 完成内核数值比对。

十、小结

aclnnLinalgCross是 CANN ops-math 中实现三维向量叉乘的标准接口，具有类型覆盖广（含整数、浮点、复数与 BF16）、支持广播与非连续 Tensor、默认确定性计算的特点。理解其两段式接口模型、参数与错误码语义，再结合 op_api、op_host、op_kernel 三层的源码实现，即可在 Atlas A2 系列产品上正确、高效地完成叉乘算子的接入与调试。

【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math