asc.language.basic

Common operations

axpy	源操作数src中每个元素与标量求积后和目的操作数dst中的对应元素相加，计算公式如下： dst[i] = src[i] * scalar + dst[i]
brcb	给定一个输入张量，每一次取输入张量中的8个数填充到结果张量的8个datablock（32Bytes）中去，每个数对应一个datablock。
cast	根据源操作数和目的操作数Tensor的数据类型进行精度转换。
cast_deq	对输入做量化并进行精度转换。不同的数据类型，转换公式不同。
check_local_memory_ia	Check设定范围内的UB读写行为，如果有设定范围的读写行为则会出现EXCEPTION报错，无设定范围的读写行为则不会报错。
copy	在 Vector Core 的不同内部存储单元（VECIN, VECCALC, VECOUT）之间进行数据搬运。
cross_core_set_flag	面向分离架构的核间同步控制接口。 该接口和cross_core_wait_flag接口配合使用。使用时需传入核间同步的标记ID(flagId)，每个ID对应一个初始值为0的计数器。执行cross_core_set_flag后ID对应的计数器增加1；执行cross_core_wait_flag时如果对应的计数器数值为0则阻塞不执行；如果对应的计数器大于0，则计数器减一，同时后续指令开始执行。 同步控制分为以下几种模式： - 模式0：AI Core核间的同步控制。对于AIC场景，同步所有的AIC核，直到所有的AIC核都执行到cross_core_set_flag时，cross_core_wait_flag后续的指令才会执行；对于AIV场景，同步所有的AIV核，直到所有的AIV核都执行到cross_core_set_flag时，cross_core_wait_flag后续的指令才会执行。 - 模式1：AI Core内部，AIV核之间的同步控制。如果两个AIV核都运行了cross_core_set_flag，cross_core_wait_flag后续的指令才会执行。 - 模式2：AI Core内部，AIC与AIV之间的同步控制。在AIC核执行cross_core_set_flag之后，两个AIV上cross_core_wait_flag后续的指令才会继续执行；两个AIV都执行cross_core_set_flag后，AIC上cross_core_wait_flag后续的指令才能执行。
cross_core_wait_flag	面向分离架构的核间同步控制接口。该接口和cross_core_set_flag接口配合使用。具体使用方法请参考cross_core_set_flag。
data_cache_clean_and_invalid	用来刷新Cache，保证Cache与Global Memory之间的数据一致性。
data_cache_preload	从源地址所在的特定GM地址预加载数据到data cache中。
data_copy	DataCopy系列接口提供全面的数据搬运功能，支持多种数据搬运场景，并可在搬运过程中实现随路格式转换和量化激活等操作。 该接口支持Local Memory与Global Memory之间的数据搬运，以及Local Memory内部的数据搬运。
data_copy_pad	DataCopyPad接口提供数据非对齐搬运的功能，其中从Global Memory搬运数据至Local Memory时，可以根据开发者的需要自行填充数据。
data_sync_barrier	用于阻塞后续的指令执行，直到所有之前的内存访问指令（需要等待的内存位置可通过参数控制）执行结束。
dump_acc_chk_point	基于算子工程开发的算子，可以使用该接口 Dump 指定 Tensor 的内容。 同时支持打印自定义的附加信息（仅支持 uint32_t 类型的信息）， 例如用于打印当前执行位置、行号等调试信息。 与 dump_tensor 不同的是，该接口支持指定 Tensor 的偏移位置进行 Dump，适用于精细化调试和问题定位。
dump_tensor	基于算子工程开发的算子，可以使用该接口Dump指定Tensor的内容。
duplicate	将一个变量或立即数复制多次并填充到向量中。
fixpipe	矩阵计算完成后，对结果进行处理，例如对计算结果进行量化操作，并把数据从CO1搬迁到Global Memory中。
gather	给定输入的张量和一个地址偏移张量，本接口根据偏移地址将输入张量按元素收集到结果张量中。
gatherb	给定一个输入的张量和一个地址偏移张量，本接口根据偏移地址按照data_block的粒度将输入张量收集到结果张量中。
get_block_idx	获取当前核的index，用于代码内部的多核逻辑控制及多核偏移量计算等。
get_block_num	获取当前任务配置的核数，用于代码内部的多核逻辑控制等。
get_cmp_mask	用于获取compare（结果存入寄存器）指令的比较结果。
get_data_block_size_in_bytes	获取当前芯片版本一个data_block的大小，单位为byte。 开发者可以根据data_block的大小来计算API指令中待传入的repeat_time、 data_block、stride、repeat_stride等参数值。
get_hccl_context	获取指定Index通信域的context（消息区）地址。
get_icache_preload_status	获取ICACHE的PreLoad的状态。
get_mrg_sort_result	获取mrg_sort已经处理过的队列里的Region Proposal个数，并依次存储在四个出参中。
get_program_counter	获取程序计数器的指针，程序计数器用于记录当前程序执行的位置。
get_store_atomic_config	获取原子操作使能位与原子操作类型的值。
get_sort_len	Get sort length in the sorted structure.
get_sort_offset	Get sort offset in the sorted structure.
get_sub_block_idx	获取 AI Core 上 Vector 核的 ID。
get_system_cycle	获取当前系统cycle数，若换算成时间需要按照50MHz的频率，时间单位为us，换算公式为：time = (cycle数/50) us 。
get_sys_workspace	获取系统workspace指针。
get_task_ratio	分离模式下，获取一个AI Core上Cube Core（AIC）或者Vector Core（AIV）的数量与AI Core数量的比例。耦合模式下，固定返回1。
ib_set	当不同核之间操作同一块全局内存且可能存在读后写、写后读以及写后写等数据依赖问题时，通过调用该函数来插入同步语句来避免上述数据依赖时可能出现的数据读写错误问题。 调用ib_set设置某一个核的标志位，与ib_wait成对出现配合使用，表示核之间的同步等待指令，等待某一个核操作完成。
ib_wait	当不同核之间操作同一块全局内存且可能存在读后写、写后读以及写后写等数据依赖问题时，通过调用该函数来插入同步语句来避免上述数据依赖时可能出现的数据读写错误问题。 ib_wait与ib_set成对出现配合使用，表示核之间的同步等待指令，等待某一个核操作完成。
icache_preload	从指令所在DDR地址预加载指令到ICache中。
init_soc_state	在由于AI Core上存在一些全局状态，如原子累加状态、Mask模式等，在实际运行中，这些值可以被前序执行的算子修改而导致计算出现不符合预期的行为，在静态Tensor编程的场景中用户必须在Kernel入口处调用此函数来初始化AI Core状态 。
load_data	源操作数/目的操作数的数据类型为uint8_t/int8_t时，分形矩阵大小在A1/A2上为16*32， 在B1/B2上为32*16。 源操作数/目的操作数的数据类型为uint16_t/int16_t/half/bfloat16_t时，分形矩阵在A1/B1/A2/B2上的大小为16*16。 源操作数/目的操作数的数据类型为uint32_t/int32_t/float时，分形矩阵大小在A1/A2上为16*8， 在B1/B2上为8*16。 支持如下数据通路： GM->A1; GM->B1; GM->A2; GM->B2; A1->A2; B1->B2。
load_data_with_transpose	该接口实现带转置的2D格式数据从A1/B1到A2/B2的加载。
load_image_to_local	将图像数据从GM搬运到A1/B1。 搬运过程中可以完成图像预处理操作：包括图像翻转，改变图像尺寸（抠图，裁边，缩放，伸展），以及色域转换，类型转换等。 图像预处理的相关参数通过set_aipp_functions进行配置。
metrics_prof_start	用于设置性能数据采集信号启动，和asc.metrics_prof_stop()配合使用。 使用msProf工具进行算子上板调优时，可在kernel侧代码段前后分别调用asc.metrics_prof_start()和asc.metrics_prof_stop()来指定需要调优的代码段范围。
metrics_prof_stop	设置性能数据采集信号停止，和asc.metrics_prof_start()配合使用。 使用msProf工具进行算子上板调优时，可在kernel侧代码段前后分别调用asc.metrics_prof_start()和asc.metrics_prof_stop()来指定需要调优的代码段范围。
mmad	完成矩阵乘加（C += A * B）操作。矩阵ABC分别为A2/B2/CO1中的数据。 ABC矩阵的数据排布格式分别为ZZ，ZN，NZ。
mrg_sort	将已经排好序的多个队列合并成一条队列，结果按照指定顺序排序。
mrg_sort4	将已经排好序的最多4条Region Proposals队列，排列并合并成1条队列，结果按照score域由大到小排序。
notify_next_block	多核同步接口，通过写入 Global Memory 中的标志位，通知下一个 AI Core 当前核的操作已完成。
pipe_barrier	阻塞相同流水，具有数据依赖的相同流水之间需要插入此同步。
printf	该接口提供CPU域/NPU域调试场景下的格式化输出功能。 在算子kernel侧实现代码中需要输出日志信息的地方调用printf接口打印相关内容。
print_time_stamp	提供时间戳打点功能，用于在算子Kernel代码中标记关键执行点。调用后会打印如下信息：
proposal_concat	将连续元素合入Region Proposal内对应位置，每次迭代会将16个连续元素合入到16个Region Proposals的对应位置里。
proposal_extract	与proposal_concat功能相反，从Region Proposals内将相应位置的单个元素抽取后重排，每次迭代处理16个Region Proposals，抽取16个元素后连续排列。
reset_mask	恢复mask的值为默认值（全1），表示矢量计算中每次迭代内的所有元素都将参与运算。
rp_sort16	根据Region Proposals中的score域对其进行排序（score大的排前面），每次排16个Region Proposals。
scatter	给定一个连续的输入张量和一个目的地址偏移张量，scatter指令根据偏移地址生成新的结果张量后将输入张量分散到结果张量中。 将源操作数src中的元素按照指定的位置（由dst_offset和dst_base共同作用）分散到目的操作数dst中。
select	给定两个源操作数src0和src1，根据sel_mask（用于选择的Mask掩码）的比特位值选取元素，得到目的操作数dst。
set_aipp_functions	设置图片预处理（AIPP，AI core pre-process）相关参数。和load_image_to_local(ISASI)接口配合使用。 设置后，调用load_image_to_local(ISASI)接口可在搬运过程中完成图像预处理操作。
set_atomic_add	调用该接口后，可对后续的从VECOUT/L0C/L1到GM的数据传输开启原子累加， 通过dtype参数设定不同类型的数据。
set_atomic_max	原子操作函数，设置后续从VECOUT传输到GM的数据是否执行原子比较： 将待拷贝的内容和GM已有内容进行比较，将最大值写入GM。 可通过设置模板参数来设定不同的数据类型。
set_atomic_min	原子操作函数，设置后续从VECOUT传输到GM的数据是否执行原子比较， 将待拷贝的内容和GM已有内容进行比较，将最小值写入GM。 可通过设置模板参数来设定不同的数据类型。
set_atomic_none	清空原子操作的状态。
set_atomic_type	通过设置模板参数来设定原子操作不同的数据类型。
set_cmp_mask	为select不传入mask参数的接口设置比较寄存器。
set_deq_scale	设置DEQSCALE寄存器的值。
set_fix_pipe_pre_quant_flag	DataCopy（CO1->GM、CO1->A1）过程中进行随路量化时，通过调用该接口设置量化流程中标量量化参数。
set_hf32_mode	调用该接口后，可设置 Mmad 计算是否开启 HF32 模式。 开启 HF32 模式后，L0A/L0B 中的 FP32 数据在参与矩阵乘法计算之前将被舍入为 HF32 精度。
set_hf32_trans_mode	调用该接口后，可设置 Mmad 的 HF32 取整模式，仅在 HF32 模式开启时有效。 在 HF32 模式下，将按照给定模式对 FP32 数据进行舍入。
set_flag	同一核内不同流水线之间的同步指令，具有数据依赖的不同流水指令之间需要插此同步。
set_hccl_context	设置通算融合算子每个通信域对应的context（消息区）地址。
set_load_data_boundary	设置 load_3d 时 A1/B1 边界值。 如果 load_3d 指令在处理源操作数时，源操作数在 A1/B1 上的地址超出设置的边界，则会从 A1/B1 起始地址开始读取数据。
set_load_data_padding_value	用于调用 load_3d_v2v1接口/load_3d_v2 接口时设置 Pad 填充的数值。 load_3d_v1/load_3d_v2 的模板参数 isSetPadding 设置为 true 时，用户需要通过本接口设置 Pad 填充的数值，设置为 false 时，本接口设置的填充值不生效。
set_load_data_repeat	用于设置 load_3d_v2 接口的 repeat 参数。设置 repeat 参数后，可以通过调用一次 load_3d_v2 接口完成多个迭代的数据搬运。
set_mask_count	设置掩码模式为 Counter 模式。在该模式下， 矢量计算时不需要开发者显式指定迭代次数和处理非对齐尾块，只需调用 SetMaskCount 即可自动推断。
set_mask_norm	设置掩码模式为 Normal 模式，这是掩码操作的默认模式。
set_mm_layout_transform	调用该接口后，可设置 Mmad 的 M/N 方向优先顺序， 控制矩阵乘加计算时先按 N 再按 M 方向还是先按 M 再按 N 方向。
set_pad_value	设置asc.data_copy_pad需要填充的数值。支持的通路如下：GM->VECIN/GM->VECOUT填充值。
set_store_atomic_config	设置原子操作使能位与原子操作类型。
set_vector_mask	用于在矢量计算时设置mask。使用前需要先调用 set_mask_count/set_mask_norm 设置 mask 模式。 在不同模式下，mask的含义不同：
sort	排序函数，按照数值大小进行降序排序。
sort32	排序函数，一次迭代可以完成32个数的排序。
sync_all	当不同核之间操作同一块全局内存且可能存在读后写、写后读以及写后写等数据依赖问题时，通过调用该函数来插入同步语句来避免上述数据依赖时可能出现的数据读写错误问题。 目前多核同步分为硬同步和软同步，硬件同步是利用硬件自带的全核同步指令由硬件保证多核同步，软件同步是使用软件算法模拟实现。
transpose	用于实现16 * 16的二维矩阵数据块转置或者[N,C,H,W]与[N,H,W,C]数据格式互相转换。
trans_data_to_5hd	数据格式转换，一般用于将NCHW格式转换成NC1HWC0格式，也可用于二维矩阵数据块的转置。 相比于transpose接口，本接口单次repeat内可处理512Byte的数据（16个datablock）， 支持不同shape的矩阵转置，还可以支持多次repeat操作。
trap	在Kernel侧调用，NPU模式下会中断AI Core的运行，CPU模式下等同于assert。可用于Kernel侧异常场景的调试。
wait_flag	同一核内不同流水线之间的同步指令，具有数据依赖的不同流水指令之间需要插此同步。
wait_pre_block	多核同步接口，通过读取 Global Memory 中的标志位，等待上一个 AI Core 完成操作。

