asc-devkit Where 高阶 API 条件选择算子样例:从 Kernel 实现到编译运行全解析
asc-devkit Where 高阶 API 条件选择算子样例:从 Kernel 实现到编译运行全解析
本文围绕 asc-devkit 仓库中基于 SIMD(向量)编程模型实现的 Where 高阶 API 样例(examples/01_simd_cpp_api/04_advanced_api/10_math/where)展开,系统讲解"根据条件从两个源操作数中选择元素"这一典型条件选择算子的完整落地路径:从样例规格、Kernel 源码结构、Where API 的函数原型与底层指令级实现,到数据生成、编译运行(NPU/CPU 调试/NPU 仿真三种模式)与精度验证。读者学完后,既能直接复现该样例的编译与运行,也能掌握 Where API 张量/标量四种混合调用模式以及其背后 Reg::Select 指令级选择原理,为编写同类高阶 API 算子提供可参考的工程范式。
样例概述:功能、计算公式与规格
该样例基于 Where 高阶 API 实现条件选择功能:根据指定的条件(condition),从两个源操作数(src0、src1)中选择元素,生成目标操作数(dst)。两个源操作数均可以是 LocalTensor 或标量,即支持张量与标量混合模式,这也是本样例区别于基础向量 API 的核心亮点。
计算公式如下:
dst_i = src0_i, if condition_i 为真(非 0)
dst_i = src1_i, otherwise(condition_i 为 0)
样例规格(对应 README.md 中的样例规格表):
| 项 | 说明 |
|---|---|
| 样例类型(OpType) | where |
| 样例输入 src0 | shape [1, 32],数据类型 float,格式 ND |
| 样例输入 src1 | shape [1, 32],数据类型 float,格式 ND |
| 样例输入 condition | shape [1, 32],数据类型 bool,格式 ND |
| 样例输出 dst | shape [1, 32],数据类型 float,格式 ND |
| 核函数名 | where_custom |
产品与版本支持情况:Ascend 950PR&950DT 系列产品,CANN 软件版本 >= 9.1.0。
样例目录结构
where
├── scripts
│ └── gen_data.py // 输入数据和真值数据生成脚本
├── CMakeLists.txt // 编译工程文件
├── data_utils.h // 数据读入写出函数
├── where.asc // Ascend C 样例实现 & 调用样例
└── README.md // 样例说明文档
其中:
- where.asc 是样例核心文件,同时包含 Kernel 实现(
KernelWhere类 +where_custom核函数)与主机侧调用实现(基于 ACL 运行时 API 的main函数); - gen_data.py 使用 NumPy 生成输入二进制文件与真值(golden)文件;
- data_utils.h 提供
ReadFile/WriteFile两个文件读写工具函数,用于主机侧读写input/、output/目录下的二进制数据; - CMakeLists.txt 通过
find_package(ASC REQUIRED)引入 asc-devkit 提供的 ASC 语言编译工具链,并将where.asc编译为可执行程序demo。
Kernel 实现深度解析
Kernel 侧实现位于 where.asc,整体遵循"CopyIn → Compute → CopyOut"三段式流水结构。
类与成员:KernelWhere<T>
KernelWhere 是模板类,T 为数据类型(本样例实例化为 float)。它通过 TPipe 管理三路向量输入队列与一路输出队列:
inQueueX、inQueueY、inQueueZ:TQue<QuePosition::VECIN, 1>,分别缓存 src0、src1、condition;outQueue:TQue<QuePosition::VECOUT, 1>,缓存计算结果 dst;- 对应的
GlobalTensor:src0Global、src1Global、dstGlobal(类型T)以及conditionGlobal(类型bool)。
在 Init 中,使用 SetGlobalBuffer 为全局张量绑定显存地址,其中 condition 缓冲区按 (shape + 31) / 32 * 32 对齐到 32 的整数倍;随后用 InitBuffer 为各队列申请 UB(统一缓冲区)空间。该初始化还接收 shape(元素数)、count(参与计算元素个数)、mode(调用模式)三个控制参数。
三段式流水:CopyIn / Compute / CopyOut
Process 依次执行 CopyIn、Compute、CopyOut,并在首尾通过 AscendC::AscendCUtils::SetOverflow(1) / SetOverflow(0) 开启/关闭溢出检测开关,用于调试时暴露计算溢出问题。
- CopyIn:分别
AllocTensor<T>()从三个输入队列申请 LocalTensor,调用AscendC::DataCopy将全局内存数据拷入 UB,最后EnQue入队。 - Compute:
DeQue出队得到三个输入 LocalTensor,先AscendC::Duplicate(dstLocal, (T)0, shape)将输出清零,然后根据mode选择调用形态调用AscendC::Where<T>(...),完成后EnQue输出队列并FreeTensor释放输入队列。 - CopyOut:从输出队列
DeQue取出结果,AscendC::DataCopy拷回全局内存,再FreeTensor。
四种调用模式:张量与标量混合
where.asc 中通过 mode 参数区分四种 Where 调用形态:
| mode | 形态 | 调用示例(代码注释中的说明) |
|---|---|---|
| 0 | 张量对张量 | Where<T>(dstLocal, src0Local, src1Local, conditionLocal, dataSize) |
| 1 | src0 为标量 | Where<T>(dstLocal, src0, src1Local, conditionLocal, dataSize) |
| 2 | src1 为标量 | Where<T>(dstLocal, src0Local, src1, conditionLocal, dataSize) |
| 3 | src0 与 src1 均为标量 | Where<T>(dstLocal, src0, src1, conditionLocal, dataSize) |
需要特别说明的是标量提取过程:标量并非直接由外部传入,而是通过 src0Local.GetValue(0) 从已入队的 LocalTensor 中取出首元素作为标量。由于 GetValue 是标量(S)侧操作,而数据搬运是 MTE2 侧操作,二者存在跨流水单元的数据依赖,因此代码中使用硬件事件同步保证正确性:
event_t eventIdMTE2ToS = static_cast<event_t>(GetTPipePtr()->FetchEventID(AscendC::HardEvent::MTE2_S));
AscendC::SetFlag<AscendC::HardEvent::MTE2_S>(eventIdMTE2ToS);
AscendC::WaitFlag<AscendC::HardEvent::MTE2_S>(eventIdMTE2ToS);
T src0 = src0Local.GetValue(0);
event_t eventIdSToV = static_cast<event_t>(GetTPipePtr()->FetchEventID(AscendC::HardEvent::S_V));
AscendC::SetFlag<AscendC::HardEvent::S_V>(eventIdSToV);
AscendC::WaitFlag<AscendC::HardEvent::S_V>(eventIdSToV);
即先用 MTE2_S 事件保证"MTE2 数据搬运完成 → 标量读取",再用 S_V 事件保证"标量读取完成 → 向量计算可用",这是 SIMD 编程模型中处理 MTE2/标量/向量跨单元依赖的标准写法。
主机侧调用实现
核函数 where_custom 声明为 __global__ __vector__,固定 shape=32、count=32、mode=0(张量对张量模式)。主机侧 main 函数完整走通 ACL 运行时流程:
aclInit初始化、aclrtSetDevice/aclrtCreateContext/aclrtCreateStream建立设备上下文与流;- 为 src0、src1、condition、tiling 及输出分别
aclrtMallocHost+aclrtMalloc申请主机与设备内存; - 通过
ReadFile读取./input/*.bin,用aclrtMemcpy(..., ACL_MEMCPY_HOST_TO_DEVICE)拷入设备; - 使用内核调用符
where_custom<<<numBlocks, 0, stream>>>(param1Device, param2Device, param3Device, param5Device)触发核函数(本样例numBlocks = 1); aclrtSynchronizeStream等待执行完成,ACL_MEMCPY_DEVICE_TO_HOST拷回结果并WriteFile写出./output/output.bin;- 调用
CompareResult与真值./output/golden.bin逐元素比对,绝对误差与相对误差均大于EPS = 1e-4才判定为错误,最终打印test pass!或test failed!。
Where 高阶 API:函数原型与参数说明
样例调用的 AscendC::Where 属于高级 API(adv_api)数学计算接口,公开头文件为 include/adv_api/math/where.h,完整接口说明可参见 docs/zh/api/SIMD-API/adv_api/math_compute/Where_interface/Where.md。
函数原型:
template <typename T, typename U, typename S, typename V>
__aicore__ inline void Where(
const LocalTensor<T>& dst, const U& src0, const S& src1,
const LocalTensor<V>& condition, const uint32_t count)
模板参数说明:
| 模板参数 | 描述 |
|---|---|
| T | 目的操作数数据类型。支持 bool、int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_t。 |
| U | LocalTensor 类型或标量类型,由 src0 自动推导,无需显式配置;src0 数据类型须与目的操作数一致。 |
| S | LocalTensor 类型或标量类型,由 src1 自动推导,无需显式配置;src1 数据类型须与目的操作数一致。 |
| V | 条件操作数数据类型,当前仅支持 bool。 |
参数说明:
| 参数 | 方向 | 说明 |
|---|---|---|
| dst | 输出 | 目的操作数,类型为 LocalTensor<T>,支持的 TPosition 为 VECIN/VECCALC/VECOUT。 |
| src0、src1 | 输入 | 源操作数,类型为标量或 LocalTensor;为 LocalTensor 时支持的 TPosition 为 VECIN/VECCALC/VECOUT,数据类型须与目的操作数一致。 |
| condition | 输入 | 条件操作数,类型为 LocalTensor<bool>,支持的 TPosition 为 VECIN/VECCALC/VECOUT。 |
| count | 输入 | 参与计算的元素个数。 |
官方接口文档给出的调用示例(half 类型):
AscendC::LocalTensor<half> dst, src0, src1;
AscendC::LocalTensor<bool> condition;
uint32_t count = 512; // 参与计算的元素个数
AscendC::Where(dst, src0, src1, condition, count);
对应语义为:condition 为 1 时选择 src0 元素,为 0 时选择 src1 元素。
产品支持范围(据 Where.md):Ascend 950PR&950DT 系列产品支持;Atlas A3/A2 系列、Atlas 200I/500 A2 推理产品、Atlas 推理系列产品及 Atlas 训练系列产品均不支持。此外,where.h 头部明确禁止在 --enable-simt(纯 SIMT 编译)模式下包含该头文件。
底层实现原理:指令级条件选择
Where 的 Kernel 侧实现位于 impl/adv_api/detail/math/where/where_3510_impl.h(该文件为内部头文件,官方要求开发者只通过 #include "adv_api/math/where.h" 使用公开接口)。分析该实现可以还原 Where 的指令级工作方式。
静态类型约束
WhereImpl 通过 static_assert 与 SupportType 编译期约束模板参数:
- T(数据类型)支持 bool/int8_t/uint8_t/int16_t/uint16_t/half/bfloat16_t/int32_t/uint32_t/float/int64_t/uint64_t;
- condition 类型 V 仅支持 bool;
- 当 src0、src1 为 LocalTensor 时,其模板参数须与 T 及 PrimType 一致(
static_assert(Std::is_same<U, S>::value)等),保证三者的元素类型统一。
四种形态的模板分派
WhereImpl 用 if constexpr 结合 TypeUtils::IsLocalTensorType / IsInnerDefaultType 在编译期区分四种输入形态(对应样例中的 mode 0~3),并将是否标量固化为模板参数 src0Val/src1Val 传给 WhereCompute。WhereCompute<src0Val, src1Val, ...> 利用 if constexpr (src0Val) 提前用 Reg::Duplicate 把标量值灌入向量寄存器,避免在循环体内反复加载。
核心计算循环
WhereCompute 的核心是逐 repeat 的寄存器级循环,关键步骤为:
Reg::LoadAlign(selReg, conditionUb + i * repeatElm)加载条件数据;Reg::CompareScalar<uint8_t, CMPMODE::NE>(selMask, selReg, 0, maskFull)将条件与 0 比较,生成选择掩码(bool 非 0 即真);- 对 2/4/8 字节数据类型执行
Reg::MaskUnPack将按字节展开的掩码压缩为与元素粒度一致的掩码; Reg::LoadAlign加载 src0、src1 数据(仅当对应操作数为张量时);Reg::Select(dstReg, src0Reg, src1Reg, selMask)依据掩码完成指令级选择:掩码位为 1 选 src0,为 0 选 src1;Reg::StoreAlign(dstUb + i * repeatElm, dstReg, maskReg)按剩余 count 生成的掩码回写结果。
其中 repeatTime = CeilDivision(count, GetVecLen() / sizeof(WhereType)) 表示按向量长度切分的重复次数;对于 8 字节类型(int64_t/uint64_t),实现选用 Reg::RegTraitNumTwo(双寄存器粒度)与 uint64_t 工作类型,以适配 64 位元素在向量寄存器中的排布。
参数校验与 Tiling 辅助接口
- 设备侧参数校验:
CheckFuncWhere(见 where_check_aicore.h)在 CPU 调试(ASCENDC_CPU_DEBUG)场景下对 count 与各 Tensor 进行CalCountVerifyingParameters(计算个数校验)与TensorVerifyingParameters(TPosition 为 VECIN/VECOUT/VECCALC 的位置校验),从 API 层拦截非法调用; - 主机侧 Tiling 辅助: where_tiling.h 提供
GetWhereMaxMinTmpSize(获取最大/最小临时空间)与GetWhereTmpBufferFactorSize(推导单次迭代计算元素数)两个接口,供 Tiling 算子计算临时缓冲区大小。其实现(where_tiling_impl.cpp)目前仅接受 DAV_3510 与 DAV_9201 两种架构,且校验通过后返回的临时空间需求为 0——说明该实现版本中 Where 为"原地直算"型算子,无需额外临时空间,Tiling 阶段只需依据剩余空间切分迭代即可。
数据生成与真值对比
gen_data.py 使用 NumPy 生成测试数据与真值:
src0:np.random.uniform(10.0, 20.0, [32]),即 10~20 区间的 float32 随机数;src1:np.random.uniform(0, 10.0, [32]),即 0~10 区间的 float32 随机数;condition:np.random.choice([True, False], size=shape)随机布尔序列;- 真值
golden = np.where(condition, src0, src1),与 Kernel 语义一一对应;脚本同时支持 mode 0~3 四种真值计算分支; - 另将
[shape, count, mode, is_dynamic]打包为 uint32 数组写入input_tiling.bin,作为 Tiling 参数输入。
脚本生成 ./input/input_src0.bin、./input/input_src1.bin、./input/input_condition.bin、./input/input_tiling.bin 及 ./output/golden.bin。主机侧 CompareResult 从 ./output/golden.bin 读取真值,按 EPS = 1e-4 的绝对/相对误差双阈值逐元素比对,全部通过才输出 test pass!。
编译运行:三种运行模式与编译选项
配置环境变量
根据当前环境上 CANN 开发套件包的安装方式配置环境变量:
source ${install_path}/cann/set_env.sh
说明:
${install_path}为 CANN 包安装目录,未指定安装目录时默认安装至/usr/local/Ascend下。
样例执行(默认 NPU 模式)
在样例根目录 examples/01_simd_cpp_api/04_advanced_api/10_math/where 下依次执行:
mkdir -p build && cd build; # 创建并进入 build 目录
cmake -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..; make -j; # 编译工程,默认 npu 模式
python3 ../scripts/gen_data.py # 生成测试输入数据
./demo # 执行编译生成的可执行程序
CPU 调试与 NPU 仿真模式
在 cmake 阶段追加 -DCMAKE_ASC_RUN_MODE 参数即可切换运行模式:
cmake -DCMAKE_ASC_RUN_MODE=cpu -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..; make -j; # CPU 调试模式
cmake -DCMAKE_ASC_RUN_MODE=sim -DCMAKE_ASC_ARCHITECTURES=dav-3510 ..; make -j; # NPU 仿真模式
注意:切换编译模式前需清理 cmake 缓存,可在 build 目录下执行
rm CMakeCache.txt后重新 cmake。
编译选项说明
| 选项 | 可选值 | 说明 |
|---|---|---|
CMAKE_ASC_RUN_MODE |
npu(默认)、cpu、sim |
运行模式:NPU 运行、CPU 调试、NPU 仿真 |
CMAKE_ASC_ARCHITECTURES |
dav-3510(默认) |
NPU 架构:dav-3510 对应 Ascend 950PR&950DT 系列产品 |
这两个选项在 CMakeLists.txt 中以 CACHE STRING 形式声明(CMAKE_ASC_RUN_MODE 默认 npu,CMAKE_ASC_ARCHITECTURES 默认 dav-3510,并注明亦支持 dav-2201),工程通过 find_package(ASC REQUIRED) 找到 ASC 编译器后,以 target_compile_options 传入 --npu-arch=${CMAKE_ASC_ARCHITECTURES} 完成目标架构编译。
执行结果
精度对比成功后输出:
test pass!
测试用例佐证:多类型多形态覆盖
仓库单元测试 tests/api/adv_api/math/where/test_operator_where.cpp 用 gtest 参数化测试(AdvanceWhereTestSuite)覆盖了 Where 的多种组合,印证了样例 Kernel 设计的通用性:
- 数据类型:
float(4 字节)、half(2 字节)、int8_t(1 字节)、int64_t(8 字节),对应WhereTestParams.dataTypeSize1/2/4/8; - 数据规模:32、64、96、256、1024、4096 等多种 count;
- 调用形态:mode 0~3 全部覆盖,且测试 Kernel 中的 mode 分支与样例
where.asc保持一致(Where张量/标量四种调用)。
这组测试同时验证了 Where 在 64 位数据类型上的寄存器扩展实现(RegTraitNumTwo)与 1 字节类型上的掩码压缩逻辑。
约束与注意事项
- 不支持源操作数与目的操作数地址重叠,开发者需保证 dst 与 src0、src1、condition 指向不同缓冲区;
- 操作数地址偏移对齐要求遵循高阶 API 的通用说明和约束;
- 产品支持面较窄:当前仅 Ascend 950PR&950DT 系列(CANN >= 9.1.0)支持该 API,Atlas A2/A3、推理及训练系列均不支持,跨平台迁移前需先确认目标产品的支持矩阵;
- 头文件 where.h 明确禁止在
--enable-simt编译选项下使用; - 标量模式(mode 1/2/3)涉及
GetValue(0)的标量读取,必须配以MTE2_S与S_V事件同步,否则可能读到搬运未完成的数据。
综上,该 Where 样例从 API 使用、指令级原理到工程化编译运行形成了完整闭环,既是条件选择类算子的标准实现范本,也是理解高阶 API 张量/标量混合调用与跨流水单元同步机制的绝佳入门样例。