--- title: Select（灵活标量位置） description: "| 产品 | 是否支持 |" url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/ascendcopapi/atlasascendc_api_07_00257.html sourcePath: /source/zh/canncommercial/900/API/ascendcopapi/atlasascendc_api_07_00257.html indexId: 14e6a60b11e226edc5c37482923158ac40ebf19dafcc7fce4e34e7348ba57b5e77 --- # Select（灵活标量位置） #### 产品支持情况 | 产品 | 是否支持 | | --- | --- | | Atlas 350 加速卡 | √ | | Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | x | | Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | x | | Atlas 200I/500 A2 推理产品 | x | | Atlas 推理系列产品 AI Core | x | | Atlas 推理系列产品 Vector Core | x | | Atlas 训练系列产品 | x | #### 功能说明 给定两个源操作数src0和src1，根据selMask（用于选择的Mask掩码）的比特位值选取元素，得到目的操作数dst。选择的规则为：当selMask的比特位是1时，从src0中选取，比特位是0时从src1选取。 对于tensor高维切分计算接口，支持根据mask参数对上述选取结果，再次进行过滤，有效位填入最终的dst，无效位则保持dst原始值。例如：src0为[1,2,3,4,5,6,7,8]，src1为[9,10,11,12,13,14,15,16]，selMask为[0,0,0,0,1,1,1,1]，mask为[1,1,1,1,0,0,0,0]，dst原始值为[-1,-2,-3,-4,-5,-6,-7,-8]，则根据selMask的比特位选取后的结果dst_temp为：[9,10,11,12,5,6,7,8]，然后再根据mask进行过滤，dst的最终输出结果为[9,10,11,12,-5,-6,-7,-8]。 本选择功能支持三种模式： - 模式0：根据selMask在两个tensor中选取元素。selMask中有效数据的个数存在限制，具体取决于源操作数的数据类型。在每一轮迭代中，根据selMask的有效位数据进行选择操作，每一轮迭代采用的selMask，均为相同数值，即selMask的有效数值。 - 模式1：根据selMask在1个tensor和1个scalar标量中选取元素，selMask无有效数据限制。多轮迭代时，每轮迭代连续使用selMask的不同部分。 - 模式2：根据selMask在两个tensor中选取元素，selMask无有效数据限制。多轮迭代时，每轮迭代连续使用selMask的不同部分。 针对模式1，提供灵活标量位置的接口。 #### 函数原型 - tensor前n个数据计算 1 2 template __aicore__ inline void Select(const T2& dst, const LocalTensor& selMask, const T3& src0, const T4& src1, SELMODE selMode, uint32_t count) - tensor高维切分计算 - mask逐bit模式 1 2 template __aicore__ inline void Select(const T2& dst, const LocalTensor& selMask, const T3& src0, const T4& src1, SELMODE selMode, uint64_t mask[], uint8_t repeatTime, const BinaryRepeatParams& repeatParams) - mask连续模式 1 2 template __aicore__ inline void Select(const T2& dst, const LocalTensor& selMask, const T3& src0, const T4& src1, SELMODE selMode, uint64_t mask, uint8_t repeatTime, const BinaryRepeatParams& repeatParams) #### 参数说明 **表1 模板参数说明** | 参数名称 | 含义 | | | | --- | --- | --- | --- | | T0 | 源操作数和目的操作数的数据类型。 特别地，对于灵活标量位置接口，为预留参数，暂未启用，为后续的功能扩展做保留，需要指定时，传入默认值BinaryDefaultType即可。 | | | | T1 | selMask的数据类型。 | | | | isSetMask | 预留参数，保持默认值即可。如需使用在接口外部设置mask的功能，可以调用不传入mask参数的接口来实现。 | | | | selMode | 同表2 参数说明中的selMode参数说明。 | | | | config | 类型为BinaryConfig，当标量为LocalTensor单点元素类型时生效，用于指定单点元素操作数位置。默认值DEFAULT\_BINARY\_CONFIG，表示右操作数为标量。 1 2 3 4 struct BinaryConfig { int8\_t scalarTensorIndex = 1; // 用于指定标量为LocalTensor单点元素时标量的位置，0表示左操作数，1表示右操作数 }; constexpr BinaryConfig DEFAULT\_BINARY\_CONFIG = {1}; | 1 2 3 4 | struct BinaryConfig { int8\_t scalarTensorIndex = 1; // 用于指定标量为LocalTensor单点元素时标量的位置，0表示左操作数，1表示右操作数 }; constexpr BinaryConfig DEFAULT\_BINARY\_CONFIG = {1}; | | 1 2 3 4 | struct BinaryConfig { int8\_t scalarTensorIndex = 1; // 用于指定标量为LocalTensor单点元素时标量的位置，0表示左操作数，1表示右操作数 }; constexpr BinaryConfig DEFAULT\_BINARY\_CONFIG = {1}; | | | | T2 | LocalTensor类型，根据输入参数dst自动推导相应的数据类型，开发者无需配置该参数，保证dst满足数据类型的约束即可。 | | | | T3 | LocalTensor类型或标量类型，根据输入参数src0自动推导相应的数据类型，开发者无需配置该参数，保证src0满足数据类型的约束即可。 | | | | T4 | LocalTensor类型或标量类型，根据输入参数src1自动推导相应的数据类型，开发者无需配置该参数，保证src1满足数据类型的约束即可。 | | | **表2 参数说明** | 参数名称 | 输入/输出 | 含义 | | | | --- | --- | --- | --- | --- | | dst | 输出 | 目的操作数。 类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要32字节对齐。 Atlas 350 加速卡，支持的数据类型为：int8\_t/uint8\_t/int16\_t/uint16\_t/half/bfloat16\_t/float/int32\_t/uint32\_t/complex32/int64\_t/uint64\_t/complex64 | | | | selMask | 输入 | 选取mask。 类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要32字节对齐。 Atlas 350 加速卡，支持的数据类型为：uint8\_t/uint16\_t/uint32\_t/uint64\_t。 每个比特位表示1个元素的选取，当selMask的比特位为1时，从src0中选取元素；比特位为0时，从src1中选取元素。 selMode为模式0时，在每一轮迭代中，根据selMask的有效位数据进行选择操作，每一轮迭代采用的selMask，均为相同数值，即selMask的有效数值。selMode为模式1/2时，多次迭代对selMask连续消耗。 模式0：根据selMask在两个tensor中选取元素，selMask有位数限制，不管迭代多少次，每次迭代都只根据截取后的固定位数的selMask进行选择。当源操作数的数据类型为8位时，selMask前256比特位有效；当源操作数的数据类型为16位时，selMask前128比特位有效；源操作数的数据类型为32位时，selMask前64比特位有效；源操作数的数据类型为64位时，selMask前32比特位有效。 模式1：根据selMask在1个tensor和1个scalar标量中选取元素。支持多次迭代，选取方式为，根据selMask的设置值，如果selMask比特值为1，则选择src0内的同位置数值，如果selMask比特值为0，则选择标量值。selMask连续存放，当源操作数的数据类型为8位时，一次比较获取selMask256bit长度的数据；当源操作数的数据类型为16位时，一次比较获取selMask128bit长度的数据；源操作数的数据类型为32位时，一次比较获取selMask64bit长度的数据；源操作数的数据类型为64位时，一次比较获取selMask32bit长度的数据。 模式2：根据selMask在两个tensor中选取元素。支持多次迭代，选取方式为，根据selMask的设置值，如果selMask比特值为1，则选择src0内的同位置数值，如果selMask比特值为0，则选择src1内的同位置数值。selMask连续存放，当源操作数的数据类型为8位时，一次比较获取selMask256bit长度的数据；当源操作数的数据类型为16位时，一次比较获取selMask128bit长度的数据；源操作数的数据类型为32位时，一次比较获取selMask64bit长度的数据；源操作数的数据类型为64位时，一次比较获取selMask32bit长度的数据。 | | | | src0 | 输入 | 灵活标量位置接口中源操作数。 类型为LocalTensor时，支持当作矢量操作数或标量单点元素，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要32字节对齐。 Atlas 350 加速卡，支持的数据类型为：int8\_t/uint8\_t/int16\_t/uint16\_t/half/bfloat16\_t/float/int32\_t/uint32\_t/complex32/int64\_t/uint64\_t/complex64 类型为标量时： Atlas 350 加速卡，支持的数据类型为：int8\_t/uint8\_t/int16\_t/uint16\_t/half/bfloat16\_t/float/int32\_t/uint32\_t/complex32/int64\_t/uint64\_t/complex64 数据类型需要与目的操作数保持一致。 | | | | src1 | 输入 | 灵活标量位置接口中源操作数。 类型为LocalTensor时，支持当作矢量操作数或标量单点元素，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要32字节对齐。 Atlas 350 加速卡，支持的数据类型为：int8\_t/uint8\_t/int16\_t/uint16\_t/half/bfloat16\_t/float/int32\_t/uint32\_t/complex32/int64\_t/uint64\_t/complex64 类型为标量时： Atlas 350 加速卡，支持的数据类型为：int8\_t/uint8\_t/int16\_t/uint16\_t/half/bfloat16\_t/float/int32\_t/uint32\_t/complex32/int64\_t/uint64\_t/complex64 数据类型需要与目的操作数保持一致。 | | | | selMode | 输入 | 指令模式，SELMODE类型，取值如下： 1 2 3 4 5 enum class SELMODE : uint8\_t { VSEL\_CMPMASK\_SPR = 0, VSEL\_TENSOR\_SCALAR\_MODE, VSEL\_TENSOR\_TENSOR\_MODE, }; 模式0：取值为VSEL\_CMPMASK\_SPR。根据selMask在两个tensor中选取元素。selMask中有效数据的个数存在限制，具体取决于源操作数的数据类型。在每一轮迭代中，根据selMask的有效位数据进行选择操作，每一轮迭代采用的selMask，均为相同数值，即selMask的有效数值。 模式1：取值为VSEL\_TENSOR\_SCALAR\_MODE。根据selMask在1个tensor和1个scalar标量中选取元素，selMask无有效数据限制。多轮迭代时，每轮迭代连续使用selMask的不同部分。 模式2：取值为VSEL\_TENSOR\_TENSOR\_MODE。根据selMask在两个tensor中选取元素，selMask无有效数据限制。多轮迭代时，每轮迭代连续使用selMask的不同部分。 | 1 2 3 4 5 | enum class SELMODE : uint8\_t { VSEL\_CMPMASK\_SPR = 0, VSEL\_TENSOR\_SCALAR\_MODE, VSEL\_TENSOR\_TENSOR\_MODE, }; | | 1 2 3 4 5 | enum class SELMODE : uint8\_t { VSEL\_CMPMASK\_SPR = 0, VSEL\_TENSOR\_SCALAR\_MODE, VSEL\_TENSOR\_TENSOR\_MODE, }; | | | | | mask/mask[] | 输入 | mask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/programug/Ascendcopdevg/atlas\_ascendc\_10\_0022.html\#ZH\-CN\_TOPIC\_0000002562282205\_\_zh\-cn\_topic\_0000002267504656\_zh\-cn\_topic\_0000001764162593\_section4252658182)用于控制每次迭代内参与计算的元素。 逐bit模式：可以按位控制哪些元素参与计算，bit位的值为1表示参与计算，0表示不参与。 mask为数组形式，数组长度和数组元素的取值范围和操作数的数据类型有关。当操作数为16位时，数组长度为2，mask[0]、mask[1]∈[0, 264\-1]并且不同时为0；当操作数为32位时，数组长度为1，mask[0]∈(0, 264\-1]；当操作数为64位时，数组长度为1，mask[0]∈(0, 232\-1]。 例如，mask=[8, 0]，8=0b1000，表示仅第4个元素参与计算。 连续模式：表示前面连续的多少个元素参与计算。取值范围和操作数的数据类型有关，数据类型不同，每次迭代内能够处理的元素个数最大值不同。当操作数为16位时，mask∈[1, 128]；当操作数为32位时，mask∈[1, 64]；当操作数为64位时，mask∈[1, 32]。 | | | | repeatTime | 输入 | 重复迭代次数。矢量计算单元，每次读取连续的256Bytes数据进行计算，为完成对输入数据的处理，必须通过多次迭代（repeat）才能完成所有数据的读取与计算。repeatTime表示迭代的次数。 关于该参数的具体描述请参考高维切分API(https://www.hiascend.comdocument/detail/zh/canncommercial/900/programug/Ascendcopdevg/atlas\_ascendc\_10\_0022.html)。 | | | | repeatParams | 输入 | 控制操作数地址步长的参数。BinaryRepeatParams类型，包含操作数相邻迭代间相同datablock的地址步长，操作数同一迭代内不同datablock的地址步长等参数。 相邻迭代间的地址步长参数说明请参考repeatStride(https://www.hiascend.comdocument/detail/zh/canncommercial/900/programug/Ascendcopdevg/atlas\_ascendc\_10\_0022.html\#ZH\-CN\_TOPIC\_0000002562282205\_\_zh\-cn\_topic\_0000002267504656\_zh\-cn\_topic\_0000001764162593\_section139459347420)；同一迭代内DataBlock的地址步长参数说明请参考dataBlockStride(https://www.hiascend.comdocument/detail/zh/canncommercial/900/programug/Ascendcopdevg/atlas\_ascendc\_10\_0022.html\#ZH\-CN\_TOPIC\_0000002562282205\_\_zh\-cn\_topic\_0000002267504656\_zh\-cn\_topic\_0000001764162593\_section2815124173416)。 | | | | count | 输入 | 参与计算的元素个数。 | | | #### 返回值说明 无 #### 约束说明 - 调用灵活标量位置接口且源操作数为LocalTensor单点元素的场景，不支持源操作数和目的操作数地址重叠。 - 操作数地址对齐要求请参见 通用地址对齐约束 。 - 针对Atlas 350 加速卡，int8_t/uint8_t/uint64_t/int64_t/complex32/complex64数据类型仅支持tensor前n个数据计算接口。 - 左操作数及右操作数中，必须有一个为矢量；当前不支持左右操作数同时为标量。 - 本接口传入LocalTensor单点数据作为标量时，idx参数需要传入编译期已知的常量，传入变量时需要声明为constexpr。 - 模式1场景使用灵活标量位置接口时需要填写模板参数config避免接口匹配到其他模式。 #### 调用示例 - Select-tensor前n个数据计算样例（模式1） 1 2 3 4 5 6 7 // 灵活标量位置，src1Local[0]作为标量 static constexpr AscendC::BinaryConfig config = { 1 }; AscendC::Select(dstLocal, maskLocal, src0Local, src1Local[0], AscendC::SELMODE::VSEL_TENSOR_SCALAR_MODE, dataSize); // 灵活标量位置，src0Local[0]作为标量 static constexpr AscendC::BinaryConfig config = { 0 }; AscendC::Select(dstLocal, maskLocal, src0Local[0], src1Local, AscendC::SELMODE::VSEL_TENSOR_SCALAR_MODE, dataSize);