TensorDesc operations

class asc.language.basic.TensorDesc(dtype: DataType = KT.float32)

class asc.language.basic.TensorDesc(handle: Value, dtype: DataType = KT.float32)

TensorDesc.set_shape_addr	配置用于储存shape信息的地址。
TensorDesc.get_dim	获取Tensor的维度。
TensorDesc.get_index	获取TensorDesc在ListTensorDesc中对应的索引值。
TensorDesc.get_shape	获取对应维度的shape信息。
TensorDesc.get_data_ptr	获取储存Tensor数据地址。
TensorDesc.get_data_obj	将数据指针置于GlobalTensor中并返回该GlobalTensor。

class asc.language.basic.ListTensorDesc

class asc.language.basic.ListTensorDesc(data: GlobalAddress, length: int = 4294967295, shape_size: int = 4294967295)

class asc.language.basic.ListTensorDesc(handle: Value)

ListTensorDesc.init	初始化函数，用于解析对应的内存排布。
ListTensorDesc.get_desc	根据index获得功能说明图中对应的TensorDesc信息。
ListTensorDesc.get_data_ptr	根据index获取储存对应数据的地址。
ListTensorDesc.get_size	获取ListTensor中包含的数据指针的个数。

Scalar operations

count_bits_cnt_same_as_sign_bit	计算一个 int64_t 类型数字的二进制中，从最高数值位开始与符号位相同的连续比特位的个数。 当输入是 -1 （比特位全 1 ）或者 0 （比特位全 0 ）时，返回 -1 。
scalar_cast	对标量的数据类型进行转换。
scalar_count_leading_zero	计算一个 uint64_t 类型数字前导 0 的个数 （二进制从最高位到第一个 1 一共有多少个 0 ）。
scalar_get_count_of_value	获取一个 uint64_t 类型数字的二进制中 0 或者 1 的个数。
scalar_get_sff_value	获取一个 uint64_t 类型数字的二进制表示中，从最低有效位（LSB）开始第一个 0 或 1 出现的位置。 如果未找到指定值，则返回 -1。

