功能说明

此为有两个源操作数时指令的通用格式，两个源操作数为src和标量scalar。

注意，此章节仅为通用格式说明，不是真正的指令。

函数原型

instruction (mask, dst, src, scalar, repeat_times, dst_rep_stride, src_rep_stride, mask_mode="normal")

参数说明

表1 参数说明
参数名称	输入/输出	含义
instruction	输入	指令名称，TIK DSL中为全小写字符串。
mask	输入	根据mask_mode，分为两种模式： normal mode：element操作有效指示，共128bits，每一个bit位用来表示vector的每个元素是否参与操作，bit位的值为1表示参与计算，0表示不参与计算。支持的模式分为连续、逐bits两种。连续模式：支持传入单个Scalar或Python立即数，表示前多少连续的elements操作有效。例如mask=16，表示前16个elements参与计算。支持的数据类型为：立即数(int)，scalar(int64, int32, int16)。 mask∈[1, 8block_size//dtype_size]，其中dtype_size为dst/src的元素大小。比如，block_size为32Bytes时的取值范围：当dst/src为16位时，mask∈[1, 128]；当dst/src为32位时，mask∈[1, 64]；当dst/src为64位时，mask∈[1, 32]。逐bits模式：传入长度为2的scalar list或立即数list[mask_h, mask_l]，list中每个元素支持数据类型：Scalar(int64)、立即数(int64)。逐bits表示vector的每个元素是否参与操作，bit位的值为1表示参与计算，0表示不参与。mask_h对应高64个元素操作，mask_l对应低64个元素操作。如mask=[0,8]，8=0b1000，表示仅第4个element参与计算。 block_size为32Bytes时的取值范围：当dst/src为16位时，mask_h/mask_l∈[0, 264-1]；当dst/src为32位时，mask_h为0，mask_l∈[0, 264-1]；当dst/src为64位时，mask_h为0，mask_l∈[0, 232-1]。 counter_mode：支持传输数据类型Scalar(int64, int32, int16), 立即数(int)，表示指令中实际操作的有效源操作数元素数量。在该模式下，指令的迭代次数由源操作矢量与mask值共同决定，入参repeat_times无效，取值范围[1, 2*32 – 1]。 Atlas 200/300/500 推理产品，按照normal mode处理。 Atlas 训练系列产品，按照normal mode处理。
dst	输出	矢量目的操作数，tensor起始element，支持数据精度见具体指令。 Tensor的scope为Unified Buffer。
src	输入	矢量源操作数，tensor起始element，支持数据精度见具体指令。 Tensor的scope为Unified Buffer。
scalar	输入	标量源操作数，支持Scalar/立即数。
repeat_times	输入	重复迭代次数。
dst_rep_stride	输入	相邻迭代间，矢量目的操作数相同block地址步长。
src_rep_stride	输入	相邻迭代间，矢量源操作数相同block地址步长。
mask_mode	输入	mask模式选择参数，支持的数据类型：string，取值： normal：mask为normal mode counter：mask为counter mode Atlas 200/300/500 推理产品，该参数不生效。 Atlas 训练系列产品，该参数不生效。

注意事项

repeat_times∈[0,255]，支持的数据类型为：Scalar(int16/int32/int64/uint16/uint32/uint64)、立即数(int)、Expr(int16/int32/int64/uint16/uint32/uint64)，当repeat_times为立即数时，不支持0。
dst_rep_stride/src_rep_stride∈[0,255] ，单位为32B。支持的数据类型：Scalar(int16/int32/int64/uint16/uint32/uint64)、立即数(int)、Expr(int16/int32/int64/uint16/uint32/uint64)。
dst和src的地址不能重叠。
scalar参数支持Scalar/立即数(int/float)两种数据类型。
为了节省地址空间，开发者可以定义一个Tensor，供源操作数与目的操作数同时使用（即地址重叠），相关约束如下：
- 对于单次repeat（repeat_times=1），且源操作数与目的操作数之间要求100%完全重叠，不支持部分重叠。
- 对于多次repeat（repeat_times>1），若源操作数与目的操作数之间存在依赖，即第N次迭代的目的操作数是第N+1次的源操作数，这种情况是不支持地址重叠的。
操作数地址偏移对齐要求请见通用约束。

调用示例

数据连续操作样例

"""
对所有源操作数加2再放置回目的操作空间中
"""
tik_instance = tik.Tik()
dtype_size = {
    "int8": 1,
    "uint8": 1,
    "int16": 2,
    "uint16": 2,
    "float16": 2,
    "int32": 4,
    "uint32": 4,
    "float32": 4,
    "int64": 8,
}

shape = (2, 256)
dtype = "float16"
elements = 2 * 256
# 单次迭代操作的数，当前示例一次迭代处理128个数，mask逐bits模式可写成 [2**64-1, 2**64-1]
mask = 128
# 迭代次数，当前示例进行了4次迭代，可根据需要调整对应的迭代次数
repeat_times = 4
# 迭代间目的操作数前一次repeat头与后一次repeat头之间的距离,单位32B,该示例是连续放置目的操作数,若不需要连续处理数据，可调整对应的参数
dst_rep_stride = 8
src_rep_stride = 8
src_gm = tik_instance.Tensor(dtype, shape, name="src_gm", scope=tik.scope_gm)
dst_gm = tik_instance.Tensor(dtype, shape, name="dst_gm", scope=tik.scope_gm)
src_ub = tik_instance.Tensor(dtype, shape, name="src_ub", scope=tik.scope_ubuf)
dst_ub = tik_instance.Tensor(dtype, shape, name="dst_ub", scope=tik.scope_ubuf)
# 初始化定义scalar数据
scalar = tik_instance.Scalar(dtype=dtype, init_value=2)
# 搬移的片段数
nburst = 1
# 每次搬运的片段长度,单位32B
burst = elements * dtype_size[dtype] // 32 // nburst
# 前burst尾与后burst头的距离,单位32B
dst_stride, src_stride = 0, 0
# 拷贝用户输入数据到src ubuf
tik_instance.data_move(src_ub, src_gm, 0, nburst, burst, src_stride, dst_stride)
tik_instance.vec_adds(mask, dst_ub, src_ub, scalar, repeat_times, dst_rep_stride, src_rep_stride)
# 将计算结果拷贝到目标gm
tik_instance.data_move(dst_gm, dst_ub, 0, nburst, burst, src_stride, dst_stride)
tik_instance.BuildCCE(kernel_name="vec_adds", inputs=[src_gm], outputs=[dst_gm])

示例结果
输入数据(src_gm):
[[  0.   1.   2.   3.   4.   5.   6.   7.   8.   9.  10.  11.  12.  13.
   14.  15.  16.  17.  18.  19.  20.  21.  22.  23.  24.  25.  26.  27.
   28.  29.  30.  31.  32.  33.  34.  35.  36.  37.  38.  39.  40.  41.
   42.  43.  44.  45.  46.  47.  48.  49.  50.  51.  52.  53.  54.  55.
   56.  57.  58.  59.  60.  61.  62.  63.  64.  65.  66.  67.  68.  69.
   70.  71.  72.  73.  74.  75.  76.  77.  78.  79.  80.  81.  82.  83.
   84.  85.  86.  87.  88.  89.  90.  91.  92.  93.  94.  95.  96.  97.
   98.  99. 100. 101. 102. 103. 104. 105. 106. 107. 108. 109. 110. 111.
  112. 113. 114. 115. 116. 117. 118. 119. 120. 121. 122. 123. 124. 125.
  126. 127. 128. 129. 130. 131. 132. 133. 134. 135. 136. 137. 138. 139.
  140. 141. 142. 143. 144. 145. 146. 147. 148. 149. 150. 151. 152. 153.
  154. 155. 156. 157. 158. 159. 160. 161. 162. 163. 164. 165. 166. 167.
  168. 169. 170. 171. 172. 173. 174. 175. 176. 177. 178. 179. 180. 181.
  182. 183. 184. 185. 186. 187. 188. 189. 190. 191. 192. 193. 194. 195.
  196. 197. 198. 199. 200. 201. 202. 203. 204. 205. 206. 207. 208. 209.
  210. 211. 212. 213. 214. 215. 216. 217. 218. 219. 220. 221. 222. 223.
  224. 225. 226. 227. 228. 229. 230. 231. 232. 233. 234. 235. 236. 237.
  238. 239. 240. 241. 242. 243. 244. 245. 246. 247. 248. 249. 250. 251.
  252. 253. 254. 255.]
 [256. 257. 258. 259. 260. 261. 262. 263. 264. 265. 266. 267. 268. 269.
  270. 271. 272. 273. 274. 275. 276. 277. 278. 279. 280. 281. 282. 283.
  284. 285. 286. 287. 288. 289. 290. 291. 292. 293. 294. 295. 296. 297.
  298. 299. 300. 301. 302. 303. 304. 305. 306. 307. 308. 309. 310. 311.
  312. 313. 314. 315. 316. 317. 318. 319. 320. 321. 322. 323. 324. 325.
  326. 327. 328. 329. 330. 331. 332. 333. 334. 335. 336. 337. 338. 339.
  340. 341. 342. 343. 344. 345. 346. 347. 348. 349. 350. 351. 352. 353.
  354. 355. 356. 357. 358. 359. 360. 361. 362. 363. 364. 365. 366. 367.
  368. 369. 370. 371. 372. 373. 374. 375. 376. 377. 378. 379. 380. 381.
  382. 383. 384. 385. 386. 387. 388. 389. 390. 391. 392. 393. 394. 395.
  396. 397. 398. 399. 400. 401. 402. 403. 404. 405. 406. 407. 408. 409.
  410. 411. 412. 413. 414. 415. 416. 417. 418. 419. 420. 421. 422. 423.
  424. 425. 426. 427. 428. 429. 430. 431. 432. 433. 434. 435. 436. 437.
  438. 439. 440. 441. 442. 443. 444. 445. 446. 447. 448. 449. 450. 451.
  452. 453. 454. 455. 456. 457. 458. 459. 460. 461. 462. 463. 464. 465.
  466. 467. 468. 469. 470. 471. 472. 473. 474. 475. 476. 477. 478. 479.
  480. 481. 482. 483. 484. 485. 486. 487. 488. 489. 490. 491. 492. 493.
  494. 495. 496. 497. 498. 499. 500. 501. 502. 503. 504. 505. 506. 507.
  508. 509. 510. 511.]]
输出数据(dst_gm):
[[  2.   3.   4.   5.   6.   7.   8.   9.  10.  11.  12.  13.  14.  15.
   16.  17.  18.  19.  20.  21.  22.  23.  24.  25.  26.  27.  28.  29.
   30.  31.  32.  33.  34.  35.  36.  37.  38.  39.  40.  41.  42.  43.
   44.  45.  46.  47.  48.  49.  50.  51.  52.  53.  54.  55.  56.  57.
   58.  59.  60.  61.  62.  63.  64.  65.  66.  67.  68.  69.  70.  71.
   72.  73.  74.  75.  76.  77.  78.  79.  80.  81.  82.  83.  84.  85.
   86.  87.  88.  89.  90.  91.  92.  93.  94.  95.  96.  97.  98.  99.
  100. 101. 102. 103. 104. 105. 106. 107. 108. 109. 110. 111. 112. 113.
  114. 115. 116. 117. 118. 119. 120. 121. 122. 123. 124. 125. 126. 127.
  128. 129. 130. 131. 132. 133. 134. 135. 136. 137. 138. 139. 140. 141.
  142. 143. 144. 145. 146. 147. 148. 149. 150. 151. 152. 153. 154. 155.
  156. 157. 158. 159. 160. 161. 162. 163. 164. 165. 166. 167. 168. 169.
  170. 171. 172. 173. 174. 175. 176. 177. 178. 179. 180. 181. 182. 183.
  184. 185. 186. 187. 188. 189. 190. 191. 192. 193. 194. 195. 196. 197.
  198. 199. 200. 201. 202. 203. 204. 205. 206. 207. 208. 209. 210. 211.
  212. 213. 214. 215. 216. 217. 218. 219. 220. 221. 222. 223. 224. 225.
  226. 227. 228. 229. 230. 231. 232. 233. 234. 235. 236. 237. 238. 239.
  240. 241. 242. 243. 244. 245. 246. 247. 248. 249. 250. 251. 252. 253.
  254. 255. 256. 257.]
 [258. 259. 260. 261. 262. 263. 264. 265. 266. 267. 268. 269. 270. 271.
  272. 273. 274. 275. 276. 277. 278. 279. 280. 281. 282. 283. 284. 285.
  286. 287. 288. 289. 290. 291. 292. 293. 294. 295. 296. 297. 298. 299.
  300. 301. 302. 303. 304. 305. 306. 307. 308. 309. 310. 311. 312. 313.
  314. 315. 316. 317. 318. 319. 320. 321. 322. 323. 324. 325. 326. 327.
  328. 329. 330. 331. 332. 333. 334. 335. 336. 337. 338. 339. 340. 341.
  342. 343. 344. 345. 346. 347. 348. 349. 350. 351. 352. 353. 354. 355.
  356. 357. 358. 359. 360. 361. 362. 363. 364. 365. 366. 367. 368. 369.
  370. 371. 372. 373. 374. 375. 376. 377. 378. 379. 380. 381. 382. 383.
  384. 385. 386. 387. 388. 389. 390. 391. 392. 393. 394. 395. 396. 397.
  398. 399. 400. 401. 402. 403. 404. 405. 406. 407. 408. 409. 410. 411.
  412. 413. 414. 415. 416. 417. 418. 419. 420. 421. 422. 423. 424. 425.
  426. 427. 428. 429. 430. 431. 432. 433. 434. 435. 436. 437. 438. 439.
  440. 441. 442. 443. 444. 445. 446. 447. 448. 449. 450. 451. 452. 453.
  454. 455. 456. 457. 458. 459. 460. 461. 462. 463. 464. 465. 466. 467.
  468. 469. 470. 471. 472. 473. 474. 475. 476. 477. 478. 479. 480. 481.
  482. 483. 484. 485. 486. 487. 488. 489. 490. 491. 492. 493. 494. 495.
  496. 497. 498. 499. 500. 501. 502. 503. 504. 505. 506. 507. 508. 509.
  510. 511. 512. 513.]]

数据非连续操作样例

"""
把128个源操作数，经过指令vadds加上2，然后按照每放32个数再间隔32个数放置目的数据
"""
tik_instance = tik.Tik()
dtype_size = {
    "int8": 1,
    "uint8": 1,
    "int16": 2,
    "uint16": 2,
    "float16": 2,
    "int32": 4,
    "uint32": 4,
    "float32": 4,
    "int64": 8,
}

src_shape = (4, 32)
dst_shape = (8, 32)
dtype = "float16"
src_elements = 4 * 32
dst_elements = 8 * 32
# 单次迭代操作的数，当前示例一次迭代处理32个数，mask逐bits模式可写成 [0, 2**32-1]
mask = 32
# 迭代次数，当前示例进行了4次迭代，可根据需要调整对应的迭代次数
repeat_times = 4
# 迭代间目的操作数前一次repeat头与后一次repeat头之间的距离,单位32B, 由于每次迭代处理32个数，所以当前迭代间需要间隔4个block放置目地操作数才能达到效果
dst_rep_stride = 4
src_rep_stride = 2
src_gm = tik_instance.Tensor(dtype, src_shape, name="src_gm", scope=tik.scope_gm)
dst_gm = tik_instance.Tensor(dtype, dst_shape, name="dst_gm", scope=tik.scope_gm)
src_ub = tik_instance.Tensor(dtype, src_shape, name="src_ub", scope=tik.scope_ubuf)
dst_ub = tik_instance.Tensor(dtype, dst_shape, name="dst_ub", scope=tik.scope_ubuf)
scalar = tik_instance.Scalar(dtype=dtype, init_value=2)
# 搬移的片段数
nburst = 1
# 每次搬运的片段长度,单位32B
burst = src_elements * dtype_size[dtype] // 32 // nburst
dst_burst = dst_elements * dtype_size[dtype] // 32 // nburst
# 前burst尾与后burst头的距离,单位32B
dst_stride, src_stride = 0, 0
# 拷贝用户输入数据到src ubuf
tik_instance.data_move(src_ub, src_gm, 0, nburst, burst, src_stride, dst_stride)
# 对dst_ub进行置零处理,详细参数见对应指令说明
tik_instance.vec_dup(128, dst_ub, 0, 2, 8)
tik_instance.vec_adds(mask, dst_ub, src_ub, scalar, repeat_times, dst_rep_stride, src_rep_stride)
# 将计算结果拷贝到目标gm
tik_instance.data_move(dst_gm, dst_ub, 0, nburst, dst_burst, src_stride, dst_stride)
tik_instance.BuildCCE(kernel_name="vec_adds", inputs=[src_gm], outputs=[dst_gm])

示例结果
输入数据(src_gm):
[[  0.   1.   2.   3.   4.   5.   6.   7.   8.   9.  10.  11.  12.  13.
   14.  15.  16.  17.  18.  19.  20.  21.  22.  23.  24.  25.  26.  27.
   28.  29.  30.  31.]
 [ 32.  33.  34.  35.  36.  37.  38.  39.  40.  41.  42.  43.  44.  45.
   46.  47.  48.  49.  50.  51.  52.  53.  54.  55.  56.  57.  58.  59.
   60.  61.  62.  63.]
 [ 64.  65.  66.  67.  68.  69.  70.  71.  72.  73.  74.  75.  76.  77.
   78.  79.  80.  81.  82.  83.  84.  85.  86.  87.  88.  89.  90.  91.
   92.  93.  94.  95.]
 [ 96.  97.  98.  99. 100. 101. 102. 103. 104. 105. 106. 107. 108. 109.
  110. 111. 112. 113. 114. 115. 116. 117. 118. 119. 120. 121. 122. 123.
  124. 125. 126. 127.]]
输出数据(dst_gm):
[[  2.   3.   4.   5.   6.   7.   8.   9.  10.  11.  12.  13.  14.  15.
   16.  17.  18.  19.  20.  21.  22.  23.  24.  25.  26.  27.  28.  29.
   30.  31.  32.  33.]
 [  0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.]
 [ 34.  35.  36.  37.  38.  39.  40.  41.  42.  43.  44.  45.  46.  47.
   48.  49.  50.  51.  52.  53.  54.  55.  56.  57.  58.  59.  60.  61.
   62.  63.  64.  65.]
 [  0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.]
 [ 66.  67.  68.  69.  70.  71.  72.  73.  74.  75.  76.  77.  78.  79.
   80.  81.  82.  83.  84.  85.  86.  87.  88.  89.  90.  91.  92.  93.
   94.  95.  96.  97.]
 [  0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.]
 [ 98.  99. 100. 101. 102. 103. 104. 105. 106. 107. 108. 109. 110. 111.
  112. 113. 114. 115. 116. 117. 118. 119. 120. 121. 122. 123. 124. 125.
  126. 127. 128. 129.]
 [  0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.   0.
    0.   0.   0.   0.]]

通用定义

功能说明

函数原型

参数说明

注意事项

调用示例