Vector binary operations

add	按元素求和。
add_deq_relu	依次计算按元素求和、结果进行deq量化后再进行relu计算（结果和0对比取较大值）。
add_relu	按元素求和，再进行Relu计算（结果和0对比取较大值）。
add_relu_cast	按元素求和，结果和0对比取较大值，并根据源操作数和目的操作数Tensor的数据类型进行精度转换。
bilinear_interpolation	分为水平迭代和垂直迭代。 每个水平迭代顺序地从src0_offset读取8个偏移值，表示src0的偏移，每个偏移值指向src0的一个data_block的起始地址，如果repeat_mode=false，从src1中取一个值， 与src0中8个data_block中每个值进行乘操作；如果repeat_mode=true，从src1中取8个值，按顺序与src0中8个data_block中的值进行乘操作， 最后当前迭代的dst结果与前一个dst结果按data_block进行累加，存入目的地址，在同一个水平迭代内dst地址不变。 然后进行垂直迭代，垂直迭代的dst起始地址为上一轮垂直迭代的dst起始地址加上v_r_offset，本轮垂直迭代占用dst空间为dst起始地址之后的8个data_block，每轮垂直迭代进行h_repeat次水平迭代。
bitwise_and	每对elements按位与运算。命名为 bitwise_and 避免与Python关键字重名。
bitwise_or	每对elements按位或运算。命名为 bitwise_or 避免与Python关键字重名。
compare	逐元素比较两个tensor大小，如果比较后的结果为真，则输出的结果的对应比特位为1，否则为0。可将结果存入寄存器中。
div	按元素求商。
fused_mul_add	按元素将src0和dst相乘并加上src1，最终结果存放入dst。
fused_mul_add_relu	按元素将src0和dst相乘并加上src1，再进行Relu计算（结果和0对比取较大值），最终结果存放进dst中。
max	按元素求最大值。
min	按元素求最小值。
mul	按元素求积。
mul_add_dst	按元素将src0和src1相乘并和dst相加，将最终结果存放进dst中。
mul_cast	按元素求积，并根据源操作数和目的操作数Tensor的数据类型进行精度转换。
sub	按元素求差。
sub_relu	按元素求差，再进行Relu计算（结果和0对比取较大值）。
sub_relu_cast	按元素求差，结果和0对比取较大值，并根据源操作数和目的操作数Tensor的数据类型进行精度转换。

Vector reduce operations

block_reduce_max	对每个datablock内所有元素求最大值。
block_reduce_min	对每个datablock内所有元素求最小值。
block_reduce_sum	对每个datablock内所有元素求和。源操作数相加采用二叉树方式，两两相加。归约指令的总体介绍请参考如何使用归约计算API。 以128个half类型的数据求和为例，每个datablock可以计算16个half类型数据，分成8个datablock进行计算；每个datablock内，通过二叉树的方式，两两相加。 需要注意的是两两相加的计算过程中，计算结果大于65504时结果保存为65504。 例如，源操作数为[60000,60000,-30000,100]，首先60000+60000溢出，结果为65504，然后计算-30000+100=-29900，最后计算65504-29900=35604。
pair_reduce_sum	PairReduceSum：相邻两个（奇偶）元素求和。例如，对于序列 (a1, a2, a3, a4, a5, a6, ...)， 相邻两个数据求和为 (a1+a2, a3+a4, a5+a6, ...)。
reduce_max	在所有的输入数据中找出最小值及最小值对应的索引位置。
reduce_min	在所有的输入数据中找出最小值及最小值对应的索引位置。
reduce_sum	对所有的输入数据求和。ReduceSum的相加方式分为两种： - 方式一：同一repeat内先按照二叉树累加、不同repeat的结果也按照二叉树累加。 - 方式二：同一repeat内采用二叉树累加，不同repeat的结果按顺序累加。 tensor前n个数据计算接口采用方式二，tensor高维切分计算接口采用方式一。
repeat_reduce_sum	对每个 repeat 内的所有数据进行求和。 与 whole_reduce_sum 接口相比，不支持 mask 逐比特模式。 建议使用功能更全面的 whole_reduce_sum 接口。
whole_reduce_max	每个repeat内所有数据求最大值以及其索引index，返回的索引值为每个repeat内部索引。 归约指令的总体介绍请参考如何使用归约指令。
whole_reduce_min	每个repeat内所有数据求最小值以及其索引index，返回的索引值为每个repeat内部索引。 归约指令的总体介绍请参考如何使用归约指令。
whole_reduce_sum	每个迭代内所有数据求和。归约指令的总体介绍请参考如何使用归约指令。

Vector-scalar operations

adds	矢量内每个元素与标量求和。
compare_scalar	逐元素比较一个tensor中的元素和另一个scalar的大小，如果比较后的结果为真，则输出的结果的对应比特位为1，否则为0。
leaky_relu	按元素执行Leaky ReLU（Leaky Rectified Linear Unit）操作。
maxs	源操作数矢量内每个元素与标量相比，如果比标量大，则取源操作数值，比标量的值小，则取标量值。
mins	源操作数矢量内每个元素与标量相比，如果比标量大，则取标量值，比标量的值小，则取源操作数。
muls	矢量内每个元素与标量求积。
shift_left	对源操作数中的每个元素进行左移操作，左移的位数由输入参数scalar决定。
shift_right	对源操作数中的每个元素进行右移操作，右移的位数由输入参数scalar决定。

Vector unary operations

abs	按元素取绝对值。
exp	按元素取自然指数。
ln	按元素取自然对数。
bitwise_not	按元素做按位取反。命名为 bitwise_not 避免与Python关键字重名。
gather_mask	以内置固定模式对应的二进制或者用户自定义输入的Tensor数值对应的二进制为gather mask（数据收集的掩码），从源操作数中选取元素写入目的操作数中。
reciprocal	按元素取倒数。
relu	按元素做线性整流Relu。
rsqrt	按元素进行开方后取倒数的计算。
sqrt	按元素做开方。

Matrix operations

init_const_value	将特定TPosition的LocalTensor初始化为某一具体数值。
load_data_with_sparse	用于搬运存放在B1里的512B的稠密权重矩阵到B2里，同时读取128B的索引矩阵用于稠密矩阵的稀疏化。 索引矩阵的数据类型为int2，需要拼成int8的数据类型，再传入接口。 索引矩阵在一个int8的地址中的排布是逆序排布的，例如：索引矩阵1 2 0 1 0 2 1 0， 在地址中的排布为1 0 2 1 0 1 2 0，其中1 0 2 1（对应索引矩阵前四位1 2 0 1）为一个int8，0 1 2 0（对应索引矩阵后四位0 2 1 0）为一个int8。
mmad_with_sparse	完成矩阵乘加操作，传入的左矩阵A为稀疏矩阵， 右矩阵B为稠密矩阵 。 对于矩阵A，在mmad_with_sparse计算时完成稠密化； 对于矩阵B，在计算执行前的输入数据准备时自行完成稠密化（按照下文中介绍的稠密算法进行稠密化）， 所以输入本接口的B矩阵为稠密矩阵。B稠密矩阵需要通过调用load_data_with_sparse载入，同时加载索引矩阵， 索引矩阵在矩阵B稠密化的过程中生成，再用于A矩阵的稠密化。